@bycrux/editor 0.11.2 → 1.0.1

package/src/engine/audio-worklet-source.ts

@@ -0,0 +1,160 @@
+/**
+ * SP4 T4 — the master clock's `AudioWorkletProcessor`, as an inlined source
+ * string.
+ *
+ * Loaded via `URL.createObjectURL(new Blob([audioWorkletSource], { type:
+ * 'text/javascript' }))` and `ctx.audioWorklet.addModule(url)` — plan decision
+ * 6, the same rule `decode-worker-source.ts` follows and for the same reason:
+ * the Blob-URL form is the only one that needs nothing from a consumer's
+ * bundler (`?raw` is Vite-only, and montaj's ui is not the only host).
+ *
+ * Because it is a string it cannot be type-checked, linted or unit-tested, so
+ * — exactly like the decode worker — it is **thin by architecture**. Every
+ * decision lives main-side in `audio-clock.ts` under test: what to decode,
+ * how much to keep queued, the resample ratio, the project↔media time mapping,
+ * the clock extrapolation (volume rides a main-side output GainNode, downstream
+ * of this node — not the ring). What is left here is
+ * the irreducible audio-thread part:
+ *
+ *  1. a FIFO of interleaved Float32 PCM chunks, drained one render quantum at
+ *     a time ("ring buffer" is the spike's name for it; the transport is
+ *     postMessage chunks, NOT a `SharedArrayBuffer` — Hub cannot serve the
+ *     COOP/COEP headers cross-origin isolation requires, plan decision 4);
+ *  2. `samplesConsumed`: how many output frames have actually been rendered
+ *     since the last reset. This — not decode progress, not wall time — is
+ *     the master clock's ground truth, reported back at ~10Hz;
+ *  3. **silence through underruns**: an empty queue renders silence and the
+ *     frame counter still advances. A real audio device does not stall when
+ *     it is starved, and neither may the clock: freezing it here would freeze
+ *     the canvas painter that follows it (SP1 §6 measured playback against
+ *     exactly this clock);
+ *  4. a `playing` gate, so pause stops output *and* stops the clock without
+ *     tearing down the node;
+ *  5. an `epoch` echoed on every report, so main can discard readings that
+ *     were in flight when it reset the ring (a seek). Same shape as the decode
+ *     worker's `reqId` supersession — SP1 §7.3/§7.4 are what stale-request
+ *     bookkeeping costs when it is missing.
+ *
+ * Constants are INJECTED via `processorOptions` rather than duplicated in the
+ * string (the string cannot import), matching how `decode-worker-source.ts`
+ * receives `preRollEpsilonUs` at `init`.
+ *
+ * `spikes/playback-engine/src/audio-worklet.js` is the precedent. The
+ * deliberate additions over it are the `playing` gate, the `epoch`, and the
+ * duplicate-registration guard — the spike had no transport (it played once,
+ * from a context it owned and threw away), whereas this runs on the page's
+ * ONE shared `window.__montajSharedCtx`, which outlives every clock built on
+ * it and would otherwise throw `NotSupportedError` on the second
+ * `registerProcessor` of the same name (dev HMR and every clip-boundary
+ * clock swap both hit that path).
+ */
+
+/** Processor name registered by `audioWorkletSource`. Keep in sync with the string. */
+export const RING_PROCESSOR_NAME = 'montaj-engine-pcm-ring'
+
+export const audioWorkletSource = `'use strict';
+
+class MontajRingProcessor extends AudioWorkletProcessor {
+  constructor(options) {
+    super();
+    var opts = (options && options.processorOptions) || {};
+    // ~10Hz. Injected, not hardcoded: audio-clock.ts owns the number because
+    // its wall-clock extrapolation window is derived from the same constant.
+    this.reportIntervalS = typeof opts.reportIntervalS === 'number' ? opts.reportIntervalS : 0.1;
+
+    // FIFO of { pcm: Float32Array (interleaved), channels: number, offsetFrames: number }.
+    this.queue = [];
+    this.queuedFrames = 0;    // frames sitting in the FIFO, not yet rendered
+    this.samplesConsumed = 0; // output frames rendered since the last reset — the clock's ground truth
+    this.underrunFrames = 0;  // of those, how many were silence because the FIFO was empty
+    this.epoch = 0;           // bumped by main on every reset; echoed on every report
+    this.playing = false;     // pause gate: no output, no drain, no clock advance
+    this.lastReportAt = 0;    // AudioWorkletGlobalScope currentTime (s) at the last report
+
+    this.port.onmessage = (ev) => {
+      var msg = ev.data;
+      if (msg.t === 'chunk') {
+        this.queue.push({ pcm: msg.pcm, channels: msg.channels, offsetFrames: 0 });
+        this.queuedFrames += msg.frames;
+      } else if (msg.t === 'play') {
+        this.playing = true;
+      } else if (msg.t === 'pause') {
+        this.playing = false;
+        // Report immediately: main freezes the playhead at pause and wants the
+        // truest sample count it can get rather than waiting up to a full
+        // report interval for one.
+        this.report();
+      } else if (msg.t === 'reset') {
+        this.queue = [];
+        this.queuedFrames = 0;
+        this.samplesConsumed = 0;
+        this.underrunFrames = 0;
+        this.epoch = msg.epoch;
+        this.lastReportAt = currentTime;
+        this.report();
+      }
+    };
+  }
+
+  report() {
+    this.port.postMessage({
+      t: 'consumed',
+      epoch: this.epoch,
+      samplesConsumed: this.samplesConsumed,
+      underrunFrames: this.underrunFrames,
+      queuedFrames: this.queuedFrames,
+    });
+  }
+
+  process(_inputs, outputs) {
+    var output = outputs[0];
+    if (!output || output.length === 0 || !output[0]) return true;
+    var frameCount = output[0].length;
+    var outChannels = output.length;
+
+    // Paused: leave \`output\` untouched (it arrives zero-filled, i.e. silence)
+    // and do NOT advance the clock or drain the FIFO. Resuming continues from
+    // exactly where the audio stopped.
+    if (this.playing) {
+      for (var i = 0; i < frameCount; i++) {
+        var entry = this.queue[0];
+        if (!entry) {
+          // Underrun: nothing queued. This frame is silence and the clock
+          // still advances through it — see the module header, point 3.
+          this.underrunFrames++;
+          continue;
+        }
+        var frameBase = entry.offsetFrames * entry.channels;
+        for (var ch = 0; ch < outChannels; ch++) {
+          // Fewer source channels than outputs (mono source, stereo out):
+          // duplicate the last source channel rather than emitting silence.
+          var srcCh = ch < entry.channels ? ch : entry.channels - 1;
+          output[ch][i] = entry.pcm[frameBase + srcCh];
+        }
+        entry.offsetFrames++;
+        this.queuedFrames--;
+        if (entry.offsetFrames * entry.channels >= entry.pcm.length) this.queue.shift();
+      }
+      this.samplesConsumed += frameCount;
+    }
+
+    if (currentTime - this.lastReportAt >= this.reportIntervalS) {
+      this.lastReportAt = currentTime;
+      this.report();
+    }
+
+    return true; // keep the processor alive for the life of the node
+  }
+}
+
+// The AudioWorkletGlobalScope belongs to the CONTEXT, and the context here is
+// the page-lifetime shared one — so this module can be added more than once
+// (a second clock, a dev-server hot reload). A duplicate registerProcessor
+// throws NotSupportedError and rejects the addModule promise, which would drop
+// an otherwise-healthy engine onto the wall-clock fallback. The name stays
+// registered from the first load either way.
+if (!globalThis.__montajEngineRingRegistered) {
+  globalThis.__montajEngineRingRegistered = true;
+  registerProcessor('${RING_PROCESSOR_NAME}', MontajRingProcessor);
+}
+`

