@bycrux/editor 1.2.0 → 1.2.2

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

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, afterEach } from 'vitest'
 import { render, screen, waitFor, cleanup } from '@testing-library/react'
-import type { CaptionEvent, EditorAdapter, ImageElement, Project } from '../../types'
+import type { CaptionEvent, CaptionProfileDefaults, EditorAdapter, ImageElement, Project } from '../../types'
 import type { Captions } from '../../schema'
 import CaptionRegenModal from '../CaptionRegenModal'
 
@@ -45,7 +45,9 @@ describe('CaptionRegenModal', () => {
     )
 
     await waitFor(() => expect(screen.getByText(/transcribing audio/i)).toBeTruthy())
-    await waitFor(() => expect(onDone).toHaveBeenCalledWith(doneCaptions))
+    // Second argument is the profile defaults the host resolved — `null` on
+    // this adapter, which implements no `getCaptionProfileDefaults`.
+    await waitFor(() => expect(onDone).toHaveBeenCalledWith(doneCaptions, null))
   })
 
   it('shows an error message verbatim on error', async () => {
@@ -92,3 +94,160 @@ describe('CaptionRegenModal', () => {
     expect(screen.queryByText(/caption rows/i)).toBeNull()
   })
 })
+
+// ── Profile-seeded caption defaults ──────────────────────────────────────────
+//
+// `adapter.getCaptionProfileDefaults` is an OPTIONAL host seam: this package
+// owns no notion of what a profile is beyond `Project.profile`'s bare name, so
+// a host that can resolve one answers, and a host that cannot omits the method
+// entirely. Every assertion below therefore comes in a pair — the seam present
+// and the seam absent — because the absent case is the one every existing host
+// (Hub, Los Parceros, the OSS `serve` UI) is in today, and it must keep
+// producing the byte-identical call it produced before this seam existed.
+
+/** Adapter whose `generateCaptions` is a spy, so the opts argument is readable. */
+function makeSpyAdapter() {
+  const adapter = makeAdapter()
+  const generateCaptions = vi.fn(async function* (): AsyncIterable<CaptionEvent> {
+    yield { type: 'done', captions: doneCaptions }
+  })
+  adapter.generateCaptions = generateCaptions
+  return { adapter, generateCaptions }
+}
+
+const PROFILE_DEFAULTS: CaptionProfileDefaults = {
+  style: 'karaoke',
+  fontFamily: '"Inter", system-ui, sans-serif',
+  color: '#112233',
+}
+
+describe('CaptionRegenModal — profile-seeded caption defaults', () => {
+  it('seeds the generation style from the defaults the host resolves for the project profile', async () => {
+    const { adapter, generateCaptions } = makeSpyAdapter()
+    const getCaptionProfileDefaults = vi.fn(async () => PROFILE_DEFAULTS)
+    adapter.getCaptionProfileDefaults = getCaptionProfileDefaults
+
+    render(
+      <CaptionRegenModal
+        adapter={adapter}
+        projectId="vid-1"
+        profile="sam"
+        existingRowCount={1}
+        onDone={vi.fn()}
+        onClose={vi.fn()}
+      />,
+    )
+
+    await waitFor(() => expect(generateCaptions).toHaveBeenCalledWith('vid-1', { style: 'karaoke' }))
+    expect(getCaptionProfileDefaults).toHaveBeenCalledWith('sam')
+  })
+
+  it('hands the resolved defaults to onDone alongside the fresh captions', async () => {
+    // The host merges font/color onto the track at its own apply seam; the
+    // modal resolves the profile ONCE and passes what it got, so the host
+    // never repeats the round trip (and can never race a second answer).
+    const { adapter } = makeSpyAdapter()
+    adapter.getCaptionProfileDefaults = vi.fn(async () => PROFILE_DEFAULTS)
+    const onDone = vi.fn()
+
+    render(
+      <CaptionRegenModal
+        adapter={adapter}
+        projectId="vid-1"
+        profile="sam"
+        existingRowCount={1}
+        onDone={onDone}
+        onClose={vi.fn()}
+      />,
+    )
+
+    await waitFor(() => expect(onDone).toHaveBeenCalledWith(doneCaptions, PROFILE_DEFAULTS))
+  })
+
+  it('passes no opts at all when the host implements no caption-defaults seam', async () => {
+    // Today's behaviour for every existing host, pinned: a bare one-argument
+    // call, not `(id, undefined)` and not `(id, {})`.
+    const { adapter, generateCaptions } = makeSpyAdapter()
+    const onDone = vi.fn()
+
+    render(
+      <CaptionRegenModal
+        adapter={adapter}
+        projectId="vid-1"
+        profile="sam"
+        existingRowCount={1}
+        onDone={onDone}
+        onClose={vi.fn()}
+      />,
+    )
+
+    await waitFor(() => expect(onDone).toHaveBeenCalled())
+    expect(generateCaptions).toHaveBeenCalledWith('vid-1')
+    expect(onDone).toHaveBeenCalledWith(doneCaptions, null)
+  })
+
+  it('never asks for defaults when the project has no profile', async () => {
+    const { adapter, generateCaptions } = makeSpyAdapter()
+    const getCaptionProfileDefaults = vi.fn(async () => PROFILE_DEFAULTS)
+    adapter.getCaptionProfileDefaults = getCaptionProfileDefaults
+
+    render(
+      <CaptionRegenModal
+        adapter={adapter}
+        projectId="vid-1"
+        existingRowCount={1}
+        onDone={vi.fn()}
+        onClose={vi.fn()}
+      />,
+    )
+
+    await waitFor(() => expect(generateCaptions).toHaveBeenCalledWith('vid-1'))
+    expect(getCaptionProfileDefaults).not.toHaveBeenCalled()
+  })
+
+  it('still generates when the caption-defaults seam rejects', async () => {
+    // Seeding is a convenience. A profile lookup that 500s must never be the
+    // reason a user cannot regenerate their captions.
+    const { adapter, generateCaptions } = makeSpyAdapter()
+    adapter.getCaptionProfileDefaults = vi.fn(async () => { throw new Error('boom') })
+    const onDone = vi.fn()
+
+    render(
+      <CaptionRegenModal
+        adapter={adapter}
+        projectId="vid-1"
+        profile="sam"
+        existingRowCount={1}
+        onDone={onDone}
+        onClose={vi.fn()}
+      />,
+    )
+
+    await waitFor(() => expect(generateCaptions).toHaveBeenCalledWith('vid-1'))
+    await waitFor(() => expect(onDone).toHaveBeenCalledWith(doneCaptions, null))
+    expect(screen.queryByText('boom')).toBeNull()
+  })
+
+  it('passes no style when the profile resolves without one', async () => {
+    // A profile that sets only a font and a color must not send `style:
+    // undefined` — the host route reads presence, not value.
+    const { adapter, generateCaptions } = makeSpyAdapter()
+    const fontOnly: CaptionProfileDefaults = { fontFamily: '"Inter", system-ui, sans-serif' }
+    adapter.getCaptionProfileDefaults = vi.fn(async () => fontOnly)
+    const onDone = vi.fn()
+
+    render(
+      <CaptionRegenModal
+        adapter={adapter}
+        projectId="vid-1"
+        profile="sam"
+        existingRowCount={1}
+        onDone={onDone}
+        onClose={vi.fn()}
+      />,
+    )
+
+    await waitFor(() => expect(generateCaptions).toHaveBeenCalledWith('vid-1'))
+    await waitFor(() => expect(onDone).toHaveBeenCalledWith(doneCaptions, fontOnly))
+  })
+})

