@bycrux/editor 0.12.0 → 1.0.1

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

@@ -0,0 +1,316 @@
+/**
+ * SP4 T4 — the ring processor's own rules, tested against the shipped string.
+ *
+ * The worklet ships as an inlined source string (plan decision 6), so it can
+ * neither be imported as a module nor type-checked. It can be *executed*
+ * though — `decode-worker-source.test.ts` is the precedent. Its only free
+ * identifiers are `AudioWorkletProcessor`, `registerProcessor`, `globalThis`
+ * and `currentTime`; the first three are shadowed by `new Function`
+ * parameters, and `currentTime` (which the report cadence reads dynamically)
+ * is driven through the real global object.
+ *
+ * Worth executing rather than re-implementing main-side, because the rules
+ * that live in this string live ONLY in this string: silence-through-
+ * underruns (the clock must advance through starvation or the painter
+ * freezes), the pause gate, and the epoch echo that lets main discard reports
+ * from a ring it has already reset.
+ */
+import { describe, it, expect, afterEach } from 'vitest'
+import { audioWorkletSource, RING_PROCESSOR_NAME } from '../audio-worklet-source'
+
+const QUANTUM = 128
+
+interface Report {
+  t: 'consumed'
+  epoch: number
+  samplesConsumed: number
+  underrunFrames: number
+  queuedFrames: number
+}
+
+interface RingProcessor {
+  process(inputs: unknown[], outputs: Float32Array[][]): boolean
+}
+
+interface Harness {
+  /** Name the string registered under, or null if the guard suppressed it. */
+  registeredAs: string | null
+  processor: RingProcessor
+  /** Everything the processor posted back to main, in order. */
+  reports: Report[]
+  /** main → worklet. */
+  send(msg: Record<string, unknown>): void
+  /** Run one render quantum and return the (fresh, zero-filled) output channels. */
+  render(channels?: number): Float32Array[]
+}
+
+function setCurrentTime(seconds: number): void {
+  ;(globalThis as unknown as { currentTime: number }).currentTime = seconds
+}
+
+afterEach(() => {
+  delete (globalThis as unknown as { currentTime?: number }).currentTime
+})
+
+function harness(processorOptions: Record<string, unknown> = {}, scope: Record<string, unknown> = {}): Harness {
+  setCurrentTime(0)
+  const reports: Report[] = []
+  let onmessage: ((ev: { data: unknown }) => void) | null = null
+
+  const port = {
+    set onmessage(fn: ((ev: { data: unknown }) => void) | null) {
+      onmessage = fn
+    },
+    get onmessage() {
+      return onmessage
+    },
+    postMessage(msg: Report) {
+      reports.push(msg)
+    },
+  }
+
+  class FakeAudioWorkletProcessor {
+    port = port
+  }
+
+  let registered: { name: string; cls: new (opts: unknown) => RingProcessor } | null = null
+  const registerProcessor = (name: string, cls: new (opts: unknown) => RingProcessor) => {
+    registered = { name, cls }
+  }
+
+  const load = new Function(
+    'AudioWorkletProcessor',
+    'registerProcessor',
+    'globalThis',
+    audioWorkletSource,
+  ) as (base: unknown, register: unknown, scope: unknown) => void
+  load(FakeAudioWorkletProcessor, registerProcessor, scope)
+
+  const entry = registered as { name: string; cls: new (opts: unknown) => RingProcessor } | null
+  if (!entry) {
+    return {
+      registeredAs: null,
+      processor: { process: () => true },
+      reports,
+      send: () => {},
+      render: () => [],
+    }
+  }
+
+  const processor = new entry.cls({ processorOptions })
+  return {
+    registeredAs: entry.name,
+    processor,
+    reports,
+    send(msg) {
+      onmessage?.({ data: msg })
+    },
+    render(channels = 2) {
+      // The host hands `process` zero-filled output buffers every quantum;
+      // "silence" in this processor means "left untouched".
+      const out = Array.from({ length: channels }, () => new Float32Array(QUANTUM))
+      processor.process([], [out])
+      return out
+    },
+  }
+}
+
+/** Interleaved stereo PCM chunk message with `frames` frames of a constant value per channel. */
+function chunk(frames: number, left: number, right: number) {
+  const pcm = new Float32Array(frames * 2)
+  for (let i = 0; i < frames; i++) {
+    pcm[i * 2] = left
+    pcm[i * 2 + 1] = right
+  }
+  return { t: 'chunk', pcm, channels: 2, frames }
+}
+
+describe('registration', () => {
+  it('registers the processor name audio-clock.ts constructs its node with', () => {
+    expect(harness().registeredAs).toBe(RING_PROCESSOR_NAME)
+    expect(RING_PROCESSOR_NAME).toBe('montaj-engine-pcm-ring')
+  })
+
+  it('does not re-register into a scope that already has it (shared context, second clock)', () => {
+    const scope: Record<string, unknown> = {}
+    expect(harness({}, scope).registeredAs).toBe(RING_PROCESSOR_NAME)
+    // A duplicate registerProcessor throws NotSupportedError and would reject
+    // addModule, dropping a healthy engine onto the wall clock.
+    expect(harness({}, scope).registeredAs).toBe(null)
+  })
+})
+
+describe('pause gate', () => {
+  it('renders silence and does not advance the clock before play', () => {
+    const h = harness()
+    h.send(chunk(QUANTUM, 0.5, -0.5))
+    const out = h.render()
+    expect(Array.from(out[0]).every((v) => v === 0)).toBe(true)
+    setCurrentTime(0.2)
+    h.render()
+    const last = h.reports[h.reports.length - 1]
+    expect(last.samplesConsumed).toBe(0)
+    // The chunk is still queued — pausing does not throw audio away.
+    expect(last.queuedFrames).toBe(QUANTUM)
+  })
+
+  it('stops advancing on pause and resumes from exactly where it stopped', () => {
+    const h = harness()
+    h.send({ t: 'play' })
+    h.send(chunk(QUANTUM * 3, 0.25, 0.25))
+    h.render()
+    h.send({ t: 'pause' })
+    const atPause = h.reports[h.reports.length - 1]
+    expect(atPause.samplesConsumed).toBe(QUANTUM)
+    expect(atPause.queuedFrames).toBe(QUANTUM * 2)
+
+    h.render() // paused: no drain, no advance
+    setCurrentTime(0.5)
+    h.render()
+    expect(h.reports[h.reports.length - 1].samplesConsumed).toBe(QUANTUM)
+
+    h.send({ t: 'play' })
+    const out = h.render()
+    expect(out[0][0]).toBeCloseTo(0.25, 6)
+    setCurrentTime(1)
+    h.render()
+    expect(h.reports[h.reports.length - 1].samplesConsumed).toBe(QUANTUM * 3)
+  })
+
+  it('reports immediately on pause rather than making main wait a full interval', () => {
+    const h = harness()
+    h.send({ t: 'play' })
+    h.render()
+    const before = h.reports.length
+    h.send({ t: 'pause' })
+    expect(h.reports.length).toBe(before + 1)
+  })
+})
+
+describe('ring drain', () => {
+  it('drains interleaved PCM into the output channels in order', () => {
+    const h = harness()
+    h.send({ t: 'play' })
+    h.send(chunk(QUANTUM, 0.5, -0.5))
+    const out = h.render()
+    expect(out[0][0]).toBeCloseTo(0.5, 6)
+    expect(out[1][0]).toBeCloseTo(-0.5, 6)
+    expect(out[0][QUANTUM - 1]).toBeCloseTo(0.5, 6)
+  })
+
+  it('spans chunk boundaries within one render quantum', () => {
+    const h = harness()
+    h.send({ t: 'play' })
+    h.send(chunk(QUANTUM / 2, 1, 1))
+    h.send(chunk(QUANTUM / 2, -1, -1))
+    const out = h.render()
+    expect(out[0][0]).toBeCloseTo(1, 6)
+    expect(out[0][QUANTUM / 2 - 1]).toBeCloseTo(1, 6)
+    expect(out[0][QUANTUM / 2]).toBeCloseTo(-1, 6)
+    expect(out[0][QUANTUM - 1]).toBeCloseTo(-1, 6)
+  })
+
+  it('duplicates the last source channel when a mono clip plays to a stereo output', () => {
+    const h = harness()
+    h.send({ t: 'play' })
+    h.send({ t: 'chunk', pcm: new Float32Array(QUANTUM).fill(0.75), channels: 1, frames: QUANTUM })
+    const out = h.render()
+    expect(out[0][0]).toBeCloseTo(0.75, 6)
+    expect(out[1][0]).toBeCloseTo(0.75, 6)
+  })
+})
+
+describe('silence through underruns', () => {
+  it('renders silence AND keeps the clock advancing when the ring is empty', () => {
+    const h = harness()
+    h.send({ t: 'play' })
+    const out = h.render()
+    expect(Array.from(out[0]).every((v) => v === 0)).toBe(true)
+
+    setCurrentTime(0.2)
+    h.render()
+    const report = h.reports[h.reports.length - 1]
+    // The load-bearing half: a starved ring must NOT stall the clock, or the
+    // canvas painter that follows it freezes on every slow decode tick.
+    expect(report.samplesConsumed).toBe(QUANTUM * 2)
+    expect(report.underrunFrames).toBe(QUANTUM * 2)
+    expect(report.queuedFrames).toBe(0)
+  })
+
+  it('counts only the starved frames, not the rendered ones', () => {
+    const h = harness()
+    h.send({ t: 'play' })
+    h.send(chunk(QUANTUM, 0.5, 0.5))
+    h.render() // fully fed
+    h.render() // starved
+    setCurrentTime(0.2)
+    h.render() // starved
+    const report = h.reports[h.reports.length - 1]
+    expect(report.samplesConsumed).toBe(QUANTUM * 3)
+    expect(report.underrunFrames).toBe(QUANTUM * 2)
+    // samplesConsumed - underrunFrames is what audio-clock.ts treats as the
+    // ring's drained frames; it must equal what was actually enqueued.
+    expect(report.samplesConsumed - report.underrunFrames).toBe(QUANTUM)
+  })
+})
+
+describe('report cadence and epoch', () => {
+  it('reports no more often than the injected interval', () => {
+    const h = harness({ reportIntervalS: 0.1 })
+    h.send({ t: 'play' })
+    h.render()
+    h.render()
+    expect(h.reports.length).toBe(0)
+    setCurrentTime(0.1)
+    h.render()
+    expect(h.reports.length).toBe(1)
+    setCurrentTime(0.15)
+    h.render()
+    expect(h.reports.length).toBe(1)
+    setCurrentTime(0.2)
+    h.render()
+    expect(h.reports.length).toBe(2)
+  })
+
+  it('honors an injected interval rather than a duplicated constant', () => {
+    const h = harness({ reportIntervalS: 0.5 })
+    h.send({ t: 'play' })
+    setCurrentTime(0.2)
+    h.render()
+    expect(h.reports.length).toBe(0)
+    setCurrentTime(0.5)
+    h.render()
+    expect(h.reports.length).toBe(1)
+  })
+
+  it('resets the ring, zeroes the counters and adopts the new epoch immediately', () => {
+    const h = harness()
+    h.send({ t: 'play' })
+    h.send(chunk(QUANTUM * 4, 0.5, 0.5))
+    h.render()
+    setCurrentTime(0.1)
+    h.render()
+    expect(h.reports[h.reports.length - 1].epoch).toBe(0)
+
+    h.send({ t: 'reset', epoch: 7 })
+    const afterReset = h.reports[h.reports.length - 1]
+    expect(afterReset.epoch).toBe(7)
+    expect(afterReset.samplesConsumed).toBe(0)
+    expect(afterReset.underrunFrames).toBe(0)
+    // Stale audio for the position we just left is discarded, not played.
+    expect(afterReset.queuedFrames).toBe(0)
+
+    const out = h.render()
+    expect(Array.from(out[0]).every((v) => v === 0)).toBe(true)
+  })
+
+  it('stamps every later report with the new epoch so main can discard stale ones', () => {
+    const h = harness()
+    h.send({ t: 'play' })
+    h.send({ t: 'reset', epoch: 3 })
+    setCurrentTime(0.2)
+    h.render()
+    expect(h.reports.every((r) => r.epoch === 0 || r.epoch === 3)).toBe(true)
+    expect(h.reports[h.reports.length - 1].epoch).toBe(3)
+  })
+})

