@pictor-sdk/video-android 0.1.0

package/android/src/main/java/dev/pictor/video/PictorVideoModule.kt

@@ -0,0 +1,1612 @@
+package dev.pictor.video
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReadableArray
+import com.facebook.react.bridge.WritableMap
+
+/**
+ * The JS boundary.
+ *
+ * One process-scoped player, because that is what the architecture is: Media3
+ * renders into a presentation surface that outlives any single source, and a
+ * map of handles would imply several players sharing one texture.
+ *
+ * Nothing native is reachable from a finalizer. Teardown is [media3Release] or
+ * [invalidate], both explicit and both on the player's own thread — collection
+ * running a finalizer on a thread of the runtime's choosing is exactly how the
+ * Skia video binding aborts the process.
+ *
+ * No call here is per frame. Frames reach the renderer through the
+ * `__pictorVideoSurface` host object on the UI runtime; these are controls and
+ * a throttled snapshot.
+ */
+class PictorVideoModule(reactContext: ReactApplicationContext) :
+    NativePictorVideoSpec(reactContext) {
+
+    override fun getName() = NAME
+
+    /**
+     * Install the JSI probe as a global on the React runtime.
+     *
+     * From there JS captures it in a worklet closure and Worklets carries the
+     * *same* C++ object into the UI runtime — `SerializableHostObject` holds
+     * the shared_ptr rather than copying. This is the supported route; the UI
+     * runtime pointer itself is not reachable, since `WorkletRuntimeRegistry`
+     * exposes only `isRuntimeAlive`.
+     */
+    /** Publishes `__pictorVideoSurface` for the UI runtime to drive. */
+    override fun installVideoSurface(): Boolean {
+        val pointer = reactApplicationContext.javaScriptContextHolder?.get() ?: return false
+        if (pointer == 0L) return false
+        return runCatching { nativeInstallVideoSurface(pointer) }.getOrDefault(false)
+    }
+
+    /**
+     * Publishes `__pictorOverlayStaging`, for writing export sidecars.
+     *
+     * The cache directory is handed over here and nowhere else: JS supplies
+     * bytes and dimensions, and native decides where they land. A destination
+     * that crossed the boundary would let a document string reach a path.
+     */
+    override fun installOverlayStaging(): Boolean {
+        val pointer = reactApplicationContext.javaScriptContextHolder?.get() ?: return false
+        if (pointer == 0L) return false
+        val cache = reactApplicationContext.cacheDir?.absolutePath ?: return false
+        return runCatching { nativeInstallOverlayStaging(pointer, cache) }.getOrDefault(false)
+    }
+
+    // ---- Media3 ----------------------------------------------------------
+    // Numbers and strings only. ExoPlayer, MediaItem and every other Media3
+    // type stops at this boundary.
+
+    private var media3: Media3Player? = null
+
+    override fun media3Prepare(uri: String): Boolean =
+        runCatching {
+            media3?.release()
+            media3 = Media3Player.create(reactApplicationContext, uri)
+            true
+        }.getOrElse {
+            lastMedia3Error = it.message ?: it.toString()
+            false
+        }
+
+    /** Heap attribution: a player with no video output at all. */
+    override fun media3PrepareNoSurface(uri: String): Boolean =
+        runCatching {
+            media3?.release()
+            media3 = Media3Player.create(reactApplicationContext, uri, attachSurface = false)
+            true
+        }.getOrElse { lastMedia3Error = it.message ?: it.toString(); false }
+
+    /** Heap attribution: reuse the process-scoped player for another source. */
+    override fun media3Rebind(uri: String): Boolean =
+        runCatching {
+            val player = media3 ?: return@runCatching false
+            player.rebind(uri)
+            true
+        }.getOrElse { lastMedia3Error = it.message ?: it.toString(); false }
+
+    /** Heap attribution: end the source but keep the player alive. */
+    override fun media3StopKeepingPlayer() { media3?.stopKeepingPlayer() }
+
+    /**
+     * Replace the playlist on the process-scoped player.
+     *
+     * Creates the player if there is not one yet, so a host can open a
+     * multi-clip project without a separate prepare step.
+     */
+    override fun media3SetPlaylist(
+        uris: ReadableArray,
+        bounds: ReadableArray,
+        startWindow: Double,
+        startPositionUs: Double,
+    ): Boolean =
+        runCatching {
+            val sources = ArrayList<String>(uris.size())
+            for (i in 0 until uris.size()) sources.add(uris.getString(i) ?: "")
+            val numbers = DoubleArray(bounds.size()) { bounds.getDouble(it) }
+            if (sources.isEmpty()) {
+                media3?.stopKeepingPlayer()
+                return@runCatching true
+            }
+            val player = media3 ?: Media3Player.create(
+                reactApplicationContext,
+                sources.first(),
+            ).also { media3 = it }
+            player.setPlaylist(sources, numbers, startWindow.toInt(), startPositionUs.toLong())
+            true
+        }.getOrElse {
+            // Logged as well as stored. A playlist that fails to load shows up
+            // as a black preview and nothing else, and "no output and no
+            // explanation" is the hardest kind of failure to chase.
+            lastMedia3Error = it.message ?: it.toString()
+            android.util.Log.e(NAME, "media3SetPlaylist failed: $lastMedia3Error", it)
+            false
+        }
+
+    /** Seek in the player's own coordinates: window index plus offset. */
+    override fun media3SeekToWindow(windowIndex: Double, positionUs: Double) {
+        media3?.seekToWindow(windowIndex.toInt(), positionUs.toLong())
+    }
+
+    // ---- V3.3 export gate -------------------------------------------------
+    // Experimental and deliberately unlike the rest: one URI in, a JSON report
+    // out. Not an exporter, not wired to VideoExporter, and not a shape anything
+    // should depend on.
+
+    private var gate: ExportGate? = null
+
+    /** One worker: the native module runs one export per process. */
+    private val exportExecutor = java.util.concurrent.Executors.newSingleThreadExecutor()
+
+    @androidx.media3.common.util.UnstableApi
+    override fun exportGateRun(uri: String, withSkia: Boolean, timeoutSeconds: Double): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        val running = gate ?: ExportGate(reactApplicationContext).also { gate = it }
+        val outcome = runCatching { running.run(uri, withSkia, timeoutSeconds.toLong()) }
+            .getOrElse {
+                return org.json.JSONObject()
+                    .put("ok", false)
+                    .put("error", "gate threw: ${'$'}{it.message}")
+                    .toString()
+            }
+        return report(outcome, running)
+    }
+
+    @androidx.media3.common.util.UnstableApi
+    private fun report(outcome: ExportGate.Outcome, running: ExportGate): String {
+        return org.json.JSONObject()
+            .put("ok", outcome.ok)
+            .put("uri", outcome.uri)
+            .put("error", outcome.error)
+            .put("elapsedMs", outcome.elapsedMs)
+            .put("fileBytes", outcome.fileBytes)
+            .put("durationMs", outcome.durationMs)
+            .put("width", outcome.width)
+            .put("height", outcome.height)
+            .put("videoFrameCount", outcome.videoFrameCount)
+            .put("hasAudio", outcome.hasAudio)
+            .put("videoMimeType", outcome.videoMimeType)
+            .put("audioMimeType", outcome.audioMimeType)
+            .put("colorInfo", outcome.colorInfo)
+            .put("glErrors", outcome.glErrors)
+            .put("effectFrames", outcome.effectFrames)
+            .put("effectTimestampsUs", outcome.effectTimestampsUs)
+            .put("boundary", outcome.boundary)
+            .put("nativeHeapBytes", outcome.nativeHeapBytes)
+            .put("javaHeapBytes", outcome.javaHeapBytes)
+            .put("callerThread", outcome.callerThread)
+            .put("refusals", running.refusalCount())
+            .put("started", running.startedCount())
+            .put("releases", running.releaseCount())
+            .put("completed", running.completedCount())
+            .put("failures", running.failureCount())
+            .put("lifecycle", outcome.lifecycle)
+            .put("programTrace", outcome.programTrace)
+            .put("muxTrace", outcome.muxTrace)
+            .put("overlayUploads", outcome.overlayUploads)
+            .put("overlayTexturesFreed", outcome.overlayTexturesFreed)
+            .toString()
+    }
+
+    @androidx.media3.common.util.UnstableApi
+    override fun exportGateRunScene(
+        uri: String,
+        sceneJson: String,
+        timeoutSeconds: Double,
+        failAfterFrames: Double,
+    ): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        val running = gate ?: ExportGate(reactApplicationContext).also { gate = it }
+        val outcome = runCatching {
+            running.runScene(uri, sceneJson, timeoutSeconds.toLong(), failAfterFrames.toInt())
+        }
+            .getOrElse {
+                return org.json.JSONObject()
+                    .put("ok", false)
+                    .put("error", "gate threw: ${'$'}{it.message}")
+                    .toString()
+            }
+        return report(outcome, running)
+    }
+
+    @androidx.media3.common.util.UnstableApi
+    override fun exportGateRunProgram(
+        uris: ReadableArray,
+        programJson: String,
+        timeoutSeconds: Double,
+    ): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        val running = gate ?: ExportGate(reactApplicationContext).also { gate = it }
+        val list = (0 until uris.size()).mapNotNull { uris.getString(it) }
+        val outcome = runCatching { running.runProgram(list, programJson, timeoutSeconds.toLong()) }
+            .getOrElse {
+                return org.json.JSONObject().put("ok", false)
+                    .put("error", "gate threw: " + it.message).toString()
+            }
+        return report(outcome, running)
+    }
+
+    @androidx.media3.common.util.UnstableApi
+    override fun exportGateReleaseTemporary(): Double {
+        // A sweep, not scoped cleanup: it takes temporaries a caller may still
+        // own. Production uses `exportReleaseTemporaryOutput`, which removes one
+        // path and refuses any it did not create. -1 is "not in this build",
+        // distinguishable from a sweep that found nothing.
+        if (!Diagnostics.ENABLED) return -1.0
+        return (gate?.releaseTemporary() ?: 0).toDouble()
+    }
+
+    @androidx.media3.common.util.UnstableApi
+    override fun exportGateRunItems(
+        itemsJson: String,
+        programJson: String,
+        timeoutSeconds: Double,
+    ): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        val running = gate ?: ExportGate(reactApplicationContext).also { gate = it }
+        val parsed = try {
+            val array = org.json.JSONArray(itemsJson)
+            (0 until array.length()).map {
+                val o = array.getJSONObject(it)
+                ExportGate.Item(
+                    o.getString("uri"),
+                    o.optLong("startMs", 0),
+                    o.optLong("endMs", 0),
+                    o.optDouble("speed", 1.0).toFloat(),
+                    o.optBoolean("removeAudio", false),
+                    o.optString("speedMode", "preserve"),
+                    o.optLong("durationUs", 0),
+                )
+            }
+        } catch (e: Exception) {
+            return org.json.JSONObject().put("ok", false)
+                .put("error", "items: " + e.message).toString()
+        }
+        // Sequence-level, not per item: reading it off the first entry alone
+        // would silently ignore it anywhere else in the list.
+        val force = try {
+            val array = org.json.JSONArray(itemsJson)
+            (0 until array.length()).any { array.optJSONObject(it)?.optBoolean("forceAudioTrack", false) == true }
+        } catch (e: Exception) {
+            false
+        }
+        val outcome = runCatching { running.runItems(parsed, programJson, timeoutSeconds.toLong(), force) }
+            .getOrElse {
+                return org.json.JSONObject().put("ok", false)
+                    .put("error", "gate threw: " + it.message).toString()
+            }
+        return report(outcome, running)
+    }
+
+    @androidx.media3.common.util.UnstableApi
+    override fun exportGateRunShards(
+        shardsJson: String,
+        programJson: String,
+        timeoutSeconds: Double,
+        overlaysJson: String,
+    ): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        val running = gate ?: ExportGate(reactApplicationContext).also { gate = it }
+        val parsed = try {
+            val array = org.json.JSONArray(shardsJson)
+            (0 until array.length()).map {
+                val o = array.getJSONObject(it)
+                ExportGate.Shard(
+                    o.getString("uri"),
+                    o.optLong("startMs", 0),
+                    o.optLong("endMs", 0),
+                    o.optDouble("speed", 1.0).toFloat(),
+                    o.optLong("timelineOffsetUs", 0),
+                    o.optBoolean("forceAudioTrack", false),
+                    o.optInt("frameDropFps", 0),
+                    o.optLong("encoderRepeatUs", 0),
+                    o.optJSONArray("emitsPerInput")?.let { a ->
+                        IntArray(a.length()) { i -> a.getInt(i) }
+                    },
+                    o.optJSONArray("outputPtsUs")?.let { a ->
+                        LongArray(a.length()) { i -> a.getLong(i) }
+                    },
+                    o.optInt("cadenceFailAfterEmits", -1),
+                    o.optLong("spanUs", 0),
+                    o.optBoolean("removeAudio", false),
+                    o.optString("speedMode", "preserve"),
+                    o.optInt("overlayFailAfterDraws", -1),
+                    o.optBoolean("failConcat", false),
+                    o.optInt("cadenceStallAfterEmits", -1),
+                )
+            }
+        } catch (e: Exception) {
+            return org.json.JSONObject().put("ok", false)
+                .put("error", "shards: " + e.message).toString()
+        }
+        val outcome = runCatching {
+            running.runShards(parsed, programJson, timeoutSeconds.toLong(), overlaysJson)
+        }
+            .getOrElse {
+                return org.json.JSONObject().put("ok", false)
+                    .put("error", "gate threw: " + it.message).toString()
+            }
+        return report(outcome, running)
+    }
+
+    override fun exportGateSampleHashes(uri: String): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        return GateFrames.sampleHashes(reactApplicationContext, uri)
+    }
+
+    @androidx.media3.common.util.UnstableApi
+    override fun exportGateEncodeStill(pngBase64: String, frames: Double): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        val running = gate ?: ExportGate(reactApplicationContext).also { gate = it }
+        val bytes = try {
+            android.util.Base64.decode(pngBase64, android.util.Base64.DEFAULT)
+        } catch (e: Exception) {
+            return org.json.JSONObject().put("ok", false).put("error", "base64: " + e.message).toString()
+        }
+        val outcome = runCatching { running.runStill(bytes, frames.toInt()) }
+            .getOrElse {
+                return org.json.JSONObject().put("ok", false)
+                    .put("error", "gate threw: " + it.message).toString()
+            }
+        return report(outcome, running)
+    }
+
+    override fun exportGateGeometry(
+        leftUri: String,
+        leftUs: Double,
+        rightUri: String,
+        rightUs: Double,
+        maskThreshold: Double,
+    ): String = GateFrames.geometry(
+        reactApplicationContext, leftUri, leftUs.toLong(), rightUri, rightUs.toLong(), maskThreshold.toInt(),
+    )
+
+    override fun exportGateFramePng(uri: String, timeUs: Double): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        return GateFrames.framePng(reactApplicationContext, uri, timeUs.toLong())
+    }
+
+    /**
+     * Run an export off the bridge, so it can be cancelled while it runs.
+     *
+     * A blocking export holds the JS thread for the whole encode, which makes
+     * cancellation impossible by construction — the message asking it to stop
+     * cannot be delivered until the thing it would stop has finished. So the
+     * work moves to a worker and the result arrives on a promise.
+     */
+    @androidx.media3.common.util.UnstableApi
+    override fun exportRunProjectAsync(
+        jobId: String,
+        shardsJson: String,
+        programJson: String,
+        overlaysJson: String,
+        mixProgramJson: String,
+        mixUrisJson: String,
+        timeoutSeconds: Double,
+        destinationJson: String,
+        promise: com.facebook.react.bridge.Promise,
+    ) {
+        val running = gate ?: ExportGate(reactApplicationContext).also { gate = it }
+        if (!running.beginJob(jobId)) {
+            promise.resolve(
+                org.json.JSONObject().put("ok", false)
+                    .put("error", "an export is already running").toString(),
+            )
+            return
+        }
+        exportExecutor.execute {
+            val outcome = try {
+                runProjectInternal(
+                    shardsJson, programJson, overlaysJson, mixProgramJson, mixUrisJson, timeoutSeconds,
+                    destinationJson,
+                )
+            } catch (e: Throwable) {
+                org.json.JSONObject().put("ok", false)
+                    .put("error", e.javaClass.simpleName + ": " + e.message).toString()
+            } finally {
+                running.endJob()
+            }
+            promise.resolve(outcome)
+        }
+    }
+
+    /** Counted work plus the beat total, read by the JavaScript progress pump. */
+    @androidx.media3.common.util.UnstableApi
+    override fun exportProgressSnapshot(): String =
+        gate?.progressSnapshotJson()
+            ?: org.json.JSONObject()
+                .put("shards", org.json.JSONArray())
+                .put("audioSamples", 0)
+                .put("audioPlanned", 0)
+                .put("muxed", false)
+                .put("beats", 0)
+                .toString()
+
+    /**
+     * Prove the destination opens before anyone is told the export is done.
+     *
+     * Progress reaching 1 over a file that cannot be read is a worse lie than a
+     * bar that sits at 97 for a moment, and the encoder finishing is not the
+     * same event as the container being closed and parseable.
+     */
+    /**
+     * What a picked audio file contains, before it may enter a project.
+     *
+     * See [AudioProbe]: the mix compiler has no decoder and takes the
+     * document's word for whether a source has audio, so this is the only
+     * thing that can establish it.
+     */
+    /**
+     * Prepare the audio a preview plays, off the JS thread.
+     *
+     * The same mixer an export runs, over the same compiled program — see
+     * [PreviewMix]. Asynchronous because it decodes, re-times and encodes every
+     * contributing source: this is preparation, not playback.
+     */
+    override fun previewMixPrepare(
+        jobId: String,
+        programJson: String,
+        urisJson: String,
+        promise: com.facebook.react.bridge.Promise,
+    ) {
+        PreviewMix.submit {
+            val outcome = try {
+                PreviewMix.prepare(reactApplicationContext, jobId, programJson, urisJson)
+            } catch (e: Throwable) {
+                org.json.JSONObject().put("ok", false)
+                    .put("error", e.javaClass.simpleName + ": " + e.message).toString()
+            }
+            promise.resolve(outcome)
+        }
+    }
+
+    /**
+     * Gate-only: prepare a preview mix whose only source is the marker fixture,
+     * then decode the result and report where the markers actually landed.
+     *
+     * The end-to-end alignment question. The encoder baseline proves the encoder
+     * is unchanged; this proves the file a player is handed puts the sound where
+     * the timeline says it is.
+     */
+    override fun previewAlignmentGate(startUs: Double): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        return try {
+            val dir = reactApplicationContext.cacheDir
+            // WAV, not AAC: an uncompressed source has no priming of its own,
+            // so the only delay left to measure is the one under test.
+            val source = java.io.File(dir, "pictor-align-source.wav")
+            val written = EncoderGate.writeWavFixture(reactApplicationContext, "markers", source)
+            if (!written.optBoolean("ok", false)) return written.toString()
+
+            val durationUs = written.getLong("durationUs")
+            val start = startUs.toLong()
+            val spanId = "align"
+            val program = org.json.JSONObject()
+                .put("version", 1)
+                .put("rule", "sum-then-saturate")
+                .put("durationUs", start + durationUs)
+                .put(
+                    "spans",
+                    org.json.JSONArray().put(
+                        org.json.JSONObject()
+                            .put("id", spanId)
+                            .put("startUs", start)
+                            .put("endUs", start + durationUs)
+                            .put("sourceInUs", 0)
+                            .put("sourceOutUs", durationUs)
+                            .put("speed", 1.0)
+                            .put("gain", 1.0)
+                            .put("silent", false)
+                            .put("ramps", org.json.JSONArray()),
+                    ),
+                )
+            val uris = org.json.JSONObject().put(spanId, written.getString("uri"))
+
+            val raw = java.io.File(dir, "pictor-align-raw.m4a")
+            val result = org.json.JSONObject(
+                AudioMixer.mix(reactApplicationContext, program.toString(), uris.toString(), raw),
+            )
+            if (!result.optBoolean("ok", false)) return result.toString()
+
+            /*
+              Through the correction, because that is what preview publishes.
+
+              The first version of this gate measured `raw` and reported the
+              mix's priming as still present — which was true of that file and
+              false of the one a player is given. A gate that measures a
+              different artifact from the product is worse than no gate: it
+              reported a defect that had already been fixed.
+            */
+            val mix = java.io.File(dir, "pictor-align-mix.m4a")
+            val trimmed = org.json.JSONObject(
+                PrimingTrim.shiftAudioFile(reactApplicationContext, raw, mix).toString(),
+            )
+            runCatching { raw.delete() }
+            if (!trimmed.optBoolean("ok", false)) return trimmed.toString()
+
+            // Expected timeline positions: the source markers, shifted by where
+            // the span was placed.
+            val expected = org.json.JSONArray()
+            val markers = written.getJSONArray("markersMs")
+            for (i in 0 until markers.length()) {
+                expected.put(markers.getInt(i) + (start / 1000).toInt())
+            }
+            EncoderGate.alignment(reactApplicationContext, mix, expected)
+                .put("startUs", start)
+                .put("sourceDurationUs", durationUs)
+                .put("priming", trimmed)
+                .toString()
+        } catch (e: Throwable) {
+            org.json.JSONObject().put("ok", false)
+                .put("error", e.javaClass.simpleName + ": " + e.message).toString()
+        }
+    }
+
+    /**
+     * Gate-only: the objective Music gates that can be measured from files.
+     *
+     * Preview and export mix from the same program through the same code, so
+     * equality is checked by decoding both and comparing samples — not by
+     * trusting that they share a function. Source formats are exercised at a
+     * zero and a non-zero trim, because a decoder's behaviour at the head of a
+     * file is not its behaviour after a seek.
+     */
+    override fun musicGates(): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        val results = org.json.JSONArray()
+        val dir = reactApplicationContext.cacheDir
+        val wav = java.io.File(dir, "pictor-g-src.wav")
+        val aac = java.io.File(dir, "pictor-g-src.m4a")
+        return try {
+            val w = EncoderGate.writeWavFixture(reactApplicationContext, "markers", wav)
+            val a = EncoderGate.writeFixture(reactApplicationContext, "markers", aac)
+            if (!w.optBoolean("ok", false) || !a.optBoolean("ok", false)) {
+                return org.json.JSONObject().put("ok", false).put("error", "fixtures").toString()
+            }
+            val durationUs = w.getLong("durationUs")
+
+            fun programFor(uri: String, sourceInUs: Long, endUs: Long): Pair<String, String> {
+                val span = org.json.JSONObject()
+                    .put("id", "g").put("startUs", 0).put("endUs", endUs - sourceInUs)
+                    .put("sourceInUs", sourceInUs).put("sourceOutUs", endUs)
+                    .put("speed", 1.0).put("gain", 1.0).put("silent", false)
+                    .put("ramps", org.json.JSONArray())
+                val program = org.json.JSONObject()
+                    .put("version", 1).put("rule", "sum-then-saturate")
+                    .put("durationUs", endUs - sourceInUs)
+                    .put("spans", org.json.JSONArray().put(span))
+                return program.toString() to org.json.JSONObject().put("g", uri).toString()
+            }
+
+            /** Mix, publish through the shared correction, decode. */
+            fun publishAndDecode(programJson: String, urisJson: String, tag: String): org.json.JSONObject {
+                val raw = java.io.File(dir, "pictor-g-$tag-raw.m4a")
+                val pub = java.io.File(dir, "pictor-g-$tag.m4a")
+                val mixed = org.json.JSONObject(
+                    AudioMixer.mix(reactApplicationContext, programJson, urisJson, raw),
+                )
+                if (!mixed.optBoolean("ok", false)) {
+                    return org.json.JSONObject().put("ok", false).put("error", mixed.optString("error"))
+                }
+                val endUs = org.json.JSONObject(programJson).optLong("durationUs", 0)
+                val shifted = PrimingTrim.shiftAudioFile(reactApplicationContext, raw, pub, endUs)
+                runCatching { raw.delete() }
+                if (!shifted.optBoolean("ok", false)) {
+                    return org.json.JSONObject().put("ok", false).put("error", shifted.optString("error"))
+                }
+                val pcm = EncoderGate.decodeFile(pub)
+                val out = EncoderGate.describeStage(tag, pcm)
+                    .put("container", PrimingTrim.inspect(pub))
+                    .put("tailUnitsDropped", shifted.optInt("tailUnitsDropped"))
+                    .put("expectedFrames", endUs * AudioMixer.SAMPLE_RATE / 1_000_000L)
+                    .put("fileBytes", pub.length())
+                runCatching { pub.delete() }
+                return out.put("ok", true)
+            }
+
+            // Tail and duration, now that the compiled end reaches publication.
+            val (p0, u0) = programFor(w.getString("uri"), 0, durationUs)
+            results.put(publishAndDecode(p0, u0, "wav-from-zero"))
+
+            // The same program twice: preview and export mix identically, so
+            // decoding both must give the same samples.
+            val first = publishAndDecode(p0, u0, "equality-a")
+            val second = publishAndDecode(p0, u0, "equality-b")
+            results.put(
+                org.json.JSONObject()
+                    .put("stage", "preview-export-equality")
+                    .put("framesEqual", first.optInt("frames") == second.optInt("frames"))
+                    .put("rmsEqual", first.optDouble("rms") == second.optDouble("rms"))
+                    .put("markersEqual", first.optJSONArray("markersMs").toString() == second.optJSONArray("markersMs").toString())
+                    .put("headEqual", first.optDouble("peakFirst60ms") == second.optDouble("peakFirst60ms"))
+                    .put("bytesEqual", first.optLong("fileBytes") == second.optLong("fileBytes")),
+            )
+
+            // AAC source, from zero and after a non-zero trim.
+            val (p1, u1) = programFor(a.getString("uri"), 0, durationUs)
+            results.put(publishAndDecode(p1, u1, "aac-from-zero"))
+            val (p2, u2) = programFor(a.getString("uri"), 2_000_000, durationUs)
+            results.put(publishAndDecode(p2, u2, "aac-from-2s"))
+
+            // MP3 source, likewise — the format whose declared delay once made
+            // the head check stricter than declaring nothing.
+            val mp3 = "android.resource://dev.pictor.example/raw/music_b"
+            val (p3, u3) = programFor(mp3, 0, 6_000_000)
+            results.put(publishAndDecode(p3, u3, "mp3-from-zero"))
+            val (p4, u4) = programFor(mp3, 2_000_000, 6_000_000)
+            results.put(publishAndDecode(p4, u4, "mp3-from-2s"))
+
+            org.json.JSONObject().put("ok", true).put("gates", results).toString()
+        } catch (e: Throwable) {
+            org.json.JSONObject().put("ok", false)
+                .put("error", e.javaClass.simpleName + ": " + e.message).toString()
+        } finally {
+            runCatching { wav.delete() }
+            runCatching { aac.delete() }
+        }
+    }
+
+    /**
+     * Gate-only: where the samples go, stage by stage.
+     *
+     * One deterministic WAV source with a marker at sample zero, carried
+     * through mixing, encoding, decoding and both candidate corrections. Each
+     * stage is measured the same way, so "the marker moved" and "the marker
+     * went" can finally be told apart.
+     */
+    override fun primingAttribution(): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        val out = org.json.JSONArray()
+        val dir = reactApplicationContext.cacheDir
+        val source = java.io.File(dir, "pictor-attr-source.wav")
+        val raw = java.io.File(dir, "pictor-attr-raw.m4a")
+        val published = java.io.File(dir, "pictor-attr-published.m4a")
+        return try {
+            val written = EncoderGate.writeWavFixture(reactApplicationContext, "markers", source)
+            if (!written.optBoolean("ok", false)) return written.toString()
+            val durationUs = written.getLong("durationUs")
+
+            // 1. The source, before anything touches it.
+            out.put(EncoderGate.describeStage("1-source-pcm", EncoderGate.pcmFor("markers")))
+
+            val spanId = "attr"
+            val program = org.json.JSONObject()
+                .put("version", 1).put("rule", "sum-then-saturate").put("durationUs", durationUs)
+                .put(
+                    "spans",
+                    org.json.JSONArray().put(
+                        org.json.JSONObject()
+                            .put("id", spanId).put("startUs", 0).put("endUs", durationUs)
+                            .put("sourceInUs", 0).put("sourceOutUs", durationUs)
+                            .put("speed", 1.0).put("gain", 1.0).put("silent", false)
+                            .put("ramps", org.json.JSONArray()),
+                    ),
+                )
+            val uris = org.json.JSONObject().put(spanId, written.getString("uri"))
+            val mixed = org.json.JSONObject(
+                AudioMixer.mix(reactApplicationContext, program.toString(), uris.toString(), raw),
+            )
+            if (!mixed.optBoolean("ok", false)) return mixed.toString()
+
+            // 2. What the encoder was handed, de-click envelope included.
+            AudioMixer.lastMixedPcm?.let {
+                out.put(EncoderGate.describeStage("2-mixed-pcm-before-encode", it))
+            }
+
+            // 3. The encoded file, decoded from its very beginning.
+            val fullDecode = EncoderGate.decodeFile(raw)
+            out.put(EncoderGate.describeStage("3-encoded-decoded-full", fullDecode))
+
+            // 4. The same decode with exactly the measured priming removed, in
+            //    memory. Sample-exact, and it never loses overlap context
+            //    because the decoder saw every access unit.
+            val priming = PrimingTrim.measureFor(reactApplicationContext, raw.absolutePath)
+            val drop = minOf(fullDecode.size, priming * AudioMixer.CHANNELS)
+            val sampleExact = fullDecode.copyOfRange(drop, fullDecode.size)
+            out.put(
+                EncoderGate.describeStage("4-decoded-minus-measured-priming", sampleExact)
+                    .put("primingFramesRemoved", priming),
+            )
+
+            // 5. What is published: every unit kept, the start moved instead.
+            val shiftedFile = java.io.File(dir, "pictor-attr-shifted.m4a")
+            val shifted = PrimingTrim.shiftAudioFile(reactApplicationContext, raw, shiftedFile)
+            if (shifted.optBoolean("ok", false)) {
+                out.put(
+                    EncoderGate.describeStage("5-published-timestamp-shifted", EncoderGate.decodeFile(shiftedFile))
+                        .put("negativePtsUnits", shifted.optInt("negativePtsUnits"))
+                        .put("firstPtsUs", shifted.optLong("firstPtsUs"))
+                        .put("container", PrimingTrim.inspect(shiftedFile)),
+                )
+            } else {
+                out.put(org.json.JSONObject().put("stage", "5-published-timestamp-shifted").put("failed", shifted))
+            }
+            runCatching { shiftedFile.delete() }
+
+            org.json.JSONObject()
+                .put("ok", true)
+                .put("expectedMarkersMs", EncoderGate.expectedMarkersMs())
+                .put("measuredPrimingFrames", priming)
+                .put("stages", out)
+                .toString()
+        } catch (e: Throwable) {
+            org.json.JSONObject().put("ok", false)
+                .put("error", e.javaClass.simpleName + ": " + e.message).toString()
+        } finally {
+            runCatching { source.delete() }
+            runCatching { raw.delete() }
+            runCatching { published.delete() }
+        }
+    }
+
+    /** Gate-only: encode a fixed PCM fixture and describe the result completely. */
+    override fun encoderGateRun(fixture: String, maxInputSize: Double): String =
+        EncoderGate.run(reactApplicationContext, fixture, maxInputSize.toInt()).toString()
+
+    override fun previewMixCancel(): String = PreviewMix.cancel()
+
+    /**
+     * Every codec mix preparation owns, and what became of it.
+     *
+     * Read-only accounting. The preview video decoder is deliberately absent:
+     * it belongs to the player and lives as long as the screen, so counting it
+     * would make "live after publication" always true.
+     */
+    override fun previewCodecLedger(): String =
+        CodecLedger.snapshot()
+            // What a bounds gate actually asks: not just codecs, but how many
+            // second players and preparation jobs a run left behind.
+            .put("players", PreviewAudioPlayer.instanceCounters())
+            .put("jobs", PreviewMix.jobCounters())
+            .toString()
+
+
+    /** Gate-only: which parts of the music preview exist. @see PreviewConfig */
+    override fun previewConfigSet(json: String): String = PreviewConfig.apply(json).toString()
+
+    /** What the configuration currently is. Read-only. */
+    override fun previewConfigGet(): String = PreviewConfig.current().put("ok", true).toString()
+
+
+    /**
+     * How many frames the pipeline has offered, queued and drawn.
+     *
+     * Read-only accounting, so it stays available in release for the same
+     * reason the ledgers do — and specifically so that "is the instrument
+     * disturbing the picture?" can be asked *without* the instrument. Volatile
+     * reads only: the counters that needed the frame lock were what froze the
+     * renderer when sampled at 40 Hz.
+     */
+    override fun spikeStart(specJson: String): String =
+        CompositionSpike.start(reactApplicationContext, specJson)
+
+    override fun spikePlay(): String = CompositionSpike.play()
+
+    override fun spikePause(): String = CompositionSpike.pause()
+
+    override fun spikeSeek(positionUs: Double): String =
+        CompositionSpike.seek(positionUs.toLong())
+
+    override fun spikeClaim(): String = CompositionSpike.claim()
+
+    override fun spikeState(): String = CompositionSpike.state()
+
+    override fun spikeDrain(fromSeq: Double, limit: Double): String =
+        CompositionSpike.drain(fromSeq.toLong(), limit.toInt())
+
+    override fun spikeRelease(): String = CompositionSpike.release()
+
+    override fun previewFramePipeline(): String {
+        val c = FrameClock.pipeline()
+        val d = VideoSurface.delivery()
+        return org.json.JSONObject()
+            .put("ok", true)
+            .put("offered", c[0])
+            .put("available", c[1])
+            .put("taken", c[2])
+            .put("orphaned", c[3])
+            .put("unpaired", c[4])
+            .put("stale", c[5])
+            .put("coalesced", c[6])
+            .put("generation", c[7])
+            // Entries to `take`, counted before the lock: a consumer that has
+            // stopped ticking and one blocked inside the latch are otherwise
+            // identical from the outside.
+            .put("takeCalls", c[8])
+            // Identity, separated from timing: a mislabelled frame and a late
+            // one produce the same offset and need opposite fixes.
+            .put("mismatched", FrameClock.mismatched)
+            .put("unverified", FrameClock.unverified)
+            // Why frames stopped arriving, when they have. A cleared listener,
+            // a quit delivery thread and a silent producer all look the same in
+            // `available` alone.
+            .put("watches", d[0])
+            .put("releases", d[1])
+            .put("threadQuits", d[2])
+            .put("deliveryAlive", d[3] == 1L)
+            .put("releaseLeadMs", FrameClock.lastReleaseLeadNs / 1_000_000)
+            .put("lastOfferedPtsMs", FrameClock.lastOfferedPtsUs / 1000)
+            .put("farFutureOffers", FrameClock.farFutureOffers)
+            .put("farPastOffers", FrameClock.farPastOffers)
+            .put("overflowed", FrameClock.overflowed)
+            .put("depth", FrameClock.depth())
+            .put("announced", d[4])
+            .put("rejectedAnnouncements", d[5])
+            .put("pendingDepth", d[6])
+            .put("updatesAttempted", d[7])
+            .put("updatesSucceeded", d[8])
+            .put("updatesFailed", d[9])
+            .put("updatesSkipped", d[10])
+            .toString()
+    }
+
+
+    /**
+     * The host is stopping playback for a reason of its own.
+     *
+     * Backgrounding, a picker taking the foreground, an unmount. Any of them
+     * must override a resume the coordinator is holding, or playback would
+     * start again at a moment nobody asked for.
+     */
+    override fun previewSyncStop(reason: String): String {
+        PreviewSync.onUserStop(reason)
+        PreviewAudioPlayer.current()?.pause()
+        return PreviewSync.counters().put("ok", true).toString()
+    }
+
+    /** What the coordinator has done, for assertions. */
+    override fun previewSyncCounters(): String =
+        PreviewSync.counters().put("ok", true).toString()
+
+
+    /**
+     * Compare the players and correct the mix past a tolerance.
+     *
+     * Native because both anchors are published on one clock here; asking from
+     * JavaScript would put a bridge hop inside the measurement.
+     */
+    override fun previewDriftCheck(toleranceUs: Double): String =
+        PreviewTrace.driftCheck(toleranceUs.toLong()).toString()
+
+
+    /**
+     * Gate-only: arm the paired trace and start sampling both players.
+     *
+     * Off by default even in a diagnostics build — sampling two players every
+     * few milliseconds is work a preview should not be doing for anyone who is
+     * not measuring it.
+     */
+    override fun previewTraceArm(on: Boolean, intervalMs: Double): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        PreviewTrace.arm(on)
+        if (on) PreviewTrace.startSampling(intervalMs.toLong()) else PreviewTrace.stopSampling()
+        return org.json.JSONObject().put("ok", true).put("armed", on).toString()
+    }
+
+    /** Gate-only: a label the harness can find its own cases by. */
+    override fun previewTraceMark(label: String): String {
+        PreviewTrace.record("mark") { org.json.JSONObject().put("label", label) }
+        return org.json.JSONObject().put("ok", true).toString()
+    }
+
+    /**
+     * Gate-only: drain events from a sequence number.
+     *
+     * Chunked by `limit` because a whole trace is far past what a single log
+     * line survives, and the caller pages rather than truncating.
+     */
+    override fun previewTraceDrain(fromSeq: Double, limit: Double): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        return PreviewTrace.drain(fromSeq.toLong(), limit.toInt()).toString()
+    }
+
+
+    /**
+     * The mixed-audio player.
+     *
+     * A second, deliberately small player: one item, no surface, no playlist.
+     * Its position is the global timeline position, because the mix already
+     * covers the whole timeline with every clip speed compiled in.
+     */
+    override fun previewAudioLoad(uri: String, epoch: Double): String {
+        // The bisect configuration that prepares a mix but creates no player
+        // stops here: `require` is what brings the second ExoPlayer into
+        // existence.
+        if (!PreviewConfig.loadPlayer) {
+            return org.json.JSONObject().put("ok", true).put("skipped", "loadPlayer").toString()
+        }
+        PreviewAudioPlayer.require(reactApplicationContext).load(uri, epoch.toLong())
+        return org.json.JSONObject().put("ok", true).toString()
+    }
+
+    override fun previewAudioPlay(epoch: Double): String {
+        PreviewAudioPlayer.current()?.play(epoch.toLong())
+        return org.json.JSONObject().put("ok", true).toString()
+    }
+
+    override fun previewAudioPause(): String {
+        PreviewAudioPlayer.current()?.pause()
+        return org.json.JSONObject().put("ok", true).toString()
+    }
+
+    override fun previewAudioSeek(positionUs: Double, epoch: Double): String {
+        PreviewAudioPlayer.current()?.seekTo(positionUs.toLong(), epoch.toLong())
+        return org.json.JSONObject().put("ok", true).toString()
+    }
+
+    override fun previewAudioSetRate(rate: Double): String {
+        PreviewAudioPlayer.current()?.setRate(rate.toFloat())
+        return org.json.JSONObject().put("ok", true).toString()
+    }
+
+    override fun previewAudioState(): String =
+        PreviewAudioPlayer.current()?.state()
+            ?: org.json.JSONObject().put("ok", false).put("error", "no player").toString()
+
+    /**
+     * Silence the video player's own audio while a mixed preview plays.
+     *
+     * The mix already contains the clips' audio, so both being audible plays
+     * the timeline twice.
+     */
+    override fun previewMuteSourceAudio(muted: Boolean): String {
+        media3?.setSourceAudioMuted(muted)
+        return org.json.JSONObject().put("ok", true).toString()
+    }
+
+    override fun previewAudioRelease(): String {
+        PreviewAudioPlayer.releaseAll()
+        return org.json.JSONObject().put("ok", true).toString()
+    }
+
+
+    override fun previewMixKey(programJson: String, urisJson: String): String =
+        PreviewMix.keyFor(programJson, urisJson)
+
+    override fun previewMixRelease(key: String): String =
+        PreviewMix.release(reactApplicationContext, key)
+
+    override fun previewMixSweep(keepKeysJson: String): String =
+        try {
+            PreviewMix.sweep(reactApplicationContext, org.json.JSONArray(keepKeysJson))
+        } catch (e: Exception) {
+            // An unreadable keep list must never be read as "keep nothing".
+            org.json.JSONObject().put("ok", false).put("error", "unparseable keep list").toString()
+        }
+
+    override fun previewMixLedger(): String = PreviewMix.ledger(reactApplicationContext)
+
+    /** Copy a picked source into durable, app-owned storage. @see ManagedSources */
+    override fun ingestManagedSource(uri: String): String =
+        ManagedSources.ingest(reactApplicationContext, uri).toString()
+
+    override fun releaseManagedSource(token: String): String =
+        org.json.JSONObject()
+            .put("ok", true)
+            .put("removed", ManagedSources.release(reactApplicationContext, token))
+            .toString()
+
+    override fun sweepManagedSources(keepTokensJson: String): String =
+        try {
+            ManagedSources.sweep(reactApplicationContext, org.json.JSONArray(keepTokensJson)).toString()
+        } catch (e: Exception) {
+            // An unparseable keep list must never be read as "keep nothing".
+            org.json.JSONObject().put("ok", false).put("reason", "unparseable keep list").toString()
+        }
+
+    override fun managedSourceList(): String =
+        ManagedSources.list(reactApplicationContext).toString()
+
+    /** Gate-only: sweep with an unparsed keep list, to prove refusal deletes nothing. */
+    override fun managedSourceGateSweepRaw(rawKeep: String): String =
+        ManagedSources.gateSweepRaw(reactApplicationContext, rawKeep).toString()
+
+    /** Gate-only: seed a file so the sweep's enumeration can be exercised. */
+    override fun managedSourceGateSeed(name: String, bytes: Double): String =
+        ManagedSources.gateSeed(reactApplicationContext, name, bytes.toInt()).toString()
+
+    override fun managedSourceLedger(): String =
+        ManagedSources.ledger(reactApplicationContext).toString()
+
+    override fun probeAudioSource(uri: String): String =
+        AudioProbe.probe(reactApplicationContext, uri).toString()
+
+    @androidx.media3.common.util.UnstableApi
+    override fun exportProbeOutput(uri: String): String =
+        GateDestination.probe(uri).toString()
+
+    /** Gate-only: hold inside the media copy, so a kill can land there. */
+    @androidx.media3.common.util.UnstableApi
+    override fun exportGateHoldMediaCopy(enabled: Boolean): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        MediaStoreSave.holdInCopy = enabled
+        return org.json.JSONObject().put("ok", true).put("hold", enabled).toString()
+    }
+
+    /** Gate-only: wedge the cadence program after N frames. -1 is off. */
+    @androidx.media3.common.util.UnstableApi
+    override fun exportGateStallAfterFrames(frames: Double): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        val running = gate ?: ExportGate(reactApplicationContext).also { gate = it }
+        if (!running.diagnostics) {
+            return org.json.JSONObject().put("ok", false)
+                .put("error", "diagnostics are not enabled").toString()
+        }
+        running.stallAfterFrames = frames.toInt()
+        return org.json.JSONObject().put("ok", true).put("stallAfterFrames", frames.toInt()).toString()
+    }
+
+    /**
+     * Arm the gate-only controls.
+     *
+     * Every fault control, hold, provenance hash and test beat is inert until
+     * this is called, including the ones a shard descriptor asks for. The
+     * production exporter never calls it, so a shipped build cannot be talked
+     * into injecting a failure by a malformed payload.
+     *
+     * Not reversible by accident either — passing `false` disarms and clears
+     * every control, so a conformance run cannot leave one set.
+     */
+    @androidx.media3.common.util.UnstableApi
+    override fun exportGateEnableDiagnostics(enabled: Boolean): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        val running = gate ?: ExportGate(reactApplicationContext).also { gate = it }
+        running.armed = enabled
+        if (!enabled) {
+            running.provenance = false
+            running.publishFault = ""
+            running.stallAfterFrames = -1
+            GateDestination.legacyPlaceholderPublish = false
+            GateDestination.pretendNoAtomicNoReplace = false
+            GateDestination.killDuringCopy = false
+            GateDestination.betweenClaimAndRename = null
+        }
+        return org.json.JSONObject().put("diagnostics", enabled).toString()
+    }
+
+    /** Gate-only: fail publication at "stage", "afterStage" or "raceCreate". */
+    @androidx.media3.common.util.UnstableApi
+    override fun exportGatePublishFault(mode: String): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        val running = gate ?: ExportGate(reactApplicationContext).also { gate = it }
+        if (!running.diagnostics) {
+            return org.json.JSONObject().put("ok", false)
+                .put("error", "diagnostics are not enabled").toString()
+        }
+        running.publishFault = mode
+        // The publication-shape controls, which are not stages of the copy.
+        GateDestination.legacyPlaceholderPublish = mode == "legacyClaim" || mode == "killBetween"
+        GateDestination.pretendNoAtomicNoReplace = mode == "noAtomic"
+        GateDestination.killDuringCopy = mode == "killDuringCopy"
+        GateDestination.betweenClaimAndRename = if (mode == "killBetween") {
+            {
+                // A real process death, not a simulation of one: what is being
+                // measured is the state the filesystem is left in, and only the
+                // kernel can leave it.
+                android.os.Process.killProcess(android.os.Process.myPid())
+            }
+        } else {
+            null
+        }
+        return org.json.JSONObject().put("ok", true).put("mode", mode).toString()
+    }
+
+    /**
+     * Gate-only: does this filesystem have an atomic create-if-absent rename?
+     *
+     * Answered by doing it, in the directory the export would publish into. A
+     * capability read from an API level or a mount table is a guess about the
+     * filesystem the file is actually going to.
+     */
+    @androidx.media3.common.util.UnstableApi
+    override fun exportGateProbeNoReplace(directory: String): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        return GateDestination.probeNoReplace(java.io.File(directory)).toString()
+    }
+
+    /** Gate-only: size and CRC32 of a file, to prove it did or did not change. */
+    @androidx.media3.common.util.UnstableApi
+    override fun exportGateFileDigest(path: String): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        val file = java.io.File(path)
+        val result = org.json.JSONObject().put("exists", file.exists())
+        if (!file.exists()) return result.toString()
+        val crc = java.util.zip.CRC32()
+        runCatching {
+            java.io.FileInputStream(file).use { input ->
+                val buffer = ByteArray(256 * 1024)
+                while (true) {
+                    val read = input.read(buffer)
+                    if (read <= 0) break
+                    crc.update(buffer, 0, read)
+                }
+            }
+        }
+        return result.put("bytes", file.length()).put("crc32", crc.value).toString()
+    }
+
+    /**
+     * Save a finished export into the device's video collection.
+     *
+     * Off the bridge, because a copy is seconds of work and a cancel arriving
+     * during it has to be deliverable. Settles once: the published `content:`
+     * uri, or an error with the pending row already deleted.
+     */
+    @androidx.media3.common.util.UnstableApi
+    override fun mediaSaveAsync(
+        jobId: String,
+        sourceUri: String,
+        promise: com.facebook.react.bridge.Promise,
+    ) {
+        exportExecutor.execute {
+            val result = try {
+                MediaStoreSave.save(reactApplicationContext, jobId, sourceUri)
+            } catch (e: Throwable) {
+                org.json.JSONObject().put("ok", false)
+                    .put("error", "saving failed (" + e.javaClass.simpleName + ")").toString()
+            }
+            promise.resolve(result)
+        }
+    }
+
+    /**
+     * Offer a saved video to the system share sheet.
+     *
+     * The durable `content:` uri only, with a read grant and nothing else.
+     * Returns what the intent actually carried, so a gate can inspect it.
+     */
+    @androidx.media3.common.util.UnstableApi
+    override fun mediaShare(uri: String): String =
+        MediaStoreSave.share(reactApplicationContext, uri)
+
+    /** Ask a running save to stop. Idempotent; a no-op for an unknown job. */
+    @androidx.media3.common.util.UnstableApi
+    override fun mediaSaveCancel(jobId: String): String =
+        org.json.JSONObject().put("ok", true)
+            .put("stopped", MediaStoreSave.cancel(jobId)).toString()
+
+    /**
+     * Delete pending rows a killed process left behind.
+     *
+     * Only this app's, only still-pending, and only under its own folder. A
+     * published item is never a candidate.
+     */
+    @androidx.media3.common.util.UnstableApi
+    override fun mediaSaveSweepPending(): String =
+        MediaStoreSave.sweepPending(reactApplicationContext)
+
+    /** Confirm a saved item still opens. */
+    @androidx.media3.common.util.UnstableApi
+    override fun mediaSaveReadable(uri: String): String =
+        MediaStoreSave.readable(reactApplicationContext, uri)
+
+    /**
+     * Release one temporary output this module produced.
+     *
+     * Not a sweep. Idempotent, and refuses any path it did not create, so a
+     * caller cannot use it to delete something of theirs.
+     */
+    @androidx.media3.common.util.UnstableApi
+    override fun exportReleaseTemporaryOutput(uri: String): String {
+        val running = gate
+        val released = running?.releaseTemporaryOutput(uri) ?: false
+        return org.json.JSONObject().put("released", released).toString()
+    }
+
+    /**
+     * Remove staging orphans a killed process left in a destination directory.
+     *
+     * Positively identified only: the `.pictor-staging-` prefix and the `.tmp`
+     * suffix, in a directory the caller names. Never a wildcard over user files
+     * that happen to look similar.
+     */
+    @androidx.media3.common.util.UnstableApi
+    override fun exportSweepStagingOrphans(directory: String): String {
+        val target = GateDestination.Target(java.io.File(directory, "unused").absolutePath, false)
+        return org.json.JSONObject()
+            .put("swept", GateDestination.sweepStaging(target))
+            .toString()
+    }
+
+    /** Gate-only: which temporaries are still registered, by name only. */
+    @androidx.media3.common.util.UnstableApi
+    override fun exportGateLiveTemporaries(): String {
+        val names = org.json.JSONArray()
+        gate?.liveTemporaryNames()?.forEach { names.put(it) }
+        return names.toString()
+    }
+
+    /** Gate-only: remove a file, so a case can start from a known state. */
+    @androidx.media3.common.util.UnstableApi
+    override fun exportGateDeleteFile(path: String): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        val file = java.io.File(path)
+        val existed = file.exists()
+        val gone = runCatching { file.delete() }.getOrDefault(false)
+        return org.json.JSONObject().put("existed", existed).put("gone", gone).toString()
+    }
+
+    /** Gate-only: a writable directory that is not the gallery. */
+    @androidx.media3.common.util.UnstableApi
+    override fun exportGateExternalFilesDir(): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        return org.json.JSONObject()
+            .put("path", reactApplicationContext.getExternalFilesDir(null)?.absolutePath ?: "")
+            .put(
+                "staging",
+                (reactApplicationContext.getExternalFilesDir(null)?.listFiles { f ->
+                    f.name.startsWith(".pictor-staging-")
+                }?.size) ?: -1,
+            )
+            .toString()
+    }
+
+    /** Gate-only: the current heartbeat epoch. */
+    @androidx.media3.common.util.UnstableApi
+    override fun exportGateBeatEpoch(): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        return org.json.JSONObject().put("epoch", gate?.currentBeatEpoch() ?: -1L).toString()
+    }
+
+    /** Gate-only: offer a beat for `epoch`; reports whether it was accepted. */
+    @androidx.media3.common.util.UnstableApi
+    override fun exportGateTestBeat(source: String, epoch: Double): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        return org.json.JSONObject()
+            .put("accepted", gate?.testBeat(source, epoch.toLong()) ?: false)
+            .toString()
+    }
+
+    /** Gate-only: enable sample hashing so conformance can be checked. */
+    @androidx.media3.common.util.UnstableApi
+    override fun exportGateProvenance(enabled: Boolean): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        val running = gate ?: ExportGate(reactApplicationContext).also { gate = it }
+        if (!running.diagnostics) {
+            return org.json.JSONObject().put("ok", false)
+                .put("error", "diagnostics are not enabled").toString()
+        }
+        running.provenance = enabled
+        return org.json.JSONObject().put("ok", true).put("provenance", enabled).toString()
+    }
+
+    /**
+     * Heartbeat counts and the maximum gap per source.
+     *
+     * The gap is what the watchdog's threshold has to be derived from: the
+     * longest silence real work produces, not how long the platform takes to
+     * notice a wedge.
+     */
+    @androidx.media3.common.util.UnstableApi
+    override fun exportGateHeartbeats(): String =
+        gate?.heartbeatJson() ?: org.json.JSONObject().put("sources", org.json.JSONObject()).toString()
+
+    /** Gate-only: run and resource accounting, by domain. */
+    @androidx.media3.common.util.UnstableApi
+    override fun exportGateAccounting(): String =
+        gate?.accountingJson() ?: org.json.JSONObject().put("runs", org.json.JSONObject()).toString()
+
+    /** Stop `jobId` if it is the one running. Idempotent. */
+    @androidx.media3.common.util.UnstableApi
+    override fun exportCancelJob(jobId: String): String {
+        val running = gate
+        val stopped = running?.cancelJob(jobId) ?: false
+        return org.json.JSONObject().put("ok", true).put("stopped", stopped).toString()
+    }
+
+    /**
+     * Run a compiled project. The production path, and not a gate.
+     *
+     * Split out because the production async entry used to call
+     * `exportGateRunProject`, which meant guarding the gate surface killed real
+     * exports in a release build: every one failed with "diagnostics unavailable
+     * in this build". Caught by the boundary gate on device, which is the reason
+     * that gate exists — "the exporter calls no gate method" was true of the
+     * TypeScript and false of the native entry point it went through.
+     *
+     * The gate wrapper below now adds only its refusal.
+     */
+    @androidx.media3.common.util.UnstableApi
+    private fun runProjectInternal(
+        shardsJson: String,
+        programJson: String,
+        overlaysJson: String,
+        mixProgramJson: String,
+        mixUrisJson: String,
+        timeoutSeconds: Double,
+        destinationJson: String,
+    ): String {
+        val running = gate ?: ExportGate(reactApplicationContext).also { gate = it }
+        val shards = try {
+            val array = org.json.JSONArray(shardsJson)
+            (0 until array.length()).map {
+                val o = array.getJSONObject(it)
+                ExportGate.Shard(
+                    o.getString("uri"), o.optLong("startMs", 0), o.optLong("endMs", 0),
+                    o.optDouble("speed", 1.0).toFloat(), o.optLong("timelineOffsetUs", 0),
+                    o.optBoolean("forceAudioTrack", false), o.optInt("frameDropFps", 0),
+                    o.optLong("encoderRepeatUs", 0),
+                    o.optJSONArray("emitsPerInput")?.let { a -> IntArray(a.length()) { i -> a.getInt(i) } },
+                    o.optJSONArray("outputPtsUs")?.let { a -> LongArray(a.length()) { i -> a.getLong(i) } },
+                    /*
+                      Read, and then ignored unless the build has diagnostics.
+
+                      Parsing them unconditionally keeps one payload shape; what
+                      makes a release safe is that `ExportGate` will not act on
+                      them, not that they were absent from the JSON.
+                    */
+                    o.optInt("cadenceFailAfterEmits", -1),
+                    o.optLong("spanUs", 0),
+                    o.optBoolean("removeAudio", false), o.optString("speedMode", "preserve"),
+                    o.optInt("overlayFailAfterDraws", -1), o.optBoolean("failConcat", false),
+                    o.optInt("cadenceStallAfterEmits", -1),
+                )
+            }
+        } catch (e: Exception) {
+            return org.json.JSONObject().put("ok", false).put("error", "shards: " + e.message).toString()
+        }
+        val outcome = runCatching {
+            running.runProject(
+                shards, programJson, overlaysJson, mixProgramJson, mixUrisJson, timeoutSeconds.toLong(),
+                destinationJson,
+            )
+        }.getOrElse {
+            return org.json.JSONObject().put("ok", false)
+                .put("error", "export threw: " + it.message).toString()
+        }
+        return report(outcome, running)
+    }
+
+    /** The blocking gate entry. Same work, plus the refusal. */
+    @androidx.media3.common.util.UnstableApi
+    override fun exportGateRunProject(
+        shardsJson: String,
+        programJson: String,
+        overlaysJson: String,
+        mixProgramJson: String,
+        mixUrisJson: String,
+        timeoutSeconds: Double,
+        destinationJson: String,
+    ): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        return runProjectInternal(
+            shardsJson, programJson, overlaysJson, mixProgramJson, mixUrisJson,
+            timeoutSeconds, destinationJson,
+        )
+    }
+
+    override fun exportGateMixAudio(programJson: String, urisJson: String): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        val file = java.io.File.createTempFile(
+            "pictor-gate-mix-", ".m4a", reactApplicationContext.cacheDir,
+        )
+        val result = AudioMixer.mix(reactApplicationContext, programJson, urisJson, file)
+        if (!org.json.JSONObject(result).optBoolean("ok", false)) {
+            runCatching { file.delete() }
+        }
+        return result
+    }
+
+    override fun exportGateDecodeProbe(
+        uri: String,
+        fromUs: Double,
+        toUs: Double,
+        speed: Double,
+    ): String = AudioMixer.probeDecode(
+        reactApplicationContext, uri, fromUs.toLong(), toUs.toLong(), speed.toFloat(),
+    )
+
+    override fun exportGatePrerollProbe(
+        uri: String,
+        fromUs: Double,
+        toUs: Double,
+        warmupUs: Double,
+    ): String = AudioMixer.probePreroll(
+        reactApplicationContext, uri, fromUs.toLong(), toUs.toLong(), warmupUs.toLong(),
+    )
+
+    /**
+     * Copy a gate output somewhere a person can play it.
+     *
+     * The human gates need to hear and watch the file, and the adapter's own
+     * temporaries live in app-private cache where nothing else can open them.
+     * This copies, so the cleanup accounting over the originals stays true.
+     */
+    override fun exportGateTrajectory(uri: String, spec: String): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        return GateAudio.trajectory(reactApplicationContext, uri, spec)
+    }
+
+    override fun exportGateStage(uri: String, name: String): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        val out = org.json.JSONObject()
+        return try {
+            val dir = reactApplicationContext.getExternalFilesDir(null)
+                ?: return out.put("ok", false).put("error", "no external files dir").toString()
+            val target = java.io.File(dir, name)
+            java.io.File(uri).inputStream().use { input ->
+                target.outputStream().use { output -> input.copyTo(output) }
+            }
+            out.put("ok", true).put("path", target.absolutePath).put("bytes", target.length()).toString()
+        } catch (e: Exception) {
+            out.put("ok", false).put("error", e.javaClass.simpleName + ": " + e.message).toString()
+        }
+    }
+
+    override fun exportGatePrimingProbe(
+        rate: Double,
+        channels: Double,
+        bitrate: Double,
+        at: Double,
+    ): String = AacPriming.probe(rate.toInt(), channels.toInt(), bitrate.toInt(), at.toInt())
+
+    override fun exportGateStretchProbe(
+        rate: Double,
+        channels: Double,
+        frames: Double,
+        speed: Double,
+    ): String = AudioMixer.probeStretch(rate.toInt(), channels.toInt(), frames.toInt(), speed.toFloat())
+
+    override fun exportGateStageResource(base64: String, width: Double, height: Double): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        val out = org.json.JSONObject()
+        try {
+            val bytes = android.util.Base64.decode(base64, android.util.Base64.DEFAULT)
+            val file = java.io.File.createTempFile(
+                "pictor-gate-overlay-", ".rgba", reactApplicationContext.cacheDir,
+            )
+            file.writeBytes(bytes)
+            val crc = java.util.zip.CRC32()
+            crc.update(bytes)
+            out.put("ok", true).put("file", file.absolutePath)
+                .put("byteLength", bytes.size).put("checksum", crc.value)
+        } catch (e: Exception) {
+            out.put("ok", false).put("error", e.javaClass.simpleName + ": " + e.message)
+        }
+        return out.toString()
+    }
+
+    override fun exportGateAudio(uri: String, windowsJson: String): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        return GateAudio.analyse(reactApplicationContext, uri, windowsJson)
+    }
+
+    override fun exportGateProbe(uri: String, probesJson: String): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        return GateFrames.probe(reactApplicationContext, uri, probesJson)
+    }
+
+    override fun exportGateTracks(uri: String): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        return GateFrames.tracks(reactApplicationContext, uri)
+    }
+
+    override fun exportGateSample(uri: String, timestampsUs: ReadableArray): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        val times = LongArray(timestampsUs.size()) { timestampsUs.getDouble(it).toLong() }
+        return GateFrames.sample(reactApplicationContext, uri, times)
+    }
+
+    override fun exportGateCompare(
+        leftUri: String,
+        rightUri: String,
+        timestampsUs: ReadableArray,
+    ): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        val times = LongArray(timestampsUs.size()) { timestampsUs.getDouble(it).toLong() }
+        return GateFrames.compare(reactApplicationContext, leftUri, rightUri, times)
+    }
+
+    override fun media3Play() { media3?.play() }
+
+    override fun media3Pause() { media3?.pause() }
+
+    override fun media3Seek(positionUs: Double) { media3?.seekTo(positionUs.toLong()) }
+
+    override fun media3SetRate(rate: Double) { media3?.setRate(rate.toFloat()) }
+
+    /** Ask the current player to try its source again after a failure. */
+    override fun media3Retry() { media3?.retry() }
+
+    override fun media3Release() {
+        media3?.release()
+        media3 = null
+    }
+
+    // ---- Thumbnails ------------------------------------------------------
+
+    override fun thumbnailRequest(uri: String, sourceTimeUs: Double, widthPx: Double): Double =
+        ThumbnailDecoder.request(
+            uri,
+            sourceTimeUs.toLong(),
+            widthPx.toInt(),
+            reactApplicationContext,
+        ).toDouble()
+
+    override fun thumbnailCancel(token: Double) { ThumbnailDecoder.cancel(token.toLong()) }
+
+    /** Base64 JPEG, or null while it is still decoding. Consumes the result. */
+    override fun thumbnailTake(token: Double): String? = ThumbnailDecoder.take(token.toLong())
+
+    override fun thumbnailError(token: Double): String? =
+        ThumbnailDecoder.takeError(token.toLong())
+
+    override fun thumbnailRunning(token: Double): Boolean =
+        ThumbnailDecoder.isRunning(token.toLong())
+
+    override fun thumbnailReleaseSource(uri: String) { ThumbnailDecoder.releaseSource(uri) }
+
+    override fun thumbnailReleaseAll() { ThumbnailDecoder.releaseAll() }
+
+    override fun thumbnailCounters(): WritableMap {
+        val counters = ThumbnailDecoder.counters()
+        return Arguments.createMap().apply {
+            putDouble("decoded", counters[0].toDouble())
+            putDouble("cancelled", counters[1].toDouble())
+            putDouble("failed", counters[2].toDouble())
+            putDouble("running", counters[3].toDouble())
+            putDouble("retrievers", counters[4].toDouble())
+        }
+    }
+
+    override fun media3State(): WritableMap {
+        val out = Arguments.createMap()
+        val snapshot = media3?.state() ?: mapOf("released" to true)
+        for ((key, value) in snapshot) {
+            when (value) {
+                is Boolean -> out.putBoolean(key, value)
+                is Long -> out.putDouble(key, value.toDouble())
+                is Int -> out.putInt(key, value)
+                is Float -> out.putDouble(key, value.toDouble())
+                // Double had no branch, so every one of them fell to the
+                // `else` and arrived in JS as a *string*. `"1.00"` reads as
+                // present, spreads over a numeric default, and kills the app on
+                // the first `.toFixed` — a silent stringification is worse than
+                // a dropped field, because the value looks fine in a log.
+                is Double -> out.putDouble(key, value)
+                is Number -> out.putDouble(key, value.toDouble())
+                is String -> out.putString(key, value)
+                // Anything else is a type this boundary does not know how to
+                // carry. Stringifying it silently is what hid the Doubles, so
+                // it is named instead: a consumer sees the type it got rather
+                // than a plausible-looking string.
+                else -> out.putString(key, "<unconvertible ${value.javaClass.simpleName}>")
+            }
+        }
+        out.putString("error", lastMedia3Error)
+        return out
+    }
+
+    private var lastMedia3Error: String = ""
+
+
+    /**
+     * Release everything when the React context goes away.
+     *
+     * A reload or a host teardown does not give JS a chance to release, and a
+     * player outliving its context holds a codec and a surface the next one
+     * needs.
+     */
+    override fun invalidate() {
+        ThumbnailDecoder.releaseAll()
+        media3?.release()
+        media3 = null
+        super.invalidate()
+    }
+
+    companion object {
+        const val NAME = "PictorVideo"
+
+        init { System.loadLibrary("pictor_video") }
+
+        /** Implemented in `cpp/pictor_videosurface.cpp`. */
+        @JvmStatic external fun nativeInstallVideoSurface(runtimePtr: Long): Boolean
+        @JvmStatic external fun nativeInstallOverlayStaging(
+            runtimePtr: Long,
+            cacheDir: String,
+        ): Boolean
+    }
+}