@bycrux/editor 0.12.0 → 1.0.1

package/src/video/preview/__tests__/useVideoPlayback.corpus.test.ts

@@ -0,0 +1,313 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { renderHook } from '@testing-library/react'
+import { containsTime, resolveAt, sourceWindow } from '@bycrux/timeline-core'
+import { useVideoPlayback } from '../useVideoPlayback'
+import { engineSrcFor } from '../../../engine/scheduler'
+import { withItemTracks } from '../../timeline/timeline-model'
+import type { EditorProject, VisualItem } from '../../../schema'
+
+// The fixture is imported by RELATIVE path, not as `@bycrux/timeline-core/fixtures/…`:
+// the package's `exports` map declares only the `"."` entry, so subpath imports are
+// not part of its public API and T6 does not get to widen it. Everything else in this
+// file goes through the package's real barrel.
+import negativeStart from '../../../../../timeline-core/fixtures/negative-start.json'
+// SP3: T4's proxySrc-tier fixture — four tracks[0] clips spanning every
+// combination of {proxySrc, nobg_preview_src} presence (proxy-00 neither,
+// proxy-01 proxySrc only, proxy-10 nobg_preview_src only, proxy-11 both, where
+// nobg wins). Its resolver golden lives at
+// timeline-core/expected/proxy-matrix.json and is exercised end-to-end by
+// timeline-core's own corpus.test.mjs; what's checked HERE is the same parity
+// contract as negative-start above — that the editor hook's derived `clips`
+// collection agrees with `resolveAt`/`sourceWindow` — now covering the new tier.
+import proxyMatrix from '../../../../../timeline-core/fixtures/proxy-matrix.json'
+import proxyMatrixExpected from '../../../../../timeline-core/expected/proxy-matrix.json'
+
+// ── Corpus parity: useVideoPlayback's derived collections vs. the resolver ────
+//
+// `useVideoPlayback` does not expose a Scene. It exposes the editor's own
+// PARTITION of the timeline — `clips` (tracks[0] videos, sorted by start),
+// `tracks0NonVideo` (everything else on tracks[0]) and `overlayTracks`
+// (tracks[1..]) — and each consumer applies the activation predicate itself.
+// This test reassembles those three collections back into a flat, ordered scene
+// and asserts it is exactly what `resolveAt(project, t, {variant: 'preview'})`
+// reports: same items, same track indices, same kinds, same source windows.
+//
+// `negative-start.json` is the corpus's "background reel anchored before the
+// origin" case: a tracks[0] video over [0, 6) with a tracks[1] JSX overlay over
+// [-0.5, 5.5). It exercises the partition (a clip AND an overlay track), the
+// half-open predicate at both ends, and a negative `start` — while keeping ONE
+// item per track, so the same-trackIdx tie-order divergence (D7 in
+// KNOWN-DIVERGENCES.md) can't muddy the comparison.
+const project = negativeStart as unknown as EditorProject
+
+// -0.25 → overlay only (before the clip starts, after the overlay does)
+//  2.00 → both on screen
+//  5.75 → clip only (the overlay ended at 5.5; the clip runs to 6)
+const TIMESTAMPS = [-0.25, 2.0, 5.75]
+
+interface FlatItem {
+  id: string
+  trackIdx: number
+  kind: string
+}
+
+/**
+ * Reassemble the editor's three derived collections into the resolver's flat,
+ * back-to-front scene: track 0 first, then each overlay track in order. Track
+ * indices are absolute (overlayTracks[0] is project track 1) because that is
+ * what `ResolvedItem.trackIdx` reports.
+ */
+function editorSceneAt(
+  derived: {
+    clips: VisualItem[]
+    tracks0NonVideo: VisualItem[]
+    overlayTracks: VisualItem[][]
+  },
+  t: number,
+): FlatItem[] {
+  const flat: FlatItem[] = []
+  const push = (items: VisualItem[], trackIdx: number) => {
+    for (const item of items) {
+      if (containsTime(item.start, item.end, t)) flat.push({ id: item.id, trackIdx, kind: item.type })
+    }
+  }
+  push(derived.clips, 0)
+  push(derived.tracks0NonVideo, 0)
+  derived.overlayTracks.forEach((items, i) => push(items, i + 1))
+  return flat.sort((a, b) => a.trackIdx - b.trackIdx)
+}
+
+// `proj` defaults to the negative-start fixture so every existing call site
+// below is unchanged; the proxy-matrix block passes its own project explicitly.
+function resolverSceneAt(t: number, proj: EditorProject = project): FlatItem[] {
+  return resolveAt(withItemTracks(proj), t, { variant: 'preview' }).items.map((r) => ({
+    id: r.item.id as string,
+    trackIdx: r.trackIdx,
+    kind: r.kind,
+  }))
+}
+
+// Testing Library auto-cleans between tests, so the hook is mounted fresh per
+// case at the timestamp under test rather than reused and re-rendered.
+function derivedAt(t: number, proj: EditorProject = project) {
+  return renderHook(() => useVideoPlayback(proj, t, () => {}, (p) => p)).result.current
+}
+
+describe('useVideoPlayback derived collections vs. resolveAt (negative-start corpus fixture)', () => {
+  it.each(TIMESTAMPS)('agrees on what is on screen at t=%s', (t) => {
+    const { clips, tracks0NonVideo, overlayTracks } = derivedAt(t)
+    expect(editorSceneAt({ clips, tracks0NonVideo, overlayTracks }, t)).toEqual(resolverSceneAt(t))
+  })
+
+  it('splits the fixture the way the resolver labels it', () => {
+    const { clips, tracks0NonVideo, overlayTracks } = derivedAt(TIMESTAMPS[1])
+    expect(clips.map((c) => c.id)).toEqual(['mainClip'])
+    expect(tracks0NonVideo).toEqual([])
+    expect(overlayTracks.map((tr) => tr.map((i) => i.id))).toEqual([['bgReel']])
+  })
+
+  it.each(TIMESTAMPS)('seeks the active clip where the resolver says, at t=%s', (t) => {
+    const { clips } = derivedAt(t)
+    const scene = resolveAt(withItemTracks(project), t, { variant: 'preview' })
+    const videos = scene.items.filter((r) => r.kind === 'video')
+    // t=-0.25 is before the only clip starts — assert that, so a fixture change
+    // that silently empties this loop can't turn the case into a no-op.
+    expect(videos.length).toBe(t < 0 ? 0 : 1)
+    for (const resolved of videos) {
+      const clip = clips.find((c) => c.id === resolved.item.id)!
+      // What the hook assigns to `video.currentTime` for this clip at this
+      // instant (useVideoPlayback's scrub branch), against ResolvedItem.seek.
+      const inPoint = sourceWindow(clip, 'preview').inPoint
+      expect(Math.max(inPoint, inPoint + (t - clip.start))).toBeCloseTo(resolved.seek, 10)
+      expect(resolved.window).toEqual(sourceWindow(clip, 'preview'))
+    }
+  })
+
+  it('reports an empty scene past the end of every item (no last-clip fallback)', () => {
+    // The resolver has no fallback; PreviewPlayer's `?? clips[clips.length - 1]`
+    // is editor-side presentation and lives there, not here.
+    expect(resolverSceneAt(6.5)).toEqual([])
+  })
+})
+
+// ── Corpus parity: same contract, proxy-matrix fixture (SP3) ──────────────────
+//
+// proxy-matrix.json is four tracks[0] clips, one per combination of
+// {proxySrc, nobg_preview_src}: proxy-00 has neither (falls through to
+// normalizedSrc), proxy-01 has proxySrc only, proxy-10 has nobg_preview_src
+// only, proxy-11 has both (nobg wins — see chooseSrcRaw in
+// timeline-core/src/source-window.js). No overlay tracks, so this fixture
+// complements negative-start rather than replacing it: it exercises the new
+// tier through the SAME `clips` → `sourceWindow` path production code uses,
+// while negative-start keeps covering the partition/overlay-track side.
+const proxyMatrixProject = proxyMatrix as unknown as EditorProject
+
+interface ProxyMatrixGolden {
+  sourceWindow: Record<string, { preview: unknown; render: unknown }>
+}
+const proxyMatrixGolden = proxyMatrixExpected as unknown as ProxyMatrixGolden
+
+// One timestamp per clip (each clip spans 2s: [0,2), [2,4), [4,6), [6,8)),
+// matching timeline-core/expected/proxy-matrix.json's resolveAt.preview.
+const TIMESTAMPS_PROXY = [0, 2, 4, 6]
+
+describe('useVideoPlayback derived collections vs. resolveAt (proxy-matrix corpus fixture)', () => {
+  it.each(TIMESTAMPS_PROXY)('agrees on what is on screen at t=%s', (t) => {
+    const { clips, tracks0NonVideo, overlayTracks } = derivedAt(t, proxyMatrixProject)
+    expect(editorSceneAt({ clips, tracks0NonVideo, overlayTracks }, t)).toEqual(resolverSceneAt(t, proxyMatrixProject))
+  })
+
+  it('splits the fixture the way the resolver labels it (four clips, no overlay tracks)', () => {
+    const { clips, tracks0NonVideo, overlayTracks } = derivedAt(TIMESTAMPS_PROXY[0], proxyMatrixProject)
+    expect(clips.map((c) => c.id)).toEqual(['proxy-00', 'proxy-01', 'proxy-10', 'proxy-11'])
+    expect(tracks0NonVideo).toEqual([])
+    expect(overlayTracks).toEqual([])
+  })
+
+  it.each(TIMESTAMPS_PROXY)('seeks the active clip where the resolver says, at t=%s', (t) => {
+    const { clips } = derivedAt(t, proxyMatrixProject)
+    const scene = resolveAt(withItemTracks(proxyMatrixProject), t, { variant: 'preview' })
+    const videos = scene.items.filter((r) => r.kind === 'video')
+    // Every fixture timestamp lands inside exactly one clip's [start, end) —
+    // assert that so a fixture edit that empties this loop can't go unnoticed.
+    expect(videos.length).toBe(1)
+    for (const resolved of videos) {
+      const clip = clips.find((c) => c.id === resolved.item.id)!
+      const inPoint = sourceWindow(clip, 'preview').inPoint
+      expect(Math.max(inPoint, inPoint + (t - clip.start))).toBeCloseTo(resolved.seek, 10)
+      expect(resolved.window).toEqual(sourceWindow(clip, 'preview'))
+    }
+  })
+
+  it('resolves the proxySrc/nobg_preview_src tier per clip the same way the resolver golden does', () => {
+    // Direct tier-selection check, independent of any timestamp: each clip's
+    // `sourceWindow(clip, 'preview').src` — reached through `clips`, the same
+    // collection `playbackSrcFor` consumes in useVideoPlayback.ts — must match
+    // the committed golden. This is what actually pins proxy-01 to its
+    // proxySrc and proxy-11 to nobg_preview_src (proxy over it) rather than
+    // just "some src or other".
+    const { clips } = derivedAt(TIMESTAMPS_PROXY[0], proxyMatrixProject)
+    expect(clips).toHaveLength(4)
+    for (const clip of clips) {
+      expect(sourceWindow(clip, 'preview')).toEqual(proxyMatrixGolden.sourceWindow[clip.id].preview)
+    }
+  })
+
+  // ── SP4 T6: the ENGINE path reads the same window ──────────────────────────
+  //
+  // The engine cannot open every src the preview chain can — the masters are
+  // 4K 10-bit HEVC and `nobg_preview_src` is VP9 WebM, while its demuxer is
+  // MP4-only and its decoder is configured for AV1 — so `engineSrcFor` narrows
+  // the chain's answer down to "the proxy, or nothing". What must NOT differ is
+  // the INPUT: both paths ask `sourceWindow(clip, 'preview')`, one shared
+  // resolver call, never a second copy of the precedence chain. This asserts
+  // that at the pure level, per clip, over the same corpus fixture:
+  //
+  //   • whenever the engine accepts a clip, the src it accepts is bit-identical
+  //     to the src the legacy player would load (the golden's `.src`);
+  //   • whenever it declines, it declines because the SHARED window chose
+  //     something other than the proxy — never because it disagreed about what
+  //     the window is.
+  //
+  // proxy-11 is the case that matters: `nobg_preview_src` outranks the proxy in
+  // the chain, so the legacy player loads the alpha preview and the engine must
+  // decline rather than quietly decode the proxy (which still has the
+  // background the user just removed in it).
+  it('selects the engine-path src from the same sourceWindow results as the legacy path', () => {
+    const { clips } = derivedAt(TIMESTAMPS_PROXY[0], proxyMatrixProject)
+    const verdicts: Record<string, { src: string; blocked?: string }> = {}
+    for (const clip of clips) {
+      const golden = proxyMatrixGolden.sourceWindow[clip.id].preview as { src: string }
+      const window = sourceWindow(clip, 'preview')
+      // Same input as the legacy path, and as the committed golden.
+      expect(window.src).toBe(golden.src)
+      const verdict = engineSrcFor(clip, window)
+      // Accepted ⇒ identical to what legacy would load. Declined ⇒ empty.
+      expect(verdict.src === '' || verdict.src === golden.src).toBe(true)
+      verdicts[clip.id] = verdict
+    }
+    expect(verdicts).toEqual({
+      'proxy-00': { src: '', blocked: 'no editing proxy yet' },
+      'proxy-01': { src: (proxyMatrixGolden.sourceWindow['proxy-01'].preview as { src: string }).src },
+      'proxy-10': { src: '', blocked: 'no editing proxy yet' },
+      'proxy-11': { src: '', blocked: 'a higher-precedence preview source the engine cannot decode' },
+    })
+  })
+})
+
+// ── Reload effect: the clip-identity memo key must include proxySrc ───────────
+//
+// useVideoPlayback.ts:522-536 tracks clip identity (nobg_preview_src|proxySrc|
+// src|inPoint|outPoint per clip) in a ref, and only reloads the active <video>
+// element when that string changes — otherwise overlay-only edits would tear
+// down and restart playback on every keystroke. SP3's proxySrc arrives via SSE
+// mid-session: the proxy step finishes AFTER the project is already loaded and
+// playing, so the field appears on a clip whose src the <video> element already
+// has loaded. Without proxySrc in the identity string, that arrival is
+// invisible to the effect and the preview never picks up the proxy.
+//
+// Fixtures can't exercise this — it's about the SAME logical clip gaining a
+// field BETWEEN renders — so this uses renderHook's own rerender with two
+// hand-built projects instead of a corpus fixture. And because this file is
+// `.ts`, not `.tsx`, there's no JSX to mount a real `<video ref={...}>`
+// through the render tree; the ref is attached directly to a detached
+// `<video>` element after the first render instead. That's a legitimate way to
+// drive this specific effect: it only ever reads `video0Ref.current` /
+// `video1Ref.current`, never the DOM position of the element.
+describe('useVideoPlayback reload effect — proxySrc identity (SP3 mid-session arrival)', () => {
+  // jsdom doesn't implement HTMLMediaElement.pause — the identity effect calls
+  // it on the inactive slot as part of a load. Stub it so the test exercises
+  // the effect without jsdom's "not implemented" console noise (same pattern
+  // as captionPositioning.test.tsx / VideoEditor.test.tsx, minus `play` and
+  // `AudioContext`: this test never calls play() or wires audio).
+  const pauseSpy = vi.spyOn(HTMLMediaElement.prototype, 'pause').mockImplementation(() => {})
+  afterEach(() => { pauseSpy.mockClear() })
+
+  const baseClip = { id: 'c1', type: 'video' as const, start: 0, end: 10, inPoint: 0, outPoint: 10, src: '/corpus/orig.mp4' }
+  const projectWith = (clip: VisualItem): EditorProject => ({
+    id: 'reload-test',
+    status: 'draft',
+    settings: { resolution: [1080, 1920] },
+    tracks: [{ id: 'trk-0', items: [clip] }],
+  })
+
+  it('reloads only when proxySrc actually changes, not on every re-render', () => {
+    const { result, rerender } = renderHook(
+      ({ project }: { project: EditorProject }) => useVideoPlayback(project, 0, () => {}, (p) => p),
+      { initialProps: { project: projectWith({ ...baseClip }) } },
+    )
+
+    const active   = document.createElement('video')
+    const inactive = document.createElement('video')
+    result.current.video0Ref.current = active
+    result.current.video1Ref.current = inactive
+
+    // Step 1 — warm-up load: the initial mount ran with video0Ref still null
+    // (attached above, after render), so its effect early-returned without
+    // recording an identity. This rerender is the first one the effect can
+    // actually act on; it must load the clip's src into the active slot.
+    inactive.setAttribute('src', 'sentinel')
+    rerender({ project: projectWith({ ...baseClip }) })
+    expect(active.src).toContain('/corpus/orig.mp4')
+    expect(inactive.hasAttribute('src')).toBe(false) // cleared as part of the load
+
+    // Step 2 — control: a brand-new project/clip object with IDENTICAL fields
+    // (same src, same in/outPoint, still no proxySrc) must produce the SAME
+    // identity string and skip the reload entirely. Re-arm the sentinel and
+    // confirm it survives untouched — proving the effect body did not run.
+    inactive.setAttribute('src', 'sentinel')
+    rerender({ project: projectWith({ ...baseClip }) })
+    expect(inactive.getAttribute('src')).toBe('sentinel')
+
+    // Step 3 — the fix under test: proxySrc appears on the SAME clip (id,
+    // src, in/outPoint all unchanged) — exactly what an SSE proxy-ready event
+    // looks like against an already-loaded project. This must be recognized
+    // as an identity change: the sentinel gets cleared again (the effect body
+    // ran) and the active slot reloads onto the proxy path. Without proxySrc
+    // in the identity string this step is indistinguishable from step 2 — the
+    // sentinel would survive and `active.src` would stay on the original file.
+    rerender({ project: projectWith({ ...baseClip, proxySrc: '/corpus/proxy.mp4' }) })
+    expect(inactive.hasAttribute('src')).toBe(false)
+    expect(active.src).toContain('/corpus/proxy.mp4')
+  })
+})

