@bycrux/editor 0.12.0 → 1.0.1

package/src/video/__tests__/keymap.test.tsx

@@ -0,0 +1,171 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { render, cleanup, fireEvent } from '@testing-library/react'
+import {
+  useKeymap,
+  matchesKey,
+  matchesUndo,
+  matchesRedo,
+  matchesModKey,
+  matchesPlainKey,
+  matchesDelete,
+  matchesShiftDelete,
+  isTypingTarget,
+  type KeyBinding,
+} from '../keymap'
+
+afterEach(() => cleanup())
+
+function Harness({ bindings, modalOpen }: { bindings: KeyBinding[]; modalOpen?: boolean }) {
+  useKeymap(bindings, { modalOpen })
+  return (
+    <div>
+      <input data-testid="input" />
+      <textarea data-testid="textarea" />
+      <div data-testid="editable" contentEditable suppressContentEditableWarning>text</div>
+      <div data-testid="plain">plain</div>
+    </div>
+  )
+}
+
+describe('useKeymap — the shared base guard', () => {
+  it('fires on a plain target', () => {
+    const action = vi.fn()
+    const { getByTestId } = render(<Harness bindings={[{ id: 'a', description: 'A', matches: matchesKey('s'), action }]} />)
+    fireEvent.keyDown(getByTestId('plain'), { key: 's' })
+    expect(action).toHaveBeenCalledTimes(1)
+  })
+
+  it('never fires while an INPUT is the target', () => {
+    const action = vi.fn()
+    const { getByTestId } = render(<Harness bindings={[{ id: 'a', description: 'A', matches: matchesKey('s'), action }]} />)
+    fireEvent.keyDown(getByTestId('input'), { key: 's' })
+    expect(action).not.toHaveBeenCalled()
+  })
+
+  it('never fires while a TEXTAREA is the target', () => {
+    const action = vi.fn()
+    const { getByTestId } = render(<Harness bindings={[{ id: 'a', description: 'A', matches: matchesKey('s'), action }]} />)
+    fireEvent.keyDown(getByTestId('textarea'), { key: 's' })
+    expect(action).not.toHaveBeenCalled()
+  })
+
+  it('never fires while a contentEditable host is the target', () => {
+    const action = vi.fn()
+    const { getByTestId } = render(<Harness bindings={[{ id: 'a', description: 'A', matches: matchesKey('s'), action }]} />)
+    const editable = getByTestId('editable')
+    // jsdom doesn't implement `isContentEditable` (it's always `undefined`,
+    // even with the `contenteditable` attribute set) — force it so this
+    // exercises the same guard real browsers hit. See keymap.ts's
+    // `isTypingTarget` doc comment.
+    Object.defineProperty(editable, 'isContentEditable', { value: true, configurable: true })
+    fireEvent.keyDown(editable, { key: 's' })
+    expect(action).not.toHaveBeenCalled()
+  })
+
+  it('never fires while modalOpen is true, even on a plain target', () => {
+    const action = vi.fn()
+    const { getByTestId } = render(
+      <Harness modalOpen bindings={[{ id: 'a', description: 'A', matches: matchesKey('s'), action }]} />,
+    )
+    fireEvent.keyDown(getByTestId('plain'), { key: 's' })
+    expect(action).not.toHaveBeenCalled()
+  })
+
+  it('resumes firing once modalOpen goes back to false', () => {
+    const action = vi.fn()
+    const bindings = [{ id: 'a', description: 'A', matches: matchesKey('s'), action }]
+    const { getByTestId, rerender } = render(<Harness modalOpen bindings={bindings} />)
+    fireEvent.keyDown(getByTestId('plain'), { key: 's' })
+    expect(action).not.toHaveBeenCalled()
+    rerender(<Harness modalOpen={false} bindings={bindings} />)
+    fireEvent.keyDown(getByTestId('plain'), { key: 's' })
+    expect(action).toHaveBeenCalledTimes(1)
+  })
+
+  it('is always ignored for Space — the playback hooks own it, never the keymap', () => {
+    // A deliberately over-broad matcher (would match ANY key) to prove Space
+    // is rejected structurally, before any binding is even consulted.
+    const action = vi.fn()
+    const { getByTestId } = render(
+      <Harness bindings={[{ id: 'catch-all', description: 'catch-all', matches: () => true, action }]} />,
+    )
+    fireEvent.keyDown(getByTestId('plain'), { key: ' ', code: 'Space' })
+    expect(action).not.toHaveBeenCalled()
+    // Sanity: the same catch-all binding DOES fire for an unrelated key,
+    // proving Space specifically (not everything) is what's rejected.
+    fireEvent.keyDown(getByTestId('plain'), { key: 'x' })
+    expect(action).toHaveBeenCalledTimes(1)
+  })
+
+  it('per-binding guard() gates the action independently of the base guard', () => {
+    const action = vi.fn()
+    let allowed = false
+    const { getByTestId } = render(
+      <Harness bindings={[{ id: 'a', description: 'A', matches: matchesKey('s'), guard: () => allowed, action }]} />,
+    )
+    fireEvent.keyDown(getByTestId('plain'), { key: 's' })
+    expect(action).not.toHaveBeenCalled()
+    allowed = true
+    fireEvent.keyDown(getByTestId('plain'), { key: 's' })
+    expect(action).toHaveBeenCalledTimes(1)
+  })
+
+  it('evaluates bindings in order and stops at the first match', () => {
+    const first = vi.fn()
+    const second = vi.fn()
+    const { getByTestId } = render(
+      <Harness
+        bindings={[
+          { id: 'first', description: 'first', matches: matchesKey('s'), action: first },
+          { id: 'second', description: 'second', matches: matchesKey('s'), action: second },
+        ]}
+      />,
+    )
+    fireEvent.keyDown(getByTestId('plain'), { key: 's' })
+    expect(first).toHaveBeenCalledTimes(1)
+    expect(second).not.toHaveBeenCalled()
+  })
+})
+
+describe('isTypingTarget', () => {
+  it('is true for INPUT/TEXTAREA/contentEditable, false otherwise', () => {
+    const input = document.createElement('input')
+    const textarea = document.createElement('textarea')
+    // jsdom doesn't implement `isContentEditable` — force it (see the guard
+    // test above for the same workaround, with the full explanation).
+    const editable = document.createElement('div')
+    Object.defineProperty(editable, 'isContentEditable', { value: true, configurable: true })
+    const plain = document.createElement('div')
+    Object.defineProperty(plain, 'isContentEditable', { value: false, configurable: true })
+    for (const [el, expected] of [[input, true], [textarea, true], [editable, true], [plain, false]] as const) {
+      const ev = { target: el } as unknown as KeyboardEvent
+      expect(isTypingTarget(ev)).toBe(expected)
+    }
+  })
+})
+
+describe('combo matchers', () => {
+  it('matchesUndo requires mod+z without shift; matchesRedo requires mod+shift+z or mod+y', () => {
+    expect(matchesUndo({ metaKey: true, key: 'z', shiftKey: false } as KeyboardEvent)).toBe(true)
+    expect(matchesUndo({ metaKey: true, key: 'z', shiftKey: true } as KeyboardEvent)).toBe(false)
+    expect(matchesUndo({ metaKey: false, key: 'z', shiftKey: false } as KeyboardEvent)).toBe(false)
+
+    expect(matchesRedo({ metaKey: true, key: 'z', shiftKey: true } as KeyboardEvent)).toBe(true)
+    expect(matchesRedo({ metaKey: true, key: 'y', shiftKey: false } as KeyboardEvent)).toBe(true)
+    expect(matchesRedo({ metaKey: true, key: 'z', shiftKey: false } as KeyboardEvent)).toBe(false)
+  })
+
+  it('matchesDelete excludes Shift; matchesShiftDelete requires it', () => {
+    expect(matchesDelete({ key: 'Delete', shiftKey: false } as KeyboardEvent)).toBe(true)
+    expect(matchesDelete({ key: 'Delete', shiftKey: true } as KeyboardEvent)).toBe(false)
+    expect(matchesShiftDelete({ key: 'Backspace', shiftKey: true } as KeyboardEvent)).toBe(true)
+    expect(matchesShiftDelete({ key: 'Backspace', shiftKey: false } as KeyboardEvent)).toBe(false)
+  })
+
+  it('matchesPlainKey excludes mod/alt combos; matchesModKey requires mod', () => {
+    expect(matchesPlainKey('l')({ key: 'l', metaKey: false, ctrlKey: false, altKey: false } as KeyboardEvent)).toBe(true)
+    expect(matchesPlainKey('l')({ key: 'l', metaKey: true, ctrlKey: false, altKey: false } as KeyboardEvent)).toBe(false)
+    expect(matchesModKey('k')({ key: 'k', metaKey: true, ctrlKey: false } as KeyboardEvent)).toBe(true)
+    expect(matchesModKey('k')({ key: 'k', metaKey: false, ctrlKey: false } as KeyboardEvent)).toBe(false)
+  })
+})

