ElectronBrowserTextureSession.kt

    init {
        val electron = fieldElectronBinary(projectRoot)
        val producer = File(projectRoot, "electron/browser-texture-producer.js")
        listOfNotNull(electron, producer, transport?.nodeBridge).forEach { file ->
            require(file.isFile) {
                "Missing browser texture runtime ${file.absolutePath}; run ./gradlew electronInstall"
            }
        }

        val streamId = (System.nanoTime() and Long.MAX_VALUE).coerceAtLeast(1)
        process = ProcessBuilder(electron.absolutePath, producer.absolutePath)
            .directory(projectRoot)
            .redirectErrorStream(true)
            .apply {
                environment()["FIELD_BROWSER_TEXTURE_URL"] = url
                environment()["FIELD_BROWSER_TEXTURE_WIDTH"] = spec.width.toString()
                environment()["FIELD_BROWSER_TEXTURE_HEIGHT"] = spec.height.toString()
                environment()["FIELD_BROWSER_TEXTURE_DEVICE_SCALE_FACTOR"] = spec.deviceScaleFactor.toString()
                environment()["FIELD_BROWSER_TEXTURE_SLOTS"] = spec.slotCount.toString()
                environment()["FIELD_BROWSER_TEXTURE_CONTROL_PORT"] = server.localPort.toString()
                transport?.nodeBridge?.let { environment()["FIELD_BROWSER_TEXTURE_BRIDGE"] = it.absolutePath }
                environment()["FIELD_BROWSER_TEXTURE_STREAM_ID"] = streamId.toString()
                if (transport == null) environment()["FIELD_BROWSER_TEXTURE_NO_FRAMES"] = "1"
                framesPerSecond?.let { environment()["FIELD_BROWSER_TEXTURE_FRAME_RATE"] = it.toString() }
                environment().putAll(transport?.producerEnvironment ?: emptyMap())
                readyBoxUid?.takeIf { it.isNotBlank() }?.let {
                    environment()["FIELD_BROWSER_TEXTURE_READY_BOX_UID"] = it
                }
            }
            .start()

        Thread({
            process.inputStream.bufferedReader().useLines { lines ->
                lines.forEach { println("[field-browser-texture] $it") }
            }
        }, "field-browser-texture-output").apply {
            isDaemon = true
            start()
        }

        worker = Thread({ runControlLoop() }, "field-browser-texture-control").apply {
            isDaemon = true
            start()
        }
    }

    private fun runControlLoop() {
        try {
            server.accept().use { socket ->
                val out = PrintWriter(socket.getOutputStream(), true)
                writer.set(out)
                BufferedReader(InputStreamReader(socket.getInputStream())).useLines { lines ->
                    lines.takeWhile { !closed.get() }.forEach { line ->
                        if (line.isNotBlank()) handle(Json.parseToJsonElement(line).jsonObject)
                    }
                }
            }
        } catch (t: Throwable) {
            if (!closed.get()) System.err.println("[field-browser-texture] control failed: ${t.message}")
        } finally {
            writer.set(null)
        }
    }

    private fun handle(message: JsonObject) {
        when (message.string("type")) {
            "ready" -> {
                message.objectOrNull("state")?.let { stateListener(puppetBrowserState(it)) }
                ready.complete(Unit)
                println("[field-browser-texture] producer ready pid=${message.string("pid")}")
            }
            "loaded" -> {
                loadedAfterFrame.set(message.long("afterFrameId"))
                val loaded = message.objectOrNull("state")?.let(::puppetBrowserState)
                loaded?.let(stateListener)
                loadedListener(loaded ?: PuppetBrowserState(url = message.string("url")))
                println("[field-browser-texture] page loaded ${message.string("url")}")
            }
            "error" -> System.err.println("[field-browser-texture] ${message.string("message")}")
            "frame" -> offer(message)
            "response" -> receiveResponse(message)
            "event" -> receiveEvent(message)
            "page-request" -> pageRequest(
                message.string("id"),
                message.string("name"),
                message["value"] ?: JsonNull,
            )
        }
    }

    fun pageResponse(id: String, result: JsonElement?, error: Throwable?) {
        if (closed.get()) return
        send(buildJsonObject {
            put("type", "page-response")
            put("id", id)
            put("ok", error == null)
            if (error == null) put("result", result ?: JsonNull)
            else put("error", buildJsonObject {
                put("name", error::class.simpleName ?: "Error")
                put("message", error.message ?: error.toString())
            })
        })
    }

    private fun send(message: JsonObject) {
        val out = writer.get() ?: throw PuppetBrowserCommandException("Puppet browser control channel is unavailable")
        synchronized(out) {
            out.println(message.toString())
            out.flush()
            if (out.checkError()) throw PuppetBrowserCommandException("Puppet browser control channel write failed")
        }
    }

    private fun receiveResponse(message: JsonObject) {
        val id = message.string("id")
        val future = pending.remove(id) ?: return
        if (message.boolean("ok")) {
            future.complete(message.objectOrNull("result") ?: JsonObject(emptyMap()))
        } else {
            val error = message.objectOrNull("error")
            future.completeExceptionally(
                PuppetBrowserCommandException(
                    error?.stringOrNull("message") ?: "Puppet browser command failed",
                    details = error,
                )
            )
        }
    }

    private fun receiveEvent(message: JsonObject) {
        val event = PuppetBrowserEvent(
            sequence = message["sequence"]?.jsonPrimitive?.longOrNull ?: 0,
            name = message.string("name"),
            payload = message.objectOrNull("payload") ?: JsonObject(emptyMap()),
        )
        if (event.name == "state") {
            event.payload.objectOrNull("state")?.let { stateListener(puppetBrowserState(it)) }
        }
        eventListener(event)
    }

    private fun offer(message: JsonObject) {
        // The producer only announces frames when it was given somewhere to put them, so this is a
        // protocol violation rather than a mode: fail loudly instead of dropping a leased texture.
        val transport = transport ?: error("The producer announced a frame in no-frames mode: $message")
        val surface = surface ?: error("The producer announced a frame with no receiving surface")
        val token = message.long("token")
        val handle = transport.receive(message, token, 5_000)
        val colorSpace = message.colorSpace("colorSpace")
        val isSrgb = colorSpace?.transfer.equals("srgb", ignoreCase = true)
        val pixelFormat = when (message.string("pixelFormat")) {
            "bgra" -> if (isSrgb) BrowserSurfacePixelFormat.BGRA8_SRGB else BrowserSurfacePixelFormat.BGRA8_UNORM
            "rgba" -> if (isSrgb) BrowserSurfacePixelFormat.RGBA8_SRGB else BrowserSurfacePixelFormat.RGBA8_UNORM
            "rgbaf16" -> BrowserSurfacePixelFormat.RGBA16_FLOAT
            else -> error("Unsupported Electron browser texture format ${message.string("pixelFormat")}")
        }
        surface.offerFrame(
            ExternalBrowserFrame(
                streamId = message.long("streamId"),
                frameId = message.long("frameId"),
                releaseToken = token,
                slot = message.int("slot"),
                width = message.int("width"),
                height = message.int("height"),
                pixelFormat = pixelFormat,
                handle = handle,
                colorSpace = colorSpace,
                visibleRect = message.rect("visibleRect"),
                contentRect = message.rect("contentRect"),
                timestampMicros = message["timestamp"]?.jsonPrimitive?.longOrNull,
            )
        )
    }