package/src/video/__tests__/VideoEditor.captionSeam.test.tsx

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 import { render, screen, waitFor, fireEvent } from '@testing-library/react'
 import type { CaptionEvent, EditorAdapter, ImageElement, Project, RenderEvent, VersionEntry, WaveformChunk } from '../../types'
+import type { Captions } from '../../schema'
 import VideoEditor from '../VideoEditor'
 
 // ── T1 — host-driven caption trigger seam ────────────────────────────────────
@@ -132,3 +133,104 @@ describe('VideoEditor — host-driven caption trigger seam', () => {
     await waitFor(() => expect(screen.getByText('Regenerating captions…')).toBeTruthy())
   })
 })
+
+// ── Profile-seeded caption defaults, through the real apply seam ─────────────
+//
+// The unit-level rules live in `captionProfileDefaults.test.ts`; what these
+// two prove is the WIRING — that `project.profile` reaches the host seam, and
+// that the merged track is what `applyExternal` lands on the project. There is
+// no spy for `applyExternal` (it is internal to `useProjectSync`, and it
+// deliberately calls neither `onProjectChange` nor `adapter.saveProject` — see
+// VideoEditor.captionDelete.test.tsx's note), so the assertion reads the
+// caption color back out of the Format tab's swatch, which renders
+// `project.captions.color` and falls back to '#ffffff' when unset.
+
+function readCaptionColor(): string {
+  fireEvent.click(screen.getByRole('button', { name: 'Format' }))
+  return (screen.getByLabelText('Caption text color') as HTMLInputElement).value
+}
+
+/** Adapter whose regen stream terminates with the given track. */
+function makeRegenAdapter(captions: Captions) {
+  const adapter = makeFakeAdapter()
+  adapter.generateCaptions = vi.fn(async function* (): AsyncIterable<CaptionEvent> {
+    yield { type: 'done', captions }
+  })
+  return adapter
+}
+
+describe('VideoEditor — profile-seeded caption defaults', () => {
+  it('merges the profile font/color onto a server track that set neither', async () => {
+    const adapter = makeRegenAdapter({
+      style: 'pop',
+      segments: [{ id: 'cap-new', text: 'fresh', start: 0, end: 1, words: [{ word: 'fresh', start: 0, end: 1 }] }],
+    })
+    const getCaptionProfileDefaults = vi.fn(async () => ({
+      style: 'karaoke',
+      fontFamily: '"Inter", system-ui, sans-serif',
+      color: '#112233',
+    }))
+    ;(adapter as unknown as { getCaptionProfileDefaults: unknown }).getCaptionProfileDefaults = getCaptionProfileDefaults
+
+    render(
+      <VideoEditor
+        project={makeVideoProject({ profile: 'sam' })}
+        adapter={adapter}
+        onProjectChange={vi.fn()}
+      />,
+    )
+
+    fireEvent.click(await screen.findByText('Regenerate captions'))
+
+    // The modal closes itself once the host's onDone runs, which is also when
+    // the merged track has landed.
+    await waitFor(() => expect(screen.queryByText('Regenerating captions…')).toBeNull())
+    expect(getCaptionProfileDefaults).toHaveBeenCalledWith('sam')
+    expect(adapter.generateCaptions).toHaveBeenCalledWith('vid-1', { style: 'karaoke' })
+    expect(readCaptionColor()).toBe('#112233')
+  })
+
+  it('leaves a color the server response already set alone', async () => {
+    const adapter = makeRegenAdapter({
+      style: 'pop',
+      color: '#ff0000',
+      segments: [{ id: 'cap-new', text: 'fresh', start: 0, end: 1, words: [{ word: 'fresh', start: 0, end: 1 }] }],
+    })
+    ;(adapter as unknown as { getCaptionProfileDefaults: unknown }).getCaptionProfileDefaults =
+      vi.fn(async () => ({ color: '#112233' }))
+
+    render(
+      <VideoEditor
+        project={makeVideoProject({ profile: 'sam' })}
+        adapter={adapter}
+        onProjectChange={vi.fn()}
+      />,
+    )
+
+    fireEvent.click(await screen.findByText('Regenerate captions'))
+    await waitFor(() => expect(screen.queryByText('Regenerating captions…')).toBeNull())
+    expect(readCaptionColor()).toBe('#ff0000')
+  })
+
+  it('applies the server track untouched on a host with no caption-defaults seam', async () => {
+    // Every host shipping today is in this case; the regen call must stay the
+    // bare one-argument call it has always been.
+    const adapter = makeRegenAdapter({
+      style: 'pop',
+      segments: [{ id: 'cap-new', text: 'fresh', start: 0, end: 1, words: [{ word: 'fresh', start: 0, end: 1 }] }],
+    })
+
+    render(
+      <VideoEditor
+        project={makeVideoProject({ profile: 'sam' })}
+        adapter={adapter}
+        onProjectChange={vi.fn()}
+      />,
+    )
+
+    fireEvent.click(await screen.findByText('Regenerate captions'))
+    await waitFor(() => expect(screen.queryByText('Regenerating captions…')).toBeNull())
+    expect(adapter.generateCaptions).toHaveBeenCalledWith('vid-1')
+    expect(readCaptionColor()).toBe('#ffffff')
+  })
+})

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

