From ac72901e42b8375ab5e604c3a6f9c0c4fb522134 Mon Sep 17 00:00:00 2001
From: Patrick Lu <lightning.lu7@gmail.com>
Date: Tue, 8 Sep 2026 13:35:11 -0700
Subject: [PATCH 01/22] test(host): construct readonly timeline fixtures
 without push

---
 src/features/editor/host/controller.test.ts | 20 ++++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/src/features/editor/host/controller.test.ts b/src/features/editor/host/controller.test.ts
index f75d73205..aa0bd9be7 100644
--- a/src/features/editor/host/controller.test.ts
+++ b/src/features/editor/host/controller.test.ts
@@ -1907,10 +1907,13 @@ describe('gesture authority and recovery regressions', () => {
     const initial = snapshot()
     const anchor = initial.timeline.tracks[0]!.items[0]!
     Object.assign(anchor, { from: 10, sourceStart: 20, sourceEnd: 140, speed: 2 })
-    initial.timeline.tracks[0]!.items.push(
-      { ...anchor, id: 'next', from: 70, sourceStart: 0, sourceEnd: 120 },
-      { ...anchor, id: 'detached', from: 130, rippleLinked: false },
-    )
+    Object.assign(initial.timeline.tracks[0]!, {
+      items: [
+        ...initial.timeline.tracks[0]!.items,
+        { ...anchor, id: 'next', from: 70, sourceStart: 0, sourceEnd: 120 },
+        { ...anchor, id: 'detached', from: 130, rippleLinked: false },
+      ],
+    })
     const batch = trimIntentBatch(initial.timeline, 'clip-1', {
       handle: 'start',
       deltaFrames: 5,
@@ -1944,10 +1947,11 @@ describe('gesture authority and recovery regressions', () => {
 
 it('never interprets a new delete selection as a retry of an unknown earlier delete', async () => {
   const initial = snapshot()
-  initial.timeline.tracks[0]!.items.push({
-    ...initial.timeline.tracks[0]!.items[0]!,
-    id: 'clip-2',
-    from: 60,
+  Object.assign(initial.timeline.tracks[0]!, {
+    items: [
+      ...initial.timeline.tracks[0]!.items,
+      { ...initial.timeline.tracks[0]!.items[0]!, id: 'clip-2', from: 60 },
+    ],
   })
   const submitEdit = vi.fn(async () => {
     throw new Error('unknown outcome')

From dfad1cf03ab889c791c176cc0b9a04a85419f530 Mon Sep 17 00:00:00 2001
From: Patrick Lu <lightning.lu7@gmail.com>
Date: Tue, 8 Sep 2026 13:41:02 -0700
Subject: [PATCH 02/22] fix(host): hide local media transcription actions

---
 .../components/media-card.test.tsx            | 20 +++++++++++++++++++
 .../media-library/components/media-card.tsx   |  2 +-
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/src/features/media-library/components/media-card.test.tsx b/src/features/media-library/components/media-card.test.tsx
index b6a22d1b6..261cc8160 100644
--- a/src/features/media-library/components/media-card.test.tsx
+++ b/src/features/media-library/components/media-card.test.tsx
@@ -3,6 +3,13 @@ import { fireEvent, render, screen, waitFor } from '@testing-library/react'
 import type { MouseEvent, ReactNode } from 'react'
 import type { MediaMetadata } from '@/types/storage'
 
+const hostContextState = vi.hoisted(() => ({ hostMode: false }))
+
+vi.mock('../deps/editor', () => ({
+  useEditorHostMode: () => hostContextState.hostMode,
+  useEditorCapability: () => true,
+}))
+
 const mediaLibraryServiceMocks = vi.hoisted(() => ({
   getThumbnailBlobUrl: vi.fn(),
   getMediaFile: vi.fn(),
@@ -365,6 +372,7 @@ describe('MediaCard', () => {
   beforeEach(() => {
     vi.clearAllMocks()
     vi.useRealTimers()
+    hostContextState.hostMode = false
     mediaStoreState.selectedMediaIds = []
     mediaStoreState.mediaItems = [makeMedia()]
     mediaStoreState.importingIds = []
@@ -467,6 +475,18 @@ describe('MediaCard', () => {
     )
   })
 
+  it('hides local transcription actions in host mode even when transcription capability is enabled', () => {
+    hostContextState.hostMode = true
+    const { rerender } = render(<ListMediaCard media={makeMedia()} />)
+    expect(screen.queryByText('Generate Transcript')).not.toBeInTheDocument()
+    mediaStoreState.transcriptStatus = new Map([['media-1', 'ready']])
+    rerender(<ListMediaCard media={makeMedia()} />)
+    expect(screen.queryByText('Refresh Transcript')).not.toBeInTheDocument()
+    expect(screen.queryByText('Delete Transcript')).not.toBeInTheDocument()
+    expect(screen.queryByTestId('transcribe-dialog')).not.toBeInTheDocument()
+    expect(mediaTranscriptionRunnerMocks.runMediaTranscriptionJob).not.toHaveBeenCalled()
+  })
+
   it('uses transcript wording in the media action menu', () => {
     const { rerender } = render(<ListMediaCard media={makeMedia()} />)
     expect(screen.getByText('Generate Transcript')).toBeInTheDocument()
diff --git a/src/features/media-library/components/media-card.tsx b/src/features/media-library/components/media-card.tsx
index 9c60c68ad..f15865b94 100644
--- a/src/features/media-library/components/media-card.tsx
+++ b/src/features/media-library/components/media-card.tsx
@@ -710,7 +710,7 @@ const MediaCardInternal = memo(function MediaCardInternal({
 
   const mediaType = getMediaType(media.mimeType)
   const isTranscribable =
-    canTranscribeCapability && (mediaType === 'video' || mediaType === 'audio')
+    !hostMode && canTranscribeCapability && (mediaType === 'video' || mediaType === 'audio')
   const canGenerateProxy =
     canGenerateProxyCapability &&
     !hostMode &&

From f308ced62e44f64fd94e370ebb467ff83fe1324f Mon Sep 17 00:00:00 2001
From: Patrick Lu <lightning.lu7@gmail.com>
Date: Tue, 8 Sep 2026 13:57:41 -0700
Subject: [PATCH 03/22] fix(editor): preserve host focus and cancel hidden move
 gestures

---
 .../editor-workspace-shell.test.tsx           | 28 ++++++++
 .../components/editor-workspace-shell.tsx     |  6 +-
 .../timeline/hooks/use-timeline-drag.ts       | 12 ++++
 tests/browser/layout-refresh.spec.ts          | 46 ++++++++++++-
 tests/browser/layout-refresh.tsx              | 67 +++++++++++++++++--
 5 files changed, 152 insertions(+), 7 deletions(-)

diff --git a/src/features/editor/components/editor-workspace-shell.test.tsx b/src/features/editor/components/editor-workspace-shell.test.tsx
index e9a8953d8..8328e10ab 100644
--- a/src/features/editor/components/editor-workspace-shell.test.tsx
+++ b/src/features/editor/components/editor-workspace-shell.test.tsx
@@ -109,6 +109,34 @@ describe('editor workspace columns', () => {
       screen.getByRole('button', { name: 'editor.refresh.canvasSettings' }),
     )
   })
+  it('closes stale settings without stealing focus from the host chat', () => {
+    const workspace = (
+      <>
+        <textarea aria-label="Host chat" />
+        <EditorWorkspaceShell>
+          <div />
+        </EditorWorkspaceShell>
+      </>
+    )
+    const { rerender } = render(workspace)
+    fireEvent.click(screen.getByRole('button', { name: 'editor.refresh.clipSettings' }))
+    const chat = screen.getByRole('textbox', { name: 'Host chat' })
+    chat.focus()
+    selection.selectedItemIds = []
+    rerender(
+      <>
+        <textarea aria-label="Host chat" />
+        <EditorWorkspaceShell>
+          <div />
+        </EditorWorkspaceShell>
+      </>,
+    )
+    expect(screen.queryByRole('region', { name: 'editor.refresh.settings' })).toBeNull()
+    expect(document.activeElement).toBe(chat)
+    fireEvent.change(chat, { target: { value: 'continue the draft' } })
+    expect(chat).toHaveValue('continue the draft')
+  })
+
   it('resizes with keyboard without resetting the reading state', () => {
     render(
       <EditorWorkspaceShell>
diff --git a/src/features/editor/components/editor-workspace-shell.tsx b/src/features/editor/components/editor-workspace-shell.tsx
index 7b4d9c8cc..e9b37bf1a 100644
--- a/src/features/editor/components/editor-workspace-shell.tsx
+++ b/src/features/editor/components/editor-workspace-shell.tsx
@@ -37,6 +37,7 @@ export function EditorWorkspaceShell({
   const [settingsOpen, setSettingsOpen] = useState(false)
   const libraryToggleRef = useRef<HTMLButtonElement>(null)
   const settingsTrigger = useRef<HTMLButtonElement>(null)
+  const settingsPanel = useRef<HTMLElement>(null)
   const selectedIds = useSelectionStore((s) => s.selectedItemIds)
   const rootRef = useRef<HTMLDivElement>(null)
   useEffect(() => {
@@ -52,7 +53,9 @@ export function EditorWorkspaceShell({
     if (settingsOpen && settingsSelection.current.some((id) => !selectedIds.includes(id))) {
       setSettingsOpen(false)
       setSettingsNotice(true)
-      settingsTrigger.current?.focus()
+      if (settingsPanel.current?.contains(document.activeElement)) {
+        settingsTrigger.current?.focus()
+      }
     }
   }, [selectedIds, settingsOpen])
   const onLayoutChange = options?.onLayoutChange
@@ -216,6 +219,7 @@ export function EditorWorkspaceShell({
           )}
           {settingsOpen && (
             <section
+              ref={settingsPanel}
               role="region"
               aria-label={t('editor.refresh.settings')}
               className="absolute right-3 top-3 z-40 flex max-h-[55%] w-[320px] max-w-[calc(100%-24px)] flex-col overflow-hidden rounded-xl border border-border bg-card shadow-xl"
diff --git a/src/features/timeline/hooks/use-timeline-drag.ts b/src/features/timeline/hooks/use-timeline-drag.ts
index fe89e27de..541e0146b 100644
--- a/src/features/timeline/hooks/use-timeline-drag.ts
+++ b/src/features/timeline/hooks/use-timeline-drag.ts
@@ -1781,12 +1781,24 @@ export function useTimelineDrag(
         handleMouseUp()
       }
 
+      const handleEditorCollapse = (event: Event) => {
+        if (
+          elementRef?.current &&
+          (!(event.target instanceof Element) || !event.target.contains(elementRef.current))
+        )
+          return
+        coalescedMouseMove.cancel()
+        handleCancellation()
+      }
+
+      window.addEventListener('freecut:cancel-timeline-gesture', handleEditorCollapse)
       window.addEventListener('mousemove', coalescedMouseMove.queue)
       window.addEventListener('mouseup', handleCoalescedMouseUp)
       window.addEventListener('pointercancel', handleCancellation)
       window.addEventListener('keydown', handleKeyDown)
 
       return () => {
+        window.removeEventListener('freecut:cancel-timeline-gesture', handleEditorCollapse)
         window.removeEventListener('mousemove', coalescedMouseMove.queue)
         window.removeEventListener('mouseup', handleCoalescedMouseUp)
         window.removeEventListener('pointercancel', handleCancellation)
diff --git a/tests/browser/layout-refresh.spec.ts b/tests/browser/layout-refresh.spec.ts
index d085eddd4..8e5b39337 100644
--- a/tests/browser/layout-refresh.spec.ts
+++ b/tests/browser/layout-refresh.spec.ts
@@ -84,7 +84,9 @@ test('independent columns preserve draft/search and restore from every combinati
   await page.keyboard.press('Backspace')
   expect(await page.locator('[data-item-id]').count()).toBe(clipCount)
   expect(
-    await page.locator('video').evaluateAll((videos) => videos.every((video) => video.paused)),
+    await page
+      .locator('video')
+      .evaluateAll((videos) => videos.every((video) => (video as HTMLVideoElement).paused)),
   ).toBe(true)
   await page.getByRole('button', { name: 'Canvas settings', exact: true }).click()
   await expect(page.getByRole('region', { name: 'Settings', exact: true })).toBeVisible()
@@ -96,3 +98,45 @@ test('independent columns preserve draft/search and restore from every combinati
   await expect(page.getByRole('button', { name: 'Undo', exact: true })).toHaveCount(1)
   await expect(page.getByRole('button', { name: 'Redo', exact: true })).toHaveCount(1)
 })
+
+test('host removal closes stale settings without stealing chat focus', async ({ page }) => {
+  await page.goto('/tests/browser/layout-refresh.html')
+  const clip = page.locator('[data-timeline-item][data-item-id="retained-video"]').first()
+  await clip.click()
+  await page.getByRole('button', { name: 'Clip settings', exact: true }).click()
+  const chat = page.getByRole('textbox', { name: 'Chat draft' })
+  await chat.fill('Keep typing')
+  await page.evaluate(() => window.__layoutHarness.removeClip())
+  await expect(page.getByRole('region', { name: 'Settings', exact: true })).toHaveCount(0)
+  await expect(chat).toBeFocused()
+  await page.keyboard.type(' here')
+  await expect(chat).toHaveValue('Keep typing here')
+})
+
+test('actual Hide Editor cancels a held body move before late mouseup', async ({ page }) => {
+  await page.goto('/tests/browser/layout-refresh.html')
+  await page.getByRole('button', { name: 'Hide Library', exact: true }).click()
+  const clip = page.locator('[data-timeline-item][data-item-id="retained-video"]').first()
+  await clip.waitFor()
+  const bounds = await clip.boundingBox()
+  const x = bounds!.x + Math.min(bounds!.width / 2, 80)
+  const y = bounds!.y + bounds!.height / 2
+  await page.mouse.move(x, y)
+  await page.mouse.down()
+  await page.mouse.move(x + 110, y, { steps: 6 })
+  await expect
+    .poll(() => clip.evaluate((element) => (element.parentElement as HTMLElement).style.transform))
+    .not.toBe('')
+  await expect.poll(() => page.evaluate(() => window.__layoutHarness.state().dragging)).toBe(true)
+  await page.getByRole('button', { name: 'Hide Editor', exact: true }).focus()
+  await page.keyboard.press('Enter')
+  await expect(page.locator('[data-editor-column="editor"]')).toBeHidden()
+  await expect.poll(() => page.evaluate(() => window.__layoutHarness.state().dragging)).toBe(false)
+  await page.getByRole('button', { name: 'Show Editor', exact: true }).focus()
+  await page.keyboard.press('Enter')
+  await page.mouse.up()
+  await expect(clip).toBeVisible()
+  const state = await page.evaluate(() => window.__layoutHarness.state())
+  expect(state.submitCount).toBe(0)
+  expect(state.snapshot.timeline.tracks[0]!.items[0]!.from).toBe(0)
+})
diff --git a/tests/browser/layout-refresh.tsx b/tests/browser/layout-refresh.tsx
index 958f63419..6162d8c60 100644
--- a/tests/browser/layout-refresh.tsx
+++ b/tests/browser/layout-refresh.tsx
@@ -1,8 +1,18 @@
 // fallow-ignore-file unused-file
 import { useState } from 'react'
+import { useSelectionStore } from '../../src/shared/state/selection'
 import { createRoot } from 'react-dom/client'
 import { FreeCutEditorSurface } from '../../src/features/editor/host/editor-surface'
-import type { EditorHost, EmbeddedEditorSnapshot } from '../../src/features/editor/host/contract'
+import {
+  DEFAULT_HOST_CAPABILITIES,
+  type EditorHost,
+  type EmbeddedEditorSnapshot,
+} from '../../src/features/editor/host/contract'
+import {
+  createCodePressCommandAdapter,
+  freeCutDocumentToControlledDocument,
+  controlledDocumentToFreeCutDocument,
+} from '../../src/features/editor/codepress'
 
 const MEDIA_ID = 'generated-av'
 const ITEM_ID = 'retained-video'
@@ -79,10 +89,14 @@ function snapshot(
 
 let currentSnapshot = snapshot(0, 0, 60)
 let loadCount = 0
+let submitCount = 0
+let adapter = createCodePressCommandAdapter({
+  document: freeCutDocumentToControlledDocument(currentSnapshot.timeline),
+})
 const listeners = new Set<(value: EmbeddedEditorSnapshot) => void>()
 
 const host: EditorHost = {
-  capabilities: { 'media.resolve': true, 'media.transcription': true },
+  capabilities: { ...DEFAULT_HOST_CAPABILITIES, 'media.transcription': true },
   transcript: {
     getStatus: () => ({
       transcriptId: 'layout-transcript',
@@ -124,8 +138,16 @@ const host: EditorHost = {
     return currentSnapshot
   },
   resolveMedia: ({ mediaId }) => (mediaId === MEDIA_ID ? { source: MEDIA_SOURCE } : null),
-  submitEdit: () => {
-    throw new Error('The source-range fixture does not submit edits')
+  submitEdit: (batch) => {
+    submitCount += 1
+    const result = adapter.apply(batch)
+    if (result.status === 'rejected')
+      return { status: 'rejected', snapshot: currentSnapshot, result }
+    currentSnapshot = {
+      ...currentSnapshot,
+      timeline: controlledDocumentToFreeCutDocument(adapter.getDocument()),
+    }
+    return { status: result.status, snapshot: currentSnapshot, result }
   },
   subscribe: (listener) => {
     listeners.add(listener)
@@ -133,7 +155,42 @@ const host: EditorHost = {
   },
 }
 
-function LayoutReview() {
+declare global {
+  interface Window {
+    __layoutHarness: {
+      state(): { snapshot: EmbeddedEditorSnapshot; submitCount: number; dragging: boolean }
+      removeClip(): void
+    }
+  }
+}
+window.__layoutHarness = {
+  state: () => ({
+    snapshot: currentSnapshot,
+    submitCount,
+    dragging: useSelectionStore.getState().dragState?.isDragging === true,
+  }),
+  removeClip: () => {
+    currentSnapshot = {
+      ...currentSnapshot,
+      timeline: {
+        ...currentSnapshot.timeline,
+        revision: currentSnapshot.timeline.revision + 1,
+        tracks: currentSnapshot.timeline.tracks.map(
+          (track: EmbeddedEditorSnapshot['timeline']['tracks'][number]) => ({
+            ...track,
+            items: [],
+          }),
+        ),
+      },
+    }
+    adapter = createCodePressCommandAdapter({
+      document: freeCutDocumentToControlledDocument(currentSnapshot.timeline),
+    })
+    listeners.forEach((listener) => listener(currentSnapshot))
+  },
+}
+
+export function LayoutReview() {
   const [chatOpen, setChatOpen] = useState(true)
   return (
     <div style={{ height: '100vh', display: 'flex', flexDirection: 'column' }}>

From d12d5dd88bddd3d09b6b4568938355ddd7a36ce0 Mon Sep 17 00:00:00 2001
From: Patrick Lu <lightning.lu7@gmail.com>
Date: Tue, 8 Sep 2026 13:25:49 -0700
Subject: [PATCH 04/22] feat(transcript): define provider word occurrence
 contract

---
 packages/freecut-editor/src/index.d.ts        |  13 ++
 packages/freecut-editor/src/index.ts          |   1 +
 src/features/editor/host/contract.ts          |  13 ++
 src/features/editor/host/index.ts             |   1 +
 .../editor/host/transcript-words.test.ts      | 114 ++++++++++++++++++
 src/features/editor/host/transcript-words.ts  |  89 ++++++++++++++
 6 files changed, 231 insertions(+)
 create mode 100644 src/features/editor/host/transcript-words.test.ts
 create mode 100644 src/features/editor/host/transcript-words.ts

diff --git a/packages/freecut-editor/src/index.d.ts b/packages/freecut-editor/src/index.d.ts
index c004af42a..bf3f6628b 100644
--- a/packages/freecut-editor/src/index.d.ts
+++ b/packages/freecut-editor/src/index.d.ts
@@ -304,7 +304,16 @@ export interface HostTranscriptStatusReceipt {
   error?: HostTranscriptError | null
 }
 
+/** Only measured provider timings are eligible for word editing. */
+export interface HostTranscriptWord {
+  startUs: Microseconds
+  endUs: Microseconds
+  text: string
+}
+
 export interface HostTranscriptSection {
+  timingSource?: 'provider' | 'synthetic'
+  words?: readonly HostTranscriptWord[] | null
   id: string
   transcriptId: string
   ordinal: number
@@ -345,6 +354,8 @@ export interface HostTranscriptSearchPage {
 }
 
 export interface HostTranscriptRange {
+  /** Exact sequence occurrence; omitted retains legacy all-occurrences behavior. */
+  itemId?: string
   startUs: number
   endUs: number
   text?: string
@@ -391,6 +402,8 @@ export interface HostTranscriptCommandPreview {
 }
 
 export interface EditorTranscriptPort {
+  /** Explicit opt-in: this host validates range.itemId and never broadens its scope. */
+  occurrenceSelection?: boolean
   getStatus(): Promise<HostTranscriptStatusReceipt | null> | HostTranscriptStatusReceipt | null
   requestTranscription?(input: {
     assetId: string
diff --git a/packages/freecut-editor/src/index.ts b/packages/freecut-editor/src/index.ts
index b7ced84a9..b29a843fd 100644
--- a/packages/freecut-editor/src/index.ts
+++ b/packages/freecut-editor/src/index.ts
@@ -48,6 +48,7 @@ export type {
   HostTranscriptSearchPage,
   HostTranscriptSearchRequest,
   HostTranscriptSection,
+  HostTranscriptWord,
   HostTranscriptSectionsPage,
   HostTranscriptSectionsRequest,
   HostTranscriptStatus,
diff --git a/src/features/editor/host/contract.ts b/src/features/editor/host/contract.ts
index d291e3d65..7ce8f8783 100644
--- a/src/features/editor/host/contract.ts
+++ b/src/features/editor/host/contract.ts
@@ -198,7 +198,16 @@ export interface HostTranscriptStatusReceipt {
 }
 
 /** One bounded, source-addressable transcript section. */
+/** Only measured provider timings are eligible for word editing. */
+export interface HostTranscriptWord {
+  startUs: Microseconds
+  endUs: Microseconds
+  text: string
+}
+
 export interface HostTranscriptSection {
+  timingSource?: 'provider' | 'synthetic'
+  words?: readonly HostTranscriptWord[] | null
   id: string
   transcriptId: string
   ordinal: number
@@ -240,6 +249,8 @@ export interface HostTranscriptSearchPage {
 
 /** A positive integer-microsecond source range selected for preview. */
 export interface HostTranscriptRange {
+  /** Exact sequence occurrence; omitted retains legacy all-occurrences behavior. */
+  itemId?: string
   startUs: Microseconds
   endUs: Microseconds
   text?: string
@@ -292,6 +303,8 @@ export interface HostTranscriptCommandPreview {
  * those details never enter the FreeCut surface.
  */
 export interface EditorTranscriptPort {
+  /** Explicit opt-in: this host validates range.itemId and never broadens its scope. */
+  occurrenceSelection?: boolean
   getStatus(): Promise<HostTranscriptStatusReceipt | null> | HostTranscriptStatusReceipt | null
   /**
    * Optional host-owned transcription start.  The host performs the work and
diff --git a/src/features/editor/host/index.ts b/src/features/editor/host/index.ts
index ad2645826..4a03b45a4 100644
--- a/src/features/editor/host/index.ts
+++ b/src/features/editor/host/index.ts
@@ -49,6 +49,7 @@ export type {
   HostTranscriptSearchPage,
   HostTranscriptSearchRequest,
   HostTranscriptSection,
+  HostTranscriptWord,
   HostTranscriptSectionsPage,
   HostTranscriptSectionsRequest,
   HostTranscriptStatus,
diff --git a/src/features/editor/host/transcript-words.test.ts b/src/features/editor/host/transcript-words.test.ts
new file mode 100644
index 000000000..6274a0fa7
--- /dev/null
+++ b/src/features/editor/host/transcript-words.test.ts
@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'vite-plus/test'
+import type { FreeCutFrameDocument, FreeCutFrameClip } from '../codepress/document'
+import type { HostTranscriptSection } from './contract'
+import { hostWordSelectionRanges, mapHostTranscriptWords } from './transcript-words'
+
+const section: HostTranscriptSection = {
+  id: 'section',
+  transcriptId: 'transcript',
+  ordinal: 0,
+  startUs: 0,
+  endUs: 3_000_000,
+  text: 'hello um world',
+  timingSource: 'provider',
+  words: [
+    { text: 'hello', startUs: 0, endUs: 500_000 },
+    { text: 'um', startUs: 1_000_000, endUs: 1_200_000 },
+    { text: 'world', startUs: 2_000_000, endUs: 3_000_000 },
+  ],
+}
+function document(clips: FreeCutFrameClip[]): FreeCutFrameDocument {
+  return {
+    timelineId: 'timeline',
+    revision: 7,
+    fps: 30,
+    width: 1280,
+    height: 720,
+    durationInFrames: 300,
+    media: [],
+    tracks: [
+      { id: 'video', kind: 'video', name: 'Video', locked: false, muted: false, items: clips },
+    ],
+  }
+}
+const clip: FreeCutFrameClip = {
+  type: 'video',
+  id: 'a',
+  mediaId: 'media',
+  trackId: 'video',
+  from: 0,
+  durationInFrames: 90,
+  sourceStart: 0,
+  sourceEnd: 90,
+}
+
+describe('host word occurrence mapping', () => {
+  it('retains repeated occurrences, clamps trims and maps speed without quantizing provider words', () => {
+    const words = mapHostTranscriptWords(
+      document([
+        clip,
+        {
+          ...clip,
+          id: 'b',
+          from: 100,
+          sourceStart: 33,
+          sourceEnd: 90,
+          durationInFrames: 38,
+          speed: 1.5,
+        },
+      ]),
+      'media',
+      [section],
+    )
+    expect(words.map((word) => word.key)).toEqual([
+      'a:section:0',
+      'a:section:1',
+      'a:section:2',
+      'b:section:1',
+      'b:section:2',
+    ])
+    expect(words[3]).toMatchObject({
+      revision: 7,
+      itemId: 'b',
+      sourceStartUs: 1_000_000,
+      startFrame: 100,
+      endFrame: 102,
+    })
+    expect(hostWordSelectionRanges(words.slice(1, 2))).toEqual([
+      { itemId: 'a', startUs: 1_000_000, endUs: 1_200_000, text: 'um' },
+    ])
+    expect(hostWordSelectionRanges(words.slice(2, 4)).map((range) => range.itemId)).toEqual([
+      'a',
+      'b',
+    ])
+  })
+  it('only deduplicates proven linked same-source/time representations', () => {
+    const words = mapHostTranscriptWords(
+      document([
+        { ...clip, linkedGroupId: 'group' },
+        { ...clip, id: 'audio', type: 'audio', linkedGroupId: 'group' },
+        { ...clip, id: 'independent', type: 'audio' },
+        { ...clip, id: 'different-time', from: 100, linkedGroupId: 'group' },
+      ]),
+      'media',
+      [section],
+    )
+    expect([...new Set(words.map((word) => word.itemId))]).toEqual([
+      'a',
+      'independent',
+      'different-time',
+    ])
+  })
+  it('never invents word timing from legacy or synthetic sections and leaves gaps inactive', () => {
+    expect(
+      mapHostTranscriptWords(document([clip]), 'media', [
+        { ...section, timingSource: 'synthetic' },
+      ]),
+    ).toEqual([])
+    expect(
+      mapHostTranscriptWords(document([clip]), 'media', [{ ...section, words: null }]),
+    ).toEqual([])
+    const words = mapHostTranscriptWords(document([clip]), 'media', [section])
+    expect(words.find((word) => 20 >= word.startFrame && 20 < word.endFrame)).toBeUndefined()
+  })
+})
diff --git a/src/features/editor/host/transcript-words.ts b/src/features/editor/host/transcript-words.ts
new file mode 100644
index 000000000..a8246b3e6
--- /dev/null
+++ b/src/features/editor/host/transcript-words.ts
@@ -0,0 +1,89 @@
+import type { FreeCutFrameDocument } from '../codepress/document'
+import { framesToMicroseconds } from '../codepress/timing'
+import type { HostTranscriptRange, HostTranscriptSection } from './contract'
+
+export interface HostWordOccurrence {
+  key: string
+  itemId: string
+  sectionId: string
+  revision: number
+  text: string
+  sourceStartUs: number
+  sourceEndUs: number
+  /** Unrounded frame coordinates; quantization belongs to the command boundary. */
+  startFrame: number
+  endFrame: number
+}
+
+/** Project source words into the current edit, retaining each distinct occurrence. */
+export function mapHostTranscriptWords(
+  document: FreeCutFrameDocument,
+  assetId: string,
+  sections: readonly HostTranscriptSection[],
+): HostWordOccurrence[] {
+  const words: HostWordOccurrence[] = []
+  const linked = new Set<string>()
+  const clips = document.tracks
+    .flatMap((track) => track.items)
+    .filter((item) => (item.type === 'video' || item.type === 'audio') && item.mediaId === assetId)
+    .sort((a, b) => Number(a.type !== 'video') - Number(b.type !== 'video'))
+  for (const clip of clips) {
+    if (clip.type !== 'video' && clip.type !== 'audio') continue
+    const cohort = clip.linkedGroupId
+      ? `${clip.linkedGroupId}:${clip.mediaId}:${clip.from}:${clip.durationInFrames}:${clip.sourceStart}:${clip.sourceEnd}:${clip.speed ?? 1}`
+      : null
+    if (cohort && linked.has(cohort)) continue
+    if (cohort) linked.add(cohort)
+    const sourceStart = framesToMicroseconds(clip.sourceStart ?? 0, document.fps)
+    const sourceEnd = framesToMicroseconds(
+      clip.sourceEnd ?? (clip.sourceStart ?? 0) + clip.durationInFrames * (clip.speed ?? 1),
+      document.fps,
+    )
+    if (sourceEnd <= sourceStart) continue
+    for (const section of sections) {
+      if (section.timingSource !== 'provider') continue
+      section.words?.forEach((word, index) => {
+        if (word.endUs <= sourceStart || word.startUs >= sourceEnd) return
+        const start = Math.max(sourceStart, word.startUs)
+        const end = Math.min(sourceEnd, word.endUs)
+        words.push({
+          key: `${clip.id}:${section.id}:${index}`,
+          itemId: clip.id,
+          sectionId: section.id,
+          revision: document.revision,
+          text: word.text,
+          // Preserve the measured word boundaries. The backend intersects the trim.
+          sourceStartUs: word.startUs,
+          sourceEndUs: word.endUs,
+          startFrame:
+            clip.from + ((start - sourceStart) / (sourceEnd - sourceStart)) * clip.durationInFrames,
+          endFrame:
+            clip.from + ((end - sourceStart) / (sourceEnd - sourceStart)) * clip.durationInFrames,
+        })
+      })
+    }
+  }
+  return words.sort((a, b) => a.startFrame - b.startFrame)
+}
+
+/** Adjacent selected words merge only within the same occurrence. */
+export function hostWordSelectionRanges(
+  words: readonly HostWordOccurrence[],
+): HostTranscriptRange[] {
+  const ranges: HostTranscriptRange[] = []
+  for (const word of words) {
+    const previous = ranges.at(-1)
+    if (previous?.itemId === word.itemId) {
+      previous.endUs = Math.max(previous.endUs, word.sourceEndUs)
+      previous.text += ` ${word.text}`
+    } else {
+      ranges.push({
+        itemId: word.itemId,
+        startUs: word.sourceStartUs,
+        endUs: word.sourceEndUs,
+        text: word.text,
+      })
+    }
+  }
+  return ranges
+}

From 5291f83bdfba08bdb58ee71148fb3d4b54b7d0a0 Mon Sep 17 00:00:00 2001
From: Patrick Lu <lightning.lu7@gmail.com>
Date: Tue, 8 Sep 2026 13:27:54 -0700
Subject: [PATCH 05/22] fix(transcript): retain disjoint word selection
 boundaries

---
 src/features/editor/host/transcript-words.test.ts |  1 +
 src/features/editor/host/transcript-words.ts      | 10 +++++++++-
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/src/features/editor/host/transcript-words.test.ts b/src/features/editor/host/transcript-words.test.ts
index 6274a0fa7..6ca900366 100644
--- a/src/features/editor/host/transcript-words.test.ts
+++ b/src/features/editor/host/transcript-words.test.ts
@@ -110,5 +110,6 @@ describe('host word occurrence mapping', () => {
     ).toEqual([])
     const words = mapHostTranscriptWords(document([clip]), 'media', [section])
     expect(words.find((word) => 20 >= word.startFrame && 20 < word.endFrame)).toBeUndefined()
+    expect(hostWordSelectionRanges([words[0]!, words[2]!])).toHaveLength(2)
   })
 })
diff --git a/src/features/editor/host/transcript-words.ts b/src/features/editor/host/transcript-words.ts
index a8246b3e6..db208fb28 100644
--- a/src/features/editor/host/transcript-words.ts
+++ b/src/features/editor/host/transcript-words.ts
@@ -5,6 +5,7 @@ import type { HostTranscriptRange, HostTranscriptSection } from './contract'
 export interface HostWordOccurrence {
   key: string
   itemId: string
+  wordIndex: number
   sectionId: string
   revision: number
   text: string
@@ -49,6 +50,7 @@ export function mapHostTranscriptWords(
         words.push({
           key: `${clip.id}:${section.id}:${index}`,
           itemId: clip.id,
+          wordIndex: index,
           sectionId: section.id,
           revision: document.revision,
           text: word.text,
@@ -71,9 +73,14 @@ export function hostWordSelectionRanges(
   words: readonly HostWordOccurrence[],
 ): HostTranscriptRange[] {
   const ranges: HostTranscriptRange[] = []
+  let previousWord: HostWordOccurrence | undefined
   for (const word of words) {
     const previous = ranges.at(-1)
-    if (previous?.itemId === word.itemId) {
+    if (
+      previous?.itemId === word.itemId &&
+      previousWord?.sectionId === word.sectionId &&
+      previousWord.wordIndex + 1 === word.wordIndex
+    ) {
       previous.endUs = Math.max(previous.endUs, word.sourceEndUs)
       previous.text += ` ${word.text}`
     } else {
@@ -84,6 +91,7 @@ export function hostWordSelectionRanges(
         text: word.text,
       })
     }
+    previousWord = word
   }
   return ranges
 }

From 2ba64616ec12127320ac940c3aca9c5b14f25a6b Mon Sep 17 00:00:00 2001
From: Patrick Lu <lightning.lu7@gmail.com>
Date: Tue, 8 Sep 2026 13:34:35 -0700
Subject: [PATCH 06/22] fix(transcript): reject incomplete provider word
 coverage

---
 packages/freecut-editor/src/index.d.ts       |  4 ++--
 src/features/editor/host/transcript-words.ts | 24 +++++++++++++++++++-
 2 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/packages/freecut-editor/src/index.d.ts b/packages/freecut-editor/src/index.d.ts
index bf3f6628b..4c2cd2551 100644
--- a/packages/freecut-editor/src/index.d.ts
+++ b/packages/freecut-editor/src/index.d.ts
@@ -306,8 +306,8 @@ export interface HostTranscriptStatusReceipt {
 
 /** Only measured provider timings are eligible for word editing. */
 export interface HostTranscriptWord {
-  startUs: Microseconds
-  endUs: Microseconds
+  startUs: number
+  endUs: number
   text: string
 }
 
diff --git a/src/features/editor/host/transcript-words.ts b/src/features/editor/host/transcript-words.ts
index db208fb28..a10812ab2 100644
--- a/src/features/editor/host/transcript-words.ts
+++ b/src/features/editor/host/transcript-words.ts
@@ -16,6 +16,28 @@ export interface HostWordOccurrence {
   endFrame: number
 }
 
+/** Fail closed on partial, synthetic or malformed word data, including direct mapper callers. */
+export function hasUsableHostWordTiming(section: HostTranscriptSection): boolean {
+  if (section.timingSource !== 'provider' || !section.words?.length || section.words.length > 2000)
+    return false
+  let previousEnd = section.startUs
+  for (const word of section.words) {
+    if (
+      !Number.isSafeInteger(word.startUs) ||
+      !Number.isSafeInteger(word.endUs) ||
+      word.startUs < previousEnd ||
+      word.endUs <= word.startUs ||
+      word.endUs > section.endUs ||
+      typeof word.text !== 'string' ||
+      !word.text.trim()
+    )
+      return false
+    previousEnd = word.endUs
+  }
+  const normalize = (text: string) => text.replace(/[\s\p{P}]/gu, '').toLocaleLowerCase()
+  return normalize(section.words.map((word) => word.text).join(' ')) === normalize(section.text)
+}
+
 /** Project source words into the current edit, retaining each distinct occurrence. */
 export function mapHostTranscriptWords(
   document: FreeCutFrameDocument,
@@ -42,7 +64,7 @@ export function mapHostTranscriptWords(
     )
     if (sourceEnd <= sourceStart) continue
     for (const section of sections) {
-      if (section.timingSource !== 'provider') continue
+      if (!hasUsableHostWordTiming(section)) continue
       section.words?.forEach((word, index) => {
         if (word.endUs <= sourceStart || word.startUs >= sourceEnd) return
         const start = Math.max(sourceStart, word.startUs)

From d242bf3d9e4667e58689dbbfcfa70b72fd4e03c3 Mon Sep 17 00:00:00 2001
From: Patrick Lu <lightning.lu7@gmail.com>
Date: Tue, 8 Sep 2026 13:49:30 -0700
Subject: [PATCH 07/22] feat(transcript): cut selected word occurrences
 immediately

---
 docs/qa/ux7144-word-editing.md                |  60 +++
 .../editor/host/transcript-editor.test.tsx    |  73 ++++
 .../editor/host/transcript-editor.tsx         | 360 +++++++++++-------
 .../editor/host/transcript-word-view.tsx      | 278 ++++++++++++++
 .../editor/host/transcript-words.test.ts      |  18 +
 src/features/editor/host/transcript-words.ts  |  70 ++--
 .../transcript-editor-panel.tsx               | 187 +++++----
 .../actions/edit/range-removal-actions.ts     |  84 +++-
 .../actions/range-removal-actions.test.ts     |  58 ++-
 src/features/timeline/types.ts                |   1 +
 .../utils/transcript-edit-model.test.ts       |  11 +-
 .../timeline/utils/transcript-edit-model.ts   |  47 +--
 src/shared/utils/transcript-selection.ts      |  19 +
 13 files changed, 988 insertions(+), 278 deletions(-)
 create mode 100644 docs/qa/ux7144-word-editing.md
 create mode 100644 src/features/editor/host/transcript-word-view.tsx
 create mode 100644 src/shared/utils/transcript-selection.ts

diff --git a/docs/qa/ux7144-word-editing.md b/docs/qa/ux7144-word-editing.md
new file mode 100644
index 000000000..296c9cb2f
--- /dev/null
+++ b/docs/qa/ux7144-word-editing.md
@@ -0,0 +1,60 @@
+# Word editing — #7144 PR4
+
+This source change is stacked on FreeCut PR38 (`ux7144-03-reliability`,
+6c11e173656b7b00b2c418784959dbc4e0a71803). Its consumer companion is stacked on
+CodePress PR7147 (a69438dc447c913f47f1af28aeb05ca54630f58f). The parent owns
+package adoption, the 0.3.12 vendor patch, asset guards, and aggregate QA.
+No package version was changed or published for this work.
+
+Provider words remain immutable source data. The host contract adds measured
+`words`, `timingSource`, per-range `itemId`, and the `occurrenceSelection` opt-in.
+The source mapper rejects synthetic, malformed, or partial word coverage. It
+projects each occurrence through source trims and speed into unrounded sequence
+frames; the backend quantizes once to the nearest rational project-frame
+boundary (half up) and rejects zero-frame cuts. Only proven linked same-source,
+same-time representations are deduplicated. Sparse word selections do not merge
+across unselected words.
+
+The host view seeks/selects words, extends by drag/Shift or keyboard, cuts
+immediately through preview + one controller submission, and derives remaining
+words from authoritative occurrences. Selection binds to document revision and
+transcript/source identity. Older hosts can seek but cannot cut words. Playback
+highlight is separate from selection; gaps clear it, and manual reading
+suspends following until Resume following. Standalone defaults to the whole
+edit and uses its existing single undoable split/ripple operation with ranges
+keyed by occurrence. Linked media cut together even if clip linked-selection is
+disabled. Lock and transition/frame preflight run before mutation.
+
+Validation performed in this isolated worktree:
+
+- Focused host UI/mapping, standalone mapping/range removal tests (including
+  repeated sources, linked audio, undo/redo, disjoint source ranges, and gaps).
+- Browser fixtures for host: click seek/select, Backspace cuts one repeat,
+  local fixture persistence after reload, undo restoration, active-word gap,
+  follow suspend/resume, Shift+arrow selection, adjacent textarea Backspace,
+  section-only fallback, and old-host capability denial; no page errors.
+- Browser fixture for standalone: whole-edit default, real store Backspace
+  footage cut, repeated source preserved, one undo restores words/footage;
+  no page errors.
+- Source boundary/dependency/edge/unused-export checks, package build and
+  installed-package consumer smoke tests. Changed-health passes against the
+  actual PR38 base. Full source check encounters PR38's two inherited readonly
+  fixture `.push` errors in controller.test.ts; parent owns their test-only fix.
+
+Browser fixture artifacts and scripts remain in this worker's ignored
+`tmp/ux7144-pr4/` directory: host-selection.png, host-legacy.png,
+host-narrow.png, standalone.png, browser.mjs, standalone-browser.mjs and TSX
+fixtures. These use manually specified timing fixtures, not claimed provider
+transcription runs. The host persistence/undo transport is a fixture; it is not
+an authenticated CodePress session or durable backend-history browser proof.
+Backend companion tests separately exercise real atomic preview/apply in a
+worker-owned disposable Postgres instance. No live-project transcription or
+media upload request was made.
+
+Explicit follow-ups agreed with the parent: mixed-source host transcript
+batching (current source is labeled), durable text correction, and a real
+regenerate/align/cache-bypass path. Existing Generate transcript can reuse a
+cached transcript; Start over does not supply missing words. Audio listening,
+authenticated aggregate CodePress playback/reload, and the unprompted user
+usability session remain integration evidence gaps. Caption design/export is
+PR5's scope.
diff --git a/src/features/editor/host/transcript-editor.test.tsx b/src/features/editor/host/transcript-editor.test.tsx
index 087f7c3df..363d0acec 100644
--- a/src/features/editor/host/transcript-editor.test.tsx
+++ b/src/features/editor/host/transcript-editor.test.tsx
@@ -21,6 +21,7 @@ import {
   type EditCommandBatch,
 } from '@/features/editor/codepress'
 import { useEditorStore } from '@/shared/state/editor'
+import { usePlaybackStore } from '@/shared/state/playback'
 import { MediaSidebar } from '../components/media-sidebar'
 import { EditorHostProvider } from './context-provider'
 import {
@@ -68,6 +69,7 @@ const sections: HostTranscriptSection[] = [
     startUs: 1_000_000,
     endUs: 2_000_000,
     text: 'First bounded caption.',
+    timingSource: 'provider',
     speaker: 'Speaker 1',
   },
   {
@@ -77,6 +79,7 @@ const sections: HostTranscriptSection[] = [
     startUs: 4_000_000,
     endUs: 5_000_000,
     text: 'Second bounded caption.',
+    timingSource: 'provider',
     speaker: 'Speaker 1',
   },
 ]
@@ -326,6 +329,76 @@ afterEach(() => {
 })
 
 describe('host-backed transcript consumer', () => {
+  it('selects provider words, seeks, suspends follow and immediately submits one occurrence cut', async () => {
+    const initial = snapshot()
+    initial.timeline.media = [
+      {
+        media_id: 'asset-1',
+        media_kind: 'video',
+        content_hash: 'sha256:source-1',
+        duration_us: 10_000_000,
+        availability: { mode: 'cloud', cloud: { object_id: 'object-1' } },
+      },
+    ]
+    initial.timeline.tracks = [
+      {
+        id: 'video',
+        name: 'Video',
+        kind: 'video',
+        locked: false,
+        muted: false,
+        items: [
+          {
+            type: 'video',
+            id: 'occurrence-a',
+            trackId: 'video',
+            mediaId: 'asset-1',
+            from: 0,
+            durationInFrames: 300,
+            sourceStart: 0,
+            sourceEnd: 300,
+          },
+        ],
+      },
+    ]
+    const harness = createHarness(initial)
+    harness.host.transcript!.occurrenceSelection = true
+    harness.host.transcript!.getSections = () => ({
+      transcriptId: 'transcript-1',
+      hasMore: false,
+      sections: [
+        {
+          ...sections[0]!,
+          timingSource: 'provider',
+          words: [
+            { text: 'First', startUs: 1_000_000, endUs: 1_300_000 },
+            { text: 'bounded', startUs: 1_400_000, endUs: 1_700_000 },
+            { text: 'caption.', startUs: 1_800_000, endUs: 2_000_000 },
+          ],
+        },
+      ],
+    })
+    renderHostEditor(harness)
+    const first = await screen.findByRole('button', { name: 'First' })
+    fireEvent.pointerDown(first)
+    expect(usePlaybackStore.getState().currentFrame).toBe(30)
+    expect(screen.getByRole('button', { name: 'Resume following' })).toBeInTheDocument()
+    const region = screen.getByRole('region', { name: 'Timed transcript words' })
+    fireEvent.keyDown(region, { key: 'ArrowRight', shiftKey: true })
+    expect(screen.getByRole('button', { name: 'bounded' })).toHaveAttribute('aria-pressed', 'true')
+    fireEvent.keyDown(region, { key: 'Backspace' })
+    await waitFor(() => expect(harness.submitEdit).toHaveBeenCalledTimes(1))
+    expect(harness.previewCommands).toHaveBeenCalledWith(
+      expect.objectContaining({
+        baseRevision: 0,
+        ranges: [
+          { itemId: 'occurrence-a', startUs: 1_000_000, endUs: 1_700_000, text: 'First bounded' },
+        ],
+      }),
+    )
+    expect(screen.queryByTestId('host-transcript-apply')).not.toBeInTheDocument()
+  })
+
   it('displays bounded sections, previews without mutation, then applies through submitEdit', async () => {
     const harness = createHarness(snapshot())
     renderHostEditor(harness)
diff --git a/src/features/editor/host/transcript-editor.tsx b/src/features/editor/host/transcript-editor.tsx
index bf9056681..4f134f1c8 100644
--- a/src/features/editor/host/transcript-editor.tsx
+++ b/src/features/editor/host/transcript-editor.tsx
@@ -36,6 +36,8 @@ import {
 } from './contract'
 import { useEditorHostContext } from './context'
 import { useHostTranscriptEditorRuntime } from './transcript-editor-context'
+import { HostTranscriptWordView } from './transcript-word-view'
+import { hasUsableHostWordTiming } from './transcript-words'
 
 const OPAQUE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u
 const SAFE_HASH_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u
@@ -249,9 +251,35 @@ function normalizeSection(value: unknown, expectedTranscriptId: string): HostTra
     endUs: endUs as number,
     text,
     speaker: speaker ?? null,
+    timingSource: value.timingSource === 'provider' ? 'provider' : 'synthetic',
+    words: normalizeWords(value.words, startUs as number, endUs as number),
   }
 }
 
+function normalizeWords(
+  value: unknown,
+  sectionStart: number,
+  sectionEnd: number,
+): HostTranscriptSection['words'] {
+  if (value === undefined || value === null) return null
+  if (!Array.isArray(value) || value.length > 2000) throw new Error('Invalid transcript words.')
+  let previousEnd = sectionStart
+  return value.map((raw) => {
+    if (!isRecord(raw) || !boundedText(raw.text, MAX_TRANSCRIPT_SECTION_TEXT_BYTES))
+      throw new Error('Invalid transcript word text.')
+    const startUs = raw.startUs
+    const endUs = raw.endUs
+    if (typeof startUs !== 'number' || typeof endUs !== 'number')
+      throw new Error('Invalid transcript word timing.')
+    if (![startUs, endUs].every(Number.isSafeInteger))
+      throw new Error('Invalid transcript word timing.')
+    if (startUs < previousEnd || endUs <= startUs || endUs > sectionEnd)
+      throw new Error('Invalid transcript word bounds.')
+    previousEnd = endUs
+    return { startUs, endUs, text: raw.text }
+  })
+}
+
 // fallow-ignore-next-line complexity
 function normalizePage(value: unknown, expectedTranscriptId: string): NormalizedPage {
   if (!isRecord(value) || value.transcriptId !== expectedTranscriptId) {
@@ -702,7 +730,10 @@ export function HostTranscriptEditor({ active = true }: { active?: boolean }) {
 
   const previewSelection = useCallback(
     // fallow-ignore-next-line complexity
-    async (action: HostTranscriptCommandAction) => {
+    async (
+      action: HostTranscriptCommandAction,
+      wordSelection?: { ranges: HostTranscriptRange[]; revision: number },
+    ) => {
       if (!port || !runtime || !status || status.status !== 'succeeded' || previewing) return
       if (!isOpaqueId(status.assetId)) {
         setError({
@@ -718,8 +749,25 @@ export function HostTranscriptEditor({ active = true }: { active?: boolean }) {
       setError(null)
       setAnnouncement('Preparing a non-mutating transcript preview…')
       try {
-        const ranges = rangesForSelection(selectedSections)
+        if (
+          !wordSelection &&
+          selectedSections.some((section) => section.timingSource !== 'provider')
+        ) {
+          throw new Error(
+            'Measured section timing is needed before footage can be cut or captioned.',
+          )
+        }
+        const ranges = wordSelection?.ranges ?? rangesForSelection(selectedSections)
         const currentSnapshot = runtime.controller.getSnapshot()
+        if (
+          wordSelection &&
+          (wordSelection.revision !== currentSnapshot.timeline.revision ||
+            !port.occurrenceSelection)
+        ) {
+          throw new Error(
+            'This edit changed or the host cannot target occurrences. Select the words again.',
+          )
+        }
         const request = {
           transcriptId: status.transcriptId,
           assetId: status.assetId,
@@ -748,6 +796,19 @@ export function HostTranscriptEditor({ active = true }: { active?: boolean }) {
         ) {
           throw new Error('The transcript preview contains an unsupported timeline command.')
         }
+        if (wordSelection) {
+          const applied = await runtime.controller.submitEdit(result.commandBatch)
+          if (applied.status !== 'applied' && applied.status !== 'replayed') {
+            throw new Error(
+              applied.status === 'unsupported'
+                ? applied.reason
+                : 'This edit could not be saved. Refresh and select the words again.',
+            )
+          }
+          setPreview(null)
+          setAnnouncement('Selected footage deleted and gap closed. Undo restores this cut.')
+          return
+        }
         setPreview(result)
         setAnnouncement(
           result.status === 'replayed'
@@ -903,6 +964,8 @@ export function HostTranscriptEditor({ active = true }: { active?: boolean }) {
     }
   }, [port, refresh, status, transcribeAssetId, transcribing])
 
+  const hasWordTiming = sections.some(hasUsableHostWordTiming)
+
   if (!port || !runtime || !canTranscribe) {
     return (
       <UnavailableTranscript
@@ -974,14 +1037,16 @@ export function HostTranscriptEditor({ active = true }: { active?: boolean }) {
         </Button>
       </div>
 
-      <div className="flex items-center justify-between border-b border-border px-3 py-2 text-[11px] text-muted-foreground">
-        <span data-testid="host-transcript-status">
-          {status?.status === 'succeeded' ? '' : status?.status}
-        </span>
-        <span>
-          {selectedIds.size}/{MAX_TRANSCRIPT_SELECTIONS} selected
-        </span>
-      </div>
+      {!hasWordTiming && (
+        <div className="flex items-center justify-between border-b border-border px-3 py-2 text-[11px] text-muted-foreground">
+          <span data-testid="host-transcript-status">
+            {status?.status === 'succeeded' ? '' : status?.status}
+          </span>
+          <span>
+            {selectedIds.size}/{MAX_TRANSCRIPT_SELECTIONS} selected
+          </span>
+        </div>
+      )}
 
       {error ? (
         <div
@@ -1005,132 +1070,171 @@ export function HostTranscriptEditor({ active = true }: { active?: boolean }) {
         </div>
       ) : null}
 
-      <div className="min-h-0 flex-1 overflow-x-hidden overflow-y-auto px-3 py-2">
-        {visibleSections.length === 0 ? (
-          <div className="flex h-full items-center justify-center p-4 text-center text-sm text-muted-foreground">
-            {normalizedQuery
-              ? 'No transcript sections match this search.'
-              : 'No transcript sections are available.'}
+      {hasWordTiming && hasMore && (
+        <Button variant="ghost" size="sm" disabled={loadingMore} onClick={() => void loadMore()}>
+          Load more transcript
+        </Button>
+      )}
+      {hasWordTiming && sections.some((section) => !hasUsableHostWordTiming(section)) && (
+        <p role="status" className="px-3 py-2 text-xs">
+          Some sections need word timing and cannot be edited as words.
+        </p>
+      )}
+      {hasWordTiming && status?.assetId ? (
+        <HostTranscriptWordView
+          key={`${status.transcriptId}:${status.sourceAssetHash}`}
+          runtime={runtime}
+          assetId={status.assetId}
+          sections={sections}
+          query={query}
+          canCut={
+            port.occurrenceSelection === true &&
+            isHostCapabilityEnabled(capabilities, 'timeline.remove')
+          }
+          busy={previewing || applying}
+          onDelete={(ranges, revision) => previewSelection('cut', { ranges, revision })}
+        />
+      ) : (
+        <>
+          <div
+            className="border-b border-border px-3 py-2 text-xs text-muted-foreground"
+            role="status"
+          >
+            <p className="font-medium text-foreground">Word timing needed</p>
+            <p>
+              Word editing is unavailable for this transcript. These controls select whole sections.
+              Check Generate transcript for supported transcription options; regeneration may reuse
+              cached timing.
+            </p>
           </div>
-        ) : (
-          <div className="mx-auto max-w-[62ch] space-y-2">
-            {visibleSections.map((section, index) => {
-              const selected = selectedIds.has(section.id)
-              return (
-                <button
-                  key={section.id}
+          <div className="min-h-0 flex-1 overflow-x-hidden overflow-y-auto px-3 py-2">
+            {visibleSections.length === 0 ? (
+              <div className="flex h-full items-center justify-center p-4 text-center text-sm text-muted-foreground">
+                {normalizedQuery
+                  ? 'No transcript sections match this search.'
+                  : 'No transcript sections are available.'}
+              </div>
+            ) : (
+              <div className="mx-auto max-w-[62ch] space-y-2">
+                {visibleSections.map((section, index) => {
+                  const selected = selectedIds.has(section.id)
+                  return (
+                    <button
+                      key={section.id}
+                      type="button"
+                      data-testid={`host-transcript-section-${section.id}`}
+                      aria-pressed={selected}
+                      onClick={(event) => selectSection(index, event.shiftKey)}
+                      className={`grid w-full grid-cols-[3rem_minmax(0,1fr)] gap-x-3 rounded-md px-1 py-1.5 text-left transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-primary ${
+                        selected
+                          ? 'bg-primary text-primary-foreground'
+                          : 'text-foreground/85 hover:bg-secondary/60'
+                      }`}
+                    >
+                      <span className="mt-px select-none text-right font-mono text-[11px] tabular-nums leading-7 opacity-70">
+                        {formatTimecode(section.startUs)}
+                      </span>
+                      <span className="min-w-0 break-words text-sm leading-7">
+                        {section.text}
+                        {section.speaker ? (
+                          <span className="ml-1 text-[11px] opacity-70">({section.speaker})</span>
+                        ) : null}
+                      </span>
+                    </button>
+                  )
+                })}
+              </div>
+            )}
+            {hasMore ? (
+              <div className="flex justify-center py-3">
+                <Button
                   type="button"
-                  data-testid={`host-transcript-section-${section.id}`}
-                  aria-pressed={selected}
-                  onClick={(event) => selectSection(index, event.shiftKey)}
-                  className={`grid w-full grid-cols-[3rem_minmax(0,1fr)] gap-x-3 rounded-md px-1 py-1.5 text-left transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-primary ${
-                    selected
-                      ? 'bg-primary text-primary-foreground'
-                      : 'text-foreground/85 hover:bg-secondary/60'
-                  }`}
+                  variant="ghost"
+                  size="sm"
+                  onClick={() => void loadMore()}
+                  disabled={loadingMore}
+                  data-testid="host-transcript-load-more"
                 >
-                  <span className="mt-px select-none text-right font-mono text-[11px] tabular-nums leading-7 opacity-70">
-                    {formatTimecode(section.startUs)}
-                  </span>
-                  <span className="min-w-0 break-words text-sm leading-7">
-                    {section.text}
-                    {section.speaker ? (
-                      <span className="ml-1 text-[11px] opacity-70">({section.speaker})</span>
-                    ) : null}
-                  </span>
-                </button>
-              )
-            })}
+                  {loadingMore && <Loader2 className="mr-1.5 h-3.5 w-3.5 animate-spin" />}
+                  Load more
+                  <ChevronDown className="ml-1.5 h-3.5 w-3.5" />
+                </Button>
+              </div>
+            ) : null}
           </div>
-        )}
-        {hasMore ? (
-          <div className="flex justify-center py-3">
-            <Button
-              type="button"
-              variant="ghost"
-              size="sm"
-              onClick={() => void loadMore()}
-              disabled={loadingMore}
-              data-testid="host-transcript-load-more"
-            >
-              {loadingMore && <Loader2 className="mr-1.5 h-3.5 w-3.5 animate-spin" />}
-              Load more
-              <ChevronDown className="ml-1.5 h-3.5 w-3.5" />
-            </Button>
-          </div>
-        ) : null}
-      </div>
 
-      {preview ? (
-        <div
-          className="border-t border-border bg-secondary/30 px-3 py-2"
-          data-testid="host-transcript-preview"
-        >
-          <div className="flex items-start gap-2">
-            <CheckCircle2 className="mt-0.5 h-3.5 w-3.5 shrink-0 text-emerald-500" />
-            <div className="min-w-0 flex-1 text-xs">
-              <p className="font-medium text-foreground">
-                {preview.status === 'replayed' ? 'Preview replayed safely.' : 'Preview ready.'}
-              </p>
-              <p className="text-[11px] leading-4 text-muted-foreground">
+          {preview ? (
+            <div
+              className="border-t border-border bg-secondary/30 px-3 py-2"
+              data-testid="host-transcript-preview"
+            >
+              <div className="flex items-start gap-2">
+                <CheckCircle2 className="mt-0.5 h-3.5 w-3.5 shrink-0 text-emerald-500" />
+                <div className="min-w-0 flex-1 text-xs">
+                  <p className="font-medium text-foreground">
+                    {preview.status === 'replayed' ? 'Preview replayed safely.' : 'Preview ready.'}
+                  </p>
+                  <p className="text-[11px] leading-4 text-muted-foreground">
+                    {previewAction === 'captions' || previewAction === 'caption'
+                      ? `${preview.preview.captionCount ?? selectedIds.size} caption(s) · timeline unchanged`
+                      : `${selectedIds.size} range(s) · timeline unchanged`}
+                  </p>
+                </div>
+              </div>
+              <Button
+                type="button"
+                size="sm"
+                className="mt-2 w-full"
+                onClick={() => void applyPreview()}
+                disabled={applying}
+                data-testid="host-transcript-apply"
+              >
+                {applying && <Loader2 className="mr-1.5 h-3.5 w-3.5 animate-spin" />}
                 {previewAction === 'captions' || previewAction === 'caption'
-                  ? `${preview.preview.captionCount ?? selectedIds.size} caption(s) · timeline unchanged`
-                  : `${selectedIds.size} range(s) · timeline unchanged`}
-              </p>
+                  ? 'Apply captions'
+                  : 'Apply cut'}
+              </Button>
             </div>
-          </div>
-          <Button
-            type="button"
-            size="sm"
-            className="mt-2 w-full"
-            onClick={() => void applyPreview()}
-            disabled={applying}
-            data-testid="host-transcript-apply"
-          >
-            {applying && <Loader2 className="mr-1.5 h-3.5 w-3.5 animate-spin" />}
-            {previewAction === 'captions' || previewAction === 'caption'
-              ? 'Apply captions'
-              : 'Apply cut'}
-          </Button>
-        </div>
-      ) : null}
+          ) : null}
 
-      <div className="flex flex-wrap items-center justify-between gap-2 border-t border-border p-2">
-        <span className="min-w-0 text-xs text-muted-foreground">
-          {selectedIds.size > 0
-            ? `${selectedIds.size} section${selectedIds.size === 1 ? '' : 's'} selected`
-            : 'Select sections to cut or caption'}
-        </span>
-        <div className="flex items-center gap-2">
-          <Button
-            type="button"
-            size="sm"
-            variant="secondary"
-            onClick={() => void previewSelection('cut')}
-            disabled={selectedIds.size === 0 || previewing || applying}
-            data-testid="host-transcript-cut-button"
-          >
-            {previewing && previewAction === 'cut' ? (
-              <Loader2 className="mr-1.5 h-3.5 w-3.5 animate-spin" />
-            ) : (
-              <Scissors className="mr-1.5 h-3.5 w-3.5" />
-            )}
-            Cut selection
-          </Button>
-          <Button
-            type="button"
-            size="sm"
-            onClick={() => void previewSelection('captions')}
-            disabled={selectedIds.size === 0 || previewing || applying}
-            data-testid="host-transcript-preview-button"
-          >
-            {previewing && previewAction !== 'cut' && (
-              <Loader2 className="mr-1.5 h-3.5 w-3.5 animate-spin" />
-            )}
-            Preview captions
-          </Button>
-        </div>
-      </div>
+          <div className="flex flex-wrap items-center justify-between gap-2 border-t border-border p-2">
+            <span className="min-w-0 text-xs text-muted-foreground">
+              {selectedIds.size > 0
+                ? `${selectedIds.size} section${selectedIds.size === 1 ? '' : 's'} selected`
+                : 'Select sections to cut or caption'}
+            </span>
+            <div className="flex items-center gap-2">
+              <Button
+                type="button"
+                size="sm"
+                variant="secondary"
+                onClick={() => void previewSelection('cut')}
+                disabled={selectedIds.size === 0 || previewing || applying}
+                data-testid="host-transcript-cut-button"
+              >
+                {previewing && previewAction === 'cut' ? (
+                  <Loader2 className="mr-1.5 h-3.5 w-3.5 animate-spin" />
+                ) : (
+                  <Scissors className="mr-1.5 h-3.5 w-3.5" />
+                )}
+                Cut whole sections
+              </Button>
+              <Button
+                type="button"
+                size="sm"
+                onClick={() => void previewSelection('captions')}
+                disabled={selectedIds.size === 0 || previewing || applying}
+                data-testid="host-transcript-preview-button"
+              >
+                {previewing && previewAction !== 'cut' && (
+                  <Loader2 className="mr-1.5 h-3.5 w-3.5 animate-spin" />
+                )}
+                Preview captions
+              </Button>
+            </div>
+          </div>
+        </>
+      )}
 
       <span className="sr-only" aria-live="polite">
         {announcement}
diff --git a/src/features/editor/host/transcript-word-view.tsx b/src/features/editor/host/transcript-word-view.tsx
new file mode 100644
index 000000000..fc7514f7d
--- /dev/null
+++ b/src/features/editor/host/transcript-word-view.tsx
@@ -0,0 +1,278 @@
+import { transcriptSelectionIndex } from '@/shared/utils/transcript-selection'
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { Button } from '@/components/ui/button'
+import { usePlaybackStore } from '@/shared/state/playback'
+import { useSelectionStore } from '@/shared/state/selection'
+import { useEditorStore } from '@/shared/state/editor'
+import type { EmbeddedEditorHostRuntime } from './runtime'
+import type { HostTranscriptRange, HostTranscriptSection } from './contract'
+import {
+  hostWordSelectionRanges,
+  mapHostTranscriptWords,
+  type HostWordOccurrence,
+} from './transcript-words'
+
+function selectionDurationFrames(words: readonly HostWordOccurrence[]): number {
+  const intervals = hostWordSelectionRanges(words)
+    .map((range) => {
+      const selected = words.filter(
+        (word) =>
+          word.itemId === range.itemId &&
+          word.sourceStartUs >= range.startUs &&
+          word.sourceEndUs <= range.endUs,
+      )
+      return {
+        start: Math.min(...selected.map((word) => word.startFrame)),
+        end: Math.max(...selected.map((word) => word.endFrame)),
+      }
+    })
+    .sort((a, b) => a.start - b.start)
+  let end = 0
+  let duration = 0
+  for (const interval of intervals) {
+    duration += Math.max(0, interval.end - Math.max(end, interval.start))
+    end = Math.max(end, interval.end)
+  }
+  return duration
+}
+
+export function HostTranscriptWordView({
+  runtime,
+  assetId,
+  sections,
+  query,
+  canCut,
+  busy,
+  onDelete,
+}: {
+  runtime: EmbeddedEditorHostRuntime
+  assetId: string
+  sections: readonly HostTranscriptSection[]
+  query: string
+  canCut: boolean
+  busy: boolean
+  onDelete: (ranges: HostTranscriptRange[], revision: number) => Promise<void>
+}) {
+  const [document, setDocument] = useState(() => runtime.controller.getSnapshot().timeline)
+  const [scope, setScope] = useState('edit')
+  const selectedClips = useSelectionStore((state) => state.selectedItemIds)
+  const [selection, setSelection] = useState<{
+    anchor: number
+    focus: number
+    revision: number
+  } | null>(null)
+  const [following, setFollowing] = useState(true)
+  const scroll = useRef<HTMLDivElement>(null)
+  const dragging = useRef(false)
+  useEffect(() => () => useEditorStore.getState().setTranscriptEditorShortcutScopeActive(false), [])
+  const inFlight = useRef(false)
+  const currentFrame = usePlaybackStore((state) => state.currentFrame)
+  const playing = usePlaybackStore((state) => state.isPlaying)
+  useEffect(
+    () => runtime.controller.subscribe((snapshot) => setDocument(snapshot.timeline)),
+    [runtime],
+  )
+  const words = useMemo(
+    () =>
+      mapHostTranscriptWords(document, assetId, sections).filter(
+        (word) => scope === 'edit' || selectedClips.includes(word.itemId),
+      ),
+    [document, assetId, sections, scope, selectedClips],
+  )
+  const otherSources = document.tracks.some((track) =>
+    track.items.some((item) => 'mediaId' in item && item.mediaId !== assetId),
+  )
+  const active = words.findIndex(
+    (word) => currentFrame >= word.startFrame && currentFrame < word.endFrame,
+  )
+  const stale = selection !== null && selection.revision !== document.revision
+  const selected =
+    selection && !stale
+      ? words.slice(
+          Math.min(selection.anchor, selection.focus),
+          Math.max(selection.anchor, selection.focus) + 1,
+        )
+      : []
+  const duration = selectionDurationFrames(selected) / runtime.controller.getSnapshot().project.fps
+
+  useEffect(() => {
+    if (following && playing && active >= 0)
+      scroll.current
+        ?.querySelector(`[data-word-index="${active}"]`)
+        ?.scrollIntoView({ block: 'nearest' })
+  }, [following, playing, active])
+  useEffect(() => {
+    const stop = () => {
+      dragging.current = false
+    }
+    window.addEventListener('pointerup', stop)
+    return () => window.removeEventListener('pointerup', stop)
+  }, [])
+  const choose = (index: number, extend: boolean) => {
+    setFollowing(false)
+    setSelection((previous) => ({
+      anchor: extend && previous?.revision === document.revision ? previous.anchor : index,
+      focus: index,
+      revision: document.revision,
+    }))
+    usePlaybackStore.getState().setCurrentFrame(Math.floor(words[index]!.startFrame))
+  }
+  const remove = async () => {
+    if (!canCut || busy || inFlight.current || selected.length === 0 || !selection || stale) return
+    inFlight.current = true
+    try {
+      await onDelete(hostWordSelectionRanges(selected), selection.revision)
+      setSelection(null)
+    } finally {
+      inFlight.current = false
+    }
+  }
+  return (
+    <div className="flex min-h-0 flex-1 flex-col" data-testid="host-transcript-words">
+      <div className="flex flex-wrap items-center justify-between gap-2 px-3 py-2 text-xs">
+        <select
+          aria-label="Transcript scope"
+          value={scope}
+          onChange={(event) => {
+            setScope(event.target.value)
+            setSelection(null)
+          }}
+          className="min-w-0 max-w-full rounded bg-secondary px-2 py-1"
+        >
+          <option value="edit">{otherSources ? 'This edit · current source' : 'This edit'}</option>
+          <option value="selection">Selected clip</option>
+        </select>
+        {!following && (
+          <Button size="sm" variant="ghost" onClick={() => setFollowing(true)}>
+            Resume following
+          </Button>
+        )}
+      </div>
+      {otherSources && (
+        <p className="px-3 pb-2 text-xs text-muted-foreground">
+          Showing this transcript’s source in the current edit. Other source transcripts are not
+          included.
+        </p>
+      )}
+      <div
+        ref={scroll}
+        tabIndex={0}
+        role="region"
+        aria-label="Timed transcript words"
+        className="min-h-0 flex-1 overflow-y-auto px-3 py-2 outline-none"
+        onFocus={() => useEditorStore.getState().setTranscriptEditorShortcutScopeActive(true)}
+        onBlur={(event) => {
+          if (!event.currentTarget.contains(event.relatedTarget as Node | null))
+            useEditorStore.getState().setTranscriptEditorShortcutScopeActive(false)
+        }}
+        onWheel={() => setFollowing(false)}
+        onTouchMove={() => setFollowing(false)}
+        onPointerDown={(event) => {
+          if (event.target === event.currentTarget) setFollowing(false)
+        }}
+        onPointerMove={(event) => {
+          if (!dragging.current) return
+          const element = globalThis.document
+            .elementFromPoint(event.clientX, event.clientY)
+            ?.closest<HTMLElement>('[data-word-index]')
+          if (element && scroll.current?.contains(element)) {
+            const index = Number(element.dataset.wordIndex)
+            setSelection((previous) => (previous ? { ...previous, focus: index } : previous))
+          }
+        }}
+        onKeyDown={(event) => {
+          if (event.key === 'Backspace' || event.key === 'Delete') {
+            event.preventDefault()
+            event.stopPropagation()
+            void remove()
+          } else if (event.key === 'Escape') {
+            event.stopPropagation()
+            setSelection(null)
+          } else {
+            const next = transcriptSelectionIndex(event.key, selection?.focus ?? 0, words.length)
+            if (next === null) return
+            event.preventDefault()
+            event.stopPropagation()
+            choose(next, event.shiftKey)
+          }
+        }}
+      >
+        {words.length === 0 && (
+          <p className="text-sm text-muted-foreground">
+            No timed words in {scope === 'selection' ? 'the selected clip' : 'this edit'}.
+          </p>
+        )}
+        <div className="max-w-[62ch] text-sm leading-8">
+          {words.map((word, index) => {
+            const previous = words[index - 1]
+            const paragraph =
+              !previous || previous.itemId !== word.itemId || previous.sectionId !== word.sectionId
+            const chosen = selected.some((entry) => entry.key === word.key)
+            const matches =
+              query && word.text.toLocaleLowerCase().includes(query.toLocaleLowerCase())
+            return (
+              <span key={word.key}>
+                {paragraph && (
+                  <span className="mt-3 block font-mono text-[11px] text-muted-foreground">
+                    {Math.floor(
+                      word.startFrame / runtime.controller.getSnapshot().project.fps / 60,
+                    )}
+                    :
+                    {String(
+                      Math.floor(word.startFrame / runtime.controller.getSnapshot().project.fps) %
+                        60,
+                    ).padStart(2, '0')}
+                  </span>
+                )}
+                <button
+                  type="button"
+                  tabIndex={-1}
+                  data-word-index={index}
+                  aria-pressed={chosen}
+                  aria-current={active === index ? 'true' : undefined}
+                  className={`rounded px-0.5 outline-offset-2 ${chosen ? 'bg-primary/20 outline outline-1 outline-primary' : active === index ? 'bg-secondary underline decoration-2' : matches ? 'bg-yellow-500/20' : 'hover:bg-secondary/60'}`}
+                  onPointerDown={(event) => {
+                    event.preventDefault()
+                    dragging.current = true
+                    choose(index, event.shiftKey)
+                    scroll.current?.focus({ preventScroll: true })
+                    scroll.current?.setPointerCapture?.(event.pointerId)
+                  }}
+                  onClick={(event) => {
+                    if (event.detail === 0) choose(index, event.shiftKey)
+                  }}
+                >
+                  {word.text}
+                </button>{' '}
+              </span>
+            )
+          })}
+        </div>
+      </div>
+      {stale && (
+        <p role="status" className="px-3 py-2 text-xs">
+          This edit changed. Select the words again.
+        </p>
+      )}
+      {!canCut && (
+        <p className="px-3 py-2 text-xs text-muted-foreground">
+          This host needs occurrence-aware transcript editing before words can be cut.
+        </p>
+      )}
+      <div className="border-t border-border p-2">
+        <Button
+          size="sm"
+          variant="secondary"
+          disabled={!canCut || busy || selected.length === 0}
+          onClick={() => void remove()}
+        >
+          Delete selection{selected.length ? ` · ${duration.toFixed(2)}s` : ''}
+        </Button>
+        <p className="mt-2 text-xs text-muted-foreground">
+          Select words, then Backspace or Delete to cut footage and close the gap. Undo restores the
+          cut.
+        </p>
+      </div>
+    </div>
+  )
+}
diff --git a/src/features/editor/host/transcript-words.test.ts b/src/features/editor/host/transcript-words.test.ts
index 6ca900366..fab1df218 100644
--- a/src/features/editor/host/transcript-words.test.ts
+++ b/src/features/editor/host/transcript-words.test.ts
@@ -99,6 +99,24 @@ describe('host word occurrence mapping', () => {
       'different-time',
     ])
   })
+  it('rejects incomplete or malformed provider word coverage', () => {
+    expect(
+      mapHostTranscriptWords(document([clip]), 'media', [
+        { ...section, words: section.words!.slice(1) },
+      ]),
+    ).toEqual([])
+    expect(
+      mapHostTranscriptWords(document([clip]), 'media', [
+        { ...section, words: [{ text: section.text, startUs: NaN, endUs: 3_000_000 }] },
+      ]),
+    ).toEqual([])
+    expect(
+      mapHostTranscriptWords(document([clip]), 'media', [
+        { ...section, words: [{ text: section.text, startUs: 0, endUs: 3_000_001 }] },
+      ]),
+    ).toEqual([])
+  })
+
   it('never invents word timing from legacy or synthetic sections and leaves gaps inactive', () => {
     expect(
       mapHostTranscriptWords(document([clip]), 'media', [
diff --git a/src/features/editor/host/transcript-words.ts b/src/features/editor/host/transcript-words.ts
index a10812ab2..7b8209206 100644
--- a/src/features/editor/host/transcript-words.ts
+++ b/src/features/editor/host/transcript-words.ts
@@ -1,4 +1,4 @@
-import type { FreeCutFrameDocument } from '../codepress/document'
+import type { FreeCutFrameDocument, FreeCutFrameClip } from '../codepress/document'
 import { framesToMicroseconds } from '../codepress/timing'
 import type { HostTranscriptRange, HostTranscriptSection } from './contract'
 
@@ -57,39 +57,49 @@ export function mapHostTranscriptWords(
       : null
     if (cohort && linked.has(cohort)) continue
     if (cohort) linked.add(cohort)
-    const sourceStart = framesToMicroseconds(clip.sourceStart ?? 0, document.fps)
-    const sourceEnd = framesToMicroseconds(
-      clip.sourceEnd ?? (clip.sourceStart ?? 0) + clip.durationInFrames * (clip.speed ?? 1),
-      document.fps,
-    )
-    if (sourceEnd <= sourceStart) continue
-    for (const section of sections) {
-      if (!hasUsableHostWordTiming(section)) continue
-      section.words?.forEach((word, index) => {
-        if (word.endUs <= sourceStart || word.startUs >= sourceEnd) return
-        const start = Math.max(sourceStart, word.startUs)
-        const end = Math.min(sourceEnd, word.endUs)
-        words.push({
-          key: `${clip.id}:${section.id}:${index}`,
-          itemId: clip.id,
-          wordIndex: index,
-          sectionId: section.id,
-          revision: document.revision,
-          text: word.text,
-          // Preserve the measured word boundaries. The backend intersects the trim.
-          sourceStartUs: word.startUs,
-          sourceEndUs: word.endUs,
-          startFrame:
-            clip.from + ((start - sourceStart) / (sourceEnd - sourceStart)) * clip.durationInFrames,
-          endFrame:
-            clip.from + ((end - sourceStart) / (sourceEnd - sourceStart)) * clip.durationInFrames,
-        })
-      })
-    }
+    words.push(...wordsForClip(clip, document, sections))
   }
   return words.sort((a, b) => a.startFrame - b.startFrame)
 }
 
+function wordsForClip(
+  clip: FreeCutFrameClip,
+  document: FreeCutFrameDocument,
+  sections: readonly HostTranscriptSection[],
+): HostWordOccurrence[] {
+  const words: HostWordOccurrence[] = []
+  const sourceStart = framesToMicroseconds(clip.sourceStart ?? 0, document.fps)
+  const sourceEnd = framesToMicroseconds(
+    clip.sourceEnd ?? (clip.sourceStart ?? 0) + clip.durationInFrames * (clip.speed ?? 1),
+    document.fps,
+  )
+  if (sourceEnd <= sourceStart) return []
+  for (const section of sections) {
+    if (!hasUsableHostWordTiming(section)) continue
+    section.words?.forEach((word, index) => {
+      if (word.endUs <= sourceStart || word.startUs >= sourceEnd) return
+      const start = Math.max(sourceStart, word.startUs)
+      const end = Math.min(sourceEnd, word.endUs)
+      words.push({
+        key: `${clip.id}:${section.id}:${index}`,
+        itemId: clip.id,
+        wordIndex: index,
+        sectionId: section.id,
+        revision: document.revision,
+        text: word.text,
+        // Preserve the measured word boundaries. The backend intersects the trim.
+        sourceStartUs: word.startUs,
+        sourceEndUs: word.endUs,
+        startFrame:
+          clip.from + ((start - sourceStart) / (sourceEnd - sourceStart)) * clip.durationInFrames,
+        endFrame:
+          clip.from + ((end - sourceStart) / (sourceEnd - sourceStart)) * clip.durationInFrames,
+      })
+    })
+  }
+  return words
+}
+
 /** Adjacent selected words merge only within the same occurrence. */
 export function hostWordSelectionRanges(
   words: readonly HostWordOccurrence[],
diff --git a/src/features/timeline/components/transcript-editor/transcript-editor-panel.tsx b/src/features/timeline/components/transcript-editor/transcript-editor-panel.tsx
index a220cce93..6bd2e10a7 100644
--- a/src/features/timeline/components/transcript-editor/transcript-editor-panel.tsx
+++ b/src/features/timeline/components/transcript-editor/transcript-editor-panel.tsx
@@ -1,3 +1,4 @@
+import { transcriptSelectionIndex } from '@/shared/utils/transcript-selection'
 import {
   Fragment,
   memo,
@@ -59,6 +60,7 @@ import {
 } from '../../deps/media-transcription-service'
 import {
   buildRemovalRangesByMediaId,
+  buildRemovalRangesByItemId,
   buildTranscriptTokens,
   findActiveTokenIndex,
   getSelectedTokenSlice,
@@ -275,7 +277,8 @@ export function TranscriptEditorPanel({ active }: TranscriptEditorPanelProps) {
   const ignoreRanges = useTranscriptIgnoreStore((s) => s.ranges)
   const setTranscriptShortcutScope = useEditorStore((s) => s.setTranscriptEditorShortcutScopeActive)
 
-  const [scope, setScope] = useState<TranscriptScope>('selection')
+  const [following, setFollowing] = useState(true)
+  const [scope, setScope] = useState<TranscriptScope>('project')
   const [mediaState, setMediaState] = useState<Record<string, MediaEntry>>({})
   const [anchorIndex, setAnchorIndex] = useState(-1)
   const [focusIndex, setFocusIndex] = useState(-1)
@@ -404,7 +407,7 @@ export function TranscriptEditorPanel({ active }: TranscriptEditorPanelProps) {
     setAnchorIndex(-1)
     setFocusIndex(-1)
     setMatchCursor(0)
-  }, [uniqueMediaIds, scope])
+  }, [uniqueMediaIds, scope, allItems, tokens])
 
   useEffect(() => {
     mountedRef.current = true
@@ -478,14 +481,14 @@ export function TranscriptEditorPanel({ active }: TranscriptEditorPanelProps) {
   // Keep the active word in view during playback. Skip entirely when hidden — a
   // querySelector + scrollIntoView every frame on an off-screen panel is pure waste.
   useEffect(() => {
-    if (!active || !isPlaying || activeIndex < 0) return
+    if (!active || !following || !isPlaying || activeIndex < 0) return
     const key = tokens[activeIndex]?.key
     if (!key) return
     const el = scrollRef.current?.querySelector<HTMLElement>(
       `[data-token-key="${CSS.escape(key)}"]`,
     )
     el?.scrollIntoView({ block: 'nearest' })
-  }, [active, isPlaying, activeIndex, tokens])
+  }, [active, following, isPlaying, activeIndex, tokens])
 
   useEffect(() => {
     const stop = () => {
@@ -503,6 +506,7 @@ export function TranscriptEditorPanel({ active }: TranscriptEditorPanelProps) {
     (index: number, event: ReactPointerEvent) => {
       const token = tokens[index]
       if (!token) return
+      setFollowing(false)
       if (event.shiftKey && anchorIndexRef.current >= 0) {
         setFocusIndex(index)
       } else {
@@ -536,18 +540,27 @@ export function TranscriptEditorPanel({ active }: TranscriptEditorPanelProps) {
     if (Number.isInteger(index)) setFocusIndex(index)
   }, [])
 
-  // Non-destructive: striking words stages them as "ignored" (restorable) rather
-  // than cutting the timeline. Re-striking an already-ignored selection restores it.
   const handleIgnoreToggle = useCallback(() => {
     if (selectedSlice.length === 0) return
-    const ranges = buildRemovalRangesByMediaId(selectedSlice)
-    const allIgnored = selectedSlice.every((token) => ignoredKeys.has(token.key))
-    if (allIgnored) {
-      useTranscriptIgnoreStore.getState().restore(ranges)
-    } else {
-      useTranscriptIgnoreStore.getState().ignore(ranges)
+    try {
+      const result = useTimelineStore
+        .getState()
+        .removeTranscriptRangesFromItems(
+          [...new Set(selectedSlice.map((token) => token.itemId))],
+          buildRemovalRangesByMediaId(selectedSlice),
+          buildRemovalRangesByItemId(selectedSlice),
+        )
+      if (result.removedItemCount === 0) {
+        toast.error('The selection cannot be cut. Check locked tracks and transition boundaries.')
+        return
+      }
+      setAnchorIndex(-1)
+      setFocusIndex(-1)
+      toast.success('Selected footage deleted. Undo restores this cut.')
+    } catch {
+      toast.error(t('transcript.toastRemoveFailed'))
     }
-  }, [selectedSlice, ignoredKeys])
+  }, [selectedSlice, t])
 
   // Word-level copy/cut that carries the media: each run of selected words
   // becomes a trimmed clone of its clip, placed on the shared clipboard so the
@@ -576,7 +589,13 @@ export function TranscriptEditorPanel({ active }: TranscriptEditorPanelProps) {
       const rangesByMediaId = buildRemovalRangesByMediaId(selectedSlice)
       const itemIds = Array.from(new Set(selectedSlice.map((token) => token.itemId)))
       try {
-        useTimelineStore.getState().removeTranscriptRangesFromItems(itemIds, rangesByMediaId)
+        useTimelineStore
+          .getState()
+          .removeTranscriptRangesFromItems(
+            itemIds,
+            rangesByMediaId,
+            buildRemovalRangesByItemId(selectedSlice),
+          )
       } catch (error) {
         logger.warn('Transcript cut failed', error)
         toast.error(t('transcript.toastRemoveFailed'))
@@ -685,23 +704,35 @@ export function TranscriptEditorPanel({ active }: TranscriptEditorPanelProps) {
         return
       }
 
+      const next = transcriptSelectionIndex(event.key, focusIndex, tokens.length)
+      if (next !== null) {
+        event.preventDefault()
+        event.stopPropagation()
+        setFollowing(false)
+        if (!event.shiftKey || anchorIndex < 0) setAnchorIndex(next)
+        setFocusIndex(next)
+        seekToToken(tokens[next]!.startFrame)
+        return
+      }
       if (event.key === 'Delete' || event.key === 'Backspace') {
         // Always own these so they never fall through to the timeline's clip
         // delete — even with no selection (then it's simply a no-op).
         event.preventDefault()
         event.stopPropagation()
         if (selectedKeys.size > 0) handleIgnoreToggle()
-      } else if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
-        if (ignoredSpanCount === 0) return
-        event.preventDefault()
-        event.stopPropagation()
-        handleApply()
       } else if (event.key === 'Escape') {
         setAnchorIndex(-1)
         setFocusIndex(-1)
       }
     },
-    [selectedKeys.size, handleIgnoreToggle, ignoredSpanCount, handleApply],
+    [
+      selectedKeys.size,
+      handleIgnoreToggle,
+      tokens,
+      focusIndex,
+      anchorIndex,
+      seekToToken,
+    ],
   )
 
   const needsTranscription = uniqueMediaIds.filter(
@@ -712,61 +743,64 @@ export function TranscriptEditorPanel({ active }: TranscriptEditorPanelProps) {
     return status === 'loading' || status === 'transcribing'
   })
 
-  const handleTranscribe = useCallback((values: TranscribeDialogValues) => {
-    const targets = uniqueMediaIds.filter((id) => {
-      const status = mediaState[id]?.status
-      return status === 'needs' || status === 'error'
-    })
-    if (targets.length === 0) return
+  const handleTranscribe = useCallback(
+    (values: TranscribeDialogValues) => {
+      const targets = uniqueMediaIds.filter((id) => {
+        const status = mediaState[id]?.status
+        return status === 'needs' || status === 'error'
+      })
+      if (targets.length === 0) return
 
-    setTranscribeDialogOpen(false)
+      setTranscribeDialogOpen(false)
 
-    for (const id of targets) requestedRef.current.add(id)
-    setMediaState((prev) => {
-      const next = { ...prev }
-      for (const id of targets) next[id] = { status: 'transcribing' }
-      return next
-    })
+      for (const id of targets) requestedRef.current.add(id)
+      setMediaState((prev) => {
+        const next = { ...prev }
+        for (const id of targets) next[id] = { status: 'transcribing' }
+        return next
+      })
 
-    void Promise.all(
-      targets.map(async (mediaId) => {
-        try {
-          const result = await runMediaTranscriptionJob(mediaId, {
-            ...values,
-            onModelFallback: () => {
-              toast.info(t('transcript.largeTurboFallback'))
-            },
-          })
-          if (!mountedRef.current) return
-          if (result.status === 'cancelled') {
-            setMediaState((prev) => ({ ...prev, [mediaId]: { status: 'needs' } }))
-            return
-          }
-          const { transcript } = result
-          setMediaState((prev) => ({
-            ...prev,
-            [mediaId]: hasWordTimings(transcript)
-              ? { status: 'ready', transcript }
-              : { status: 'needs' },
-          }))
-        } catch (error) {
-          logger.warn('Transcription failed', { mediaId, error })
-          const errorMessage = isTranscriptionOutOfMemoryError(error)
-            ? TRANSCRIPTION_OOM_HINT
-            : error instanceof Error && error.message.trim().length > 0
-              ? error.message
-              : t('transcript.toastTranscribeFailed')
-          if (mountedRef.current) {
+      void Promise.all(
+        targets.map(async (mediaId) => {
+          try {
+            const result = await runMediaTranscriptionJob(mediaId, {
+              ...values,
+              onModelFallback: () => {
+                toast.info(t('transcript.largeTurboFallback'))
+              },
+            })
+            if (!mountedRef.current) return
+            if (result.status === 'cancelled') {
+              setMediaState((prev) => ({ ...prev, [mediaId]: { status: 'needs' } }))
+              return
+            }
+            const { transcript } = result
             setMediaState((prev) => ({
               ...prev,
-              [mediaId]: { status: 'error', errorMessage },
+              [mediaId]: hasWordTimings(transcript)
+                ? { status: 'ready', transcript }
+                : { status: 'needs' },
             }))
+          } catch (error) {
+            logger.warn('Transcription failed', { mediaId, error })
+            const errorMessage = isTranscriptionOutOfMemoryError(error)
+              ? TRANSCRIPTION_OOM_HINT
+              : error instanceof Error && error.message.trim().length > 0
+                ? error.message
+                : t('transcript.toastTranscribeFailed')
+            if (mountedRef.current) {
+              setMediaState((prev) => ({
+                ...prev,
+                [mediaId]: { status: 'error', errorMessage },
+              }))
+            }
+            toast.error(errorMessage)
           }
-          toast.error(errorMessage)
-        }
-      }),
-    )
-  }, [uniqueMediaIds, mediaState, t])
+        }),
+      )
+    },
+    [uniqueMediaIds, mediaState, t],
+  )
 
   const transcriptionError = useMemo(
     () =>
@@ -812,6 +846,11 @@ export function TranscriptEditorPanel({ active }: TranscriptEditorPanelProps) {
       {/* Scope toggle */}
       <div className="flex items-center gap-1 border-b border-border p-2">
         <ScopeToggle scope={scope} onChange={setScope} t={t} />
+        {!following && (
+          <Button size="sm" variant="ghost" onClick={() => setFollowing(true)}>
+            Resume following
+          </Button>
+        )}
       </div>
 
       {/* Search */}
@@ -889,6 +928,8 @@ export function TranscriptEditorPanel({ active }: TranscriptEditorPanelProps) {
       {/* Transcript body */}
       <div
         ref={scrollRef}
+        onWheel={() => setFollowing(false)}
+        onTouchMove={() => setFollowing(false)}
         onPointerMove={handlePointerMove}
         className="min-h-0 flex-1 overflow-x-hidden overflow-y-auto px-3 py-2"
       >
@@ -1021,9 +1062,7 @@ export function TranscriptEditorPanel({ active }: TranscriptEditorPanelProps) {
         <span className="min-w-0 text-xs text-muted-foreground">
           {selectionCount > 0
             ? t('transcript.wordsSelected', { count: selectionCount })
-            : t('transcript.ignoreHint', {
-                defaultValue: 'Select words, then Backspace to mark them for deletion',
-              })}
+            : 'Select words, then Backspace or Delete to cut footage'}
         </span>
         <div className="flex shrink-0 flex-wrap items-center justify-end gap-1.5">
           <Button
@@ -1065,12 +1104,12 @@ export function TranscriptEditorPanel({ active }: TranscriptEditorPanelProps) {
             aria-label={
               selectionAllIgnored
                 ? t('transcript.restoreSelection', { defaultValue: 'Restore' })
-                : t('transcript.ignoreSelection', { defaultValue: 'Mark for delete' })
+                : 'Delete selection'
             }
             data-tooltip={
               selectionAllIgnored
                 ? t('transcript.restoreSelection', { defaultValue: 'Restore' })
-                : t('transcript.ignoreSelection', { defaultValue: 'Mark for delete' })
+                : 'Delete selection'
             }
           >
             {selectionAllIgnored ? (
@@ -1081,7 +1120,7 @@ export function TranscriptEditorPanel({ active }: TranscriptEditorPanelProps) {
             <span className="hidden @[340px]:inline">
               {selectionAllIgnored
                 ? t('transcript.restoreSelection', { defaultValue: 'Restore' })
-                : t('transcript.ignoreSelection', { defaultValue: 'Mark for delete' })}
+                : 'Delete selection'}
             </span>
           </Button>
         </div>
diff --git a/src/features/timeline/stores/actions/edit/range-removal-actions.ts b/src/features/timeline/stores/actions/edit/range-removal-actions.ts
index 81caab759..5d59755dc 100644
--- a/src/features/timeline/stores/actions/edit/range-removal-actions.ts
+++ b/src/features/timeline/stores/actions/edit/range-removal-actions.ts
@@ -61,9 +61,12 @@ function isMostlyInsideRanges(
   return covered / duration >= SILENCE_COVERAGE_REMOVAL_THRESHOLD
 }
 
-function applyRippleRemoval(ids: string[]): { removedIds: string[]; affectedIds: string[] } {
+function applyRippleRemoval(
+  ids: string[],
+  forceLinked = false,
+): { removedIds: string[]; affectedIds: string[] } {
   const items = useItemsStore.getState().items
-  const linkedSelectionEnabled = isLinkedSelectionEnabled()
+  const linkedSelectionEnabled = forceLinked || isLinkedSelectionEnabled()
   const expandedIds = expandIdsWithLinkedItems(items, ids, linkedSelectionEnabled)
   if (expandedIds.length === 0) return { removedIds: [], affectedIds: [] }
 
@@ -206,13 +209,20 @@ export function removeFillerWordsFromItems(
 export function removeTranscriptRangesFromItems(
   itemIds: string[],
   rangesByMediaId: Record<string, RemoveSilenceRange[]>,
+  rangesByItemId?: Record<string, RemoveSilenceRange[]>,
 ): RemoveSilenceResult {
-  return removeTimelineRangesFromItems('REMOVE_TRANSCRIPT_SELECTION', itemIds, rangesByMediaId)
+  return removeTimelineRangesFromItems(
+    'REMOVE_TRANSCRIPT_SELECTION',
+    itemIds,
+    rangesByMediaId,
+    rangesByItemId,
+  )
 }
 
 function getRangeRemovalAnchors(
   itemIds: string[],
   rangesByMediaId: Record<string, RemoveSilenceRange[]>,
+  rangesByItemId?: Record<string, RemoveSilenceRange[]>,
 ): TimelineItem[] {
   const store = useItemsStore.getState()
   const anchorIds = getUniqueLinkedItemAnchorIds(store.items, itemIds)
@@ -223,7 +233,8 @@ function getRangeRemovalAnchors(
         item !== undefined &&
         (item.type === 'video' || item.type === 'audio') &&
         !!item.mediaId &&
-        (rangesByMediaId[item.mediaId]?.length ?? 0) > 0,
+        ((rangesByItemId ? rangesByItemId[item.id] : rangesByMediaId[item.mediaId])?.length ?? 0) >
+          0,
     )
 }
 
@@ -314,13 +325,14 @@ function addRangeDownstreamPreflight(params: {
 function buildRangeRemovalPreflight(
   itemIds: string[],
   rangesByMediaId: Record<string, RemoveSilenceRange[]>,
+  rangesByItemId?: Record<string, RemoveSilenceRange[]>,
 ): { analyzedItemCount: number; mutationIds: string[] } {
   const store = useItemsStore.getState()
   const timelineFps = useTimelineSettingsStore.getState().fps
-  const anchors = getRangeRemovalAnchors(itemIds, rangesByMediaId)
+  const anchors = getRangeRemovalAnchors(itemIds, rangesByMediaId, rangesByItemId)
   if (anchors.length === 0) return { analyzedItemCount: 0, mutationIds: [] }
 
-  const linkedSelectionEnabled = isLinkedSelectionEnabled()
+  const linkedSelectionEnabled = !!rangesByItemId || isLinkedSelectionEnabled()
   const accumulator: RangeRemovalPreflightAccumulator = {
     mutationIds: new Set<string>(),
     editedTrackIds: new Set<string>(),
@@ -331,7 +343,7 @@ function buildRangeRemovalPreflight(
   for (const anchor of anchors) {
     addRangeAnchorPreflight({
       anchor,
-      ranges: rangesByMediaId[anchor.mediaId!] ?? [],
+      ranges: (rangesByItemId ? rangesByItemId[anchor.id] : rangesByMediaId[anchor.mediaId!]) ?? [],
       timelineFps,
       linkedSelectionEnabled,
       accumulator,
@@ -352,16 +364,44 @@ function buildRangeRemovalPreflight(
   return { analyzedItemCount: anchors.length, mutationIds: Array.from(accumulator.mutationIds) }
 }
 
+function assertTranscriptSplitOutsideTransition(item: TimelineItem, frame: number): void {
+  if (frame <= item.from || frame >= item.from + item.durationInFrames) return
+  if (isInTransitionOverlap(item.id, frame - item.from, item.durationInFrames)) {
+    throw new Error('The selected word crosses a transition. Adjust the transition before cutting.')
+  }
+}
+
+function assertTranscriptRangesRepresentable(
+  anchor: TimelineItem,
+  ranges: RemoveSilenceRange[],
+): void {
+  const fps = useTimelineSettingsStore.getState().fps
+  const linkedItems = getLinkedItemsForEdit(useItemsStore.getState().items, anchor.id, true)
+  for (const range of ranges) {
+    const start = Math.max(anchor.from, sourceSecondsToTimelineFrame(anchor, range.start, fps))
+    const end = Math.min(
+      anchor.from + anchor.durationInFrames,
+      sourceSecondsToTimelineFrame(anchor, range.end, fps),
+    )
+    if (end <= start) throw new Error('The selected word is smaller than one timeline frame.')
+    for (const linked of linkedItems) {
+      assertTranscriptSplitOutsideTransition(linked, start)
+      assertTranscriptSplitOutsideTransition(linked, end)
+    }
+  }
+}
+
 function removeTimelineRangesFromItems(
   commandType: 'REMOVE_SILENCE' | 'REMOVE_FILLER_WORDS' | 'REMOVE_TRANSCRIPT_SELECTION',
   itemIds: string[],
   rangesByMediaId: Record<string, RemoveSilenceRange[]>,
+  rangesByItemId?: Record<string, RemoveSilenceRange[]>,
 ): RemoveSilenceResult {
   if (itemIds.length === 0) {
     return { analyzedItemCount: 0, removedRangeCount: 0, removedItemCount: 0, splitCount: 0 }
   }
 
-  const preflight = buildRangeRemovalPreflight(itemIds, rangesByMediaId)
+  const preflight = buildRangeRemovalPreflight(itemIds, rangesByMediaId, rangesByItemId)
   if (preflight.mutationIds.length === 0 || !canMutateTimelineItems(preflight.mutationIds)) {
     return {
       analyzedItemCount: preflight.analyzedItemCount,
@@ -371,6 +411,12 @@ function removeTimelineRangesFromItems(
     }
   }
 
+  if (rangesByItemId) {
+    for (const anchor of getRangeRemovalAnchors(itemIds, rangesByMediaId, rangesByItemId)) {
+      assertTranscriptRangesRepresentable(anchor, rangesByItemId[anchor.id] ?? [])
+    }
+  }
+
   return execute(
     commandType,
     () => {
@@ -384,7 +430,8 @@ function removeTimelineRangesFromItems(
             item !== undefined &&
             (item.type === 'video' || item.type === 'audio') &&
             !!item.mediaId &&
-            (rangesByMediaId[item.mediaId]?.length ?? 0) > 0,
+            ((rangesByItemId ? rangesByItemId[item.id] : rangesByMediaId[item.mediaId])?.length ??
+              0) > 0,
         )
 
       if (anchors.length === 0) {
@@ -395,11 +442,13 @@ function removeTimelineRangesFromItems(
         id: item.id,
         mediaId: item.mediaId!,
         originId: item.originId ?? item.id,
+        from: item.from,
+        to: item.from + item.durationInFrames,
       }))
 
       let splitCount = 0
       for (const anchor of anchors) {
-        const ranges = rangesByMediaId[anchor.mediaId!]
+        const ranges = rangesByItemId ? rangesByItemId[anchor.id] : rangesByMediaId[anchor.mediaId!]
         if (!ranges || ranges.length === 0) continue
 
         const splitFrames = Array.from(
@@ -418,7 +467,7 @@ function removeTimelineRangesFromItems(
         const itemsToSplit = getLinkedItemsForEdit(
           useItemsStore.getState().items,
           anchor.id,
-          isLinkedSelectionEnabled(),
+          !!rangesByItemId || isLinkedSelectionEnabled(),
         )
         if (itemsToSplit.length === 0) continue
 
@@ -468,7 +517,9 @@ function removeTimelineRangesFromItems(
       const removedRangeKeys = new Set<string>()
 
       for (const descriptor of anchorDescriptors) {
-        const ranges = rangesByMediaId[descriptor.mediaId]
+        const ranges = rangesByItemId
+          ? rangesByItemId[descriptor.id]
+          : rangesByMediaId[descriptor.mediaId]
         if (!ranges || ranges.length === 0) continue
 
         for (const candidate of currentItems) {
@@ -476,6 +527,13 @@ function removeTimelineRangesFromItems(
           if (candidate.mediaId !== descriptor.mediaId) continue
           if ((candidate.originId ?? candidate.id) !== descriptor.originId) continue
 
+          if (
+            rangesByItemId &&
+            (candidate.from < descriptor.from ||
+              candidate.from + candidate.durationInFrames > descriptor.to)
+          )
+            continue
+
           const span = getItemSourceSpanSeconds(candidate, timelineFps)
           if (span !== null && isMostlyInsideRanges(span, ranges)) {
             idsToRemove.add(candidate.id)
@@ -497,7 +555,7 @@ function removeTimelineRangesFromItems(
         }
       }
 
-      const removalResult = applyRippleRemoval(Array.from(idsToRemove))
+      const removalResult = applyRippleRemoval(Array.from(idsToRemove), !!rangesByItemId)
       const affectedIds = Array.from(new Set([...idsToRemove, ...removalResult.affectedIds]))
       requestPostEditWarmForItems(affectedIds)
       useTimelineSettingsStore.getState().markDirty()
diff --git a/src/features/timeline/stores/actions/range-removal-actions.test.ts b/src/features/timeline/stores/actions/range-removal-actions.test.ts
index 0419c8de5..710e24cd2 100644
--- a/src/features/timeline/stores/actions/range-removal-actions.test.ts
+++ b/src/features/timeline/stores/actions/range-removal-actions.test.ts
@@ -9,7 +9,10 @@ import { useItemsStore } from '../items-store'
 import { useTimelineCommandStore } from '../timeline-command-store'
 import { useTimelineSettingsStore } from '../timeline-settings-store'
 import { useTransitionsStore } from '../transitions-store'
-import { removeSilenceFromItems } from './edit/range-removal-actions'
+import {
+  removeSilenceFromItems,
+  removeTranscriptRangesFromItems,
+} from './edit/range-removal-actions'
 
 function makeVideoItem(overrides: Partial<VideoItem> = {}): VideoItem {
   return {
@@ -128,4 +131,57 @@ describe('removeSilenceFromItems', () => {
     expect(sourceSpans('video')).toHaveLength(2)
     expect(sourceSpans('audio')).toHaveLength(2)
   })
+  it('cuts only selected occurrence ranges with linked audio and restores once', () => {
+    useEditorStore.setState({ linkedSelectionEnabled: false })
+    const original = [
+      makeVideoItem({ linkedGroupId: 'av' }),
+      makeAudioItem({ linkedGroupId: 'av' }),
+      makeVideoItem({ id: 'repeat', from: 300 }),
+    ]
+    useItemsStore.getState().setItems(original)
+    const result = removeTranscriptRangesFromItems(
+      ['video-1'],
+      { 'media-1': [{ start: 2, end: 4 }] },
+      { 'video-1': [{ start: 2, end: 4 }] },
+    )
+    expect(result.removedItemCount).toBe(2)
+    expect(useItemsStore.getState().itemById.repeat).toMatchObject({
+      sourceStart: 0,
+      sourceEnd: 300,
+      durationInFrames: 300,
+      from: 240,
+    })
+    expect(sourceSpans('audio')).toEqual([
+      { from: 0, durationInFrames: 60, sourceStart: 0, sourceEnd: 60 },
+      { from: 60, durationInFrames: 180, sourceStart: 120, sourceEnd: 300 },
+    ])
+    useTimelineCommandStore.getState().undo()
+    expect(useItemsStore.getState().items).toEqual(original)
+    useTimelineCommandStore.getState().redo()
+    expect(useItemsStore.getState().itemById.repeat).toMatchObject({
+      sourceStart: 0,
+      sourceEnd: 300,
+      durationInFrames: 300,
+    })
+  })
+
+  it('does not cross-apply ranges when two selected occurrences share media and origin', () => {
+    useItemsStore.getState().setItems([makeVideoItem(), makeVideoItem({ id: 'repeat', from: 300 })])
+    removeTranscriptRangesFromItems(
+      ['video-1', 'repeat'],
+      {
+        'media-1': [
+          { start: 2, end: 4 },
+          { start: 6, end: 7 },
+        ],
+      },
+      { 'video-1': [{ start: 2, end: 4 }], repeat: [{ start: 6, end: 7 }] },
+    )
+    expect(sourceSpans('video')).toEqual([
+      { from: 0, durationInFrames: 60, sourceStart: 0, sourceEnd: 60 },
+      { from: 60, durationInFrames: 180, sourceStart: 120, sourceEnd: 300 },
+      { from: 240, durationInFrames: 180, sourceStart: 0, sourceEnd: 180 },
+      { from: 420, durationInFrames: 90, sourceStart: 210, sourceEnd: 300 },
+    ])
+  })
 })
diff --git a/src/features/timeline/types.ts b/src/features/timeline/types.ts
index 2a4ffeacc..9af1ea4c3 100644
--- a/src/features/timeline/types.ts
+++ b/src/features/timeline/types.ts
@@ -118,6 +118,7 @@ export interface TimelineActions {
   removeTranscriptRangesFromItems: (
     itemIds: string[],
     rangesByMediaId: Record<string, Array<{ start: number; end: number }>>,
+    rangesByItemId?: Record<string, Array<{ start: number; end: number }>>,
   ) => {
     analyzedItemCount: number
     removedRangeCount: number
diff --git a/src/features/timeline/utils/transcript-edit-model.test.ts b/src/features/timeline/utils/transcript-edit-model.test.ts
index 2b099cf89..3c55f91fb 100644
--- a/src/features/timeline/utils/transcript-edit-model.test.ts
+++ b/src/features/timeline/utils/transcript-edit-model.test.ts
@@ -91,8 +91,8 @@ describe('buildTranscriptTokens', () => {
 
   it('does not duplicate words for a linked video + audio pair', () => {
     // Same media, same source span (a linked companion) — words appear once.
-    const video = makeItem({ id: 'v', type: 'video', mediaId: 'm1' })
-    const audio = makeItem({ id: 'a', type: 'audio', mediaId: 'm1' })
+    const video = makeItem({ id: 'v', type: 'video', mediaId: 'm1', linkedGroupId: 'linked' })
+    const audio = makeItem({ id: 'a', type: 'audio', mediaId: 'm1', linkedGroupId: 'linked' })
     const transcript = makeTranscript('m1', [
       { text: 'hello', start: 0, end: 0.5 },
       { text: 'world', start: 0.5, end: 1.0 },
@@ -134,9 +134,8 @@ describe('buildTranscriptTokens', () => {
     expect(tokens.every((t) => t.itemId === 'v')).toBe(true)
   })
 
-  it('collapses identical, identically-timed tokens from different media', () => {
-    // Same footage imported as two separate media (different mediaIds) stacked at
-    // the same spot escapes per-media dedup, so the token-level net must catch it.
+  it('retains independent identical words from different media', () => {
+    // Independently placed sources must remain independently selectable.
     const a = makeItem({ id: 'a', type: 'video', mediaId: 'm1', from: 0, durationInFrames: 300 })
     const b = makeItem({ id: 'b', type: 'audio', mediaId: 'm2', from: 0, durationInFrames: 300 })
     const words = [
@@ -149,7 +148,7 @@ describe('buildTranscriptTokens', () => {
       { m1: makeTranscript('m1', words), m2: makeTranscript('m2', words) },
       FPS,
     )
-    expect(tokens.map((t) => t.text)).toEqual(['hello', 'world'])
+    expect(tokens.map((t) => t.text)).toEqual(['hello', 'hello', 'world', 'world'])
   })
 
   it('keeps distinct trims of the same media', () => {
diff --git a/src/features/timeline/utils/transcript-edit-model.ts b/src/features/timeline/utils/transcript-edit-model.ts
index bbce1cdf7..3ee67278a 100644
--- a/src/features/timeline/utils/transcript-edit-model.ts
+++ b/src/features/timeline/utils/transcript-edit-model.ts
@@ -62,12 +62,7 @@ export function buildTranscriptTokens(
   timelineFps: number,
 ): TranscriptToken[] {
   const tokens: TranscriptToken[] = []
-  // Timeline ranges already emitted per media. A linked audio companion shares
-  // the exact `from`/duration of its video, so deduping on the timeline range
-  // (rather than the source span, which can differ between a video and its
-  // separately-based audio frames) reliably drops the companion. Distinct trims
-  // of the same media sit at different timeline positions and are both kept.
-  const acceptedRangesByMedia = new Map<string, Array<{ from: number; to: number }>>()
+  const acceptedCohorts = new Set<string>()
 
   // Prefer the video item when a video/audio pair covers the same range.
   const ordered = [...items].sort((a, b) => Number(a.type !== 'video') - Number(b.type !== 'video'))
@@ -79,12 +74,11 @@ export function buildTranscriptTokens(
     const span = getItemSourceSpanSeconds(item, timelineFps)
     if (!span) continue
 
-    const from = item.from
-    const to = item.from + item.durationInFrames
-    const accepted = acceptedRangesByMedia.get(item.mediaId) ?? []
-    if (accepted.some((other) => other.from < to && from < other.to)) continue
-    accepted.push({ from, to })
-    acceptedRangesByMedia.set(item.mediaId, accepted)
+    const cohort = item.linkedGroupId
+      ? `${item.linkedGroupId}:${item.mediaId}:${item.from}:${item.durationInFrames}:${span.start}:${span.end}`
+      : null
+    if (cohort && acceptedCohorts.has(cohort)) continue
+    if (cohort) acceptedCohorts.add(cohort)
 
     const words = collectWords(transcript)
     words.forEach((word, index) => {
@@ -106,20 +100,7 @@ export function buildTranscriptTokens(
     })
   }
 
-  const sorted = tokens.toSorted((left, right) => left.startFrame - right.startFrame)
-
-  // Final safety net: collapse tokens identical in text AND exact timeline timing.
-  // Two sources of the same spoken content (a linked companion, or the same
-  // footage imported as separate media so it escapes per-media dedup above) emit
-  // word-for-word identical, identically-timed tokens. Genuinely distinct clips
-  // map to different frames, so real repeated words are preserved.
-  const seen = new Set<string>()
-  return sorted.filter((token) => {
-    const signature = `${token.startFrame}:${token.endFrame}:${token.text}`
-    if (seen.has(signature)) return false
-    seen.add(signature)
-    return true
-  })
+  return tokens.toSorted((left, right) => left.startFrame - right.startFrame)
 }
 
 /**
@@ -174,6 +155,20 @@ export function buildRemovalRangesByMediaId(
   return rangesByMediaId
 }
 
+/** Keep source ranges isolated per selected occurrence, including repeated source runs. */
+export function buildRemovalRangesByItemId(
+  tokens: readonly TranscriptToken[],
+): Record<string, RemoveSilenceRange[]> {
+  const ranges: Record<string, RemoveSilenceRange[]> = {}
+  for (const token of tokens) {
+    const list = ranges[token.itemId] ?? (ranges[token.itemId] = [])
+    const previous = list.at(-1)
+    if (previous) previous.end = Math.max(previous.end, token.sourceEnd)
+    else list.push({ start: token.sourceStart, end: token.sourceEnd })
+  }
+  return ranges
+}
+
 /** Resolve a contiguous index range [anchor, focus] into the tokens it covers. */
 export function getSelectedTokenSlice(
   tokens: readonly TranscriptToken[],
diff --git a/src/shared/utils/transcript-selection.ts b/src/shared/utils/transcript-selection.ts
new file mode 100644
index 000000000..3134bb149
--- /dev/null
+++ b/src/shared/utils/transcript-selection.ts
@@ -0,0 +1,19 @@
+/** Keyboard movement in a flat, document-ordered transcript. */
+export function transcriptSelectionIndex(
+  key: string,
+  current: number,
+  length: number,
+): number | null {
+  if (length === 0) return null
+  if (key === 'Home') return 0
+  if (key === 'End') return length - 1
+  const directions: Record<string, number> = {
+    ArrowLeft: -1,
+    ArrowUp: -1,
+    ArrowRight: 1,
+    ArrowDown: 1,
+  }
+  const direction = directions[key]
+  if (direction === undefined) return null
+  return Math.max(0, Math.min(length - 1, Math.max(0, current) + direction))
+}

From f38cd372d0aec1cc6b90b7f189ac90a212292c8c Mon Sep 17 00:00:00 2001
From: Patrick Lu <lightning.lu7@gmail.com>
Date: Tue, 8 Sep 2026 13:48:01 -0700
Subject: [PATCH 08/22] feat(captions): expose edited-sequence captions in
 Library

---
 docs/qa/ux7144-pr5-captions.md                |  70 +++++
 playwright.caption-refresh.config.ts          |  17 ++
 src/config/editor-workspaces.ts               |   2 +
 .../docs/pages/11-text-captions-subtitles.ts  |   5 +-
 .../editor/codepress/caption-editor-view.tsx  |  20 +-
 .../editor/codepress/caption-editor.tsx       |   4 +-
 .../editor/components/media-sidebar.tsx       |  13 +
 .../editor/host/caption-generation.test.ts    | 131 +++++++++
 .../editor/host/caption-generation.ts         | 209 ++++++++++++++
 src/features/editor/host/caption-library.tsx  | 254 ++++++++++++++++++
 .../host/caption-render-contract.test.ts      | 160 +++++++++++
 src/features/editor/host/document.ts          |  30 ++-
 src/features/editor/host/runtime.ts           |   2 +-
 tests/browser/caption-refresh.html            |   1 +
 tests/browser/caption-refresh.spec.ts         | 183 +++++++++++++
 tests/browser/caption-refresh.tsx             | 243 +++++++++++++++++
 16 files changed, 1333 insertions(+), 11 deletions(-)
 create mode 100644 docs/qa/ux7144-pr5-captions.md
 create mode 100644 playwright.caption-refresh.config.ts
 create mode 100644 src/features/editor/host/caption-generation.test.ts
 create mode 100644 src/features/editor/host/caption-generation.ts
 create mode 100644 src/features/editor/host/caption-library.tsx
 create mode 100644 src/features/editor/host/caption-render-contract.test.ts
 create mode 100644 tests/browser/caption-refresh.html
 create mode 100644 tests/browser/caption-refresh.spec.ts
 create mode 100644 tests/browser/caption-refresh.tsx

diff --git a/docs/qa/ux7144-pr5-captions.md b/docs/qa/ux7144-pr5-captions.md
new file mode 100644
index 000000000..345a2cf1f
--- /dev/null
+++ b/docs/qa/ux7144-pr5-captions.md
@@ -0,0 +1,70 @@
+# Captions Library follow-up
+
+Tracking: quantfive/codepress#7144. This is a dependent draft; its prerequisite
+branch includes PR38, PR39, PR40 and PR4's word-occurrence contract checkpoints.
+The source release target remains `codepress-main`; no package is published here.
+
+## Behavior and limits
+
+Library → More → Captions opens the existing host caption editor alongside a
+non-mutating generation preview. This edit / Selected clip explicitly maps
+measured transcript words into remaining clip occurrences. Missing/incomplete
+word timing, mixed source scopes, old hosts, oversized ranges and locked target
+tracks fail with explanations. This UI cannot align a cached legacy transcript.
+Standalone points to its existing Transcript, clip context menu Generate Captions,
+and temporary Clip settings workflow; it does not add a new local generator.
+
+Apply submits one revision-bound caption-only batch. An unchecked, explicit
+Replace all cues choice is required before replacing the Transcript captions
+track, including its manual corrections. Other tracks are not touched. New
+tracks go above video. Existing generated tracks below video require explicit
+removal and recreation; the tool explains that removal loses manual corrections.
+Text corrections in the caption editor never cut footage.
+
+Track defaults reach the real preview/render projection, cue overrides take
+precedence (including zero opacity), and unchanged effective styles round-trip
+back to their original provenance. Explicit overrides equal to a default remain
+overrides after changing that default. A subsequent clip trim still derives and
+applies as a trim-only command.
+
+## Reproducible fixture verification
+
+- `npm run dev -- --port 4195 --strictPort`
+- `node_modules/.bin/playwright test --config playwright.caption-refresh.config.ts`
+- `npm run test:run -- src/features/editor/host/caption-generation.test.ts src/features/editor/host/caption-render-contract.test.ts src/features/editor/codepress/caption-editor.test.tsx src/features/editor/host/caption-editor-context.test.tsx`
+
+The browser test generates a three-second test-pattern video with sine audio.
+Its source transcript is a controlled test fixture, not provider output from real
+footage. The first occurrence retains source 0–1s and 2–3s; the repeat retains
+0–3s. Expected caption output is HELLO 0–1s, WORLD 1–2s, HELLO UM WORLD 2–5s.
+The fixture adapter submits real surface command batches and renders the host's
+native projection through `window.freecut.renderTimeline`. It is not an
+authenticated CodePress backend test or a pinned consumer adoption test.
+
+Artifacts retained under `artifacts/qa/captions/`:
+
+- `caption-export.webm`: actual five-second rendered AV export.
+- `export-hello.png`: output 0.5s / source 0.5s, HELLO.
+- `export-world.png`: output 1.5s / source 2.5s, WORLD in yellow.
+- `export-repeat.png`: output 3.5s / source 1.5s, HELLO UM WORLD in yellow.
+- `library-1280.png`, `library-1440.png`: Library controls with independent chat.
+
+Browser scenarios cover discovery, preview without mutation, one apply, explicit
+replacement without duplicate cues, selected occurrence + one undo, live style
+preview, navigation retention, and unsupported/pending/missing/error recovery.
+No unprompted human usability session, authenticated provider/backend flow, or
+final CodePress pin/patch/static-asset adoption is claimed. Parent owns those
+integration gates.
+
+## Backend augmentation contract evidence
+
+Read-only inspection of CodePress `apps/backend/apps/video_editor/api.py`
+`apply_video_operation` and `services.py` `apply_command_batch` establishes that
+normal editor submission accepts `VideoCommandBatchRequest`, validates the
+submitted batch, binds the current revision, and hashes the submitted operation
+for idempotency. No transcript preview receipt ID or signed exact-preview binding
+is part of this apply request. Replacement augmentation is checked again by the
+surface command validator before submission. This is source evidence, not a
+backend execution claim; the parent handoff records the inspected checkpoint.
+
+Full exact-head gate results are posted separately on the draft PR.
diff --git a/playwright.caption-refresh.config.ts b/playwright.caption-refresh.config.ts
new file mode 100644
index 000000000..95343ba3c
--- /dev/null
+++ b/playwright.caption-refresh.config.ts
@@ -0,0 +1,17 @@
+// fallow-ignore-file unused-file
+// Invoked explicitly by the caption browser QA command.
+import { defineConfig } from 'playwright/test'
+export default defineConfig({
+  testDir: './tests/browser',
+  testMatch: 'caption-refresh.spec.ts',
+  workers: 1,
+  reporter: 'line',
+  use: {
+    baseURL: 'http://127.0.0.1:4195',
+    channel: 'chrome',
+    headless: true,
+    viewport: { width: 1440, height: 900 },
+    trace: 'retain-on-failure',
+    video: 'retain-on-failure',
+  },
+})
diff --git a/src/config/editor-workspaces.ts b/src/config/editor-workspaces.ts
index fc579fa90..bad4bf5e4 100644
--- a/src/config/editor-workspaces.ts
+++ b/src/config/editor-workspaces.ts
@@ -16,6 +16,7 @@ export type EditorSidebarTab =
   | 'effects'
   | 'transitions'
   | 'lottie'
+  | 'captions'
   | 'transcript'
   | 'ai'
 export type EditorClipInspectorTab = 'video' | 'motion' | 'audio' | 'effects'
@@ -81,6 +82,7 @@ const SIDEBAR_TABS: readonly EditorSidebarTab[] = [
   'effects',
   'transitions',
   'lottie',
+  'captions',
   'transcript',
   'ai',
 ]
diff --git a/src/features/docs/pages/11-text-captions-subtitles.ts b/src/features/docs/pages/11-text-captions-subtitles.ts
index 1cff8e5e9..ec025bdb5 100644
--- a/src/features/docs/pages/11-text-captions-subtitles.ts
+++ b/src/features/docs/pages/11-text-captions-subtitles.ts
@@ -82,7 +82,10 @@ const page = {
         {
           kind: 'steps',
           items: [
-            'Generate a transcript for the clip from the Media library or the Transcript panel.',
+            'Open **Library → More → Captions**. In a host-backed editor, choose **This edit** or **Selected clip**, then **Preview captions** using the current transcript.',
+            'Review the cue text and output times, then **Apply captions**. Replacing an existing generated track requires **Replace all cues**, which also replaces manual corrections in that track. Other caption tracks are preserved.',
+            'Caption text corrections change displayed text only. Transcript footage deletion remains a separate action. Hosts without occurrence-bound caption support explain why generation is unavailable.',
+            'For local media, generate a transcript for the clip from the Media library or the Transcript panel.',
             'Use **Generate Captions** (or let FreeCut enable transcript captions automatically) from the clip context menu.',
             'Edit cue timing and text, and pick a style preset (Netflix, YouTube, Bold Yellow, Outlined, TikTok) in the **Subtitle** section.',
             'Adjust caption color, size, vertical position, and an optional background.',
diff --git a/src/features/editor/codepress/caption-editor-view.tsx b/src/features/editor/codepress/caption-editor-view.tsx
index f7d4b6c73..e52d8d880 100644
--- a/src/features/editor/codepress/caption-editor-view.tsx
+++ b/src/features/editor/codepress/caption-editor-view.tsx
@@ -74,6 +74,7 @@ interface CaptionStyleControlsProps {
 }
 
 interface CaptionPreviewProps {
+  styleDraft: CaptionStyle
   activeCue?: FreeCutFrameCaptionCue
   activeTrack: FreeCutFrameTrack
   currentFrame: number
@@ -111,7 +112,7 @@ function CaptionStyleControls({
         <div>
           <h3 className="text-xs font-semibold">Caption style</h3>
           <p className="text-[11px] text-muted-foreground">
-            Apply a default or cue-specific style through the command contract.
+            Preview a style, then apply it to this track or one cue.
           </p>
         </div>
         <select
@@ -128,7 +129,7 @@ function CaptionStyleControls({
           ))}
         </select>
       </div>
-      <div className="mt-3 grid gap-2 sm:grid-cols-2 lg:grid-cols-4">
+      <div className="mt-3 grid grid-cols-2 gap-2">
         <div>
           <Label htmlFor="caption-font-family" className="text-[11px]">
             Font
@@ -202,8 +203,14 @@ function CaptionStyleControls({
   )
 }
 
-function CaptionPreview({ activeCue, activeTrack, currentFrame, fps }: CaptionPreviewProps) {
-  const previewStyle = captionStyleOrDefault(activeCue?.style ?? activeTrack.defaultStyle)
+function CaptionPreview({
+  activeCue,
+  activeTrack,
+  currentFrame,
+  fps,
+  styleDraft,
+}: CaptionPreviewProps) {
+  const previewStyle = captionStyleOrDefault(styleDraft)
 
   return (
     <div
@@ -211,7 +218,7 @@ function CaptionPreview({ activeCue, activeTrack, currentFrame, fps }: CaptionPr
       data-testid="caption-preview"
     >
       <p className="text-[11px] font-medium uppercase tracking-wide text-muted-foreground">
-        Preview · {formatFrame(currentFrame, fps)}
+        Style preview · {formatFrame(currentFrame, fps)}
       </p>
       <div className="mt-2 flex min-h-14 items-center justify-center rounded bg-black px-4 py-3">
         {activeTrack.muted ? (
@@ -607,6 +614,7 @@ function CaptionTrackEditor({
       />
 
       <CaptionPreview
+        styleDraft={styleDraft}
         activeCue={activeCue}
         activeTrack={activeTrack}
         currentFrame={currentFrame}
@@ -724,7 +732,7 @@ export function CaptionEditorView({
             <h2 className="text-sm font-semibold">Captions</h2>
           </div>
           <p className="mt-1 text-xs text-muted-foreground">
-            Frame-aligned cues are saved through the controlled command contract.
+            Edit the text displayed in your video. Text corrections never remove footage.
           </p>
         </div>
         <Button
diff --git a/src/features/editor/codepress/caption-editor.tsx b/src/features/editor/codepress/caption-editor.tsx
index 000530548..44a2e2144 100644
--- a/src/features/editor/codepress/caption-editor.tsx
+++ b/src/features/editor/codepress/caption-editor.tsx
@@ -223,11 +223,11 @@ export function CaptionEditor({
         track_id: trackId,
         name: `Captions ${tracks.length + 1}`,
         language: 'en',
-        index: document?.tracks.length ?? 0,
+        index: 0,
       },
     ])
     if (applied) setActiveTrackId(trackId)
-  }, [document?.tracks.length, runCommands, tracks])
+  }, [runCommands, tracks])
 
   const removeTrack = useCallback(async () => {
     if (!activeTrack) return
diff --git a/src/features/editor/components/media-sidebar.tsx b/src/features/editor/components/media-sidebar.tsx
index 32008c4b1..ce6b49863 100644
--- a/src/features/editor/components/media-sidebar.tsx
+++ b/src/features/editor/components/media-sidebar.tsx
@@ -62,6 +62,7 @@ import { createLogger } from '@/shared/logging/logger'
 import { useSettingsStore } from '@/features/editor/deps/settings'
 import { resolveGeneratedLayerCanvasSize } from '../utils/generated-layer-canvas-size'
 import { useEditorCapability, useEditorHostContext, useEditorHostMode } from '../host/context'
+import { HostCaptionLibrary } from '../host/caption-library'
 import { HostTranscriptEditor } from '../host/transcript-editor'
 const LazyAiPanel = lazy(() => import('./ai-tab').then((m) => ({ default: m.AiTab })))
 const LazyTranscriptEditorPanel = lazy(() =>
@@ -547,6 +548,10 @@ export const MediaSidebar = memo(function MediaSidebar({
     toggleLeftSidebar,
   })
 
+  const [captionsActivated, setCaptionsActivated] = useState(activeTab === 'captions')
+  useEffect(() => {
+    if (activeTab === 'captions') setCaptionsActivated(true)
+  }, [activeTab])
   const [transcriptActivated, setTranscriptActivated] = useState(activeTab === 'transcript')
   useEffect(() => {
     if (activeTab === 'transcript') setTranscriptActivated(true)
@@ -795,6 +800,7 @@ export const MediaSidebar = memo(function MediaSidebar({
   // Category items for the vertical nav
   const categories = [
     { id: 'media' as const, icon: Film, label: t('editor.mediaSidebar.media') },
+    { id: 'captions' as const, icon: Captions, label: 'Captions' },
     { id: 'text' as const, icon: Type, label: t('editor.mediaSidebar.text') },
     { id: 'shapes' as const, icon: Pentagon, label: t('editor.mediaSidebar.shapes') },
     { id: 'effects' as const, icon: Layers, label: t('editor.mediaSidebar.effects') },
@@ -807,6 +813,7 @@ export const MediaSidebar = memo(function MediaSidebar({
     ? categories.filter(
         ({ id }) =>
           id === 'media' ||
+          id === 'captions' ||
           (id === 'text' && canAddTimeline) ||
           (id === 'transcript' && canTranscribe && !!host?.transcript),
       )
@@ -1408,6 +1415,12 @@ export const MediaSidebar = memo(function MediaSidebar({
               {lottieTabActivated && <LottieBrowserPanel />}
             </div>
 
+            <div
+              className={`min-h-0 flex-1 overflow-y-auto ${activeTab === 'captions' ? 'block' : 'hidden'}`}
+            >
+              {captionsActivated && <HostCaptionLibrary />}
+            </div>
+
             {/* Transcript Tab */}
             <TranscriptSidebarContent
               activeTab={activeTab}
diff --git a/src/features/editor/host/caption-generation.test.ts b/src/features/editor/host/caption-generation.test.ts
new file mode 100644
index 000000000..5a6606826
--- /dev/null
+++ b/src/features/editor/host/caption-generation.test.ts
@@ -0,0 +1,131 @@
+import { describe, expect, it, vi } from 'vite-plus/test'
+import type { FreeCutFrameClip, FreeCutFrameDocument } from '../codepress/document'
+import type { EditorTranscriptPort, HostTranscriptSection } from './contract'
+import {
+  captionRangesForEdit,
+  assertCaptionTargetAvailable,
+  loadCaptionSections,
+  validateCaptionPreview,
+} from './caption-generation'
+
+const section: HostTranscriptSection = {
+  id: 's',
+  transcriptId: 't',
+  ordinal: 0,
+  startUs: 0,
+  endUs: 3_000_000,
+  text: 'hello um world',
+  timingSource: 'provider',
+  words: [
+    { text: 'hello', startUs: 0, endUs: 1_000_000 },
+    { text: 'um', startUs: 1_000_000, endUs: 2_000_000 },
+    { text: 'world', startUs: 2_000_000, endUs: 3_000_000 },
+  ],
+}
+const clip: FreeCutFrameClip = {
+  type: 'video',
+  id: 'a',
+  trackId: 'v',
+  mediaId: 'm',
+  from: 0,
+  durationInFrames: 30,
+  sourceStart: 0,
+  sourceEnd: 30,
+}
+const document: FreeCutFrameDocument = {
+  timelineId: 'timeline',
+  revision: 4,
+  fps: 30,
+  width: 1280,
+  height: 720,
+  durationInFrames: 150,
+  media: [],
+  tracks: [
+    {
+      id: 'v',
+      kind: 'video',
+      name: 'Video',
+      locked: false,
+      muted: false,
+      items: [
+        clip,
+        { ...clip, id: 'after-cut', from: 30, sourceStart: 60, sourceEnd: 90 },
+        { ...clip, id: 'repeat', from: 60, durationInFrames: 90, sourceEnd: 90 },
+      ],
+    },
+  ],
+}
+
+describe('captions from the edited sequence', () => {
+  it('excludes removed words while retaining an untouched repeated occurrence', () => {
+    expect(captionRangesForEdit(document, 'm', [section])).toEqual([
+      { itemId: 'a', startUs: 0, endUs: 1_000_000, text: 'hello' },
+      { itemId: 'after-cut', startUs: 2_000_000, endUs: 3_000_000, text: 'world' },
+      { itemId: 'repeat', startUs: 0, endUs: 3_000_000, text: 'hello um world' },
+    ])
+    expect(captionRangesForEdit(document, 'm', [section], new Set(['after-cut']))).toEqual([
+      { itemId: 'after-cut', startUs: 2_000_000, endUs: 3_000_000, text: 'world' },
+    ])
+  })
+  it('clamps measured word boundaries to trimmed source handles for caption containment', () => {
+    const trimmed = {
+      ...document,
+      tracks: [
+        { ...document.tracks[0]!, items: [{ ...clip, sourceStart: 15, sourceEnd: 75, speed: 2 }] },
+      ],
+    }
+    expect(captionRangesForEdit(trimmed, 'm', [section])).toEqual([
+      { itemId: 'a', startUs: 500_000, endUs: 2_500_000, text: 'hello um world' },
+    ])
+  })
+  it('fails honestly without real timing or selected clips', () => {
+    expect(() =>
+      captionRangesForEdit(document, 'm', [{ ...section, timingSource: 'synthetic' }]),
+    ).toThrow('No timed transcript')
+    expect(() => captionRangesForEdit(document, 'm', [section], new Set())).toThrow(
+      'No timed transcript',
+    )
+  })
+  it('loads all pages and rejects a repeated cursor instead of silently captioning a partial edit', async () => {
+    const getSections = vi
+      .fn()
+      .mockResolvedValueOnce({
+        transcriptId: 't',
+        sections: [section],
+        hasMore: true,
+        nextCursor: 'next',
+      })
+      .mockResolvedValue({ transcriptId: 't', sections: [], hasMore: true, nextCursor: 'next' })
+    await expect(
+      loadCaptionSections({ getSections } as unknown as EditorTranscriptPort, 't'),
+    ).rejects.toThrow('completely')
+  })
+  it('rejects a footage-changing command masquerading as captions', () => {
+    expect(() =>
+      validateCaptionPreview(
+        { commandBatch: { commands: [{ type: 'ripple_delete' }] } } as never,
+        {} as never,
+        'timeline',
+      ),
+    ).toThrow()
+  })
+  it('rejects an existing generated caption track hidden below video or locked', () => {
+    const track = {
+      id: 'host-transcript-captions',
+      name: 'Transcript captions',
+      kind: 'caption' as const,
+      locked: false,
+      muted: false,
+      items: [],
+    }
+    expect(() =>
+      assertCaptionTargetAvailable({ ...document, tracks: [...document.tracks, track] }, true),
+    ).toThrow('below video')
+    expect(() =>
+      assertCaptionTargetAvailable({ ...document, tracks: [{ ...track, locked: true }] }, true),
+    ).toThrow('locked')
+    expect(() => assertCaptionTargetAvailable({ ...document, tracks: [track] }, false)).toThrow(
+      'Replace all cues',
+    )
+  })
+})
diff --git a/src/features/editor/host/caption-generation.ts b/src/features/editor/host/caption-generation.ts
new file mode 100644
index 000000000..33cbc1d3c
--- /dev/null
+++ b/src/features/editor/host/caption-generation.ts
@@ -0,0 +1,209 @@
+import { makeCaptionOperationId } from '../codepress/caption-commands'
+import { validateCommandBatch } from '../codepress/contract'
+import type { FreeCutFrameDocument } from '../codepress/document'
+import { framesToMicroseconds } from '../codepress/timing'
+import {
+  MAX_TRANSCRIPT_SELECTIONS,
+  type EditorTranscriptPort,
+  type HostTranscriptCommandPreview,
+  type HostTranscriptCommandPreviewRequest,
+  type HostTranscriptSection,
+  type HostTranscriptStatusReceipt,
+} from './contract'
+import {
+  hasUsableHostWordTiming,
+  hostWordSelectionRanges,
+  mapHostTranscriptWords,
+} from './transcript-words'
+
+/** Caption ranges describe only the footage remaining in each edited occurrence. */
+export function captionRangesForEdit(
+  document: FreeCutFrameDocument,
+  assetId: string,
+  sections: readonly HostTranscriptSection[],
+  selectedItemIds?: ReadonlySet<string>,
+) {
+  const scopedClips = document.tracks
+    .flatMap((track) => track.items)
+    .filter(
+      (item) =>
+        (item.type === 'video' || item.type === 'audio') &&
+        (!selectedItemIds || selectedItemIds.has(item.id)),
+    )
+  if (
+    scopedClips.some(
+      (item) => (item.type === 'video' || item.type === 'audio') && item.mediaId !== assetId,
+    )
+  ) {
+    throw new Error(
+      'This scope includes media without the current host transcript. Choose a clip belonging to that transcript, Caption generation currently supports only the host’s current transcript source.',
+    )
+  }
+  if (sections.some((section) => !hasUsableHostWordTiming(section))) {
+    throw new Error(
+      'No timed transcript can be used safely: measured word timing is missing or incomplete. Caption creation from this transcript is unavailable.',
+    )
+  }
+  const clips = new Map(
+    document.tracks.flatMap((track) => track.items).map((item) => [item.id, item]),
+  )
+  const words = mapHostTranscriptWords(document, assetId, sections)
+    .filter((word) => !selectedItemIds || selectedItemIds.has(word.itemId))
+    .map((word) => {
+      const clip = clips.get(word.itemId)!
+      if (clip.type !== 'video' && clip.type !== 'audio') return word
+      return {
+        ...word,
+        sourceStartUs: Math.max(
+          word.sourceStartUs,
+          framesToMicroseconds(clip.sourceStart ?? 0, document.fps),
+        ),
+        sourceEndUs: Math.min(
+          word.sourceEndUs,
+          framesToMicroseconds(
+            clip.sourceEnd ?? (clip.sourceStart ?? 0) + clip.durationInFrames * (clip.speed ?? 1),
+            document.fps,
+          ),
+        ),
+      }
+    })
+  const ranges = hostWordSelectionRanges(words)
+  if (!ranges.length)
+    throw new Error(
+      'No timed transcript words remain in this scope. Select a clip covered by the current transcript.',
+    )
+  if (ranges.length > MAX_TRANSCRIPT_SELECTIONS)
+    throw new Error(
+      `This edit needs more than ${MAX_TRANSCRIPT_SELECTIONS} caption ranges. Choose Selected clip to create a smaller caption batch.`,
+    )
+  return ranges
+}
+
+export async function loadCaptionSections(port: EditorTranscriptPort, transcriptId: string) {
+  const sections: HostTranscriptSection[] = []
+  const cursors = new Set<string>()
+  let cursor: string | null = null
+  for (let pageIndex = 0; pageIndex < 200; pageIndex++) {
+    const page = await port.getSections({ transcriptId, cursor, limit: 50 })
+    if (page.transcriptId !== transcriptId)
+      throw new Error('The transcript changed. Reload captions and try again.')
+    sections.push(...page.sections)
+    if (!page.hasMore) return sections
+    if (!page.nextCursor || cursors.has(page.nextCursor))
+      throw new Error('The transcript could not be loaded completely. Retry loading captions.')
+    cursor = page.nextCursor
+    cursors.add(cursor)
+  }
+  throw new Error('This transcript is too large to load here. Choose a shorter edit.')
+}
+
+const CAPTION_COMMANDS = new Set([
+  'add_caption_track',
+  'update_caption_track',
+  'remove_caption_track',
+  'upsert_caption_cues',
+  'remove_caption_cues',
+  'set_caption_style',
+])
+
+/** Never allow a caption preview to smuggle a footage edit or a different revision. */
+export function validateCaptionPreview(
+  preview: HostTranscriptCommandPreview,
+  request: HostTranscriptCommandPreviewRequest,
+  timelineId: string,
+) {
+  const validation = validateCommandBatch(preview.commandBatch)
+  if (
+    !validation.ok ||
+    preview.transcriptId !== request.transcriptId ||
+    preview.assetId !== request.assetId ||
+    preview.sourceAssetHash !== request.sourceAssetHash ||
+    preview.timelineId !== timelineId ||
+    preview.baseRevision !== request.baseRevision ||
+    preview.preview.willMutateTimeline !== false ||
+    (preview.preview.action !== undefined &&
+      !['caption', 'captions'].includes(preview.preview.action)) ||
+    preview.commandBatch.timeline_id !== timelineId ||
+    preview.commandBatch.base_revision !== request.baseRevision ||
+    preview.commandBatch.operation_id !== preview.operationId ||
+    preview.commandBatch.idempotency_key !== preview.idempotencyKey ||
+    !preview.commandBatch.commands.length ||
+    !preview.commandBatch.commands.every(
+      (command) =>
+        CAPTION_COMMANDS.has(command.type) &&
+        'track_id' in command &&
+        command.track_id === request.captionTrackId,
+    )
+  ) {
+    throw new Error('The caption preview does not match this edit. Reload captions and try again.')
+  }
+  return preview
+}
+
+export function captionStatusOrThrow(
+  status: HostTranscriptStatusReceipt | null,
+): HostTranscriptStatusReceipt & { assetId: string } {
+  if (status?.status === 'succeeded' && status.assetId)
+    return { ...status, assetId: status.assetId }
+  const pending = status?.status === 'pending' || status?.status === 'running'
+  throw new Error(
+    pending
+      ? 'Transcription is still processing. Return to Transcript to follow progress, then retry.'
+      : 'A completed transcript is needed. Open Transcript to check available transcription options, then return here.',
+  )
+}
+
+export function assertCaptionTargetAvailable(document: FreeCutFrameDocument, replaceAll: boolean) {
+  const index = document.tracks.findIndex((track) => track.id === 'host-transcript-captions')
+  const track = document.tracks[index]
+  if (!track) return
+  if (track.locked)
+    throw new Error('The generated caption track is locked. Unlock it before replacing captions.')
+  if (!replaceAll)
+    throw new Error(
+      'Choose Replace all cues to replace Transcript captions, including manual corrections.',
+    )
+  if (
+    document.tracks
+      .slice(0, index)
+      .some((candidate) => candidate.kind === 'video' || candidate.kind === 'overlay')
+  ) {
+    throw new Error(
+      'This caption track is below video and may be hidden. Remove this track using Remove track below, then preview captions to create a new top track. Removing a track discards its manual corrections.',
+    )
+  }
+}
+
+export function replaceGeneratedCaptionCues(
+  preview: HostTranscriptCommandPreview,
+  request: HostTranscriptCommandPreviewRequest,
+  document: FreeCutFrameDocument,
+) {
+  const previousCues =
+    document.tracks
+      .find((track) => track.id === request.captionTrackId)
+      ?.items.filter((item) => item.type === 'caption_cue') ?? []
+  const commands = preview.commandBatch.commands.map((command) =>
+    command.type === 'add_caption_track' ? { ...command, index: 0 } : command,
+  )
+  const replacement = {
+    ...preview,
+    commandBatch: {
+      ...preview.commandBatch,
+      commands: [
+        ...(previousCues.length
+          ? [
+              {
+                type: 'remove_caption_cues' as const,
+                command_id: makeCaptionOperationId('replace-captions'),
+                track_id: request.captionTrackId!,
+                cue_ids: previousCues.map((cue) => cue.id),
+              },
+            ]
+          : []),
+        ...commands,
+      ],
+    },
+  }
+  return validateCaptionPreview(replacement, request, document.timelineId)
+}
diff --git a/src/features/editor/host/caption-library.tsx b/src/features/editor/host/caption-library.tsx
new file mode 100644
index 000000000..a16fbd1a4
--- /dev/null
+++ b/src/features/editor/host/caption-library.tsx
@@ -0,0 +1,254 @@
+import { useEffect, useState } from 'react'
+import { Button } from '@/components/ui/button'
+import { useSelectionStore } from '@/shared/state/selection'
+import { usePlaybackStore } from '@/shared/state/playback'
+import { useEditorStore } from '@/shared/state/editor'
+import { makeCaptionOperationId } from '../codepress/caption-commands'
+import { HostCaptionEditor } from './caption-editor-context'
+import {
+  captionRangesForEdit,
+  loadCaptionSections,
+  validateCaptionPreview,
+  captionStatusOrThrow,
+  assertCaptionTargetAvailable,
+  replaceGeneratedCaptionCues,
+} from './caption-generation'
+import { useEditorCapability, useEditorHostContext } from './context'
+import type { HostTranscriptCommandPreview, HostTranscriptCommandPreviewRequest } from './contract'
+import { useHostTranscriptEditorRuntime } from './transcript-editor-context'
+
+/** Focused Library tool: generation previews never modify footage. */
+export function HostCaptionLibrary() {
+  const { host, mode } = useEditorHostContext()
+  const runtime = useHostTranscriptEditorRuntime()
+  const canCaption = useEditorCapability('timeline.caption')
+  const selectedIds = useSelectionStore((state) => state.selectedItemIds)
+  const [scope, setScope] = useState('edit')
+  const [replaceAll, setReplaceAll] = useState(false)
+  const [hasGeneratedTrack, setHasGeneratedTrack] = useState(false)
+  const [busy, setBusy] = useState(false)
+  const [message, setMessage] = useState('')
+  const [error, setError] = useState(false)
+  const [preview, setPreview] = useState<HostTranscriptCommandPreview | null>(null)
+  const port = host?.transcript
+
+  useEffect(() => {
+    if (!runtime) return
+    const sync = () => {
+      setPreview(null)
+      setReplaceAll(false)
+      setHasGeneratedTrack(
+        runtime.controller
+          .getSnapshot()
+          .timeline.tracks.some((track) => track.id === 'host-transcript-captions'),
+      )
+    }
+    sync()
+    return runtime.controller.subscribe(sync)
+  }, [runtime])
+  useEffect(() => setPreview(null), [scope, selectedIds])
+
+  async function prepare() {
+    if (!port || !runtime || busy) return
+    setBusy(true)
+    setError(false)
+    setPreview(null)
+    setMessage('Loading the edited transcript…')
+    try {
+      const status = captionStatusOrThrow(await port.getStatus())
+      const snapshot = runtime.controller.getSnapshot()
+      assertCaptionTargetAvailable(snapshot.timeline, replaceAll)
+      const sections = await loadCaptionSections(port, status.transcriptId)
+      const ranges = captionRangesForEdit(
+        snapshot.timeline,
+        status.assetId,
+        sections,
+        scope === 'selected' ? new Set(selectedIds) : undefined,
+      )
+      const request: HostTranscriptCommandPreviewRequest = {
+        transcriptId: status.transcriptId,
+        assetId: status.assetId,
+        sourceAssetHash: status.sourceAssetHash,
+        operationId: makeCaptionOperationId('caption-preview'),
+        idempotencyKey: makeCaptionOperationId('caption-preview-key'),
+        baseRevision: snapshot.timeline.revision,
+        action: 'captions',
+        timestampCapability: 'section',
+        ranges,
+        captionTrackId: 'host-transcript-captions',
+        captionTrackName: 'Transcript captions',
+        captionLanguage: status.language,
+      }
+      const validated = validateCaptionPreview(
+        await port.previewCommands(request),
+        request,
+        snapshot.timeline.timelineId,
+      )
+      if (runtime.controller.getSnapshot().timeline.revision !== snapshot.timeline.revision)
+        throw new Error(
+          'The edit changed while captions were loading. Preview again using the latest edit.',
+        )
+      setPreview(replaceGeneratedCaptionCues(validated, request, snapshot.timeline))
+      setMessage(
+        'Review the cues below. Apply replaces the generated caption track in one undoable edit.',
+      )
+    } catch (caught) {
+      setError(true)
+      setMessage(
+        caught instanceof Error ? caught.message : 'Could not prepare captions. Retry preview.',
+      )
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  async function apply() {
+    if (!runtime || !preview || busy) return
+    setBusy(true)
+    setError(false)
+    setMessage('Applying captions…')
+    try {
+      const result = await runtime.controller.submitEdit(preview.commandBatch)
+      if (result.status !== 'applied' && result.status !== 'replayed')
+        throw new Error(
+          result.status === 'unsupported'
+            ? result.reason
+            : 'Caption apply did not complete. Preview again using the latest edit.',
+        )
+      setPreview(null)
+      setMessage(
+        'Captions applied. Use Undo to restore the previous captions. Text corrections here never cut footage.',
+      )
+    } catch (caught) {
+      setError(true)
+      setMessage(
+        caught instanceof Error
+          ? caught.message
+          : 'Could not apply captions. Preview again to retry.',
+      )
+      setPreview(null)
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  const available = canCaption && port?.occurrenceSelection === true
+  const cues =
+    preview?.commandBatch.commands.flatMap((command) =>
+      command.type === 'upsert_caption_cues' ? command.cues : [],
+    ) ?? []
+  return (
+    <div className="min-w-0 space-y-4 p-3" data-testid="caption-library">
+      <div className="space-y-2">
+        <h2 className="text-sm font-semibold">Create captions</h2>
+        <p className="text-xs text-muted-foreground">
+          Captions display text in your video. Create them from the words remaining in this edit,
+          then adjust their text and style below.
+        </p>
+        <label className="block text-xs">
+          Caption scope
+          <select
+            className="mt-1 h-9 w-full rounded-md border border-input bg-background px-2"
+            value={scope}
+            onChange={(event) => setScope(event.target.value)}
+            disabled={busy}
+          >
+            <option value="edit">This edit</option>
+            <option value="selected">Selected clip</option>
+          </select>
+        </label>
+        {!available && (
+          <p role="status" className="text-xs text-muted-foreground">
+            {mode === 'local'
+              ? 'For local media, open Transcript to generate timing. Select a clip and use Generate Captions in its context menu; caption styling is available in Clip settings.'
+              : !port
+                ? 'This host does not provide a transcript. Caption tracks can still be edited below when supported.'
+                : 'This host needs support for captions bound to edited clip occurrences. Caption creation is unavailable until the host is updated.'}
+          </p>
+        )}
+        {hasGeneratedTrack && (
+          <label className="flex items-start gap-2 text-xs">
+            <input
+              type="checkbox"
+              checked={replaceAll}
+              disabled={busy}
+              onChange={(event) => {
+                setReplaceAll(event.target.checked)
+                setPreview(null)
+              }}
+            />
+            Replace all cues in “Transcript captions”, including manual corrections. Other tracks
+            stay unchanged.
+          </label>
+        )}
+        <div className="flex flex-wrap gap-2">
+          <Button
+            size="sm"
+            disabled={
+              !available ||
+              busy ||
+              (hasGeneratedTrack && !replaceAll) ||
+              (scope === 'selected' && !selectedIds.length)
+            }
+            onClick={() => void prepare()}
+          >
+            {busy ? 'Working…' : 'Preview captions'}
+          </Button>
+          <Button
+            size="sm"
+            variant="outline"
+            onClick={() => useEditorStore.getState().setActiveTab('transcript')}
+          >
+            Open Transcript
+          </Button>
+        </div>
+        <p className="text-xs text-muted-foreground">
+          Uses the host’s current transcript asset. Existing captions follow supported footage cuts.
+          Preview again to replace generated captions from the current transcript.
+        </p>
+      </div>
+      {message && (
+        <p role={error ? 'alert' : 'status'} className="text-xs">
+          {message}
+        </p>
+      )}
+      {preview && (
+        <div className="space-y-2 rounded-lg border border-border p-3">
+          <h3 className="text-xs font-semibold">{cues.length} cues ready · footage unchanged</h3>
+          <ul className="max-h-48 space-y-2 overflow-auto">
+            {cues.map((cue) => (
+              <li key={cue.cue_id} className="text-xs">
+                <button
+                  className="text-left hover:underline"
+                  onClick={() => {
+                    const fps = runtime!.controller.getSnapshot().timeline.fps
+                    usePlaybackStore
+                      .getState()
+                      .setCurrentFrame(
+                        Math.round(
+                          (cue.start_us / 1_000_000) * (typeof fps === 'number' ? fps : fps.value),
+                        ),
+                      )
+                  }}
+                >
+                  <span className="text-muted-foreground">
+                    {(cue.start_us / 1_000_000).toFixed(2)}–{(cue.end_us / 1_000_000).toFixed(2)}s
+                  </span>{' '}
+                  {cue.text}
+                </button>
+              </li>
+            ))}
+          </ul>
+          <Button size="sm" disabled={busy} onClick={() => void apply()}>
+            Apply captions
+          </Button>
+        </div>
+      )}
+      <HostCaptionEditor />
+      <p className="text-xs text-muted-foreground">
+        Visible caption tracks appear in the video preview and rendered video. Check captions across
+        each cut before exporting.
+      </p>
+    </div>
+  )
+}
diff --git a/src/features/editor/host/caption-render-contract.test.ts b/src/features/editor/host/caption-render-contract.test.ts
new file mode 100644
index 000000000..dc183a2b5
--- /dev/null
+++ b/src/features/editor/host/caption-render-contract.test.ts
@@ -0,0 +1,160 @@
+import { describe, expect, it } from 'vite-plus/test'
+import { deriveSupportedHostEdit } from './controller'
+import { createCodePressCommandAdapter, freeCutDocumentToControlledDocument } from '../codepress'
+import type { EmbeddedEditorSnapshot } from './contract'
+import { hostSnapshotToNativeTimeline, nativeTimelineToFrameDocument } from './document'
+
+const snapshot: EmbeddedEditorSnapshot = {
+  project: { id: 'project', name: 'Captions', width: 640, height: 360, fps: 30 },
+  assets: [],
+  timeline: {
+    timelineId: 'timeline',
+    revision: 2,
+    fps: 30,
+    width: 640,
+    height: 360,
+    durationInFrames: 60,
+    media: [],
+    tracks: [
+      {
+        id: 'captions',
+        name: 'Captions',
+        kind: 'caption',
+        locked: false,
+        muted: false,
+        defaultStyle: { color: '#ffff00', font_size: 48 },
+        items: [
+          {
+            id: 'cue',
+            type: 'caption_cue',
+            trackId: 'captions',
+            from: 30,
+            durationInFrames: 30,
+            text: 'WORLD',
+          },
+          {
+            id: 'override',
+            type: 'caption_cue',
+            trackId: 'captions',
+            from: 0,
+            durationInFrames: 30,
+            text: 'HELLO',
+            style: { color: '#ff0000', background_opacity: 0 },
+          },
+        ],
+      },
+    ],
+  },
+}
+describe('caption render contract', () => {
+  it('projects track defaults and cue overrides into real preview/export text', () => {
+    const native = hostSnapshotToNativeTimeline(snapshot)
+    expect(native.items[0]).toMatchObject({
+      type: 'text',
+      text: 'WORLD',
+      color: '#ffff00',
+      fontSize: 48,
+      from: 30,
+      durationInFrames: 30,
+    })
+    expect(native.items[1]).toMatchObject({ color: '#ff0000', fontSize: 48 })
+    expect(native.items[1]).toMatchObject({ backgroundOpacity: 0 })
+    const restored = nativeTimelineToFrameDocument(native, snapshot.timeline)
+    expect(restored.ok).toBe(true)
+    if (restored.ok)
+      expect(restored.document.tracks[0]!.items).toEqual(snapshot.timeline.tracks[0]!.items)
+  })
+  it.each(['#ffff00', '#ffffff'])(
+    'keeps explicit %s override equal to the default when the default later changes',
+    (color) => {
+      const track = snapshot.timeline.tracks[0]!
+      const original = {
+        ...snapshot,
+        timeline: {
+          ...snapshot.timeline,
+          tracks: [
+            {
+              ...track,
+              defaultStyle: { color, background_opacity: 0 },
+              items: [{ ...track.items[0]!, style: { color, background_opacity: 0 } }],
+            },
+          ],
+        },
+      }
+      const native = hostSnapshotToNativeTimeline(original)
+      const restored = nativeTimelineToFrameDocument(native, original.timeline)
+      expect(restored.ok).toBe(true)
+      if (!restored.ok) return
+      const changed = hostSnapshotToNativeTimeline({
+        ...original,
+        timeline: {
+          ...restored.document,
+          tracks: restored.document.tracks.map((candidate) => ({
+            ...candidate,
+            defaultStyle: { color: '#ff0000', background_opacity: 1 },
+          })),
+        },
+      })
+      expect(changed.items[0]).toMatchObject({ color, backgroundOpacity: 0 })
+    },
+  )
+  it('derives and applies a subsequent clip trim without turning inherited styles into edits', () => {
+    const original: EmbeddedEditorSnapshot = {
+      ...snapshot,
+      timeline: {
+        ...snapshot.timeline,
+        media: [
+          {
+            media_id: 'media',
+            media_kind: 'video',
+            content_hash: 'hash',
+            duration_us: 3_000_000,
+            availability: { mode: 'cloud', cloud: { object_id: 'media' } },
+          },
+        ],
+        tracks: [
+          ...snapshot.timeline.tracks,
+          {
+            id: 'video',
+            kind: 'video',
+            name: 'Video',
+            locked: false,
+            muted: false,
+            items: [
+              {
+                type: 'video',
+                id: 'clip',
+                trackId: 'video',
+                mediaId: 'media',
+                from: 0,
+                durationInFrames: 60,
+                sourceStart: 0,
+                sourceEnd: 60,
+              },
+            ],
+          },
+        ],
+      },
+    }
+    const native = hostSnapshotToNativeTimeline(original)
+    const edited = nativeTimelineToFrameDocument(
+      {
+        ...native,
+        items: native.items.map((item) =>
+          item.id === 'clip' ? { ...item, from: 5, durationInFrames: 55, sourceStart: 5 } : item,
+        ),
+      },
+      original.timeline,
+    )
+    expect(edited.ok).toBe(true)
+    if (!edited.ok) return
+    const derived = deriveSupportedHostEdit(original.timeline, edited.document)
+    expect(derived.batch?.commands.map((command) => command.type)).toEqual(['trim_item'])
+    const adapter = createCodePressCommandAdapter({
+      document: freeCutDocumentToControlledDocument(original.timeline),
+    })
+    const captionsBeforeTrim = adapter.getDocument().timeline.tracks[0]
+    expect(adapter.apply(derived.batch).status).toBe('applied')
+    expect(adapter.getDocument().timeline.tracks[0]).toEqual(captionsBeforeTrim)
+  })
+})
diff --git a/src/features/editor/host/document.ts b/src/features/editor/host/document.ts
index 6faea0b97..0f4f96a1b 100644
--- a/src/features/editor/host/document.ts
+++ b/src/features/editor/host/document.ts
@@ -251,7 +251,14 @@ export function hostSnapshotToNativeTimeline(snapshot: EmbeddedEditorSnapshot):
   const assets = assetById(snapshot.assets)
   const tracks = snapshot.timeline.tracks.map(nativeTrackFromHostTrack)
   const items = snapshot.timeline.tracks.flatMap((track) =>
-    track.items.map((item) => nativeItemFromHostItem(item, assets)),
+    track.items.map((item) =>
+      nativeItemFromHostItem(
+        item.type === 'caption_cue'
+          ? { ...item, style: { ...track.defaultStyle, ...item.style } }
+          : item,
+        assets,
+      ),
+    ),
   )
   return { tracks, items, fps: snapshot.project.fps }
 }
@@ -381,6 +388,26 @@ function authoritativeTrackMetadata(
  * document.  Shapes, compositions, subtitles, Lottie, effects, and animation
  * edits fail closed so a host action can be visibly rejected and restored.
  */
+function restoreCaptionStyleProvenance(
+  converted: Extract<FreeCutFrameItem, { type: 'caption_cue' }>,
+  authoritative: FreeCutFrameDocument,
+) {
+  const track = authoritative.tracks.find((candidate) => candidate.id === converted.trackId)
+  const original = track?.items.find((candidate) => candidate.id === converted.id)
+  if (original?.type !== 'caption_cue') return
+  const effective = frameItemToNativeComparable(
+    nativeItemFromHostItem(
+      { ...original, style: { ...track?.defaultStyle, ...original.style } },
+      new Map(),
+    ),
+  )
+  if ('reason' in effective || effective.type !== 'caption_cue') return
+  if (JSON.stringify(converted.style) !== JSON.stringify(effective.style)) return
+  // Restore original provenance, including explicit overrides equal to defaults.
+  if (original.style === undefined) delete converted.style
+  else converted.style = original.style
+}
+
 export function nativeTimelineToFrameDocument(
   state: Pick<TimelineState, 'tracks' | 'items' | 'fps'>,
   authoritative: FreeCutFrameDocument,
@@ -399,6 +426,7 @@ export function nativeTimelineToFrameDocument(
     }
     const converted = frameItemToNativeComparable(item)
     if ('reason' in converted) return { ok: false, failure: converted }
+    if (converted.type === 'caption_cue') restoreCaptionStyleProvenance(converted, authoritative)
     const list = itemsByTrack.get(item.trackId) ?? []
     list.push(converted)
     itemsByTrack.set(item.trackId, list)
diff --git a/src/features/editor/host/runtime.ts b/src/features/editor/host/runtime.ts
index 69ac20c1b..5ff9366d8 100644
--- a/src/features/editor/host/runtime.ts
+++ b/src/features/editor/host/runtime.ts
@@ -305,7 +305,7 @@ export class EmbeddedEditorHostRuntime implements EmbeddedEditorHostRuntimeContr
       // applied/conflict state before the user can see it.
       const currentTab = useEditorStore.getState().activeTab
       const currentTabVisibleInHostMode =
-        currentTab === 'media' ||
+        ['media', 'captions'].includes(currentTab) ||
         (currentTab === 'text' &&
           isHostCapabilityEnabled(this.host.capabilities, 'timeline.add')) ||
         (currentTab === 'transcript' &&
diff --git a/tests/browser/caption-refresh.html b/tests/browser/caption-refresh.html
new file mode 100644
index 000000000..8c7a15bd8
--- /dev/null
+++ b/tests/browser/caption-refresh.html
@@ -0,0 +1 @@
+<!doctype html><html><head><meta charset="UTF-8"></head><body><div id="root"></div><script type="module" src="/tests/browser/caption-refresh.tsx"></script></body></html>
diff --git a/tests/browser/caption-refresh.spec.ts b/tests/browser/caption-refresh.spec.ts
new file mode 100644
index 000000000..d45a824b6
--- /dev/null
+++ b/tests/browser/caption-refresh.spec.ts
@@ -0,0 +1,183 @@
+import { execFileSync } from 'node:child_process'
+import { unlinkSync, mkdirSync } from 'node:fs'
+import { expect, test } from 'playwright/test'
+const media = 'tests/browser/.caption-generated.webm'
+test.beforeAll(() => {
+  mkdirSync('artifacts/qa/captions', { recursive: true })
+  execFileSync(
+    'ffmpeg',
+    [
+      '-y',
+      '-f',
+      'lavfi',
+      '-i',
+      'testsrc2=size=640x360:rate=30:duration=3',
+      '-f',
+      'lavfi',
+      '-i',
+      'sine=frequency=440:duration=3',
+      '-c:v',
+      'libvpx-vp9',
+      '-c:a',
+      'libopus',
+      media,
+    ],
+    { stdio: 'ignore' },
+  )
+})
+test.afterAll(() => unlinkSync(media))
+test.setTimeout(120_000)
+test('More discovers captions; edited occurrence timing, style and one apply survive Library navigation', async ({
+  page,
+}) => {
+  await page.goto('/tests/browser/caption-refresh.html')
+  await page.locator('[data-item-id]').first().waitFor()
+  await page.getByRole('combobox', { name: 'More library tools' }).selectOption('captions')
+  await expect(page.getByRole('heading', { name: 'Create captions', exact: true })).toBeVisible()
+  await page.getByRole('textbox', { name: 'Chat draft' }).fill('Keep this draft')
+  await page.getByRole('button', { name: 'Preview captions', exact: true }).click()
+  await expect(page.getByRole('button', { name: 'Apply captions', exact: true })).toBeVisible()
+  expect(await page.evaluate(() => (window as any).captionFixture.applies)).toBe(0)
+  await expect(page.getByText('1.00–2.00s')).toBeVisible()
+  await page.getByRole('button', { name: 'Apply captions', exact: true }).click()
+  await expect(page.getByTestId('caption-editor')).toBeVisible()
+  expect(await page.evaluate(() => (window as any).captionFixture.applies)).toBe(1)
+  const cues = await page.evaluate(
+    () =>
+      (window as any).captionFixture
+        .snapshot()
+        .timeline.tracks.find((track: any) => track.kind === 'caption').items,
+  )
+  expect(cues.map((cue: any) => [cue.text, cue.from, cue.durationInFrames])).toEqual([
+    ['HELLO', 0, 30],
+    ['WORLD', 30, 30],
+    ['HELLO UM WORLD', 60, 90],
+  ])
+  await page.getByRole('button', { name: /Seek to cue 2 at frame 30/ }).click()
+  await page.getByLabel('Color', { exact: true }).fill('#ffff00')
+  await expect(page.getByTestId('caption-preview').getByText('WORLD', { exact: true })).toHaveCSS(
+    'color',
+    'rgb(255, 255, 0)',
+  )
+  await page.getByRole('button', { name: 'Apply style', exact: true }).click()
+  await page.getByRole('button', { name: 'Media', exact: true }).click()
+  await page.getByRole('combobox', { name: 'More library tools' }).selectOption('captions')
+  await expect(page.getByLabel('Color', { exact: true })).toHaveValue('#ffff00')
+  await expect(page.getByRole('textbox', { name: 'Chat draft' })).toHaveValue('Keep this draft')
+  const native = await page.evaluate(() => (window as any).captionFixture.native())
+  expect(native.items.find((item: any) => item.text === 'WORLD').color).toBe('#ffff00')
+  const renderPage = await page.context().newPage()
+  await renderPage.goto('/headless.html')
+  await renderPage.waitForFunction(() => Boolean((window as any).freecut?.ready))
+  const downloadPromise = renderPage.waitForEvent('download', { timeout: 120_000 })
+  const summary = await renderPage.evaluate(
+    (native) =>
+      (window as any).freecut.renderTimeline({
+        ...native,
+        width: 640,
+        height: 360,
+        media: [
+          {
+            mediaId: 'fixture',
+            url: 'http://127.0.0.1:4195/tests/browser/.caption-generated.webm',
+          },
+        ],
+        settings: {
+          mode: 'video',
+          codec: 'vp9',
+          audioCodec: 'opus',
+          container: 'webm',
+          quality: 'high',
+          resolution: { width: 640, height: 360 },
+          fps: 30,
+          audioBitrate: 128000,
+        },
+        outputFileName: 'caption-export.webm',
+      }),
+    native,
+  )
+  await (await downloadPromise).saveAs('artifacts/qa/captions/caption-export.webm')
+  expect(summary).toBeTruthy()
+  for (const [name, time] of [
+    ['hello', '0.5'],
+    ['world', '1.5'],
+    ['repeat', '3.5'],
+  ])
+    execFileSync(
+      'ffmpeg',
+      [
+        '-y',
+        '-ss',
+        time!,
+        '-i',
+        'artifacts/qa/captions/caption-export.webm',
+        '-frames:v',
+        '1',
+        `artifacts/qa/captions/export-${name}.png`,
+      ],
+      { stdio: 'ignore' },
+    )
+  await renderPage.close()
+  for (const width of [1440, 1280]) {
+    await page.setViewportSize({ width, height: 900 })
+    await page.screenshot({ path: `artifacts/qa/captions/library-${width}.png` })
+  }
+  await page.getByRole('checkbox', { name: /Replace all cues/ }).check()
+  await page.getByRole('button', { name: 'Preview captions', exact: true }).click()
+  await page.getByRole('button', { name: 'Apply captions', exact: true }).click()
+  await expect(page.getByTestId('caption-editor')).toBeVisible()
+  expect(
+    await page.evaluate(
+      () =>
+        (window as any).captionFixture
+          .snapshot()
+          .timeline.tracks.find((track: any) => track.kind === 'caption').items.length,
+    ),
+  ).toBe(3)
+})
+
+for (const [scenario, message] of [
+  ['unsupported', 'This host needs support for captions bound to edited clip occurrences.'],
+  ['pending', 'Transcription is still processing.'],
+  ['missing', 'A completed transcript is needed.'],
+  ['error', 'Fixture preview unavailable.'],
+]) {
+  test(`caption recovery: ${scenario}`, async ({ page }) => {
+    await page.goto(`/tests/browser/caption-refresh.html?scenario=${scenario}`)
+    await page.locator('[data-item-id]').first().waitFor()
+    await page.getByRole('combobox', { name: 'More library tools' }).selectOption('captions')
+    const preview = page.getByRole('button', { name: 'Preview captions', exact: true })
+    if (scenario === 'unsupported') await expect(preview).toBeDisabled()
+    else await preview.click()
+    await expect(page.getByText(message, { exact: false })).toBeVisible()
+    expect(await page.evaluate(() => (window as any).captionFixture.applies)).toBe(0)
+  })
+}
+test('selected occurrence captions undo in one transaction', async ({ page }) => {
+  await page.goto('/tests/browser/caption-refresh.html')
+  await page.locator('[data-item-id="after-cut"][role="button"]').click()
+  await page.getByRole('combobox', { name: 'More library tools' }).selectOption('captions')
+  await page.getByLabel('Caption scope').selectOption('selected')
+  await page.getByRole('button', { name: 'Preview captions', exact: true }).click()
+  await page.getByRole('button', { name: 'Apply captions', exact: true }).click()
+  await expect(page.getByTestId('caption-editor')).toBeVisible()
+  const cues = await page.evaluate(
+    () =>
+      (window as any).captionFixture
+        .snapshot()
+        .timeline.tracks.find((track: any) => track.kind === 'caption').items,
+  )
+  expect(cues.map((cue: any) => [cue.text, cue.from, cue.durationInFrames])).toEqual([
+    ['WORLD', 30, 30],
+  ])
+  await page.evaluate(() => (window as any).captionFixture.undo())
+  await expect(page.getByTestId('caption-editor-empty')).toBeVisible()
+  expect(
+    await page.evaluate(
+      () =>
+        (window as any).captionFixture
+          .snapshot()
+          .timeline.tracks.flatMap((track: any) => track.items).length,
+    ),
+  ).toBe(3)
+})
diff --git a/tests/browser/caption-refresh.tsx b/tests/browser/caption-refresh.tsx
new file mode 100644
index 000000000..6f2a3eea4
--- /dev/null
+++ b/tests/browser/caption-refresh.tsx
@@ -0,0 +1,243 @@
+// fallow-ignore-file unused-file
+import { createRoot } from 'react-dom/client'
+import { FreeCutEditorSurface } from '../../src/features/editor/host/editor-surface'
+import {
+  createCodePressCommandAdapter,
+  controlledDocumentToFreeCutDocument,
+  freeCutDocumentToControlledDocument,
+} from '../../src/features/editor/codepress'
+import type { EditorHost, EmbeddedEditorSnapshot } from '../../src/features/editor/host/contract'
+import { hostSnapshotToNativeTimeline } from '../../src/features/editor/host/document'
+
+const scenario = new URLSearchParams(location.search).get('scenario')
+const clip = {
+  id: 'first',
+  type: 'video' as const,
+  trackId: 'video',
+  mediaId: 'fixture',
+  from: 0,
+  durationInFrames: 30,
+  sourceStart: 0,
+  sourceEnd: 30,
+}
+let snapshot: EmbeddedEditorSnapshot = {
+  project: {
+    id: 'caption-fixture',
+    name: 'Caption fixture · edited sequence',
+    width: 640,
+    height: 360,
+    fps: 30,
+  },
+  timeline: {
+    timelineId: 'caption-timeline',
+    revision: 0,
+    fps: 30,
+    width: 640,
+    height: 360,
+    durationInFrames: 150,
+    media: [
+      {
+        media_id: 'fixture',
+        media_kind: 'video',
+        content_hash: 'fixture-hash',
+        duration_us: 3_000_000,
+        availability: { mode: 'cloud', cloud: { object_id: 'fixture' } },
+      },
+    ],
+    tracks: [
+      {
+        id: 'video',
+        kind: 'video',
+        name: 'V1',
+        locked: false,
+        muted: false,
+        items: [
+          clip,
+          { ...clip, id: 'after-cut', from: 30, sourceStart: 60, sourceEnd: 90 },
+          { ...clip, id: 'repeat', from: 60, durationInFrames: 90, sourceEnd: 90 },
+        ],
+      },
+    ],
+  },
+  assets: [
+    {
+      id: 'fixture',
+      kind: 'video',
+      fileName: 'generated-av.webm',
+      mimeType: 'video/webm',
+      durationSeconds: 3,
+      width: 640,
+      height: 360,
+      fps: 30,
+      contentHash: 'fixture-hash',
+    },
+  ],
+}
+let adapter = createCodePressCommandAdapter({
+  document: freeCutDocumentToControlledDocument(snapshot.timeline),
+})
+const listeners = new Set<(value: EmbeddedEditorSnapshot) => void>()
+const history: EmbeddedEditorSnapshot[] = []
+const fixtureState = {
+  applies: 0,
+  undo: () => host.history!.undo(),
+  requests: [] as unknown[],
+  native: () => hostSnapshotToNativeTimeline(snapshot),
+  snapshot: () => snapshot,
+}
+Object.assign(window, { captionFixture: fixtureState })
+const host: EditorHost = {
+  capabilities: { 'media.resolve': true, 'media.transcription': true, 'timeline.caption': true },
+  load: () => snapshot,
+  resolveMedia: () => ({ source: '/tests/browser/.caption-generated.webm' }),
+  subscribe: (listener) => {
+    listeners.add(listener)
+    return () => {
+      listeners.delete(listener)
+    }
+  },
+  history: {
+    undo: () => {
+      const previous = history.pop()
+      if (previous) {
+        snapshot = {
+          ...previous,
+          timeline: { ...previous.timeline, revision: snapshot.timeline.revision + 1 },
+        }
+        adapter = createCodePressCommandAdapter({
+          document: freeCutDocumentToControlledDocument(snapshot.timeline),
+        })
+        listeners.forEach((listener) => listener(snapshot))
+      }
+    },
+    redo: () => {},
+  },
+  submitEdit: (batch) => {
+    const previous = snapshot
+    const result = adapter.apply(batch)
+    if (result.status !== 'rejected') {
+      history.push(previous)
+      fixtureState.applies++
+      snapshot = {
+        ...snapshot,
+        timeline: controlledDocumentToFreeCutDocument(adapter.getDocument()),
+      }
+      listeners.forEach((listener) => listener(snapshot))
+    }
+    return { status: result.status, result, snapshot }
+  },
+  transcript: {
+    occurrenceSelection: scenario !== 'unsupported',
+    getStatus: () => ({
+      transcriptId: 'transcript',
+      assetId: 'fixture',
+      sourceAssetHash: 'fixture-hash',
+      status: scenario === 'pending' ? 'running' : scenario === 'missing' ? 'failed' : 'succeeded',
+      durationUs: 3_000_000,
+      sectionCount: 1,
+    }),
+    getSections: () => ({
+      transcriptId: 'transcript',
+      hasMore: false,
+      sections: [
+        {
+          id: 'section',
+          transcriptId: 'transcript',
+          ordinal: 0,
+          startUs: 0,
+          endUs: 3_000_000,
+          text: 'HELLO UM WORLD',
+          timingSource: 'provider',
+          words: [
+            { text: 'HELLO', startUs: 0, endUs: 1_000_000 },
+            { text: 'UM', startUs: 1_000_000, endUs: 2_000_000 },
+            { text: 'WORLD', startUs: 2_000_000, endUs: 3_000_000 },
+          ],
+        },
+      ],
+    }),
+    previewCommands: (request) => {
+      if (scenario === 'error') throw new Error('Fixture preview unavailable. Retry preview.')
+      fixtureState.requests.push(request)
+      const trackId = request.captionTrackId!
+      const existing = snapshot.timeline.tracks.find((track) => track.id === trackId)
+      const cues = request.ranges!.map((range, index) => {
+        const item = snapshot.timeline.tracks
+          .flatMap((track) => track.items)
+          .find((item) => item.id === range.itemId)!
+        if (item.type !== 'video') throw new Error('Unsupported fixture')
+        return {
+          item_type: 'caption_cue' as const,
+          cue_id: `cue-${index}`,
+          track_id: trackId,
+          start_us: Math.round(
+            (item.from / 30) * 1_000_000 + range.startUs - (item.sourceStart! / 30) * 1_000_000,
+          ),
+          end_us: Math.round(
+            (item.from / 30) * 1_000_000 + range.endUs - (item.sourceStart! / 30) * 1_000_000,
+          ),
+          text: range.text!,
+        }
+      })
+      const commandBatch = {
+        contract_version: 1 as const,
+        timeline_id: snapshot.timeline.timelineId,
+        operation_id: request.operationId,
+        idempotency_key: request.idempotencyKey,
+        base_revision: request.baseRevision,
+        preconditions: [],
+        commands: [
+          ...(existing
+            ? []
+            : [
+                {
+                  type: 'add_caption_track' as const,
+                  command_id: 'track',
+                  track_id: trackId,
+                  name: 'Captions',
+                  language: 'en',
+                  index: 1,
+                },
+              ]),
+          { type: 'upsert_caption_cues' as const, command_id: 'cues', track_id: trackId, cues },
+        ],
+      }
+      return {
+        status: 'preview',
+        receiptId: 'receipt',
+        transcriptId: request.transcriptId,
+        assetId: request.assetId,
+        sourceAssetHash: request.sourceAssetHash,
+        timestampCapability: 'section',
+        timelineId: snapshot.timeline.timelineId,
+        operationId: request.operationId,
+        idempotencyKey: request.idempotencyKey,
+        baseRevision: request.baseRevision,
+        commandBatch,
+        preview: { action: 'captions', captionCount: cues.length, willMutateTimeline: false },
+      }
+    },
+  },
+}
+createRoot(document.getElementById('root')!).render(
+  <div style={{ height: '100vh', display: 'flex' }}>
+    <aside
+      style={{
+        width: 280,
+        flexShrink: 0,
+        padding: 20,
+        background: '#f5f6f8',
+        color: '#20242b',
+        display: 'flex',
+        flexDirection: 'column',
+      }}
+    >
+      <h2>Conversation</h2>
+      <p>Generated fixture. Keep captions in sync with my edit.</p>
+      <textarea aria-label="Chat draft" style={{ marginTop: 'auto' }} />
+    </aside>
+    <main style={{ flex: 1, minWidth: 0 }}>
+      <FreeCutEditorSurface host={host} />
+    </main>
+  </div>,
+)

From f0bf8d3597f8f7e7baca38988b0e270e23cf2eb3 Mon Sep 17 00:00:00 2001
From: Patrick Lu <lightning.lu7@gmail.com>
Date: Tue, 8 Sep 2026 13:49:03 -0700
Subject: [PATCH 09/22] fix(media): preserve anonymous CORS in host package
 sources

---
 .../preview/components/edit-2up-panels.tsx    |  1 +
 .../preview/components/source-composition.tsx | 11 ++++++++--
 .../clip-filmstrip/filmstrip-image-cache.ts   |  1 +
 .../components/item-content.tsx               |  6 ++----
 .../player/video/VideoSourcePool.test.ts      | 21 +++++++++++++++++++
 src/runtime/player/video/VideoSourcePool.ts   |  1 +
 6 files changed, 35 insertions(+), 6 deletions(-)

diff --git a/src/features/preview/components/edit-2up-panels.tsx b/src/features/preview/components/edit-2up-panels.tsx
index 13e6cde3e..37e0abcd4 100644
--- a/src/features/preview/components/edit-2up-panels.tsx
+++ b/src/features/preview/components/edit-2up-panels.tsx
@@ -820,6 +820,7 @@ function ImageFrameImpl({ item }: ImageFrameProps) {
     if (!canvas) return
 
     const img = new Image()
+    img.crossOrigin = 'anonymous'
     img.onload = () => {
       canvas.width = img.naturalWidth || 280
       canvas.height = img.naturalHeight || 158
diff --git a/src/features/preview/components/source-composition.tsx b/src/features/preview/components/source-composition.tsx
index d1328f21d..e822b2154 100644
--- a/src/features/preview/components/source-composition.tsx
+++ b/src/features/preview/components/source-composition.tsx
@@ -917,7 +917,13 @@ function VideoSource({
           display: showDecodedCanvas ? 'block' : 'none',
         }}
       />
-      <audio ref={audioRef} src={src} preload="auto" style={{ display: 'none' }} />
+      <audio
+        crossOrigin="anonymous"
+        ref={audioRef}
+        src={src}
+        preload="auto"
+        style={{ display: 'none' }}
+      />
     </AbsoluteFill>
   )
 }
@@ -926,6 +932,7 @@ function ImageSource({ src }: { src: string }) {
   return (
     <AbsoluteFill>
       <img
+        crossOrigin="anonymous"
         key={src}
         src={src}
         style={{ width: '100%', height: '100%', objectFit: 'contain' }}
@@ -1045,7 +1052,7 @@ function AudioSource({ mediaId, src }: { mediaId?: string; src: string }) {
           onSeekSeconds={handleSeekSeconds}
         />
       </div>
-      <audio ref={audioRef} src={src} preload="auto" />
+      <audio crossOrigin="anonymous" ref={audioRef} src={src} preload="auto" />
     </AbsoluteFill>
   )
 }
diff --git a/src/features/timeline/components/clip-filmstrip/filmstrip-image-cache.ts b/src/features/timeline/components/clip-filmstrip/filmstrip-image-cache.ts
index 318c442e1..876eaface 100644
--- a/src/features/timeline/components/clip-filmstrip/filmstrip-image-cache.ts
+++ b/src/features/timeline/components/clip-filmstrip/filmstrip-image-cache.ts
@@ -32,6 +32,7 @@ function prune(): void {
 
 function createEntry(url: string): CachedFilmstripImage {
   const image = new Image()
+  image.crossOrigin = 'anonymous'
   image.decoding = 'async'
   const entry: CachedFilmstripImage = {
     image,
diff --git a/src/runtime/composition-runtime/components/item-content.tsx b/src/runtime/composition-runtime/components/item-content.tsx
index 8c8e1e6ab..97e31c70e 100644
--- a/src/runtime/composition-runtime/components/item-content.tsx
+++ b/src/runtime/composition-runtime/components/item-content.tsx
@@ -1,8 +1,5 @@
 import React from 'react'
-import {
-  AbsoluteFill,
-  useClockPlaybackRate,
-} from '@/runtime/composition-runtime/deps/player'
+import { AbsoluteFill, useClockPlaybackRate } from '@/runtime/composition-runtime/deps/player'
 import { useDebugStore, useGizmoStore } from '@/runtime/composition-runtime/deps/stores'
 import type { AudioItem, CompositionItem, TimelineItem, ShapeItem } from '@/types/timeline'
 import type { ResolvedAudioEqSettings } from '@/types/audio'
@@ -541,6 +538,7 @@ export const ItemContent = React.memo<ItemProps>(
       // Regular static images - use native img element
       const imageContent = (
         <img
+          crossOrigin="anonymous"
           src={item.src}
           alt=""
           style={{
diff --git a/src/runtime/player/video/VideoSourcePool.test.ts b/src/runtime/player/video/VideoSourcePool.test.ts
index 56507e5d1..889c5f9b3 100644
--- a/src/runtime/player/video/VideoSourcePool.test.ts
+++ b/src/runtime/player/video/VideoSourcePool.test.ts
@@ -118,6 +118,27 @@ describe('VideoSourcePool', () => {
     expect(videoMocks.createdVideos[1]!.play).toHaveBeenCalledTimes(1)
   })
 
+  it('sets anonymous CORS before starting a remote media request', () => {
+    const descriptor = Object.getOwnPropertyDescriptor(HTMLMediaElement.prototype, 'src')!
+    const requestModes: Array<string | null> = []
+    const setter = vi.spyOn(HTMLMediaElement.prototype, 'src', 'set').mockImplementation(function (
+      this: HTMLMediaElement,
+      value: string,
+    ) {
+      requestModes.push(this.crossOrigin)
+      descriptor.set!.call(this, value)
+    })
+    const pool = new VideoSourcePool()
+    try {
+      expect(pool.acquireForClip('remote-clip', 'https://cdn.example.com/video.mp4')).not.toBeNull()
+      expect(requestModes.length).toBeGreaterThan(0)
+      expect(requestModes.every((mode) => mode === 'anonymous')).toBe(true)
+    } finally {
+      setter.mockRestore()
+      pool.dispose()
+    }
+  })
+
   it('reuses a clip assignment during sticky release windows', async () => {
     vi.useFakeTimers()
     const pool = new VideoSourcePool()
diff --git a/src/runtime/player/video/VideoSourcePool.ts b/src/runtime/player/video/VideoSourcePool.ts
index 3a72aeab0..30be05208 100644
--- a/src/runtime/player/video/VideoSourcePool.ts
+++ b/src/runtime/player/video/VideoSourcePool.ts
@@ -445,6 +445,7 @@ class SourceController {
 
   private createElementSync(): HTMLVideoElement {
     const element = document.createElement('video')
+    element.crossOrigin = 'anonymous'
     element.src = this.sourceUrl
     element.preload = 'auto'
     element.playsInline = true

From 4edf7a24a7d83c73ad961d34a160e3cca3a760ae Mon Sep 17 00:00:00 2001
From: Patrick Lu <lightning.lu7@gmail.com>
Date: Tue, 8 Sep 2026 14:00:48 -0700
Subject: [PATCH 10/22] test(editor): align shell expectations and package
 provenance

---
 provenance/dependency-inventory.json          |  2 +-
 provenance/freecut-baseline.json              | 13 +++-
 .../editor/components/editor.test.tsx         | 60 +++++++++----------
 3 files changed, 38 insertions(+), 37 deletions(-)

diff --git a/provenance/dependency-inventory.json b/provenance/dependency-inventory.json
index c08f6d559..ada5bc796 100644
--- a/provenance/dependency-inventory.json
+++ b/provenance/dependency-inventory.json
@@ -3,7 +3,7 @@
   "generatedFrom": "package.json",
   "packageName": "freecut",
   "packageVersion": "0.0.0",
-  "packageJsonSha256": "7786ffe5cde5b09b6f88fc4fd13af399365ac0d6dc32f320d6f719c6f62edc89",
+  "packageJsonSha256": "6047ae253aacc102cf79a9b30f7f45250974e0c312f5106fe8056cb7a37a7538",
   "lockfile": {
     "path": "package-lock.json",
     "lockfileVersion": 3,
diff --git a/provenance/freecut-baseline.json b/provenance/freecut-baseline.json
index 3ee69326d..1c81b34ff 100644
--- a/provenance/freecut-baseline.json
+++ b/provenance/freecut-baseline.json
@@ -1,7 +1,7 @@
 {
   "schema": "freecut-pr2-provenance-baseline/v1",
   "issue": "https://github.com/quantfive/codepress/issues/5319",
-  "scope": "PR 2 — FreeCut fork provenance and reproducible package baseline",
+  "scope": "PR 2 \u2014 FreeCut fork provenance and reproducible package baseline",
   "upstream": {
     "repository": "https://github.com/walterlow/freecut",
     "fork": "https://github.com/quantfive/freecut",
@@ -34,7 +34,7 @@
   ],
   "dependencies": {
     "packageJson": "package.json",
-    "packageJsonSha256": "7786ffe5cde5b09b6f88fc4fd13af399365ac0d6dc32f320d6f719c6f62edc89",
+    "packageJsonSha256": "6047ae253aacc102cf79a9b30f7f45250974e0c312f5106fe8056cb7a37a7538",
     "lockfile": "package-lock.json",
     "lockfileVersion": 3,
     "lockfileSha256": "b4a86741ce7891da1f63df01b6fdd4ed507e8887d5097c6a0f93fc2ea6f3420e",
@@ -79,7 +79,14 @@
     "packageCommand": "npm run package:reproducible",
     "artifactPattern": "artifacts/freecut-<source-revision>.tar.gz",
     "archiveFormat": "deterministic tar.gz with sorted paths, zeroed mtimes, and uid/gid 0",
-    "contents": ["dist/", "LICENSE", "notices/", "package.json", "package-lock.json", "provenance/"]
+    "contents": [
+      "dist/",
+      "LICENSE",
+      "notices/",
+      "package.json",
+      "package-lock.json",
+      "provenance/"
+    ]
   },
   "ciVerification": {
     "workflow": ".github/workflows/reproducible-package.yml",
diff --git a/src/features/editor/components/editor.test.tsx b/src/features/editor/components/editor.test.tsx
index b3c35a122..18e048ec0 100644
--- a/src/features/editor/components/editor.test.tsx
+++ b/src/features/editor/components/editor.test.tsx
@@ -438,7 +438,7 @@ describe('LoadedEditor migration metadata refresh', () => {
 
     expect(mocks.resizablePanelGroup).toHaveBeenCalledWith(
       expect.objectContaining({
-        autoSaveId: 'editor:timeline-layout',
+        autoSaveId: 'editor:timeline-layout-refresh',
         direction: 'vertical',
       }),
     )
@@ -497,6 +497,8 @@ describe('LoadedEditor migration metadata refresh', () => {
     expect(screen.getByTestId('motion-preview-area')).toBeInTheDocument()
     expect(screen.queryByTestId('timeline')).not.toBeInTheDocument()
     expect(screen.getByTestId('media-sidebar')).toBeInTheDocument()
+    expect(screen.queryByTestId('properties-sidebar')).not.toBeInTheDocument()
+    fireEvent.click(screen.getByRole('button', { name: 'Canvas settings' }))
     expect(screen.getByTestId('properties-sidebar')).toBeInTheDocument()
   })
 })
@@ -589,7 +591,7 @@ describe('editor responsive shell', () => {
 
   afterEach(() => cleanup())
 
-  it('starts 390px standalone with core surfaces visible and persisted desktop panels untouched', async () => {
+  it('keeps independent columns at 390px without changing persisted desktop panels', async () => {
     mocks.editorWidth = 390
 
     render(<LoadedEditor projectId="project-1" project={project} migration={migration} />)
@@ -597,8 +599,8 @@ describe('editor responsive shell', () => {
     const shell = screen.getByRole('application')
     await waitFor(() => expect(shell).toHaveAttribute('data-editor-layout', 'mobile'))
     expect(screen.getByTestId('toolbar')).toHaveAttribute('data-compact', 'true')
-    expect(await screen.findByTestId('timeline')).toHaveAttribute('data-compact', 'true')
-    expect(screen.queryByTestId('media-sidebar')).not.toBeInTheDocument()
+    expect(await screen.findByTestId('timeline')).toHaveAttribute('data-compact', 'false')
+    expect(screen.getByTestId('media-sidebar')).toBeVisible()
     expect(screen.queryByTestId('properties-sidebar')).not.toBeInTheDocument()
     expect(screen.queryByTestId('audio-meter-panel')).not.toBeInTheDocument()
     expect(mocks.setLeftSidebarOpen).not.toHaveBeenCalled()
@@ -606,33 +608,25 @@ describe('editor responsive shell', () => {
     expect(mocks.syncSidebarLayout).not.toHaveBeenCalled()
   })
 
-  it('opens each 390px panel as a focus-restoring drawer and closes it with Escape', async () => {
+  it('offers explicit column collapse and focus-restoring settings at 390px', async () => {
     mocks.editorWidth = 390
     render(<LoadedEditor projectId="project-1" project={project} migration={migration} />)
-    await waitFor(() =>
-      expect(screen.getByRole('application')).toHaveAttribute('data-editor-layout', 'mobile'),
-    )
-
-    for (const name of ['Media', 'Properties', 'Meters']) {
-      const trigger = screen.getByRole('button', { name })
-      trigger.focus()
-      fireEvent.click(trigger)
-
-      const drawer = await screen.findByRole('dialog', { name })
-      expect(drawer).toBeInTheDocument()
-      expect(drawer).toContainElement(document.activeElement as HTMLElement)
-      const expectedTestId =
-        name === 'Media'
-          ? 'media-sidebar'
-          : name === 'Properties'
-            ? 'properties-sidebar'
-            : 'audio-meter-panel'
-      expect(screen.getByTestId(expectedTestId)).toHaveAttribute('data-mobile-drawer', 'true')
-
-      fireEvent.keyDown(document, { key: 'Escape' })
-      await waitFor(() => expect(screen.queryByRole('dialog', { name })).not.toBeInTheDocument())
-      await waitFor(() => expect(trigger).toHaveFocus())
-    }
+    await screen.findByTestId('timeline')
+    fireEvent.click(screen.getByRole('button', { name: 'Hide Library' }))
+    expect(screen.getByTestId('media-sidebar')).not.toBeVisible()
+    fireEvent.click(screen.getByRole('button', { name: 'Show Library' }))
+    expect(screen.getByTestId('media-sidebar')).toBeVisible()
+    fireEvent.click(screen.getByRole('button', { name: 'Hide Editor' }))
+    expect(screen.getByTestId('timeline')).not.toBeVisible()
+    fireEvent.click(screen.getByRole('button', { name: 'Show Editor' }))
+    expect(screen.getByTestId('timeline')).toBeVisible()
+    const trigger = screen.getByRole('button', { name: 'Canvas settings' })
+    fireEvent.click(trigger)
+    const settings = screen.getByRole('region', { name: 'Settings' })
+    expect(screen.getByTestId('properties-sidebar')).toBeVisible()
+    fireEvent.keyDown(settings, { key: 'Escape' })
+    expect(screen.queryByRole('region', { name: 'Settings' })).not.toBeInTheDocument()
+    expect(trigger).toHaveFocus()
   })
 
   it('uses the same 390px layout inside a definite-height host surface', async () => {
@@ -654,11 +648,11 @@ describe('editor responsive shell', () => {
       expect(screen.getByRole('application')).toHaveAttribute('data-editor-layout', 'mobile'),
     )
     expect(screen.getByTestId('toolbar')).toHaveAttribute('data-compact', 'true')
-    expect(await screen.findByTestId('timeline')).toHaveAttribute('data-compact', 'true')
+    expect(await screen.findByTestId('timeline')).toHaveAttribute('data-compact', 'false')
     expect(hostRuntime.mountStores).toHaveBeenCalledTimes(1)
   })
 
-  it('preserves the existing 320/288/84 desktop layout branch at 1440px', async () => {
+  it('shows the desktop editor with library and on-demand settings and meters at 1440px', async () => {
     render(<LoadedEditor projectId="project-1" project={project} migration={migration} />)
 
     const shell = screen.getByRole('application')
@@ -666,7 +660,7 @@ describe('editor responsive shell', () => {
     expect(screen.getByTestId('toolbar')).toHaveAttribute('data-compact', 'false')
     expect(await screen.findByTestId('timeline')).toHaveAttribute('data-compact', 'false')
     expect(screen.getByTestId('media-sidebar')).toHaveAttribute('data-mobile-drawer', 'false')
-    expect(screen.getByTestId('properties-sidebar')).toHaveAttribute('data-mobile-drawer', 'false')
-    expect(screen.getByTestId('audio-meter-panel')).toHaveAttribute('data-mobile-drawer', 'false')
+    expect(screen.queryByTestId('properties-sidebar')).not.toBeInTheDocument()
+    expect(screen.queryByTestId('audio-meter-panel')).not.toBeInTheDocument()
   })
 })

From 61fc6cc03b3091b55aa1a71b0f45f194cf49302b Mon Sep 17 00:00:00 2001
From: Patrick Lu <lightning.lu7@gmail.com>
Date: Tue, 8 Sep 2026 14:05:44 -0700
Subject: [PATCH 11/22] fix(package): emit host worker URLs without bundler
 wrappers

---
 scripts/editor-package-worker-urls.mjs      | 37 +++++++++++++++++++++
 scripts/editor-package-worker-urls.test.mjs | 26 +++++++++++++++
 vite.editor-package.config.ts               | 12 +++++--
 3 files changed, 73 insertions(+), 2 deletions(-)
 create mode 100644 scripts/editor-package-worker-urls.mjs
 create mode 100644 scripts/editor-package-worker-urls.test.mjs

diff --git a/scripts/editor-package-worker-urls.mjs b/scripts/editor-package-worker-urls.mjs
new file mode 100644
index 000000000..eedfb535b
--- /dev/null
+++ b/scripts/editor-package-worker-urls.mjs
@@ -0,0 +1,37 @@
+import { parseSync, Visitor } from 'vite-plus'
+
+function isImportMetaUrl(node) {
+  return node?.type === 'MemberExpression' && !node.computed &&
+    node.object.type === 'MetaProperty' && node.object.meta.name === 'import' &&
+    node.object.property.name === 'meta' && node.property.type === 'Identifier' &&
+    node.property.name === 'url'
+}
+
+function isGeneratedWorkerBase(node) {
+  return isImportMetaUrl(node) || (node?.type === 'BinaryExpression' && node.operator === '+' &&
+    node.left.type === 'Literal' && node.left.value === '' && isImportMetaUrl(node.right))
+}
+
+/** Embedded hosts stage workers at their public root; keep them runtime URLs for Turbopack. */
+export function normalizeEditorWorkerUrls(code, filename = 'editor-chunk.js') {
+  if (!code.includes('/assets/')) return code
+  const parsed = parseSync(filename, code)
+  if (parsed.errors.length) throw new Error(`Cannot inspect editor worker URLs in ${filename}`)
+  const replacements = []
+  new Visitor({
+    NewExpression(node) {
+      if (node.callee.type !== 'Identifier' || !['Worker', 'SharedWorker'].includes(node.callee.name)) return
+      const url = node.arguments[0]
+      if (url?.type !== 'NewExpression' || url.callee.type !== 'Identifier' ||
+        url.callee.name !== 'URL' || url.arguments.length !== 2) return
+      const [asset, base] = url.arguments
+      if (asset.type !== 'Literal' || typeof asset.value !== 'string' ||
+        !/^\/assets\/[A-Za-z0-9][A-Za-z0-9._-]*\.js$/.test(asset.value) || !isGeneratedWorkerBase(base)) return
+      replacements.push({ start: url.start, end: url.end, text: JSON.stringify(asset.value) })
+    },
+  }).visit(parsed.program)
+  return replacements.sort((left, right) => right.start - left.start).reduce(
+    (result, replacement) => result.slice(0, replacement.start) + replacement.text + result.slice(replacement.end),
+    code,
+  )
+}
diff --git a/scripts/editor-package-worker-urls.test.mjs b/scripts/editor-package-worker-urls.test.mjs
new file mode 100644
index 000000000..bc111bf4f
--- /dev/null
+++ b/scripts/editor-package-worker-urls.test.mjs
@@ -0,0 +1,26 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { normalizeEditorWorkerUrls } from './editor-package-worker-urls.mjs'
+
+test('unwraps generated worker URLs while retaining worker options and content', () => {
+  const source = `new Worker(new URL(/* @vite-ignore */ "/assets/decoder-abc.js", "" + import.meta.url), {type:"module"});
+new SharedWorker(new URL('/assets/waveform-def.js', import.meta.url), {name:'audio'});`
+  assert.equal(normalizeEditorWorkerUrls(source), `new Worker("/assets/decoder-abc.js", {type:"module"});
+new SharedWorker("/assets/waveform-def.js", {name:'audio'});`)
+})
+
+test('leaves relative, external, computed, non-worker URLs and documentation unchanged', () => {
+  const source = `new Worker(new URL('./relative.js', import.meta.url));
+new Worker(new URL('https://cdn.example.com/assets/worker.js', import.meta.url));
+new Worker(new URL('/assets/worker.js', otherBase));
+new Worker(new URL(assetPath, import.meta.url));
+new URL('/assets/worker.js', import.meta.url).href;
+const documentation = 'new Worker(new URL("/assets/worker.js", import.meta.url))';`
+  assert.equal(normalizeEditorWorkerUrls(source), source)
+})
+
+test('is idempotent and rejects malformed chunks instead of silently changing code', () => {
+  const normalized = 'new Worker("/assets/worker.js", {type:"module"})'
+  assert.equal(normalizeEditorWorkerUrls(normalized), normalized)
+  assert.throws(() => normalizeEditorWorkerUrls('new Worker( /* /assets/ */'), /Cannot inspect/)
+})
diff --git a/vite.editor-package.config.ts b/vite.editor-package.config.ts
index 1c5da402b..953f6a381 100644
--- a/vite.editor-package.config.ts
+++ b/vite.editor-package.config.ts
@@ -1,4 +1,5 @@
-import { defineConfig, lazyPlugins } from 'vite-plus'
+import { defineConfig, lazyPlugins, type Plugin } from 'vite-plus'
+import { normalizeEditorWorkerUrls } from './scripts/editor-package-worker-urls.mjs'
 import react from '@vitejs/plugin-react'
 import tailwindcss from '@tailwindcss/vite'
 import {
@@ -50,9 +51,16 @@ function removeHostDisabledWorkers() {
   }
 }
 
-function normalizeEditorPackageAssets() {
+function normalizeEditorPackageAssets(): Plugin {
   return {
     name: 'freecut-editor-package-assets',
+    renderChunk: {
+      order: 'post',
+      handler(code, chunk) {
+        const normalized = normalizeEditorWorkerUrls(code, chunk.fileName)
+        return normalized === code ? null : { code: normalized, map: null }
+      },
+    },
     buildStart() {
       rmSync(outDir, { recursive: true, force: true })
     },

From 04e857e49205438fd964b4a8142be7d0d0ffab96 Mon Sep 17 00:00:00 2001
From: Patrick Lu <lightning.lu7@gmail.com>
Date: Tue, 8 Sep 2026 14:09:37 -0700
Subject: [PATCH 12/22] fix(host): preserve property and duration patch
 compatibility

---
 packages/freecut-editor/src/index.d.ts        |   1 +
 src/features/editor/codepress/adapter.test.ts | 144 ++++++++++++
 src/features/editor/codepress/edit-engine.ts  |  15 ++
 src/features/editor/host/contract.ts          |   3 +
 src/features/editor/host/controller.test.ts   | 209 +++++++++++++++++-
 src/features/editor/host/controller.ts        |  39 ++++
 src/features/editor/host/document.ts          |  18 +-
 7 files changed, 418 insertions(+), 11 deletions(-)

diff --git a/packages/freecut-editor/src/index.d.ts b/packages/freecut-editor/src/index.d.ts
index 4c2cd2551..49f9aa1db 100644
--- a/packages/freecut-editor/src/index.d.ts
+++ b/packages/freecut-editor/src/index.d.ts
@@ -550,6 +550,7 @@ export declare const SUPPORTED_HOST_COMMANDS: readonly [
   'add_text',
   'move_item',
   'set_item_attachment',
+  'set_item_properties',
   'trim_item',
   'split_item',
   'remove_item',
diff --git a/src/features/editor/codepress/adapter.test.ts b/src/features/editor/codepress/adapter.test.ts
index d38ae6d14..5983cc1e3 100644
--- a/src/features/editor/codepress/adapter.test.ts
+++ b/src/features/editor/codepress/adapter.test.ts
@@ -1217,3 +1217,147 @@ describe('controlled command adapter', () => {
 function itemIdForTest(item: TimelineState['tracks'][number]['items'][number]): string {
   return item.item_type === 'caption_cue' ? item.cue_id : item.item_id
 }
+
+describe('adopted move and trim duration extension', () => {
+  it.each(['move', 'attached move', 'trim'] as const)(
+    'expands duration after %s before validating the resulting timeline',
+    (mode) => {
+      const initial = timeline({ duration_us: mode === 'attached move' ? 2_000_000 : 1_000_000 })
+      if (mode === 'attached move')
+        initial.tracks[0]!.items = [
+          ...initial.tracks[0]!.items,
+          clip({ item_id: 'tail', timeline_start_us: 1_000_000, timeline_end_us: 2_000_000 }),
+        ]
+      const adapter = createCodePressCommandAdapter({ document: documentFor(initial) })
+      const commands: EditCommandBatch['commands'] =
+        mode === 'trim'
+          ? [
+              {
+                command_id: 'trim',
+                type: 'trim_item',
+                item_id: 'clip-a',
+                edge: 'end',
+                timeline_us: 3_000_000,
+                source_us: 3_000_000,
+              },
+            ]
+          : [
+              {
+                command_id: 'move',
+                type: 'move_item',
+                item_id: 'clip-a',
+                to_track_id: 'track-video',
+                timeline_start_us: 2_000_000,
+                index: 0,
+                ...(mode === 'attached move' ? { ripple: true } : {}),
+              },
+            ]
+      applyRequest(adapter, {
+        contract_version: 1,
+        timeline_id: initial.timeline_id,
+        operation_id: 'extend',
+        idempotency_key: 'extend',
+        base_revision: 0,
+        preconditions: [],
+        commands,
+      })
+      expect(adapter.getDocument().timeline.duration_us).toBe(
+        mode === 'attached move' ? 4_000_000 : 3_000_000,
+      )
+      if (mode === 'attached move')
+        expect(adapter.getDocument().timeline.tracks[0]!.items[1]).toMatchObject({
+          timeline_start_us: 3_000_000,
+          timeline_end_us: 4_000_000,
+        })
+    },
+  )
+})
+
+describe('known source bounds when extending trim duration', () => {
+  it.each([30, 29.97])('uses source microseconds at %s fps including double-speed clips', (fps) => {
+    const frame = (value: number) => framesToMicroseconds(value, fps)
+    const initial = timeline({
+      duration_us: frame(30),
+      media: [{ ...videoMedia, duration_us: frame(180) }],
+    })
+    initial.tracks[0]!.items = [
+      clip({ timeline_end_us: frame(30), source_end_us: frame(60), speed: 2 }),
+    ]
+    const adapter = createCodePressCommandAdapter({ document: documentFor(initial, fps) })
+    const request = (endFrame: number, revision: number): EditCommandBatch => ({
+      contract_version: 1,
+      timeline_id: initial.timeline_id,
+      operation_id: `trim-${endFrame}`,
+      idempotency_key: `trim-${endFrame}`,
+      base_revision: revision,
+      preconditions: [],
+      commands: [
+        {
+          command_id: 'trim',
+          type: 'trim_item',
+          item_id: 'clip-a',
+          edge: 'end',
+          timeline_us: frame(endFrame),
+          source_us: frame(endFrame * 2),
+        },
+      ],
+    })
+    applyRequest(adapter, request(60, 0))
+    expect(adapter.getDocument().timeline.duration_us).toBe(frame(60))
+    applyRequest(adapter, request(90, 1))
+    expect(adapter.getDocument().timeline.duration_us).toBe(frame(90))
+    const before = structuredClone(adapter.getSnapshot())
+    const invalid = request(91, 2)
+    // A preceding valid property command must also roll back with the trim.
+    invalid.commands = [
+      {
+        command_id: 'opacity',
+        type: 'set_item_properties',
+        item_id: 'clip-a',
+        properties: { opacity: 0.5 },
+      },
+      ...invalid.commands,
+    ]
+    expect(adapter.apply(invalid)).toMatchObject({
+      status: 'rejected',
+      error: {
+        code: 'invalid_request',
+        message: expect.stringContaining('exceeds known media duration'),
+      },
+    })
+    expect(adapter.getSnapshot()).toEqual(before)
+    // Rejection does not advance authority or poison the successful request receipt.
+    expect(adapter.apply(request(90, 1))).toMatchObject({
+      status: 'replayed',
+      resulting_revision: 2,
+    })
+    expect(adapter.getSnapshot()).toEqual(before)
+  })
+
+  it('does not invent a source bound when media duration is unknown', () => {
+    const initial = timeline({
+      duration_us: 1_000_000,
+      media: [{ ...videoMedia, duration_us: null }],
+    })
+    const adapter = createCodePressCommandAdapter({ document: documentFor(initial) })
+    applyRequest(adapter, {
+      contract_version: 1,
+      timeline_id: initial.timeline_id,
+      operation_id: 'unknown',
+      idempotency_key: 'unknown',
+      base_revision: 0,
+      preconditions: [],
+      commands: [
+        {
+          command_id: 'trim',
+          type: 'trim_item',
+          item_id: 'clip-a',
+          edge: 'end',
+          timeline_us: 40_000_000,
+          source_us: 40_000_000,
+        },
+      ],
+    })
+    expect(adapter.getDocument().timeline.duration_us).toBe(40_000_000)
+  })
+})
diff --git a/src/features/editor/codepress/edit-engine.ts b/src/features/editor/codepress/edit-engine.ts
index 0c6a3b9d1..caeacbb75 100644
--- a/src/features/editor/codepress/edit-engine.ts
+++ b/src/features/editor/codepress/edit-engine.ts
@@ -440,6 +440,7 @@ function applyMoveItem(
         setItemFramePosition(member.item, range.start + deltaFrames, range.end + deltaFrames, fps),
       )
     }
+    recomputeDuration(timeline)
     return {
       ...moved,
       moved_item_ids: chainIds,
@@ -457,6 +458,7 @@ function applyMoveItem(
   replaceTrackItems(timeline, located.trackIndex, sourceItems)
   const targetItems = targetIndex === located.trackIndex ? sourceItems : target.items
   replaceTrackItems(timeline, targetIndex, insertAt(targetItems, moved, command.index))
+  recomputeDuration(timeline)
   return {
     ...emptyEffect(),
     moved_item_ids: [command.item_id],
@@ -513,7 +515,20 @@ function applyTrim(
       `Trim would make item "${command.item_id}" empty`,
       command.command_id,
     )
+  if (next.item_type === 'clip') {
+    const mediaDuration = timeline.media.find(
+      (media) => media.media_id === next.media_id,
+    )?.duration_us
+    if (mediaDuration != null && next.source_end_us > mediaDuration) {
+      throw new EditEngineError(
+        'invalid_request',
+        `Trim source end exceeds known media duration for item "${command.item_id}"`,
+        command.command_id,
+      )
+    }
+  }
   setItemAt(timeline, located, next)
+  recomputeDuration(timeline)
   return { ...emptyEffect(), updated_item_ids: [command.item_id] }
 }
 
diff --git a/src/features/editor/host/contract.ts b/src/features/editor/host/contract.ts
index 7ce8f8783..c194c6fc0 100644
--- a/src/features/editor/host/contract.ts
+++ b/src/features/editor/host/contract.ts
@@ -411,6 +411,7 @@ export const SUPPORTED_HOST_COMMANDS = [
   'add_text',
   'move_item',
   'set_item_attachment',
+  'set_item_properties',
   'trim_item',
   'split_item',
   'remove_item',
@@ -432,6 +433,8 @@ export function capabilityForCommand(command: EditCommand['type']): EditorCapabi
       return 'timeline.add'
     case 'move_item':
       return 'timeline.move'
+    case 'set_item_properties':
+      return 'workspace.edit'
     case 'set_item_attachment':
       return 'timeline.attachment'
     case 'trim_item':
diff --git a/src/features/editor/host/controller.test.ts b/src/features/editor/host/controller.test.ts
index aa0bd9be7..8c7824a4e 100644
--- a/src/features/editor/host/controller.test.ts
+++ b/src/features/editor/host/controller.test.ts
@@ -757,6 +757,7 @@ describe('embedded FreeCut host controller', () => {
       'add_text',
       'move_item',
       'set_item_attachment',
+      'set_item_properties',
       'trim_item',
       'split_item',
       'remove_item',
@@ -1707,7 +1708,7 @@ describe('embedded FreeCut host controller', () => {
       }
     })
 
-    it('still names a real resize once identity transforms compare equal', () => {
+    it('serializes a real resize once identity transforms compare equal', () => {
       const base = minimalTwoClipSnapshot()
       const sized = withClipTwo(base.timeline, {
         transform: {
@@ -1736,13 +1737,14 @@ describe('embedded FreeCut host controller', () => {
 
       const derived = deriveSupportedHostEdit(sized, resized)
 
-      // The normalized transform has to carry the size, or a gizmo resize is
-      // indistinguishable from an untouched clip and is silently swallowed.
-      expect(derived.batch).toBeNull()
-      // `timelinePosition` rides along on every rejection of a clip that did
-      // not also move; `transform` is the predicate this pins.
-      expect(derived.detail?.failedPredicates).toEqual(['transform', 'timelinePosition'])
-      expect(derived.detail?.changedFields).toEqual(['transform.height', 'transform.width'])
+      expect(derived.batch?.commands).toEqual([
+        {
+          command_id: 'properties-clip-2',
+          type: 'set_item_properties',
+          item_id: 'clip-2',
+          properties: { transform: expect.objectContaining({ width: 1280, height: 720 }) },
+        },
+      ])
     })
   })
 })
@@ -1997,7 +1999,15 @@ it('rejects exhausted source handles before any host mutation', async () => {
     mode: 'normal',
     itemIds: ['clip-1'],
   })
-  await expect(controller.submitEdit(batch)).resolves.toMatchObject({ status: 'rejected' })
+  await expect(controller.submitEdit(batch)).resolves.toMatchObject({
+    status: 'rejected',
+    result: {
+      error: {
+        code: 'invalid_request',
+        message: expect.stringContaining('exceeds known media duration'),
+      },
+    },
+  })
   expect(harness.submitEdit).not.toHaveBeenCalled()
   expect(controller.getSnapshot()).toEqual(initial)
 })
@@ -2028,3 +2038,184 @@ it('does not restore a superseded timeline identity from a late receipt', async
   await pending
   expect(controller.getSnapshot().timeline.timelineId).toBe('replacement')
 })
+
+describe('adopted host property compatibility', () => {
+  it('submits native placement and opacity, applies authority, and restores an authoritative undo snapshot', async () => {
+    const initial = snapshot()
+    const native = hostSnapshotToNativeTimeline(initial)
+    native.items[0]!.transform = {
+      x: 24,
+      y: 12,
+      width: 640,
+      height: 360,
+      anchorX: 320,
+      anchorY: 180,
+      rotation: 15,
+      opacity: 0.4,
+    }
+    const converted = nativeTimelineToFrameDocument(native, initial.timeline)
+    if (!converted.ok) throw new Error(converted.failure.reason)
+    const derived = deriveSupportedHostEdit(initial.timeline, converted.document)
+    expect(capabilityForCommand('set_item_properties')).toBe('workspace.edit')
+    expect(derived.batch?.commands).toMatchObject([
+      {
+        type: 'set_item_properties',
+        properties: { opacity: 0.4, transform: native.items[0]!.transform },
+      },
+    ])
+    expect(derived.batch?.preconditions).toHaveLength(1)
+    const applied = { ...initial, timeline: { ...converted.document, revision: 1 } }
+    const submitEdit = vi.fn(
+      async (): Promise<HostEditResult> => ({
+        status: 'applied',
+        snapshot: applied,
+        result: { status: 'applied' } as HostAppliedEditResult['result'],
+      }),
+    )
+    const host: EditorHost = { ...createFakeHost(initial).host, submitEdit }
+    const controller = new HostEditorController(host, initial)
+    host.history = {
+      undo: () =>
+        controller.replaceAuthoritativeSnapshot({
+          ...initial,
+          timeline: { ...initial.timeline, revision: 2 },
+        }),
+      redo: () => undefined,
+    }
+    await expect(controller.submitEdit(derived.batch!)).resolves.toMatchObject({
+      status: 'applied',
+    })
+    expect(submitEdit).toHaveBeenCalledWith(derived.batch)
+    expect(controller.getSnapshot()).toEqual(applied)
+    await host.history.undo()
+    expect(controller.getSnapshot().timeline.tracks).toEqual(initial.timeline.tracks)
+    expect(controller.getSnapshot().timeline.revision).toBe(2)
+    expect(submitEdit).toHaveBeenCalledTimes(1)
+  })
+
+  it('gates property edits and does not broaden volume or combined move/property support', async () => {
+    const initial = snapshot()
+    const edited = structuredClone(initial)
+    Object.assign(edited.timeline.tracks[0]!.items[0]!, { opacity: 0.5 })
+    const batch = deriveSupportedHostEdit(initial.timeline, edited.timeline).batch!
+    expect(batch.commands).toMatchObject([
+      { type: 'set_item_properties', properties: { opacity: 0.5 } },
+    ])
+    const harness = createFakeHost(initial, {
+      ...DEFAULT_HOST_CAPABILITIES,
+      'workspace.edit': false,
+    })
+    await expect(
+      new HostEditorController(harness.host, initial).submitEdit(batch),
+    ).resolves.toMatchObject({ status: 'unsupported' })
+    expect(harness.submitEdit).not.toHaveBeenCalled()
+    Object.assign(edited.timeline.tracks[0]!.items[0]!, { from: 10 })
+    expect(deriveSupportedHostEdit(initial.timeline, edited.timeline).batch).toBeNull()
+    Object.assign(edited.timeline.tracks[0]!.items[0]!, { from: 0, volume: 0.5 })
+    expect(deriveSupportedHostEdit(initial.timeline, edited.timeline).batch).toBeNull()
+  })
+
+  it.each(['video', 'text'] as const)(
+    'preserves top-level opacity alongside a %s transform without deriving a phantom edit',
+    (type) => {
+      const initial = snapshot()
+      const base = initial.timeline.tracks[0]!.items[0]!
+      initial.timeline.tracks[0]!.items = [
+        {
+          ...base,
+          type,
+          ...(type === 'text' ? { text: 'Title' } : {}),
+          opacity: 0.35,
+          transform: {
+            x: 20,
+            y: 10,
+            width: 640,
+            height: 360,
+            anchorX: 320,
+            anchorY: 180,
+            rotation: 5,
+            opacity: 1,
+          },
+        } as typeof base,
+      ]
+      const native = hostSnapshotToNativeTimeline(initial)
+      expect(native.items[0]!.transform).toMatchObject({ x: 20, width: 640, opacity: 0.35 })
+      // Top-level opacity is authoritative when both carriers exist.
+      const expected = structuredClone(initial.timeline)
+      const expectedItem = expected.tracks[0]!.items[0]!
+      if (expectedItem.type === 'caption_cue') throw new Error('Expected media or text')
+      expectedItem.transform!.opacity = 0.35
+      const converted = nativeTimelineToFrameDocument(native, expected)
+      if (!converted.ok) throw new Error(converted.failure.reason)
+      expect(deriveSupportedHostEdit(expected, converted.document).batch).toBeNull()
+    },
+  )
+
+  it('does not turn inherited caption style into incidental cue edits while changing media opacity', () => {
+    const initial = snapshot()
+    initial.timeline.tracks = [
+      ...initial.timeline.tracks,
+      {
+        id: 'captions',
+        kind: 'caption',
+        name: 'Captions',
+        locked: false,
+        muted: false,
+        defaultStyle: { font_size: 52, color: '#ffaa00' },
+        items: [
+          {
+            id: 'cue',
+            type: 'caption_cue',
+            trackId: 'captions',
+            from: 0,
+            durationInFrames: 30,
+            text: 'Hello',
+          },
+        ],
+      },
+    ]
+    const native = hostSnapshotToNativeTimeline(initial)
+    native.items.find((item) => item.id === 'clip-1')!.transform = { opacity: 0.5 }
+    const converted = nativeTimelineToFrameDocument(native, initial.timeline)
+    if (!converted.ok) throw new Error(converted.failure.reason)
+    expect(converted.document.tracks[1]!.items[0]).not.toHaveProperty('style')
+    const batch = deriveSupportedHostEdit(initial.timeline, converted.document).batch!
+    expect(batch.commands).toMatchObject([
+      { type: 'set_item_properties', item_id: 'clip-1', properties: { opacity: 0.5 } },
+    ])
+    expect(batch.commands).toHaveLength(1)
+  })
+
+  it('enforces 128-item attachment bounds before direct or diff-based submission', async () => {
+    const initial = snapshot({ durationInFrames: 129 * 60 })
+    const anchor = initial.timeline.tracks[0]!.items[0]!
+    initial.timeline.tracks[0]!.items = Array.from({ length: 129 }, (_, index) => ({
+      ...anchor,
+      id: `clip-${index}`,
+      from: index * 60,
+    }))
+    const ids = initial.timeline.tracks[0]!.items.map((item) => item.id)
+    const harness = createFakeHost(initial)
+    const controller = new HostEditorController(harness.host, initial)
+    await expect(controller.requestSetItemAttachment(ids, false)).resolves.toMatchObject({
+      status: 'unsupported',
+      reason: expect.stringContaining('128'),
+    })
+    expect(harness.submitEdit).not.toHaveBeenCalled()
+    const changed = structuredClone(initial.timeline)
+    changed.tracks[0]!.items.forEach((item) => {
+      item.rippleLinked = false
+    })
+    expect(deriveSupportedHostEdit(initial.timeline, changed)).toMatchObject({
+      batch: null,
+      reason: expect.stringContaining('128'),
+    })
+    changed.tracks[0]!.items[128]!.rippleLinked = undefined
+    expect(deriveSupportedHostEdit(initial.timeline, changed).batch?.preconditions).toHaveLength(
+      128,
+    )
+    await expect(
+      controller.requestSetItemAttachment(ids.slice(0, 128), false),
+    ).resolves.toMatchObject({ status: 'applied' })
+  })
+})
diff --git a/src/features/editor/host/controller.ts b/src/features/editor/host/controller.ts
index b8686a953..b2c17672e 100644
--- a/src/features/editor/host/controller.ts
+++ b/src/features/editor/host/controller.ts
@@ -531,6 +531,11 @@ function deriveSetItemAttachment(
   const ids = [...new Set(itemIds)]
   const items = itemMap(previous)
   if (ids.length === 0) return { batch: null, reason: 'No timeline item is selected' }
+  if (ids.length > 128)
+    return {
+      batch: null,
+      reason: 'Cannot change attachment for more than 128 timeline items at once',
+    }
   const selected = ids.map((id) => items.get(id))
   if (selected.some((item) => item === undefined)) {
     return { batch: null, reason: 'The selected timeline item is no longer authoritative' }
@@ -624,6 +629,11 @@ export function deriveSupportedHostEdit(
     })
 
   if (attachmentOnlyChange) {
+    if (changed.length > 128)
+      return {
+        batch: null,
+        reason: 'Cannot change attachment for more than 128 timeline items at once',
+      }
     commands.push({
       command_id: `attachment-${operationId}`,
       type: 'set_item_attachment',
@@ -933,6 +943,35 @@ export function deriveSupportedHostEdit(
         source_us: framesToMicroseconds(sourceFrame, fps),
       })
       preconditions.push(preconditionForItem(before, fps))
+    } else if (
+      metadataUnchanged &&
+      sourceUnchanged &&
+      durationUnchanged &&
+      timelineUnchanged &&
+      sameTrack &&
+      !transformUnchanged
+    ) {
+      const previousTransform = normalizedTransform(before)
+      const nextTransform = normalizedTransform(after)
+      const properties: Extract<EditCommand, { type: 'set_item_properties' }>['properties'] = {}
+      const placementChanged = ['x', 'y', 'width', 'height', 'anchorX', 'anchorY', 'rotation'].some(
+        (key) => previousTransform[key] !== nextTransform[key],
+      )
+      if (previousTransform.opacity !== nextTransform.opacity)
+        properties.opacity = nextTransform.opacity
+      // Preserve the surface's native placement payload. The host owns its
+      // canvas/media-dependent conversion to the wire transform coordinates.
+      if (placementChanged)
+        properties.transform = after.transform
+          ? ({ ...after.transform } as unknown as NonNullable<typeof properties.transform>)
+          : null
+      commands.push({
+        command_id: `properties-${id}`,
+        type: 'set_item_properties',
+        item_id: id,
+        properties,
+      })
+      preconditions.push(preconditionForItem(before, fps))
     } else {
       const failedPredicates: HostEditPredicate[] = []
       if (!metadataUnchanged) failedPredicates.push('metadata')
diff --git a/src/features/editor/host/document.ts b/src/features/editor/host/document.ts
index 0f4f96a1b..366ff8f12 100644
--- a/src/features/editor/host/document.ts
+++ b/src/features/editor/host/document.ts
@@ -177,7 +177,14 @@ function nativeItemFromHostItem(
         ? { textAlign: item.style.alignment }
         : {}),
       ...(item.opacity !== undefined ? { transform: { opacity: item.opacity } } : {}),
-      ...(item.transform ? { transform: frameTransformToNative(item.transform) } : {}),
+      ...(item.transform
+        ? {
+            transform: {
+              ...frameTransformToNative(item.transform),
+              ...(item.opacity !== undefined ? { opacity: item.opacity } : {}),
+            },
+          }
+        : {}),
     }
   }
 
@@ -239,7 +246,14 @@ function nativeItemFromHostItem(
     ...(item.volume !== undefined ? { volume: item.volume } : {}),
     ...(item.speed !== undefined ? { speed: item.speed } : {}),
     ...(item.opacity !== undefined ? { transform: { opacity: item.opacity } } : {}),
-    ...(item.transform ? { transform: frameTransformToNative(item.transform) } : {}),
+    ...(item.transform
+      ? {
+          transform: {
+            ...frameTransformToNative(item.transform),
+            ...(item.opacity !== undefined ? { opacity: item.opacity } : {}),
+          },
+        }
+      : {}),
   }
 
   if (item.type === 'audio') return { ...common, type: 'audio' }

From 182d7ce37f55586b86f800d32c4b8e43061c6c4a Mon Sep 17 00:00:00 2001
From: Patrick Lu <lightning.lu7@gmail.com>
Date: Tue, 8 Sep 2026 14:12:06 -0700
Subject: [PATCH 13/22] fix(preview): preserve host geometry and transport
 compatibility

---
 .../preview/hooks/use-custom-player.test.tsx  | 34 +++++++++++++
 .../preview/hooks/use-custom-player.ts        |  6 ++-
 .../components/item-visual-wrapper.test.tsx   | 50 +++++++++++++++++++
 .../components/item-visual-wrapper.tsx        | 17 ++++++-
 .../components/video-content.test.tsx         | 35 ++++++++++++-
 .../components/video-content.tsx              |  6 +--
 .../deps/stores-contract.ts                   |  1 +
 7 files changed, 141 insertions(+), 8 deletions(-)
 create mode 100644 src/features/preview/hooks/use-custom-player.test.tsx
 create mode 100644 src/runtime/composition-runtime/components/item-visual-wrapper.test.tsx

diff --git a/src/features/preview/hooks/use-custom-player.test.tsx b/src/features/preview/hooks/use-custom-player.test.tsx
new file mode 100644
index 000000000..d693b5981
--- /dev/null
+++ b/src/features/preview/hooks/use-custom-player.test.tsx
@@ -0,0 +1,34 @@
+import { cleanup, renderHook } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vite-plus/test'
+import { usePlaybackStore } from '@/shared/state/playback'
+import { useEditorStore } from '@/shared/state/editor'
+import { useCustomPlayer } from './use-custom-player'
+
+afterEach(() => {
+  cleanup()
+  usePlaybackStore.setState({ isPlaying: false })
+  useEditorStore.setState({ hostMode: false })
+})
+
+describe('preview mount transport ownership', () => {
+  it.each([true, false])('preserves host transport only when hostMode=%s', (hostMode) => {
+    useEditorStore.setState({ hostMode })
+    usePlaybackStore.setState({ isPlaying: true, currentFrame: 42 })
+    const playerRef = {
+      current: {
+        seekTo: vi.fn(),
+        play: vi.fn(),
+        pause: vi.fn(),
+        getCurrentFrame: () => 42,
+        isPlaying: () => true,
+        setPlaybackRate: vi.fn(),
+      },
+    }
+    const first = renderHook(() => useCustomPlayer(playerRef))
+    expect(usePlaybackStore.getState().isPlaying).toBe(hostMode)
+    first.unmount()
+    renderHook(() => useCustomPlayer(playerRef))
+    expect(usePlaybackStore.getState().isPlaying).toBe(hostMode)
+    expect(usePlaybackStore.getState().currentFrame).toBe(42)
+  })
+})
diff --git a/src/features/preview/hooks/use-custom-player.ts b/src/features/preview/hooks/use-custom-player.ts
index 86f531cac..7fb105db8 100644
--- a/src/features/preview/hooks/use-custom-player.ts
+++ b/src/features/preview/hooks/use-custom-player.ts
@@ -10,6 +10,7 @@
  */
 
 import { useRef, useEffect, useState, useCallback } from 'react'
+import { useEditorStore } from '@/shared/state/editor'
 import { usePlaybackStore } from '@/shared/state/playback'
 import { useTimelineSettingsStore } from '@/features/preview/deps/timeline-store'
 import { resolvePreviewTransitionFromPlaybackStates } from '../utils/preview-state-coordinator'
@@ -168,7 +169,7 @@ export function useCustomPlayer(
     [playerRef, seekPlayerToFrame],
   )
 
-  // Pause playback when this hook mounts while already playing. That only
+  // In standalone mode, pause when this hook mounts while already playing. That only
   // happens on a mid-playback remount of the preview — e.g. switching to/from
   // the Color workspace swaps VideoPreview<->ColorVideoPreview, remounting the
   // Player. The fresh player starts paused at the preserved frame (via the
@@ -178,7 +179,8 @@ export function useCustomPlayer(
   // store is never playing, so this is a no-op.)
   useEffect(() => {
     const playback = usePlaybackStore.getState()
-    if (playback.isPlaying) {
+    // Host transport outlives this preview; mounting must not pause it.
+    if (playback.isPlaying && !useEditorStore.getState().hostMode) {
       playback.pause()
     }
     // Mount-only: intentionally no deps.
diff --git a/src/runtime/composition-runtime/components/item-visual-wrapper.test.tsx b/src/runtime/composition-runtime/components/item-visual-wrapper.test.tsx
new file mode 100644
index 000000000..8957b067b
--- /dev/null
+++ b/src/runtime/composition-runtime/components/item-visual-wrapper.test.tsx
@@ -0,0 +1,50 @@
+import { cleanup, render } from '@testing-library/react'
+import { afterEach, describe, expect, it } from 'vite-plus/test'
+import { useEditorStore } from '@/shared/state/editor'
+import { VideoConfigProvider } from '@/runtime/composition-runtime/deps/player'
+import { ItemVisualWrapper } from './item-visual-wrapper'
+
+afterEach(() => {
+  cleanup()
+  useEditorStore.setState({ hostMode: false })
+})
+
+describe('host explicit media geometry', () => {
+  it.each([
+    { hostMode: true, sourceWidth: 1920, sourceHeight: 1080, height: '100%' },
+    { hostMode: false, sourceWidth: 1920, sourceHeight: 1080, height: '56.25%' },
+    { hostMode: true, sourceWidth: 400, sourceHeight: 400, height: '100%' },
+  ])(
+    'renders requested bounds for $hostMode / $sourceWidth x $sourceHeight',
+    ({ hostMode, sourceWidth, sourceHeight, height }) => {
+      useEditorStore.setState({ hostMode })
+      const view = render(
+        <VideoConfigProvider
+          id="geometry"
+          width={1920}
+          height={1080}
+          fps={30}
+          durationInFrames={90}
+        >
+          <ItemVisualWrapper
+            item={{
+              id: 'image',
+              type: 'image',
+              trackId: 'track',
+              from: 0,
+              durationInFrames: 90,
+              label: 'Image',
+              src: 'blob:test',
+              transform: { width: 400, height: 400 },
+            }}
+            mediaContent={{ fitMode: 'contain', sourceWidth, sourceHeight }}
+          >
+            <img data-testid="media" alt="" />
+          </ItemVisualWrapper>
+        </VideoConfigProvider>,
+      )
+      expect(view.getByTestId('media').parentElement?.style.height).toBe(height)
+      expect(view.getByTestId('media').parentElement?.style.width).toBe('100%')
+    },
+  )
+})
diff --git a/src/runtime/composition-runtime/components/item-visual-wrapper.tsx b/src/runtime/composition-runtime/components/item-visual-wrapper.tsx
index dfb3b893f..f9b0d3245 100644
--- a/src/runtime/composition-runtime/components/item-visual-wrapper.tsx
+++ b/src/runtime/composition-runtime/components/item-visual-wrapper.tsx
@@ -18,6 +18,7 @@ import {
 } from '../utils/corner-pin'
 import { getShapePath } from '../utils/shape-path'
 import {
+  useEditorStore,
   useCornerPinStore,
   useGizmoStore,
   usePlaybackStore,
@@ -571,6 +572,18 @@ export const ItemVisualWrapper: React.FC<ItemVisualWrapperProps> = ({
     state.transform.height,
     state.transform.width,
   ])
+  // Host geometry is explicit: preserve the shipped nonproportional sizing
+  // rather than introducing letterboxing inside an authored rectangle.
+  const hostMediaFitMode =
+    useEditorStore.getState().hostMode &&
+    mediaFitMode === 'contain' &&
+    (mediaSourceWidth ?? 0) > 0 &&
+    (mediaSourceHeight ?? 0) > 0 &&
+    Math.abs(
+      state.transform.width * mediaSourceHeight! - state.transform.height * mediaSourceWidth!,
+    ) > 0.01
+      ? 'fill'
+      : mediaFitMode
   const containedMediaStyle = useMemo((): React.CSSProperties => {
     const width = state.transform.width
     const height = state.transform.height
@@ -709,7 +722,7 @@ export const ItemVisualWrapper: React.FC<ItemVisualWrapperProps> = ({
       containerWidth={state.transform.width}
       containerHeight={state.transform.height}
       crop={effectiveCrop}
-      fitMode={mediaContent.fitMode}
+      fitMode={hostMediaFitMode}
     >
       {children}
     </ContainedMediaLayout>
@@ -735,7 +748,7 @@ export const ItemVisualWrapper: React.FC<ItemVisualWrapperProps> = ({
       containerWidth={cornerPinTargetRect.width}
       containerHeight={cornerPinTargetRect.height}
       crop={effectiveCrop}
-      fitMode={mediaContent.fitMode}
+      fitMode={hostMediaFitMode}
     >
       {children}
     </ContainedMediaLayout>
diff --git a/src/runtime/composition-runtime/components/video-content.test.tsx b/src/runtime/composition-runtime/components/video-content.test.tsx
index d0e1463b9..6adc801be 100644
--- a/src/runtime/composition-runtime/components/video-content.test.tsx
+++ b/src/runtime/composition-runtime/components/video-content.test.tsx
@@ -15,6 +15,7 @@ const testState = vi.hoisted(() => ({
     acquireForClip: ReturnType<typeof vi.fn>
     releaseClip: ReturnType<typeof vi.fn>
   } | null,
+  renderedIsPlaying: null as boolean | null,
   playbackState: {
     currentFrame: 0,
     isPlaying: true,
@@ -120,7 +121,7 @@ vi.mock('@/runtime/composition-runtime/deps/stores', () => ({
 
 vi.mock('../hooks/use-player-compat', () => ({
   useVideoConfig: () => ({ fps: 30, width: 1280, height: 720, durationInFrames: 120 }),
-  useIsPlaying: () => testState.playbackState.isPlaying,
+  useIsPlaying: () => testState.renderedIsPlaying ?? testState.playbackState.isPlaying,
 }))
 
 vi.mock('../contexts/keyframes-context', () => ({
@@ -152,6 +153,7 @@ describe('VideoContent pooled handoff', () => {
     releaseClipMock.mockClear()
     registerDomVideoElementMock.mockClear()
     unregisterDomVideoElementMock.mockClear()
+    testState.renderedIsPlaying = null
     playbackState.currentFrame = 0
     playbackState.isPlaying = true
     playbackState.previewFrame = null
@@ -162,6 +164,37 @@ describe('VideoContent pooled handoff', () => {
     timelineState.keyframes = []
   })
 
+  it.each([true, false])(
+    'stale paused render respects live transport playing=%s',
+    async (livePlaying) => {
+      testState.renderedIsPlaying = false
+      playbackState.isPlaying = livePlaying
+      const video = createMockVideoElement()
+      await video.play()
+      acquireForClipMock.mockReturnValue(video)
+      render(
+        <VideoContent
+          item={{
+            id: 'stale',
+            type: 'video',
+            trackId: 'track',
+            from: 0,
+            durationInFrames: 90,
+            label: 'Stale',
+            src: 'blob:test',
+          }}
+          muted={false}
+          safeTrimBefore={0}
+          playbackRate={1}
+          sourceFps={30}
+          audioEqStages={[]}
+        />,
+      )
+      await waitFor(() => expect(acquireForClipMock).toHaveBeenCalledTimes(1))
+      expect(video.paused).toBe(!livePlaying)
+    },
+  )
+
   it('keeps the acquired pool element when only itemId changes on the same pool lane', async () => {
     const pooledElement = createMockVideoElement()
     acquireForClipMock.mockReturnValue(pooledElement)
diff --git a/src/runtime/composition-runtime/components/video-content.tsx b/src/runtime/composition-runtime/components/video-content.tsx
index f299196d4..be7dc16b9 100644
--- a/src/runtime/composition-runtime/components/video-content.tsx
+++ b/src/runtime/composition-runtime/components/video-content.tsx
@@ -897,11 +897,11 @@ const NativePreviewVideo: React.FC<{
         })
       }
     } else {
-      // Pause video when not playing
-      if (!video.paused) {
+      // A delayed paused render must not stop transport that has already resumed.
+      const playbackState = usePlaybackStore.getState()
+      if (!video.paused && !playbackState.isPlaying) {
         video.pause()
       }
-      const playbackState = usePlaybackStore.getState()
       const isPreviewScrubbing =
         !playbackState.isPlaying &&
         playbackState.previewFrame !== null &&
diff --git a/src/runtime/composition-runtime/deps/stores-contract.ts b/src/runtime/composition-runtime/deps/stores-contract.ts
index 05533cbbc..a54342f5d 100644
--- a/src/runtime/composition-runtime/deps/stores-contract.ts
+++ b/src/runtime/composition-runtime/deps/stores-contract.ts
@@ -13,3 +13,4 @@ export { usePlaybackStore } from '@/shared/state/playback'
 export { useTimelineStore } from '@/features/timeline/stores/timeline-store'
 export { useCompositionsStore } from '@/features/timeline/stores/compositions-store'
 export { useDebugStore } from '@/features/editor/stores/debug-store'
+export { useEditorStore } from '@/shared/state/editor'

From 3f2aed03a1cdd26b201cdd38ee23fbc829b0f67e Mon Sep 17 00:00:00 2001
From: Patrick Lu <lightning.lu7@gmail.com>
Date: Tue, 8 Sep 2026 14:19:06 -0700
Subject: [PATCH 14/22] test(package): include worker URL regressions in
 regular suite

---
 scripts/editor-package-worker-urls.mjs        | 22 +++++++++++++------
 ...mjs => editor-package-worker-urls.test.ts} |  2 +-
 vite.config.ts                                |  2 +-
 3 files changed, 17 insertions(+), 9 deletions(-)
 rename scripts/{editor-package-worker-urls.test.mjs => editor-package-worker-urls.test.ts} (97%)

diff --git a/scripts/editor-package-worker-urls.mjs b/scripts/editor-package-worker-urls.mjs
index eedfb535b..66467095a 100644
--- a/scripts/editor-package-worker-urls.mjs
+++ b/scripts/editor-package-worker-urls.mjs
@@ -12,6 +12,19 @@ function isGeneratedWorkerBase(node) {
     node.left.type === 'Literal' && node.left.value === '' && isImportMetaUrl(node.right))
 }
 
+function isNamedConstructor(node, name) {
+  return node?.type === 'NewExpression' && node.callee.type === 'Identifier' &&
+    node.callee.name === name
+}
+
+function publicWorkerUrl(url) {
+  if (!isNamedConstructor(url, 'URL') || url.arguments.length !== 2) return null
+  const [asset, base] = url.arguments
+  if (asset.type !== 'Literal' || typeof asset.value !== 'string' ||
+    !/^\/assets\/[A-Za-z0-9][A-Za-z0-9._-]*\.js$/.test(asset.value) || !isGeneratedWorkerBase(base)) return null
+  return { start: url.start, end: url.end, text: JSON.stringify(asset.value) }
+}
+
 /** Embedded hosts stage workers at their public root; keep them runtime URLs for Turbopack. */
 export function normalizeEditorWorkerUrls(code, filename = 'editor-chunk.js') {
   if (!code.includes('/assets/')) return code
@@ -21,13 +34,8 @@ export function normalizeEditorWorkerUrls(code, filename = 'editor-chunk.js') {
   new Visitor({
     NewExpression(node) {
       if (node.callee.type !== 'Identifier' || !['Worker', 'SharedWorker'].includes(node.callee.name)) return
-      const url = node.arguments[0]
-      if (url?.type !== 'NewExpression' || url.callee.type !== 'Identifier' ||
-        url.callee.name !== 'URL' || url.arguments.length !== 2) return
-      const [asset, base] = url.arguments
-      if (asset.type !== 'Literal' || typeof asset.value !== 'string' ||
-        !/^\/assets\/[A-Za-z0-9][A-Za-z0-9._-]*\.js$/.test(asset.value) || !isGeneratedWorkerBase(base)) return
-      replacements.push({ start: url.start, end: url.end, text: JSON.stringify(asset.value) })
+      const replacement = publicWorkerUrl(node.arguments[0])
+      if (replacement) replacements.push(replacement)
     },
   }).visit(parsed.program)
   return replacements.sort((left, right) => right.start - left.start).reduce(
diff --git a/scripts/editor-package-worker-urls.test.mjs b/scripts/editor-package-worker-urls.test.ts
similarity index 97%
rename from scripts/editor-package-worker-urls.test.mjs
rename to scripts/editor-package-worker-urls.test.ts
index bc111bf4f..f6675f7a3 100644
--- a/scripts/editor-package-worker-urls.test.mjs
+++ b/scripts/editor-package-worker-urls.test.ts
@@ -1,5 +1,5 @@
 import assert from 'node:assert/strict'
-import test from 'node:test'
+import { test } from 'vite-plus/test'
 import { normalizeEditorWorkerUrls } from './editor-package-worker-urls.mjs'
 
 test('unwraps generated worker URLs while retaining worker options and content', () => {
diff --git a/vite.config.ts b/vite.config.ts
index b12c6a422..74e3b6801 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -79,7 +79,7 @@ export default defineConfig({
     globals: true,
     environment: 'jsdom',
     setupFiles: ['./src/test/setup.ts'],
-    include: ['src/**/*.test.{ts,tsx}'],
+    include: ['src/**/*.test.{ts,tsx}', 'scripts/editor-package-worker-urls.test.ts'],
     coverage: {
       provider: 'v8',
       reporter: ['text', 'json', 'html'],

From 323fa67295b69a89957c9b0411696d1e11c30b8c Mon Sep 17 00:00:00 2001
From: Patrick Lu <lightning.lu7@gmail.com>
Date: Tue, 8 Sep 2026 14:18:12 -0700
Subject: [PATCH 15/22] refactor(host): simplify trim intent and commit flow

---
 src/features/editor/host/runtime.ts     |  41 ++++----
 src/features/editor/host/trim-intent.ts | 130 +++++++++++++++---------
 2 files changed, 104 insertions(+), 67 deletions(-)

diff --git a/src/features/editor/host/runtime.ts b/src/features/editor/host/runtime.ts
index 5ff9366d8..30d7c7bb7 100644
--- a/src/features/editor/host/runtime.ts
+++ b/src/features/editor/host/runtime.ts
@@ -112,23 +112,7 @@ export class EmbeddedEditorHostRuntime implements EmbeddedEditorHostRuntimeContr
     this.trimGesture = null // one-shot, including no-op and rejection
     try {
       if (intent.deltaFrames === 0) return
-      const current = this.controller.getSnapshot().timeline
-      if (
-        current.timelineId !== gesture.snapshot.timeline.timelineId ||
-        current.revision !== gesture.snapshot.timeline.revision ||
-        JSON.stringify(current) !== JSON.stringify(gesture.snapshot.timeline) ||
-        JSON.stringify(this.controller.getSnapshot().assets) !==
-          JSON.stringify(gesture.snapshot.assets)
-      ) {
-        throw new Error('This clip changed during the trim. Review the updated cut and try again.')
-      }
-      const batch = trimIntentBatch(gesture.snapshot.timeline, gesture.itemId, {
-        ...intent,
-        itemIds: gesture.itemIds,
-      })
-      const result = await this.controller.submitEdit(batch)
-      if (result.status === 'unsupported')
-        this.host.notify?.({ kind: 'warning', message: result.reason })
+      await this.submitTrimGesture(gesture, intent)
     } catch (error) {
       this.host.notify?.({
         kind: 'error',
@@ -142,6 +126,29 @@ export class EmbeddedEditorHostRuntime implements EmbeddedEditorHostRuntimeContr
     }
   }
 
+  private async submitTrimGesture(
+    gesture: NonNullable<EmbeddedEditorHostRuntime['trimGesture']>,
+    intent: HostTrimIntent,
+  ): Promise<void> {
+    const current = this.controller.getSnapshot().timeline
+    if (
+      current.timelineId !== gesture.snapshot.timeline.timelineId ||
+      current.revision !== gesture.snapshot.timeline.revision ||
+      JSON.stringify(current) !== JSON.stringify(gesture.snapshot.timeline) ||
+      JSON.stringify(this.controller.getSnapshot().assets) !==
+        JSON.stringify(gesture.snapshot.assets)
+    ) {
+      throw new Error('This clip changed during the trim. Review the updated cut and try again.')
+    }
+    const batch = trimIntentBatch(gesture.snapshot.timeline, gesture.itemId, {
+      ...intent,
+      itemIds: gesture.itemIds,
+    })
+    const result = await this.controller.submitEdit(batch)
+    if (result.status === 'unsupported')
+      this.host.notify?.({ kind: 'warning', message: result.reason })
+  }
+
   /**
    * Runtime producer for the host UI's Delete action. It submits against the
    * controller's authoritative snapshot and leaves the visible stores alone
diff --git a/src/features/editor/host/trim-intent.ts b/src/features/editor/host/trim-intent.ts
index 1b853c7eb..0d9eb2f0a 100644
--- a/src/features/editor/host/trim-intent.ts
+++ b/src/features/editor/host/trim-intent.ts
@@ -15,6 +15,82 @@ export interface HostTrimIntent {
   neighborId?: string | null
 }
 
+function assertTrimEditable(document: FreeCutFrameDocument, item: FreeCutFrameItem): void {
+  if (item.linkedGroupId)
+    throw new Error('Linked clip trimming is not supported by the host yet. No clips were changed.')
+  let track = document.tracks.find((candidate) => candidate.id === item.trackId)
+  const seen = new Set<string>()
+  while (track && !seen.has(track.id)) {
+    seen.add(track.id)
+    if (track.locked)
+      throw new Error('Unlock the affected track before trimming. No clips were changed.')
+    track = document.tracks.find((candidate) => candidate.id === track?.parentTrackId)
+  }
+}
+
+function trimmedSourceFrame(
+  item: FreeCutFrameItem,
+  edge: HostTrimIntent['handle'],
+  deltaFrames: number,
+): number {
+  if (item.type !== 'video' && item.type !== 'audio' && item.type !== 'image')
+    throw new Error('This item does not support source trimming.')
+  const sourceStart = item.sourceStart ?? 0
+  const sourceEnd = item.sourceEnd ?? sourceStart + item.durationInFrames
+  const speed = item.speed ?? 1
+  const source = (edge === 'start' ? sourceStart : sourceEnd) + Math.round(deltaFrames * speed)
+  if (source < 0) throw new Error('This trim exceeds the available source handles.')
+  return source
+}
+
+function rollingNeighbor(
+  all: readonly FreeCutFrameItem[],
+  anchor: FreeCutFrameItem,
+  intent: HostTrimIntent,
+): FreeCutFrameItem {
+  const neighbor = all.find((item) => item.id === intent.neighborId)
+  if (
+    !neighbor ||
+    neighbor.trackId !== anchor.trackId ||
+    (intent.handle === 'end'
+      ? anchor.from + anchor.durationInFrames !== neighbor.from
+      : neighbor.from + neighbor.durationInFrames !== anchor.from)
+  ) {
+    throw new Error('The adjacent cut changed. Review the cut and try again.')
+  }
+  return neighbor
+}
+
+function appendRippleMoves(
+  document: FreeCutFrameDocument,
+  anchor: FreeCutFrameItem,
+  intent: HostTrimIntent,
+  move: (item: FreeCutFrameItem, from: number) => void,
+): void {
+  if (document.tracks.some((track) => track.id !== anchor.trackId && track.syncLock)) {
+    throw new Error(
+      'This trim affects synchronized tracks. Use a supported sequence edit; no clips were changed.',
+    )
+  }
+  const shift = intent.handle === 'start' ? -intent.deltaFrames : intent.deltaFrames
+  if (intent.handle === 'start') move(anchor, anchor.from)
+  // Respect durable attachment breaks, including a detached anchor. Gaps
+  // before the break retain their width, matching the existing ripple tool.
+  if (anchor.rippleLinked !== false) {
+    const tail = document.tracks
+      .flatMap((track) => track.items)
+      .filter(
+        (item) =>
+          item.trackId === anchor.trackId && item.from >= anchor.from + anchor.durationInFrames,
+      )
+      .sort((a, b) => a.from - b.from)
+    for (const item of tail) {
+      if (item.rippleLinked === false) break
+      move(item, item.from + shift)
+    }
+  }
+}
+
 export function trimIntentBatch(
   document: FreeCutFrameDocument,
   anchorId: string,
@@ -31,30 +107,13 @@ export function trimIntentBatch(
   const commands: EditCommand[] = []
   const touched = new Map<string, FreeCutFrameItem>()
   const assertEditable = (item: FreeCutFrameItem) => {
-    if (item.linkedGroupId)
-      throw new Error(
-        'Linked clip trimming is not supported by the host yet. No clips were changed.',
-      )
-    let track = document.tracks.find((candidate) => candidate.id === item.trackId)
-    const seen = new Set<string>()
-    while (track && !seen.has(track.id)) {
-      seen.add(track.id)
-      if (track.locked)
-        throw new Error('Unlock the affected track before trimming. No clips were changed.')
-      track = document.tracks.find((candidate) => candidate.id === track?.parentTrackId)
-    }
+    assertTrimEditable(document, item)
     touched.set(item.id, item)
   }
   const trim = (item: FreeCutFrameItem, edge: 'start' | 'end') => {
     assertEditable(item)
-    if (item.type !== 'video' && item.type !== 'audio' && item.type !== 'image')
-      throw new Error('This item does not support source trimming.')
     const delta = intent.deltaFrames
-    const sourceStart = item.sourceStart ?? 0
-    const sourceEnd = item.sourceEnd ?? sourceStart + item.durationInFrames
-    const speed = item.speed ?? 1
-    const source = (edge === 'start' ? sourceStart : sourceEnd) + Math.round(delta * speed)
-    if (source < 0) throw new Error('This trim exceeds the available source handles.')
+    const source = trimmedSourceFrame(item, edge, delta)
     commands.push({
       command_id: `trim-${item.id}`,
       type: 'trim_item',
@@ -82,39 +141,10 @@ export function trimIntentBatch(
   }
   trim(anchor, intent.handle)
   if (intent.mode === 'rolling') {
-    const neighbor = all.find((item) => item.id === intent.neighborId)
-    if (
-      !neighbor ||
-      neighbor.trackId !== anchor.trackId ||
-      (intent.handle === 'end'
-        ? anchor.from + anchor.durationInFrames !== neighbor.from
-        : neighbor.from + neighbor.durationInFrames !== anchor.from)
-    ) {
-      throw new Error('The adjacent cut changed. Review the cut and try again.')
-    }
+    const neighbor = rollingNeighbor(all, anchor, intent)
     trim(neighbor, intent.handle === 'start' ? 'end' : 'start')
   } else if (intent.mode === 'ripple') {
-    if (document.tracks.some((track) => track.id !== anchor.trackId && track.syncLock)) {
-      throw new Error(
-        'This trim affects synchronized tracks. Use a supported sequence edit; no clips were changed.',
-      )
-    }
-    const shift = intent.handle === 'start' ? -intent.deltaFrames : intent.deltaFrames
-    if (intent.handle === 'start') move(anchor, anchor.from)
-    // Respect durable attachment breaks, including a detached anchor. Gaps
-    // before the break retain their width, matching the existing ripple tool.
-    if (anchor.rippleLinked !== false) {
-      const tail = all
-        .filter(
-          (item) =>
-            item.trackId === anchor.trackId && item.from >= anchor.from + anchor.durationInFrames,
-        )
-        .sort((a, b) => a.from - b.from)
-      for (const item of tail) {
-        if (item.rippleLinked === false) break
-        move(item, item.from + shift)
-      }
-    }
+    appendRippleMoves(document, anchor, intent, move)
   }
   if (commands.length > 64)
     throw new Error('This trim exceeds the host operation limit. No clips were changed.')

From 99d2edc5a9c8a37206fc64ae1f277053bea86bb3 Mon Sep 17 00:00:00 2001
From: Patrick Lu <lightning.lu7@gmail.com>
Date: Tue, 8 Sep 2026 14:45:22 -0700
Subject: [PATCH 16/22] fix(transcript): invalidate selection when word
 projection changes

---
 .../editor/host/transcript-editor.test.tsx    | 120 +++++++++++++++++-
 .../editor/host/transcript-word-view.tsx      |  22 +++-
 2 files changed, 137 insertions(+), 5 deletions(-)

diff --git a/src/features/editor/host/transcript-editor.test.tsx b/src/features/editor/host/transcript-editor.test.tsx
index 363d0acec..de406a34b 100644
--- a/src/features/editor/host/transcript-editor.test.tsx
+++ b/src/features/editor/host/transcript-editor.test.tsx
@@ -205,6 +205,34 @@ function createHarness(
   const previewCommands = vi.fn(
     async (request: HostTranscriptCommandPreviewRequest): Promise<HostTranscriptCommandPreview> => {
       const isCut = request.action === 'cut' || request.action === 'ripple_cut'
+      // Model the backend's occurrence projection, then execute through the real adapter.
+      const targetedCutBatch = request.ranges?.every((range) => range.itemId)
+        ? {
+            ...cutBatch,
+            base_revision: request.baseRevision,
+            commands: request.ranges
+              .map((range, index) => {
+                const clip = remoteSnapshot.timeline.tracks
+                  .flatMap((track) => track.items)
+                  .find((item) => item.id === range.itemId)
+                if (!clip || (clip.type !== 'video' && clip.type !== 'audio'))
+                  throw new Error('Unknown fixture occurrence')
+                const frameUs = 1_000_000 / remoteSnapshot.project.fps
+                const sourceStartUs = (clip.sourceStart ?? 0) * frameUs
+                const speed = clip.speed ?? 1
+                return {
+                  command_id: `targeted-cut-${index}`,
+                  type: 'ripple_delete' as const,
+                  start_us: Math.round(
+                    clip.from * frameUs + (range.startUs - sourceStartUs) / speed,
+                  ),
+                  end_us: Math.round(clip.from * frameUs + (range.endUs - sourceStartUs) / speed),
+                  track_ids: null,
+                }
+              })
+              .sort((a, b) => b.start_us - a.start_us),
+          }
+        : cutBatch
       return {
         status: previewStatus,
         receiptId: 'transcript-receipt-1',
@@ -217,7 +245,7 @@ function createHarness(
         operationId: previewBatch.operation_id,
         idempotencyKey: previewBatch.idempotency_key,
         baseRevision: 0,
-        commandBatch: isCut ? cutBatch : previewBatch,
+        commandBatch: isCut ? targetedCutBatch : previewBatch,
         preview: isCut
           ? { action: 'cut', selectionCount: 1, willMutateTimeline: false }
           : { action: 'captions', captionCount: 1, willMutateTimeline: false },
@@ -399,6 +427,96 @@ describe('host-backed transcript consumer', () => {
     expect(screen.queryByTestId('host-transcript-apply')).not.toBeInTheDocument()
   })
 
+  it('invalidates a repeated-occurrence word selection when Load more reorders the projection', async () => {
+    const initial = snapshot()
+    initial.timeline.durationInFrames = 600
+    initial.timeline.media = [
+      {
+        media_id: 'asset-1',
+        media_kind: 'video',
+        content_hash: 'sha256:source-1',
+        duration_us: 10_000_000,
+        availability: { mode: 'cloud', cloud: { object_id: 'object-1' } },
+      },
+    ]
+    const occurrenceA = {
+      type: 'video' as const,
+      id: 'occurrence-a',
+      trackId: 'video',
+      mediaId: 'asset-1',
+      from: 0,
+      durationInFrames: 300,
+      sourceStart: 0,
+      sourceEnd: 300,
+    }
+    initial.timeline.tracks = [
+      {
+        id: 'video',
+        name: 'Video',
+        kind: 'video',
+        locked: false,
+        muted: false,
+        items: [occurrenceA, { ...occurrenceA, id: 'occurrence-b', from: 300 }],
+      },
+    ]
+    const harness = createHarness(initial)
+    harness.host.transcript!.occurrenceSelection = true
+    const pages = sections.map((section, index) => ({
+      ...section,
+      text: index === 0 ? 'X' : 'Y',
+      words: [{ text: index === 0 ? 'X' : 'Y', startUs: section.startUs, endUs: section.endUs }],
+    }))
+    harness.host.transcript!.getSections = vi.fn(({ cursor }) => ({
+      transcriptId: 'transcript-1',
+      sections: [pages[cursor ? 1 : 0]!],
+      hasMore: !cursor,
+      nextCursor: cursor ? null : 'page-2',
+    }))
+    renderHostEditor(harness)
+    const originalA = structuredClone(
+      harness.runtime.controller.getSnapshot().timeline.tracks[0]!.items[0],
+    )
+    const words = await screen.findAllByRole('button', { name: 'X' })
+    fireEvent.pointerDown(words[1]!) // index1 is B:X before pagination.
+    fireEvent.pointerUp(window)
+    fireEvent.click(screen.getByRole('button', { name: 'Load more transcript' }))
+    await screen.findAllByRole('button', { name: 'Y' }) // index1 is now A:Y.
+    expect(harness.runtime.controller.getSnapshot().timeline.revision).toBe(0)
+    const region = screen.getByRole('region', { name: 'Timed transcript words' })
+    fireEvent.keyDown(region, { key: 'Delete' })
+    expect(harness.previewCommands).not.toHaveBeenCalled()
+    expect(harness.submitEdit).not.toHaveBeenCalled()
+    expect(
+      screen.getByText('The edit or transcript changed. Select the words again.'),
+    ).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Delete selection' })).toBeDisabled()
+
+    // A fresh B:X selection derives an actual ripple command from B + X's source range.
+    fireEvent.pointerDown(screen.getAllByRole('button', { name: 'X' })[1]!)
+    fireEvent.pointerUp(window)
+    fireEvent.keyDown(region, { key: 'Delete' })
+    await waitFor(() => expect(harness.submitEdit).toHaveBeenCalledTimes(1))
+    expect(harness.previewCommands).toHaveBeenCalledWith(
+      expect.objectContaining({
+        baseRevision: 0,
+        ranges: [{ itemId: 'occurrence-b', startUs: 1_000_000, endUs: 2_000_000, text: 'X' }],
+      }),
+    )
+    expect(harness.submitEdit.mock.calls[0]![0].commands).toEqual([
+      expect.objectContaining({
+        type: 'ripple_delete',
+        start_us: 11_000_000,
+        end_us: 12_000_000,
+      }),
+    ])
+    await waitFor(() => expect(harness.runtime.controller.getSnapshot().timeline.revision).toBe(1))
+    const edited = harness.runtime.controller.getSnapshot().timeline
+    expect(edited.tracks[0]!.items.find((item) => item.id === 'occurrence-a')).toEqual(originalA)
+    expect(edited.durationInFrames).toBe(570)
+    expect(screen.getAllByRole('button', { name: 'X' })).toHaveLength(1)
+    expect(screen.getAllByRole('button', { name: 'Y' })).toHaveLength(2)
+  })
+
   it('displays bounded sections, previews without mutation, then applies through submitEdit', async () => {
     const harness = createHarness(snapshot())
     renderHostEditor(harness)
diff --git a/src/features/editor/host/transcript-word-view.tsx b/src/features/editor/host/transcript-word-view.tsx
index fc7514f7d..1a6b6ed6a 100644
--- a/src/features/editor/host/transcript-word-view.tsx
+++ b/src/features/editor/host/transcript-word-view.tsx
@@ -60,6 +60,7 @@ export function HostTranscriptWordView({
     anchor: number
     focus: number
     revision: number
+    projection: string
   } | null>(null)
   const [following, setFollowing] = useState(true)
   const scroll = useRef<HTMLDivElement>(null)
@@ -79,13 +80,18 @@ export function HostTranscriptWordView({
       ),
     [document, assetId, sections, scope, selectedClips],
   )
+  // Pagination can reorder repeated occurrences without changing the timeline revision.
+  // Bind indices to the complete measured projection, including retranscribed timings/text.
+  const projection = useMemo(() => JSON.stringify(words), [words])
   const otherSources = document.tracks.some((track) =>
     track.items.some((item) => 'mediaId' in item && item.mediaId !== assetId),
   )
   const active = words.findIndex(
     (word) => currentFrame >= word.startFrame && currentFrame < word.endFrame,
   )
-  const stale = selection !== null && selection.revision !== document.revision
+  const stale =
+    selection !== null &&
+    (selection.revision !== document.revision || selection.projection !== projection)
   const selected =
     selection && !stale
       ? words.slice(
@@ -111,9 +117,13 @@ export function HostTranscriptWordView({
   const choose = (index: number, extend: boolean) => {
     setFollowing(false)
     setSelection((previous) => ({
-      anchor: extend && previous?.revision === document.revision ? previous.anchor : index,
+      anchor:
+        extend && previous?.revision === document.revision && previous.projection === projection
+          ? previous.anchor
+          : index,
       focus: index,
       revision: document.revision,
+      projection,
     }))
     usePlaybackStore.getState().setCurrentFrame(Math.floor(words[index]!.startFrame))
   }
@@ -189,7 +199,11 @@ export function HostTranscriptWordView({
             event.stopPropagation()
             setSelection(null)
           } else {
-            const next = transcriptSelectionIndex(event.key, selection?.focus ?? 0, words.length)
+            const next = transcriptSelectionIndex(
+              event.key,
+              stale ? 0 : (selection?.focus ?? 0),
+              words.length,
+            )
             if (next === null) return
             event.preventDefault()
             event.stopPropagation()
@@ -251,7 +265,7 @@ export function HostTranscriptWordView({
       </div>
       {stale && (
         <p role="status" className="px-3 py-2 text-xs">
-          This edit changed. Select the words again.
+          The edit or transcript changed. Select the words again.
         </p>
       )}
       {!canCut && (

From 54d40d8d92b112834cce323972a51292207985f0 Mon Sep 17 00:00:00 2001
From: Patrick Lu <lightning.lu7@gmail.com>
Date: Tue, 8 Sep 2026 15:01:12 -0700
Subject: [PATCH 17/22] fix(timeline): enable split for one selected linked
 cohort

---
 .../timeline-primary-actions.test.tsx         | 65 +++++++++++++++++++
 .../components/timeline-primary-actions.tsx   | 12 +++-
 2 files changed, 75 insertions(+), 2 deletions(-)

diff --git a/src/features/timeline/components/timeline-primary-actions.test.tsx b/src/features/timeline/components/timeline-primary-actions.test.tsx
index 03381c9b4..ef4ea45fd 100644
--- a/src/features/timeline/components/timeline-primary-actions.test.tsx
+++ b/src/features/timeline/components/timeline-primary-actions.test.tsx
@@ -2,6 +2,7 @@ import { act, fireEvent, render, screen } from '@testing-library/react'
 import { beforeEach, describe, expect, it, vi } from 'vite-plus/test'
 import { toast } from 'sonner'
 import { useItemsStore } from '../stores/items-store'
+import { useTimelineCommandStore } from '../stores/timeline-command-store'
 import { useTimelineStore } from '../stores/timeline-store'
 import { useSelectionStore } from '@/shared/state/selection'
 import { usePlaybackStore } from '@/shared/state/playback'
@@ -56,6 +57,70 @@ describe('timeline primary actions', () => {
     expect(split).toHaveBeenCalledExactlyOnceWith('clip', 30)
   })
 
+  it('splits a selected linked A/V cohort once and restores both with one undo', () => {
+    context.mode = 'standalone'
+    useEditorStore.setState({ hostMode: false })
+    useItemsStore
+      .getState()
+      .setItems([
+        makeTimelineVideoItem({
+          id: 'clip',
+          trackId: 'v',
+          linkedGroupId: 'pair',
+          from: 0,
+          durationInFrames: 60,
+        }),
+        makeTimelineAudioItem({
+          id: 'audio',
+          trackId: 'a',
+          linkedGroupId: 'pair',
+          from: 0,
+          durationInFrames: 60,
+        }),
+      ])
+    useSelectionStore.getState().selectItems(['clip', 'audio'])
+    useTimelineCommandStore.getState().clearHistory()
+    render(<TimelinePrimaryActions />)
+    expect(screen.getByRole('button', { name: 'Split' })).toBeEnabled()
+    fireEvent.click(screen.getByRole('button', { name: 'Split' }))
+    expect(useItemsStore.getState().items).toHaveLength(4)
+    for (const trackId of ['v', 'a']) {
+      expect(
+        useItemsStore
+          .getState()
+          .items.filter((item) => item.trackId === trackId)
+          .map((item) => [item.from, item.durationInFrames]),
+      ).toEqual([
+        [0, 30],
+        [30, 30],
+      ])
+    }
+    expect(useTimelineCommandStore.getState().undoStack).toHaveLength(1)
+    act(() => useTimelineStore.temporal.getState().undo())
+    expect(
+      useItemsStore.getState().items.map((item) => [item.id, item.from, item.durationInFrames]),
+    ).toEqual([
+      ['clip', 0, 60],
+      ['audio', 0, 60],
+    ])
+  })
+
+  it.each([false, true])(
+    'keeps unrelated multi-selection disabled with linked selection %s',
+    (linkedSelectionEnabled) => {
+      useEditorStore.setState({ linkedSelectionEnabled })
+      useItemsStore
+        .getState()
+        .setItems([
+          makeTimelineVideoItem({ id: 'clip', trackId: 'v', from: 0, durationInFrames: 60 }),
+          makeTimelineAudioItem({ id: 'audio', trackId: 'a', from: 0, durationInFrames: 60 }),
+        ])
+      useSelectionStore.getState().selectItems(['clip', 'audio'])
+      render(<TimelinePrimaryActions />)
+      expect(screen.getByRole('button', { name: 'Split' })).toBeDisabled()
+    },
+  )
+
   it('disables delete when the host denies timeline.remove', () => {
     context.denied = 'timeline.remove'
     render(<TimelinePrimaryActions />)
diff --git a/src/features/timeline/components/timeline-primary-actions.tsx b/src/features/timeline/components/timeline-primary-actions.tsx
index 62ef37502..6f48b62d0 100644
--- a/src/features/timeline/components/timeline-primary-actions.tsx
+++ b/src/features/timeline/components/timeline-primary-actions.tsx
@@ -8,7 +8,11 @@ import { usePlaybackStore } from '@/shared/state/playback'
 import { useEditorStore } from '@/shared/state/editor'
 import { useTimelineStore } from '../stores/timeline-store'
 import { useEditorCapability, useEditorHostContext } from '../deps/editor'
-import { expandSelectionWithLinkedItems, getSynchronizedLinkedItems } from '../utils/linked-items'
+import {
+  expandSelectionWithLinkedItems,
+  getSynchronizedLinkedItems,
+  getUniqueLinkedItemAnchorIds,
+} from '../utils/linked-items'
 
 function isSplitDisabled(
   item: TimelineItem | undefined,
@@ -41,7 +45,11 @@ export function TimelinePrimaryActions({ onZoomToSelection }: { onZoomToSelectio
     (item) =>
       cohortIds.includes(item.id) && tracks.find((track) => track.id === item.trackId)?.locked,
   )
-  const splitItem = selected.length === 1 ? selected[0] : undefined
+  const splitAnchorIds = linked ? getUniqueLinkedItemAnchorIds(items, selectedIds) : selectedIds
+  const splitItem =
+    splitAnchorIds.length === 1 && selected.length === selectedIds.length
+      ? selected.find((item) => item.id === splitAnchorIds[0])
+      : undefined
   const malformed =
     splitItem &&
     linked &&

From 114216714ffa59abd82bbf022d6ff1d1ac4b63fa Mon Sep 17 00:00:00 2001
From: Patrick Lu <lightning.lu7@gmail.com>
Date: Tue, 8 Sep 2026 15:14:53 -0700
Subject: [PATCH 18/22] chore(editor): prepare UX surface 0.3.14 release

---
 packages/freecut-editor/package.json               | 2 +-
 scripts/fallow-unused-class-members.allowlist.json | 5 -----
 2 files changed, 1 insertion(+), 6 deletions(-)

diff --git a/packages/freecut-editor/package.json b/packages/freecut-editor/package.json
index 41c3dbf9e..5d1a8a09f 100644
--- a/packages/freecut-editor/package.json
+++ b/packages/freecut-editor/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@quantfive/freecut-editor-surface",
-  "version": "0.3.13",
+  "version": "0.3.14",
   "description": "The host-backed FreeCut browser editor surface.",
   "license": "MIT",
   "repository": {
diff --git a/scripts/fallow-unused-class-members.allowlist.json b/scripts/fallow-unused-class-members.allowlist.json
index a7cf4d483..46946aca5 100644
--- a/scripts/fallow-unused-class-members.allowlist.json
+++ b/scripts/fallow-unused-class-members.allowlist.json
@@ -452,11 +452,6 @@
       "path": "src/runtime/player/video/VideoSourcePool.ts",
       "reason": "Audited as a live video source pool API reached through preview/export integrations.",
       "members": [
-        {
-          "parentName": "VideoSourcePool",
-          "memberName": "dispose",
-          "kind": "class_method"
-        },
         {
           "parentName": "VideoSourcePool",
           "memberName": "preloadSource",

From ee9c3a452f3a49dafaee1dcabe6d5d4223556725 Mon Sep 17 00:00:00 2001
From: Patrick Lu <lightning.lu7@gmail.com>
Date: Tue, 8 Sep 2026 15:21:24 -0700
Subject: [PATCH 19/22] fix(editor): pause source monitor before hiding
 workspace

---
 .../editor-workspace-shell.test.tsx           | 16 ++++++++-
 .../components/editor-workspace-shell.tsx     |  4 +++
 tests/browser/layout-refresh.spec.ts          | 34 +++++++++++++++++++
 3 files changed, 53 insertions(+), 1 deletion(-)

diff --git a/src/features/editor/components/editor-workspace-shell.test.tsx b/src/features/editor/components/editor-workspace-shell.test.tsx
index 8328e10ab..9b49f5708 100644
--- a/src/features/editor/components/editor-workspace-shell.test.tsx
+++ b/src/features/editor/components/editor-workspace-shell.test.tsx
@@ -2,8 +2,10 @@
 import { cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vite-plus/test'
 import { useEffect } from 'react'
-const { pause, cancel, actionMounts, actionUnmounts, selection } = vi.hoisted(() => ({
+const { pause, sourcePause, setPendingPlay, cancel, actionMounts, actionUnmounts, selection } = vi.hoisted(() => ({
   pause: vi.fn(),
+  sourcePause: vi.fn(),
+  setPendingPlay: vi.fn(),
   cancel: vi.fn(),
   actionMounts: vi.fn(),
   actionUnmounts: vi.fn(),
@@ -11,6 +13,11 @@ const { pause, cancel, actionMounts, actionUnmounts, selection } = vi.hoisted(()
 }))
 vi.mock('react-i18next', () => ({ useTranslation: () => ({ t: (key: string) => key }) }))
 vi.mock('@/shared/state/playback', () => ({ usePlaybackStore: { getState: () => ({ pause }) } }))
+vi.mock('@/shared/state/source-player', () => ({
+  useSourcePlayerStore: {
+    getState: () => ({ playerMethods: { pause: sourcePause }, setPendingPlay }),
+  },
+}))
 vi.mock('@/shared/state/selection', () => ({
   useSelectionStore: (select: (s: typeof selection) => unknown) => select(selection),
 }))
@@ -68,9 +75,16 @@ describe('editor workspace columns', () => {
       libraryVisible: false,
       editorVisible: true,
     })
+    sourcePause.mockImplementationOnce(() => {
+      expect(editor.style.display).toBe('flex')
+      expect(cancel).toHaveBeenCalledOnce()
+      expect(pause).toHaveBeenCalledOnce()
+      expect(setPendingPlay).toHaveBeenCalledWith(false)
+    })
     fireEvent.click(screen.getByRole('button', { name: 'editor.refresh.hideEditor' }))
     expect(cancel).toHaveBeenCalledOnce()
     expect(pause).toHaveBeenCalledOnce()
+    expect(sourcePause).toHaveBeenCalledOnce()
     expect(editor.style.display).toBe('none')
     expect(actionMounts).toHaveBeenCalledOnce()
     expect(actionUnmounts).not.toHaveBeenCalled()
diff --git a/src/features/editor/components/editor-workspace-shell.tsx b/src/features/editor/components/editor-workspace-shell.tsx
index e9b37bf1a..f1e05025f 100644
--- a/src/features/editor/components/editor-workspace-shell.tsx
+++ b/src/features/editor/components/editor-workspace-shell.tsx
@@ -3,6 +3,7 @@ import { useTranslation } from 'react-i18next'
 import { Settings2, X } from 'lucide-react'
 import { usePlaybackStore } from '@/shared/state/playback'
 import { useSelectionStore } from '@/shared/state/selection'
+import { useSourcePlayerStore } from '@/shared/state/source-player'
 import { MediaSidebar } from './media-sidebar'
 import { AudioMeterPanel } from './audio-meter-panel'
 import { PropertiesSidebar } from './properties-sidebar'
@@ -80,6 +81,9 @@ export function EditorWorkspaceShell({
         new CustomEvent('freecut:cancel-timeline-gesture', { bubbles: true }),
       )
       usePlaybackStore.getState().pause()
+      const sourcePlayer = useSourcePlayerStore.getState()
+      sourcePlayer.setPendingPlay(false)
+      sourcePlayer.playerMethods?.pause()
     }
     setEditorVisible(!editorVisible)
   }
diff --git a/tests/browser/layout-refresh.spec.ts b/tests/browser/layout-refresh.spec.ts
index 8e5b39337..f27ff43e3 100644
--- a/tests/browser/layout-refresh.spec.ts
+++ b/tests/browser/layout-refresh.spec.ts
@@ -140,3 +140,37 @@ test('actual Hide Editor cancels a held body move before late mouseup', async ({
   expect(state.submitCount).toBe(0)
   expect(state.snapshot.timeline.tracks[0]!.items[0]!.from).toBe(0)
 })
+
+test('hiding Editor pauses a playing source monitor without losing its frame', async ({ page }) => {
+  await page.goto('/tests/browser/layout-refresh.html')
+  await page.locator('[data-item-id]').first().waitFor()
+  await page.getByRole('button', { name: 'Media', exact: true }).click()
+  await page.getByText('generated-source-range.webm', { exact: true }).first().dblclick()
+  await page.getByRole('button', { name: 'Close source monitor', exact: true }).waitFor()
+  const sourceState = () =>
+    page.evaluate(async (modulePath) => {
+      const { useSourcePlayerStore } = await import(modulePath)
+      const state = useSourcePlayerStore.getState()
+      return { playing: state.playerMethods?.isPlaying(), frame: state.currentSourceFrame }
+    }, '/src/shared/state/source-player/store.ts')
+  const timelineState = () =>
+    page.evaluate(async (modulePath) => {
+      const { usePlaybackStore } = await import(modulePath)
+      return usePlaybackStore.getState().isPlaying
+    }, '/src/shared/state/playback/index.ts')
+  await page.getByRole('button', { name: 'Play (Space)', exact: true }).click()
+  await expect.poll(async () => (await sourceState()).playing).toBe(true)
+  await expect.poll(async () => (await sourceState()).frame).toBeGreaterThan(0)
+  expect(await timelineState()).toBe(false)
+  await page.getByRole('button', { name: 'Hide Editor', exact: true }).click()
+  await expect(page.locator('[data-editor-column="editor"]')).toBeHidden()
+  expect((await sourceState()).playing).toBe(false)
+  const pausedFrame = (await sourceState()).frame
+  // Observe beyond several real source clock ticks, not just the pause callback.
+  await page.waitForTimeout(250)
+  expect((await sourceState()).frame).toBe(pausedFrame)
+  await page.getByRole('button', { name: 'Show Editor', exact: true }).click()
+  expect((await sourceState()).frame).toBe(pausedFrame)
+  expect((await sourceState()).playing).toBe(false)
+  await expect(page.getByRole('button', { name: 'Close source monitor', exact: true })).toBeVisible()
+})

From c5ab08b77a06d90e00e8a6998b3c60f946b47c9e Mon Sep 17 00:00:00 2001
From: Patrick Lu <lightning.lu7@gmail.com>
Date: Tue, 8 Sep 2026 15:26:25 -0700
Subject: [PATCH 20/22] fix(captions): bind previews to selected occurrences

---
 .../editor/host/caption-generation.test.ts    | 20 ++++++++
 .../editor/host/caption-generation.ts         | 46 +++++++++++--------
 src/features/editor/host/caption-library.tsx  | 31 ++++++++++++-
 tests/browser/caption-refresh.spec.ts         | 35 ++++++++++++++
 tests/browser/caption-refresh.tsx             |  7 ++-
 5 files changed, 117 insertions(+), 22 deletions(-)

diff --git a/src/features/editor/host/caption-generation.test.ts b/src/features/editor/host/caption-generation.test.ts
index 5a6606826..f4786f7a4 100644
--- a/src/features/editor/host/caption-generation.test.ts
+++ b/src/features/editor/host/caption-generation.test.ts
@@ -67,6 +67,26 @@ describe('captions from the edited sequence', () => {
       { itemId: 'after-cut', startUs: 2_000_000, endUs: 3_000_000, text: 'world' },
     ])
   })
+  it('scopes individually selected linked audio before occurrence deduplication', () => {
+    const linked = {
+      ...document,
+      tracks: [
+        {
+          ...document.tracks[0]!,
+          items: [
+            { ...clip, linkedGroupId: 'linked' },
+            { ...clip, type: 'audio' as const, id: 'audio', linkedGroupId: 'linked' },
+          ],
+        },
+      ],
+    }
+    expect(captionRangesForEdit(linked, 'm', [section], new Set(['audio']))).toEqual([
+      { itemId: 'audio', startUs: 0, endUs: 1_000_000, text: 'hello' },
+    ])
+    expect(captionRangesForEdit(linked, 'm', [section])).toEqual([
+      { itemId: 'a', startUs: 0, endUs: 1_000_000, text: 'hello' },
+    ])
+  })
   it('clamps measured word boundaries to trimmed source handles for caption containment', () => {
     const trimmed = {
       ...document,
diff --git a/src/features/editor/host/caption-generation.ts b/src/features/editor/host/caption-generation.ts
index 33cbc1d3c..19eb915a6 100644
--- a/src/features/editor/host/caption-generation.ts
+++ b/src/features/editor/host/caption-generation.ts
@@ -47,26 +47,34 @@ export function captionRangesForEdit(
   const clips = new Map(
     document.tracks.flatMap((track) => track.items).map((item) => [item.id, item]),
   )
-  const words = mapHostTranscriptWords(document, assetId, sections)
-    .filter((word) => !selectedItemIds || selectedItemIds.has(word.itemId))
-    .map((word) => {
-      const clip = clips.get(word.itemId)!
-      if (clip.type !== 'video' && clip.type !== 'audio') return word
-      return {
-        ...word,
-        sourceStartUs: Math.max(
-          word.sourceStartUs,
-          framesToMicroseconds(clip.sourceStart ?? 0, document.fps),
-        ),
-        sourceEndUs: Math.min(
-          word.sourceEndUs,
-          framesToMicroseconds(
-            clip.sourceEnd ?? (clip.sourceStart ?? 0) + clip.durationInFrames * (clip.speed ?? 1),
-            document.fps,
-          ),
-        ),
+  // Scope before linked-cohort deduplication so individually selected audio retains its identity.
+  const scopedDocument = selectedItemIds
+    ? {
+        ...document,
+        tracks: document.tracks.map((track) => ({
+          ...track,
+          items: track.items.filter((item) => selectedItemIds.has(item.id)),
+        })),
       }
-    })
+    : document
+  const words = mapHostTranscriptWords(scopedDocument, assetId, sections).map((word) => {
+    const clip = clips.get(word.itemId)!
+    if (clip.type !== 'video' && clip.type !== 'audio') return word
+    return {
+      ...word,
+      sourceStartUs: Math.max(
+        word.sourceStartUs,
+        framesToMicroseconds(clip.sourceStart ?? 0, document.fps),
+      ),
+      sourceEndUs: Math.min(
+        word.sourceEndUs,
+        framesToMicroseconds(
+          clip.sourceEnd ?? (clip.sourceStart ?? 0) + clip.durationInFrames * (clip.speed ?? 1),
+          document.fps,
+        ),
+      ),
+    }
+  })
   const ranges = hostWordSelectionRanges(words)
   if (!ranges.length)
     throw new Error(
diff --git a/src/features/editor/host/caption-library.tsx b/src/features/editor/host/caption-library.tsx
index a16fbd1a4..0092e70b2 100644
--- a/src/features/editor/host/caption-library.tsx
+++ b/src/features/editor/host/caption-library.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
 import { Button } from '@/components/ui/button'
 import { useSelectionStore } from '@/shared/state/selection'
 import { usePlaybackStore } from '@/shared/state/playback'
@@ -30,8 +30,22 @@ export function HostCaptionLibrary() {
   const [message, setMessage] = useState('')
   const [error, setError] = useState(false)
   const [preview, setPreview] = useState<HostTranscriptCommandPreview | null>(null)
+  const requestGeneration = useRef(0)
   const port = host?.transcript
 
+  useEffect(() => {
+    const unsubscribe = useSelectionStore.subscribe((state, previous) => {
+      if (state.selectedItemIds !== previous.selectedItemIds) {
+        requestGeneration.current += 1
+        setPreview(null)
+      }
+    })
+    return () => {
+      requestGeneration.current += 1
+      unsubscribe()
+    }
+  }, [])
+
   useEffect(() => {
     if (!runtime) return
     const sync = () => {
@@ -50,15 +64,24 @@ export function HostCaptionLibrary() {
 
   async function prepare() {
     if (!port || !runtime || busy) return
+    const generation = ++requestGeneration.current
+    const assertCurrentRequest = () => {
+      if (generation !== requestGeneration.current)
+        throw new Error(
+          'The selection changed while captions were loading. Preview again using the current selection.',
+        )
+    }
     setBusy(true)
     setError(false)
     setPreview(null)
     setMessage('Loading the edited transcript…')
     try {
       const status = captionStatusOrThrow(await port.getStatus())
+      assertCurrentRequest()
       const snapshot = runtime.controller.getSnapshot()
       assertCaptionTargetAvailable(snapshot.timeline, replaceAll)
       const sections = await loadCaptionSections(port, status.transcriptId)
+      assertCurrentRequest()
       const ranges = captionRangesForEdit(
         snapshot.timeline,
         status.assetId,
@@ -84,6 +107,7 @@ export function HostCaptionLibrary() {
         request,
         snapshot.timeline.timelineId,
       )
+      assertCurrentRequest()
       if (runtime.controller.getSnapshot().timeline.revision !== snapshot.timeline.revision)
         throw new Error(
           'The edit changed while captions were loading. Preview again using the latest edit.',
@@ -150,7 +174,10 @@ export function HostCaptionLibrary() {
           <select
             className="mt-1 h-9 w-full rounded-md border border-input bg-background px-2"
             value={scope}
-            onChange={(event) => setScope(event.target.value)}
+            onChange={(event) => {
+              requestGeneration.current += 1
+              setScope(event.target.value)
+            }}
             disabled={busy}
           >
             <option value="edit">This edit</option>
diff --git a/tests/browser/caption-refresh.spec.ts b/tests/browser/caption-refresh.spec.ts
index d45a824b6..54eee748d 100644
--- a/tests/browser/caption-refresh.spec.ts
+++ b/tests/browser/caption-refresh.spec.ts
@@ -181,3 +181,38 @@ test('selected occurrence captions undo in one transaction', async ({ page }) =>
     ),
   ).toBe(3)
 })
+
+for (const returnToFirst of [false, true]) {
+  test(`pending selected caption preview rejects A→B${returnToFirst ? '→A' : ''}`, async ({
+    page,
+  }) => {
+    await page.goto('/tests/browser/caption-refresh.html?scenario=deferred')
+    const first = page.locator('[data-item-id="first"][role="button"]')
+    const second = page.locator('[data-item-id="after-cut"][role="button"]')
+    await first.click()
+    await page.getByRole('combobox', { name: 'More library tools' }).selectOption('captions')
+    await page.getByLabel('Caption scope').selectOption('selected')
+    await page.getByRole('button', { name: 'Preview captions', exact: true }).click()
+    await expect
+      .poll(() => page.evaluate(() => (window as any).captionFixture.requests.length))
+      .toBe(1)
+    await second.click()
+    if (returnToFirst) await first.click()
+    await page.evaluate(() => (window as any).captionFixture.resolvePreview())
+    await expect(page.getByRole('alert')).toContainText('selection changed')
+    await expect(page.getByRole('button', { name: 'Apply captions', exact: true })).toHaveCount(0)
+    expect(await page.evaluate(() => (window as any).captionFixture.applies)).toBe(0)
+    await page.getByRole('button', { name: 'Preview captions', exact: true }).click()
+    await expect
+      .poll(() => page.evaluate(() => (window as any).captionFixture.requests.length))
+      .toBe(2)
+    expect(
+      await page.evaluate(() =>
+        (window as any).captionFixture.requests[1].ranges.map((range: any) => range.itemId),
+      ),
+    ).toEqual([returnToFirst ? 'first' : 'after-cut'])
+    await page.evaluate(() => (window as any).captionFixture.resolvePreview())
+    await page.getByRole('button', { name: 'Apply captions', exact: true }).click()
+    expect(await page.evaluate(() => (window as any).captionFixture.applies)).toBe(1)
+  })
+}
diff --git a/tests/browser/caption-refresh.tsx b/tests/browser/caption-refresh.tsx
index 6f2a3eea4..6d24beabb 100644
--- a/tests/browser/caption-refresh.tsx
+++ b/tests/browser/caption-refresh.tsx
@@ -80,6 +80,7 @@ const listeners = new Set<(value: EmbeddedEditorSnapshot) => void>()
 const history: EmbeddedEditorSnapshot[] = []
 const fixtureState = {
   applies: 0,
+  resolvePreview: () => {},
   undo: () => host.history!.undo(),
   requests: [] as unknown[],
   native: () => hostSnapshotToNativeTimeline(snapshot),
@@ -156,9 +157,13 @@ const host: EditorHost = {
         },
       ],
     }),
-    previewCommands: (request) => {
+    previewCommands: async (request) => {
       if (scenario === 'error') throw new Error('Fixture preview unavailable. Retry preview.')
       fixtureState.requests.push(request)
+      if (scenario === 'deferred')
+        await new Promise<void>((resolve) => {
+          fixtureState.resolvePreview = resolve
+        })
       const trackId = request.captionTrackId!
       const existing = snapshot.timeline.tracks.find((track) => track.id === trackId)
       const cues = request.ranges!.map((range, index) => {

From 802dbd7b147e4dddc673cb299657f3c2eb02eae7 Mon Sep 17 00:00:00 2001
From: Patrick Lu <lightning.lu7@gmail.com>
Date: Tue, 8 Sep 2026 15:27:20 -0700
Subject: [PATCH 21/22] fix(transcript): fence occurrence cuts and stale page
 responses

---
 .../editor/host/transcript-editor.test.tsx    | 119 ++++++++++++++++++
 .../editor/host/transcript-editor.tsx         |  25 ++--
 .../actions/edit/range-removal-actions.ts     |  55 ++++++--
 .../actions/range-removal-actions.test.ts     |  70 +++++++++++
 4 files changed, 249 insertions(+), 20 deletions(-)

diff --git a/src/features/editor/host/transcript-editor.test.tsx b/src/features/editor/host/transcript-editor.test.tsx
index de406a34b..5d870535a 100644
--- a/src/features/editor/host/transcript-editor.test.tsx
+++ b/src/features/editor/host/transcript-editor.test.tsx
@@ -32,6 +32,7 @@ import {
   type HostTranscriptCommandPreview,
   type HostTranscriptCommandPreviewRequest,
   type HostTranscriptSection,
+  type HostTranscriptSectionsPage,
   type HostTranscriptStatusReceipt,
 } from './contract'
 import { EmbeddedEditorHostRuntime } from './runtime'
@@ -326,6 +327,16 @@ function renderHostEditor(harness: ReturnType<typeof createHarness>) {
   )
 }
 
+function deferredPage() {
+  let resolve!: (page: HostTranscriptSectionsPage) => void
+  let reject!: (error: Error) => void
+  const promise = new Promise<HostTranscriptSectionsPage>((resolvePage, rejectPage) => {
+    resolve = resolvePage
+    reject = rejectPage
+  })
+  return { promise, resolve, reject }
+}
+
 function receipt(
   status: HostTranscriptStatusReceipt['status'],
   overrides: Partial<HostTranscriptStatusReceipt> = {},
@@ -517,6 +528,114 @@ describe('host-backed transcript consumer', () => {
     expect(screen.getAllByRole('button', { name: 'Y' })).toHaveLength(2)
   })
 
+  it.each(['resolve', 'reject'] as const)(
+    'ignores an old transcript page that %ss after refresh while the new source is loading more',
+    async (outcome) => {
+      const initial = snapshot()
+      initial.timeline.durationInFrames = 600
+      initial.timeline.media = ['asset-1', 'asset-2'].map((id) => ({
+        media_id: id,
+        media_kind: 'video',
+        content_hash: `sha256:${id}`,
+        duration_us: 10_000_000,
+        availability: { mode: 'cloud', cloud: { object_id: id } },
+      }))
+      initial.timeline.tracks = [
+        {
+          id: 'video',
+          name: 'Video',
+          kind: 'video',
+          locked: false,
+          muted: false,
+          items: ['asset-1', 'asset-2'].map((id, index) => ({
+            type: 'video',
+            id: `clip-${id}`,
+            trackId: 'video',
+            mediaId: id,
+            from: index * 300,
+            durationInFrames: 300,
+            sourceStart: 0,
+            sourceEnd: 300,
+          })),
+        },
+      ]
+      const harness = createHarness(initial)
+      harness.host.transcript!.occurrenceSelection = true
+      let fresh = false
+      harness.host.transcript!.getStatus = () =>
+        receipt(
+          'succeeded',
+          fresh
+            ? {
+                transcriptId: 'transcript-2',
+                assetId: 'asset-2',
+                sourceAssetHash: 'sha256:asset-2',
+              }
+            : {},
+        )
+      const oldPage = deferredPage()
+      const newPage = deferredPage()
+      const page = (
+        transcriptId: string,
+        text: string,
+        ordinal: number,
+      ): HostTranscriptSectionsPage => ({
+        transcriptId,
+        hasMore: ordinal === 0,
+        nextCursor: ordinal === 0 ? 'next' : null,
+        sections: [
+          {
+            id: `${transcriptId}-${ordinal}`,
+            transcriptId,
+            ordinal,
+            startUs: ordinal * 2_000_000,
+            endUs: ordinal * 2_000_000 + 1_000_000,
+            text,
+            timingSource: 'provider',
+            words: [{ text, startUs: ordinal * 2_000_000, endUs: ordinal * 2_000_000 + 1_000_000 }],
+          },
+        ],
+      })
+      const getSections = vi.fn(
+        ({ transcriptId, cursor }: { transcriptId: string; cursor?: string | null }) => {
+          if (cursor) return transcriptId === 'transcript-1' ? oldPage.promise : newPage.promise
+          return page(transcriptId, transcriptId === 'transcript-1' ? 'Original' : 'Fresh', 0)
+        },
+      )
+      harness.host.transcript!.getSections = getSections
+      renderHostEditor(harness)
+      await screen.findByRole('button', { name: 'Original' })
+      fireEvent.click(screen.getByRole('button', { name: 'Load more transcript' }))
+      expect(getSections).toHaveBeenCalledWith(
+        expect.objectContaining({ transcriptId: 'transcript-1', cursor: 'next' }),
+      )
+      fresh = true
+      fireEvent.click(screen.getByRole('button', { name: 'Refresh transcript' }))
+      await screen.findByRole('button', { name: 'Fresh' })
+      expect(screen.queryByRole('button', { name: 'Original' })).not.toBeInTheDocument()
+      fireEvent.click(screen.getByRole('button', { name: 'Load more transcript' }))
+      expect(getSections).toHaveBeenCalledWith(
+        expect.objectContaining({ transcriptId: 'transcript-2', cursor: 'next' }),
+      )
+      await act(async () => {
+        if (outcome === 'resolve') oldPage.resolve(page('transcript-1', 'Forbidden', 1))
+        else oldPage.reject(new Error('Obsolete source page failed'))
+        await Promise.resolve()
+      })
+      expect(screen.queryByRole('button', { name: 'Forbidden' })).not.toBeInTheDocument()
+      expect(screen.queryByTestId('host-transcript-error')).not.toBeInTheDocument()
+      expect(screen.getByRole('button', { name: 'Load more transcript' })).toBeDisabled()
+      await act(async () => {
+        newPage.resolve(page('transcript-2', 'Latest', 1))
+      })
+      await screen.findByRole('button', { name: 'Latest' })
+      expect(screen.queryByRole('button', { name: 'Load more transcript' })).not.toBeInTheDocument()
+      expect(screen.queryByRole('button', { name: 'Forbidden' })).not.toBeInTheDocument()
+      expect(harness.previewCommands).not.toHaveBeenCalled()
+      expect(harness.submitEdit).not.toHaveBeenCalled()
+    },
+  )
+
   it('displays bounded sections, previews without mutation, then applies through submitEdit', async () => {
     const harness = createHarness(snapshot())
     renderHostEditor(harness)
diff --git a/src/features/editor/host/transcript-editor.tsx b/src/features/editor/host/transcript-editor.tsx
index 4f134f1c8..02d9d1c94 100644
--- a/src/features/editor/host/transcript-editor.tsx
+++ b/src/features/editor/host/transcript-editor.tsx
@@ -589,14 +589,14 @@ export function HostTranscriptEditor({ active = true }: { active?: boolean }) {
       replace: boolean,
     ): Promise<void> => {
       if (!port) return
-      const page = normalizePage(
-        await port.getSections({
-          transcriptId: receipt.transcriptId,
-          cursor,
-          limit: MAX_TRANSCRIPT_SECTION_PAGE_SIZE,
-        }),
-        receipt.transcriptId,
-      )
+      const generation = requestGeneration.current
+      const response = await port.getSections({
+        transcriptId: receipt.transcriptId,
+        cursor,
+        limit: MAX_TRANSCRIPT_SECTION_PAGE_SIZE,
+      })
+      if (requestGeneration.current !== generation) return
+      const page = normalizePage(response, receipt.transcriptId)
       const durationUs = receipt.durationUs
       if (
         (durationUs !== null && page.sections.some((section) => section.endUs > durationUs)) ||
@@ -607,6 +607,7 @@ export function HostTranscriptEditor({ active = true }: { active?: boolean }) {
         throw new Error('The host returned transcript sections outside the bounded transcript.')
       }
       setSections((current) => {
+        if (requestGeneration.current !== generation) return current
         const next = replace ? [] : [...current]
         const ids = new Set(next.map((section) => section.id))
         for (const section of page.sections) {
@@ -628,6 +629,7 @@ export function HostTranscriptEditor({ active = true }: { active?: boolean }) {
     const generation = requestGeneration.current + 1
     requestGeneration.current = generation
     setLoading(true)
+    setLoadingMore(false)
     setError(null)
     setPreview(null)
     setSelectedIds(new Set())
@@ -673,17 +675,22 @@ export function HostTranscriptEditor({ active = true }: { active?: boolean }) {
   useEffect(() => {
     if (!active || !port || !canTranscribe) return
     void refresh()
+    return () => {
+      requestGeneration.current += 1
+    }
   }, [active, canTranscribe, port, refresh])
 
   const loadMore = useCallback(async () => {
     if (!status || status.status !== 'succeeded' || !nextCursor || !port || loadingMore) return
+    const generation = requestGeneration.current
     setLoadingMore(true)
     try {
       await loadSectionsPage(status, nextCursor, false)
     } catch (caught) {
+      if (requestGeneration.current !== generation) return
       setError(errorFromHost(caught, 'More transcript sections could not be loaded.'))
     } finally {
-      setLoadingMore(false)
+      if (requestGeneration.current === generation) setLoadingMore(false)
     }
   }, [loadSectionsPage, loadingMore, nextCursor, port, status])
 
diff --git a/src/features/timeline/stores/actions/edit/range-removal-actions.ts b/src/features/timeline/stores/actions/edit/range-removal-actions.ts
index 5d59755dc..ef87d86dc 100644
--- a/src/features/timeline/stores/actions/edit/range-removal-actions.ts
+++ b/src/features/timeline/stores/actions/edit/range-removal-actions.ts
@@ -371,12 +371,37 @@ function assertTranscriptSplitOutsideTransition(item: TimelineItem, frame: numbe
   }
 }
 
+function transcriptOccurrenceTiming(item: TimelineItem, fps: number) {
+  const span = getItemSourceSpanSeconds(item, fps)
+  return [
+    item.mediaId,
+    item.from,
+    item.durationInFrames,
+    item.speed ?? 1,
+    !!item.isReversed,
+    span?.start,
+    span?.end,
+  ] as const
+}
+
+function assertTranscriptLinkedCohort(anchor: TimelineItem, linkedItems: TimelineItem[]): void {
+  const fps = useTimelineSettingsStore.getState().fps
+  const anchorTiming = transcriptOccurrenceTiming(anchor, fps)
+  const synchronized = linkedItems.every((item) =>
+    transcriptOccurrenceTiming(item, fps).every((value, index) => value === anchorTiming[index]),
+  )
+  if (!synchronized) {
+    throw new Error('Linked clips have different trims or timing. Align them before cutting words.')
+  }
+}
+
 function assertTranscriptRangesRepresentable(
   anchor: TimelineItem,
   ranges: RemoveSilenceRange[],
 ): void {
   const fps = useTimelineSettingsStore.getState().fps
   const linkedItems = getLinkedItemsForEdit(useItemsStore.getState().items, anchor.id, true)
+  assertTranscriptLinkedCohort(anchor, linkedItems)
   for (const range of ranges) {
     const start = Math.max(anchor.from, sourceSecondsToTimelineFrame(anchor, range.start, fps))
     const end = Math.min(
@@ -442,8 +467,11 @@ function removeTimelineRangesFromItems(
         id: item.id,
         mediaId: item.mediaId!,
         originId: item.originId ?? item.id,
-        from: item.from,
-        to: item.from + item.durationInFrames,
+        // Only these actual IDs and their split descendants belong to this selection.
+        // Shared originId/time bounds can also describe an independent stacked repeat.
+        descendantIds: new Set(
+          getLinkedItemsForEdit(initialItems, item.id, !!rangesByItemId).map((linked) => linked.id),
+        ),
       }))
 
       let splitCount = 0
@@ -503,6 +531,14 @@ function removeTimelineRangesFromItems(
 
           if (frameSplitResults.length !== itemsToSplit.length) continue
 
+          for (const descriptor of anchorDescriptors) {
+            for (const entry of frameSplitResults) {
+              if (descriptor.descendantIds.has(entry.originalId)) {
+                descriptor.descendantIds.add(entry.result.leftItem.id)
+                descriptor.descendantIds.add(entry.result.rightItem.id)
+              }
+            }
+          }
           applySplitBookkeeping(frameSplitResults)
           splitCount += 1
 
@@ -524,15 +560,12 @@ function removeTimelineRangesFromItems(
 
         for (const candidate of currentItems) {
           if (candidate.type !== 'video' && candidate.type !== 'audio') continue
-          if (candidate.mediaId !== descriptor.mediaId) continue
-          if ((candidate.originId ?? candidate.id) !== descriptor.originId) continue
-
-          if (
-            rangesByItemId &&
-            (candidate.from < descriptor.from ||
-              candidate.from + candidate.durationInFrames > descriptor.to)
-          )
-            continue
+          if (rangesByItemId) {
+            if (!descriptor.descendantIds.has(candidate.id)) continue
+          } else {
+            if (candidate.mediaId !== descriptor.mediaId) continue
+            if ((candidate.originId ?? candidate.id) !== descriptor.originId) continue
+          }
 
           const span = getItemSourceSpanSeconds(candidate, timelineFps)
           if (span !== null && isMostlyInsideRanges(span, ranges)) {
diff --git a/src/features/timeline/stores/actions/range-removal-actions.test.ts b/src/features/timeline/stores/actions/range-removal-actions.test.ts
index 710e24cd2..ff29e3a0f 100644
--- a/src/features/timeline/stores/actions/range-removal-actions.test.ts
+++ b/src/features/timeline/stores/actions/range-removal-actions.test.ts
@@ -2,6 +2,7 @@
 
 import { beforeEach, describe, expect, it } from 'vite-plus/test'
 import type { AudioItem, VideoItem } from '@/types/timeline'
+import { makeTimelineTrack } from '../../test-helpers'
 import { useEditorStore } from '@/shared/state/editor'
 import { useSelectionStore } from '@/shared/state/selection'
 import { useKeyframesStore } from '../keyframes-store'
@@ -184,4 +185,73 @@ describe('removeSilenceFromItems', () => {
       { from: 420, durationInFrames: 90, sourceStart: 210, sourceEnd: 300 },
     ])
   })
+  it('preserves an unselected stacked repeat with shared origin inside the selected range', () => {
+    useItemsStore
+      .getState()
+      .setTracks([
+        makeTimelineTrack({ id: 'video-track', name: 'A', order: 0, syncLock: false }),
+        makeTimelineTrack({ id: 'repeat-track', name: 'B', order: 1, syncLock: false }),
+      ])
+    const repeat = makeVideoItem({
+      id: 'repeat',
+      trackId: 'repeat-track',
+      from: 60,
+      durationInFrames: 60,
+      sourceStart: 60,
+      sourceEnd: 120,
+    })
+    const original = [makeVideoItem(), repeat]
+    useItemsStore.getState().setItems(original)
+    const result = removeTranscriptRangesFromItems(
+      ['video-1'],
+      { 'media-1': [{ start: 2, end: 4 }] },
+      { 'video-1': [{ start: 2, end: 4 }] },
+    )
+    expect(result.removedItemCount).toBe(1)
+    expect(useItemsStore.getState().itemById.repeat).toEqual(repeat)
+    expect(
+      useItemsStore
+        .getState()
+        .items.filter((item) => item.trackId === 'video-track')
+        .map(({ from, durationInFrames, sourceStart, sourceEnd }) => ({
+          from,
+          durationInFrames,
+          sourceStart,
+          sourceEnd,
+        })),
+    ).toEqual([
+      { from: 0, durationInFrames: 60, sourceStart: 0, sourceEnd: 60 },
+      { from: 60, durationInFrames: 180, sourceStart: 120, sourceEnd: 300 },
+    ])
+    expect(useTimelineCommandStore.getState().undoStack).toHaveLength(1)
+    useTimelineCommandStore.getState().undo()
+    expect(useItemsStore.getState().items).toEqual(original)
+    useTimelineCommandStore.getState().redo()
+    expect(useItemsStore.getState().itemById.repeat).toEqual(repeat)
+  })
+
+  it.each([
+    { label: 'asymmetric duration', audio: { durationInFrames: 300, sourceEnd: 300 } },
+    { label: 'different source offset', audio: { sourceStart: 60, sourceEnd: 90 } },
+    { label: 'reversed partner', audio: { isReversed: true } },
+  ])('rejects $label before a word cut mutates linked footage or history', ({ audio }) => {
+    useEditorStore.setState({ linkedSelectionEnabled: false })
+    const original = [
+      makeVideoItem({ linkedGroupId: 'av', durationInFrames: 30, sourceEnd: 30 }),
+      makeAudioItem({ linkedGroupId: 'av', durationInFrames: 30, sourceEnd: 30, ...audio }),
+    ]
+    useItemsStore.getState().setItems(original)
+    expect(() =>
+      removeTranscriptRangesFromItems(
+        ['video-1'],
+        { 'media-1': [{ start: 0, end: 1 }] },
+        { 'video-1': [{ start: 0, end: 1 }] },
+      ),
+    ).toThrow('Linked clips have different trims or timing')
+    expect(useItemsStore.getState().items).toEqual(original)
+    expect(useTimelineCommandStore.getState().undoStack).toHaveLength(0)
+    expect(useTimelineSettingsStore.getState().isDirty).toBe(false)
+    expect(useTransitionsStore.getState().transitions).toEqual([])
+    expect(useKeyframesStore.getState().keyframes).toEqual([])
+  })
 })

From e964e3345ba6a001aad1d66f9fcdca69242b8baa Mon Sep 17 00:00:00 2001
From: Patrick Lu <lightning.lu7@gmail.com>
Date: Tue, 8 Sep 2026 15:33:09 -0700
Subject: [PATCH 22/22] fix(timeline): preserve voiceover when advanced tools
 close

---
 .../timeline-header-recording.test.tsx        | 103 ++++++++++++++++++
 .../components/timeline-header.test.tsx       |   3 +-
 .../timeline/components/timeline-header.tsx   |  11 +-
 3 files changed, 110 insertions(+), 7 deletions(-)
 create mode 100644 src/features/timeline/components/timeline-header-recording.test.tsx

diff --git a/src/features/timeline/components/timeline-header-recording.test.tsx b/src/features/timeline/components/timeline-header-recording.test.tsx
new file mode 100644
index 000000000..28486b7d4
--- /dev/null
+++ b/src/features/timeline/components/timeline-header-recording.test.tsx
@@ -0,0 +1,103 @@
+import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vite-plus/test'
+import { useEditorStore } from '@/shared/state/editor'
+import { useMicRecordingStore } from '@/shared/state/mic-recording-store'
+import { usePlaybackStore } from '@/shared/state/playback'
+import { useMediaLibraryStore } from '../deps/media-library-store'
+import { useItemsStore } from '../stores/items-store'
+import { useTimelineSettingsStore } from '../stores/timeline-settings-store'
+import { TimelineHeader } from './timeline-header'
+
+const capture = vi.hoisted(() => ({
+  start: vi.fn(),
+  stop: vi.fn(),
+  dispose: vi.fn(),
+  importAudio: vi.fn(),
+}))
+vi.mock('@/infrastructure/audio/mic-recorder', () => ({
+  MicRecorder: class {
+    start = capture.start
+    stop = capture.stop
+    dispose = capture.dispose
+    elapsedMs = () => 1000
+  },
+  hasMicRecordingSupport: () => true,
+  enumerateAudioInputs: async () => [],
+  extensionForMimeType: () => 'webm',
+  startMicLevelMonitor: vi.fn(),
+}))
+vi.mock('../deps/media-library-service', () => ({
+  importMediaLibraryService: async () => ({
+    mediaLibraryService: { importRecordedAudio: capture.importAudio },
+  }),
+}))
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  useEditorStore.setState({ hostMode: false })
+  useMicRecordingStore.getState().reset()
+  useMediaLibraryStore.setState({ currentProjectId: 'recording-project' })
+  useItemsStore.getState().setItems([])
+  useItemsStore.getState().setTracks([])
+  useTimelineSettingsStore.setState({ fps: 30 })
+  usePlaybackStore.setState({ isPlaying: false, currentFrame: 15 })
+  capture.start.mockResolvedValue(undefined)
+  capture.stop.mockResolvedValue({
+    blob: new Blob(['same-take']),
+    mimeType: 'audio/webm',
+    durationMs: 1000,
+  })
+  capture.importAudio.mockResolvedValue({
+    id: 'saved-take',
+    duration: 1,
+    type: 'audio',
+    fileName: 'take.webm',
+  })
+})
+afterEach(() => {
+  cleanup()
+  useMicRecordingStore.getState().reset()
+})
+
+describe('timeline voiceover owner', () => {
+  it('preserves the take across More dismissal/reopening, then saves that same recorder', async () => {
+    render(<TimelineHeader />)
+    const more = screen.getByRole('button', { name: 'More timeline tools' })
+    fireEvent.click(more)
+    await screen.findByRole('dialog')
+    fireEvent.click(screen.getByRole('button', { name: 'Record voiceover' }))
+    await waitFor(() => expect(useMicRecordingStore.getState().status).toBe('recording'))
+    fireEvent.keyDown(screen.getByRole('dialog'), { key: 'Escape' })
+    await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument())
+    expect(useMicRecordingStore.getState().status).toBe('recording')
+    expect(capture.dispose).not.toHaveBeenCalled()
+    expect(screen.getByRole('button', { name: 'Stop and save' })).toBeVisible()
+    fireEvent.click(more)
+    await screen.findByRole('dialog')
+    fireEvent.click(more)
+    await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument())
+    expect(useMicRecordingStore.getState().status).toBe('recording')
+    await act(async () => fireEvent.click(screen.getByRole('button', { name: 'Stop and save' })))
+    await waitFor(() => expect(useMicRecordingStore.getState().status).toBe('idle'))
+    expect(capture.start).toHaveBeenCalledTimes(1)
+    expect(capture.stop).toHaveBeenCalledTimes(1)
+    expect(capture.dispose).not.toHaveBeenCalled()
+    expect(capture.importAudio).toHaveBeenCalledTimes(1)
+    expect(useItemsStore.getState().items).toEqual([
+      expect.objectContaining({ mediaId: 'saved-take', from: 15, durationInFrames: 30 }),
+    ])
+  })
+
+  it('disposes an active take on actual editor header unmount without saving', async () => {
+    const view = render(<TimelineHeader />)
+    fireEvent.click(screen.getByRole('button', { name: 'More timeline tools' }))
+    fireEvent.click(screen.getByRole('button', { name: 'Record voiceover' }))
+    await waitFor(() => expect(useMicRecordingStore.getState().status).toBe('recording'))
+    view.unmount()
+    expect(capture.dispose).toHaveBeenCalledTimes(1)
+    expect(capture.stop).not.toHaveBeenCalled()
+    expect(capture.importAudio).not.toHaveBeenCalled()
+    expect(useMicRecordingStore.getState().status).toBe('idle')
+    expect(usePlaybackStore.getState().isPlaying).toBe(false)
+  })
+})
diff --git a/src/features/timeline/components/timeline-header.test.tsx b/src/features/timeline/components/timeline-header.test.tsx
index b5324547e..3366c9da4 100644
--- a/src/features/timeline/components/timeline-header.test.tsx
+++ b/src/features/timeline/components/timeline-header.test.tsx
@@ -108,7 +108,8 @@ describe('TimelineHeader zoom slider', () => {
     const targetZoom = ZOOM_MIN * Math.pow(ZOOM_MAX / ZOOM_MIN, 0.75)
 
     render(<TimelineHeader onZoomChange={onZoomChange} />)
-    expect(micRenderSpy).not.toHaveBeenCalled()
+    expect(micRenderSpy).toHaveBeenCalledTimes(1)
+    micRenderSpy.mockClear()
 
     fireEvent.mouseDown(screen.getByRole('slider'))
 
diff --git a/src/features/timeline/components/timeline-header.tsx b/src/features/timeline/components/timeline-header.tsx
index 2e6e53331..0ab1fcfbc 100644
--- a/src/features/timeline/components/timeline-header.tsx
+++ b/src/features/timeline/components/timeline-header.tsx
@@ -545,7 +545,11 @@ export const TimelineHeader = memo(function TimelineHeader({
       role="toolbar"
       aria-label={t('timeline.header.controls')}
     >
-      <TimelinePrimaryActions onZoomToSelection={onZoomToSelection} />
+      <div className="flex items-center gap-1">
+        <TimelinePrimaryActions onZoomToSelection={onZoomToSelection} />
+        {/* The recorder owns the live take: menu dismissal must not unmount it. */}
+        {!hostMode && <MicRecordControl />}
+      </div>
 
       <Popover>
         <PopoverTrigger asChild>
@@ -827,11 +831,6 @@ export const TimelineHeader = memo(function TimelineHeader({
 
             <Separator orientation="vertical" className="h-5 mx-1.5" />
 
-            {/* Microphone voiceover */}
-            {!hostMode && <MicRecordControl />}
-
-            <Separator orientation="vertical" className="h-5 mx-1.5" />
-
             {/* Snap Toggle */}
             <Button
               variant="ghost"