private class LinuxDmaBufTransport(projectRoot: File) : BrowserHandleTransport {
    private val socket = "field4.browser-texture.${ProcessHandle.current().pid()}.${System.nanoTime()}"
    private val bridgeDir = File(projectRoot, "build/field-browser-bridge/linux")
    private val inbox = LinuxDmaBufInbox(File(bridgeDir, "libfield_browser_bridge.so"), socket)

    override val nodeBridge = File(bridgeDir, "field_browser_bridge.node")
    override val producerEnvironment = mapOf("FIELD_BROWSER_TEXTURE_DMABUF_SOCKET" to socket)

    override fun receive(message: JsonObject, token: Long, timeoutMs: Int): ExternalBrowserImageHandle {
        val received = inbox.receive(timeoutMs)
        if (received.token != token) {
            received.closeFds()
            error("dma-buf token ${received.token} did not match frame token $token")
        }
        return try {
            val planes = message["planes"]?.jsonArray
                ?: error("Linux browser frame carries no plane layout: $message")
            ExternalBrowserImageHandle.LinuxDmaBuf(
                planes = planes.map { element ->
                    val plane = element.jsonObject
                    val index = plane.int("fdIndex")
                    require(index in received.fds.indices) {
                        "plane names descriptor $index but only ${received.fds.size} arrived"
                    }
                    ExternalBrowserImageHandle.LinuxDmaBuf.Plane(
                        fd = received.fds[index],
                        stride = plane.int("stride"),
                        offset = plane.int("offset"),
                        size = plane.long("size"),
                    )
                },
                // Electron sends the modifier as a decimal string; DRM_FORMAT_MOD_INVALID and the
                // vendor-high-bit modifiers do not fit a signed parse.
                modifier = java.lang.Long.parseUnsignedLong(message.string("modifier")),
            )
        } catch (t: Throwable) {
            received.closeFds()
            throw t
        }
    }

    override fun close() = inbox.close()
}

private fun JsonObject.string(name: String): String =
    this[name]?.jsonPrimitive?.contentOrNull ?: error("Browser texture message has no '$name': $this")

private fun JsonObject.long(name: String): Long =
    this[name]?.jsonPrimitive?.longOrNull ?: string(name).toLong()

private fun JsonObject.int(name: String): Int =
    this[name]?.jsonPrimitive?.intOrNull ?: string(name).toInt()

private fun JsonObject.rect(name: String): BrowserSurfaceRect? =
    this[name]?.jsonObject?.let { BrowserSurfaceRect(it.int("x"), it.int("y"), it.int("width"), it.int("height")) }

