ThreeJsViewer.kt

package afield.graphics.three

import afield.geometry.path.FLine
import afield.geometry.path.div
import afield.geometry.path.getFLineEditSession
import afield.geometry.path.registerFLineEditSession
import afield.geometry.path.removeFLineEditSession
import afield.ui.visualization.customGeometryReviewInbox
import afield.ui.visualization.flineTopologyJson
import afield.ui.visualization.lines

import afield.ai.agent.*
import afield.ai.conversation.*
import afield.ai.tools.*
import afield.animation.gesture.*
import afield.animation.interpolation.*
import afield.animation.keyframes.*
import afield.app.diagnostics.*
import afield.app.notifications.*
import afield.app.protocol.*
import afield.app.server.*
import afield.app.settings.*
import afield.audio.synth.*
import afield.data.table.*
import afield.document.context.*
import afield.document.graph.*
import afield.document.history.*
import afield.document.persistence.*
import afield.document.properties.*
import afield.document.workspace.*
import afield.graphics.color.*
import afield.graphics.paint.*
import afield.graphics.vulkan.*
import afield.math.functions.*
import afield.media.capture.*
import afield.media.stream.*
import afield.media.video.*
import afield.runtime.completion.*
import afield.runtime.execution.*
import afield.runtime.kotlin.*
import afield.runtime.lifecycle.*
import afield.tools.automation.*
import afield.tools.docs.*
import afield.ui.controls.*
import afield.ui.layout.*
import afield.ui.notation.*
import afield.ui.output.*
import afield.ui.output.templates.*
import afield.ui.slides.*
import afield.ui.visualization.*
import afield.ai.learning.*
import afield.ai.retrieval.*
import afield.animation.motion.*
import afield.app.commands.*
import afield.audio.analysis.*
import afield.data.collections.*
import afield.data.formats.*
import afield.data.graph.*
import afield.data.sorting.*
import afield.geometry.mesh.*
import afield.geometry.path.*
import afield.geometry.spatial.*
import afield.graphics.interaction.*
import afield.graphics.render.*
import afield.graphics.shader.*
import afield.graphics.text.*
import afield.graphics.vulkan.buffers.*
import afield.io.osc.*
import afield.io.process.*
import afield.lang.lambda.*
import afield.lang.python.*
import afield.lang.remotejs.*
import afield.lang.stacksl.*
import afield.math.autodiff.*
import afield.math.control.*
import afield.math.estimation.*
import afield.math.linalg.*
import afield.math.optimization.*
import afield.math.statistics.*
import afield.math.units.*
import afield.media.image.*
import afield.runtime.languages.*
import afield.simulation.agents.*
import afield.simulation.automata.*
import afield.simulation.particles.*
import afield.study.build.*
import afield.study.evidence.*
import afield.study.search.*
import afield.study.source.*
import afield.study.ui.*
import io.ktor.websocket.*
import kotlinx.coroutines.DelicateCoroutinesApi
import kotlinx.coroutines.GlobalScope
import kotlinx.coroutines.launch
import kotlinx.serialization.EncodeDefault
import kotlinx.serialization.ExperimentalSerializationApi
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.contentOrNull
import kotlinx.serialization.json.decodeFromJsonElement
import kotlinx.serialization.json.jsonObject
import kotlinx.serialization.json.jsonPrimitive
import java.net.URLEncoder
import java.util.UUID
import java.util.concurrent.ConcurrentHashMap
import java.util.concurrent.CopyOnWriteArraySet
import kotlin.math.max
import kotlin.math.min

