@file:afield.runtime.completion.CompletionCategory("Visualization")

package afield.ui.visualization

import afield.ai.conversation.images
import afield.app.protocol.Output
import afield.data.table.div
import afield.data.table.minus
import afield.data.table.plus
import afield.data.table.ref
import afield.data.table.rem
import afield.data.table.spreadsheet
import afield.data.table.times
import afield.document.graph.nested
import afield.runtime.completion.CompletionCategory
import afield.runtime.execution.plus
import afield.runtime.lifecycle.plus
import afield.runtime.lifecycle.rem
import afield.runtime.lifecycle.then
import afield.ui.notation.center
import afield.ui.notation.custom
import afield.ui.notation.double
import afield.ui.notation.long
import afield.ui.notation.string
import afield.ui.notation.with
import afield.ui.output.column

import afield.app.server.SessionInformation
import afield.app.server.documents
import afield.app.server.thisSessionInfo
import afield.audio.synth.*
import afield.data.table.cell
import afield.data.table.get
import afield.document.graph.Box
import afield.document.graph.box
import afield.document.workspace.BoxReference
import afield.graphics.vulkan.*
import afield.media.stream.*
import afield.media.video.*
import afield.runtime.lifecycle.end
import afield.runtime.lifecycle.map
import afield.tools.docs.format
import afield.ui.notation.obj
import afield.ui.output.stats
import afield.ui.output.tree
import afield.math.linalg.Vector2f
import afield.math.linalg.Vector2fc
import afield.math.linalg.Vector3f
import afield.math.linalg.Vector3fc
import afield.math.linalg.Vector4f
import afield.math.linalg.Vector4fc
import afield.geometry.path.FLine
import afield.math.functions.Functions
import afield.math.units.Quantity
import afield.math.units.formatExpression
import afield.math.units.formatQuantityDisplay
import afield.math.linalg.*
import eu.sirotin.kotunil.core.Expression
import space.kscience.plotly.Plot
import java.util.Collections
import java.util.IdentityHashMap
import kotlin.math.abs
import kotlin.math.atan2
import kotlin.math.cos
import kotlin.math.max
import kotlin.math.min
import kotlin.math.pow
import kotlin.math.sin
import kotlin.math.sqrt
import kotlin.reflect.KClass
import kotlin.reflect.KType
import kotlin.reflect.KTypeProjection
import kotlin.reflect.full.memberProperties
import kotlin.reflect.jvm.isAccessible

    private const val ELISION_SLACK = 2
    private const val OBJECT_EXPANSION_CHUNK = 8
    private const val BYTE_EXPANSION_CHUNK = 16
    private const val FLINE_THUMBNAIL_WIDTH = 136
    private const val FLINE_THUMBNAIL_HEIGHT = 84
    private const val FLINE_SIGNATURE_FULL_MAX_NODES = 80
    private const val FLINE_SIGNATURE_PREVIEW_MAX_NODES = 900
    private const val FLINE_THUMBNAIL_MAX_COMPLEXITY = 350
    private const val FLINE_LENGTH_MAX_COMPLEXITY = 1200
    private const val FLINE_SIGNATURE_HEAD = 42
    private const val FLINE_SIGNATURE_TAIL = 22
    private const val FN_PLOT_WIDTH = 248
    private const val FN_PLOT_HEIGHT = 104
    private const val FN_PLOT_GUTTER_LEFT = 38
    private const val FN_PLOT_GUTTER_BOTTOM = 14
    private const val FN_PLOT_PAD_TOP = 8
    private const val FN_PLOT_PAD_RIGHT = 8
    private const val FN_PLOT_SAMPLES = 160
    private const val VEC_THUMBNAIL_SIZE = 84
    private const val MATRIX_CELL_SIZE = 24
    private const val SPARKLINE_WIDTH = 120
    private const val SPARKLINE_HEIGHT = 22
    private const val SPARKLINE_MAX_SAMPLES = 240
    private const val SPARKLINE_MIN_POINTS = 3
    private const val INLINE_STRUCT_MAX_FIELDS = 3
    private const val INLINE_STRUCT_MAX_CHARS = 64
    private const val RECORD_TABLE_MAX_ROWS = 24
    private const val INDENT_STEP_PX = 12
    private const val BOX_SYMBOL = "\u25A1"
    private val UNDERSCORE_UUID_REGEX = Regex(
        "^_?([0-9a-f]{8})_([0-9a-f]{4})_([0-9a-f]{4})_([0-9a-f]{4})_([0-9a-f]{12})$",
        options = setOf(RegexOption.IGNORE_CASE)
    )
    private val BOX_ID_TOKEN_REGEX = Regex(
        pattern = "(?<![A-Za-z0-9_])(_[0-9a-f]{8}_[0-9a-f]{4}_[0-9a-f]{4}_[0-9a-f]{4}_[0-9a-f]{12})(__(\\d+))?(@[0-9a-f]+)?(?![A-Za-z0-9_])",
        options = setOf(RegexOption.IGNORE_CASE)
    )

    private data class ThumbnailResult(
        val svg: String?,
        val reason: String? = null
    )

    fun visualize(value: Any?, appendable: Boolean = false): String {
        return buildString {
            append("<div class='value-viz")
            if (appendable) append(" afield-appendable-output")
            append("' style='font-family: \"Iosevka Web\", monospace; font-size: 12px; color: #ccc; line-height: 1.4; font-feature-settings: \"calt\" 1, \"dlig\" 1; font-variant-ligatures: contextual;'>")
            // Track only the current recursion path, using reference equality.
            val visited = newIdentitySet()
            append(visualizeValue(value, 0, visited))
            append("</div>")
        }
    }

    private fun newIdentitySet(): MutableSet<Any> =
        Collections.newSetFromMap(IdentityHashMap())

    private fun visualizeValue(
        value: Any?,
        depth: Int,
        visited: MutableSet<Any>,
        respectDepthLimit: Boolean = true
    ): String {
        // Check depth limit
        if (respectDepthLimit && depth > MAX_DEPTH) return formatDepthLimitedValue(value)

        return when (value) {
            null -> "<span style='color: #888;'>null</span>"

            // Check for ToHTML interface first
            is ToHTML -> rewriteBoxReferencesInHtml(value.toHTML())

            // Check custom printers
            else -> {
                // For complex objects, check for circular references
                val trackCircular = shouldCheckCircular(value)
                if (trackCircular) {
                    if (value in visited) {
                        return "<span style='color: #f88;'>[circular reference]</span>"
                    }
                    visited.add(value)
                }

                try {
                    ValuePrinterRegistry.getPrinter(value)?.invoke(value) ?: visualizeBuiltIn(value, depth, visited, respectDepthLimit)
                } finally {
                    if (trackCircular) visited.remove(value)
                }
            }
        }
    }

    private fun shouldCheckCircular(value: Any): Boolean {
        return when (value) {
            // Skip primitives and value types
            is Number, is Boolean, is Char, is String -> false
            // Skip linalg value types (they are value types)
            is Vector2fc, is Vector3fc, is Vector4fc,
            is Vector2dc, is Vector3dc, is Vector4dc,
            is Quaternionfc,
            is Matrix2fc, is Matrix3fc, is Matrix4fc,
            is Matrix2dc, is Matrix3dc, is Matrix4dc -> false
            // Check data classes, collections and other objects
            else -> true
        }
    }

    private fun visualizeBuiltIn(
        value: Any,
        depth: Int,
        visited: MutableSet<Any>,
        respectDepthLimit: Boolean
    ): String = when (value) {
        // Physical quantities. These precede the generic object fallback so a unit-bearing
        // spreadsheet result reads as a value, not as `Quantity 3 mm`.
        is Quantity -> formatQuantity(value)
        is Expression -> formatUnitExpression(value)

        // A kotlinx JSON leaf is shown as the value it holds. Without this a JsonObject (a Map, so it
        // already reads as one) printed every entry as `JsonLiteral "speed"`: the class name from the
        // reflective fallback, then the quotes from JsonLiteral.toString().
        is kotlinx.serialization.json.JsonPrimitive -> visualizeValue(jsonLeafValue(value), depth, visited, respectDepthLimit)

        // Primitives
        is Boolean -> "<span style='color: #f88;'>${value}</span>"
        is Number -> formatNumber(value)
        is Char -> "<span style='color: #8f8;'>'${escape(value.toString())}'</span>"
        is String -> formatString(value)

        // Field vectors
        is Vector2fc -> formatVec2(value)
        is Vector3fc -> formatVec3(value)
        is Vector4fc -> formatVec4(value)
        is Vector2dc -> formatVec2(Vector2f(value.x().toFloat(), value.y().toFloat()))
        is Vector3dc -> formatVec3(Vector3f(value.x().toFloat(), value.y().toFloat(), value.z().toFloat()))
        is Vector4dc -> formatVec4(Vector4f(value.x().toFloat(), value.y().toFloat(), value.z().toFloat(), value.w().toFloat()))

        // Field quaternions
        is Quaternionfc -> formatQuat(value)

        // Field matrices — both the single-precision (…fc) and the generated
        // double-precision (…dc) families render as diverging heatmaps. (There is still no
        // double-precision quaternion type, so quaternions stay single-precision above.)
        is Matrix2fc -> formatMatrix(value)
        is Matrix3fc -> formatMatrix(value)
        is Matrix4fc -> formatMatrix(value)
        is Matrix2dc -> formatMatrix(value)
        is Matrix3dc -> formatMatrix(value)
        is Matrix4dc -> formatMatrix(value)

        // kotlin.Pair, as the `to` that almost always built it. Precedes the reflective
        // data-class fallback, which would otherwise expand it to `Pair { first -> a, second -> b }`.
        is Pair<*, *> -> formatPair(value, depth, visited, respectDepthLimit)

        // Collections
        is Map<*, *> -> formatMap(value, depth, visited, respectDepthLimit)
        is List<*> -> formatList(value, depth, visited, respectDepthLimit = respectDepthLimit)
        is Set<*> -> formatSet(value, depth, visited, respectDepthLimit)
        is Array<*> -> formatArray(value, depth, visited, respectDepthLimit)
        is ByteArray -> formatByteArray(value)
        is IntArray -> formatIntArray(value)
        is FloatArray -> formatFloatArray(value)
        is DoubleArray -> formatDoubleArray(value)
        is FLine -> formatFLine(value)
        is Functions.Domain -> formatDomain(value)
        is Functions.Fn -> formatFn(value, depth, visited, respectDepthLimit)
        is afield.math.functions.FnFitRun -> formatFnFitRun(value)
        is Box -> formatBox(value)
        is Plot -> value.toHtml()
        is Function<*> -> formatFunction(value, null)

        // Imaging / computer-vision family — Gradient, the pyramids, FlowField, ComponentLabelling.
        // Lives in ImagingVisualizer.kt and returns null for anything it does not own, so the
        // reflective paths below stay the default.
        // Data classes
        else -> ImagingVisualizer.format(value)
            ?: if (value::class.isData) {
                formatDataClass(value, depth, visited, respectDepthLimit)
            } else {
                formatFallbackObject(value)
            }
    }

    private fun formatQuantity(value: Quantity): String {
        val (number, symbol) = formatQuantityDisplay(value)
        return formatUnitValue(number, symbol)
    }

    private fun formatUnitExpression(value: Expression): String {
        val (number, symbol) = formatExpression(value)
        return formatUnitValue(number, symbol)
    }

    private fun formatUnitValue(number: Double, symbol: String): String = buildString {
        append(formatNumber(number))
        if (symbol.isNotBlank()) {
            append("<span style='color:#777;'> </span>")
            append("<span class='afield-unit-symbol' style='color:#9ac;'>")
            append(escape(symbol))
            append("</span>")
        }
    }

    private fun formatDepthLimitedValue(value: Any?): String = when (value) {
        null -> "<span style='color: #888;'>null</span>"
        is Boolean -> "<span style='color: #f88;'>${value}</span>"
        is Number -> formatNumber(value)
        is Char -> "<span style='color: #8f8;'>'${escape(value.toString())}'</span>"
        is String -> formatString(value)
        else -> lazyInlineExpanderHtml(
            value = value,
            label = "…",
            kind = "full",
            offset = 0,
            title = value::class.simpleName ?: value::class.java.simpleName
        )
    }

    private fun formatFallbackObject(value: Any): String {
        val className = value::class.simpleName ?: value::class.java.simpleName.ifBlank { "Object" }
        val rendered = value.toString()
        val preview = rendered.take(MAX_STRING_LENGTH)

        return buildString {
            append("<span style='color: #cc8;'>")
            append(escape(className))
            append("</span>")
            if (preview.isNotBlank()) {
                append("<span style='color: #666;'> </span>")
                append("<span style='color: #aaa;'>")
                append(escape(preview))
                append("</span>")
            }
            if (rendered.length > MAX_STRING_LENGTH) {
                append(" ")
                append(
                    lazyInlineExpanderHtml(
                        value = value,
                        label = "… +${rendered.length - MAX_STRING_LENGTH} chars",
                        kind = "full",
                        offset = 0,
                        title = className
                    )
                )
            }
        }
    }

    private fun functionArity(value: Any): Int? {
        val queue = ArrayDeque<Class<*>>()
        val seen = HashSet<Class<*>>()
        queue.add(value.javaClass)
        while (queue.isNotEmpty()) {
            val c = queue.removeFirst()
            if (!seen.add(c)) continue
            val n = c.name
            if (n.startsWith("kotlin.jvm.functions.Function")) {
                return n.removePrefix("kotlin.jvm.functions.Function").toIntOrNull()
            }
            c.superclass?.let { queue.add(it) }
            c.interfaces.forEach { queue.add(it) }
        }
        return null
    }

    private fun formatBox(box: Box): String {
        val displayName = box.name.ifBlank { box.id }
        val escapedUid = escapeHtmlText(box.id)
        return buildString {
            append("<a href='#box:")
            append(escapedUid)
            append("' data-box-uid='")
            append(escapedUid)
            append("' style='text-decoration:none;cursor:pointer;'>")
            append("<span style='color:#fff;font-weight:300;'>")
            append(BOX_SYMBOL)
            append("</span>")
            append("<span style='color:#fff;font-weight:300;font-style:italic;'>")
            append(escapeHtmlText(displayName))
            append("</span>")
            append("</a>")
        }
    }

    private fun formatNumber(n: Number): String {
        val formatted = when (n) {
            is Float -> {
                when {
                    n.isNaN() -> "NaN"
                    n.isInfinite() -> if (n > 0) "∞" else "-∞"
                    abs(n) < 0.001f && n != 0f -> "%.3e".format(n)
                    abs(n) > 10000f -> "%.3e".format(n)
                    else -> "%.3f".format(n).trimEnd('0').trimEnd('.')
                }
            }
            is Double -> {
                when {
                    n.isNaN() -> "NaN"
                    n.isInfinite() -> if (n > 0) "∞" else "-∞"
                    abs(n) < 0.001 && n != 0.0 -> "%.3e".format(n)
                    abs(n) > 10000.0 -> "%.3e".format(n)
                    else -> "%.3f".format(n).trimEnd('0').trimEnd('.')
                }
            }
            else -> n.toString()
        }
        return "<span style='color: #8cf;'>$formatted</span>"
    }

    private data class FLineBounds(
        val minX: Float,
        val minY: Float,
        val maxX: Float,
        val maxY: Float
    ) {
        val width: Double get() = (maxX - minX).toDouble()
        val height: Double get() = (maxY - minY).toDouble()
    }

    private fun compressSignatureRuns(sig: String): String = buildString {
        var i = 0
        while (i < sig.length) {
            val ch = sig[i]
            if (ch in "MLCZ") {
                var run = 1
                while (i + run < sig.length && sig[i + run] == ch) run++
                if (run > 6) {
                    append("(${ch}x$run)")
                } else {
                    repeat(run) { append(ch) }
                }
                i += run
            } else {
                append(ch)
                i++
            }
        }
    }

    private fun formatFLine(line: FLine): String {
        val nodes = line.nodes
        if (nodes.isEmpty()) {
            return "<span style='color: #9cf;'>FLine</span> <span style='color: #888;'>[empty]</span>"
        }

        var moveCount = 0
        var lineCount = 0
        var cubicCount = 0
        var closeCount = 0
        nodes.forEach { node ->
            when (node) {
                is FLine.MoveTo -> moveCount++
                is FLine.LineTo -> lineCount++
                is FLine.CubicTo -> cubicCount++
                is FLine.Close -> closeCount++
            }
        }

        val nodeCount = nodes.size
        val complexity = moveCount + lineCount + closeCount + cubicCount * 4
        val showThumbnail = complexity <= FLINE_THUMBNAIL_MAX_COMPLEXITY
        val showLength = complexity <= FLINE_LENGTH_MAX_COMPLEXITY

        val signature = if (nodeCount <= FLINE_SIGNATURE_PREVIEW_MAX_NODES) {
            buildString(nodeCount) {
                nodes.forEach { node ->
                    append(
                        when (node) {
                            is FLine.MoveTo -> 'M'
                            is FLine.LineTo -> 'L'
                            is FLine.CubicTo -> 'C'
                            is FLine.Close -> 'Z'
                        }
                    )
                }
            }
        } else null

        val shownSignature = signature?.let {
            val raw = if (nodeCount <= FLINE_SIGNATURE_FULL_MAX_NODES) {
                it
            } else {
                val head = it.take(FLINE_SIGNATURE_HEAD)
                val tail = it.takeLast(FLINE_SIGNATURE_TAIL)
                "$head … $tail"
            }
            compressSignatureRuns(raw)
        }

        val length = if (showLength) runCatching { line.cursor(0.5f).lengthD().toDouble() }.getOrNull() else null
        val bounds = computeFLineBounds(line)
        val thumbnail = if (showThumbnail) renderFLineThumbnail(line) else ThumbnailResult(
            svg = null,
            reason = "complex path"
        )

        return buildString {
            append("<div style='display:inline-block; max-width: 320px;'>")
            append("<div><span style='color: #9cf;'>FLine</span> <span style='color: #666;'>(</span>")
            append(formatNumberToken(nodeCount))
            append("<span style='color: #666;'> nodes)</span></div>")

            append("<div style='color: #888;'>")
            append("M=")
            append(formatNumberToken(moveCount))
            append(" L=")
            append(formatNumberToken(lineCount))
            append(" C=")
            append(formatNumberToken(cubicCount))
            if (closeCount > 0) {
                append(" Z=")
                append(formatNumberToken(closeCount))
            }
            if (bounds != null) {
                append(" • b=")
                append(formatNumericLiteral(bounds.width))
                append("×")
                append(formatNumericLiteral(bounds.height))
            }
            if (length != null) {
                append(" • len=")
                append(formatNumericLiteral(length))
            }
            append("</div>")

            if (shownSignature != null) {
                append("<div style='color: #9f9; letter-spacing: 0.04em;'>")
                append(escape(shownSignature))
                append("</div>")
            }

            if (thumbnail.svg != null) {
                append("<div style='margin-top: 4px; border: 1px solid #333; border-radius: 4px; background: #111; width: ${FLINE_THUMBNAIL_WIDTH}px; height: ${FLINE_THUMBNAIL_HEIGHT}px; overflow: hidden;'>")
                append(thumbnail.svg)
                append("</div>")
            } else if (thumbnail.reason != null) {
                append("<div style='color: #666;'>thumbnail unavailable (${escape(thumbnail.reason)})</div>")
            }

            append("</div>")
        }
    }

    private fun renderFLineThumbnail(line: FLine): ThumbnailResult {
        val normalized = runCatching { normalizeFLineForThumbnail(line) }
            .getOrElse { return ThumbnailResult(svg = null, reason = "normalize failed") }

        val pathData = buildSvgPathData(normalized)
        if (pathData.isBlank()) return ThumbnailResult(svg = null, reason = "no drawable segments")

        val svg = buildString {
            append("<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 $FLINE_THUMBNAIL_WIDTH $FLINE_THUMBNAIL_HEIGHT' width='$FLINE_THUMBNAIL_WIDTH' height='$FLINE_THUMBNAIL_HEIGHT'>")
            append("<rect x='0' y='0' width='$FLINE_THUMBNAIL_WIDTH' height='$FLINE_THUMBNAIL_HEIGHT' fill='transparent'/>")
            append("<path d='")
            append(pathData)
            append("' fill='none' stroke='#9cf' stroke-width='1.3' stroke-linecap='round' stroke-linejoin='round' vector-effect='non-scaling-stroke'/>")
            append("</svg>")
        }

        return ThumbnailResult(svg = svg)
    }

    private fun buildSvgPathData(line: FLine): String {
        if (line.nodes.isEmpty()) return ""

        val out = StringBuilder(line.nodes.size * 12)
        var hasDrawableSegment = false
        var penIsDown = false

        line.nodes.forEach { node ->
            when (node) {
                is FLine.MoveTo -> {
                    val p = node.to
                    if (!p.x.isFinite() || !p.y.isFinite()) return@forEach
                    out.append('M').append(svgNum(p.x)).append(' ').append(svgNum(p.y)).append(' ')
                    penIsDown = true
                }
                is FLine.LineTo -> {
                    val p = node.to
                    if (!p.x.isFinite() || !p.y.isFinite()) return@forEach
                    if (!penIsDown) {
                        out.append('M').append(svgNum(p.x)).append(' ').append(svgNum(p.y)).append(' ')
                        penIsDown = true
                    } else {
                        out.append('L').append(svgNum(p.x)).append(' ').append(svgNum(p.y)).append(' ')
                        hasDrawableSegment = true
                    }
                }
                is FLine.CubicTo -> {
                    val end = node.to
                    val c1 = node.c1
                    val c2 = node.c2
                    if (!end.x.isFinite() || !end.y.isFinite() || !c1.x.isFinite() || !c1.y.isFinite() || !c2.x.isFinite() || !c2.y.isFinite()) return@forEach
                    if (!penIsDown) {
                        out.append('M').append(svgNum(end.x)).append(' ').append(svgNum(end.y)).append(' ')
                        penIsDown = true
                    } else {
                        out.append('C')
                            .append(svgNum(c1.x)).append(' ').append(svgNum(c1.y)).append(' ')
                            .append(svgNum(c2.x)).append(' ').append(svgNum(c2.y)).append(' ')
                            .append(svgNum(end.x)).append(' ').append(svgNum(end.y)).append(' ')
                        hasDrawableSegment = true
                    }
                }
                is FLine.Close -> {
                    if (penIsDown) {
                        out.append('Z').append(' ')
                        hasDrawableSegment = true
                    }
                }
            }
        }

        return if (hasDrawableSegment) out.toString().trim() else ""
    }

    private fun svgNum(n: Float): String {
        return runCatching {
            if (!n.isFinite()) "0"
            else "%.3f".format(n).trimEnd('0').trimEnd('.')
        }.getOrDefault("0")
    }

    private fun normalizeFLineForThumbnail(
        line: FLine,
        width: Float = FLINE_THUMBNAIL_WIDTH.toFloat(),
        height: Float = FLINE_THUMBNAIL_HEIGHT.toFloat(),
        padding: Float = 6f
    ): FLine {
        val b = computeFLineBounds(line) ?: return line.copy()

        val sourceW = max((b.maxX - b.minX), 1f)
        val sourceH = max((b.maxY - b.minY), 1f)
        val contentW = max(width - padding * 2f, 1f)
        val contentH = max(height - padding * 2f, 1f)
        val scale = min(contentW / sourceW, contentH / sourceH)
        val offsetX = (width - sourceW * scale) * 0.5f - b.minX * scale
        val offsetY = (height - sourceH * scale) * 0.5f - b.minY * scale

        return line.transform { p ->
            Vector3f(
                p.x * scale + offsetX,
                p.y * scale + offsetY,
                p.z
            )
        }
    }

    private fun computeFLineBounds(line: FLine): FLineBounds? {
        var minX = Float.POSITIVE_INFINITY
        var minY = Float.POSITIVE_INFINITY
        var maxX = Float.NEGATIVE_INFINITY
        var maxY = Float.NEGATIVE_INFINITY
        var seen = false

        line.nodes.forEach { node ->
            node.storage.forEach { p ->
                if (!p.x.isFinite() || !p.y.isFinite()) return@forEach
                seen = true
                minX = min(minX, p.x)
                minY = min(minY, p.y)
                maxX = max(maxX, p.x)
                maxY = max(maxY, p.y)
            }
        }

        if (!seen) return null
        return FLineBounds(minX, minY, maxX, maxY)
    }

    private fun renderFnPlot(fn: Functions.Fn): String? {
        // Resolve a finite x-window (plotSafe): finite non-empty domain as-is, a
        // point domain widened to ±0.5, anything unbounded falls back to 0..1.
        val d = fn.domain
        val xMin: Double
        val xMax: Double
        when {
            d.isFinite && d.length > 0.0 -> { xMin = d.min; xMax = d.max }
            d.min.isFinite() && d.length == 0.0 -> { xMin = d.min - 0.5; xMax = d.min + 0.5 }
            else -> { xMin = 0.0; xMax = 1.0 }
        }
        if (!xMin.isFinite() || !xMax.isFinite() || xMax <= xMin) return null

        val count = FN_PLOT_SAMPLES
        val step = (xMax - xMin) / (count - 1).toDouble()
        val ys = DoubleArray(count) { i ->
            val x = xMin + step * i.toDouble()
            runCatching { fn.evalSafe(x, outside = Double.NaN, edge = Functions.EdgeMode.ZERO) }
                .getOrElse { Double.NaN }
                .let { if (it.isFinite()) it else Double.NaN }
        }

        var lo = Double.POSITIVE_INFINITY
        var hi = Double.NEGATIVE_INFINITY
        for (y in ys) {
            if (!y.isFinite()) continue
            if (y < lo) lo = y
            if (y > hi) hi = y
        }
        if (!lo.isFinite() || !hi.isFinite()) return null // nothing finite to draw

        var yLo = lo
        var yHi = hi
        if (yLo == yHi) {
            val pad = max(1.0, abs(yLo) * 0.1)
            yLo -= pad; yHi += pad
        } else {
            val pad = (yHi - yLo) * 0.08
            yLo -= pad; yHi += pad
        }

        val plotW = (FN_PLOT_WIDTH - FN_PLOT_GUTTER_LEFT - FN_PLOT_PAD_RIGHT).toDouble()
        val plotH = (FN_PLOT_HEIGHT - FN_PLOT_PAD_TOP - FN_PLOT_GUTTER_BOTTOM).toDouble()
        val left = FN_PLOT_GUTTER_LEFT.toDouble()
        val top = FN_PLOT_PAD_TOP.toDouble()
        val ySpan = yHi - yLo

        fun px(i: Int): Double = left + (i.toDouble() / (count - 1).toDouble()) * plotW
        fun py(y: Double): Double = top + (1.0 - (y - yLo) / ySpan) * plotH

        // Build the path, lifting the pen across non-finite gaps.
        val path = StringBuilder(count * 12)
        var penDown = false
        for (i in 0 until count) {
            val y = ys[i]
            if (!y.isFinite()) { penDown = false; continue }
            val cx = plotNum(px(i)); val cy = plotNum(py(y))
            if (!penDown) { path.append('M').append(cx).append(' ').append(cy).append(' '); penDown = true }
            else path.append('L').append(cx).append(' ').append(cy).append(' ')
        }
        if (path.isBlank()) return null

        return buildString {
            append(
                "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 $FN_PLOT_WIDTH $FN_PLOT_HEIGHT' " +
                    "width='$FN_PLOT_WIDTH' height='$FN_PLOT_HEIGHT'>"
            )
            // zero baseline, when the range straddles it
            if (yLo < 0.0 && yHi > 0.0) {
                val zy = plotNum(py(0.0))
                append("<line x1='${plotNum(left)}' y1='$zy' x2='${plotNum(left + plotW)}' y2='$zy' stroke='#444' stroke-width='1' stroke-dasharray='2 2'/>")
            }
            // the curve
            append("<path d='")
            append(path.toString().trim())
            append("' fill='none' stroke='#6cf' stroke-width='1.3' stroke-linecap='round' stroke-linejoin='round' vector-effect='non-scaling-stroke'/>")
            // faint value-range labels (top-left = max, bottom-left = min)
            append("<text x='3' y='${FN_PLOT_PAD_TOP + 3}' fill='#666' font-size='8' font-family='monospace'>${escape(plotLabel(yHi))}</text>")
            append("<text x='3' y='${FN_PLOT_HEIGHT - FN_PLOT_GUTTER_BOTTOM}' fill='#666' font-size='8' font-family='monospace'>${escape(plotLabel(yLo))}</text>")
            // faint domain labels along the bottom
            append("<text x='${plotNum(left)}' y='${FN_PLOT_HEIGHT - 3}' fill='#666' font-size='8' font-family='monospace'>${escape(plotLabel(xMin))}</text>")
            append("<text x='$FN_PLOT_WIDTH' y='${FN_PLOT_HEIGHT - 3}' fill='#666' font-size='8' font-family='monospace' text-anchor='end'>${escape(plotLabel(xMax))}</text>")
            append("</svg>")
        }
    }

    private fun plotNum(n: Double): String = runCatching {
        if (!n.isFinite()) "0" else "%.2f".format(n).trimEnd('0').trimEnd('.')
    }.getOrDefault("0")

    private fun plotLabel(n: Double): String = runCatching {
        when {
            !n.isFinite() -> if (n > 0) "∞" else "-∞"
            n == 0.0 -> "0"
            abs(n) >= 100000.0 || abs(n) < 0.001 -> "%.1e".format(n)
            else -> "%.3f".format(n).trimEnd('0').trimEnd('.')
        }
    }.getOrDefault("?")

    private fun formatString(s: String): String {
        return if (s.length > MAX_STRING_LENGTH) {
            val preview = escape(s.take(MAX_STRING_LENGTH))
            buildString {
                append("<span style='color: #8f8;'>")
                append(preview)
                append("</span>")
                append(" ")
                append(
                    lazyInlineExpanderHtml(
                        value = s,
                        label = "… +${s.length - MAX_STRING_LENGTH} chars",
                        kind = "string",
                        offset = MAX_STRING_LENGTH,
                        title = "String"
                    )
                )
                append(" <span style='color: #888;'>(</span>")
                append(formatNumberToken(s.length))
                append("<span style='color: #888;'> chars)</span>")
            }
        } else {
            "<span style='color: #8f8;'>${escape(s)}</span>"
        }
    }

    private fun formatTypeName(name: String, color: String): String =
        "<span style='color: $color;'>${escape(name)}</span>"

    private fun formatPunctuation(token: String): String =
        "<span style='color: #777;'>${escape(token)}</span>"

    private fun formatIdentifier(name: String): String =
        "<span style='color: #bbb;'>${escape(name)}</span>"

    private fun formatNumberToken(n: Int): String =
        "<span style='color: #8cf;'>$n</span>"

    private fun formatNumberToken(n: Long): String =
        "<span style='color: #8cf;'>$n</span>"

    private fun formatNumberToken(n: String): String =
        "<span style='color: #8cf;'>${escape(n)}</span>"

    private fun formatNumericLiteral(n: Float): String =
        "<span style='color: #8cf;'>${fmt(n)}</span>"

    private fun formatNumericLiteral(n: Double): String =
        "<span style='color: #8cf;'>${fmt(n)}</span>"

    private fun formatSizeSuffix(size: Int): String =
        """ <span style='color: #666;'>(</span>${formatNumberToken(size)}<span style='color: #666;'>)</span>"""

    private fun isBlockVisualization(html: String): Boolean =
        html.trimStart().startsWith("<div")

    private fun shouldShowInlineSeparator(previousHtml: String, currentHtml: String): Boolean =
        !isBlockVisualization(previousHtml) && !isBlockVisualization(currentHtml)

    private fun visibleTextLength(html: String): Int =
        html.replace(Regex("<[^>]*>"), "").length

    private fun renderStructValue(
        typeName: String?,
        typeColor: String,
        keyColor: String?,
        rawFields: List<RawField>,
        hasMore: Boolean,
        trailing: String,
        depth: Int,
        visited: MutableSet<Any>,
        respectDepthLimit: Boolean,
        moreHtml: () -> String
    ): FieldValue {
        val header = if (typeName != null) "<span style='color: $typeColor;'>${escape(typeName)}</span> " else ""
        val fields = rawFields.map { rf ->
            rf.keyHtml to renderFieldValue(rf.rawValue, rf.declaredType, depth + 1, visited, respectDepthLimit)
        }

        // Inline collapse: small, no block/struct children, short.
        val inlineable = !hasMore && fields.size <= INLINE_STRUCT_MAX_FIELDS &&
            fields.all { it.second is FieldValue.Inline }
        if (inlineable) {
            val approxLen = fields.sumOf {
                visibleTextLength(it.first) + visibleTextLength((it.second as FieldValue.Inline).html) + 4
            }
            if (fields.isEmpty() || approxLen <= INLINE_STRUCT_MAX_CHARS) {
                return FieldValue.Inline(buildString {
                    append(header).append(BRACE_OPEN)
                    if (fields.isNotEmpty()) {
                        append(" ")
                        append(fields.joinToString("<span style='color:#666;'>, </span>") {
                            keyArrow(it.first, keyColor) + (it.second as FieldValue.Inline).html
                        })
                        append(" ")
                    }
                    append(BRACE_CLOSE).append(trailing)
                })
            }
        }

        return FieldValue.Struct(buildStructLines(header, keyColor, fields, hasMore, trailing, moreHtml))
    }

    private fun cuddleCloses(lines: List<VizLine>): List<VizLine> {
        val res = ArrayList<VizLine>()
        for (l in lines) {
            val prev = res.lastOrNull()
            if (l.isClose && prev != null && prev.isClose) {
                res[res.size - 1] = VizLine(l.indent, prev.html + l.html, isClose = true)
            } else {
                res.add(l)
            }
        }
        return res
    }

    private fun linesToHtml(lines: List<VizLine>): String = buildString {
        append("<div>")
        lines.forEach {
            append("<div style='padding-left: ${it.indent * INDENT_STEP_PX}px;'>")
            append(it.html)
            append("</div>")
        }
        append("</div>")
    }

    private fun fieldValueToHtml(fv: FieldValue): String = when (fv) {
        is FieldValue.Inline -> fv.html
        is FieldValue.Block -> fv.html
        is FieldValue.Struct -> linesToHtml(fv.lines)
    }

    private fun previewCountForListLike(size: Int): Int {
        if (size <= 0) return 0
        return if (size > LIST_INLINE_ELISION_THRESHOLD) MAX_LIST_PREVIEW else size
    }

    private fun formatMoreSuffix(
        extra: Int,
        noun: String,
        value: Any?,
        title: String,
        kind: String,
        offset: Int,
        depth: Int
    ): String {
        if (extra <= 0) return ""
        return " " + lazyInlineExpanderHtml(
            value = value,
            label = "… +$extra more $noun",
            kind = kind,
            offset = offset,
            depth = depth,
            title = title
        )
    }

    private fun formatStatsSummary(stats: Stats): String {
        return buildString {
            append(" <span style='color: #888;'>[μ=</span>")
            append(formatNumericLiteral(stats.mean))
            append("<span style='color: #888;'>, σ=</span>")
            append(formatNumericLiteral(stats.stdDev))
            append("<span style='color: #888;'>, range=</span>")
            append(formatNumericLiteral(stats.min))
            append("<span style='color: #888;'>…</span>")
            append(formatNumericLiteral(stats.max))
            append("<span style='color: #888;'>]</span>")
        }
    }

    private fun formatVec2(v: Vector2fc): String {
        val text = buildString {
            append(formatTypeName("vec2", "#fc8"))
            append(formatPunctuation("("))
            append(formatNumericLiteral(v.x()))
            append(formatPunctuation(", "))
            append(formatNumericLiteral(v.y()))
            append(formatPunctuation(")"))
        }
        return withLinalgThumbnail(text, VEC_THUMBNAIL_SIZE, VEC_THUMBNAIL_SIZE) {
            renderVec2Thumbnail(v.x(), v.y())
        }
    }

    private fun formatVec3(v: Vector3fc): String {
        val text = buildString {
            append(formatTypeName("vec3", "#fc8"))
            append(formatPunctuation("("))
            append(formatNumericLiteral(v.x()))
            append(formatPunctuation(", "))
            append(formatNumericLiteral(v.y()))
            append(formatPunctuation(", "))
            append(formatNumericLiteral(v.z()))
            append(formatPunctuation(")"))
        }
        return withLinalgThumbnail(text, VEC_THUMBNAIL_SIZE, VEC_THUMBNAIL_SIZE) {
            renderVec3Thumbnail(v.x(), v.y(), v.z())
        }
    }

    private fun formatVec4(v: Vector4fc): String {
        val text = buildString {
            append(formatTypeName("vec4", "#fc8"))
            append(formatPunctuation("("))
            append(formatNumericLiteral(v.x()))
            append(formatPunctuation(", "))
            append(formatNumericLiteral(v.y()))
            append(formatPunctuation(", "))
            append(formatNumericLiteral(v.z()))
            append(formatPunctuation(", "))
            append(formatNumericLiteral(v.w()))
            append(formatPunctuation(")"))
        }
        return withLinalgThumbnail(text, VEC_THUMBNAIL_SIZE, VEC_THUMBNAIL_SIZE) {
            renderVec4Thumbnail(v.x(), v.y(), v.z(), v.w())
        }
    }

    private fun renderVec4Thumbnail(x: Float, y: Float, z: Float, w: Float): String? {
        val comps = listOf("x" to x, "y" to y, "z" to z, "w" to w)
        if (comps.none { it.second.isFinite() }) return null

        val size = VEC_THUMBNAIL_SIZE.toDouble()
        val maxAbs = comps.mapNotNull { (_, c) -> c.takeIf { it.isFinite() }?.let { abs(it.toDouble()) } }
            .maxOrNull() ?: 0.0
        val labelBand = 11.0
        val plotTop = 4.0
        val plotBottom = size - labelBand
        val zero = (plotTop + plotBottom) / 2.0
        val halfHeight = (plotBottom - zero) - 2.0
        val slot = size / comps.size
        val barWidth = slot * 0.52

        return buildString {
            append(svgOpen(VEC_THUMBNAIL_SIZE, VEC_THUMBNAIL_SIZE))
            appendAxis(this, 3.0, zero, size - 3.0, zero)
            comps.forEachIndexed { i, (label, value) ->
                val cx = slot * (i + 0.5)
                val left = cx - barWidth / 2.0
                if (!value.isFinite()) {
                    append(
                        "<rect x='${plotNum(left)}' y='${plotNum(zero - 3.0)}' width='${plotNum(barWidth)}' " +
                            "height='6' fill='${matrixCellColor(value, maxAbs)}'/>"
                    )
                } else {
                    val t = if (maxAbs > 0.0) abs(value.toDouble()) / maxAbs else 0.0
                    val h = (t * halfHeight).coerceAtLeast(if (value == 0f) 0.0 else 1.0)
                    val top = if (value >= 0f) zero - h else zero
                    append(
                        "<rect x='${plotNum(left)}' y='${plotNum(top)}' width='${plotNum(barWidth)}' " +
                            "height='${plotNum(h)}' fill='${matrixCellColor(value, maxAbs)}'/>"
                    )
                }
                append(
                    "<text x='${plotNum(cx)}' y='${plotNum(size - 2.0)}' fill='#666' font-size='7' " +
                        "font-family='monospace' text-anchor='middle'>$label</text>"
                )
            }
            append("</svg>")
        }
    }

    private fun formatQuat(q: Quaternionfc): String {
        return buildString {
            append(formatTypeName("quat", "#f8c"))
            append(formatPunctuation("("))
            append(formatNumericLiteral(q.x()))
            append(formatPunctuation(", "))
            append(formatNumericLiteral(q.y()))
            append(formatPunctuation(", "))
            append(formatNumericLiteral(q.z()))
            append(formatPunctuation(", "))
            append(formatNumericLiteral(q.w()))
            append(formatPunctuation(")"))
        }
    }

    private fun formatMatrix(m: Matrix2fc): String {
        val text = buildString {
            append(formatTypeName("mat2", "#cf8"))
            append(" ")
            append(formatPunctuation("["))
            append(formatNumericLiteral(m.m00()))
            append(formatPunctuation(", "))
            append(formatNumericLiteral(m.m10()))
            append(formatPunctuation(" / "))
            append(formatNumericLiteral(m.m01()))
            append(formatPunctuation(", "))
            append(formatNumericLiteral(m.m11()))
            append(formatPunctuation("]"))
        }
        val rows = listOf(
            listOf(m.m00(), m.m10()),
            listOf(m.m01(), m.m11())
        )
        val side = 2 * MATRIX_CELL_SIZE
        return withLinalgThumbnail(text, side, side) { renderMatrixThumbnail(rows) }
    }

    private fun formatMatrix(m: Matrix3fc): String {
        val det = m.determinant()
        val text = buildString {
            append(formatTypeName("mat3", "#cf8"))
            append(" ")
            append(formatPunctuation("["))
            append(formatIdentifier("det"))
            append(formatPunctuation("="))
            append(formatNumericLiteral(det))
            append(formatPunctuation("]"))
        }
        val rows = listOf(
            listOf(m.m00(), m.m10(), m.m20()),
            listOf(m.m01(), m.m11(), m.m21()),
            listOf(m.m02(), m.m12(), m.m22())
        )
        val side = 3 * MATRIX_CELL_SIZE
        return withLinalgThumbnail(text, side, side) { renderMatrixThumbnail(rows) }
    }

    private fun formatMatrix(m: Matrix4fc): String {
        val det = m.determinant()
        val translation = Vector3f()
        m.getTranslation(translation)
        val text = buildString {
            append(formatTypeName("mat4", "#cf8"))
            append(" ")
            append(formatPunctuation("["))
            append(formatIdentifier("det"))
            append(formatPunctuation("="))
            append(formatNumericLiteral(det))
            append(formatPunctuation(", "))
            append(formatIdentifier("t"))
            append(formatPunctuation("=("))
            append(formatNumericLiteral(translation.x))
            append(formatPunctuation(", "))
            append(formatNumericLiteral(translation.y))
            append(formatPunctuation(", "))
            append(formatNumericLiteral(translation.z))
            append(formatPunctuation(")"))
            append(formatPunctuation("]"))
        }
        val rows = listOf(
            listOf(m.m00(), m.m10(), m.m20(), m.m30()),
            listOf(m.m01(), m.m11(), m.m21(), m.m31()),
            listOf(m.m02(), m.m12(), m.m22(), m.m32()),
            listOf(m.m03(), m.m13(), m.m23(), m.m33())
        )
        val side = 4 * MATRIX_CELL_SIZE
        return withLinalgThumbnail(text, side, side) { renderMatrixThumbnail(rows) }
    }

    private fun formatMatrix(m: Matrix2dc): String {
        val text = buildString {
            append(formatTypeName("mat2d", "#cf8"))
            append(" ")
            append(formatPunctuation("["))
            append(formatNumericLiteral(m.m00()))
            append(formatPunctuation(", "))
            append(formatNumericLiteral(m.m10()))
            append(formatPunctuation(" / "))
            append(formatNumericLiteral(m.m01()))
            append(formatPunctuation(", "))
            append(formatNumericLiteral(m.m11()))
            append(formatPunctuation("]"))
        }
        val rows = listOf(
            listOf(m.m00().toFloat(), m.m10().toFloat()),
            listOf(m.m01().toFloat(), m.m11().toFloat())
        )
        val side = 2 * MATRIX_CELL_SIZE
        return withLinalgThumbnail(text, side, side) { renderMatrixThumbnail(rows) }
    }

    private fun formatMatrix(m: Matrix3dc): String {
        val det = m.determinant()
        val text = buildString {
            append(formatTypeName("mat3d", "#cf8"))
            append(" ")
            append(formatPunctuation("["))
            append(formatIdentifier("det"))
            append(formatPunctuation("="))
            append(formatNumericLiteral(det))
            append(formatPunctuation("]"))
        }
        val rows = listOf(
            listOf(m.m00().toFloat(), m.m10().toFloat(), m.m20().toFloat()),
            listOf(m.m01().toFloat(), m.m11().toFloat(), m.m21().toFloat()),
            listOf(m.m02().toFloat(), m.m12().toFloat(), m.m22().toFloat())
        )
        val side = 3 * MATRIX_CELL_SIZE
        return withLinalgThumbnail(text, side, side) { renderMatrixThumbnail(rows) }
    }

    private fun formatMatrix(m: Matrix4dc): String {
        val det = m.determinant()
        val text = buildString {
            append(formatTypeName("mat4d", "#cf8"))
            append(" ")
            append(formatPunctuation("["))
            append(formatIdentifier("det"))
            append(formatPunctuation("="))
            append(formatNumericLiteral(det))
            append(formatPunctuation(", "))
            append(formatIdentifier("t"))
            append(formatPunctuation("=("))
            append(formatNumericLiteral(m.m30()))
            append(formatPunctuation(", "))
            append(formatNumericLiteral(m.m31()))
            append(formatPunctuation(", "))
            append(formatNumericLiteral(m.m32()))
            append(formatPunctuation(")"))
            append(formatPunctuation("]"))
        }
        val rows = listOf(
            listOf(m.m00().toFloat(), m.m10().toFloat(), m.m20().toFloat(), m.m30().toFloat()),
            listOf(m.m01().toFloat(), m.m11().toFloat(), m.m21().toFloat(), m.m31().toFloat()),
            listOf(m.m02().toFloat(), m.m12().toFloat(), m.m22().toFloat(), m.m32().toFloat()),
            listOf(m.m03().toFloat(), m.m13().toFloat(), m.m23().toFloat(), m.m33().toFloat())
        )
        val side = 4 * MATRIX_CELL_SIZE
        return withLinalgThumbnail(text, side, side) { renderMatrixThumbnail(rows) }
    }

    private fun appendArrow(sb: StringBuilder, x1: Double, y1: Double, x2: Double, y2: Double, color: String) {
        sb.append("<line x1='${plotNum(x1)}' y1='${plotNum(y1)}' x2='${plotNum(x2)}' y2='${plotNum(y2)}' stroke='$color' stroke-width='1.6' stroke-linecap='round'/>")
        val ang = atan2(y2 - y1, x2 - x1)
        val headLen = 6.0
        val spread = 0.42
        val hx1 = x2 - headLen * cos(ang - spread)
        val hy1 = y2 - headLen * sin(ang - spread)
        val hx2 = x2 - headLen * cos(ang + spread)
        val hy2 = y2 - headLen * sin(ang + spread)
        sb.append(
            "<polygon points='${plotNum(x2)},${plotNum(y2)} ${plotNum(hx1)},${plotNum(hy1)} " +
                "${plotNum(hx2)},${plotNum(hy2)}' fill='$color'/>"
        )
    }

    private fun matrixCellColor(v: Float, maxAbs: Double): String {
        if (!v.isFinite()) return "#4a3030"
        if (maxAbs <= 0.0) return "#222222"
        val t = min(1.0, abs(v.toDouble()) / maxAbs)
        // neutral (34,34,34) -> #6cf (102,204,255) for +, -> #f83 (248,136,51) for -
        val target = if (v >= 0f) Triple(102, 204, 255) else Triple(248, 136, 51)
        val rr = (34 + (target.first - 34) * t).toInt()
        val gg = (34 + (target.second - 34) * t).toInt()
        val bb = (34 + (target.third - 34) * t).toInt()
        return "#%02x%02x%02x".format(rr.coerceIn(0, 255), gg.coerceIn(0, 255), bb.coerceIn(0, 255))
    }

    private fun matrixCellLabel(v: Float): String = runCatching {
        val a = abs(v)
        when {
            a == 0f -> "0"
            a >= 1000f || a < 0.01f -> "%.0e".format(v)
            else -> "%.2f".format(v).trimEnd('0').trimEnd('.')
        }
    }.getOrDefault("?")

    private fun formatRepeatSuffix(count: Int): String {
        if (count <= 1) return ""
        return " <span style='color: #777;'>same ref x</span>${formatNumberToken(count)}"
    }

    private fun sameReferenceRunLength(list: List<*>, start: Int, endExclusive: Int): Int {
        if (start >= endExclusive) return 0
        val first = list[start] ?: return 1
        if (!shouldCheckCircular(first)) return 1

        var count = 1
        while (start + count < endExclusive && list[start + count] === first) {
            count++
        }
        return count
    }

    private fun renderListPreviewElements(
        list: List<*>,
        start: Int,
        previewEndExclusive: Int,
        listEndExclusive: Int,
        depth: Int,
        visited: MutableSet<Any>,
        respectDepthLimit: Boolean
    ): Pair<List<RenderedListElement>, Int> {
        val elements = mutableListOf<RenderedListElement>()
        var i = start
        while (i < previewEndExclusive) {
            val runLength = sameReferenceRunLength(list, i, listEndExclusive).coerceAtLeast(1)
            val rendered = visualizeValue(list[i], depth + 1, visited, respectDepthLimit)
            elements += RenderedListElement(rendered, runLength)
            i += runLength
        }
        return elements to i
    }

    private fun StringBuilder.appendRenderedListElements(elements: List<RenderedListElement>) {
        elements.forEachIndexed { i, element ->
            if (i > 0 && shouldShowInlineSeparator(elements[i - 1].html, element.html)) {
                append("<span style='color: #888;'>, </span>")
            }
            append(element.html)
            append(formatRepeatSuffix(element.repeatCount))
        }
    }

    private fun recordTableHtml(list: List<*>): String? {
        val first = list.firstOrNull() ?: return null
        if (first is ToHTML || ValuePrinterRegistry.getPrinter(first) != null) return null
        if (first::class.java.name.startsWith("kotlin.")) return null
        if (list.all { it is List<*> }) return null

        val table = recordTable(list) ?: return null
        if (table.rows.any { row -> row.any { !isScalarCell(it) } }) return null
        table.maxRows = RECORD_TABLE_MAX_ROWS
        return table.toHTML()
    }

    private fun isScalarCell(value: Any?): Boolean =
        value == null || value is Number || value is Boolean || value is Char ||
            value is CharSequence || value is Enum<*>

    private fun formatList(
        list: List<*>,
        depth: Int,
        visited: MutableSet<Any>,
        expandValue: Any? = list,
        expandTitle: String = list::class.simpleName ?: "List",
        respectDepthLimit: Boolean = true
    ): String {
        if (list.isEmpty()) return "<span style='color: #888;'>[empty list]</span>"

        // A homogeneous list of imaging detections (corners, Hough peaks, flow vectors, images) is a
        // picture, not a table of records. Returns null for every other list.
        ImagingVisualizer.formatList(list)?.let { return it }

        // And a list that *is* a table of records gets drawn as one. Top level only: nested inside a
        // struct there is no width to spend on columns.
        if (depth == 0) recordTableHtml(list)?.let { return it }

        val size = list.size
        val previewCount = previewCountForListLike(size)
        return buildString {
            append("<span style='color: #aaa;'>[</span>")

            val (renderedPreview, nextOffset) = renderListPreviewElements(
                list = list,
                start = 0,
                previewEndExclusive = previewCount,
                listEndExclusive = size,
                depth = depth,
                visited = visited,
                respectDepthLimit = respectDepthLimit
            )
            appendRenderedListElements(renderedPreview)

            if (size > nextOffset) {
                append(
                    formatMoreSuffix(
                        size - nextOffset,
                        "items",
                        expandValue,
                        expandTitle,
                        "list",
                        nextOffset,
                        depth
                    )
                )

                // Add summary stats if all numbers
                if (list.all { it is Number }) {
                    @Suppress("UNCHECKED_CAST")
                    val numbers = list as List<Number>
                    val stats = calculateStats(numbers)
                    append(formatStatsSummary(stats))
                }
            }

            append("<span style='color: #aaa;'>]</span>")
            append(formatSizeSuffix(size))
            append(renderNumericSparkline(numericSeriesForSparkline(list)))
        }
    }

    private fun formatSet(set: Set<*>, depth: Int, visited: MutableSet<Any>, respectDepthLimit: Boolean): String {
        if (set.isEmpty()) return "<span style='color: #888;'>{empty set}</span>"

        val size = set.size
        val previewCount = previewCountForListLike(size)
        return buildString {
            append("<span style='color: #aaa;'>{</span>")

            val preview = set.take(previewCount)
            val renderedPreview = preview.map { item ->
                visualizeValue(item, depth + 1, visited, respectDepthLimit)
            }
            renderedPreview.forEachIndexed { i, rendered ->
                if (i > 0 && shouldShowInlineSeparator(renderedPreview[i - 1], rendered)) {
                    append("<span style='color: #888;'>, </span>")
                }
                append(rendered)
            }

            if (size > previewCount) {
                append(
                    formatMoreSuffix(
                        size - previewCount,
                        "items",
                        set,
                        set::class.simpleName ?: "Set",
                        "list",
                        previewCount,
                        depth
                    )
                )
            }

            append("<span style='color: #aaa;'>}</span>")
            append(formatSizeSuffix(size))
        }
    }

    private fun formatPair(
        pair: Pair<*, *>, depth: Int, visited: MutableSet<Any>, respectDepthLimit: Boolean
    ): String {
        val first = visualizeValue(pair.first, depth + 1, visited, respectDepthLimit)
        val second = visualizeValue(pair.second, depth + 1, visited, respectDepthLimit)
        return "$first<span style='color: #777;'> to </span>$second"
    }

    private fun formatMap(map: Map<*, *>, depth: Int, visited: MutableSet<Any>, respectDepthLimit: Boolean): String {
        if (map.isEmpty()) return "<span style='color: #888;'>{empty map}</span>"
        return fieldValueToHtml(structValueFromMap(map, depth, visited, respectDepthLimit))
    }

    private fun structValueFromMap(
        map: Map<*, *>, depth: Int, visited: MutableSet<Any>, respectDepthLimit: Boolean
    ): FieldValue {
        val size = map.size
        val hasMore = size > MAX_MAP_ENTRIES + ELISION_SLACK
        val shown = if (hasMore) MAX_MAP_ENTRIES else size
        val entries = map.entries.take(shown).toList()
        val rawFields = entries.map { (key, value) ->
            RawField(visualizeValue(key, depth + 1, visited, respectDepthLimit), value)
        }
        return renderStructValue(
            typeName = null,
            typeColor = "",
            keyColor = null,
            rawFields = rawFields,
            hasMore = hasMore,
            trailing = formatSizeSuffix(size),
            depth = depth,
            visited = visited,
            respectDepthLimit = respectDepthLimit,
            moreHtml = {
                formatMoreSuffix(
                    size - MAX_MAP_ENTRIES,
                    "entries",
                    map,
                    map::class.simpleName ?: "Map",
                    "map",
                    MAX_MAP_ENTRIES,
                    depth
                )
            }
        )
    }

    private fun formatArray(arr: Array<*>, depth: Int, visited: MutableSet<Any>, respectDepthLimit: Boolean): String {
        return formatList(
            arr.toList(),
            depth,
            visited,
            expandValue = arr,
            expandTitle = arr::class.simpleName ?: "Array",
            respectDepthLimit = respectDepthLimit
        )
    }

    private fun formatByteArray(arr: ByteArray): String {
        if (arr.isEmpty()) return "<span style='color: #888;'>[empty bytes]</span>"

        // Encoded raster? Render it inline so `display(PngEncoder.encode(px, w, h))` (and any
        // PNG/JPEG/GIF bytes) shows the picture instead of a hex dump.
        imageMimeType(arr)?.let { mime ->
            val b64 = java.util.Base64.getEncoder().encodeToString(arr)
            // Absolute max-width (not 100%): the box output panel is shrink-wrap, so a percentage
            // width collapses the image; an absolute cap lets the panel size to the picture while
            // still scaling down on narrow pages (the docs theme re-caps at the column width).
            return "<img src='data:$mime;base64,$b64' " +
                "style='max-width:900px;height:auto;border-radius:6px;display:block' " +
                "alt='${arr.size}-byte $mime image'/>"
        }

        // Encoded audio? Render a player so `display(WavFloatArrayWriter.encodeMono16(sig, sr))` plays.
        if (isWav(arr)) {
            val b64 = java.util.Base64.getEncoder().encodeToString(arr)
            return "<audio controls src='data:audio/wav;base64,$b64' " +
                "style='width:420px;max-width:100%;display:block'></audio>"
        }

        return buildString {
            append("<span style='color: #c8f;'>bytes[</span>")
            val preview = arr.take(8)
            append(preview.joinToString(" ") { formatNumberToken("%02x".format(it)) })
            if (arr.size > 8) {
                append(" ")
                append(
                    lazyInlineExpanderHtml(
                        value = arr,
                        label = "… +${arr.size - 8} more bytes",
                        kind = "bytes",
                        offset = 8,
                        title = arr::class.simpleName ?: "ByteArray"
                    )
                )
            }
            append("<span style='color: #c8f;'>]</span>")
            append(formatSizeSuffix(arr.size))
        }
    }

    private fun isWav(a: ByteArray): Boolean =
        a.size >= 12 &&
            a[0] == 'R'.code.toByte() && a[1] == 'I'.code.toByte() &&
            a[2] == 'F'.code.toByte() && a[3] == 'F'.code.toByte() &&
            a[8] == 'W'.code.toByte() && a[9] == 'A'.code.toByte() &&
            a[10] == 'V'.code.toByte() && a[11] == 'E'.code.toByte()

    private fun formatIntArray(arr: IntArray): String {
        if (arr.isEmpty()) return "<span style='color: #888;'>[empty ints]</span>"

        val previewCount = previewCountForListLike(arr.size)
        return buildString {
            append("<span style='color: #aaa;'>[</span>")
            val preview = arr.take(previewCount)
            append("<span style='color: #8cf;'>")
            append(preview.joinToString(", "))
            append("</span>")

            if (arr.size > previewCount) {
                append(
                    formatMoreSuffix(
                        arr.size - previewCount,
                        "items",
                        arr,
                        arr::class.simpleName ?: "IntArray",
                        "list",
                        previewCount,
                        0
                    )
                )
                val stats = calculateStats(arr.map { it.toDouble() })
                append(formatStatsSummary(stats))
            }

            append("<span style='color: #aaa;'>]</span>")
            append(formatSizeSuffix(arr.size))
            append(renderNumericSparkline(arr.map { it.toDouble() }))
        }
    }

    private fun formatFloatArray(arr: FloatArray): String {
        if (arr.isEmpty()) return "<span style='color: #888;'>[empty floats]</span>"

        val previewCount = previewCountForListLike(arr.size)
        return buildString {
            append("<span style='color: #aaa;'>[</span>")
            val preview = arr.take(previewCount)
            append("<span style='color: #8cf;'>")
            append(preview.joinToString(", ") { fmt(it) })
            append("</span>")

            if (arr.size > previewCount) {
                append(
                    formatMoreSuffix(
                        arr.size - previewCount,
                        "items",
                        arr,
                        arr::class.simpleName ?: "FloatArray",
                        "list",
                        previewCount,
                        0
                    )
                )
                val stats = calculateStats(arr.map { it.toDouble() })
                append(formatStatsSummary(stats))
            }

            append("<span style='color: #aaa;'>]</span>")
            append(formatSizeSuffix(arr.size))
            append(renderNumericSparkline(arr.map { it.toDouble() }))
        }
    }

    private fun formatDoubleArray(arr: DoubleArray): String {
        if (arr.isEmpty()) return "<span style='color: #888;'>[empty doubles]</span>"

        val previewCount = previewCountForListLike(arr.size)
        return buildString {
            append("<span style='color: #aaa;'>[</span>")
            val preview = arr.take(previewCount)
            append("<span style='color: #8cf;'>")
            append(preview.joinToString(", ") { fmt(it) })
            append("</span>")

            if (arr.size > previewCount) {
                append(
                    formatMoreSuffix(
                        arr.size - previewCount,
                        "items",
                        arr,
                        arr::class.simpleName ?: "DoubleArray",
                        "list",
                        previewCount,
                        0
                    )
                )
                val stats = calculateStats(arr.toList())
                append(formatStatsSummary(stats))
            }

            append("<span style='color: #aaa;'>]</span>")
            append(formatSizeSuffix(arr.size))
            append(renderNumericSparkline(arr.toList()))
        }
    }

    private fun renderNumericSparkline(values: List<Double>): String =
        runCatching { buildNumericSparkline(values) }.getOrDefault("")

    private fun buildNumericSparkline(values: List<Double>): String {
        if (values.size < SPARKLINE_MIN_POINTS) return ""

        val total = values.size
        val downsampled = total > SPARKLINE_MAX_SAMPLES
        val samples: List<Double> = if (!downsampled) values else {
            val step = total.toDouble() / SPARKLINE_MAX_SAMPLES.toDouble()
            List(SPARKLINE_MAX_SAMPLES) { i -> values[(i * step).toInt().coerceIn(0, total - 1)] }
        }

        var lo = Double.POSITIVE_INFINITY
        var hi = Double.NEGATIVE_INFINITY
        var finite = 0
        for (v in samples) {
            if (!v.isFinite()) continue
            finite++
            if (v < lo) lo = v
            if (v > hi) hi = v
        }
        if (finite < SPARKLINE_MIN_POINTS) return "" // not enough finite data to be meaningful

        var yLo = lo
        var yHi = hi
        if (yLo == yHi) {
            val pad = max(1.0, abs(yLo) * 0.1)
            yLo -= pad; yHi += pad
        } else {
            val pad = (yHi - yLo) * 0.08
            yLo -= pad; yHi += pad
        }
        val ySpan = yHi - yLo
        if (!ySpan.isFinite() || ySpan <= 0.0) return ""

        val n = samples.size
        val w = SPARKLINE_WIDTH.toDouble()
        val h = SPARKLINE_HEIGHT.toDouble()
        val padY = 2.0
        val plotH = h - padY * 2.0

        fun px(i: Int): Double = if (n <= 1) w * 0.5 else (i.toDouble() / (n - 1).toDouble()) * w
        fun py(y: Double): Double = padY + (1.0 - (y - yLo) / ySpan) * plotH

        // Build the path, lifting the pen across non-finite gaps (as renderFnPlot does).
        val path = StringBuilder(n * 10)
        var penDown = false
        for (i in 0 until n) {
            val y = samples[i]
            if (!y.isFinite()) { penDown = false; continue }
            val cx = plotNum(px(i)); val cy = plotNum(py(y))
            if (!penDown) { path.append('M').append(cx).append(' ').append(cy).append(' '); penDown = true }
            else path.append('L').append(cx).append(' ').append(cy).append(' ')
        }
        if (path.isBlank()) return ""

        val note = if (downsampled) " (downsampled $total→$n)" else ""
        return buildString {
            append("<span style='display: inline-block; vertical-align: middle; margin-left: 6px; ")
            append("border: 1px solid #333; border-radius: 3px; background: #111; ")
            append("width: ${SPARKLINE_WIDTH}px; height: ${SPARKLINE_HEIGHT}px; overflow: hidden;' ")
            append("title='sparkline of $total value${if (total == 1) "" else "s"}$note'>")
            append("<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 $SPARKLINE_WIDTH $SPARKLINE_HEIGHT' ")
            append("width='$SPARKLINE_WIDTH' height='$SPARKLINE_HEIGHT'>")
            // faint dashed zero baseline when the *data* straddles zero
            // (test against lo/hi, not the padded range, so a ramp from 0 up
            // doesn't spuriously grow a baseline once padding dips below zero)
            if (lo < 0.0 && hi > 0.0) {
                val zy = plotNum(py(0.0))
                append("<line x1='0' y1='$zy' x2='$SPARKLINE_WIDTH' y2='$zy' stroke='#444' stroke-width='1' stroke-dasharray='2 2'/>")
            }
            append("<path d='")
            append(path.toString().trim())
            append("' fill='none' stroke='#6cf' stroke-width='1.2' stroke-linecap='round' stroke-linejoin='round' vector-effect='non-scaling-stroke'/>")
            append("</svg>")
            append("</span>")
        }
    }

    private fun formatDataClass(obj: Any, depth: Int, visited: MutableSet<Any>, respectDepthLimit: Boolean): String {
        val className = obj::class.simpleName ?: "DataClass"
        return try {
            fieldValueToHtml(structValueFromDataClass(obj, depth, visited, respectDepthLimit))
        } catch (e: Exception) {
            "<span style='color: #f88;'>$className [reflection failed: ${e.message}]</span>"
        }
    }

    private fun structValueFromDataClass(
        obj: Any, depth: Int, visited: MutableSet<Any>, respectDepthLimit: Boolean
    ): FieldValue {
        val className = obj::class.simpleName ?: "DataClass"
        val properties = obj::class.memberProperties
        if (properties.isEmpty()) {
            return FieldValue.Inline("<span style='color: #cc8;'>$className()</span>")
        }

        val entries = properties.toList()
        val hasMore = entries.size > MAX_OBJECT_FIELDS + ELISION_SLACK
        val previewEntries = if (hasMore) entries.take(MAX_OBJECT_FIELDS) else entries

        val rawFields = previewEntries.map { prop ->
            val propValue = try {
                prop.isAccessible = true
                prop.getter.call(obj)
            } catch (e: Exception) {
                "[error: ${e.message}]"
            }
            RawField(escape(prop.name), propValue, prop.returnType)
        }

        return renderStructValue(
            typeName = className,
            typeColor = "#cc8",
            keyColor = "#aaf",
            rawFields = rawFields,
            hasMore = hasMore,
            trailing = "",
            depth = depth,
            visited = visited,
            respectDepthLimit = respectDepthLimit,
            moreHtml = {
                lazyInlineExpanderHtml(
                    value = obj,
                    label = "… +${entries.size - previewEntries.size} more fields",
                    kind = "object",
                    offset = previewEntries.size,
                    depth = depth,
                    title = className
                )
            }
        )
    }

    internal fun renderLazyFragment(token: String, kind: String, offset: Int, depth: Int): String? {
        val value = h2GetRawValue(token) ?: return null
        val safeOffset = offset.coerceAtLeast(0)
        val safeDepth = depth.coerceAtLeast(0)
        val visited = newIdentitySet()

        return when (kind.lowercase()) {
            "full" -> visualizeValue(value, safeDepth, visited, respectDepthLimit = false)
            "string" -> renderStringContinuation(value as? String ?: return null, safeOffset)
            "list" -> renderListContinuation(value, safeOffset, safeDepth, visited)
            "map" -> renderMapContinuation(value as? Map<*, *> ?: return null, safeOffset, safeDepth, visited)
            "object" -> renderDataClassContinuation(value, safeOffset, safeDepth, visited)
            "bytes" -> renderByteArrayContinuation(value as? ByteArray ?: return null, safeOffset)
            else -> null
        }
    }

    private fun renderStringContinuation(value: String, offset: Int): String {
        val safeStart = offset.coerceIn(0, value.length)
        if (safeStart >= value.length) return ""
        val nextEnd = min(value.length, safeStart + STRING_EXPANSION_CHUNK)

        return buildString {
            append("<span style='color: #8f8;'>")
            append(escape(value.substring(safeStart, nextEnd)))
            append("</span>")
            if (nextEnd < value.length) {
                append(" ")
                append(
                    lazyInlineExpanderHtml(
                        value = value,
                        label = "… +${value.length - nextEnd} chars",
                        kind = "string",
                        offset = nextEnd,
                        title = "String"
                    )
                )
            }
        }
    }

    private fun renderByteArrayContinuation(value: ByteArray, offset: Int): String {
        val safeStart = offset.coerceIn(0, value.size)
        if (safeStart >= value.size) return ""
        val nextEnd = min(value.size, safeStart + BYTE_EXPANSION_CHUNK)

        return buildString {
            append(value.sliceArray(safeStart until nextEnd).joinToString(" ") { formatNumberToken("%02x".format(it)) })
            if (nextEnd < value.size) {
                append(" ")
                append(
                    lazyInlineExpanderHtml(
                        value = value,
                        label = "… +${value.size - nextEnd} more bytes",
                        kind = "bytes",
                        offset = nextEnd,
                        title = value::class.simpleName ?: "ByteArray"
                    )
                )
            }
        }
    }

    private fun renderListContinuation(value: Any?, offset: Int, depth: Int, visited: MutableSet<Any>): String? {
        val list = toListLike(value) ?: return null
        val safeStart = offset.coerceIn(0, list.size)
        if (safeStart >= list.size) return ""
        val nextEnd = min(list.size, safeStart + LIST_EXPANSION_CHUNK)
        val title = valueTitle(value, "List")

        return buildString {
            val (rendered, nextOffset) = renderListPreviewElements(
                list = list,
                start = safeStart,
                previewEndExclusive = nextEnd,
                listEndExclusive = list.size,
                depth = depth,
                visited = visited,
                respectDepthLimit = false
            )
            appendRenderedListElements(rendered)
            if (nextOffset < list.size) {
                append(
                    formatMoreSuffix(
                        list.size - nextOffset,
                        "items",
                        value,
                        title,
                        "list",
                        nextOffset,
                        depth
                    )
                )
            }
        }
    }

    private fun renderMapContinuation(
        value: Map<*, *>,
        offset: Int,
        depth: Int,
        visited: MutableSet<Any>
    ): String {
        val entries = value.entries.toList()
        val safeStart = offset.coerceIn(0, entries.size)
        if (safeStart >= entries.size) return ""
        val nextEnd = min(entries.size, safeStart + MAP_EXPANSION_CHUNK)
        val hasMore = nextEnd < entries.size
        val title = valueTitle(value, "Map")

        val rawFields = entries.subList(safeStart, nextEnd).map { (key, entryValue) ->
            RawField(visualizeValue(key, depth + 1, visited, respectDepthLimit = false), entryValue)
        }
        val more = if (hasMore) {
            formatMoreSuffix(entries.size - nextEnd, "entries", value, title, "map", nextEnd, depth)
        } else null
        return renderContinuationFields(rawFields, keyColor = null, depth = depth, visited = visited, moreExpander = more)
    }

    private fun renderDataClassContinuation(
        value: Any?,
        offset: Int,
        depth: Int,
        visited: MutableSet<Any>
    ): String {
        val obj = value ?: return ""
        if (!obj::class.isData) {
            return visualizeValue(obj, depth, visited, respectDepthLimit = false)
        }

        val entries = obj::class.memberProperties.toList()
        val safeStart = offset.coerceIn(0, entries.size)
        if (safeStart >= entries.size) return ""
        val nextEnd = min(entries.size, safeStart + OBJECT_EXPANSION_CHUNK)
        val hasMore = nextEnd < entries.size
        val className = valueTitle(obj, "DataClass")

        val rawFields = entries.subList(safeStart, nextEnd).map { prop ->
            val propValue = try {
                prop.isAccessible = true
                prop.getter.call(obj)
            } catch (e: Exception) {
                "[error: ${e.message}]"
            }
            RawField(escape(prop.name), propValue, prop.returnType)
        }
        val more = if (hasMore) {
            lazyInlineExpanderHtml(
                value = obj,
                label = "… +${entries.size - nextEnd} more fields",
                kind = "object",
                offset = nextEnd,
                depth = depth,
                title = className
            )
        } else null
        return renderContinuationFields(rawFields, keyColor = "#aaf", depth = depth, visited = visited, moreExpander = more)
    }

    private fun toListLike(value: Any?): List<*>? = when (value) {
        is List<*> -> value
        is Set<*> -> value.toList()
        is Array<*> -> value.toList()
        is ByteArray -> value.asList()
        is ShortArray -> value.asList()
        is IntArray -> value.asList()
        is LongArray -> value.asList()
        is FloatArray -> value.asList()
        is DoubleArray -> value.asList()
        is BooleanArray -> value.asList()
        is CharArray -> value.asList()
        else -> null
    }

    private fun valueTitle(value: Any?, fallback: String): String {
        val title = value?.let { it::class.simpleName ?: it::class.java.simpleName }
        return title?.ifBlank { fallback } ?: fallback
    }


    private fun fmt(n: Float): String {
        return when {
            n.isNaN() -> "NaN"
            n.isInfinite() -> if (n > 0) "∞" else "-∞"
            abs(n) < 0.001f && n != 0f -> "%.2e".format(n)
            abs(n) > 1000f -> "%.2e".format(n)
            else -> "%.3f".format(n).trimEnd('0').trimEnd('.')
        }
    }

    private fun fmt(n: Double): String {
        return when {
            n.isNaN() -> "NaN"
            n.isInfinite() -> if (n > 0) "∞" else "-∞"
            abs(n) < 0.001 && n != 0.0 -> "%.2e".format(n)
            abs(n) > 1000.0 -> "%.2e".format(n)
            else -> "%.3f".format(n).trimEnd('0').trimEnd('.')
        }
    }

    private fun lookupBoxReference(boxId: String): BoxReference? {
        val candidates = candidateBoxIds(boxId)
        val currentSession: SessionInformation? = thisSessionInfo.get()
        currentSession?.let { session ->
            candidates.forEach { candidate ->
                session.boxes[candidate]?.let { currentBox ->
                    return BoxReference(
                        uid = currentBox.id,
                        name = currentBox.name.ifBlank { currentBox.id }
                    )
                }
            }
        }

        documents.values.forEach { sessionInfo ->
            candidates.forEach { candidateId ->
                val candidate = sessionInfo.boxes[candidateId] ?: return@forEach
                return BoxReference(
                    uid = candidate.id,
                    name = candidate.name.ifBlank { candidate.id }
                )
            }
        }

        return null
    }

    private fun candidateBoxIds(boxId: String): List<String> {
        val candidates = linkedSetOf<String>()
        candidates += boxId
        candidates += boxId.lowercase()
        if (boxId.startsWith("_")) {
            val noPrefix = boxId.drop(1)
            candidates += noPrefix
            candidates += noPrefix.lowercase()
        }

        UNDERSCORE_UUID_REGEX.matchEntire(boxId)?.let { m ->
            val hyphenUuid = "${m.groupValues[1]}-${m.groupValues[2]}-${m.groupValues[3]}-${m.groupValues[4]}-${m.groupValues[5]}"
            candidates += hyphenUuid
            candidates += hyphenUuid.lowercase()
        }

        return candidates.toList()
    }

    private fun rewriteBoxReferencesInHtml(html: String): String {
        if (html.length < 37 || html.indexOf('_') < 0) return html

        val out = StringBuilder(html.length + 32)
        var cursor = 0
        while (cursor < html.length) {
            val tagStart = html.indexOf('<', cursor)
            if (tagStart < 0) {
                out.append(rewriteBoxReferencesInText(html.substring(cursor), escapePlainText = false))
                break
            }

            if (tagStart > cursor) {
                out.append(rewriteBoxReferencesInText(html.substring(cursor, tagStart), escapePlainText = false))
            }

            val tagEnd = html.indexOf('>', tagStart + 1)
            if (tagEnd < 0) {
                out.append(rewriteBoxReferencesInText(html.substring(tagStart), escapePlainText = false))
                break
            }

            out.append(html, tagStart, tagEnd + 1)
            cursor = tagEnd + 1
        }
        return out.toString()
    }

    private fun rewriteBoxReferencesInText(text: String, escapePlainText: Boolean): String {
        if (text.length < 37 || text.indexOf('_') < 0) {
            return if (escapePlainText) escapeHtmlText(text) else text
        }

        val nameCache = mutableMapOf<String, BoxReference?>()
        val out = StringBuilder(text.length + 32)
        var cursor = 0
        var replacedAny = false

        BOX_ID_TOKEN_REGEX.findAll(text).forEach { match ->
            val boxId = match.groups[1]?.value ?: return@forEach
            val boxRef = nameCache.getOrPut(boxId) { lookupBoxReference(boxId) } ?: return@forEach

            val start = match.range.first
            val endExclusive = match.range.last + 1
            if (start < cursor) return@forEach

            val prefix = text.substring(cursor, start)
            out.append(if (escapePlainText) escapeHtmlText(prefix) else prefix)
            out.append(formatStyledBoxReference(boxRef))
            cursor = endExclusive
            replacedAny = true
        }

        if (!replacedAny) {
            return if (escapePlainText) escapeHtmlText(text) else text
        }

        val suffix = text.substring(cursor)
        out.append(if (escapePlainText) escapeHtmlText(suffix) else suffix)
        return out.toString()
    }

    private fun escape(s: String): String {
        return rewriteBoxReferencesInText(s, escapePlainText = true)
    }

    private fun formatStyledBoxReference(boxRef: BoxReference): String {
        val escapedUid = escapeHtmlText(boxRef.uid)
        return buildString {
            append("<a href='#box:")
            append(escapedUid)
            append("' data-box-uid='")
            append(escapedUid)
            append("' style='text-decoration:none;cursor:pointer;'>")
            append("<span style='color:#fff;font-weight:300;'>")
            append(BOX_SYMBOL)
            append("</span>")
            append("<span style='color:#fff;font-weight:300;font-style:italic;'>")
            append(escapeHtmlText(boxRef.name))
            append("</span>")
            append("</a>")
        }
    }

    private fun escapeHtmlText(text: String): String {
        return text.replace("&", "&amp;")
            .replace("<", "&lt;")
            .replace(">", "&gt;")
            .replace("\"", "&quot;")
            .replace("'", "&#39;")
    }

    private data class Stats(
        val mean: Double,
        val stdDev: Double,
        val min: Double,
        val max: Double
    )

    private fun calculateStats(numbers: List<Number>): Stats {
        if (numbers.isEmpty()) return Stats(0.0, 0.0, 0.0, 0.0)

        val doubles = numbers.map { it.toDouble() }
        val mean = doubles.average()
        val variance = doubles.map { (it - mean).pow(2) }.average()
        val stdDev = sqrt(variance)
        val min = doubles.minOrNull() ?: 0.0
        val max = doubles.maxOrNull() ?: 0.0

        return Stats(mean, stdDev, min, max)
    }
}