@@ -0,0 +1,121 @@
+import { describe, it, expect, vi } from 'vitest'
+import type { EditorAdapter, Project } from '../../types'
+import type { Captions } from '../../schema'
+import { mergeCaptionProfileDefaults, resolveCaptionProfileDefaults } from '../captionProfileDefaults'
+
+// A freshly transcribed track as the host routes actually return one: a bare
+// `{ style, segments }` with no text styling at all (montaj's own
+// `steps/caption/caption.py` builds exactly this shape). Every field the
+// profile can seed is therefore absent here, which is the whole reason seeding
+// is worth doing.
+const FRESH: Captions = {
+  style: 'pop',
+  segments: [{ text: 'hola', start: 0, end: 1, words: [] }],
+}
+
+function adapterWith(
+  getCaptionProfileDefaults?: EditorAdapter<Project>['getCaptionProfileDefaults'],
+): EditorAdapter<Project> {
+  return { getCaptionProfileDefaults } as unknown as EditorAdapter<Project>
+}
+
+describe('mergeCaptionProfileDefaults', () => {
+  it('fills the fields the server left unset', () => {
+    const merged = mergeCaptionProfileDefaults(FRESH, {
+      fontFamily: '"Inter", system-ui, sans-serif',
+      color: '#112233',
+    })
+    expect(merged.fontFamily).toBe('"Inter", system-ui, sans-serif')
+    expect(merged.color).toBe('#112233')
+    expect(merged.segments).toBe(FRESH.segments)
+    expect(merged.style).toBe('pop')
+  })
+
+  it('never overwrites a color the server response already set', () => {
+    // The route returns a bare track today. If it ever starts carrying a
+    // color, that value is authored downstream of the profile and wins.
+    const withColor: Captions = { ...FRESH, color: '#ff0000' }
+    const merged = mergeCaptionProfileDefaults(withColor, { color: '#112233' })
+    expect(merged.color).toBe('#ff0000')
+  })
+
+  it('never overwrites a fontFamily the server response already set', () => {
+    const withFont: Captions = { ...FRESH, fontFamily: '"Figtree", system-ui, sans-serif' }
+    const merged = mergeCaptionProfileDefaults(withFont, {
+      fontFamily: '"Inter", system-ui, sans-serif',
+      googleFonts: ['Inter:wght@700'],
+    })
+    expect(merged.fontFamily).toBe('"Figtree", system-ui, sans-serif')
+    expect(merged.googleFonts).toBeUndefined()
+  })
+
+  it('carries googleFonts along with a seeded fontFamily', () => {
+    // `fontFamily` and `googleFonts` travel together (see the `Captions` doc
+    // comment): a family whose file is not also fetched renders as the
+    // fallback face, in the preview AND the export. Seeding one without the
+    // other is the silent half-failure this pair exists to avoid.
+    const merged = mergeCaptionProfileDefaults(FRESH, {
+      fontFamily: '"Inter", system-ui, sans-serif',
+      googleFonts: ['Inter:wght@700'],
+    })
+    expect(merged.googleFonts).toEqual(['Inter:wght@700'])
+  })
+
+  it('does not inject googleFonts when the family was not seeded', () => {
+    const withFont: Captions = { ...FRESH, fontFamily: '"Figtree", system-ui, sans-serif' }
+    const merged = mergeCaptionProfileDefaults(withFont, { googleFonts: ['Inter:wght@700'] })
+    expect(merged.googleFonts).toBeUndefined()
+  })
+
+  it('returns the very same object when there is nothing to seed', () => {
+    // Reference identity, not deep equality: the caller feeds the result
+    // straight to `applyExternal`, and a fresh object there is a state change
+    // the editor has to reconcile for no reason.
+    expect(mergeCaptionProfileDefaults(FRESH, null)).toBe(FRESH)
+    expect(mergeCaptionProfileDefaults(FRESH, undefined)).toBe(FRESH)
+    expect(mergeCaptionProfileDefaults(FRESH, {})).toBe(FRESH)
+    expect(mergeCaptionProfileDefaults(FRESH, { style: 'karaoke' })).toBe(FRESH)
+  })
+
+  it('never writes the profile style onto the track', () => {
+    // `style` seeds the GENERATION request, not the returned track: the host
+    // reports the style it actually transcribed with, and that report wins.
+    const merged = mergeCaptionProfileDefaults(FRESH, { style: 'karaoke', color: '#112233' })
+    expect(merged.style).toBe('pop')
+  })
+
+  it('treats an empty-string default as nothing to seed', () => {
+    // A host backed by a nullable column can hand back `''` for "unset".
+    expect(mergeCaptionProfileDefaults(FRESH, { fontFamily: '', color: '' })).toBe(FRESH)
+  })
+})
+
+describe('resolveCaptionProfileDefaults', () => {
+  it('returns null when the host implements no seam', async () => {
+    expect(await resolveCaptionProfileDefaults(adapterWith(), 'sam')).toBeNull()
+  })
+
+  it('returns null when the project has no profile', async () => {
+    const seam = vi.fn(async () => ({ color: '#112233' }))
+    expect(await resolveCaptionProfileDefaults(adapterWith(seam), undefined)).toBeNull()
+    expect(await resolveCaptionProfileDefaults(adapterWith(seam), '')).toBeNull()
+    expect(seam).not.toHaveBeenCalled()
+  })
+
+  it('returns null rather than throwing when the seam rejects', async () => {
+    const seam = vi.fn(async () => { throw new Error('boom') })
+    await expect(resolveCaptionProfileDefaults(adapterWith(seam), 'sam')).resolves.toBeNull()
+  })
+
+  it('returns null rather than throwing when the seam throws synchronously', async () => {
+    const seam = vi.fn(() => { throw new Error('boom') }) as unknown as EditorAdapter<Project>['getCaptionProfileDefaults']
+    await expect(resolveCaptionProfileDefaults(adapterWith(seam), 'sam')).resolves.toBeNull()
+  })
+
+  it('passes the profile name through and returns what the host answered', async () => {
+    const answer = { style: 'karaoke', color: '#112233' }
+    const seam = vi.fn(async () => answer)
+    expect(await resolveCaptionProfileDefaults(adapterWith(seam), 'sam')).toBe(answer)
+    expect(seam).toHaveBeenCalledWith('sam')
+  })
+})

