@bycrux/editor 1.2.0 → 1.2.1

package/src/lib/google-fonts.ts

@@ -5,14 +5,112 @@
 // (bundle.js) fetches. Used by both the video overlay layer and the carousel
 // overlay render path. Resilient by design: a font-load failure must never
 // break the render (we only append a <link>; the browser handles the fetch).
+import {
+  familiesDigest,
+  partitionFontSpecs,
+  reportUnvendoredFonts,
+  reportVendoredSet,
+  vendoredFaceIndex,
+  vendoredKeySet,
+} from './font-families'
+import type { FaceIndex, FaceMap } from './font-families'
 
 // Track Google Fonts URLs already injected so we don't add the same <link>
 // twice when multiple overlays declare overlapping fonts. Keyed by the full
 // stylesheet URL — the same URL never produces a duplicate fetch from
 // Chromium regardless, but the duplicate <link> tags would still clutter
 // document.head across long editing sessions.
+//
+// Keying on the full URL (rather than e.g. the family list) also means a
+// setFontsBaseUrl() call transparently invalidates this cache: the base is
+// part of the URL, so switching it produces a URL this Set has never seen
+// and the new <link> is injected regardless of what was injected before.
 const __injectedFontUrls = new Set<string>()
 
+// Unset (OSS default): ensureGoogleFontsLoaded builds a per-family
+// fonts.googleapis.com/css2 URL, exactly as before. Set: it links
+// `${base}/fonts.css` for the families `vendoredFamilies` declares and falls
+// through to fonts.googleapis.com for the rest.
+//
+// This setter is private to this module; FontPicker.tsx's own loader has its
+// own, separate setter. The two loaders keep separate injection state by
+// design — but they share the partition itself (`lib/font-families.ts`), so
+// they cannot disagree about which families a base covers.
+let fontsBaseUrl: string | undefined
+let vendoredFamilies = new Set<string>()
+// `undefined` means "no face information was supplied", which leaves the
+// partition at family level. An EMPTY index is different: it says the host
+// supplied face data that covers nothing, so nothing is vendored.
+let vendoredFaces: FaceIndex | undefined
+
+/**
+ * Point the loader at a vendored stylesheet.
+ *
+ * @param url      Base URL holding `fonts.css`, or undefined for the OSS
+ *                 default (everything from fonts.googleapis.com).
+ * @param families The families that stylesheet declares, spelled as its
+ *                 `font-family` rules spell them.
+ * @param faceData The manifest's `faces` and `requested` maps, which say
+ *                 WHICH FACES of each family are actually available. The
+ *                 family list alone cannot answer that, and getting it wrong
+ *                 is silent: `Playfair+Display:ital@1` names a vendored
+ *                 family whose italic does not exist, so the browser
+ *                 synthesises an oblique and nothing reports a problem.
+ *                 Omitting it leaves the partition at family level and keeps
+ *                 that hazard — the host should always pass it.
+ *
+ * **The family list is passed IN, never fetched here.** The host reads its
+ * `families.json` once at app init and hands both values over. That keeps this
+ * loader fully synchronous, which it has to be: `ensureGoogleFontsLoaded` is
+ * called from effects and must decide the partition before it can act. A fetch
+ * inside it would create a "manifest has not arrived yet" state with no good
+ * exit — it cannot block (it is sync), guessing is silently wrong, and
+ * re-injecting once the answer lands leaves two competing stylesheets on the
+ * page with the stale one never pruned.
+ *
+ * Omitting `families`, or passing an empty list, means NOTHING is treated as
+ * vendored: the vendored stylesheet is not linked and every requested family
+ * comes from Google. See `reportVendoredSet` for why that direction, and not
+ * the tempting opposite.
+ */
+export function setFontsBaseUrl(
+  url: string | undefined,
+  families?: readonly string[],
+  faceData?: { faces?: FaceMap; requested?: FaceMap },
+): void {
+  fontsBaseUrl = url
+  vendoredFamilies = vendoredKeySet(families)
+  vendoredFaces = faceData ? vendoredFaceIndex(faceData.faces, faceData.requested) : undefined
+  if (url) reportVendoredSet(url, vendoredFamilies, vendoredFaces)
+}
+
+/** The digest of the family list currently in force, for a host that wants to
+ *  compare it against the renderer's own logged digest without scraping the
+ *  console. Empty string when no base is set. */
+export function vendoredFamiliesDigest(): string {
+  return fontsBaseUrl ? familiesDigest(vendoredFamilies, vendoredFaces) : ''
+}
+
+function googleFontsUrl(specs: string[]): string {
+  return `https://fonts.googleapis.com/css2?${specs.map((f) => `family=${f}`).join('&')}&display=swap`
+}
+
+/** Append a stylesheet <link> unless this exact URL was already requested.
+ *  Returns whether it was newly requested, so a caller can log once per
+ *  distinct URL rather than once per overlay. The Set is updated before the
+ *  `document` guard, matching the original loader: a server-side call still
+ *  counts as "requested". */
+function injectStylesheet(url: string): boolean {
+  if (__injectedFontUrls.has(url)) return false
+  __injectedFontUrls.add(url)
+  if (typeof document === 'undefined') return false
+  const link = document.createElement('link')
+  link.rel = 'stylesheet'
+  link.href = url
+  document.head.appendChild(link)
+  return true
+}
+
 export function ensureGoogleFontsLoaded(googleFonts: string[] | string | undefined): void {
   // Defensive coercion: persisted project items have occasionally stored the
   // `googleFonts` field as a bare string (e.g. "Anton") instead of the typed
@@ -26,14 +124,38 @@ export function ensureGoogleFontsLoaded(googleFonts: string[] | string | undefin
       ? googleFonts.split(',').map((s) => s.trim()).filter(Boolean)
       : googleFonts
   if (!Array.isArray(families) || !families.length) return
-  // Match the format bundle.js uses for the render pipeline so preview and
-  // render fetch identical CSS (and identical glyphs / metrics).
-  const url = `https://fonts.googleapis.com/css2?${families.map((f) => `family=${f}`).join('&')}&display=swap`
-  if (__injectedFontUrls.has(url)) return
-  __injectedFontUrls.add(url)
-  if (typeof document === 'undefined') return
-  const link = document.createElement('link')
-  link.rel = 'stylesheet'
-  link.href = url
-  document.head.appendChild(link)
+
+  // Trailing slashes are stripped so `/fonts/editor` and `/fonts/editor/`
+  // resolve identically. This mirrors `montaj_assets/render/bundle.js`'s
+  // `vendoredFontsHref`, which applies the same `.replace(/\/+$/, '')` — and
+  // that symmetry is the point, not tidiness. The render base and this one
+  // are set by DIFFERENT mechanisms (an env var there, this setter here) and
+  // must name the same stylesheet; if one tolerates a trailing slash and the
+  // other emits `//fonts.css`, preview and render disagree about the URL for
+  // a base a host reasonably considers the same.
+  const base = fontsBaseUrl ? fontsBaseUrl.replace(/\/+$/, '') : ''
+
+  // The vendored set covers the families the host declared — and only those.
+  // It comes from the editor's picker list, while `googleFonts` comes out of
+  // project data, and skills/write-overlay documents arbitrary Google families
+  // as first-class (its own worked example names "Anton", which the picker does
+  // not carry). Linking the vendored sheet and dropping the requested entries
+  // would render those in a fallback face with nothing on screen to say so.
+  //
+  // With no base, `vendoredFamilies` is empty, everything falls through, and
+  // the emitted URL is byte-identical to the pre-vendoring one — the format
+  // bundle.js emits for the render pipeline, so preview and render fetch
+  // identical CSS and therefore identical glyphs / metrics.
+  const { vendored, fellThrough } = partitionFontSpecs(
+    families,
+    base ? vendoredFamilies : new Set(),
+    base ? vendoredFaces : undefined,
+  )
+  if (vendored.length) injectStylesheet(`${base}/fonts.css`)
+  if (!fellThrough.length) return
+  // Log once per distinct URL rather than once per overlay — a project with
+  // fifty overlays naming the same unvendored family should say so once.
+  // `base &&`: with no base nothing has "fallen through" to report, that is
+  // simply how the OSS default works.
+  if (injectStylesheet(googleFontsUrl(fellThrough)) && base) reportUnvendoredFonts(fellThrough)
 }

package/src/text/FontPicker.tsx

@@ -1,6 +1,8 @@
 import { useEffect, useRef, useState } from 'react'
 import { ChevronDown } from 'lucide-react'
 import { NumberField, stepValue } from '../ui'
+import { partitionFontSpecs, reportUnvendoredFonts, reportVendoredSet, vendoredFaceIndex, vendoredKeySet } from '../lib/font-families'
+import type { FaceIndex, FaceMap } from '../lib/font-families'
 
 export type FontOption = {
   label: string
@@ -53,22 +55,91 @@ export const FONT_OPTIONS: FontOption[] = [
 // 300/500/600/800), but that's the correct trade: the picker preview and
 // the persisted spec fetch identical weights, so what you see in the
 // dropdown is what actually renders.
-const GOOGLE_FONTS_URL = (() => {
-  const params = FONT_OPTIONS
+//
+// This loader is private to FontPicker.tsx and unrelated to the one in
+// `lib/google-fonts.ts` despite sharing a name — see that file's header. Each
+// keeps its own setFontsBaseUrl() and its own injection state. What they do
+// NOT keep separate is the partition itself: both import it from
+// `lib/font-families.ts`, so they cannot disagree about which families a
+// vendored stylesheet covers. Two loaders reaching different answers is a
+// caption in one face while editing and another at export.
+
+// Unset (OSS default): the per-family fonts.googleapis.com/css2 URL below,
+// exactly as before. Set: `${base}/fonts.css` for the families the host says
+// that stylesheet declares, plus a googleapis URL for any picker family it
+// does not.
+//
+// The picker's own families are the vendored set's reason for existing, so
+// in a correctly configured app nothing here ever falls through. It is
+// guarded anyway: the day a family is added to FONT_OPTIONS and not yet
+// vendored, the alternative is a picker preview silently showing a system
+// fallback — which is the exact rot a declared family list exists to catch.
+let fontsBaseUrl: string | undefined
+let vendoredFamilies = new Set<string>()
+let vendoredFaces: FaceIndex | undefined
+
+/** Point the picker's preview loader at a vendored stylesheet. Same contract
+ *  as `lib/google-fonts.ts`'s setter of the same name, including that the
+ *  family list is passed IN rather than fetched — see that file for why. A
+ *  host must call BOTH setters; neither covers the other's surface.
+ *
+ *  `faceData` matters more here than anywhere else: the picker requests
+ *  `Bebas+Neue:wght@400;700`, and only the 400 is on disk because Bebas Neue
+ *  publishes no 700. Without the `requested` half of `faceData` that spec
+ *  falls through and a picker-only project stops being zero-egress. */
+export function setFontsBaseUrl(
+  url: string | undefined,
+  families?: readonly string[],
+  faceData?: { faces?: FaceMap; requested?: FaceMap },
+): void {
+  fontsBaseUrl = url
+  vendoredFamilies = vendoredKeySet(families)
+  vendoredFaces = faceData ? vendoredFaceIndex(faceData.faces, faceData.requested) : undefined
+  if (url) reportVendoredSet(url, vendoredFamilies, vendoredFaces)
+}
+
+/** Every Google family the picker previews, as fetch specs. Falls back to a
+ *  label-derived guess only if `spec` is somehow missing, so a stale/partial
+ *  FontOption still resolves. */
+function pickerFontSpecs(): string[] {
+  return FONT_OPTIONS
     .filter((f) => f.isGoogleFont)
-    .map((f) => `family=${f.spec ?? `${f.label.replace(/ /g, '+')}:wght@400;700`}`)
-    .join('&')
-  return `https://fonts.googleapis.com/css2?${params}&display=swap`
-})()
+    .map((f) => f.spec ?? `${f.label.replace(/ /g, '+')}:wght@400;700`)
+}
 
-let fontsInjected = false
-function ensureGoogleFontsLoaded(): void {
-  if (fontsInjected || typeof document === 'undefined') return
-  fontsInjected = true
+// Keyed on the URLs actually injected (not a bare boolean, and not a single
+// last-URL string) so that neither a base change after a prior injection nor
+// the two-stylesheet partition case is suppressed by a stale "already done"
+// flag. A new base produces URLs this Set has never seen, so it injects again.
+const injectedFontsUrls = new Set<string>()
+function injectOnce(url: string): boolean {
+  if (injectedFontsUrls.has(url)) return false
+  injectedFontsUrls.add(url)
+  if (typeof document === 'undefined') return false
   const link = document.createElement('link')
   link.rel = 'stylesheet'
-  link.href = GOOGLE_FONTS_URL
+  link.href = url
   document.head.appendChild(link)
+  return true
+}
+
+function ensureGoogleFontsLoaded(): void {
+  if (typeof document === 'undefined') return
+  // Trailing slash stripped, matching `lib/google-fonts.ts` and
+  // `montaj_assets/render/bundle.js`'s `vendoredFontsHref`. All three build a
+  // URL from a base set elsewhere, and a host that passes `/fonts/editor/` to
+  // one and `/fonts/editor` to another must not get two different stylesheets.
+  const base = fontsBaseUrl ? fontsBaseUrl.replace(/\/+$/, '') : ''
+  const { vendored, fellThrough } = partitionFontSpecs(
+    pickerFontSpecs(),
+    base ? vendoredFamilies : new Set(),
+    base ? vendoredFaces : undefined,
+  )
+  if (vendored.length) injectOnce(`${base}/fonts.css`)
+  if (!fellThrough.length) return
+  if (injectOnce(`https://fonts.googleapis.com/css2?${fellThrough.map((f) => `family=${f}`).join('&')}&display=swap`) && base) {
+    reportUnvendoredFonts(fellThrough)
+  }
 }
 
 function firstFontToken(value: string): string {

package/src/text/__tests__/FontPicker.baseUrl.test.tsx

@@ -0,0 +1,112 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { render, cleanup } from '@testing-library/react'
+import { FontFamilyPicker, FONT_OPTIONS, setFontsBaseUrl } from '../FontPicker'
+
+// FontFamilyPicker's own `ensureGoogleFontsLoaded` is private to FontPicker.tsx
+// (unrelated to, and independent from, `lib/google-fonts.ts`'s loader of the
+// same name — see that file's header comment). It has no exported entry point,
+// so we drive it the way the app does: mount the component, whose first-mount
+// useEffect calls it.
+function mountPicker() {
+  return render(<FontFamilyPicker value="" onChange={() => {}} />)
+}
+
+function injectedHrefs(): string[] {
+  return Array.from(document.head.querySelectorAll('link[rel="stylesheet"]')).map(
+    (l) => (l as HTMLLinkElement).href,
+  )
+}
+
+/** Every Google family the picker previews, as the labels a vendored family
+ *  list would spell. Derived from FONT_OPTIONS rather than hardcoded, so
+ *  adding a family to the picker cannot leave this test asserting a stale set. */
+const PICKER_FAMILIES = FONT_OPTIONS.filter((f) => f.isGoogleFont).map((f) => f.label)
+
+beforeEach(() => {
+  document.head.querySelectorAll('link[rel="stylesheet"]').forEach((l) => l.remove())
+  vi.spyOn(console, 'info').mockImplementation(() => {})
+  vi.spyOn(console, 'warn').mockImplementation(() => {})
+})
+
+afterEach(() => {
+  cleanup()
+  setFontsBaseUrl(undefined)
+  vi.restoreAllMocks()
+})
+
+describe('FontFamilyPicker google fonts base URL', () => {
+  // Must run before any other test in this file sets a base: the injection
+  // guard is keyed on the computed URL, and the default URL can only be
+  // observed as "not yet injected" once per module lifetime.
+  it('unset produces exactly the default per-family googleapis URL (byte-identical to pre-base behaviour)', () => {
+    mountPicker()
+    const hrefs = injectedHrefs()
+    expect(hrefs).toEqual([
+      'https://fonts.googleapis.com/css2?family=Inter:wght@400;700&family=Roboto:wght@400;700&family=Open+Sans:wght@400;700&family=Lato:wght@400;700&family=Montserrat:wght@400;700&family=Poppins:wght@400;700&family=Raleway:wght@400;700&family=Nunito:wght@400;700&family=Work+Sans:wght@400;700&family=DM+Sans:wght@400;700&family=Rubik:wght@400;700&family=Oswald:wght@400;700&family=Bebas+Neue:wght@400;700&family=Playfair+Display:wght@400;700&family=Merriweather:wght@400;700&family=Source+Serif+4:wght@400;700&family=JetBrains+Mono:wght@400;700&family=Baloo+2:wght@400;500;600;700;800&family=Fredoka:wght@300;400;500;600;700&family=Sniglet:wght@400;800&display=swap',
+    ])
+  })
+
+  it('a base whose family list covers the picker produces <base>/fonts.css ONLY — zero egress', () => {
+    setFontsBaseUrl('https://example.com/fonts/editor', PICKER_FAMILIES)
+    mountPicker()
+    expect(injectedHrefs()).toEqual(['https://example.com/fonts/editor/fonts.css'])
+  })
+
+  it('setting a base after a prior injection still injects — a stale guard must not suppress it', () => {
+    // Bases unique to this test so it doesn't depend on injection history left
+    // by the tests above (module state, not DOM state, outlives a test — the
+    // beforeEach above only clears document.head).
+    setFontsBaseUrl('https://example.com/fonts/one', PICKER_FAMILIES)
+    mountPicker()
+    expect(injectedHrefs()).toEqual(['https://example.com/fonts/one/fonts.css'])
+
+    setFontsBaseUrl('https://example.com/fonts/two', PICKER_FAMILIES)
+    mountPicker()
+    const hrefs = injectedHrefs()
+    expect(hrefs).toHaveLength(2)
+    expect(hrefs).toContain('https://example.com/fonts/two/fonts.css')
+  })
+
+  // The picker's families ARE the vendored set's reason for existing, so in a
+  // correctly configured app this never fires. It is guarded because the day a
+  // family is added to FONT_OPTIONS and not yet vendored, the alternative is a
+  // picker preview silently showing a system fallback — the exact rot a
+  // declared family list exists to catch.
+  it('a family the vendored list omits falls through to Google, alongside the vendored sheet', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const partial = PICKER_FAMILIES.filter((f) => f !== 'Sniglet')
+    setFontsBaseUrl('https://example.com/fonts/partial', partial)
+    mountPicker()
+
+    const hrefs = injectedHrefs()
+    expect(hrefs).toHaveLength(2)
+    expect(hrefs[0]).toBe('https://example.com/fonts/partial/fonts.css')
+    expect(hrefs[1]).toBe('https://fonts.googleapis.com/css2?family=Sniglet:wght@400;800&display=swap')
+    expect(warn.mock.calls[0][0]).toContain('Sniglet')
+  })
+
+  it('a base with no family list links nothing vendored and emits exactly the default googleapis URL', async () => {
+    // A fresh module instance, because the URL this produces IS the default
+    // URL — every picker family falls through — and the module-level dedupe
+    // would (correctly) suppress it after the first test above already
+    // injected it. Asserting against the live module would therefore pass
+    // vacuously, on an empty list.
+    vi.resetModules()
+    const fresh = await import('../FontPicker')
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    fresh.setFontsBaseUrl('https://example.com/fonts/nolist')
+    render(<fresh.FontFamilyPicker value="" onChange={() => {}} />)
+
+    const hrefs = injectedHrefs()
+    expect(hrefs).toHaveLength(1)
+    expect(hrefs[0]).toContain('fonts.googleapis.com')
+    expect(hrefs[0]).not.toContain('fonts.css')
+    // Every picker family is in it — nothing was withheld on the strength of
+    // a base we were given no family list for.
+    for (const label of PICKER_FAMILIES) expect(hrefs[0]).toContain(`family=${label.replace(/ /g, '+')}`)
+    expect(warn.mock.calls[0][0]).toContain('treating NOTHING as vendored')
+
+    fresh.setFontsBaseUrl(undefined)
+  })
+})

package/src/video/VersionPanel.tsx

@@ -111,7 +111,7 @@ export default function VersionPanel({ versions, restoring, onRestore, onSaveVer
         <button
           onClick={handleSaveClick}
           disabled={saving || !onSaveVersion}
-          className="shrink-0 flex items-center gap-1.5 h-8 px-3 rounded-md bg-[var(--editor-accent)] text-white text-xs font-medium hover:opacity-90 transition-opacity disabled:opacity-40 disabled:hover:opacity-40"
+          className="shrink-0 flex items-center gap-1.5 h-8 px-3 rounded-md bg-[var(--editor-accent)] text-[var(--editor-accent-foreground)] text-xs font-medium hover:opacity-90 transition-opacity disabled:opacity-40 disabled:hover:opacity-40"
         >
           <Save size={13} />
           {saving ? 'Saving…' : 'Save version'}

package/src/video/VideoEditor.tsx

@@ -16,7 +16,7 @@ import { repairCaptionWords } from './captionRepair'
 import { maxCaptionLane, normalizeCaptionLanes } from './captionLanes'
 import Timeline, { type TimelineActions, type TimelineMode } from './timeline/Timeline'
 import { visualDuration } from '@bycrux/timeline-core'
-import { computeAutoCrossfade, computeDerivedTiming, computeVisualCrossfade, enabledTrackItems, mapTrackItems, normalizeAudioTracks, trackItems, withEnabledItemTracks } from './timeline/timeline-model'
+import { audioEnd, computeAutoCrossfade, computeDerivedTiming, computeVisualCrossfade, enabledTrackItems, mapTrackItems, normalizeAudioTracks, trackItems, withEnabledItemTracks } from './timeline/timeline-model'
 import { makeCaptionEdit, type CaptionEditPatch } from './timeline/makeCaptionEdit'
 import PreviewPlayer, { type TransportHandle, type ScrubHandle } from './preview/PreviewPlayer'
 import SocialPreviewMenu, { PlatformGlyph, platformOption } from './preview/SocialPreviewMenu'
@@ -1307,7 +1307,25 @@ function ReviewSurface<P extends Project>({
   }, [project.id, project.captions])
 
   const clips      = trackItems(project)[0] ?? []
-  const hasContent = clips.length > 0 || (trackItems(project).slice(1).flat().length ?? 0) > 0 || (project.captions?.segments?.length ?? 0) > 0
+  // Gates the ENTIRE preview region — transport, click-to-play surface and the
+  // multi-track audio elements all live inside it, so anything this misses is
+  // not merely invisible, it is unplayable with no UI saying why.
+  //
+  // Audio counts. An audio-only timeline is the normal state of an animations
+  // project between wiring music and authoring the first overlay, and gating
+  // the region out there left the operator a populated timeline, a drawn
+  // waveform lane, and no transport to press: space did nothing at all.
+  //
+  // `trackItems` is deliberately NOT sliced to `[1:]`. Track 0 is a content
+  // track in a canvas project — an animations-workflow project is frequently
+  // ONE track holding nothing but overlays — and `clips` only counts track-0
+  // *video* items, so a track-0 overlay fell through both terms. Same blind
+  // spot `transportEndFor` and `canvasMaxEndRef` were fixed for.
+  const hasContent =
+    clips.length > 0
+    || trackItems(project).flat().length > 0
+    || (project.captions?.segments?.length ?? 0) > 0
+    || audioEnd(project) > 0
 
   // Preview controls row's timecode readout. `currentTime` is the same
   // `usePlaybackTime(clock)` subscription `CaptionListPanelWithClock` uses

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 }}
               />
             </>