@bycrux/editor 1.2.0 → 1.2.2

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

@@ -0,0 +1,239 @@
+/**
+ * Task 4c — the `muted` master override on `PreviewPlayer` (threaded through
+ * as `useVideoPlayback`'s 5th argument). See that prop's doc in
+ * `PreviewPlayer.tsx` for the full "why": moving the pointer across a grid of
+ * project-card hover previews must not play each project's audio in turn.
+ *
+ * Two DISTINCT audio paths this hook owns a GainNode for, both asserted here:
+ *
+ *   1. The video-slot GainNodes (`videoGainRef`, via `applyClipVolume` and the
+ *      three transition sites) — same harness as
+ *      `useVideoPlayback.trackAudio.test.ts` (seeded `__montajGain`, no real
+ *      AudioContext needed).
+ *   2. The background audio-TRACK GainNodes (`gainNodesMap` — music/VO beds,
+ *      `project.audio.tracks`) — a wholly separate `<audio>` element family
+ *      the video-slot mute does nothing for. jsdom has no Web Audio at all, so
+ *      this half stubs `window.__montajSharedCtx` directly (same technique as
+ *      `latencyCompensation.test.tsx`) rather than seeding a cached node.
+ *
+ * Both must go to 0 when `muted` is true, REGARDLESS of what the clip/track's
+ * own volume/mute settings say — this is a master override on top of the
+ * existing fold, not a replacement for it. And the default (`muted` absent)
+ * must be byte-identical to every gain value `trackAudio.test.ts` already
+ * pins — that suite is untouched by this change and stays the proof.
+ */
+import { describe, it, expect, afterEach } from 'vitest'
+import { act, renderHook } from '@testing-library/react'
+import { useVideoPlayback } from '../useVideoPlayback'
+import type { EditorProject, VisualItem } from '../../../schema'
+
+// jsdom implements neither `play()` nor `pause()`. Installed once, at module
+// scope, rather than as a per-test spy: Testing Library's own `afterEach`
+// cleanup unmounts the hook — which, once a test populates
+// `project.audio.tracks`, runs the audio-lane teardown that calls
+// `el.pause()` on every lane element — AFTER a per-test `restoreAllMocks()`
+// would have put the unimplemented originals back (same hazard documented in
+// `latencyCompensation.test.tsx`).
+Object.defineProperty(HTMLMediaElement.prototype, 'paused', {
+  configurable: true,
+  get(this: HTMLMediaElement & { __paused?: boolean }) { return this.__paused !== false },
+})
+HTMLMediaElement.prototype.play = function (this: HTMLMediaElement & { __paused?: boolean }) {
+  this.__paused = false
+  return Promise.resolve()
+}
+HTMLMediaElement.prototype.pause = function (this: HTMLMediaElement & { __paused?: boolean }) {
+  this.__paused = true
+}
+
+// ── Path 1: video-slot GainNodes ────────────────────────────────────────────
+
+interface FakeGain {
+  gain: { value: number }
+  writes: number[]
+}
+
+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
+}
+
+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[]): EditorProject {
+  return {
+    id: 'muted-video',
+    status: 'draft',
+    settings: { resolution: [1080, 1920] },
+    tracks: [{ id: 'trk-0', items }],
+  } as EditorProject
+}
+
+/** Same mount dance as `trackAudio.test.ts`, with `muted` threaded through. */
+function mount(project: EditorProject, muted = false) {
+  const harness = renderHook(
+    ({ p, m }: { p: EditorProject; m: boolean }) => useVideoPlayback(p, 0, () => {}, (path) => path, m),
+    { initialProps: { p: project, m: muted } },
+  )
+  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 }, m: muted })
+  return { ...harness, v0, v1, g0, g1 }
+}
+
+describe('useVideoPlayback — muted overrides the video-slot GainNodes', () => {
+  it('unset — the default path — is byte-identical to the clip volume', () => {
+    const { g0 } = mount(projectWith([clip({ volume: 0.8 })]))
+    expect(g0.gain.value).toBeCloseTo(0.8, 10)
+  })
+
+  it('false — explicitly — is also byte-identical to the clip volume', () => {
+    const { g0 } = mount(projectWith([clip({ volume: 0.8 })]), false)
+    expect(g0.gain.value).toBeCloseTo(0.8, 10)
+  })
+
+  it('zeroes the active slot even though the clip is loud and unmuted', () => {
+    const { g0 } = mount(projectWith([clip({ volume: 2 })]), true)
+    expect(g0.gain.value).toBe(0)
+  })
+
+  it('reaches the live gain node immediately on an external toggle, not just at load', () => {
+    const items = [clip({ volume: 1 })]
+    const { rerender, g0 } = mount(projectWith(items), false)
+    expect(g0.gain.value).toBeCloseTo(1, 10)
+
+    act(() => { rerender({ p: projectWith(items), m: true }) })
+    expect(g0.gain.value).toBe(0)
+
+    // And un-muting brings the clip's own volume straight back — this is an
+    // override on TOP of the fold, not a one-way latch.
+    act(() => { rerender({ p: projectWith(items), m: false }) })
+    expect(g0.gain.value).toBeCloseTo(1, 10)
+  })
+
+  it('zeroes the incoming clip at a contiguous cut too, not just the clip already on screen', () => {
+    // If muted only held for the active slot, every clip switch would un-mute
+    // the preview for one frame.
+    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, g1 } = mount(projectWith([a, b]), true)
+
+    v0.currentTime = 5 // at a's outPoint, b starts exactly where a ends
+    act(() => { result.current.handleTimeUpdate() })
+
+    expect(g1.gain.value).toBe(0)
+  })
+})
+
+// ── Path 2: background audio-track (music/VO bed) GainNodes ────────────────
+//
+// A wholly separate `<audio>` element family — `project.audio.tracks` — with
+// its own GainNode lifecycle (`gainNodesMap`, "Multi-track audio management"
+// in useVideoPlayback.ts). The video-slot fixes above do nothing for this
+// path; it has to be muted independently, which is exactly what a caller
+// mounting a project with a music bed over its clips would otherwise miss.
+
+interface FakeLaneGain {
+  gain: { value: number }
+  connect: () => void
+}
+
+interface StubCtx {
+  state: 'running'
+  outputLatency: number
+  baseLatency: number
+  resume: () => Promise<void>
+  destination: object
+  createMediaElementSource: () => { connect: () => void }
+  createGain: () => FakeLaneGain
+}
+
+function stubSharedCtx(): { gains: FakeLaneGain[] } {
+  const gains: FakeLaneGain[] = []
+  const ctx: StubCtx = {
+    state: 'running',
+    outputLatency: 0,
+    baseLatency: 0,
+    resume: () => Promise.resolve(),
+    destination: {},
+    createMediaElementSource: () => ({ connect: () => {} }),
+    createGain: () => {
+      const node: FakeLaneGain = { gain: { value: 1 }, connect: () => {} }
+      gains.push(node)
+      return node
+    },
+  }
+  ;(window as unknown as { __montajSharedCtx?: StubCtx }).__montajSharedCtx = ctx
+  return { gains }
+}
+
+function clearSharedCtx() {
+  delete (window as unknown as { __montajSharedCtx?: unknown }).__montajSharedCtx
+}
+
+function projectWithMusicBed(): EditorProject {
+  return {
+    id: 'muted-lane',
+    status: 'draft',
+    settings: { resolution: [1080, 1920] },
+    tracks: [],
+    audio: { tracks: [{ id: 'music', src: '/music.mp3', start: 0, end: 5, volume: 1 }] },
+  } as EditorProject
+}
+
+describe('useVideoPlayback — muted overrides background audio-track GainNodes', () => {
+  afterEach(() => {
+    clearSharedCtx()
+  })
+
+  it('unset — the default path — leaves the lane at its own volume', () => {
+    const { gains } = stubSharedCtx()
+    renderHook(() => useVideoPlayback(projectWithMusicBed(), 1, () => {}, (p) => p))
+    expect(gains).toHaveLength(1)
+    expect(gains[0].gain.value).toBe(1)
+  })
+
+  it('zeroes the lane on mount, though the track itself is unmuted at volume 1', () => {
+    const { gains } = stubSharedCtx()
+    renderHook(() => useVideoPlayback(projectWithMusicBed(), 1, () => {}, (p) => p, true))
+    expect(gains).toHaveLength(1)
+    expect(gains[0].gain.value).toBe(0)
+  })
+
+  it('reaches the lane immediately on an external toggle', () => {
+    const { gains } = stubSharedCtx()
+    const { rerender } = renderHook(
+      ({ m }: { m: boolean }) => useVideoPlayback(projectWithMusicBed(), 1, () => {}, (p) => p, m),
+      { initialProps: { m: false } },
+    )
+    expect(gains[0].gain.value).toBe(1)
+
+    act(() => { rerender({ m: true }) })
+    expect(gains[0].gain.value).toBe(0)
+  })
+})

