@bycrux/editor 1.2.2 → 1.4.0

package/src/video/VideoEditor.tsx

@@ -1,5 +1,5 @@
 import { Fragment, useCallback, useEffect, useMemo, useRef, useState, type MutableRefObject } from 'react'
-import { Captions, Crop, Ear, EarOff, Film, HelpCircle, History, Magnet, Maximize2, Minimize2, Redo2, SeparatorVertical, Smartphone, SquareDashedMousePointer, Undo2, Wand2 } from 'lucide-react'
+import { AlertCircle, Captions, Crop, Ear, EarOff, Film, HelpCircle, History, Magnet, Maximize2, Minimize2, Redo2, SeparatorVertical, Smartphone, SquareDashedMousePointer, Undo2, Wand2 } from 'lucide-react'
 import type { Project, VideoEditorProps } from '../types'
 import type { AudioTrack, VisualItem } from '../schema'
 import { useProjectSync, type UseProjectSync } from '../state/use-project-sync'
@@ -212,6 +212,11 @@ export function exportDurationSec(project: { tracks?: unknown }): number {
  * prop, so a status transition (agent finishes → 'draft') must come from the
  * core's own stream, not the host re-rendering with a new prop.
  *
+ * `pendingSurface="host"` skips the pending surface: a pending project renders
+ * the review surface (which never branches on status), and the host draws its
+ * own gate over it. `onUserEdit` reports the user's own edits (never SSE frames)
+ * so such a host can react when the user edits while an agent is working.
+ *
  * ProjectHeader is lifted out (the host renders it in its shell). This component
  * renders: timeline + preview + version panel + render modal + the host-supplied
  * inspector/subcut render-prop seams + an optional back-to-setup affordance.
@@ -223,6 +228,8 @@ export default function VideoEditor<P extends Project = Project>({
   theme,
   slots,
   onBackToSetup,
+  pendingSurface = 'default',
+  onUserEdit,
   assetsPlacement = 'right',
   renderProgressView = 'phases',
   renderGenerationPanel,
@@ -245,7 +252,9 @@ export default function VideoEditor<P extends Project = Project>({
   // both the surface switch and the surface contents. `project` (the prop) is
   // only the initial value — after mount the core owns state and reconciles live
   // frames itself (video-shaped → default plain-replace reconcile).
-  const sync = useProjectSync<P>(adapter, project.id, project)
+  // `onUserEdit` rides the core's `onLocalEdit` (held in a ref there, so a new
+  // identity per render is harmless): fired for user edits only, never SSE.
+  const sync = useProjectSync<P>(adapter, project.id, project, { onLocalEdit: onUserEdit })
 
   // Set for the duration of a caption drag gesture (ReviewSurface's
   // `handleProjectChange` → `commitTimelineEdit`), read by the lane-
@@ -375,9 +384,9 @@ export default function VideoEditor<P extends Project = Project>({
   // T7 — canvas-timeline filmstrips + hover-scrub; absent → Timeline renders none (graceful).
   const getFilmstrip      = adapter.getFilmstrip
 
-  if (isPending) {
+  if (isPending && pendingSurface !== 'host') {
     return (
-      <div ref={containerRef} className="flex flex-col h-full bg-[var(--editor-bg)]">
+      <div ref={containerRef} className="flex flex-col h-full bg-[var(--editor-bg)] text-[var(--editor-text)]">
         <PendingSurface
           sync={sync}
           adapter={adapter}
@@ -394,7 +403,7 @@ export default function VideoEditor<P extends Project = Project>({
   }
 
   return (
-    <div ref={containerRef} className="flex flex-col h-full bg-[var(--editor-bg)]">
+    <div ref={containerRef} className="flex flex-col h-full bg-[var(--editor-bg)] text-[var(--editor-text)]">
       <ReviewSurface
         sync={sync}
         captionGestureRef={captionGestureRef}
@@ -629,10 +638,10 @@ function PendingSurface<P extends Project>({
                 <>
                   <div className="flex flex-col items-center gap-2">
                     <p className="text-[var(--editor-text)] text-lg font-semibold">Message your agent to start</p>
-                    <p className="text-[var(--editor-text)]/60 text-sm">Nothing will happen automatically. Copy this and send it to your agent.</p>
+                    <p className="text-[color-mix(in_srgb,var(--editor-text)_60%,transparent)] text-sm">Nothing will happen automatically. Copy this and send it to your agent.</p>
                   </div>
                   {skillPath && (
-                    <div className="w-full rounded-xl border-2 border-[var(--editor-accent)]/50 bg-[var(--editor-surface)] p-5 flex flex-col gap-3 text-left shadow-lg shadow-[var(--editor-accent)]/10">
+                    <div className="w-full rounded-xl border-2 border-[color-mix(in_srgb,var(--editor-accent)_50%,transparent)] bg-[var(--editor-surface)] p-5 flex flex-col gap-3 text-left shadow-lg shadow-[color-mix(in_srgb,var(--editor-accent)_10%,transparent)]">
                       {/* indigo-600 in light mode: the accent (indigo-500) is ~4.06:1 on
                           `--editor-surface`, and 12px bold is still NORMAL text under WCAG
                           (large starts at 18.66px bold), so it needs the 4.5:1 floor. The
@@ -835,6 +844,9 @@ function ReviewSurface<P extends Project>({
   // one caption id in `selectedIds` — taking the first is correct, the
   // preview only ever shows one box.
   const selectedCaptionId = selectedIds.find(id => captionIdSet.has(id)) ?? null
+  // Transport state for the context report. PreviewPlayer pushes it on a real
+  // play/pause change only, so this re-renders the surface per toggle, never per frame.
+  const [previewPlaying, setPreviewPlaying] = useState(false)
   // Publish what we are looking at, so an agent can resolve "this section".
   // No-ops entirely on a host that does not implement reportContext.
   useReportContext({
@@ -843,6 +855,7 @@ function ReviewSurface<P extends Project>({
     clock,
     selectedIds,
     selectedCaptionId,
+    playing: previewPlaying,
   })
   // Selecting a caption anywhere (timeline, preview box, or the caption list —
   // all funnel through `selectedIds` → `selectedCaptionId`) jumps the left
@@ -2106,6 +2119,7 @@ function ReviewSurface<P extends Project>({
                 onCaptionSegmentChange={handleCaptionSegmentChange}
                 engine={engine}
                 transportRef={transportRef}
+                onPlayingChange={setPreviewPlaying}
                 scrubHandleRef={scrubHandleRef}
                 hoverScrub={hoverScrub}
                 // Social-media preview chrome (mirrors CapCut's "Preview your
@@ -2133,7 +2147,7 @@ function ReviewSurface<P extends Project>({
           <div className="shrink-0 flex items-center gap-1.5 px-3 py-1 border-t border-[var(--editor-border)] bg-[var(--editor-surface)]">
             <span
               data-testid="preview-timecode"
-              className="mr-auto text-[10px] font-mono tabular-nums text-[var(--editor-text)]/60 select-none"
+              className="mr-auto text-[10px] font-mono tabular-nums text-[color-mix(in_srgb,var(--editor-text)_60%,transparent)] select-none"
             >
               {/* The playhead can sit past `previewDuration` while parked in
                   `getTotalDuration()`'s ~20% trailing headroom (drag room for
@@ -2155,7 +2169,7 @@ function ReviewSurface<P extends Project>({
                 className={`flex items-center justify-center w-5 h-5 rounded transition-colors ${
                   currentSocialPreview !== null
                     ? (timelineMode === 'light' ? 'text-sky-600 bg-sky-400/15 hover:bg-sky-400/25' : 'text-sky-400 bg-sky-400/15 hover:bg-sky-400/25')
-                    : 'text-[var(--editor-text)]/60 bg-transparent hover:text-[var(--editor-text)]'
+                    : 'text-[color-mix(in_srgb,var(--editor-text)_60%,transparent)] bg-transparent hover:text-[var(--editor-text)]'
                 }`}
               >
                 {/* Trigger reflects the active selection: the platform's own
@@ -2180,7 +2194,7 @@ function ReviewSurface<P extends Project>({
                 onClick={toggleFullscreen}
                 aria-label="Toggle fullscreen"
                 aria-pressed={isFullscreen}
-                className="flex items-center justify-center w-5 h-5 rounded transition-colors text-[var(--editor-text)]/60 bg-transparent hover:text-[var(--editor-text)]"
+                className="flex items-center justify-center w-5 h-5 rounded transition-colors text-[color-mix(in_srgb,var(--editor-text)_60%,transparent)] bg-transparent hover:text-[var(--editor-text)]"
               >
                 {isFullscreen ? <Minimize2 size={12} /> : <Maximize2 size={12} />}
               </button>
@@ -2189,7 +2203,7 @@ function ReviewSurface<P extends Project>({
         </>
       ) : (
         <div className="flex-1 min-h-0 flex items-center justify-center p-2">
-          <p className="text-[var(--editor-text)]/60 text-sm">No clips</p>
+          <p className="text-[color-mix(in_srgb,var(--editor-text)_60%,transparent)] text-sm">No clips</p>
         </div>
       )}
     </div>
@@ -2234,7 +2248,7 @@ function ReviewSurface<P extends Project>({
           <button
             onClick={() => setShowControls(true)}
             aria-label="Editor controls & shortcuts"
-            className="flex items-center gap-1 px-1.5 h-5 rounded transition-colors text-[var(--editor-text)]/75 bg-transparent hover:text-[var(--editor-text)] hover:bg-[var(--editor-text)]/10"
+            className="flex items-center gap-1 px-1.5 h-5 rounded transition-colors text-[color-mix(in_srgb,var(--editor-text)_75%,transparent)] bg-transparent hover:text-[var(--editor-text)] hover:bg-[color-mix(in_srgb,var(--editor-text)_10%,transparent)]"
           >
             <HelpCircle size={14} />
             <span className="text-[10px] leading-none">Controls</span>
@@ -2245,7 +2259,7 @@ function ReviewSurface<P extends Project>({
             onClick={sync.undo}
             disabled={!sync.canUndo}
             aria-label="Undo"
-            className="flex items-center justify-center w-5 h-5 rounded transition-colors text-[var(--editor-text)]/60 bg-transparent hover:text-[var(--editor-text)] disabled:opacity-50 disabled:pointer-events-none"
+            className="flex items-center justify-center w-5 h-5 rounded transition-colors text-[color-mix(in_srgb,var(--editor-text)_60%,transparent)] bg-transparent hover:text-[var(--editor-text)] disabled:opacity-50 disabled:pointer-events-none"
           >
             <Undo2 size={12} />
           </button>
@@ -2255,7 +2269,7 @@ function ReviewSurface<P extends Project>({
             onClick={sync.redo}
             disabled={!sync.canRedo}
             aria-label="Redo"
-            className="flex items-center justify-center w-5 h-5 rounded transition-colors text-[var(--editor-text)]/60 bg-transparent hover:text-[var(--editor-text)] disabled:opacity-50 disabled:pointer-events-none"
+            className="flex items-center justify-center w-5 h-5 rounded transition-colors text-[color-mix(in_srgb,var(--editor-text)_60%,transparent)] bg-transparent hover:text-[var(--editor-text)] disabled:opacity-50 disabled:pointer-events-none"
           >
             <Redo2 size={12} />
           </button>
@@ -2268,7 +2282,7 @@ function ReviewSurface<P extends Project>({
             className={`flex items-center justify-center w-5 h-5 rounded transition-colors ${
               previewAxis
                 ? (timelineMode === 'light' ? 'text-yellow-700 bg-yellow-400/15 hover:bg-yellow-400/25' : 'text-yellow-400 bg-yellow-400/15 hover:bg-yellow-400/25')
-                : 'text-[var(--editor-text)]/60 bg-transparent hover:text-[var(--editor-text)]'
+                : 'text-[color-mix(in_srgb,var(--editor-text)_60%,transparent)] bg-transparent hover:text-[var(--editor-text)]'
             }`}
           >
             <SeparatorVertical size={12} />
@@ -2282,7 +2296,7 @@ function ReviewSurface<P extends Project>({
             className={`flex items-center justify-center w-5 h-5 rounded transition-colors ${
               rippleMode
                 ? (timelineMode === 'light' ? 'text-teal-600 bg-teal-400/15 hover:bg-teal-400/25' : 'text-teal-400 bg-teal-400/15 hover:bg-teal-400/25')
-                : 'text-[var(--editor-text)]/60 bg-transparent hover:text-[var(--editor-text)]'
+                : 'text-[color-mix(in_srgb,var(--editor-text)_60%,transparent)] bg-transparent hover:text-[var(--editor-text)]'
             }`}
           >
             <Magnet size={12} />
@@ -2299,7 +2313,7 @@ function ReviewSurface<P extends Project>({
             className={`flex items-center justify-center w-5 h-5 rounded transition-colors disabled:opacity-50 disabled:pointer-events-none ${
               cropMode
                 ? (timelineMode === 'light' ? 'text-amber-600 bg-amber-400/15 hover:bg-amber-400/25' : 'text-amber-400 bg-amber-400/15 hover:bg-amber-400/25')
-                : 'text-[var(--editor-text)]/60 bg-transparent hover:text-[var(--editor-text)]'
+                : 'text-[color-mix(in_srgb,var(--editor-text)_60%,transparent)] bg-transparent hover:text-[var(--editor-text)]'
             }`}
           >
             <Crop size={12} />
@@ -2328,7 +2342,7 @@ function ReviewSurface<P extends Project>({
             <button
               onClick={handleAudioPolish}
               aria-label="Polish audio"
-              className="flex items-center justify-center w-5 h-5 rounded transition-colors text-[var(--editor-text)]/60 bg-transparent hover:text-[var(--editor-text)]"
+              className="flex items-center justify-center w-5 h-5 rounded transition-colors text-[color-mix(in_srgb,var(--editor-text)_60%,transparent)] bg-transparent hover:text-[var(--editor-text)]"
             >
               <Wand2 size={12} />
             </button>
@@ -2342,7 +2356,7 @@ function ReviewSurface<P extends Project>({
             onClick={() => handleAudibleScrubChange(!currentAudibleScrub)}
             aria-label="Toggle audible drag-scrub"
             aria-pressed={currentAudibleScrub}
-            className="flex items-center justify-center w-5 h-5 rounded transition-colors text-[var(--editor-text)]/60 bg-transparent hover:text-[var(--editor-text)]"
+            className="flex items-center justify-center w-5 h-5 rounded transition-colors text-[color-mix(in_srgb,var(--editor-text)_60%,transparent)] bg-transparent hover:text-[var(--editor-text)]"
           >
             {currentAudibleScrub ? <Ear size={12} /> : <EarOff size={12} />}
           </button>
@@ -2796,9 +2810,9 @@ function ReviewSurface<P extends Project>({
                package's generic centered default. */
             slots?.propertiesEmptyState ?? (
               <div className="flex-1 flex flex-col items-center justify-center gap-2.5 px-6 text-center">
-                <SquareDashedMousePointer size={26} className="text-[var(--editor-text)]/25" />
-                <p className="text-xs font-medium text-[var(--editor-text)]/60">Select an element</p>
-                <p className="text-[11px] text-[var(--editor-text)]/40">Choose a clip, overlay, or track to edit its properties.</p>
+                <SquareDashedMousePointer size={26} className="text-[color-mix(in_srgb,var(--editor-text)_25%,transparent)]" />
+                <p className="text-xs font-medium text-[color-mix(in_srgb,var(--editor-text)_60%,transparent)]">Select an element</p>
+                <p className="text-[11px] text-[color-mix(in_srgb,var(--editor-text)_40%,transparent)]">Choose a clip, overlay, or track to edit its properties.</p>
               </div>
             )
           )}
@@ -2808,7 +2822,18 @@ function ReviewSurface<P extends Project>({
   )
 
   return (
-    <div className="flex flex-col flex-1 overflow-hidden">
+    <div className="relative flex flex-col flex-1 overflow-hidden">
+      {/* Save-error banner — a failed sync.mutate/commit rolls the edit back
+          silently otherwise (see CarouselEditor's identical banner). Sits on
+          the outermost container so it is visible above BOTH layout branches
+          below (CapCut and classic) rather than needing its own copy in each. */}
+      {sync.lastError && (
+        <div className="absolute top-3 left-1/2 -translate-x-1/2 z-30 flex items-center gap-2 px-3 py-2 rounded-md border border-red-500/40 bg-red-950/80 text-red-200 text-xs">
+          <AlertCircle size={14} />
+          <span>{sync.lastError}</span>
+          <button onClick={sync.clearError} className="ml-2 underline">dismiss</button>
+        </div>
+      )}
       {slots?.mediaPanel ? (
         /* CapCut layout (opt-in via slots.mediaPanel): three columns across the
            top — [left panel | preview | properties] — with a full-width timeline

package/src/video/__tests__/RenderModal.hostTheme.test.tsx

@@ -0,0 +1,85 @@
+import { describe, it, expect, vi, afterEach, beforeEach } from 'vitest'
+import { render, screen, within, cleanup } from '@testing-library/react'
+import type { EditorAdapter, Project, ImageElement } from '../../types'
+import RenderModal from '../RenderModal'
+
+// The Export dialog portals to document.body, outside the editor root. A host
+// whose page text is dark (the desktop app's `text-gray-900`) must not leak
+// that colour into the dialog: the portal root sets the editor's own text
+// colour, and every control carries an explicit themed colour.
+
+afterEach(cleanup)
+
+const HOST_DARK_TEXT = 'rgb(17, 24, 39)'
+let prevColor = ''
+beforeEach(() => { prevColor = document.body.style.color; document.body.style.color = HOST_DARK_TEXT })
+afterEach(() => { document.body.style.color = prevColor })
+
+function adapter(): EditorAdapter<Project> {
+  return {
+    loadProject: vi.fn(),
+    saveProject: vi.fn(),
+    subscribe: () => () => {},
+    render: vi.fn(async function* () {}),
+    renderAsync: vi.fn(async () => ({ status: 'running' })),
+    getRenderStatus: vi.fn(async () => ({ status: 'running' as const, phase: 'rendering' as const })),
+    resolveImageSrc: (el: ImageElement) => el.src,
+    compileOverlay: vi.fn(async () => () => null),
+    listGlobalOverlays: vi.fn(async () => []),
+    listSystemOverlays: vi.fn(async () => []),
+    uploadFile: vi.fn(async () => ''),
+    fileUrl: (p: string) => `/files?path=${p}`,
+  } as unknown as EditorAdapter<Project>
+}
+
+function renderExport() {
+  return render(
+    <RenderModal
+      adapter={adapter()}
+      projectId="vid-1"
+      onClose={vi.fn()}
+      preRenderOptions={{
+        isHdr: false,
+        keeps: [{ start: 0, end: 12 }],
+        resolution: { value: [1080, 1920], available: [[720, 1280], [1080, 1920]], set: vi.fn() },
+      }}
+    />,
+  )
+}
+
+const THEMED_TEXT = /(^|\s)text-\[(var\(--editor-text\)|color-mix\(in_srgb,var\(--editor-text\)_\d+%,transparent\))\]/
+
+describe('Export dialog in a dark-text host', () => {
+  it('the portal root sets the editor text colour', () => {
+    renderExport()
+    const cancel = screen.getByRole('button', { name: 'Cancel' })
+    const root = cancel.closest('.fixed')
+    expect(root).not.toBeNull()
+    expect(root!.className).toMatch(/(^|\s)text-\[var\(--editor-text\)\](\s|$)/)
+  })
+
+  it('Cancel has a non-empty label and an explicit themed text colour', () => {
+    renderExport()
+    const cancel = screen.getByRole('button', { name: 'Cancel' })
+    expect(cancel.textContent?.trim()).toBe('Cancel')
+    expect(cancel.className).toMatch(THEMED_TEXT)
+  })
+
+  it('every resolution tile, 720p included, shows its dims in a themed colour', () => {
+    renderExport()
+    const group = screen.getByRole('radiogroup', { name: 'Resolution' })
+    const tile720 = within(group).getByRole('radio', { name: /720p/ })
+    const dims720 = within(tile720).getByText('720 × 1280')
+    expect(dims720.className).toMatch(THEMED_TEXT)
+    const tile1080 = within(group).getByRole('radio', { name: /1080p/ })
+    expect(within(tile1080).getByText('1080 × 1920').className).toMatch(THEMED_TEXT)
+  })
+
+  it('the selected tile uses the editor accent, not a hard-coded violet', () => {
+    renderExport()
+    const group = screen.getByRole('radiogroup', { name: 'Resolution' })
+    const active = within(group).getByRole('radio', { checked: true })
+    expect(active.className).toContain('border-[var(--editor-accent)]')
+    expect(active.className).not.toMatch(/violet|indigo/)
+  })
+})

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

@@ -22,6 +22,12 @@ describe('VideoEditor context reporting', () => {
     expect(call).toMatch(/adapter/)
   })
 
+  it('reports the transport state PreviewPlayer pushes on play/pause', () => {
+    const call = src.match(/useReportContext\(\{[\s\S]*?\}\)/)?.[0] ?? ''
+    expect(call).toMatch(/playing: previewPlaying/)
+    expect(src).toMatch(/onPlayingChange=\{setPreviewPlaying\}/)
+  })
+
   // D1: captions share `selectedIds` with clips/audio now, so `selectedCaptionId`
   // must be DERIVED from that array rather than tracked as its own `useState` —
   // a second selection model is exactly the bug a future refactor could

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

@@ -0,0 +1,233 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { render, waitFor, act } from '@testing-library/react'
+import type {
+  EditorAdapter,
+  ImageElement,
+  Project,
+  RenderEvent,
+  VersionEntry,
+  WaveformChunk,
+} from '../../types'
+import VideoEditor from '../VideoEditor'
+
+// `pendingSurface` and `onUserEdit`: a host that owns the pending gate
+// (`'host'`) gets the full review editor while `status === 'pending'`, and a
+// signal that tells its own user's edits apart from an agent's SSE writes.
+// Adapter helpers copied from VideoEditor.test.tsx.
+
+// ── Fake adapter ──────────────────────────────────────────────────────────────
+// Full EditorAdapter with the video-editor capabilities VideoEditor threads:
+// listVersionHistory / restoreVersion / getWaveformChunks / compileOverlay /
+// fileUrl / resolveCaptionTemplate. No host (`@/`) modules are mocked — the
+// package owns the assembled editor.
+
+function makeVideoProject(overrides: Partial<Project> = {}): Project {
+  return {
+    id: 'vid-1',
+    name: 'Test Video',
+    status: 'draft',
+    editingPrompt: '',
+    projectType: 'video',
+    settings: { resolution: [1080, 1920], fps: 30 },
+    tracks: [
+      [
+        {
+          id: 'clip-0',
+          type: 'video',
+          src: 'a.mp4',
+          start: 0,
+          end: 4,
+          inPoint: 0,
+          outPoint: 4,
+        },
+      ],
+    ],
+    audio: { tracks: [] },
+    assets: [],
+    ...overrides,
+  } as Project
+}
+
+interface FakeAdapter extends EditorAdapter<Project> {
+  saveCalls: Array<{ id: string; project: Project }>
+  /** Push a server-authored SSE frame to every active subscriber. */
+  emit: (project: Project) => void
+  /** When true, saveProject() blocks until flushSaves() so a save stays pending. */
+  setHoldSaves: (hold: boolean) => void
+  /** Resolve every held saveProject() promise. */
+  flushSaves: () => void
+}
+
+function makeFakeAdapter(): FakeAdapter {
+  const saveCalls: Array<{ id: string; project: Project }> = []
+  let subscribers: Array<(project: Project) => void> = []
+  let holdSaves = false
+  let saveResolvers: Array<() => void> = []
+  return {
+    loadProject: vi.fn(async () => makeVideoProject()),
+    saveProject: vi.fn(async (id: string, project: Project) => {
+      saveCalls.push({ id, project })
+      if (holdSaves) await new Promise<void>((resolve) => saveResolvers.push(resolve))
+    }),
+    // Capture the sync core's frame callback so a test can drive SSE frames.
+    subscribe: (_id: string, onFrame: (project: Project) => void) => {
+      subscribers.push(onFrame)
+      return () => { subscribers = subscribers.filter((s) => s !== onFrame) }
+    },
+    render: async function* (): AsyncIterable<RenderEvent> {
+      yield { type: 'done', outputPath: '/out.mp4' }
+    },
+    resolveImageSrc: (el: ImageElement) => el.src,
+    compileOverlay: vi.fn(async () => () => null),
+    listGlobalOverlays: vi.fn(async () => []),
+    listSystemOverlays: vi.fn(async () => []),
+    uploadFile: vi.fn(async () => '/path'),
+    fileUrl: (path: string) => path,
+    listVersionHistory: vi.fn(async (): Promise<VersionEntry[]> => []),
+    restoreVersion: vi.fn(async (_id: string, _hash: string) => makeVideoProject()),
+    getWaveformChunks: vi.fn(async (): Promise<WaveformChunk[]> => []),
+    resolveCaptionTemplate: (style: string) => `/caption/${style}`,
+    getInfo: vi.fn(async () => ({ root_skill_path: undefined })),
+    saveCalls,
+    emit: (project: Project) => { for (const s of [...subscribers]) s(project) },
+    setHoldSaves: (hold: boolean) => { holdSaves = hold },
+    flushSaves: () => { const r = saveResolvers; saveResolvers = []; r.forEach((res) => res()) },
+  }
+}
+
+beforeEach(() => {
+  // The caption panel now splits into Style / Captions sub-tabs and defaults
+  // to Style; these tests want the transcript + Regenerate trigger visible, so
+  // pin the sub-tab to 'captions' (usePersistentState reads this at mount).
+  window.localStorage.setItem('montaj.editor.captionPanelTab', JSON.stringify('captions'))
+  vi.spyOn(console, 'warn').mockImplementation(() => {})
+  vi.spyOn(console, 'error').mockImplementation(() => {})
+  ;(globalThis as unknown as { ResizeObserver: unknown }).ResizeObserver = class {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  }
+  // jsdom doesn't implement media element playback.
+  ;(globalThis as unknown as { HTMLMediaElement: { prototype: HTMLMediaElement } }).HTMLMediaElement.prototype.play = vi.fn(async () => {}) as never
+  ;(globalThis as unknown as { HTMLMediaElement: { prototype: HTMLMediaElement } }).HTMLMediaElement.prototype.pause = vi.fn(() => {}) as never
+  // jsdom has no Web Audio API; the video player wires per-clip gain through it.
+  ;(globalThis as unknown as { AudioContext: unknown }).AudioContext = class {
+    state = 'running'
+    createGain() { return { gain: { value: 1 }, connect() {}, disconnect() {} } }
+    createMediaElementSource() { return { connect() {}, disconnect() {} } }
+    get destination() { return {} }
+    close() {}
+  }
+})
+afterEach(() => vi.restoreAllMocks())
+
+
+function pendingProject(overrides: Partial<Project> = {}): Project {
+  return makeVideoProject({ status: 'pending', tracks: [{ id: 'trk-0', items: [] }], ...overrides } as Partial<Project>)
+}
+
+describe('VideoEditor — pendingSurface', () => {
+  it('default: a pending project shows the built-in pending surface, not the review chrome', async () => {
+    const adapter = makeFakeAdapter()
+    const { findByTestId, queryByText, container } = render(
+      <VideoEditor
+        project={pendingProject()}
+        adapter={adapter}
+        onProjectChange={vi.fn()}
+        slots={{ pendingStatus: <div data-testid="pending" /> }}
+      />,
+    )
+    await findByTestId('pending')
+    expect(container.textContent).toContain('project id:')
+    expect(queryByText('Render →')).toBeNull()
+  })
+
+  it("'host': a pending project renders the review editor and none of the pending surface", async () => {
+    const adapter = makeFakeAdapter()
+    const { findByText, queryByTestId, container } = render(
+      <VideoEditor
+        project={makeVideoProject({ status: 'pending' })}
+        adapter={adapter}
+        onProjectChange={vi.fn()}
+        pendingSurface="host"
+        onBackToSetup={vi.fn()}
+        slots={{ pendingStatus: <div data-testid="pending" /> }}
+      />,
+    )
+    await findByText('Render →')
+    expect(queryByTestId('pending')).toBeNull()
+    expect(container.textContent).not.toContain('project id:')
+    expect(container.textContent).not.toMatch(/Back to setup/i)
+    // The skill-path fetch lives in the pending surface only.
+    expect(adapter.getInfo).not.toHaveBeenCalled()
+  })
+
+  it("'host': a pending project with zero-duration placeholders renders without throwing", async () => {
+    const adapter = makeFakeAdapter()
+    const project = makeVideoProject({
+      status: 'pending',
+      tracks: [
+        [
+          { id: 'ph-0', type: 'video', src: 'a.mp4', start: 0, end: 0 },
+          { id: 'ph-1', type: 'video', src: 'b.mp4' },
+        ],
+      ],
+    } as unknown as Partial<Project>)
+    const { findByText } = render(
+      <VideoEditor project={project} adapter={adapter} onProjectChange={vi.fn()} pendingSurface="host" />,
+    )
+    await findByText('Render →')
+  })
+
+  it("'host': an SSE frame flipping pending to draft keeps the same surface mounted", async () => {
+    const adapter = makeFakeAdapter()
+    const initial = makeVideoProject({ status: 'pending' })
+    const onProjectChange = vi.fn()
+    const { findByText } = render(
+      <VideoEditor project={initial} adapter={adapter} onProjectChange={onProjectChange} pendingSurface="host" />,
+    )
+    const before = await findByText('Render →')
+    await act(async () => { adapter.emit({ ...initial, status: 'draft' }) })
+    await waitFor(() => {
+      expect(onProjectChange).toHaveBeenLastCalledWith(expect.objectContaining({ status: 'draft' }))
+    })
+    const after = await findByText('Render →')
+    expect(after).toBe(before)
+    expect(before.isConnected).toBe(true)
+  })
+})
+
+describe('VideoEditor — onUserEdit', () => {
+  it('fires once for a user edit and once for undo, never for an SSE frame', async () => {
+    const adapter = makeFakeAdapter()
+    const initial = makeVideoProject({ status: 'draft' })
+    const onUserEdit = vi.fn()
+    const { findByText } = render(
+      <VideoEditor
+        project={initial}
+        adapter={adapter}
+        onProjectChange={vi.fn()}
+        onUserEdit={onUserEdit}
+        slots={{ exportActions: <div /> }}
+      />,
+    )
+    const renderBtn = await findByText('Render →')
+    // Let mount-time normalization settle: it goes through applyExternal.
+    await act(async () => { await new Promise((resolve) => setTimeout(resolve, 0)) })
+    expect(onUserEdit).not.toHaveBeenCalled()
+
+    // Render flips status to 'final' through sync.mutate: a user edit.
+    await act(async () => { renderBtn.click() })
+    expect(onUserEdit).toHaveBeenCalledTimes(1)
+
+    await act(async () => {
+      document.dispatchEvent(new KeyboardEvent('keydown', { key: 'z', metaKey: true }))
+    })
+    expect(onUserEdit).toHaveBeenCalledTimes(2)
+
+    await waitFor(() => expect(adapter.saveCalls.length).toBe(2))
+    await act(async () => { adapter.emit({ ...initial, name: 'Agent rename' }) })
+    await act(async () => { await new Promise((resolve) => setTimeout(resolve, 0)) })
+    expect(onUserEdit).toHaveBeenCalledTimes(2)
+  })
+})