package/src/engine/batch-planner.ts

@@ -0,0 +1,308 @@
+/**
+ * SP4 T3 — the decode planner.
+ *
+ * Every decision about *what to decode next* lives here, as pure functions
+ * over a `SampleTable` (T2) and a small state record. Nothing in this file
+ * touches the DOM, WebCodecs, workers or `postMessage`, which is the point:
+ * the decode worker ships as an inlined source *string* (plan decision 6) and
+ * a string cannot be unit tested the way a module can, so the architecture
+ * pushes all planning main-side and leaves the string with nothing but decode
+ * calls and supersession bookkeeping. `frame-server.ts` is the imperative
+ * shell over these functions; `__tests__/batch-planner.test.ts` is where the
+ * SP1 requirements are actually proven.
+ *
+ * Three of SP1's five engine requirements are decided here — each one is a
+ * *fix* for a measured defect in `spikes/playback-engine/RESULTS.md`, not a
+ * stylistic preference:
+ *
+ *  1. **Decode-order feed** (§7.1). Batches are contiguous slices of
+ *     `samples`, which T2 guarantees is container/decode order. Time→index
+ *     questions bisect `presIndex` (via T2's `sampleAtOrBefore` /
+ *     `keyframeAtOrBefore`); the *slice* is never reordered. Feeding
+ *     WebCodecs in presentation order kills the decoder on the first
+ *     non-intra frame, and the bug is invisible on all-intra proxies — which
+ *     is exactly how it survived to SP1's measurement stage.
+ *  2. **Pipelined decode-ahead** (§6.1, the 4.5fps bug). Up to
+ *     `MAX_IN_FLIGHT_BATCHES` requests may sit on the worker at once, and
+ *     batches are floored at `minBatchFrames(N)`. The pre-fix planner allowed
+ *     exactly one in flight and sized each batch to the current shortfall, so
+ *     after the initial fill it asked for **one frame per batch** — and every
+ *     batch ends in `decoder.flush()`, which drains the whole decoder
+ *     pipeline. That configuration is still reachable through `PipelineConfig`
+ *     (`maxInFlightBatches: 1, minBatchFrames: 1`) purely so the test can
+ *     reproduce the degeneration against this same code.
+ *  3. **Min-cts batch targets** (§6.1's second, latent bug). The worker drops
+ *     frames below `targetTsUs` as pre-roll; in *decode* order `batch[0]` is
+ *     not the earliest presentation time in the batch, so `batch[0].tsUs` as
+ *     the target silently discards valid frames. The target is the MINIMUM
+ *     cts in the batch, floored at the session's real first-wanted frame
+ *     (the only legitimate pre-roll, i.e. keyframe → start).
+ *
+ * The fourth (`PRE_ROLL_EPSILON_US`, §7.2) is decided here and *applied*
+ * inside the worker — it is handed over in the `init` command rather than
+ * hardcoded in the worker string, so the constant has exactly one home.
+ */
+import { keyframeAtOrBefore, sampleAtOrBefore, type SampleRef, type SampleTable } from './demux'
+
+/**
+ * Tolerance for the worker's pre-roll comparison, in microseconds (SP1 §7.2).
+ *
+ * `EncodedVideoChunk.timestamp` is a `long long` — INTEGER microseconds —
+ * while T2's `SampleRef.tsUs` is deliberately an un-rounded float
+ * (`cts / timescale * 1e6`, e.g. `33333.333…`). A chunk fed in at `33333.333`
+ * comes back off the decoder stamped `33333`, so a naive
+ * `frame.timestamp < targetTsUs` test rejects **the very frame that was
+ * requested** as pre-roll: SP1 measured ~2 of 3 seeks painting nothing, and
+ * those seeks were silently excluded from the latency distribution rather
+ * than failing loudly. Frames are ≥16000µs apart at any sane frame rate, so
+ * 1µs of slack cannot admit a genuinely earlier frame.
+ */
+export const PRE_ROLL_EPSILON_US = 1
+
+/**
+ * How many `decodeRange` requests may sit on the worker at once. Two is
+ * enough to hide the main-thread round trip: the worker starts the next batch
+ * the instant it finishes flushing the previous one, instead of idling until
+ * main notices and asks again (SP1 §6.1).
+ */
+export const MAX_IN_FLIGHT_BATCHES = 2
+
+/** Default decode-ahead budget in frames — the N the spike measured at 30fps. */
+export const DEFAULT_DECODE_AHEAD_FRAMES = 30
+
+/** One contiguous run of DECODE indices to hand the worker. */
+export interface DecodeBatch {
+  /** First decode index, inclusive. */
+  startIdx: number
+  /** Last decode index, exclusive. */
+  endIdx: number
+  /** `endIdx - startIdx`; carried so callers don't recompute it for `batchExpected`. */
+  count: number
+  /**
+   * Pre-roll floor for this batch: the worker emits frames with
+   * `cts >= targetTsUs - PRE_ROLL_EPSILON_US` and closes everything below it.
+   * Always the minimum cts in the batch (floored at the session's first
+   * wanted frame) — never `samples[startIdx].tsUs`.
+   */
+  targetTsUs: number
+}
+
+/** Decode-ahead bookkeeping for one streaming session. Immutable; every transition returns a new record. */
+export interface PipelineState {
+  /** Next decode index to request. Advances monotonically through `samples`. */
+  nextSampleIdx: number
+  /** Frames decoded, delivered to main, and not yet consumed by the painter. */
+  buffered: number
+  /** Frames requested but not yet delivered (or accounted for by a batch's `done`). */
+  inFlightFrames: number
+  /** `decodeRange` requests posted but not yet `done`. */
+  inFlightBatches: number
+  /**
+   * The session's genuine first wanted frame. Only the first batch of a
+   * session has real pre-roll (keyframe → start sample); every later batch
+   * floors above this anyway, so applying it unconditionally is a no-op after
+   * the first batch and keeps the rule in one place.
+   */
+  firstBatchTargetTsUs: number
+}
+
+export interface PipelineConfig {
+  /**
+   * Decode-ahead budget in frames. `buffered + inFlightFrames` never exceeds
+   * it, so N keeps meaning "at most N frames alive at once" — the property
+   * SP1 §8's N sweep is measured against.
+   */
+  decodeAheadFrames: number
+  /** See `MAX_IN_FLIGHT_BATCHES`. */
+  maxInFlightBatches: number
+  /**
+   * Batch floor. Defaults to `minBatchFrames(decodeAheadFrames)`; overridable
+   * ONLY so the test can rebuild SP1's pre-fix (4.5fps) configuration against
+   * this same planner. Production never sets it.
+   */
+  minBatchFrames?: number
+}
+
+/**
+ * Don't pay a worker round trip plus a full `decoder.flush()` for a handful of
+ * frames: floor each batch at a quarter of the decode-ahead budget (minimum
+ * 4), so flush cost amortizes over many frames instead of one (SP1 §6.1).
+ */
+export function minBatchFrames(decodeAheadFrames: number): number {
+  return Math.max(4, Math.floor(decodeAheadFrames / 4))
+}
+
+/**
+ * The pre-roll predicate, shared by the worker (which receives
+ * `PRE_ROLL_EPSILON_US` via its `init` command) and by anything main-side that
+ * needs to reason about the same boundary. See `PRE_ROLL_EPSILON_US`.
+ */
+export function shouldEmitFrame(
+  frameTsUs: number,
+  targetTsUs: number,
+  epsilonUs: number = PRE_ROLL_EPSILON_US,
+): boolean {
+  return frameTsUs >= targetTsUs - epsilonUs
+}
+
+/**
+ * The supersession rule, stated once. A request is superseded the moment a
+ * strictly newer request id exists; the worker applies it to decide whether to
+ * transfer or close a frame, and `frame-server.ts` applies it again main-side
+ * to stragglers that were already in flight when the newer request went out.
+ */
+export function isSuperseded(reqId: number, latestReqId: number): boolean {
+  return reqId < latestReqId
+}
+
+/**
+ * Minimum presentation time across a decode-order slice.
+ *
+ * The whole reason this function exists: in decode order the timestamps
+ * zig-zag whenever B-frames are present, so the first sample of a slice is not
+ * its earliest presentation time (SP1 §6.1). Latent on SP3's all-intra
+ * proxies, live the moment a reordered source shows up.
+ */
+export function minCtsUs(samples: readonly SampleRef[], startIdx: number, endIdx: number): number {
+  let min = Infinity
+  for (let i = startIdx; i < endIdx; i++) {
+    if (samples[i].tsUs < min) min = samples[i].tsUs
+  }
+  return min
+}
+
+/**
+ * Plan a one-shot seek: the decode run needed to produce the frame displayed
+ * at `targetTsUs` (raw container microseconds — the caller maps project time
+ * through `firstPresentationTsUs`).
+ *
+ * The run is `samples.slice(keyframeAtOrBefore, sampleAtOrBefore + 1)`, both
+ * of which are DECODE indices from T2, and `targetTsUs` on the returned batch
+ * is the exact cts of the requested frame — so the worker emits that frame and
+ * anything at-or-after it in the run, and closes the keyframe→target pre-roll.
+ * Returns `null` for an empty table.
+ */
+export function planSeek(table: SampleTable, targetTsUs: number): DecodeBatch | null {
+  if (table.samples.length === 0) return null
+  const startIdx = keyframeAtOrBefore(table, targetTsUs)
+  const targetIdx = sampleAtOrBefore(table, targetTsUs)
+  const endIdx = targetIdx + 1
+  return {
+    startIdx,
+    endIdx,
+    count: endIdx - startIdx,
+    targetTsUs: table.samples[targetIdx].tsUs,
+  }
+}
+
+/**
+ * Open a streaming session at `fromTsUs`: decoding starts at the enclosing
+ * keyframe, and everything between that keyframe and the first wanted frame is
+ * this session's only genuine pre-roll.
+ */
+export function planStreamStart(table: SampleTable, fromTsUs: number): PipelineState {
+  const samples = table.samples
+  const keyIdx = samples.length === 0 ? 0 : keyframeAtOrBefore(table, fromTsUs)
+  const startIdx = samples.length === 0 ? 0 : sampleAtOrBefore(table, fromTsUs)
+  return {
+    nextSampleIdx: keyIdx,
+    buffered: 0,
+    inFlightFrames: 0,
+    inFlightBatches: 0,
+    firstBatchTargetTsUs: samples.length === 0 ? 0 : samples[startIdx].tsUs,
+  }
+}
+
+/**
+ * Top up the decode-ahead pipeline: the batches to post right now, plus the
+ * state that results from posting them (the caller posts them and keeps the
+ * state; nothing is mutated in place).
+ *
+ * Loop conditions, in order, and why each one is there:
+ *  - `inFlightBatches < maxInFlightBatches` — keep the worker fed so it never
+ *    idles waiting for a main-thread round trip (SP1 §6.1).
+ *  - end of source — nothing left to ask for.
+ *  - `capacity = N - buffered - inFlightFrames` — the frame budget. Holding
+ *    `buffered + inFlight ≤ N` is what keeps N meaning "at most N frames alive
+ *    at once", which SP1 §8's memory sweep depends on.
+ *  - `capacity < minBatch` while not starving — amortize the flush. "Starving"
+ *    (nothing buffered, nothing coming) overrides it: any batch beats a stall.
+ */
+export function planNextBatches(
+  table: SampleTable,
+  state: PipelineState,
+  config: PipelineConfig,
+): { batches: DecodeBatch[]; state: PipelineState } {
+  const samples = table.samples
+  const minBatch = config.minBatchFrames ?? minBatchFrames(config.decodeAheadFrames)
+  const batches: DecodeBatch[] = []
+  let next = { ...state }
+
+  while (next.inFlightBatches < config.maxInFlightBatches) {
+    if (next.nextSampleIdx >= samples.length) break
+
+    const capacity = config.decodeAheadFrames - next.buffered - next.inFlightFrames
+    if (capacity <= 0) break
+    const starving = next.buffered === 0 && next.inFlightFrames === 0
+    if (!starving && capacity < minBatch) break
+
+    const startIdx = next.nextSampleIdx
+    const endIdx = Math.min(startIdx + capacity, samples.length)
+    const count = endIdx - startIdx
+    if (count <= 0) break
+
+    batches.push({
+      startIdx,
+      endIdx,
+      count,
+      // Min cts, never samples[startIdx].tsUs — see `minCtsUs`. The floor is
+      // the session's real first wanted frame, which is what legitimately
+      // discards the keyframe→start pre-roll on the first batch only.
+      targetTsUs: Math.max(next.firstBatchTargetTsUs, minCtsUs(samples, startIdx, endIdx)),
+    })
+
+    next = {
+      ...next,
+      nextSampleIdx: endIdx,
+      inFlightFrames: next.inFlightFrames + count,
+      inFlightBatches: next.inFlightBatches + 1,
+    }
+  }
+
+  return { batches, state: next }
+}
+
+/** A frame arrived from the worker and joined the main-side buffer. */
+export function onFrameBuffered(state: PipelineState): PipelineState {
+  return {
+    ...state,
+    buffered: state.buffered + 1,
+    inFlightFrames: Math.max(0, state.inFlightFrames - 1),
+  }
+}
+
+/** `n` buffered frames left the buffer (painted, dropped as late, or closed on teardown). */
+export function onFramesConsumed(state: PipelineState, n = 1): PipelineState {
+  return { ...state, buffered: Math.max(0, state.buffered - n) }
+}
+
+/**
+ * A batch reported `done`. Reconciliation, not just a decrement: frames the
+ * worker dropped as pre-roll never arrive, so the per-frame decrement in
+ * `onFrameBuffered` under-counts and `inFlightFrames` would drift upward,
+ * permanently eating decode-ahead capacity until the pipeline wedged.
+ * `expected` is the batch's `count`; `decoded` is what the worker actually
+ * emitted.
+ */
+export function reconcileOnBatchDone(
+  state: PipelineState,
+  expected: number,
+  decoded: number,
+): PipelineState {
+  const missing = Math.max(0, expected - decoded)
+  return {
+    ...state,
+    inFlightBatches: Math.max(0, state.inFlightBatches - 1),
+    inFlightFrames: Math.max(0, state.inFlightFrames - missing),
+  }
+}