package/src/video/preview/useEnginePlayback.ts

@@ -34,8 +34,16 @@
  *  - **Video-item volume, including >1.0.** The legacy hook routes each
  *    `<video>` slot through a GainNode to get amplification. The engine has no
  *    element to route: `createMasterClock` takes the item's `volume`/`muted`
- *    and scales the PCM at ring-enqueue time (T4), reached from
- *    `engine/index.ts`'s `SourceRequest` → `request.item.volume`. The TRACK's
+ *    and applies the level on a PER-SESSION output `GainNode` (one node → gain
+ *    → destination chain per clip session, `engine/audio-clock.ts`), reached
+ *    from `engine/index.ts`'s `SourceRequest` → `request.item.volume`. It is
+ *    NOT scaled into the PCM at ring-enqueue time — that was the original
+ *    design and it was replaced, so that a level change is heard immediately
+ *    rather than only after the up-to-`RING_SECONDS` already in the ring
+ *    drains. `audio-clock.ts` marks both ends of that change in place: the
+ *    interleave helper now says "**Volume no longer rides here**" and is
+ *    called with `volume === 1`, and the gain chain says "the clip's volume
+ *    rides HERE, not in the PCM". Read those, not this paragraph. The TRACK's
  *    volume/mute ride the same path: the scheduler folds them into the request
  *    item (`withTrackAudio`) before the host ever sees it. Nothing to thread
  *    here either way; adding a second volume path would be the duplication the