private fun JsonObject.colorSpace(name: String): BrowserSurfaceColorSpace? =
    (this[name] as? JsonObject)?.let {
        BrowserSurfaceColorSpace(
            primaries = it.string("primaries"),
            transfer = it.string("transfer"),
            matrix = it.string("matrix"),
            range = it.string("range"),
        )
    }

    init {
        worker = Thread({ readFrames() }, "field-browser-texture-pixels").apply {
            isDaemon = true
            start()
        }
    }

    private fun readFrames() {
        try {
            server.accept().use { channel ->
                // The producer writes the header in network order; LWJGL hands back native-order
                // buffers, which is little-endian everywhere Field runs, so say so explicitly
                // rather than reading a byte-swapped magic and calling the channel desynchronised.
                val header = MemoryUtil.memAlloc(HEADER_BYTES).order(java.nio.ByteOrder.BIG_ENDIAN)
                try {
                    while (!closed.get()) {
                        header.clear()
                        if (!readFully(channel, header)) return
                        header.flip()
                        val magic = header.int
                        check(magic == MAGIC) { "browser pixel channel desynchronised (magic 0x${magic.toString(16)})" }
                        val streamId = header.long
                        val frameId = header.long
                        val slot = header.int
                        val width = header.int
                        val height = header.int
                        val stride = header.int
                        val length = header.int
                        header.int // reserved

                        require(length in 1..MAX_FRAME_BYTES) { "browser pixel frame claims $length bytes" }
                        // Read straight into the buffer the importer will memcpy from; the handle
                        // owns it from here and frees it on close, including when the mailbox
                        // conflates this frame away before it is ever imported.
                        val pixels = MemoryUtil.memAlloc(length)
                        if (!readFully(channel, pixels)) {
                            MemoryUtil.memFree(pixels)
                            return
                        }
                        pixels.flip()
                        surface.offerFrame(
                            ExternalBrowserFrame(
                                streamId = streamId,
                                frameId = frameId,
                                releaseToken = frameId,
                                slot = slot,
                                width = width,
                                height = height,
                                pixelFormat = spec.pixelFormat,
                                handle = ExternalBrowserImageHandle.CpuBitmap(pixels, stride),
                            )
                        )
                    }
                } finally {
                    MemoryUtil.memFree(header)
                }
            }
        } catch (t: Throwable) {
            if (!closed.get()) System.err.println("[field-browser-texture] pixel channel failed: ${t.message}")
        }
    }

    private fun readFully(channel: SocketChannel, into: java.nio.ByteBuffer): Boolean {
        while (into.hasRemaining()) {
            if (channel.read(into) < 0) return false
        }
        return true
    }

private class ReceivedDmaBuf(val token: Long, val fds: List<Int>) {
    fun closeFds() = fds.forEach { fd -> runCatching { ExternalBrowserFdClose.close(fd) } }
}

private class LinuxDmaBufInbox(libraryFile: File, socketName: String) : AutoCloseable {
    private val library: SharedLibrary
    private val receiveAddress: Long
    private val destroyAddress: Long
    private var receiver: Long

    init {
        require(libraryFile.isFile) {
            "Missing ${libraryFile.absolutePath}; run ./gradlew buildFieldBrowserBridge"
        }
        library = apiCreateLibrary(libraryFile.absolutePath)
        val openAddress = library.getFunctionAddress("field_browser_dmabuf_receiver_open")
        receiveAddress = library.getFunctionAddress("field_browser_dmabuf_receiver_receive")
        destroyAddress = library.getFunctionAddress("field_browser_dmabuf_receiver_destroy")
        require(openAddress != 0L && receiveAddress != 0L && destroyAddress != 0L) {
            "Native browser bridge is missing its dma-buf receiver exports"
        }
        MemoryStack.stackPush().use { stack ->
            receiver = JNI.callPP(MemoryUtil.memAddress(stack.UTF8(socketName)), openAddress)
        }
        require(receiver != 0L) { "Could not bind browser texture dma-buf socket @$socketName" }
    }

    fun receive(timeoutMs: Int): ReceivedDmaBuf {
        // token, descriptor count, then up to four descriptors.
        val output = MemoryUtil.memCalloc(8 * 8)
        try {
            val address = MemoryUtil.memAddress(output)
            val result = JNI.invokePPI(receiver, address, timeoutMs, receiveAddress)
            require(result == 0) { "dma-buf receive failed with code $result" }
            val count = MemoryUtil.memGetLong(address + 8).toInt()
            require(count in 1..4) { "dma-buf receive reported $count descriptors" }
            return ReceivedDmaBuf(
                token = MemoryUtil.memGetLong(address),
                fds = (0 until count).map { MemoryUtil.memGetLong(address + 16 + it * 8L).toInt() },
            )
        } finally {
            MemoryUtil.memFree(output)
        }
    }

    override fun close() {
        val value = receiver
        receiver = 0L
        if (value != 0L) JNI.callPV(value, destroyAddress)
        library.free()
    }
}