package/src/engine/debug-hud.tsx

@@ -0,0 +1,54 @@
+/**
+ * SP4 T7 — the debug HUD: fps / dropped / buffered / clock-kind, live,
+ * rendered only behind `engine.debugHud`.
+ *
+ * Precedent: `spikes/playback-engine/src/hud.ts`'s `mountPlaybackHud` — the
+ * same four numbers (painted fps over a rolling window, drops, decode-ahead
+ * buffer depth, which clock is driving), read the same way (a rolling
+ * window, never a single instantaneous sample). Deliberately NOT that file:
+ * no per-(source, hardwareAcceleration) bucket matrix, no JSON export
+ * button, no memory probe, no `window.__playbackHud` console handle — this
+ * is a production affordance for "is the engine keeping up right now", not
+ * the spike's benchmarking instrument. One engine, one bucket.
+ *
+ * Polls `Engine.stats()` (via the stable `getStats` the facade/hook exposes)
+ * on its own timer rather than subscribing to engine status: `EngineStatus`
+ * only republishes on a genuine transport/picture/clip/clock CHANGE
+ * (`scheduler.ts`'s `publish`), so fps/buffer — which move on every painted
+ * frame while playing — would sit stale between those events if this
+ * component keyed off status instead.
+ */
+import { useEffect, useState } from 'react'
+import type { EngineStats } from './index'
+
+/** 2Hz — fast enough to read as "live" without re-rendering on every paint. */
+const POLL_MS = 500
+
+interface DebugHudProps {
+  getStats: () => EngineStats | null
+}
+
+function fmtNum(v: number | undefined, digits = 0): string {
+  return v === undefined ? 'n/a' : v.toFixed(digits)
+}
+
+export default function DebugHud({ getStats }: DebugHudProps) {
+  const [stats, setStats] = useState<EngineStats | null>(() => getStats())
+
+  useEffect(() => {
+    const id = setInterval(() => setStats(getStats()), POLL_MS)
+    return () => clearInterval(id)
+  }, [getStats])
+
+  return (
+    <div
+      className="montaj-engine-debug-hud absolute bottom-2 left-2 select-none rounded bg-black/70 px-2 py-1 font-mono text-[10px] leading-tight text-white/80 pointer-events-none"
+      style={{ zIndex: 3 }}
+    >
+      <div>fps {fmtNum(stats?.fps, 1)}</div>
+      <div>dropped {fmtNum(stats?.dropped)}</div>
+      <div>buffered {fmtNum(stats?.buffered)}</div>
+      <div>clock {stats?.clock ?? 'n/a'}</div>
+    </div>
+  )
+}