@@ -180,7 +188,48 @@ export function useEnginePlayback(
   currentTime: number,
   onTimeUpdate: (t: number) => void,
   fileUrl: (path: string) => string,
+  muted = false,
 ): EnginePlayback {
+  // Second-rider master mute (PreviewPlayer's `muted` prop) — see the
+  // matching ref in `useVideoPlayback.ts`, whose reasoning this mirrors.
+  //
+  // PARTIAL COVERAGE, DELIBERATELY: this only reaches the audio-LANE
+  // GainNodes below (`project.audio.tracks` — music/VO beds), the one audio
+  // path this hook owns an element/GainNode for (see "THE AUDIO LANES" in
+  // this file's header). Track-0 VIDEO-ITEM audio does NOT route through a
+  // GainNode *this hook* owns, so `muted` does not reach it today.
+  //
+  // Be precise about WHY, because the obvious guess is wrong and this file's
+  // own header asserted the wrong thing until 2026-09-20: that the item's
+  // volume is scaled into the PCM at ring-enqueue time. It is not, and
+  // `engine/audio-clock.ts` says so twice — "**Volume no longer rides here.**
+  // `createAudioClock` calls this with `volume === 1` and applies the clip's
+  // real level on a per-session output `GainNode` instead", and at the chain
+  // itself, "the clip's volume rides HERE, not in the PCM". Enqueue-time
+  // scaling was REPLACED precisely so a level change could be heard
+  // immediately, including in the up-to-`RING_SECONDS` already buffered.
+  //
+  // So closing this is cheap, and it is left undone only because it is out of
+  // this rider's scope — not because it is hard. `MasterClock.setVolume` is
+  // that live lever and it is already wired: `engine/index.ts` pushes a clip's
+  // volume change straight to the live clock rather than tearing the session
+  // down. Pushing 0 through that same path when `muted` is the whole change.
+  // It does NOT touch `SourceRequest`/session-build plumbing and it never goes
+  // near `session.muted` or the retain-drop test, because `muted` is the
+  // CONSTRUCTION-time decision (a muted clip runs on the wall clock and builds
+  // no audio graph at all) while `volume` is the live one — `audio-clock.ts`
+  // draws exactly that distinction on `muted`'s own doc comment.
+  //
+  // Flagged rather than shipped, and deliberately not described as expensive:
+  // a comment claiming a cheap fix is costly is how a hole stays open. In
+  // practice this is currently moot: every caller of
+  // `PreviewPlayer` that passes `muted` (the project-card hover preview)
+  // never sets `engine: {enabled: true}`, so this hook — and the gap — is
+  // unreached. If a future host DOES combine `engine.enabled` with `muted`,
+  // primary clip audio will still play; that combination needs its own task.
+  const mutedRef = useRef(muted)
+  useEffect(() => { mutedRef.current = muted }, [muted])
+
   // ── Derived collections (the legacy memos, verbatim) ──────────────────────
   // `track0VideoItems` IS the legacy `clips` memo, lifted into the scheduler so
   // one definition serves both the engine's tick and this surface.
@@ -329,7 +378,7 @@ export function useEnginePlayback(
 
       // `audioWindow.gain` is already `baseVolume * max(0, fadeMul)`.
       const gain = gainNodesMap.current.get(track.id)
-      if (gain) gain.gain.value = win.gain
+      if (gain) gain.gain.value = mutedRef.current ? 0 : win.gain
     }
   }, [])
 