package/src/video/captionProfileDefaults.ts

@@ -0,0 +1,86 @@
+/**
+ * The two halves of profile-seeded caption defaults: ask the host what a
+ * profile looks like, and fold the answer onto a freshly transcribed track.
+ *
+ * Both live here rather than inside the two components that use them because
+ * they are used at two different moments of one flow — `CaptionRegenModal`
+ * resolves the defaults *before* the stream starts (it needs the style to put
+ * on the request), and `VideoEditor` merges them *after* it ends (at the one
+ * seam that applies server-authored captions outside the undo stack). The
+ * resolution happens once, in the modal, and rides along to the merge on the
+ * `onDone` callback; neither side repeats the round trip, so they cannot
+ * disagree about what the profile said.
+ *
+ * NOT to be confused with `captionStyleDefaults.ts` next door, which is a
+ * hand-copied mirror of each render TEMPLATE's own parameter defaults. These
+ * are the HOST's defaults for one named profile, and the editor knows nothing
+ * about where they come from.
+ */
+import type { CaptionProfileDefaults, EditorAdapter, Project } from '../types'
+import type { Captions } from '../schema'
+
+/**
+ * Ask the host for `profile`'s caption defaults, best-effort.
+ *
+ * Returns `null` — never throws, never rejects — when the project has no
+ * profile, when the host implements no `getCaptionProfileDefaults`, or when
+ * that call fails in any way. Seeding is a convenience laid over the user's
+ * actual request (regenerate my captions); a profile lookup that 500s must not
+ * be the reason that request cannot be made. The synchronous `try` matters as
+ * much as the `.catch`: an adapter method that throws before returning its
+ * promise would otherwise escape past the await.
+ */
+export async function resolveCaptionProfileDefaults<P extends Project = Project>(
+  adapter: EditorAdapter<P>,
+  profile: string | undefined | null,
+): Promise<CaptionProfileDefaults | null> {
+  if (!profile || !adapter.getCaptionProfileDefaults) return null
+  try {
+    return (await adapter.getCaptionProfileDefaults(profile)) ?? null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Fold `defaults` onto a freshly transcribed `captions` track, filling only
+ * the fields the host's response left unset.
+ *
+ * Three rules, each load-bearing:
+ *
+ *  - **The server's value always wins.** The caption route returns a bare
+ *    `{ style, segments }` today, so in practice every seedable field is
+ *    absent — but a profile default is the weakest possible authority on a
+ *    track's look, below anything the host chose to state, and the day the
+ *    route starts carrying a color is not the day this should start
+ *    clobbering it.
+ *  - **`style` is never written onto the track.** It seeds the generation
+ *    REQUEST (`GenerateCaptionsOptions.style`); what comes back reports the
+ *    style actually transcribed with, and that report is the truth.
+ *  - **`googleFonts` rides with `fontFamily` or not at all.** Seeding a
+ *    family without its font spec renders the fallback face with nothing on
+ *    screen to say so (see `Captions.fontFamily`), and seeding a spec for a
+ *    family we did not apply just fetches bytes no glyph uses.
+ *
+ * Returns the ORIGINAL object by reference when there is nothing to seed. The
+ * result goes straight to `applyExternal`, and a fresh object there is a state
+ * change the editor reconciles — and, downstream, a project that differs from
+ * one produced before this feature existed, for no reason a user could name.
+ */
+export function mergeCaptionProfileDefaults(
+  captions: Captions,
+  defaults: CaptionProfileDefaults | null | undefined,
+): Captions {
+  if (!defaults) return captions
+
+  const patch: Partial<Captions> = {}
+  if (captions.fontFamily == null && defaults.fontFamily) {
+    patch.fontFamily = defaults.fontFamily
+    if (captions.googleFonts == null && defaults.googleFonts?.length) {
+      patch.googleFonts = defaults.googleFonts
+    }
+  }
+  if (captions.color == null && defaults.color) patch.color = defaults.color
+
+  return Object.keys(patch).length === 0 ? captions : { ...captions, ...patch }
+}

package/src/video/panels/LeftPanelTabs.tsx

@@ -148,8 +148,26 @@ export default function LeftPanelTabs({ tabs, defaultTabId, storageKey = DEFAULT
                 selected
                   // Label is ~10px accent TEXT → the AA-safe accent-text token
                   // (indigo-600 in light); the tint fill keeps the plain accent.
-                  ? 'text-[var(--editor-accent-text)] bg-[var(--editor-accent)]/10'
-                  : 'text-[var(--editor-text)]/60 hover:text-[var(--editor-text)] hover:bg-[var(--editor-text)]/5',
+                  //
+                  // The tint uses `color-mix(...)` baked directly into the
+                  // arbitrary value, NOT Tailwind's `/NN` opacity modifier —
+                  // that modifier only works when Tailwind itself can parse
+                  // the color to inject an alpha channel, which it cannot do
+                  // for an arbitrary `var(...)` reference. `text-[var(--x)]/60`
+                  // silently emits NO utility at all (no build error, no
+                  // fallback), in this package's own Tailwind build and in a
+                  // host's. Measured: building this component under
+                  // montaj-app/desktop/ui's Tailwind (v3.4) produced zero
+                  // `editor-text`/`editor-accent` rules for any `/NN`-modified
+                  // class here, while the identical `color-mix(in_srgb,
+                  // var(--editor-text)_60%,transparent)` arbitrary value
+                  // compiled correctly in both builds. That silent failure is
+                  // exactly what made the rail's inactive items (all but the
+                  // selected tab) unreadable — no color rule at all, so the
+                  // button fell back to inherited/default text color against
+                  // the editor's dark background.
+                  ? 'text-[var(--editor-accent-text)] bg-[color-mix(in_srgb,var(--editor-accent)_10%,transparent)]'
+                  : 'text-[color-mix(in_srgb,var(--editor-text)_60%,transparent)] hover:text-[var(--editor-text)] hover:bg-[color-mix(in_srgb,var(--editor-text)_5%,transparent)]',
               )}
             >
               {selected && (

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