@bycrux/editor 0.11.2 → 1.0.1

package/src/engine/__tests__/engine-recovery.test.ts

@@ -0,0 +1,263 @@
+/**
+ * Phase 2 of the preview-performance work: the two ways a clip used to get
+ * stuck on "Preparing preview…" forever, and the retain window that stops a
+ * scrub across a cut rebuilding what it just left.
+ *
+ * Both stuck states came from the same design gap. `SourceState` reports
+ * `loading` and `failed` into the SAME placeholder as a proxy that has not been
+ * encoded yet — deliberately, because from the user's side they are the same
+ * sentence — but that meant nothing distinguished "still coming" from "never
+ * coming":
+ *
+ *  1. A fetch that never settles left the session `loading` for the lifetime of
+ *     the tab. `BUILD_TIMEOUT_MS` turns it into a `failed` session with a real
+ *     reason.
+ *  2. A `failed` session was kept in the map precisely so `retain` would not
+ *     rebuild it, which made every failure permanent — including the transient
+ *     ones. `MAX_SESSION_RETRIES` with a doubling backoff rebuilds it a bounded
+ *     number of times.
+ *
+ * `demux` is mocked because the point here is session bookkeeping, not
+ * container parsing, and because these tests need to hold a build open
+ * indefinitely — which no real fetch will do on request.
+ */
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
+import type { EditorProject as Project, VisualItem } from '../../schema'
+
+const demuxMock = vi.fn()
+vi.mock('../demux', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../demux')>()
+  return { ...actual, demux: (...args: unknown[]) => demuxMock(...args) }
+})
+
+// The frame server and master clock both want WebCodecs/WebAudio, neither of
+// which jsdom has. Stubbed to the smallest thing `build()` can finish against.
+vi.mock('../frame-server', () => ({
+  createFrameServer: vi.fn(() => ({
+    src: 'stub',
+    video: { samples: [], presIndex: [], firstPresentationTsUs: 0 },
+    decodeAheadFrames: 30,
+    seek: () => ({ reqId: 0, frame: Promise.resolve(null) }),
+    startStream: () => 0,
+    stopStream: () => {},
+    nextFrameFor: () => ({ frame: null, dropped: 0 }),
+    stats: () => ({
+      buffered: 0,
+      inFlightFrames: 0,
+      inFlightBatches: 0,
+      received: 0,
+      dropped: 0,
+      atEndOfSource: false,
+      drained: false,
+      lastError: null,
+    }),
+    dispose: () => {},
+  })),
+}))
+
+function clip(id: string, start: number, end: number, extra: Partial<VisualItem> = {}): VisualItem {
+  return {
+    id,
+    type: 'video',
+    src: `/media/${id}.mov`,
+    proxySrc: `/proxies/${id}_proxy.mp4`,
+    start,
+    end,
+    inPoint: 0,
+    outPoint: end - start,
+    ...extra,
+  }
+}
+
+function project(items: VisualItem[]): Project {
+  return {
+    id: 'p1',
+    status: 'draft',
+    settings: { resolution: [1080, 1920], fps: 30 },
+    tracks: [{ id: 'trk-0', items }],
+  } as unknown as Project
+}
+
+/** A demuxed source shaped just enough for `build()` to reach `ready`. */
+function fakeDemuxed(src: string) {
+  return {
+    src,
+    video: { kind: 'video', samples: [{ tsUs: 0 }], presIndex: [0], firstPresentationTsUs: 0 },
+    audio: null,
+  }
+}
+
+/** Drain the microtask queue so an in-flight `build()` settles. */
+const settle = () => new Promise<void>((r) => setTimeout(r, 0))
+
+let clock = 0
+const nowMs = () => clock
+
+beforeEach(() => {
+  clock = 0
+  demuxMock.mockReset()
+  vi.useRealTimers()
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+async function engineFor(items: VisualItem[]) {
+  const { createEngine } = await import('../index')
+  const errors: string[] = []
+  const engine = createEngine(project(items), {
+    fileUrl: (p) => p,
+    nowMs,
+    onError: (m) => errors.push(m),
+    requestFrame: () => 1,
+    cancelFrame: () => {},
+  })
+  return { engine, errors }
+}
+
+describe('build timeout', () => {
+  it('aborts a build that never settles and reports why', async () => {
+    vi.useFakeTimers()
+    const { BUILD_TIMEOUT_MS } = await import('../index')
+    // A fetch that hangs: the abort signal is the ONLY thing that can end it,
+    // which is why the timeout aborts rather than racing a timer against the
+    // promise (a race would resolve the build while the request stayed open).
+    demuxMock.mockImplementation(
+      (_src: string, _url: unknown, options: { signal?: AbortSignal }) =>
+        new Promise((_resolve, reject) => {
+          options.signal?.addEventListener('abort', () =>
+            reject(new DOMException('The operation was aborted.', 'AbortError')),
+          )
+        }),
+    )
+    const { engine } = await engineFor([clip('a', 0, 4)])
+
+    engine.seek(1)
+    await vi.advanceTimersByTimeAsync(1)
+    expect(engine.status()).toMatchObject({ picture: 'preparing' })
+
+    await vi.advanceTimersByTimeAsync(BUILD_TIMEOUT_MS + 10)
+
+    expect(engine.status().reason).toMatch(/timed out after 20000 ms/)
+    engine.dispose()
+  })
+
+  it('does not fire for a build that finishes normally', async () => {
+    vi.useFakeTimers()
+    const { BUILD_TIMEOUT_MS } = await import('../index')
+    demuxMock.mockImplementation(async (src: string) => fakeDemuxed(src))
+    const { engine, errors } = await engineFor([clip('a', 0, 4)])
+
+    engine.seek(1)
+    await vi.advanceTimersByTimeAsync(1)
+    // Past the deadline: a timer left armed would abort a source that is
+    // already in use.
+    await vi.advanceTimersByTimeAsync(BUILD_TIMEOUT_MS * 2)
+
+    expect(errors).toEqual([])
+    expect(engine.status().reason).toBeUndefined()
+    engine.dispose()
+  })
+})
+
+describe('failed-session retry', () => {
+  it('rebuilds a failed clip after the backoff, and succeeds when the cause clears', async () => {
+    demuxMock
+      .mockRejectedValueOnce(new Error('read: /proxies/a_proxy.mp4 → 503 Service Unavailable'))
+      .mockImplementation(async (src: string) => fakeDemuxed(src))
+    const { engine } = await engineFor([clip('a', 0, 4)])
+
+    engine.seek(1)
+    await settle()
+    expect(engine.status()).toMatchObject({ picture: 'preparing' })
+    expect(engine.status().reason).toMatch(/503 Service Unavailable/)
+    expect(demuxMock).toHaveBeenCalledTimes(1)
+
+    // Inside the backoff: a tick must NOT retry, or the three attempts would be
+    // spent inside a few frames of the rAF loop.
+    engine.seek(1.1)
+    await settle()
+    expect(demuxMock).toHaveBeenCalledTimes(1)
+
+    clock = 1000
+    engine.seek(1.2)
+    await settle()
+
+    expect(demuxMock).toHaveBeenCalledTimes(2)
+    expect(engine.status()).toMatchObject({ picture: 'video' })
+    engine.dispose()
+  })
+
+  it('gives up after MAX_SESSION_RETRIES rather than rebuilding forever', async () => {
+    const { MAX_SESSION_RETRIES } = await import('../index')
+    demuxMock.mockRejectedValue(new Error('corrupt proxy'))
+    const { engine } = await engineFor([clip('a', 0, 4)])
+
+    engine.seek(1)
+    await settle()
+
+    // Walk the clock far past every backoff and keep ticking.
+    for (let i = 0; i < MAX_SESSION_RETRIES + 5; i++) {
+      clock += 60_000
+      engine.seek(1 + i * 0.01)
+      await settle()
+    }
+
+    // One initial build plus exactly MAX_SESSION_RETRIES rebuilds.
+    expect(demuxMock).toHaveBeenCalledTimes(MAX_SESSION_RETRIES + 1)
+    expect(engine.status()).toMatchObject({ picture: 'preparing' })
+    expect(engine.status().reason).toMatch(/corrupt proxy/)
+    engine.dispose()
+  })
+
+  it('a src change resets the retry budget — a new proxy is a new problem', async () => {
+    // A proxy arriving over SSE replaces `proxySrc`; `retain`'s drop loop tears
+    // the session down for the src change, so the new one starts fresh rather
+    // than inheriting an exhausted budget from the file it replaced.
+    const { MAX_SESSION_RETRIES } = await import('../index')
+    demuxMock.mockRejectedValue(new Error('corrupt proxy'))
+    const { engine } = await engineFor([clip('a', 0, 4)])
+
+    engine.seek(1)
+    await settle()
+    for (let i = 0; i < MAX_SESSION_RETRIES + 2; i++) {
+      clock += 60_000
+      engine.seek(1 + i * 0.01)
+      await settle()
+    }
+    const exhausted = demuxMock.mock.calls.length
+
+    demuxMock.mockImplementation(async (src: string) => fakeDemuxed(src))
+    engine.updateProject(project([clip('a', 0, 4, { proxySrc: '/proxies/a_proxy_v2.mp4' })]))
+    engine.seek(1.5)
+    await settle()
+
+    expect(demuxMock.mock.calls.length).toBe(exhausted + 1)
+    expect(engine.status()).toMatchObject({ picture: 'video' })
+    engine.dispose()
+  })
+})
+
+describe('retain window', () => {
+  it('holds the previous clip so a scrub back over a cut does not rebuild it', async () => {
+    demuxMock.mockImplementation(async (src: string) => fakeDemuxed(src))
+    const { engine } = await engineFor([clip('a', 0, 2), clip('b', 2, 4), clip('c', 4, 6)])
+
+    engine.seek(1)
+    await settle()
+    engine.seek(3)
+    await settle()
+    const afterForward = demuxMock.mock.calls.length
+
+    // Back over the cut. 'a' was retained as the clip behind the playhead, so
+    // there is nothing to rebuild — no new demux, and the picture is live
+    // immediately rather than passing through `preparing`.
+    engine.seek(1)
+    await settle()
+
+    expect(demuxMock.mock.calls.length).toBe(afterForward)
+    expect(engine.status()).toMatchObject({ picture: 'video', clipId: 'a' })
+    engine.dispose()
+  })
+})

package/src/engine/__tests__/engine.test.ts

@@ -0,0 +1,326 @@
+/**
+ * SP4 T5 — the facade: the rAF loop, the canvas painter, and the surface T6
+ * builds on.
+ *
+ * The transport itself is covered by `scheduler.test.ts` over fakes; what is
+ * left here is the wiring only `index.ts` owns. A CANVAS project is the vehicle
+ * for the loop tests on purpose: it has no track-0 video, so nothing ever
+ * reaches `loadBytes`/`demux`/WebCodecs and the whole thing runs in jsdom with
+ * a real `EngineSourceHost` rather than a stand-in for one.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import type { EditorProject as Project } from '../../schema'
+import { createCanvasPainter, createEngine, fpsFromPaintTimes, pruneOlderThan } from '../index'
+import type { DrawPlan } from '../scheduler'
+
+/** `Array.prototype.at` is ES2022; this package targets ES2020. */
+const last = <T>(items: readonly T[]): T | undefined => items[items.length - 1]
+
+function canvasProject(overlayEnd = 4): Project {
+  return {
+    id: 'p1',
+    status: 'draft',
+    settings: { resolution: [1080, 1920], fps: 30 },
+    tracks: [
+      { id: 'trk-0', items: [{ id: 'img', type: 'image', src: '/bg.png', start: 0, end: overlayEnd }] },
+      { id: 'trk-1', items: [{ id: 'o', type: 'overlay', src: '/o.jsx', start: 0, end: overlayEnd }] },
+    ],
+  } as Project
+}
+
+/** A hand-pumped rAF, so no test depends on a real frame callback firing. */
+function fakeRaf() {
+  const queue = new Map<number, () => void>()
+  let nextHandle = 1
+  const cancelFrame = vi.fn((handle: number) => {
+    queue.delete(handle)
+  })
+  return {
+    requestFrame: (cb: () => void) => {
+      const handle = nextHandle++
+      queue.set(handle, cb)
+      return handle
+    },
+    cancelFrame,
+    /** Run every callback queued so far (each may enqueue the next). */
+    flush(times = 1) {
+      for (let i = 0; i < times; i++) {
+        const pending = [...queue.values()]
+        queue.clear()
+        for (const cb of pending) cb()
+      }
+    },
+    get pending() {
+      return queue.size
+    },
+  }
+}
+
+describe('createEngine — transport over the rAF loop', () => {
+  it('runs the loop only while playing and stops at the project end', () => {
+    const raf = fakeRaf()
+    let now = 0
+    const times: number[] = []
+    const engine = createEngine(canvasProject(4), {
+      fileUrl: (p) => p,
+      onTime: (t) => times.push(t),
+      requestFrame: raf.requestFrame,
+      cancelFrame: raf.cancelFrame,
+      nowMs: () => now,
+    })
+
+    // Nothing runs until asked to.
+    expect(raf.pending).toBe(0)
+    engine.play()
+    expect(raf.pending).toBe(1)
+
+    now = 1000
+    raf.flush()
+    expect(last(times)).toBeCloseTo(1, 6)
+    expect(engine.status().transport).toBe('playing')
+    expect(raf.pending).toBe(1)
+
+    // Past the ceiling: clamped to it exactly, transport ends, loop stops.
+    now = 5000
+    raf.flush()
+    expect(last(times)).toBe(4)
+    expect(engine.status().transport).toBe('ended')
+    expect(raf.pending).toBe(0)
+
+    engine.dispose()
+  })
+
+  it('pause stops the loop; play restarts it', () => {
+    const raf = fakeRaf()
+    let now = 0
+    const engine = createEngine(canvasProject(10), {
+      fileUrl: (p) => p,
+      requestFrame: raf.requestFrame,
+      cancelFrame: raf.cancelFrame,
+      nowMs: () => now,
+    })
+    engine.play()
+    now = 500
+    raf.flush()
+    engine.pause()
+    expect(raf.cancelFrame).toHaveBeenCalled()
+    expect(engine.status().transport).toBe('paused')
+
+    // The playhead froze where it was, and does not drift while paused.
+    const frozen = engine.clock.now()
+    now = 4000
+    expect(engine.clock.now()).toBe(frozen)
+
+    engine.play()
+    expect(raf.pending).toBe(1)
+    engine.dispose()
+  })
+
+  it('a canvas project runs on the wall clock', () => {
+    const engine = createEngine(canvasProject(4), { fileUrl: (p) => p, nowMs: () => 0 })
+    engine.seek(1)
+    expect(engine.clock.kind).toBe('fallback')
+    expect(engine.clock.now()).toBe(1)
+    expect(engine.status()).toMatchObject({ picture: 'black', clipId: null })
+    engine.dispose()
+  })
+
+  it('seek past the end stops the loop', () => {
+    const raf = fakeRaf()
+    const engine = createEngine(canvasProject(4), {
+      fileUrl: (p) => p,
+      requestFrame: raf.requestFrame,
+      cancelFrame: raf.cancelFrame,
+      nowMs: () => 0,
+    })
+    engine.play()
+    engine.seek(9)
+    expect(engine.status().transport).toBe('ended')
+    expect(raf.cancelFrame).toHaveBeenCalled()
+    engine.dispose()
+  })
+
+  it('dispose is idempotent and stops everything', () => {
+    const raf = fakeRaf()
+    const engine = createEngine(canvasProject(4), {
+      fileUrl: (p) => p,
+      requestFrame: raf.requestFrame,
+      cancelFrame: raf.cancelFrame,
+      nowMs: () => 0,
+    })
+    engine.play()
+    engine.dispose()
+    engine.dispose()
+    expect(raf.pending).toBe(0)
+  })
+})
+
+describe('createEngine — canvas attachment', () => {
+  it('sizes the backing store to the project design canvas', () => {
+    const canvas = document.createElement('canvas')
+    vi.spyOn(canvas, 'getContext').mockReturnValue(null)
+    const engine = createEngine(canvasProject(4), { fileUrl: (p) => p, nowMs: () => 0 })
+    engine.attach(canvas)
+    expect([canvas.width, canvas.height]).toEqual([1080, 1920])
+    engine.dispose()
+  })
+
+  it('re-sizes when the project resolution changes', () => {
+    const canvas = document.createElement('canvas')
+    vi.spyOn(canvas, 'getContext').mockReturnValue(null)
+    const engine = createEngine(canvasProject(4), { fileUrl: (p) => p, nowMs: () => 0 })
+    engine.attach(canvas)
+    const landscape = { ...canvasProject(4), settings: { resolution: [1920, 1080] as [number, number] } }
+    engine.updateProject(landscape as Project)
+    expect([canvas.width, canvas.height]).toEqual([1920, 1080])
+    engine.dispose()
+  })
+
+  it('unbinds cleanly on attach(null)', () => {
+    const canvas = document.createElement('canvas')
+    vi.spyOn(canvas, 'getContext').mockReturnValue(null)
+    const engine = createEngine(canvasProject(4), { fileUrl: (p) => p, nowMs: () => 0 })
+    engine.attach(canvas)
+    expect(() => engine.attach(null)).not.toThrow()
+    engine.dispose()
+  })
+})
+
+describe('createEngine — stats()', () => {
+  it('reports zeroed defaults with no active clip and no paints', () => {
+    const engine = createEngine(canvasProject(4), { fileUrl: (p) => p, nowMs: () => 0 })
+    // A canvas project's picture is always 'black' (no track-0 video), so
+    // there is never a clip clock to derive from — `stats().clock` matches
+    // `engine.clock.kind`.
+    expect(engine.stats()).toEqual({ fps: 0, dropped: 0, buffered: 0, clock: 'fallback' })
+    expect(engine.clock.kind).toBe('fallback')
+    engine.dispose()
+  })
+
+  it('attach(null) leaves stats() safe to call — no dangling painter reference', () => {
+    const canvas = document.createElement('canvas')
+    vi.spyOn(canvas, 'getContext').mockReturnValue(null)
+    const engine = createEngine(canvasProject(4), { fileUrl: (p) => p, nowMs: () => 0 })
+    engine.attach(canvas)
+    engine.attach(null)
+    expect(() => engine.stats()).not.toThrow()
+    engine.dispose()
+  })
+})
+
+// `stats().fps`'s rolling-window math is exercised directly below
+// (`pruneOlderThan`/`fpsFromPaintTimes`) rather than through a canvas and an
+// attached painter: a canvas PROJECT (this file's fixture) never reaches
+// `picture === 'video'`, so nothing here ever calls the wrapped painter's
+// `paint` — that would need a real track-0 clip behind a live decode session,
+// which is `scheduler.test.ts`/`frame-server.test.ts` territory, not this
+// file's.
+
+describe('pruneOlderThan', () => {
+  it('drops everything at or before the cutoff, keeps the rest, in place', () => {
+    const times = [0, 500, 1000, 1500, 1900]
+    pruneOlderThan(times, 2000, 1000) // cutoff = 1000: drop < 1000
+    expect(times).toEqual([1000, 1500, 1900])
+  })
+
+  it('is a no-op when nothing is old enough to drop', () => {
+    const times = [1900, 1950]
+    pruneOlderThan(times, 2000, 1000)
+    expect(times).toEqual([1900, 1950])
+  })
+
+  it('empties the array when everything is older than the window', () => {
+    const times = [0, 100, 200]
+    pruneOlderThan(times, 5000, 1000)
+    expect(times).toEqual([])
+  })
+})
+
+describe('fpsFromPaintTimes', () => {
+  it('is 0 for an empty list', () => {
+    expect(fpsFromPaintTimes([], 1000, 2000)).toBe(0)
+  })
+
+  it('reads 30fps from paints spaced exactly 1000/30 ms apart', () => {
+    // 30 paints over one second (0, 33.3, 66.6, … 966.7), read at t=1000 with
+    // a 2000ms window — the window covers the whole run, so this is exactly
+    // "how many paints in the last second", i.e. fps.
+    const times: number[] = []
+    for (let i = 0; i < 30; i++) times.push((i * 1000) / 30)
+    expect(fpsFromPaintTimes(times, 1000, 2000)).toBeCloseTo(30, 0)
+  })
+
+  it('clamps the span to the window even when the buffer spans longer', () => {
+    // First paint 5s ago, but the window is only 2s — span must clamp to
+    // 2000ms, not the full 5000ms, or a long-lived low-rate buffer would
+    // under-report fps.
+    const times = [0, 4000, 4500, 5000]
+    expect(fpsFromPaintTimes(times, 5000, 2000)).toBeCloseTo((4 / 2000) * 1000, 6)
+  })
+})
+
+describe('createCanvasPainter', () => {
+  interface Recorded {
+    fills: Array<[number, number, number, number]>
+    draws: unknown[][]
+  }
+
+  function stubCanvas(width = 1080, height = 1920): { canvas: HTMLCanvasElement; rec: Recorded } {
+    const canvas = document.createElement('canvas')
+    canvas.width = width
+    canvas.height = height
+    const rec: Recorded = { fills: [], draws: [] }
+    const ctx = {
+      fillStyle: '',
+      fillRect: (...args: [number, number, number, number]) => rec.fills.push(args),
+      drawImage: (...args: unknown[]) => rec.draws.push(args),
+    }
+    vi.spyOn(canvas, 'getContext').mockReturnValue(ctx as unknown as CanvasRenderingContext2D)
+    return { canvas, rec }
+  }
+
+  const plan: DrawPlan = { sx: 10, sy: 20, sw: 30, sh: 40, dx: 1, dy: 2, dw: 3, dh: 4 }
+  const frame = { close() {} } as unknown as VideoFrame
+
+  it('fills black before every paint so letterbox bars never keep a stale edge', () => {
+    const { canvas, rec } = stubCanvas()
+    const painter = createCanvasPainter(canvas)
+    painter.paint(frame, plan)
+    expect(rec.fills).toEqual([[0, 0, 1080, 1920]])
+    expect(rec.draws).toEqual([[frame, 10, 20, 30, 40, 1, 2, 3, 4]])
+  })
+
+  it('clears to black without drawing', () => {
+    const { canvas, rec } = stubCanvas()
+    createCanvasPainter(canvas).clear()
+    expect(rec.fills).toEqual([[0, 0, 1080, 1920]])
+    expect(rec.draws).toEqual([])
+  })
+
+  it('skips a degenerate rect rather than throwing at drawImage', () => {
+    const { canvas, rec } = stubCanvas()
+    createCanvasPainter(canvas).paint(frame, { ...plan, sw: 0 })
+    expect(rec.draws).toEqual([])
+  })
+
+  it('re-reads the backing-store size on every paint, so a host resize is picked up', () => {
+    const { canvas, rec } = stubCanvas()
+    const painter = createCanvasPainter(canvas)
+    expect(painter.size()).toEqual({ width: 1080, height: 1920 })
+    canvas.width = 540
+    canvas.height = 960
+    expect(painter.size()).toEqual({ width: 540, height: 960 })
+    painter.clear()
+    expect(last(rec.fills)).toEqual([0, 0, 540, 960])
+  })
+
+  it('is inert when the canvas gives no 2D context', () => {
+    const canvas = document.createElement('canvas')
+    vi.spyOn(canvas, 'getContext').mockReturnValue(null)
+    const painter = createCanvasPainter(canvas)
+    expect(() => {
+      painter.clear()
+      painter.paint(frame, plan)
+    }).not.toThrow()
+  })
+})