package/src/engine/decode-worker-source.ts

@@ -0,0 +1,142 @@
+/**
+ * SP4 T3 — the decode worker, as an inlined source string.
+ *
+ * Loaded via `URL.createObjectURL(new Blob([decodeWorkerSource], { type:
+ * 'text/javascript' }))` and `new Worker(url)` — a **classic** worker, so this
+ * string must be plain JS with no imports (plan decision 6: the Blob-URL form
+ * is the only one that needs nothing from a consumer's bundler; `?raw` is
+ * Vite-only and `new Worker(new URL(...))` can only be verified against Hub's
+ * webpack config, which does not live in this repo).
+ *
+ * Because it is a string, it cannot be type-checked, linted or unit-tested as
+ * a module — so it is kept **thin by architecture**. Everything that decides
+ * *what* to decode (batch boundaries, keyframe alignment, batch sizing, the
+ * min-cts pre-roll target, the epsilon value itself) lives main-side in
+ * `batch-planner.ts` under test. What is left here is the irreducible
+ * off-main-thread part:
+ *
+ *  1. a serial queue over exactly one `VideoDecoder` (every request awaits the
+ *     previous one's `flush()`, so the `output` callback always belongs to the
+ *     request marked `current`);
+ *  2. supersession by request id — **no `decoder.reset()` anywhere**. `reset()`
+ *     drops the decoder to `unconfigured` and the next `decode()` throws
+ *     `InvalidStateError`, so a superseded request is handled purely by never
+ *     transferring its frames (they are closed here instead, immediately);
+ *  3. the pre-roll drop, using the epsilon handed over at `init` (SP1 §7.2 —
+ *     see `PRE_ROLL_EPSILON_US` in `batch-planner.ts` for why 1µs);
+ *  4. the **total `done` contract**: every `decodeRange` posts exactly one
+ *     `done`, whether it decoded, was skipped as stale before reaching the
+ *     decoder, or threw. SP1 §7.4 is what happens without it — `frame-server`'s
+ *     pending map orphans an entry and a seek promise never settles.
+ *
+ * Samples arrive by structured clone (never transfer): mp4box allocates a
+ * dedicated `Uint8Array` per sample, so a clone copies exactly that sample's
+ * bytes, whereas transferring would detach the buffer from the demuxed sample
+ * table and corrupt every later request that overlaps the same GOP. See
+ * `frame-server.ts`'s `postBatch`.
+ *
+ * `spikes/playback-engine/src/decode-worker.ts` is the precedent; the
+ * deliberate simplification is that `done` is posted from ONE place after the
+ * try/catch instead of once per exit path.
+ */
+export const decodeWorkerSource = `'use strict';
+
+var decoder = null;
+var queue = [];
+var latestReqId = -1;
+var processing = false;
+var preRollEpsilonUs = 1;
+
+// The request being fed to the decoder right now. At most one exists: drain()
+// awaits each request's flush() before starting the next, so every output
+// callback belongs to whichever request is current when it fires.
+var current = null;
+
+function post(msg, transfer) {
+  self.postMessage(msg, transfer || []);
+}
+
+function describe(err) {
+  return err && err.message ? err.message : String(err);
+}
+
+function onFrame(frame) {
+  if (!current || current.reqId < latestReqId) {
+    // Superseded while this request was still flushing. Close, never transfer.
+    frame.close();
+    if (current) current.dropped++;
+    return;
+  }
+  if (frame.timestamp < current.targetTsUs - preRollEpsilonUs) {
+    // Pre-roll: decoded only to prime prediction from the keyframe.
+    frame.close();
+    current.dropped++;
+    return;
+  }
+  current.decoded++;
+  post({ t: 'frame', frame: frame, reqId: current.reqId }, [frame]);
+}
+
+async function runRange(req) {
+  current = { reqId: req.reqId, targetTsUs: req.targetTsUs, decoded: 0, dropped: 0 };
+  try {
+    if (!decoder) throw new Error('decodeRange before init');
+    for (var i = 0; i < req.samples.length; i++) {
+      var s = req.samples[i];
+      decoder.decode(new EncodedVideoChunk({
+        type: s.isKey ? 'key' : 'delta',
+        timestamp: s.tsUs,
+        duration: s.durUs,
+        data: s.data,
+      }));
+    }
+    await decoder.flush();
+  } catch (err) {
+    post({ t: 'error', message: 'decode: ' + describe(err), reqId: req.reqId });
+  }
+  // Unconditional: the total done contract has exactly one site.
+  post({ t: 'done', reqId: req.reqId, decoded: current.decoded, dropped: current.dropped });
+  current = null;
+}
+
+async function drain() {
+  if (processing) return;
+  processing = true;
+  while (queue.length > 0) {
+    var req = queue.shift();
+    if (req.reqId < latestReqId) {
+      // Stale before decoding a byte - still owes its done.
+      post({ t: 'done', reqId: req.reqId, decoded: 0, dropped: 0 });
+      continue;
+    }
+    await runRange(req);
+  }
+  processing = false;
+}
+
+self.onmessage = function (ev) {
+  var cmd = ev.data;
+  if (cmd.t === 'init') {
+    if (typeof cmd.preRollEpsilonUs === 'number') preRollEpsilonUs = cmd.preRollEpsilonUs;
+    try {
+      decoder = new VideoDecoder({
+        output: onFrame,
+        error: function (e) { post({ t: 'error', message: 'decoder: ' + describe(e) }); },
+      });
+      decoder.configure({
+        codec: cmd.codec,
+        description: cmd.description,
+        hardwareAcceleration: cmd.hardwareAcceleration,
+      });
+    } catch (err) {
+      post({ t: 'error', message: 'init: ' + describe(err) });
+    }
+    return;
+  }
+  if (cmd.t === 'decodeRange') {
+    if (cmd.reqId > latestReqId) latestReqId = cmd.reqId;
+    queue.push(cmd);
+    drain();
+  }
+};
+`