package/src/video/__tests__/render-progress.test.tsx

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi, afterEach } from 'vitest'
 import { render, screen, waitFor, act, cleanup } from '@testing-library/react'
 import type { EditorAdapter, ImageElement, Project, RenderStatus } from '../../types'
-import RenderModal, { phaseLabel, phaseIndex, RENDER_PHASES } from '../RenderModal'
+import RenderModal, { phaseLabel, phaseIndex, RENDER_PHASES, stepperPhases } from '../RenderModal'
 
 afterEach(() => {
   cleanup()
@@ -16,18 +16,20 @@ describe('phaseLabel', () => {
     expect(phaseLabel('rendering')).toBe('Rendering graphics')
     expect(phaseLabel('captions')).toBe('Adding captions')
     expect(phaseLabel('encoding')).toBe('Encoding video')
+    expect(phaseLabel('sdr_derive')).toBe('Deriving SDR')
     expect(phaseLabel('saving')).toBe('Saving to your library')
     expect(phaseLabel('done')).toBe('Done')
   })
 })
 
 describe('phaseIndex / RENDER_PHASES', () => {
-  it('orders the phases preparing → done', () => {
+  it('orders the phases preparing → done, with sdr_derive after encoding', () => {
     expect(RENDER_PHASES).toEqual([
       'preparing',
       'rendering',
       'captions',
       'encoding',
+      'sdr_derive',
       'saving',
       'done',
     ])
@@ -38,8 +40,22 @@ describe('phaseIndex / RENDER_PHASES', () => {
     expect(phaseIndex('rendering')).toBe(1)
     expect(phaseIndex('captions')).toBe(2)
     expect(phaseIndex('encoding')).toBe(3)
-    expect(phaseIndex('saving')).toBe(4)
-    expect(phaseIndex('done')).toBe(5)
+    expect(phaseIndex('sdr_derive')).toBe(4)
+    expect(phaseIndex('saving')).toBe(5)
+    expect(phaseIndex('done')).toBe(6)
+  })
+})
+
+describe('stepperPhases', () => {
+  it('hides sdr_derive unless the render actually derives an SDR file', () => {
+    expect(stepperPhases()).not.toContain('sdr_derive')
+    expect(stepperPhases({ export: 'auto' })).not.toContain('sdr_derive')
+    expect(stepperPhases({ export: 'sdr' })).toContain('sdr_derive')
+    expect(stepperPhases({ export: 'both' })).toContain('sdr_derive')
+  })
+
+  it('never lists the terminal done phase', () => {
+    expect(stepperPhases({ export: 'both' })).not.toContain('done')
   })
 })
 

package/src/video/__tests__/shuttle.test.ts

@@ -0,0 +1,210 @@
+import { describe, it, expect, vi } from 'vitest'
+import { nextShuttleRate, createShuttleController } from '../shuttle'
+import { createPlaybackClock } from '../playback-clock'
+
+describe('nextShuttleRate — pure rate-stepping', () => {
+  it('steps the same direction 1x -> 2x -> 4x, capped at 4x', () => {
+    let rate = nextShuttleRate(0, 1)
+    expect(rate).toBe(1)
+    rate = nextShuttleRate(rate, 1)
+    expect(rate).toBe(2)
+    rate = nextShuttleRate(rate, 1)
+    expect(rate).toBe(4)
+    rate = nextShuttleRate(rate, 1) // capped
+    expect(rate).toBe(4)
+  })
+
+  it('mirrors the same stepping backward', () => {
+    let rate = nextShuttleRate(0, -1)
+    expect(rate).toBe(-1)
+    rate = nextShuttleRate(rate, -1)
+    expect(rate).toBe(-2)
+    rate = nextShuttleRate(rate, -1)
+    expect(rate).toBe(-4)
+  })
+
+  it('the opposite direction resets to that direction at 1x', () => {
+    const forward2x = nextShuttleRate(nextShuttleRate(0, 1), 1)
+    expect(forward2x).toBe(2)
+    expect(nextShuttleRate(forward2x, -1)).toBe(-1)
+
+    const backward4x = nextShuttleRate(nextShuttleRate(nextShuttleRate(0, -1), -1), -1)
+    expect(backward4x).toBe(-4)
+    expect(nextShuttleRate(backward4x, 1)).toBe(1)
+  })
+})
+
+describe('createShuttleController', () => {
+  // Deterministic fake rAF: callbacks queue up and only run when the test
+  // pumps them, so the rate-stepping/cancellation contract is tested without
+  // depending on real frame timing.
+  function makeFakeRaf() {
+    let pending: ((ms: number) => void) | null = null
+    return {
+      raf: (cb: (ms: number) => void) => { pending = cb; return 1 },
+      caf: () => { pending = null },
+      pump: (ms: number) => { const cb = pending; pending = null; cb?.(ms) },
+      hasPending: () => pending !== null,
+    }
+  }
+
+  // Model real playback as a flag the play/pause deps flip, so isPlaying()
+  // reflects what the shuttle just did — exactly like the engine transport.
+  function makeDeps(clock: ReturnType<typeof createPlaybackClock>, getDuration = () => 100) {
+    let playing = false
+    const play = vi.fn(() => { playing = true })
+    const pause = vi.fn(() => { playing = false })
+    const setRate = vi.fn<(rate: number) => void>()
+    const fake = makeFakeRaf()
+    return {
+      play, pause, setRate, fake,
+      setPlaying: (v: boolean) => { playing = v },
+      deps: {
+        clock, getDuration,
+        isPlaying: () => playing,
+        play, pause, setRate,
+        raf: fake.raf, caf: fake.caf,
+      },
+    }
+  }
+
+  it('forward from idle: real playback @1x with audio, setRate(1), no seek-loop', () => {
+    const clock = createPlaybackClock(10)
+    const { deps, play, pause, setRate, fake } = makeDeps(clock)
+    const controller = createShuttleController(deps)
+
+    controller.press(1)
+    expect(play).toHaveBeenCalledTimes(1)      // engine transport (audio) started
+    expect(pause).not.toHaveBeenCalled()
+    expect(setRate).toHaveBeenLastCalledWith(1) // 1x re-anchor (harmless no-op)
+    expect(controller.getRate()).toBe(1)
+    expect(fake.hasPending()).toBe(false)      // NOT the silent seek-loop
+    expect(clock.get()).toBe(10)               // the shuttle isn't driving the clock
+  })
+
+  it('repeating forward bumps the engine rate 1x -> 2x -> 4x (audible), never the seek-loop', () => {
+    const clock = createPlaybackClock(0)
+    const { deps, play, setRate, fake } = makeDeps(clock)
+    const controller = createShuttleController(deps)
+
+    controller.press(1)                          // real play @1x
+    controller.press(1)                          // -> 2x, STILL real playback
+    expect(setRate).toHaveBeenLastCalledWith(2)
+    expect(controller.getRate()).toBe(2)
+    expect(fake.hasPending()).toBe(false)        // audible, not a seek-loop
+    expect(play).toHaveBeenCalledTimes(1)        // already playing — not re-started
+
+    controller.press(1)                          // -> 4x
+    expect(setRate).toHaveBeenLastCalledWith(4)
+    expect(controller.getRate()).toBe(4)
+
+    controller.press(1)                          // capped at 4x
+    expect(setRate).toHaveBeenLastCalledWith(4)
+    expect(controller.getRate()).toBe(4)
+  })
+
+  it('forward press while already playing (user-started via Space) does not claim ownership: stop() leaves it running', () => {
+    const clock = createPlaybackClock(0)
+    const { deps, play, pause, setRate, setPlaying } = makeDeps(clock)
+    const controller = createShuttleController(deps)
+
+    setPlaying(true)                             // the user hit Space before shuttling
+    controller.press(1)
+    expect(play).not.toHaveBeenCalled()          // already playing — shuttle didn't start it
+    expect(setRate).toHaveBeenLastCalledWith(1)
+    expect(controller.getRate()).toBe(1)
+
+    controller.stop()                            // K
+    expect(pause).not.toHaveBeenCalled()         // ownership never claimed — user's playback survives
+    expect(setRate).toHaveBeenLastCalledWith(1)  // rate still resets to 1x
+    expect(controller.getRate()).toBe(0)
+  })
+
+  it('reverse is a silent seek-loop: resets the rate, pauses real playback, never plays', () => {
+    const clock = createPlaybackClock(50)
+    const { deps, play, pause, setRate, fake, setPlaying } = makeDeps(clock)
+    const controller = createShuttleController(deps)
+
+    setPlaying(true)                             // e.g. the user hit Space first
+    controller.press(-1)
+    expect(setRate).toHaveBeenLastCalledWith(1)  // no stale forward rate during the scrub
+    expect(pause).toHaveBeenCalledTimes(1)       // real playback muted before scrubbing
+    expect(play).not.toHaveBeenCalled()          // reverse never plays
+    expect(controller.getRate()).toBe(-1)
+    expect(fake.hasPending()).toBe(true)
+  })
+
+  it('resetting from a reverse loop back to forward returns to real playback', () => {
+    const clock = createPlaybackClock(50)
+    const { deps, play, setRate, fake } = makeDeps(clock)
+    const controller = createShuttleController(deps)
+
+    controller.press(-1)                    // reverse loop (rate reset to 1, paused)
+    expect(fake.hasPending()).toBe(true)
+    controller.press(1)                     // opposite dir -> forward -> real play
+    expect(play).toHaveBeenCalledTimes(1)
+    expect(setRate).toHaveBeenLastCalledWith(1)
+    expect(controller.getRate()).toBe(1)
+    expect(fake.hasPending()).toBe(false)   // loop cancelled
+  })
+
+  it('stop() resets the transport rate and pauses shuttle-started real playback', () => {
+    const clock = createPlaybackClock(0)
+    const { deps, pause, setRate } = makeDeps(clock)
+    const controller = createShuttleController(deps)
+    controller.press(1)          // real play @1x (shuttle-started)
+    controller.stop()
+    expect(setRate).toHaveBeenLastCalledWith(1)
+    expect(pause).toHaveBeenCalledTimes(1)
+    expect(controller.getRate()).toBe(0)
+  })
+
+  it('K (stop) zeroes the rate, resets the transport rate and cancels a running seek-loop', () => {
+    const clock = createPlaybackClock(10)
+    const { deps, setRate, fake } = makeDeps(clock)
+    const controller = createShuttleController(deps)
+    controller.press(-1)         // reverse seek-loop
+    expect(fake.hasPending()).toBe(true)
+    controller.stop()
+    expect(setRate).toHaveBeenLastCalledWith(1)
+    expect(controller.getRate()).toBe(0)
+    expect(fake.hasPending()).toBe(false)
+  })
+
+  it('steps the clock down in the reverse seek-loop, clamped at 0', () => {
+    const clock = createPlaybackClock(4)
+    const { deps, fake } = makeDeps(clock, () => 100)
+    const controller = createShuttleController(deps)
+    controller.press(-1)  // -1x reverse seek-loop
+    controller.press(-1)  // -> -2x
+    expect(controller.getRate()).toBe(-2)
+    fake.pump(0)          // establishes the frame baseline, no time delta yet
+    fake.pump(1000)       // -1s at 2x -> clock should be ~2
+    expect(clock.get()).toBeCloseTo(2, 5)
+    fake.pump(3000)       // -2s at 2x would undershoot below 0 -> clamped, loop stops
+    expect(clock.get()).toBe(0)
+    expect(controller.getRate()).toBe(0)
+  })
+
+  it('cancels the seek-loop when an external transport change starts real playback', () => {
+    const clock = createPlaybackClock(0)
+    const { deps, fake, setPlaying } = makeDeps(clock)
+    const controller = createShuttleController(deps)
+    controller.press(-1)   // reverse seek-loop
+    fake.pump(0)
+    setPlaying(true)       // user hit play, outside the shuttle
+    fake.pump(16)
+    expect(controller.getRate()).toBe(0)
+  })
+
+  it('cancels the seek-loop when the clock is moved externally (a seek)', () => {
+    const clock = createPlaybackClock(0)
+    const { deps, fake } = makeDeps(clock)
+    const controller = createShuttleController(deps)
+    controller.press(-1)   // reverse seek-loop
+    fake.pump(0)
+    clock.set(50)         // an external seek, not written by the shuttle itself
+    fake.pump(16)
+    expect(controller.getRate()).toBe(0)
+  })
+})

package/src/video/__tests__/source-preview.test.ts

@@ -0,0 +1,60 @@
+/// <reference types="vitest/globals" />
+/**
+ * The source-preview override store. A sibling of `hover-scrub.ts`: it repaints
+ * the main preview with an OFF-TIMELINE clip's frame on hover and NOTHING else —
+ * it holds a proxy url + a fraction, notifies only on real change, and is inert
+ * for a host that never wires it.
+ */
+import { describe, it, expect, vi } from 'vitest'
+import { createSourcePreviewStore } from '../source-preview'
+
+describe('createSourcePreviewStore', () => {
+  it('starts empty — the main preview follows the timeline', () => {
+    expect(createSourcePreviewStore().get()).toBeNull()
+  })
+
+  it('notifies subscribers when the value changes', () => {
+    const store = createSourcePreviewStore()
+    const sub = vi.fn()
+    store.subscribe(sub)
+
+    store.set({ url: 'a.mp4', fraction: 0.5 })
+    expect(store.get()).toEqual({ url: 'a.mp4', fraction: 0.5 })
+    expect(sub).toHaveBeenCalledTimes(1)
+
+    store.set(null)
+    expect(store.get()).toBeNull()
+    expect(sub).toHaveBeenCalledTimes(2)
+  })
+
+  it('stays silent on a repeat write of the same url+fraction', () => {
+    // The host may re-set the same value on repeated pointer events over one
+    // tile; without the guard that would notify (and repaint) needlessly.
+    const store = createSourcePreviewStore()
+    const sub = vi.fn()
+    store.subscribe(sub)
+
+    store.set(null)
+    expect(sub).not.toHaveBeenCalled()
+
+    store.set({ url: 'a.mp4', fraction: 0.2 })
+    store.set({ url: 'a.mp4', fraction: 0.2 })
+    expect(sub).toHaveBeenCalledTimes(1)
+
+    // A moved fraction (same clip) is a real change.
+    store.set({ url: 'a.mp4', fraction: 0.6 })
+    expect(sub).toHaveBeenCalledTimes(2)
+
+    // A different clip is a real change.
+    store.set({ url: 'b.mp4', fraction: 0.6 })
+    expect(sub).toHaveBeenCalledTimes(3)
+  })
+
+  it('unsubscribes cleanly', () => {
+    const store = createSourcePreviewStore()
+    const sub = vi.fn()
+    store.subscribe(sub)()
+    store.set({ url: 'a.mp4', fraction: 0.1 })
+    expect(sub).not.toHaveBeenCalled()
+  })
+})

package/src/video/__tests__/timecode.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect } from 'vitest'
+import { formatTimecode, parseTimecode } from '../timecode'
+
+describe('parseTimecode', () => {
+  it('parses bare seconds', () => {
+    expect(parseTimecode('90')).toBe(90)
+    expect(parseTimecode('12.5')).toBe(12.5)
+    expect(parseTimecode('0')).toBe(0)
+  })
+
+  it('parses mm:ss', () => {
+    expect(parseTimecode('1:30')).toBe(90)
+    expect(parseTimecode('12:03.5')).toBe(12 * 60 + 3.5)
+  })
+
+  it('parses hh:mm:ss', () => {
+    expect(parseTimecode('01:02:03')).toBe(1 * 3600 + 2 * 60 + 3)
+    expect(parseTimecode('1:02:03.25')).toBe(3600 + 120 + 3.25)
+  })
+
+  it('trims surrounding whitespace', () => {
+    expect(parseTimecode('  1:30  ')).toBe(90)
+  })
+
+  it('rejects out-of-range minutes/seconds', () => {
+    expect(parseTimecode('1:60')).toBeNull()
+    expect(parseTimecode('1:60:00')).toBeNull()
+    expect(parseTimecode('60:00:00')).not.toBeNull() // hours component is unbounded
+  })
+
+  it('rejects garbage', () => {
+    expect(parseTimecode('')).toBeNull()
+    expect(parseTimecode('   ')).toBeNull()
+    expect(parseTimecode('abc')).toBeNull()
+    expect(parseTimecode('1:2:3:4')).toBeNull()
+    expect(parseTimecode('1.5:30')).toBeNull()
+    expect(parseTimecode('-5')).toBeNull()
+    expect(parseTimecode('1:')).toBeNull()
+  })
+})
+
+describe('formatTimecode', () => {
+  it('formats zero', () => {
+    expect(formatTimecode(0)).toBe('0:00.0')
+  })
+
+  it('formats sub-minute values with one decimal', () => {
+    expect(formatTimecode(5.34)).toBe('0:05.3')
+    expect(formatTimecode(59.96)).toBe('1:00.0') // rounds up and carries into minutes
+  })
+
+  it('formats minute-plus values without an hours component', () => {
+    expect(formatTimecode(65)).toBe('1:05.0')
+    expect(formatTimecode(599.9)).toBe('9:59.9')
+  })
+
+  it('formats hour-plus values with an hh:mm:ss.f shape', () => {
+    expect(formatTimecode(3600)).toBe('1:00:00.0')
+    expect(formatTimecode(3725.6)).toBe('1:02:05.6')
+  })
+
+  it('never emits a frames-style trailing group (parseTimecode has no concept of frames)', () => {
+    expect(formatTimecode(3725.6).split(':')).toHaveLength(3) // h:mm:ss.f, not h:mm:ss:ff
+  })
+
+  it('clamps negatives and non-finite input to 0', () => {
+    expect(formatTimecode(-5)).toBe('0:00.0')
+    expect(formatTimecode(NaN)).toBe('0:00.0')
+  })
+
+  it('round-trips through parseTimecode', () => {
+    const values = [0, 0.1, 5.3, 42.7, 65.0, 599.9, 3600, 3661.2, 7325.8]
+    for (const t of values) {
+      expect(parseTimecode(formatTimecode(t))).toBeCloseTo(t, 1)
+    }
+  })
+})

package/src/video/__tests__/use-report-context.test.tsx

@@ -0,0 +1,101 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+
+import { createPlaybackClock } from '../playback-clock'
+import { useReportContext, REPORT_INTERVAL_MS } from '../use-report-context'
+
+beforeEach(() => { vi.useFakeTimers() })
+afterEach(() => { vi.useRealTimers() })
+
+describe('useReportContext', () => {
+  it('does nothing when the adapter omits reportContext', () => {
+    const clock = createPlaybackClock()
+    expect(() =>
+      renderHook(() => useReportContext({
+        adapter: {} as never, projectId: 'p1', clock,
+        selectedIds: [], selectedCaptionId: null,
+      })),
+    ).not.toThrow()
+  })
+
+  it('reports once on mount', () => {
+    const reportContext = vi.fn().mockResolvedValue(undefined)
+    const clock = createPlaybackClock(4)
+    renderHook(() => useReportContext({
+      adapter: { reportContext } as never, projectId: 'p1', clock,
+      selectedIds: [], selectedCaptionId: null,
+    }))
+    expect(reportContext).toHaveBeenCalledWith('p1', {
+      playheadSec: 4, selectedIds: [], selectedCaptionId: null,
+    })
+  })
+
+  it('throttles a 60Hz clock to one report per interval', () => {
+    const reportContext = vi.fn().mockResolvedValue(undefined)
+    const clock = createPlaybackClock()
+    renderHook(() => useReportContext({
+      adapter: { reportContext } as never, projectId: 'p1', clock,
+      selectedIds: [], selectedCaptionId: null,
+    }))
+    reportContext.mockClear()
+
+    act(() => {
+      for (let i = 1; i <= 120; i++) clock.set(i / 60)
+      vi.advanceTimersByTime(REPORT_INTERVAL_MS)
+    })
+    expect(reportContext).toHaveBeenCalledTimes(1)
+    expect(reportContext.mock.calls[0][1].playheadSec).toBeCloseTo(2)
+  })
+
+  it('reports a selection change immediately, without waiting for the interval', () => {
+    const reportContext = vi.fn().mockResolvedValue(undefined)
+    const clock = createPlaybackClock()
+    // Hoisted deliberately. The playhead effect depends on `adapter` by
+    // reference, so an inline object literal would be a new adapter every
+    // render and would re-fire that effect on rerender too — giving 2 calls
+    // and testing object identity instead of the selection path. Real call
+    // sites (EditorPage.tsx, MobileLiveView.tsx, MobileVideoPreview.tsx) all
+    // wrap createMontajAdapter() in useMemo, so a stable adapter is what
+    // production actually does.
+    const adapter = { reportContext } as never
+    const { rerender } = renderHook(
+      (props: { ids: string[] }) => useReportContext({
+        adapter, projectId: 'p1', clock,
+        selectedIds: props.ids, selectedCaptionId: null,
+      }),
+      { initialProps: { ids: [] as string[] } },
+    )
+    reportContext.mockClear()
+    rerender({ ids: ['c3'] })
+    expect(reportContext).toHaveBeenCalledTimes(1)
+    expect(reportContext.mock.calls[0][1].selectedIds).toEqual(['c3'])
+  })
+
+  it('swallows a rejected report — context sync never breaks the editor', async () => {
+    const reportContext = vi.fn().mockRejectedValue(new Error('serve is down'))
+    const clock = createPlaybackClock()
+    expect(() =>
+      renderHook(() => useReportContext({
+        adapter: { reportContext } as never, projectId: 'p1', clock,
+        selectedIds: [], selectedCaptionId: null,
+      })),
+    ).not.toThrow()
+    await act(async () => { await Promise.resolve() })
+  })
+
+  it('stops reporting after unmount', () => {
+    const reportContext = vi.fn().mockResolvedValue(undefined)
+    const clock = createPlaybackClock()
+    const { unmount } = renderHook(() => useReportContext({
+      adapter: { reportContext } as never, projectId: 'p1', clock,
+      selectedIds: [], selectedCaptionId: null,
+    }))
+    unmount()
+    reportContext.mockClear()
+    act(() => {
+      clock.set(9)
+      vi.advanceTimersByTime(REPORT_INTERVAL_MS * 3)
+    })
+    expect(reportContext).not.toHaveBeenCalled()
+  })
+})