package/src/engine/__tests__/batch-planner.test.ts

@@ -0,0 +1,298 @@
+/**
+ * SP4 T3 — the decode planner, which is where three of SP1's five engine
+ * requirements are actually decided. The three tests named by the plan
+ * (`decode-order-feed`, `pipelined-batches`, `min-cts-target`) are `it()`
+ * blocks with exactly those names; the other two (`preroll-epsilon`, and
+ * supersession's `stale frames closed, done always posted`) live in
+ * `decode-worker-source.test.ts`, where they can be run against the shipped
+ * worker string itself.
+ *
+ * Every table here carries a B-frame pattern for the same reason T2's tests
+ * do: on an all-intra table (which is what SP3's proxies are) decode order ==
+ * presentation order, so a correct planner and the broken one that sorts by
+ * cts — or targets `batch[0].tsUs` — produce identical answers. That is
+ * precisely how both bugs survived to SP1's measurement stage
+ * (`spikes/playback-engine/RESULTS.md` §6.1, §7.1).
+ */
+import { describe, it, expect } from 'vitest'
+import { buildPresIndex, type SampleRef, type SampleTable } from '../demux'
+import {
+  DEFAULT_DECODE_AHEAD_FRAMES,
+  MAX_IN_FLIGHT_BATCHES,
+  minBatchFrames,
+  minCtsUs,
+  onFrameBuffered,
+  onFramesConsumed,
+  planNextBatches,
+  planSeek,
+  planStreamStart,
+  reconcileOnBatchDone,
+  type PipelineConfig,
+  type PipelineState,
+} from '../batch-planner'
+
+/** One synthetic sample. Times in µs; 1000µs "frames" keep the tables readable. */
+function s(cts: number, dts: number, isKey = false): SampleRef {
+  return { tsUs: cts, dtsUs: dts, durUs: 1000, isKey, data: new Uint8Array(0) }
+}
+
+function table(samples: SampleRef[]): SampleTable {
+  return { samples, presIndex: buildPresIndex(samples) }
+}
+
+/**
+ * Reordered GOP, decode order: I0 P3 B1 B2 P6 B4 B5 I7 (cts in the comments).
+ * The same fixture shape `demux.test.ts` uses, so both layers are exercised
+ * against one reordering pattern.
+ */
+function bFrameGop(): SampleRef[] {
+  return [
+    s(0, 0, true), //  0: I0
+    s(3000, 1000), //  1: P3
+    s(1000, 2000), //  2: B1
+    s(2000, 3000), //  3: B2
+    s(6000, 4000), //  4: P6
+    s(4000, 5000), //  5: B4
+    s(5000, 6000), //  6: B5
+    s(7000, 7000, true), // 7: I7
+  ]
+}
+
+/** A long all-intra table — the shape of a real SP3 proxy, for the pipeline simulations. */
+function allIntra(n: number): SampleRef[] {
+  return Array.from({ length: n }, (_, i) => s(i * 33333.333, i * 33333.333, true))
+}
+
+const SHIPPED: PipelineConfig = {
+  decodeAheadFrames: DEFAULT_DECODE_AHEAD_FRAMES,
+  maxInFlightBatches: MAX_IN_FLIGHT_BATCHES,
+}
+
+/**
+ * SP1's PRE-fix planner, rebuilt out of the shipped one's config: exactly one
+ * request in flight, and each batch sized to the current shortfall with no
+ * floor. Nothing else differs, so what the `pipelined-batches` test observes
+ * is the scheduling rule and not a different implementation.
+ */
+const DEGENERATE: PipelineConfig = {
+  decodeAheadFrames: DEFAULT_DECODE_AHEAD_FRAMES,
+  maxInFlightBatches: 1,
+  minBatchFrames: 1,
+}
+
+interface SimOptions {
+  ticks: number
+  /** Frames the painter consumes per tick. */
+  paintPerTick: number
+  /** Ticks between a batch being posted and the worker delivering it (decode + flush + round trip). */
+  latency: number
+}
+
+interface SimResult {
+  batchSizes: number[]
+  maxInFlightBatches: number
+  /** Peak `buffered + inFlightFrames` — the budget N is supposed to cap. */
+  maxAlive: number
+  painted: number
+}
+
+/**
+ * Drive the planner the way the real tick does — pump, paint, then absorb
+ * whatever the worker delivered — using the planner's own transition
+ * functions, so the simulation cannot drift from the shipped bookkeeping.
+ */
+function simulate(src: SampleTable, config: PipelineConfig, opts: SimOptions): SimResult {
+  let state: PipelineState = planStreamStart(src, 0)
+  const inFlight: { expected: number; landsAt: number }[] = []
+  const batchSizes: number[] = []
+  let maxInFlightBatches = 0
+  let maxAlive = 0
+  let painted = 0
+
+  for (let t = 0; t < opts.ticks; t++) {
+    const planned = planNextBatches(src, state, config)
+    state = planned.state
+    for (const batch of planned.batches) {
+      batchSizes.push(batch.count)
+      inFlight.push({ expected: batch.count, landsAt: t + opts.latency })
+    }
+    maxInFlightBatches = Math.max(maxInFlightBatches, state.inFlightBatches)
+    maxAlive = Math.max(maxAlive, state.buffered + state.inFlightFrames)
+
+    for (let p = 0; p < opts.paintPerTick && state.buffered > 0; p++) {
+      state = onFramesConsumed(state, 1)
+      painted++
+    }
+
+    while (inFlight.length > 0 && inFlight[0].landsAt <= t) {
+      const batch = inFlight.shift()!
+      for (let k = 0; k < batch.expected; k++) state = onFrameBuffered(state)
+      state = reconcileOnBatchDone(state, batch.expected, batch.expected)
+      maxAlive = Math.max(maxAlive, state.buffered + state.inFlightFrames)
+    }
+  }
+
+  return { batchSizes, maxInFlightBatches, maxAlive, painted }
+}
+
+describe('batch planner — SP1 engine requirements', () => {
+  it('decode-order-feed', () => {
+    const src = table(bFrameGop())
+
+    // A seek slices DECODE indices: enclosing keyframe → the sample displayed
+    // at the target, found by bisecting presIndex (T2), not by scanning cts.
+    const seek = planSeek(src, 2000)!
+    expect(seek.startIdx).toBe(0) // I0, walking back through decode order
+    expect(seek.endIdx).toBe(4) // B2 (cts 2000) sits at decode index 3
+    expect(seek.targetTsUs).toBe(2000)
+
+    const fed = src.samples.slice(seek.startIdx, seek.endIdx)
+    // What actually goes to VideoDecoder: strictly ascending DTS…
+    expect(fed.map((x) => x.dtsUs)).toEqual([0, 1000, 2000, 3000])
+    // …and a cts sequence that is NOT ascending. If this were ever sorted into
+    // presentation order the decoder would throw on the first non-intra frame
+    // and stay dead until respawned (SP1 §7.1).
+    expect(fed.map((x) => x.tsUs)).toEqual([0, 3000, 1000, 2000])
+    expect(fed[0].isKey).toBe(true)
+
+    // Streaming batches tile `samples` contiguously in decode order: no gaps,
+    // no overlaps, no reordering, every sample requested exactly once.
+    const src2 = table(allIntra(97))
+    let state = planStreamStart(src2, 0)
+    const covered: number[] = []
+    for (let round = 0; round < 200 && state.nextSampleIdx < src2.samples.length; round++) {
+      const planned = planNextBatches(src2, state, SHIPPED)
+      for (const batch of planned.batches) {
+        for (let i = batch.startIdx; i < batch.endIdx; i++) covered.push(i)
+      }
+      // Pretend every requested frame arrived and was painted, so the next
+      // round has budget again.
+      state = { ...planned.state, buffered: 0, inFlightFrames: 0, inFlightBatches: 0 }
+    }
+    expect(covered).toEqual(Array.from({ length: 97 }, (_, i) => i))
+  })
+
+  it('min-cts-target', () => {
+    const src = table(bFrameGop())
+
+    // Mid-stream batch (no session pre-roll left): decode indices 1..4 —
+    // P3(3000) B1(1000) B2(2000) P6(6000).
+    const midStream: PipelineState = {
+      nextSampleIdx: 1,
+      buffered: 0,
+      inFlightFrames: 0,
+      inFlightBatches: 0,
+      firstBatchTargetTsUs: 0,
+    }
+    const { batches } = planNextBatches(src, midStream, {
+      decodeAheadFrames: 4,
+      maxInFlightBatches: 1,
+    })
+    expect(batches).toHaveLength(1)
+    const batch = batches[0]
+    expect([batch.startIdx, batch.endIdx]).toEqual([1, 5])
+
+    // The requirement: the target is the MINIMUM cts in the batch.
+    expect(batch.targetTsUs).toBe(1000)
+    expect(minCtsUs(src.samples, 1, 5)).toBe(1000)
+
+    // And the bug it replaces: `batch[0].tsUs` is 3000 in decode order, which
+    // would have made the worker discard two perfectly good frames as false
+    // pre-roll on every mid-stream batch (SP1 §6.1's second, latent bug).
+    const brokenTarget = src.samples[batch.startIdx].tsUs
+    expect(brokenTarget).toBe(3000)
+    const falselyDropped = src.samples
+      .slice(batch.startIdx, batch.endIdx)
+      .filter((x) => x.tsUs < brokenTarget)
+    expect(falselyDropped.map((x) => x.tsUs)).toEqual([1000, 2000])
+
+    // The one legitimate pre-roll — keyframe → the frame actually asked for —
+    // is expressed as the first batch's floor, not as a per-batch guess.
+    const started = planStreamStart(src, 2000)
+    expect(started.nextSampleIdx).toBe(0) // decode from I0
+    expect(started.firstBatchTargetTsUs).toBe(2000) // …but emit nothing before cts 2000
+    const first = planNextBatches(src, started, SHIPPED).batches[0]
+    expect(minCtsUs(src.samples, first.startIdx, first.endIdx)).toBe(0)
+    expect(first.targetTsUs).toBe(2000)
+  })
+
+  it('pipelined-batches', () => {
+    const src = table(allIntra(400))
+    const floor = minBatchFrames(DEFAULT_DECODE_AHEAD_FRAMES)
+    expect(floor).toBe(7) // max(4, N/4) at N=30
+
+    // (a) SP1's pre-fix configuration, reproduced against this same planner:
+    // one request in flight, batch sized to the shortfall. After the initial
+    // fill it asks for ONE frame per batch — and every batch ends in
+    // `decoder.flush()`, which drains the whole decoder pipeline. That is the
+    // measured 4.5fps supply limit (§6.1), not a hypothetical.
+    const degenerate = simulate(src, DEGENERATE, { ticks: 60, paintPerTick: 1, latency: 0 })
+    expect(degenerate.maxInFlightBatches).toBe(1)
+    expect(new Set(degenerate.batchSizes.slice(1))).toEqual(new Set([1]))
+
+    // (b) The shipped configuration on the identical workload: batches floored
+    // so flush cost amortizes over many frames instead of one.
+    const shipped = simulate(src, SHIPPED, { ticks: 60, paintPerTick: 1, latency: 0 })
+    expect(Math.min(...shipped.batchSizes)).toBeGreaterThanOrEqual(floor)
+    expect(shipped.painted).toBe(degenerate.painted) // same workload, so the comparison is like-for-like
+
+    // (c) …and when decode takes longer than one pump interval, the planner
+    // keeps a second batch queued behind the in-flight one rather than
+    // degenerating to a single request the worker has to wait on.
+    const pipelined = simulate(src, SHIPPED, { ticks: 60, paintPerTick: 4, latency: 2 })
+    expect(pipelined.maxInFlightBatches).toBe(MAX_IN_FLIGHT_BATCHES)
+    expect(Math.min(...pipelined.batchSizes)).toBeGreaterThanOrEqual(floor)
+
+    // (d) The budget invariant that must survive all of the above: N still
+    // means "at most N frames alive at once" (SP1 §8's memory sweep rests on
+    // it), in every configuration.
+    for (const run of [degenerate, shipped, pipelined]) {
+      expect(run.maxAlive).toBeLessThanOrEqual(DEFAULT_DECODE_AHEAD_FRAMES)
+    }
+  })
+})
+
+describe('batch planner — bookkeeping', () => {
+  it('stops at end of source and never plans past the last sample', () => {
+    const src = table(allIntra(5))
+    const { batches, state } = planNextBatches(src, planStreamStart(src, 0), SHIPPED)
+    expect(batches).toEqual([{ startIdx: 0, endIdx: 5, count: 5, targetTsUs: 0 }])
+    expect(planNextBatches(src, state, SHIPPED).batches).toEqual([])
+  })
+
+  it('lets a starving pipeline through the batch floor rather than stalling', () => {
+    const src = table(allIntra(100))
+    // Nothing buffered, nothing coming, but only 3 frames of budget: a batch
+    // below the floor still beats painting nothing.
+    const starving: PipelineState = {
+      nextSampleIdx: 10,
+      buffered: 0,
+      inFlightFrames: 0,
+      inFlightBatches: 0,
+      firstBatchTargetTsUs: 0,
+    }
+    const { batches } = planNextBatches(src, starving, { decodeAheadFrames: 3, maxInFlightBatches: 2 })
+    expect(batches.map((b) => b.count)).toEqual([3])
+  })
+
+  it('reconciles inFlightFrames against what a batch actually decoded', () => {
+    // A 10-frame batch whose first 4 were pre-roll: only 6 frames will ever
+    // arrive, so the per-frame decrement under-counts by 4. Without
+    // reconciliation that 4 is lost decode-ahead capacity, permanently.
+    let state: PipelineState = {
+      nextSampleIdx: 10,
+      buffered: 0,
+      inFlightFrames: 10,
+      inFlightBatches: 1,
+      firstBatchTargetTsUs: 0,
+    }
+    for (let i = 0; i < 6; i++) state = onFrameBuffered(state)
+    expect(state).toMatchObject({ buffered: 6, inFlightFrames: 4 })
+    state = reconcileOnBatchDone(state, 10, 6)
+    expect(state).toMatchObject({ buffered: 6, inFlightFrames: 0, inFlightBatches: 0 })
+  })
+
+  it('planSeek returns null for an empty table', () => {
+    expect(planSeek(table([]), 0)).toBeNull()
+  })
+})