@bycrux/editor 1.1.0 → 1.2.1

package/src/video/preview/PreviewPlayer.tsx

@@ -112,6 +112,47 @@ interface PreviewPlayerProps {
    * note at its render site below.
    */
   socialPreview?: SocialPreviewPlatform | string | null
+  /**
+   * A second rider on this same pin bump (operator decision, 2026-09-20) —
+   * not font work, riding because it is the same package and the same
+   * release. Silences every audio path this component owns. Default `false`
+   * — today's behavior, unchanged, for every existing host.
+   *
+   * Exists for hosts that mount a live timeline preview somewhere audio isn't
+   * wanted (the project-card hover preview: moving the pointer across a grid
+   * must not play each project's audio in turn). `<video muted>` is NOT
+   * sufficient on its own — see `ensureVideoGain` and the "Multi-track audio
+   * management" section in `useVideoPlayback.ts`: once a slot or a lane is
+   * wired `MediaElementSource → GainNode → ctx.destination`, the element's
+   * own `muted`/`volume` stop having any audible effect and the GainNode is
+   * the only real lever. This prop zeroes every such GainNode (video slots
+   * AND background audio-track lanes) via `mutedRef` in `useVideoPlayback.ts`
+   * — the `muted` attribute set on the `<video>` slots below is defense in
+   * depth for the brief pre-wire window, not the mechanism.
+   *
+   * Read the scope of that precisely: this silences every audio path these
+   * hooks INSTANTIATE, which is not the same as every path reachable through
+   * a seam this component EXPOSES. The audible drag-scrub source
+   * (`engine/scrub-source.ts`) owns its own gain → destination chain on the
+   * same shared AudioContext, and `muted` does not touch it — it is
+   * constructed and driven by `VideoEditor`, and only reached here via the
+   * `ScrubHandle` seam below. That is sound today because a scrub needs a
+   * timeline-drag gesture that a thumbnail-hover mount has no UI for, so a
+   * silent host cannot reach it. A host that both passes `muted` and wires
+   * scrubbing would hear it, and would be right to call that a bug.
+   *
+   * Engine-mode (`engine.enabled`) coverage is PARTIAL: `useEnginePlayback.ts`
+   * zeroes the same background-lane GainNodes, but track-0 video-item audio
+   * is not reached, because this rider did not extend to the engine's own
+   * clock. It is a scope boundary, NOT a hard one — the clip's level already
+   * rides a per-session output `GainNode` with a live `MasterClock.setVolume`
+   * lever wired through `engine/index.ts`, so closing it means pushing 0 down
+   * that existing path. See that hook's own comment, which spells out why and
+   * corrects a stale claim in its file header about PCM-level scaling. No
+   * current host combines `engine.enabled` with `muted`, so this is a
+   * documented gap, not a live bug.
+   */
+  muted?: boolean
 }
 
 export default function PreviewPlayer(props: PreviewPlayerProps) {
@@ -245,12 +286,12 @@ type SurfaceProps = PreviewPlayerProps & {
 }
 
 function LegacyPreview(props: SurfaceProps) {
-  const playback = useVideoPlayback(props.project, props.currentTime, props.timeSink, props.fileUrl)
+  const playback = useVideoPlayback(props.project, props.currentTime, props.timeSink, props.fileUrl, !!props.muted)
   return <PreviewSurface {...props} playback={{ mode: 'legacy', ...playback }} />
 }
 
 function EnginePreview(props: SurfaceProps) {
-  const playback = useEnginePlayback(props.project, props.currentTime, props.timeSink, props.fileUrl)
+  const playback = useEnginePlayback(props.project, props.currentTime, props.timeSink, props.fileUrl, !!props.muted)
   return <PreviewSurface {...props} playback={{ mode: 'engine', ...playback }} />
 }
 
@@ -275,6 +316,7 @@ function PreviewSurface({
   transportRef,
   scrubHandleRef,
   socialPreview,
+  muted,
 }: SurfaceProps & { playback: PlaybackBinding }) {
   const [RENDER_W, RENDER_H] = getOverlayDesignCanvas(project.settings?.resolution)
 
@@ -497,6 +539,12 @@ function PreviewSurface({
                 onPlay={() => { if (playback.activeSlotRef.current === 0) playback.setIsPlaying(true) }}
                 onPause={() => { if (playback.activeSlotRef.current === 0) playback.handlePause() }}
                 playsInline
+                // Defense in depth, not the mechanism — see the `muted` prop
+                // doc above. Once `ensureVideoGain` wires this element through
+                // Web Audio (on first play), this attribute stops having any
+                // audible effect; the GainNode zeroed via `mutedRef` in
+                // `useVideoPlayback.ts` is what actually silences it.
+                muted={!!muted}
                 style={{ ...baseVideoStyle, opacity: showVideo && playback.activeSlot === 0 ? 1 : 0, pointerEvents: playback.activeSlot === 0 ? 'auto' : 'none', zIndex: playback.activeSlot === 0 ? 1 : 0 }}
               />
               {/* Slot 1 */}
@@ -513,6 +561,8 @@ function PreviewSurface({
                 onPlay={() => { if (playback.activeSlotRef.current === 1) playback.setIsPlaying(true) }}
                 onPause={() => { if (playback.activeSlotRef.current === 1) playback.handlePause() }}
                 playsInline
+                // See slot 0.
+                muted={!!muted}
                 style={{ ...baseVideoStyle, opacity: showVideo && playback.activeSlot === 1 ? 1 : 0, pointerEvents: playback.activeSlot === 1 ? 'auto' : 'none', zIndex: playback.activeSlot === 1 ? 1 : 0 }}
               />
             </>

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

@@ -0,0 +1,99 @@
+/**
+ * The canvas rAF clock's CEILING, driven through the real effect.
+ *
+ * `canvasMaxEndRef` is the only thing standing between "space plays" and "space
+ * does nothing" on a project with no track-0 video. It used to read
+ * `overlayTracks` (`tracks.slice(1)`), which silently skips track 0 — and track
+ * 0 in canvas mode is not the primary footage track, it is content: the
+ * background images, and on an agent-authored project frequently the overlays
+ * themselves. A project that is ONE track of nothing but overlays (what the
+ * animations workflow emits) therefore got a ceiling of 0, and the first tick
+ * clamped the playhead to 0 and called `setIsPlaying(false)` in the same frame.
+ *
+ * These drive the hook's own rAF effect rather than asserting on a helper: the
+ * ceiling lives in a ref that nothing exports, so the only honest way to pin it
+ * is to run the clock and watch where time goes. Each case fails on the
+ * pre-fix `overlayTracks` read.
+ */
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { act, renderHook } from '@testing-library/react'
+import { useVideoPlayback } from '../useVideoPlayback'
+import type { EditorProject, VisualItem } from '../../../schema'
+
+const overlay = (id: string, start: number, end: number): VisualItem =>
+  ({ id, type: 'overlay', src: `/overlays/${id}.jsx`, start, end }) as VisualItem
+
+const image = (id: string, start: number, end: number): VisualItem =>
+  ({ id, type: 'image', src: `/img/${id}.png`, start, end }) as VisualItem
+
+/** The last emission. Not `.at(-1)` — this package targets ES2020. */
+const last = (xs: number[]): number | undefined => xs[xs.length - 1]
+
+function projectOf(...tracks: VisualItem[][]): EditorProject {
+  return {
+    id: 'canvas-clock',
+    status: 'draft',
+    settings: { resolution: [1920, 1080] },
+    tracks: tracks.map((items, i) => ({ id: `trk-${i}`, items })),
+  } as EditorProject
+}
+
+/**
+ * Mount the hook on a canvas project and run the clock for one second of wall
+ * time, returning every playhead value it emitted.
+ *
+ * Two ticks, because the first only anchors `rafLastMs` — it has no `dt` yet
+ * and emits nothing. The second is the first that can move the playhead, and
+ * the one the collapsed ceiling used to kill.
+ */
+function runClock(project: EditorProject) {
+  const times: number[] = []
+  const scheduled: FrameRequestCallback[] = []
+  vi.spyOn(globalThis, 'requestAnimationFrame').mockImplementation((cb: FrameRequestCallback) => {
+    scheduled.push(cb)
+    return scheduled.length
+  })
+
+  const view = renderHook(() => useVideoPlayback(project, 0, (t) => times.push(t), (p) => p))
+  expect(view.result.current.isCanvasProject).toBe(true)
+
+  scheduled.length = 0
+  act(() => { view.result.current.setIsPlaying(true) })
+  expect(scheduled.length).toBeGreaterThan(0)
+
+  act(() => { scheduled[0](0) })          // anchor only
+  act(() => { scheduled[scheduled.length - 1](1000) })  // +1s of wall clock
+
+  return { times, isPlaying: view.result.current.isPlaying }
+}
+
+describe('useVideoPlayback — the canvas clock counts track 0', () => {
+  afterEach(() => { vi.restoreAllMocks() })
+
+  it('advances on a single track holding nothing but overlays', () => {
+    // The Daubert-demo shape: one track, 14 overlays, no captions, no video.
+    const { times, isPlaying } = runClock(projectOf([overlay('o1', 0, 5), overlay('o2', 5, 12)]))
+    expect(last(times)).toBeCloseTo(1, 6)
+    expect(isPlaying).toBe(true)
+  })
+
+  it('advances on a track-0 image that outlasts every overlay track', () => {
+    // Same defect, other content kind — the background image was invisible to
+    // the ceiling, so a slideshow stopped at its last overlay.
+    //
+    // The overlay track has to end INSIDE the second this clock runs (0.4 < 1),
+    // or `overlayTracks` alone already carries the playhead to 1 and the case
+    // passes on the broken code without ever reading track 0.
+    const { times } = runClock(projectOf([image('bg', 0, 20)], [overlay('o', 0, 0.4)]))
+    expect(last(times)).toBeCloseTo(1, 6)
+  })
+
+  it('still stops at the ceiling rather than running past the content', () => {
+    // The clamp itself is not what was wrong, and must survive: one second of
+    // wall clock against a half-second project lands on the end, not past it,
+    // and playback stops there.
+    const { times, isPlaying } = runClock(projectOf([overlay('o', 0, 0.5)]))
+    expect(last(times)).toBeCloseTo(0.5, 6)
+    expect(isPlaying).toBe(false)
+  })
+})

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(() => {