@@ -361,7 +410,7 @@ export function useEnginePlayback(
         const ctx = getSharedAudioContext()
         const source = ctx.createMediaElementSource(el)
         const gain = ctx.createGain()
-        gain.gain.value = track.volume ?? 1
+        gain.gain.value = mutedRef.current ? 0 : (track.volume ?? 1)
         source.connect(gain)
         gain.connect(ctx.destination)
         gains.set(track.id, gain)
@@ -371,7 +420,7 @@ export function useEnginePlayback(
         srcMap.set(track.id, track.src!)
       }
       const gain = gains.get(track.id)
-      if (gain) gain.gain.value = track.volume ?? 1
+      if (gain) gain.gain.value = mutedRef.current ? 0 : (track.volume ?? 1)
     }
 
     // A lane added mid-session has to be placed at the current playhead
@@ -385,13 +434,14 @@ export function useEnginePlayback(
   // changed, which is the render whose track set this effect is reconciling.
   }, [audioTrackIdentity])
 
-  // Volume in place, no element churn.
+  // Volume in place, no element churn. `muted` is a dep so an external mute
+  // toggle reaches every lane immediately (mirrors the legacy hook).
   useEffect(() => {
     for (const track of unmutedAudioTracks) {
       const gain = gainNodesMap.current.get(track.id)
-      if (gain) gain.gain.value = track.volume ?? 1
+      if (gain) gain.gain.value = mutedRef.current ? 0 : (track.volume ?? 1)
     }
-  }, [unmutedAudioTracks])
+  }, [unmutedAudioTracks, muted])
 
   // Unmount only. The shared AudioContext is window-scoped and never closed.
   useEffect(() => {

package/src/video/preview/useVideoPlayback.ts

@@ -14,7 +14,7 @@ import {
   type MontajWindow,
 } from './audio-context'
 import type { EditorProject as Project, VisualItem, VisualTrack } from '../../schema'
-import { effectiveItemAudio, enabledTrackItems, enabledTracks, withEnabledItemTracks } from '../timeline/timeline-model'
+import { audioEnd, effectiveItemAudio, enabledTrackItems, enabledTracks, withEnabledItemTracks } from '../timeline/timeline-model'
 
 // Typed extension for video elements that cache their GainNode
 interface MontajVideoElement extends HTMLVideoElement {
@@ -122,6 +122,7 @@ export function useVideoPlayback(
   currentTime: number,
   onTimeUpdate: (t: number) => void,
   fileUrl: (path: string) => string,
+  muted = false,
 ) {
   // Double-buffer video elements for seamless clip transitions
   const video0Ref     = useRef<HTMLVideoElement>(null)
@@ -137,6 +138,20 @@ export function useVideoPlayback(
   const loopOffsetRef = useRef(0)
   const rafRef        = useRef<number | null>(null)
   const rafLastMs     = useRef<number | null>(null)
+  // Second-rider master mute (PreviewPlayer's `muted` prop). Read through a
+  // ref — not the `muted` param directly — so every gain-setting site below,
+  // including the useCallback closures whose own dependency arrays this
+  // deliberately leaves untouched (`tickGap`, `handleTimeUpdate`,
+  // `syncAudioTracks`), always sees the current value without forcing a
+  // reload/re-wire of anything. Covers BOTH GainNode families this hook owns:
+  // the video-slot slots (`videoGainRef`, via `applyClipVolume`) and every
+  // background audio-track lane (`gainNodesMap`) — `<video muted>`/
+  // `el.muted` alone would silence neither, since both are routed through
+  // `MediaElementSource → GainNode → ctx.destination` (see `audio-context.ts`
+  // and `ensureVideoGain` below): once wired, the element's own mute/volume
+  // have no audible effect.
+  const mutedRef      = useRef(muted)
+  useEffect(() => { mutedRef.current = muted }, [muted])
   // rAF clock for VIDEO projects — drives clip-boundary detection at ~60Hz
   // instead of the <video> element's coarse `timeupdate` event (~4Hz). See the
   // effect below for why.
@@ -309,18 +324,21 @@ export function useVideoPlayback(
   function applyClipVolume(clip: { muted?: boolean; volume?: number }) {
     const slot = activeSlotRef.current
     const gain = getVideoGain(slot)
-    if (gain) gain.gain.value = clipGain(videoTrack, clip)
+    if (gain) gain.gain.value = mutedRef.current ? 0 : clipGain(videoTrack, clip)
   }
 
   // Apply video clip volume via Web Audio GainNode (supports > 1.0 amplification).
   // `videoTrack` is a dep in its own right: pulling the TRACK's fader while the
-  // clips themselves are untouched has to reach the live gain node too.
+  // clips themselves are untouched has to reach the live gain node too. `muted`
+  // is a dep for the same reason: an external mute toggle on an already-loaded
+  // slot must reach the live node immediately, not wait for the next natural
+  // clip switch (which is the only other place `mutedRef` gets re-read).
   useEffect(() => {
     const idx = activeIdxRef.current
     const clip = clips[idx]
     if (!clip) return
     applyClipVolume(clip)
-  }, [clips, videoTrack, activeSlot])
+  }, [clips, videoTrack, activeSlot, muted])
 
   // maxEnd for the canvas rAF clock — the furthest visual/caption end. Kept in
   // a ref, updated by its own cheap effect, so the rAF effect below doesn't tear
@@ -339,15 +357,26 @@ export function useVideoPlayback(
   // clock's ceiling and what's on screen in agreement. Mirrored in the engine
   // path's `transportEndFor` (engine/scheduler.ts) — change both together.
   //
-  // Audio stays OUT, unchanged: the canvas/video divergence over the audio tail
-  // is documented in timeline-core's `durations.js` and is not this fix.
+  // Audio stays OUT of the ceiling whenever anything VISUAL sets one: the
+  // canvas/video divergence over the audio tail is documented in timeline-core's
+  // `durations.js` and is deliberate.
+  //
+  // It cannot stay out when nothing visual sets one at all, though. An
+  // audio-only timeline — an animations-workflow project whose music is wired
+  // before any overlay exists — left this at 0, so the first tick clamped to 0
+  // and immediately called `setIsPlaying(false)`: play/space did nothing
+  // whatsoever, with no feedback saying why. The audio end is the last-resort
+  // ceiling for exactly that case and changes nothing for any project that has
+  // visual content. Mirrored in `transportEndFor` (engine/scheduler.ts) — change
+  // both together.
   const canvasMaxEndRef = useRef(0)
   useEffect(() => {
     const captionEnd = (project.captions?.segments ?? []).reduce((m: number, s) => Math.max(m, s.end), 0)
-    canvasMaxEndRef.current = Math.max(
+    const visualCeiling = Math.max(
       enabledTrackItems(project).flat().reduce((m, i) => Math.max(m, i.end ?? 0), 0),
       captionEnd,
     )
+    canvasMaxEndRef.current = visualCeiling > 0 ? visualCeiling : audioEnd(project)
   }, [project])
 
   useEffect(() => {
@@ -431,7 +460,7 @@ export function useVideoPlayback(
         const ctx = getSharedAudioContext()
         const source = ctx.createMediaElementSource(el)
         const gain = ctx.createGain()
-        gain.gain.value = track.volume ?? 1
+        gain.gain.value = mutedRef.current ? 0 : (track.volume ?? 1)
         source.connect(gain)
         gain.connect(ctx.destination)
         gains.set(track.id, gain)
@@ -442,18 +471,21 @@ export function useVideoPlayback(
       }
       // Volume is controlled via GainNode, not el.volume
       const gain = gains.get(track.id)
-      if (gain) gain.gain.value = track.volume ?? 1
+      if (gain) gain.gain.value = mutedRef.current ? 0 : (track.volume ?? 1)
     }
   // Keyed on identity string — only fires when tracks are added/removed/src changes
   }, [audioTrackIdentity])
 
-  // Update volume in-place on every render via GainNode — cheap, no element churn
+  // Update volume in-place on every render via GainNode — cheap, no element churn.
+  // `muted` is a dep (not just read via `mutedRef`) so an external mute toggle
+  // reaches every lane immediately rather than waiting for the next track-set
+  // change or `syncAudioTracks` tick.
   useEffect(() => {
     for (const track of unmutedAudioTracks) {
       const gain = gainNodesMap.current.get(track.id)
-      if (gain) gain.gain.value = track.volume ?? 1
+      if (gain) gain.gain.value = mutedRef.current ? 0 : (track.volume ?? 1)
     }
-  }, [unmutedAudioTracks])
+  }, [unmutedAudioTracks, muted])
 
   // Cleanup on unmount only. The shared AudioContext (window.__montajSharedCtx)
   // is intentionally NOT closed — it's window-scoped and reused across remounts
@@ -504,7 +536,7 @@ export function useVideoPlayback(
 
       // `audioWindow.gain` is already `baseVolume * max(0, fadeMul)`.
       const gain = gainNodesMap.current.get(track.id)
-      if (gain) gain.gain.value = win.gain
+      if (gain) gain.gain.value = mutedRef.current ? 0 : win.gain
     }
   }, [])
 
@@ -640,7 +672,7 @@ export function useVideoPlayback(
       const src = fileUrlRef.current(playbackSrcFor(nc))
       if (preloadSrcRef.current !== src) { nv.src = src; nv.currentTime = effectiveInPoint(nc) }
       const gain = ensureVideoGain(ns)
-      if (gain) gain.gain.value = clipGain(videoTrack, nc)
+      if (gain) gain.gain.value = mutedRef.current ? 0 : clipGain(videoTrack, nc)
       playSoon(nv)
     }
     void (activeSlotRef.current === 0 ? video0Ref.current : video1Ref.current)?.pause()
@@ -758,7 +790,7 @@ export function useVideoPlayback(
         inactiveVideo.currentTime = effectiveInPoint(clips[nextIdx])
         const inactiveSlot = (1 - slot) as 0 | 1
         const nextGain = ensureVideoGain(inactiveSlot)
-        if (nextGain) nextGain.gain.value = clipGain(videoTrack, clips[nextIdx])
+        if (nextGain) nextGain.gain.value = mutedRef.current ? 0 : clipGain(videoTrack, clips[nextIdx])
       }
     }
 
@@ -813,7 +845,7 @@ export function useVideoPlayback(
               nextVideo.currentTime = effectiveInPoint(next)
             }
             const nextGain = ensureVideoGain(nextSlot)
-            if (nextGain) nextGain.gain.value = clipGain(videoTrack, next)
+            if (nextGain) nextGain.gain.value = mutedRef.current ? 0 : clipGain(videoTrack, next)
             playSoon(nextVideo)
           }
 