package/src/video/preview/__tests__/useVideoPlayback.test.ts

@@ -1,11 +1,20 @@
 import { describe, it, expect } from 'vitest'
+import { sourceWindow } from '@bycrux/timeline-core'
 import { effectiveInPoint, effectiveOutPoint } from '../useVideoPlayback'
 
-// These helpers mirror render's collectAllItems rebase (render.js): when the
-// preview loads a normalizedSrc window cache (which starts at 0 and covers
-// [inPoint, outPoint] of the original), the effective seek inPoint is 0 and the
-// outPoint is rebased to the window length. nobg_preview_src is the full source
-// and must NOT rebase.
+// `effectiveInPoint` / `effectiveOutPoint` are thin wrappers over
+// @bycrux/timeline-core's `sourceWindow(clip, 'preview')` — the single
+// implementation shared with render's collectAllItems (render.js). When the
+// preview loads a normalizedSrc window cache (which plays from its own 0 and
+// covers [normalizedInPoint, +duration] of the original), the points are
+// rebased by the cache origin. nobg_preview_src is the full source and must NOT
+// rebase.
+//
+// The cases below are unchanged from before the timeline-core rebase and are
+// kept here as the EDITOR's own guard: they pin the numbers the preview seeks
+// to, whatever the wrappers delegate to. The equivalence block at the bottom
+// pins the delegation itself. timeline-core/test/source-window.test.mjs owns the
+// exhaustive matrix (both variants, degenerate items, bad-variant throws).
 
 describe('effectiveInPoint', () => {
   it('rebases to 0 when normalizedSrc is the chosen src (legacy: no normalizedInPoint)', () => {
@@ -42,6 +51,10 @@ describe('effectiveInPoint', () => {
       effectiveInPoint({ inPoint: 6, normalizedInPoint: 5, normalizedSrc: '/cache/window.mp4' }),
     ).toBeCloseTo(1, 5)
   })
+
+  it('does NOT rebase when a full-source proxy outranks the window cache (SP3)', () => {
+    expect(effectiveInPoint({ inPoint: 6, normalizedInPoint: 5, normalizedSrc: '/cache/window.mp4', proxySrc: '/p.mp4' })).toBe(6)
+  })
 })
 
 describe('effectiveOutPoint', () => {
@@ -81,3 +94,23 @@ describe('effectiveOutPoint', () => {
     ).toBeCloseTo(15, 5)
   })
 })