@Serializable
@OptIn(ExperimentalSerializationApi::class)
data class ThreeGeometryPayload(
    val type: String = "three/geometry",
    val uid: String,
    @EncodeDefault(EncodeDefault.Mode.NEVER) val revision: String? = null,
    @EncodeDefault(EncodeDefault.Mode.NEVER) val sourceBox: String? = null,
    /** Server-owned document identity for optional camera linking; not geometry identity. */
    @EncodeDefault(EncodeDefault.Mode.NEVER)
    val cameraLinkScope: String? = null,
    val lines: ThreeGeometryData? = null,
    val fills: ThreeGeometryData? = null,
    val points: ThreeGeometryData? = null,
    val bounds: ThreeBounds? = null,
    val meta: ThreeMeta? = null,
    val autoFrame: Boolean = true,
    /** Per-FLine interactive objects (separate geometry with click/hover callbacks). */
    val interactive: List<ThreeInteractiveObject> = emptyList(),
    val scene: ThreeEditableScene? = null,
    val editableEnabled: Boolean = false,
    /**
     * Measure / section / explode, when the payload came from [Box.threeInspect].
     *
     * `null` for an ordinary [Box.threeLines] payload, and the viewer then behaves exactly as it did
     * before this existed — no HUD, no clipping planes, no kept copy of the base positions.
     */
    val inspector: ThreeInspector? = null,
    /**
     * The scene as [ThreeDrawable]s — geometry plus per-drawable material state.
     *
     * Empty for every payload that predates [Box.three], and the viewer then takes exactly the path
     * it always took: `lines` / `fills` / `points` above are unchanged, and a payload with no
     * drawables encodes byte for byte as it did before this field existed.
     * `ThreeScenePayloadCompatibilityTest` is what holds that claim, rather than the comment.
     */
    @EncodeDefault(EncodeDefault.Mode.NEVER)
    val drawables: List<ThreeDrawable> = emptyList(),
    /** Explicit same-origin ES modules installed as optional viewer tools; notes cannot load modules. */
    @EncodeDefault(EncodeDefault.Mode.NEVER)
    val toolModules: List<String> = emptyList(),
    /**
     * The viewports, when this is a contact sheet. Empty or one-element means a single full-bleed view.
     *
     * See [ThreePanel] for why a panel is a scissored viewport rather than a second iframe.
     */
    @EncodeDefault(EncodeDefault.Mode.NEVER)
    val panels: List<ThreePanel> = emptyList(),
    /** Panels per row, when there is more than one. */
    @EncodeDefault(EncodeDefault.Mode.NEVER)
    val columns: Int = 1,
    /** Scene background as a CSS colour, or `null` for the viewer's transparent default. */
    @EncodeDefault(EncodeDefault.Mode.NEVER)
    val background: String? = null,
    /**
     * Draw the reference grid and the axis tripod.
     *
     * On for FLines, which is what the viewer has always done. **Off for meshes**, because both
     * helpers are a fixed world size — a 10-unit grid and a 0.9-unit tripod — and a mesh is whatever
     * size its file says. The toy car in `geometry_from_disk.md` is 7cm across, so the grid would be
     * 140 times its width and the tripod would swallow it whole. The CPU rasterizer draws neither,
     * and a figure that changes renderer should not sprout furniture.
     */
    @EncodeDefault(EncodeDefault.Mode.NEVER)
    val helpers: Boolean = true,
    /**
     * The frame size this figure wants, in CSS pixels, for the viewer to report to its host.
     *
     * # Why the viewer has to say it out loud
     *
     * A box output panel sizes itself to its content, and for an iframe it learns the content size
     * from an `afield-iframe-size` event the iframe dispatches on itself (`outputareas2.js`,
     * `bindContentLoadEvents`). Every other embedded viewer gets this from `/iframe_autosize.js`;
     * `threejs_viewer.html` is the one that never included it, because its body is `height: 100%` with
     * `overflow: hidden` and measuring it would only ever report back whatever size it already had.
     *
     * The consequence went unnoticed while the viewer only drew FLines, which want to fill their
     * column anyway. It became very visible when the mesh figures arrived: a six-panel contact sheet
     * asking for 855 pixels of height was silently drawn in 430, and each cell came out about a
     * hundred pixels tall.
     *
     * So the size is sent, and the viewer publishes it. `null` means "say nothing", which is exactly
     * what every payload did before this existed.
     */
    @EncodeDefault(EncodeDefault.Mode.NEVER)
    val frameWidth: Int? = null,
    @EncodeDefault(EncodeDefault.Mode.NEVER)
    val frameHeight: Int? = null,
    /**
     * Where the camera starts, when the caller picked an angle rather than accepting [autoFrame].
     *
     * A docs figure chooses its viewpoint deliberately — half of `geometry_from_disk.md`'s value is
     * that the toy car is seen from the one angle that shows the draped cloth — so the switch from
     * the rasterizer had to bring [MeshView]'s four numbers with it.
     */
    @EncodeDefault(EncodeDefault.Mode.NEVER)
    val camera: ThreeCameraSpec? = null,
    /** Join the document's camera link on load, in this group. See [ThreeSceneBuilder.linkCamera]. */
    @EncodeDefault(EncodeDefault.Mode.NEVER)
    val cameraLink: ThreeCameraLinkSpec? = null,
    /** Smoothed translation following a world point, independent of orbit and zoom. */
    @EncodeDefault(EncodeDefault.Mode.NEVER)
    val cameraFollow: ThreeCameraFollowSpec? = null,
    /** Turn slowly about the up axis until somebody interacts. See [ThreeSceneBuilder.turntable]. */
    @EncodeDefault(EncodeDefault.Mode.NEVER)
    val turntable: ThreeTurntableSpec? = null,
    /** A looping dolly, explode and x-ray move. See [ThreeSceneBuilder.shot]. */
    @EncodeDefault(EncodeDefault.Mode.NEVER)
    val shot: ThreeShotSpec? = null,
    /** Tone mapping, soft shadows and a ground. See [ThreeSceneBuilder.studio]. */
    @EncodeDefault(EncodeDefault.Mode.NEVER)
    val studio: ThreeStudioSpec? = null,
    /**
     * The view's stored part styles, by [ThreeDrawable.id], for the viewer to apply.
     *
     * Set by [ThreeGeometryViewState.update] from the source box's `geometryAppearance`. The viewer
     * applies them itself, as `applyPartAppearance` does, so that a later style change can be a small
     * `three/appearance` message instead of this whole payload encoded again.
     */
    @EncodeDefault(EncodeDefault.Mode.NEVER)
    val partAppearance: Map<String, ThreePartAppearance> = emptyMap(),
    /** Text pinned to points in the scene. See [ThreeSceneBuilder.label]. */
    @EncodeDefault(EncodeDefault.Mode.NEVER)
    val labels: List<ThreeLabel> = emptyList(),
    /** HTML blocks in the corners of the view. See [ThreeSceneBuilder.overlay]. */
    @EncodeDefault(EncodeDefault.Mode.NEVER)
    val overlays: List<ThreeOverlay> = emptyList(),
    /** Grey the scene out, for a picture that is older than its inputs. See [ThreeSceneBuilder.dimmed]. */
    @EncodeDefault(EncodeDefault.Mode.NEVER)
    val dimmed: Boolean = false,
    /** A short line in the bottom-left corner. See [ThreeSceneBuilder.note]. */
    @EncodeDefault(EncodeDefault.Mode.NEVER)
    val note: String? = null,
    /** Show the viewer's tool buttons and counts; `false` for a picture. See [ThreeSceneBuilder.hud]. */
    @EncodeDefault(EncodeDefault.Mode.NEVER)
    val hud: Boolean = true,
    /** Wire only: where a description's arrays are. See `ThreeWire.kt`. */
    @EncodeDefault(EncodeDefault.Mode.NEVER)
    internal val buffers: ThreeWireBuffers? = null,
) {

    fun update(payload: ThreeGeometryPayload) {
        val costs = threeWireCosts(payload)
        val estimate = costs.sumOf { it.bytes }
        if (estimate > payloadLimitBytes) throw threePayloadTooLarge(uid, estimate, payloadLimitBytes, costs, measured = false)
        val generation = UUID.randomUUID().toString()
        // Split first: it names a NaN's part and attribute, where the revision's encoder would not.
        val split = payload.splitForWire(generation)
        val revision = threeReviewRevision(payload)
        val ticket: Long
        val appearance: Map<String, ThreePartAppearance>
        synchronized(this) {
            ticket = ++updatesStarted
            appearance = storedAppearance()[appearanceKey()].orEmpty()
        }
        val ids = payload.drawables.mapTo(HashSet()) { it.id }
        appearance.forEach { (id, style) -> if (id in ids) style.validate() }
        fun ThreeGeometryPayload.stamped() = copy(revision = revision, sourceBox = reviewInbox.owner?.id,
            cameraLinkScope = cameraLinkScope(), partAppearance = appearance)
        val bufferBytes = split.buffers?.bytes ?: 0L
        val description = encodeThreeWire(threeJson, split.description.stamped(), estimate - bufferBytes)
        encodes.incrementAndGet()
        if (description.size + bufferBytes > payloadLimitBytes) {
            throw threePayloadTooLarge(uid, description.size + bufferBytes, payloadLimitBytes, costs, measured = true)
        }
        val limit = payloadLimitBytes
        val native = lazy {
            encodeForNativeClient(threeJson, payload.stamped(), limit).also { if (it != null) encodes.incrementAndGet() }
        }
        // Encoded here, outside the lock, when a native client is already listening.
        if (sessions.any { it !in bufferSessions } || threeGlobalListeners.isNotEmpty()) native.value
        synchronized(this) {
            val nextSession = payload.scene?.sessionId?.takeIf { it.isNotEmpty() }
            if (ticket < updatesCommitted) {
                // A later update is already on screen; this one never will be.
                if (nextSession != editSessionId) nextSession?.let(::removeFLineEditSession)
                return
            }
            updatesCommitted = ticket
            reviewInbox.update(revision)
            sourcePayload = payload
            sourceRevision = revision
            if (editSessionId != nextSession) editSessionId?.let(::removeFLineEditSession)
            editSessionId = nextSession

            val next = Published(generation, description, appearance, split.buffers, native)
            published?.let { old -> old.buffers?.let { recentBuffers.addLast(old.generation to it) } }
            while (recentBuffers.size > RECENT_GENERATIONS) recentBuffers.removeFirst()
            published = next
            onBroadcast?.invoke(description)
            sessions.forEach { if (it in bufferSessions) sendTo(it, description) else sendNative(it, next) }
            // Global listeners (native "subscribe-all" viewers) see every view's updates, including
            // newly-created views: threeLines() calls update() right after creating the view.
            threeGlobalListeners.forEach { sendNative(it, next) }
            // A style that landed while this was encoding is not in it.
            val current = storedAppearance()[appearanceKey()].orEmpty()
            if (current != appearance) broadcast(appearanceMessage(replace = true, parts = current))
        }
    }

@RunsAt(installHandlers)
@OptIn(DelicateCoroutinesApi::class)
fun installThreeJsHandler() {
    rawHandlers.getOrPut(THREE_CHANNEL) { mutableSetOf() }.add { text ->
        val session = thisSession.get()
        val payload = runCatching { Json.parseToJsonElement(text).jsonObject }.getOrNull()
            ?: return@add Handled.no
        val channel = payload["channel"]?.jsonPrimitive?.contentOrNull ?: return@add Handled.no
        if (channel != THREE_CHANNEL) return@add Handled.no
        val uid = payload["debug_uid"]?.jsonPrimitive?.contentOrNull ?: return@add Handled.no

        when (payload["type"]?.jsonPrimitive?.contentOrNull) {
            "three-selection", "three-observation" -> {
                val view = knownThreeViews[uid] ?: return@add Handled.no
                val record = payload["record"] as? kotlinx.serialization.json.JsonObject ?: return@add Handled.no
                val note = payload["type"]?.jsonPrimitive?.contentOrNull == "three-observation"
                inMain {
                    val result = runCatching { view.reviewInbox.receive(record, note) }
                    if (note || result.isFailure) {
                        val answer = kotlinx.serialization.json.buildJsonObject {
                            put("type", kotlinx.serialization.json.JsonPrimitive("three-review-ack"))
                            put("ok", kotlinx.serialization.json.JsonPrimitive(result.isSuccess))
                            put("message", result.getOrNull()?.get("message") ?: kotlinx.serialization.json.JsonPrimitive(result.exceptionOrNull()?.message ?: "Selected in Field"))
                        }
                        runCatching { session.send(answer.toString()) }
                    }
                }
            }
            "three-snapshot" -> {
                val view = knownThreeViews[uid] ?: return@add Handled.no
                val id = payload["id"]?.jsonPrimitive?.contentOrNull ?: return@add Handled.no
                val dataUrl = payload["dataUrl"]?.jsonPrimitive?.contentOrNull ?: return@add Handled.no
                view.receiveSnapshot(id, dataUrl)
            }
            "fline-click" -> {
                // Same wire type and same mapping as the SVG output's handler in `Server.kt`, so the
                // two clickable outputs cannot disagree about what a click returns. `threeJson`
                // ignores the envelope's own keys (`type`, `channel`, `debug_uid`).
                val click = runCatching { threeJson.decodeFromJsonElement<FLineClick>(payload) }.getOrNull()
                    ?: return@add Handled.no
                val callback = getFLineClickCallback(click.callbackId)
                if (callback != null) {
                    val intersection = click.toIntersection()
                    GlobalScope.launch {
                        runCatching { callback(intersection) }
                    }
                }
            }
            "three-surface-click" -> {
                // The mesh half of the same idea, and deliberately the same five lines: decode, look
                // the callback up, hand it the record, never let a user closure's exception reach the
                // websocket read loop.
                val click = runCatching { threeJson.decodeFromJsonElement<ThreeSurfaceClick>(payload) }.getOrNull()
                    ?: return@add Handled.no
                val callback = getThreeSurfaceClickCallback(click.callbackId)
                if (callback != null) {
                    val hit = click.toHit()
                    GlobalScope.launch {
                        runCatching { callback(hit) }
                    }
                }
            }
            "fline-edit-translate" -> {
                val update = runCatching { threeJson.decodeFromJsonElement<FLineTranslatePoints>(payload) }.getOrNull()
                    ?: return@add Handled.no
                val editSession = getFLineEditSession(update.sessionId) ?: return@add Handled.no
                // Deltas and the following commit must retain websocket order.
                runCatching { editSession.translate(update) }
            }
            "fline-edit-commit" -> {
                val id = payload["sessionId"]?.jsonPrimitive?.contentOrNull ?: return@add Handled.no
                val editSession = getFLineEditSession(id) ?: return@add Handled.no
                runCatching { editSession.commit() }
            }
            "fline-edit-add-line" -> {
                val update = runCatching { threeJson.decodeFromJsonElement<FLineAddLine>(payload) }.getOrNull()
                    ?: return@add Handled.no
                val editSession = getFLineEditSession(update.sessionId) ?: return@add Handled.no
                GlobalScope.launch {
                    runCatching { editSession.addLine(update) }
                }
            }
            "fline-edit-begin-line" -> {
                val update = runCatching { threeJson.decodeFromJsonElement<FLineBeginLine>(payload) }.getOrNull()
                    ?: return@add Handled.no
                val editSession = getFLineEditSession(update.sessionId) ?: return@add Handled.no
                GlobalScope.launch {
                    runCatching { editSession.beginLine(update) }
                }
            }
            "fline-edit-append-line" -> {
                val update = runCatching { threeJson.decodeFromJsonElement<FLineAppendLine>(payload) }.getOrNull()
                    ?: return@add Handled.no
                val editSession = getFLineEditSession(update.sessionId) ?: return@add Handled.no
                GlobalScope.launch {
                    runCatching { editSession.appendLine(update) }
                }
            }
            "fline-edit-end-line" -> {
                val update = runCatching { threeJson.decodeFromJsonElement<FLineEndLine>(payload) }.getOrNull()
                    ?: return@add Handled.no
                val editSession = getFLineEditSession(update.sessionId) ?: return@add Handled.no
                GlobalScope.launch {
                    runCatching { editSession.endLine(update) }
                }
            }
            "fline-edit-clear" -> {
                val update = runCatching { threeJson.decodeFromJsonElement<FLineClearSession>(payload) }.getOrNull()
                    ?: return@add Handled.no
                val editSession = getFLineEditSession(update.sessionId) ?: return@add Handled.no
                GlobalScope.launch {
                    runCatching { editSession.clear() }
                }
            }
            "subscribe-all" -> {
                // A discovery client (e.g. the native visionOS viewer) that wants every live view,
                // not one uid. Register it as a global listener and replay all known views' last
                // payloads immediately; future updates arrive via update()'s global broadcast.
                threeGlobalListeners.add(session)
                knownThreeViews.values.forEach { it.replayTo(session) }
            }
            else -> {
                // Default: treat as a hello/attach message. The web viewer's hello asks for `buffers`;
                // a native client's does not, and it is sent JSON it can decode.
                val viewer = knownThreeViews.computeIfAbsent(uid) { ThreeGeometryViewState(uid) }
                viewer.attach(session, buffers = payload["buffers"] != null)
            }
        }
        Handled.yes
    }
}

internal fun buildThreeGeometryPayload(
    uid: String,
    lines: Collection<FLine>,
    samplesPerCubic: Int,
    autoFrame: Boolean,
    editable: Boolean,
    groupKeys: List<String>? = null,
    inspector: ThreeInspector? = null,
    onEditCommitted: ((List<FLine>) -> Unit)? = null
): ThreeGeometryPayload {
    val sourceLines = lines.toList()
    require(groupKeys == null || groupKeys.size == sourceLines.size) {
        "one assembly-group key per line, please: ${groupKeys!!.size} keys for ${sourceLines.size} lines"
    }
    val groupNames = groupKeys?.let { distinctGroupNames(it) }
    val groupOfLine = groupKeys?.map { groupNames!!.indexOf(it) }
    val lineGroups = if (groupOfLine != null) ArrayList<Float>() else null
    val meshGroups = if (groupOfLine != null) ArrayList<Float>() else null
    val pointGroups = if (groupOfLine != null) ArrayList<Float>() else null
    val editSession = if (editable) registerFLineEditSession(sourceLines, null, onEditCommitted) else null
    val samples = samplesPerCubic.coerceAtLeast(2)
    val callbackIds = sourceLines.map { line ->
        line.onClick?.let { cb ->
            val id = "fline-${UUID.randomUUID()}"
            registerFLineClickCallback(id, cb)
            id
        } ?: ""
    }
    val hoverColors = sourceLines.map { line ->
        line.hoverColor?.let { c -> floatArrayOf(c.x, c.y, c.z, c.w) }
    }

    val linePositions = ArrayList<Float>()
    val lineColors = ArrayList<Float>()
    val lineAlphas = ArrayList<Float>()
    val meshPositions = ArrayList<Float>()
    val meshColors = ArrayList<Float>()
    val meshAlphas = ArrayList<Float>()
    val meshIndices = ArrayList<Int>()
    val pointPositions = ArrayList<Float>()
    val pointColors = ArrayList<Float>()
    val pointAlphas = ArrayList<Float>()
    val pointSizes = ArrayList<Float>()
    val geometryBounds = BoundsTracker()
    val interactiveObjects = ArrayList<ThreeInteractiveObject>()

    if (!editable) {
        sourceLines.forEachIndexed { lineIndex, f ->
            val callbackId = callbackIds[lineIndex]
            val hoverColor = hoverColors[lineIndex]
            if (callbackId.isNotEmpty() || hoverColor != null) {
                val localLinePositions = ArrayList<Float>()
                val localLineColors = ArrayList<Float>()
                val localLineAlphas = ArrayList<Float>()
                val localMeshPositions = ArrayList<Float>()
                val localMeshColors = ArrayList<Float>()
                val localMeshAlphas = ArrayList<Float>()
                val localMeshIndices = ArrayList<Int>()
                val localPointPositions = ArrayList<Float>()
                val localPointColors = ArrayList<Float>()
                val localPointAlphas = ArrayList<Float>()
                val localPointSizes = ArrayList<Float>()

                appendFLineGeometry(
                    f = f,
                    samplesPerCubic = samples,
                    linePositions = localLinePositions,
                    lineColors = localLineColors,
                    lineAlphas = localLineAlphas,
                    meshPositions = localMeshPositions,
                    meshColors = localMeshColors,
                    meshAlphas = localMeshAlphas,
                    meshIndices = localMeshIndices,
                    pointPositions = localPointPositions,
                    pointColors = localPointColors,
                    pointAlphas = localPointAlphas,
                    pointSizes = localPointSizes,
                    bounds = geometryBounds
                )

                interactiveObjects += ThreeInteractiveObject(
                    group = groupOfLine?.get(lineIndex) ?: -1,
                    callbackId = callbackId,
                    hoverColor = hoverColor,
                    lines = lineGeometryOrNull(localLinePositions, localLineColors, localLineAlphas),
                    fills = fillGeometryOrNull(localMeshPositions, localMeshColors, localMeshAlphas, localMeshIndices),
                    points = pointGeometryOrNull(localPointPositions, localPointColors, localPointAlphas, localPointSizes),
                    vertices = interactiveVertices(f),
                    lineIndex = lineIndex,
                    label = f.label,
                    // Only a clickable line needs it; hover has nothing to say about which element.
                    topology = if (callbackId.isNotEmpty()) flineTopologyJson(f) else ""
                )
            } else {
                val lineVerticesBefore = linePositions.size / 3
                val meshVerticesBefore = meshPositions.size / 3
                val pointVerticesBefore = pointPositions.size / 3
                appendFLineGeometry(
                    f = f,
                    samplesPerCubic = samples,
                    linePositions = linePositions,
                    lineColors = lineColors,
                    lineAlphas = lineAlphas,
                    meshPositions = meshPositions,
                    meshColors = meshColors,
                    meshAlphas = meshAlphas,
                    meshIndices = meshIndices,
                    pointPositions = pointPositions,
                    pointColors = pointColors,
                    pointAlphas = pointAlphas,
                    pointSizes = pointSizes,
                    bounds = geometryBounds
                )
                if (groupOfLine != null) {
                    val group = groupOfLine[lineIndex].toFloat()
                    repeat(linePositions.size / 3 - lineVerticesBefore) { lineGroups!!.add(group) }
                    repeat(meshPositions.size / 3 - meshVerticesBefore) { meshGroups!!.add(group) }
                    repeat(pointPositions.size / 3 - pointVerticesBefore) { pointGroups!!.add(group) }
                }
            }
        }
    }

    val sceneBounds = BoundsTracker()
    var sceneLineSegments = 0
    var sceneTriangles = 0
    var scenePoints = 0

    val scene = if (editable) ThreeEditableScene(
        sessionId = editSession?.sessionId ?: "",
        lines = sourceLines.mapIndexed { lineIndex, line ->
            var boundaryPoints = 0

            ThreeEditableLine(
                lineIndex = lineIndex,
                color = floatArrayOf(line.color.x, line.color.y, line.color.z, line.color.w),
                thickness = (line.thickness ?: 1.0).toFloat(),
                stroked = line.stroked,
                filled = line.filled,
                pointed = line.pointed,
                pointSize = line.pointSize.toFloat(),
                callbackId = callbackIds[lineIndex],
                hoverColor = hoverColors[lineIndex],
                label = line.label,
                topology = if (callbackIds[lineIndex].isNotEmpty()) flineTopologyJson(line) else "",
                nodes = line.nodes.mapIndexed { nodeIndex, node ->
                    when (node) {
                        is FLine.MoveTo -> {
                            scenePoints += 1
                            boundaryPoints = 1
                            sceneBounds.include(node.to)
                            ThreeEditableNode(
                                nodeIndex = nodeIndex,
                                kind = "move",
                                to = floatArrayOf(node.to.x, node.to.y, node.to.z)
                            )
                        }

                        is FLine.LineTo -> {
                            scenePoints += 1
                            if (boundaryPoints > 0) sceneLineSegments += 1
                            boundaryPoints += 1
                            sceneBounds.include(node.to)
                            ThreeEditableNode(
                                nodeIndex = nodeIndex,
                                kind = "line",
                                to = floatArrayOf(node.to.x, node.to.y, node.to.z)
                            )
                        }

                        is FLine.CubicTo -> {
                            scenePoints += 1
                            if (boundaryPoints > 0) sceneLineSegments += samples
                            boundaryPoints += samples
                            sceneBounds.include(node.to)
                            sceneBounds.include(node.c1)
                            sceneBounds.include(node.c2)
                            ThreeEditableNode(
                                nodeIndex = nodeIndex,
                                kind = "cubic",
                                to = floatArrayOf(node.to.x, node.to.y, node.to.z),
                                c1 = floatArrayOf(node.c1.x, node.c1.y, node.c1.z),
                                c2 = floatArrayOf(node.c2.x, node.c2.y, node.c2.z)
                            )
                        }

                        is FLine.Close -> {
                            if (boundaryPoints > 1) sceneLineSegments += 1
                            boundaryPoints = 0
                            ThreeEditableNode(
                                nodeIndex = nodeIndex,
                                kind = "close"
                            )
                        }
                    }
                }
            )
        }
    ).also {
        if (editable) {
            // Editable mode re-triangulates client-side, with the same rule this side runs
            // (`threejs_viewer.html`, `tessellateCoplanarGroups`), so the reported triangle count is
            // the real one. It used to be a per-subpath fan estimate — `boundaryPoints - 2` — which
            // both over-counted a holed face and under-counted a multi-plane one, and disagreed with
            // the number the same line reports with `editable = false`.
            sourceLines.forEach { line ->
                if (line.filled) {
                    line.tessellate(samples) { _, indices -> sceneTriangles += indices.size / 3 }
                }
            }
        }
    } else null

    val lineGeom = lineGeometryOrNull(linePositions, lineColors, lineAlphas).withGroups(lineGroups)
    val fillGeom = fillGeometryOrNull(meshPositions, meshColors, meshAlphas, meshIndices).withGroups(meshGroups)
    val pointGeom = pointGeometryOrNull(pointPositions, pointColors, pointAlphas, pointSizes)
        .withGroups(pointGroups)

    return ThreeGeometryPayload(
        uid = uid,
        lines = lineGeom,
        fills = fillGeom,
        points = pointGeom,
        bounds = if (editable) sceneBounds.toBounds() else geometryBounds.toBounds(),
        meta = ThreeMeta(
            lineSegments = if (editable) sceneLineSegments else linePositions.size / 6 + interactiveObjects.sumOf { it.lines?.attributes?.get("position")?.array?.size?.div(6) ?: 0 },
            triangles = if (editable) sceneTriangles else meshIndices.size / 3 + interactiveObjects.sumOf { it.fills?.index?.array?.size?.div(3) ?: 0 },
            points = if (editable) scenePoints else pointPositions.size / 3 + interactiveObjects.sumOf { it.points?.attributes?.get("position")?.array?.size?.div(3) ?: 0 }
        ),
        autoFrame = autoFrame,
        interactive = interactiveObjects,
        scene = scene,
        editableEnabled = editable,
        inspector = inspector?.copy(groups = groupNames ?: inspector.groups)
    )
}

private fun ThreeGeometryData?.withGroups(groups: List<Float>?): ThreeGeometryData? {
    if (this == null || groups == null || groups.isEmpty()) return this
    val vertexCount = (attributes["position"]?.array?.size ?: 0) / 3
    check(groups.size == vertexCount) {
        "the assembly-group attribute has ${groups.size} entries for $vertexCount vertices"
    }
    return copy(attributes = attributes + ("group" to ThreeAttribute(itemSize = 1, array = groups.toFloatArray())))
}

private fun lineGeometryOrNull(
    positions: List<Float>,
    colors: List<Float>,
    alphas: List<Float>
): ThreeGeometryData? = if (positions.isNotEmpty()) {
    buildGeometryData(
        positions = positions.toFloatArray(),
        colors = colors.toFloatArray(),
        alphas = alphas.toFloatArray(),
        sizes = null,
        indices = null
    )
} else null

private fun fillGeometryOrNull(
    positions: List<Float>,
    colors: List<Float>,
    alphas: List<Float>,
    indices: List<Int>
): ThreeGeometryData? = if (positions.isNotEmpty()) {
    buildGeometryData(
        positions = positions.toFloatArray(),
        colors = colors.toFloatArray(),
        alphas = alphas.toFloatArray(),
        sizes = null,
        indices = indices.toIntArray()
    )
} else null

private fun pointGeometryOrNull(
    positions: List<Float>,
    colors: List<Float>,
    alphas: List<Float>,
    sizes: List<Float>
): ThreeGeometryData? = if (positions.isNotEmpty()) {
    buildGeometryData(
        positions = positions.toFloatArray(),
        colors = colors.toFloatArray(),
        alphas = alphas.toFloatArray(),
        sizes = sizes.toFloatArray(),
        indices = null
    )
} else null

private fun appendFLineGeometry(
    f: FLine,
    samplesPerCubic: Int,
    linePositions: MutableList<Float>,
    lineColors: MutableList<Float>,
    lineAlphas: MutableList<Float>,
    meshPositions: MutableList<Float>,
    meshColors: MutableList<Float>,
    meshAlphas: MutableList<Float>,
    meshIndices: MutableList<Int>,
    pointPositions: MutableList<Float>,
    pointColors: MutableList<Float>,
    pointAlphas: MutableList<Float>,
    pointSizes: MutableList<Float>,
    bounds: BoundsTracker
) {
    val color = f.color
    if (f.stroked) {
        appendLineSegments(f, samplesPerCubic, color, linePositions, lineColors, lineAlphas, bounds)
    }
    if (f.filled) {
        appendFilledMesh(f, samplesPerCubic, color, meshPositions, meshColors, meshAlphas, meshIndices, bounds)
    }
    if (f.pointed) {
        appendPoints(f, color, pointPositions, pointColors, pointAlphas, pointSizes, bounds)
    }
}

private fun interactiveVertices(f: FLine): List<ThreeInteractiveVertex> =
    f.nodes.mapIndexedNotNull { index, node ->
        if (node is FLine.Close) null
        else ThreeInteractiveVertex(index, floatArrayOf(node.to.x, node.to.y, node.to.z))
    }

private fun buildGeometryData(
    positions: FloatArray,
    colors: FloatArray?,
    alphas: FloatArray?,
    sizes: FloatArray?,
    indices: IntArray?
): ThreeGeometryData {
    val attributes = mutableMapOf<String, ThreeAttribute>()
    attributes["position"] = ThreeAttribute(itemSize = 3, array = positions)
    if (colors != null) {
        attributes["color"] = ThreeAttribute(itemSize = 3, array = colors)
    }
    if (alphas != null) {
        attributes["alpha"] = ThreeAttribute(itemSize = 1, array = alphas)
    }
    if (sizes != null) {
        attributes["size"] = ThreeAttribute(itemSize = 1, array = sizes)
    }
    val index = indices?.takeIf { it.isNotEmpty() }?.let { idx ->
        val maxIndex = idx.maxOrNull() ?: 0
        val type = if (maxIndex > 65535) "Uint32Array" else "Uint16Array"
        ThreeIndex(type = type, array = idx)
    }
    return ThreeGeometryData(attributes = attributes, index = index)
}

private fun appendLineSegments(
    f: FLine,
    samplesPerCubic: Int,
    color: Vec4,
    positions: MutableList<Float>,
    colors: MutableList<Float>,
    alphas: MutableList<Float>,
    bounds: BoundsTracker
) {
    val polyline = ArrayList<Vec3>()
    val alpha = color.w.coerceIn(0f, 1f)

    fun flush() {
        if (polyline.size < 2) return
        for (i in 0 until polyline.size - 1) {
            val a = polyline[i]
            val b = polyline[i + 1]
            positions.add(a.x); positions.add(a.y); positions.add(a.z)
            positions.add(b.x); positions.add(b.y); positions.add(b.z)
            repeat(2) {
                colors.add(color.x); colors.add(color.y); colors.add(color.z)
                alphas.add(alpha)
            }
            bounds.include(a)
            bounds.include(b)
        }
    }

    f.uniform_linearize(samplesPerCubic) { at, instr ->
        val p = vec(at.x, at.y, at.z)
        if (instr < 0) {
            flush()
            polyline.clear()
            polyline.add(p)
        } else {
            polyline.add(p)
        }
    }
    flush()
}

private fun appendFilledMesh(
    f: FLine,
    samplesPerCubic: Int,
    color: Vec4,
    positions: MutableList<Float>,
    colors: MutableList<Float>,
    alphas: MutableList<Float>,
    indices: MutableList<Int>,
    bounds: BoundsTracker
) {
    val alpha = color.w.coerceIn(0f, 1f)
    f.tessellate(samplesPerCubic) { verts, index ->
        val base = positions.size / 3
        var i = 0
        while (i < verts.size) {
            val x = verts[i]
            val y = verts[i + 1]
            val z = verts[i + 2]
            positions.add(x); positions.add(y); positions.add(z)
            colors.add(color.x); colors.add(color.y); colors.add(color.z)
            alphas.add(alpha)
            bounds.include(x, y, z)
            i += 3
        }
        index.forEach { indices.add(base + it) }
    }
}

private fun appendPoints(
    f: FLine,
    color: Vec4,
    positions: MutableList<Float>,
    colors: MutableList<Float>,
    alphas: MutableList<Float>,
    sizes: MutableList<Float>,
    bounds: BoundsTracker
) {
    val alpha = color.w.coerceIn(0f, 1f)
    f.nodes.forEach { node ->
        if (node is FLine.Close) return@forEach
        val p = node.to
        positions.add(p.x); positions.add(p.y); positions.add(p.z)
        colors.add(color.x); colors.add(color.y); colors.add(color.z)
        alphas.add(alpha)
        val size = ((node.pointSize ?: f.pointSize) * 3.0).toFloat()
        sizes.add(size.coerceAtLeast(0.5f))
        bounds.include(p)
    }
}