package/src/video/timeline/canvas/TimelineCanvas.tsx

@@ -1016,12 +1016,14 @@ export default function TimelineCanvas({
   //
   // Standard NLE behaviour: drag an item/handle past the visible edge and the
   // view pans to follow, rather than trapping the gesture at whatever was on
-  // screen when the drag started. Only gestures where "the pointer is
-  // captured and following makes sense" qualify — every `dragging` state
-  // EXCEPT `scrub` (the ruler already owns the playhead directly; panning
-  // underneath it while it drags would fight the seek instead of extending
-  // it). Marquee selection is included: dragging the box out past the edge to
-  // catch items further along the timeline is the same affordance.
+  // screen when the drag started. Every `dragging` state qualifies, including
+  // `scrub` — dragging the playhead to the edge should extend the visible
+  // range the same way dragging a clip does, rather than capping the seek at
+  // whatever was on screen when the scrub started. `applyScrub` resolves an
+  // absolute time from the screen point each call, so re-feeding the same
+  // point after a pan naturally advances the seek. Marquee selection is
+  // included too: dragging the box out past the edge to catch items further
+  // along the timeline is the same affordance.
 
   function dispatchPointerMove(point: Point, modifiers: Modifiers) {
     runEffects(machine.dispatch({ type: 'pointerMove', point, modifiers, ctx: buildContext() }))
@@ -1043,7 +1045,7 @@ export default function TimelineCanvas({
     edgeScrollFrameRef.current = null
 
     const state = machine.state
-    if (state.kind !== 'dragging' || state.gesture === 'scrub') { stopEdgeAutoScroll(); return }
+    if (state.kind !== 'dragging') { stopEdgeAutoScroll(); return }
     const drag = lastDragPointRef.current
     const rect = gestureRectRef.current
     if (!drag || !rect || rect.width <= 0) { stopEdgeAutoScroll(); return }
@@ -1088,7 +1090,7 @@ export default function TimelineCanvas({
    *  that leaves the zone is caught on the loop's own next tick). */
   function updateEdgeAutoScroll() {
     const state = machine.state
-    if (state.kind !== 'dragging' || state.gesture === 'scrub') { stopEdgeAutoScroll(); return }
+    if (state.kind !== 'dragging') { stopEdgeAutoScroll(); return }
     const drag = lastDragPointRef.current
     const rect = gestureRectRef.current
     if (!drag || !rect || rect.width <= 0 || !inEdgeZone(drag.point.x, rect.width)) return

package/src/video/timeline/canvas/__tests__/TimelineCanvas.edgeScroll.test.tsx

@@ -8,9 +8,10 @@
  * The ramp/clamp MATH is `edgeScrollDelta` in viewport.ts, covered exhaustively
  * as pure data in viewport.test.ts. What can only be shown with a mounted
  * component is here: that a real drag actually starts the loop, that panning
- * re-feeds the pointer machine so the dragged item keeps tracking, that it
- * clamps and stops at the legal scroll range, and that it stands down when the
- * pointer leaves the zone, the drag ends, or the gesture is a ruler scrub.
+ * re-feeds the pointer machine so the dragged item (or, for a ruler scrub,
+ * the playhead) keeps tracking, that it clamps and stops at the legal scroll
+ * range, and that it stands down when the pointer leaves the zone or the
+ * drag ends.
  *
  * jsdom's `performance.now()` is NOT tied to Vitest's fake timers (verified:
  * advancing the fake clock by 16ms moves it by a fraction of a millisecond of
@@ -306,7 +307,7 @@ describe('TimelineCanvas — edge auto-scroll', () => {
     }
   })
 
-  it('does not auto-scroll for a ruler scrub, even with the pointer held at the edge', () => {
+  it('auto-scrolls for a ruler scrub held at the edge, same as any other drag', () => {
     const perf = stubPerfNow()
     try {
       const { surface, store, clock } = mount()
@@ -316,13 +317,43 @@ describe('TimelineCanvas — edge auto-scroll', () => {
       expect(clock.get()).toBeCloseTo(9.9)
       act(() => { document.dispatchEvent(mouse('mousemove', 990, RULER_Y)) })
 
+      act(() => { vi.advanceTimersByTime(20) }) // seed
       perf.advance(1000)
-      act(() => { vi.advanceTimersByTime(200) })
+      act(() => { vi.advanceTimersByTime(20) }) // one real pan
+
+      // The view panned to follow the scrub, same as it would for a clip
+      // drag, and the playhead kept tracking the held screen point.
+      expect(store.get().scrollSeconds).toBeGreaterThan(0)
+      expect(clock.get()).toBeGreaterThan(9.9)
+
+      act(() => { document.dispatchEvent(mouse('mouseup', 990, RULER_Y)) })
+
+      const pannedTo = store.get().scrollSeconds
       perf.advance(5000)
       act(() => { vi.advanceTimersByTime(200) })
+      expect(store.get().scrollSeconds).toBe(pannedTo)
+    } finally {
+      perf.restore()
+    }
+  })
 
-      // The playhead moved (that's what a scrub does); the VIEWPORT did not.
-      expect(store.get().scrollSeconds).toBe(0)
+  it('scrub auto-scroll clamps at the rightmost legal scroll and stops panning', () => {
+    const perf = stubPerfNow()
+    try {
+      const { surface, store } = mount()
+      act(() => { surface.dispatchEvent(mouse('mousedown', 990, RULER_Y)) })
+      act(() => { document.dispatchEvent(mouse('mousemove', 990, RULER_Y)) })
+
+      // x=990 pans at ≈0.393s/tick at this scale (see the equivalent
+      // non-scrub clamp test above) — 140 ticks clears RIGHTMOST_SCROLL
+      // (52.5s) and then some, to prove it holds there rather than merely
+      // arriving at it.
+      for (let i = 0; i < 140; i++) {
+        perf.advance(1000)
+        act(() => { vi.advanceTimersByTime(20) })
+      }
+
+      expect(store.get().scrollSeconds).toBeCloseTo(RIGHTMOST_SCROLL, 5)
 
       act(() => { document.dispatchEvent(mouse('mouseup', 990, RULER_Y)) })
     } finally {