+
+// The wrappers must stay wrappers: if someone reintroduces a local copy of the
+// rebase math here, this block fails the moment the two implementations drift.
+describe('delegation to @bycrux/timeline-core', () => {
+  const CLIPS = [
+    { inPoint: 496.92, src: '/orig.mov' },
+    { inPoint: 496.92, outPoint: 514.92, normalizedSrc: '/cache/window.mp4' },
+    { inPoint: 496.92, outPoint: 514.92, nobg_preview_src: '/nobg.webm', normalizedSrc: '/c.mp4' },
+    { inPoint: 0.9157, outPoint: 16.97, normalizedInPoint: 0, normalizedSrc: '/cache/window.mp4' },
+    { inPoint: 6, outPoint: 20, normalizedInPoint: 5, normalizedSrc: '/cache/window.mp4' },
+    { src: '/orig.mov' },
+    {},
+  ]
+
+  it.each(CLIPS)('matches sourceWindow(clip, "preview") for %j', (clip) => {
+    const w = sourceWindow(clip, 'preview')
+    expect(effectiveInPoint(clip)).toBe(w.inPoint)
+    expect(effectiveOutPoint(clip)).toBe(w.outPoint)
+  })
+})

package/src/video/preview/__tests__/useVideoPlayback.trackAudio.test.ts

@@ -0,0 +1,278 @@
+/**
+ * Track-level volume/mute in the legacy <video> preview.
+ *
+ * Two layers, deliberately:
+ *
+ *   1. `clipGain` — the fold itself, at the only place this hook turns audio
+ *      settings into a number.
+ *   2. The hook, driven through its real effects and handlers, asserting that
+ *      each of the four gain-setting sites actually routes through it. A pure
+ *      helper that nothing calls would pass layer 1 and leave the preview as
+ *      loud as it ever was.
+ *
+ * The GainNode is faked by pre-seeding `__montajGain` on the <video> elements:
+ * production caches the node there (`ensureVideoGain`) precisely so it survives
+ * remounts, and `getVideoGain` reads it without touching an AudioContext — so a
+ * seeded node is the wiring, not a stub around it. jsdom has no Web Audio at
+ * all, which is why the real one can't be used here.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { act, renderHook } from '@testing-library/react'
+import { clipGain, useVideoPlayback } from '../useVideoPlayback'
+import type { EditorProject, VisualItem, VisualTrack } from '../../../schema'
+
+// ── The fold ─────────────────────────────────────────────────────────────────
+
+describe('clipGain', () => {
+  it('multiplies the track fader into the clip volume instead of replacing it', () => {
+    // Replacing would silently throw away per-clip work an editor already did.
+    expect(clipGain({ volume: 0.5 }, { volume: 0.8 })).toBeCloseTo(0.4, 10)
+  })
+
+  it('keeps the RATIO between two differently-set clips on the same track', () => {
+    // The property that makes "multiply" the right rule: pulling the track down
+    // must move every clip on it by the same factor, not flatten them onto one
+    // level. Two clips a 2:1 mix apart stay 2:1 apart.
+    const track: Pick<VisualTrack, 'volume'> = { volume: 0.5 }
+    const loud = clipGain(track, { volume: 0.8 })
+    const quiet = clipGain(track, { volume: 0.4 })
+    expect(loud / quiet).toBeCloseTo(2, 10)
+    expect(loud).toBeCloseTo(0.4, 10)
+    expect(quiet).toBeCloseTo(0.2, 10)
+  })
+
+  it('silences a clip on a muted track whatever its own volume says', () => {
+    expect(clipGain({ muted: true }, { volume: 2 })).toBe(0)
+    expect(clipGain({ muted: true, volume: 1 }, { volume: 1 })).toBe(0)
+  })
+
+  it('keeps a muted clip muted on an unmuted track', () => {
+    // Mute is either/or — the track cannot un-mute a clip.
+    expect(clipGain({ volume: 1 }, { muted: true, volume: 1 })).toBe(0)
+    expect(clipGain(undefined, { muted: true })).toBe(0)
+  })
+
+  it('leaves the clip untouched when the track carries no settings', () => {
+    // The overwhelmingly common case: nothing writes track volume/mute by
+    // default, so every project that predates the feature must sound identical.
+    expect(clipGain({}, { volume: 0.8 })).toBeCloseTo(0.8, 10)
+    expect(clipGain({}, {})).toBe(1)
+    expect(clipGain(undefined, { volume: 0.8 })).toBeCloseTo(0.8, 10)
+    expect(clipGain(undefined, {})).toBe(1)
+  })
+
+  it('carries amplification through both halves (gain above 1.0 is legal)', () => {
+    // GainNode, not video.volume — values > 1 amplify, and the fold must not
+    // clamp them on the way through.
+    expect(clipGain({ volume: 2 }, { volume: 1.5 })).toBeCloseTo(3, 10)
+    expect(clipGain({ volume: 0.5 }, { volume: 2 })).toBeCloseTo(1, 10)
+  })
+})
+
+// ── The four gain-setting sites ──────────────────────────────────────────────
+
+interface FakeGain {
+  gain: { value: number }
+  /**
+   * Every value assigned to `gain.value`, in order.
+   *
+   * The transition sites (a cut, the gap clock) hand the incoming clip to the
+   * OTHER slot and then make that slot active, which re-runs the load-time
+   * effect over the same node. Asserting the final value alone would therefore
+   * pass even if the transition site itself wrote an unfolded number and the
+   * effect quietly corrected it a tick later. Asserting on every write pins the
+   * site under test.
+   */
+  writes: number[]
+}
+
+/** Every distinct value written to a node, rounded past float noise. */
+function distinct(node: FakeGain): number[] {
+  return [...new Set(node.writes.map((v) => Math.round(v * 1e6) / 1e6))]
+}
+
+/** A <video> whose `currentTime` is a real read/write property (jsdom's is not). */
+function fakeVideo(): HTMLVideoElement {
+  const el = document.createElement('video')
+  let t = 0
+  Object.defineProperty(el, 'currentTime', {
+    get: () => t,
+    set: (v: number) => { t = v },
+    configurable: true,
+  })
+  return el
+}
+
+/** Seed the cached GainNode the hook would otherwise build on first play. */
+function attachGain(el: HTMLVideoElement): FakeGain {
+  const writes: number[] = []
+  let value = Number.NaN
+  const node: FakeGain = {
+    gain: {
+      get value() { return value },
+      set value(next: number) { value = next; writes.push(next) },
+    },
+    writes,
+  }
+  ;(el as unknown as { __montajGain: FakeGain }).__montajGain = node
+  return node
+}
+
+const clip = (over: Partial<VisualItem>): VisualItem =>
+  ({ id: 'a', type: 'video', src: '/a.mp4', start: 0, end: 5, inPoint: 0, outPoint: 5, ...over }) as VisualItem
+
+function projectWith(items: VisualItem[], track: Partial<VisualTrack> = {}): EditorProject {
+  return {
+    id: 'track-audio',
+    status: 'draft',
+    settings: { resolution: [1080, 1920] },
+    tracks: [{ id: 'trk-0', items, ...track }],
+  } as EditorProject
+}
+
+/**
+ * Mount the hook, hand it two wired <video> slots, and let the load effect run.
+ *
+ * The mount render sees both refs still null (they are assigned after it), so
+ * nothing has touched a slot yet; the rerender with a fresh project object is
+ * the first pass whose effects can load the active slot and set its gain.
+ */
+function mount(project: EditorProject) {
+  const harness = renderHook(
+    ({ p }: { p: EditorProject }) => useVideoPlayback(p, 0, () => {}, (path) => path),
+    { initialProps: { p: project } },
+  )
+  const v0 = fakeVideo()
+  const v1 = fakeVideo()
+  const g0 = attachGain(v0)
+  const g1 = attachGain(v1)
+  harness.result.current.video0Ref.current = v0
+  harness.result.current.video1Ref.current = v1
+  harness.rerender({ p: { ...project } })
+  return { ...harness, v0, v1, g0, g1 }
+}
+
+describe('useVideoPlayback — the track fold reaches the GainNodes', () => {
+  // jsdom implements neither play nor pause; the load, boundary and gap paths
+  // all call them. Same stubbing pattern as useVideoPlayback.corpus.test.ts.
+  let playSpy: ReturnType<typeof vi.spyOn>
+  let pauseSpy: ReturnType<typeof vi.spyOn>
+  beforeEach(() => {
+    playSpy = vi.spyOn(HTMLMediaElement.prototype, 'play').mockResolvedValue(undefined)
+    pauseSpy = vi.spyOn(HTMLMediaElement.prototype, 'pause').mockImplementation(() => {})
+  })
+  afterEach(() => {
+    playSpy.mockRestore()
+    pauseSpy.mockRestore()
+    vi.restoreAllMocks()
+  })
+
+  it('folds the track fader into the active clip on load', () => {
+    const { g0 } = mount(projectWith([clip({ volume: 0.8 })], { volume: 0.5 }))
+    expect(g0.gain.value).toBeCloseTo(0.4, 10)
+  })
+
+  it('leaves the clip alone when the track carries no settings', () => {
+    const { g0 } = mount(projectWith([clip({ volume: 0.8 })]))
+    expect(g0.gain.value).toBeCloseTo(0.8, 10)
+  })
+
+  it('silences the active clip when the TRACK is muted', () => {
+    const { g0 } = mount(projectWith([clip({ volume: 2 })], { muted: true }))
+    expect(g0.gain.value).toBe(0)
+  })
+
+  it('keeps a clip muted on an unmuted track muted', () => {
+    const { g0 } = mount(projectWith([clip({ muted: true, volume: 1 })], { volume: 1 }))
+    expect(g0.gain.value).toBe(0)
+  })
+
+  it('re-applies the gain when only the TRACK volume changes', () => {
+    // Moving the track fader edits no clip, so this is the only thing that can
+    // make the change audible on a slot that is already loaded and playing.
+    const items = [clip({ volume: 0.8 })]
+    const { rerender, g0 } = mount(projectWith(items, { volume: 0.5 }))
+    expect(g0.gain.value).toBeCloseTo(0.4, 10)
+
+    // Same item objects, new track volume — the load effect's identity string
+    // is unchanged, so nothing reloads; only the gain moves.
+    act(() => { rerender({ p: projectWith(items, { volume: 0.25 }) }) })
+    expect(g0.gain.value).toBeCloseTo(0.2, 10)
+  })
+
+  it('preserves the mix between two clips when the track is pulled down (preload site)', () => {
+    // Clip A is the active slot's gain; clip B's is set by the next-clip
+    // preload inside handleTimeUpdate. Both go through the fold, so the 2:1
+    // ratio the editor set survives the track fader.
+    const a = clip({ id: 'a', volume: 0.8, start: 0, end: 5 })
+    const b = clip({ id: 'b', src: '/b.mp4', volume: 0.4, start: 5, end: 10 })
+    const { result, v0, g0, g1 } = mount(projectWith([a, b], { volume: 0.5 }))
+
+    v0.currentTime = 1 // mid-clip: preload runs, the boundary branch does not
+    act(() => { result.current.handleTimeUpdate() })
+
+    expect(distinct(g0)).toEqual([0.4])
+    expect(distinct(g1)).toEqual([0.2])
+    expect(g0.gain.value / g1.gain.value).toBeCloseTo(2, 10)
+  })
+
+  it('folds the track into the incoming clip at a contiguous cut', () => {
+    const a = clip({ id: 'a', volume: 0.8, start: 0, end: 5, outPoint: 5 })
+    const b = clip({ id: 'b', src: '/b.mp4', volume: 0.4, start: 5, end: 10 })
+    const { result, v0, g1 } = mount(projectWith([a, b], { volume: 0.5 }))
+
+    // First pass preloads slot 1 (asserted above); forget those writes so what
+    // the switch site itself sets is what this case measures.
+    v0.currentTime = 1
+    act(() => { result.current.handleTimeUpdate() })
+    g1.writes.length = 0
+
+    v0.currentTime = 5 // at outPoint, and b starts exactly where a ends
+    act(() => { result.current.handleTimeUpdate() })
+
+    expect(distinct(g1)).toEqual([0.2])
+  })
+
+  it('folds the track into the clip the gap clock lands on', () => {
+    const a = clip({ id: 'a', volume: 0.8, start: 0, end: 2, outPoint: 2 })
+    const b = clip({ id: 'b', src: '/b.mp4', volume: 0.4, start: 3, end: 5 })
+
+    // Drive the gap rAF by hand: collect every scheduled callback, then jump
+    // the wall clock past the gap so the first tick lands on b's start. The
+    // gap branch also sets isPlaying, which starts the boundary-polling pump —
+    // hence a queue rather than a single slot, and `[0]`, which is the gap
+    // tick the handler scheduled synchronously.
+    const scheduled: FrameRequestCallback[] = []
+    vi.spyOn(globalThis, 'requestAnimationFrame').mockImplementation((cb: FrameRequestCallback) => {
+      scheduled.push(cb)
+      return scheduled.length
+    })
+    const nowSpy = vi.spyOn(performance, 'now').mockReturnValue(0)
+
+    const { result, v0, g1 } = mount(projectWith([a, b], { volume: 0.5 }))
+    scheduled.length = 0
+    v0.currentTime = 2 // at a's outPoint, and b starts 1s later — a gap, not a cut
+    act(() => { result.current.handleTimeUpdate() })
+    expect(scheduled.length).toBeGreaterThan(0)
+
+    g1.writes.length = 0 // forget what the preload wrote; the gap site is under test
+    nowSpy.mockReturnValue(10_000)
+    act(() => { scheduled[0](10_000) })
+
+    expect(distinct(g1)).toEqual([0.2])
+  })
+
+  it('silences the incoming clip too when the track is muted', () => {
+    // The transition sites have their own gain assignment; a track mute that
+    // only held for the clip already on screen would leak audio at every cut.
+    const a = clip({ id: 'a', volume: 1, start: 0, end: 5, outPoint: 5 })
+    const b = clip({ id: 'b', src: '/b.mp4', volume: 1, start: 5, end: 10 })
+    const { result, v0, g0, g1 } = mount(projectWith([a, b], { muted: true }))
+
+    v0.currentTime = 1
+    act(() => { result.current.handleTimeUpdate() })
+
+    expect(distinct(g0)).toEqual([0])
+    expect(distinct(g1)).toEqual([0])
+  })
+})