@bycrux/editor 0.9.0 → 0.11.0

package/src/video/VideoEditor.tsx

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from 'react'
-import { Crop, Info, Magnet, Undo2 } from 'lucide-react'
+import { Crop, Info, Magnet, Pencil, Redo2, Undo2 } from 'lucide-react'
 import type { Project, VideoEditorProps } from '../types'
+import { useProjectSync, type UseProjectSync } from '../state/use-project-sync'
 import { VideoSourceCropModal } from '../crop/VideoSourceCropModal'
 import ControlsInfoModal, { VIDEO_CONTROLS } from '../ControlsInfoModal'
 import { getOverlayDesignCanvas } from './design-canvas'
@@ -8,10 +9,14 @@ import { applyTheme, defaultMontajTheme } from '../theme'
 import { applyCutToItem, applyCutToTracks, collapseGaps, splitAtTime } from './cuts'
 import { repairCaptionWords } from './captionRepair'
 import Timeline from './timeline/Timeline'
+import { makeCaptionEdit, type CaptionEditPatch } from './timeline/makeCaptionEdit'
 import PreviewPlayer from './preview/PreviewPlayer'
+import { createPlaybackClock, type PlaybackClock } from './playback-clock'
+import type { OverlayChanges } from './preview/useDragOverlay'
 import VersionPanel from './VersionPanel'
 import RenderModal from './RenderModal'
 import CaptionRegenModal from './CaptionRegenModal'
+import OverlayPropsModal from './preview/OverlayPropsModal'
 
 // Generic over the host's concrete project type `P` (default = the package's
 // own `Project`). Montaj passes its richer Project; the index signature on
@@ -19,16 +24,59 @@ import CaptionRegenModal from './CaptionRegenModal'
 // round-trips through edit→save (and `onProjectChange`) without casts.
 type Props<P extends Project = Project> = VideoEditorProps<P>
 
+// Fills in a stable `cap-<n>` id for any caption segment that doesn't already
+// have one (id was added to the schema after captions already existed on saved
+// projects, and `steps/lyrics/caption.py` still writes segments without one).
+// Never overwrites an existing id.
+//
+// Ids are minted against the ids already in use, NOT from the array index. A
+// track can hold a mix of already-backfilled segments and fresh id-less ones —
+// caption regeneration produces exactly that — so a literal `cap-1` sitting at
+// index 4 would make an index-derived mint hand out `cap-1` a second time. Ids
+// are the selection key for the preview drag and the timeline caption row, so a
+// duplicate means clicking one segment highlights and moves a different one.
+// The counter only ever moves forward, so the result is deterministic (a pure
+// function of the input segments) and, for the common all-id-less track, is
+// still exactly `cap-<index>`.
+//
+// Returns the same project reference when every segment already has an id, so
+// callers can skip applying a no-op update — the property the backfill effect's
+// loop-safety rests on.
+export function backfillCaptionIds<P extends Project>(project: P): P {
+  const captions = project.captions
+  if (!captions) return project
+  const { segments } = captions
+  if (!segments.length || segments.every((seg) => seg.id)) return project
+
+  const used = new Set(segments.map((seg) => seg.id).filter((id): id is string => !!id))
+  let counter = 0
+  const mint = () => {
+    let id = `cap-${counter++}`
+    while (used.has(id)) id = `cap-${counter++}`
+    used.add(id)
+    return id
+  }
+
+  return {
+    ...project,
+    captions: { ...captions, segments: segments.map((seg) => (seg.id ? seg : { ...seg, id: mint() })) },
+  }
+}
+
 /**
  * `<VideoEditor>` — the assembled, host-agnostic video editor.
  *
  * Absorbs Montaj's former LiveView (pending/processing surface) and ReviewView
  * (draft/final surface) into one component driven by the `EditorAdapter`.
- * Controlled like `<CarouselEditor>`: the host owns `project` and is notified of
- * edits via `onProjectChange`; persistence flows through `adapter.saveProject`.
- * It does NOT own a `useProjectState` reducer — it preserves the original
- * Live/Review save model exactly (mutate → onProjectChange → adapter.saveProject
- * fire-and-forget), so the host's pipeline fields survive untouched.
+ * Controlled like `<CarouselEditor>`: the host owns the initial `project` and is
+ * notified of edits via `onProjectChange`; persistence flows through the shared
+ * `useProjectSync` core (queued saves, SSE echo protection, undo/redo).
+ *
+ * The sync core is created ONCE here (not per-surface) so it owns a single SSE
+ * subscription and so `sync.project.status` drives the Pending↔Review switch —
+ * the editor now subscribes to live frames itself instead of receiving them as a
+ * 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.
  *
  * ProjectHeader is lifted out (the host renders it in its shell). This component
  * renders: timeline + preview + version panel + render modal + the host-supplied
@@ -51,31 +99,78 @@ export default function VideoEditor<P extends Project = Project>({
 }: Props<P>) {
   const emit = onProjectChange ?? (() => {})
 
+  // Shared save/undo/SSE core. Created once at the top so there is exactly one
+  // subscription per editor and `sync.project` is the single source of truth for
+  // 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)
+
+  // Every caption segment needs a stable `id` for selection (preview drag,
+  // clickable timeline row). Segments saved before `id` existed on the schema
+  // are missing it, and `steps/lyrics/caption.py` still writes segments without
+  // one, so backfill `cap-<index>` whenever the caption track changes identity.
+  //
+  // Keyed on `sync.project.id` AND `sync.project.captions` so it covers every
+  // entry point a caption track reaches state through:
+  //   - the `initial` value seeded into useProjectSync's reducer above (only
+  //     consulted on this component's first mount — React ignores later changes
+  //     to a useReducer initial arg);
+  //   - a same-mounted-instance swap to a different project id, which arrives
+  //     via the SSE subscription's `applyExternal` (e.g. client-side navigation
+  //     between two projects without VideoEditor unmounting);
+  //   - a caption REGENERATION inside a live session (CaptionRegenModal →
+  //     applyExternal with a whole new, id-less `captions` object). The project
+  //     id does not change there, so an id-keyed effect would not re-fire and
+  //     every segment would silently become unselectable.
+  //
+  // Loop-proof: `backfillCaptionIds` returns the *same* project reference when
+  // every segment already has an id, so the pass that follows our own
+  // `applyExternal` (which necessarily produces a new `captions` reference, and
+  // therefore re-fires this effect exactly once) finds nothing to do and stops.
+  // Every other re-fire — one per caption edit — is a cheap `.every()` no-op.
+  //
+  // `applyExternal` — no save, no undo push: this is normalization of loaded
+  // data, not a user edit, so it must not dirty the project or contend with the
+  // undo stack; the ids persist naturally the next time the operator makes a
+  // real edit.
+  useEffect(() => {
+    const backfilled = backfillCaptionIds(sync.project)
+    if (backfilled !== sync.project) sync.applyExternal(backfilled)
+  }, [sync.project.id, sync.project.captions])
+
+  // Notify the host of every authoritative change — edits, undo/redo, and SSE
+  // frames — so its non-editor chrome (title, status pill) stays in sync. Mirrors
+  // CarouselEditor. `emit` is read via a ref so the effect only fires on state
+  // change, not when the host passes a new `onProjectChange` identity.
+  const emitRef = useRef(emit)
+  emitRef.current = emit
+  useEffect(() => {
+    emitRef.current(sync.project)
+  }, [sync.project])
+
   // ── Theme: apply tokens onto the editor container. ──
   const containerRef = useRef<HTMLDivElement>(null)
   useEffect(() => {
     if (containerRef.current) applyTheme(containerRef.current, theme ?? defaultMontajTheme)
   }, [theme])
 
-  const isPending = project.status === 'pending'
+  const isPending = sync.project.status === 'pending'
 
   // ── Shared injected adapter fns, threaded to Timeline + PreviewPlayer. ──
   const getWaveformChunks = adapter.getWaveformChunks
   const resolveFilePath   = adapter.fileUrl
-  const save = (p: P) => { void adapter.saveProject(p.id, p) }
 
   if (isPending) {
     return (
       <div ref={containerRef} className="flex flex-col h-full bg-[var(--editor-bg)]">
         <PendingSurface
-          project={project}
+          sync={sync}
           adapter={adapter}
-          onProjectChange={emit}
           slots={slots}
           onBackToSetup={onBackToSetup}
           getWaveformChunks={getWaveformChunks}
           resolveFilePath={resolveFilePath}
-          save={save}
         />
       </div>
     )
@@ -84,15 +179,14 @@ export default function VideoEditor<P extends Project = Project>({
   return (
     <div ref={containerRef} className="flex flex-col h-full">
       <ReviewSurface
-        project={project}
+        sync={sync}
+        emit={emit}
         adapter={adapter}
-        onProjectChange={emit}
         slots={slots}
         assetsPlacement={assetsPlacement}
         renderProgressView={renderProgressView}
         getWaveformChunks={getWaveformChunks}
         resolveFilePath={resolveFilePath}
-        save={save}
         renderClipInspector={renderClipInspector}
         renderSubcutRegen={renderSubcutRegen}
         regenEnabled={regenEnabled}
@@ -119,28 +213,30 @@ function useVersionHistory<P extends Project>(adapter: VideoEditorProps<P>['adap
 // ── Pending / processing surface (former LiveView) ───────────────────────────
 
 interface SurfaceProps<P extends Project> {
-  project: P
+  sync: UseProjectSync<P>
   adapter: VideoEditorProps<P>['adapter']
-  onProjectChange: (p: P) => void
   slots?: VideoEditorProps<P>['slots']
   assetsPlacement?: VideoEditorProps<P>['assetsPlacement']
   renderProgressView?: VideoEditorProps<P>['renderProgressView']
   getWaveformChunks?: VideoEditorProps<P>['adapter']['getWaveformChunks']
   resolveFilePath: (path: string) => string
-  save: (p: P) => void
   onProvideRenderTrigger?: VideoEditorProps<P>['onProvideRenderTrigger']
 }
 
 function PendingSurface<P extends Project>({
-  project,
+  sync,
   adapter,
-  onProjectChange,
   slots,
   onBackToSetup,
   getWaveformChunks,
   resolveFilePath,
 }: SurfaceProps<P> & { onBackToSetup?: () => void }) {
-  const [currentTime, setCurrentTime] = useState(0)
+  const project = sync.project
+  // The playhead lives in an external store (not useState) so ~60Hz ticks only
+  // re-render the leaves that display time — not this whole surface.
+  const clockRef = useRef<PlaybackClock | null>(null)
+  if (!clockRef.current) clockRef.current = createPlaybackClock()
+  const clock = clockRef.current
   const [skillPath, setSkillPath] = useState<string | null>(null)
   const [copied, setCopied] = useState(false)
   const { versions, restoring, setRestoring } = useVersionHistory(adapter, project)
@@ -161,7 +257,8 @@ function PendingSurface<P extends Project>({
     setRestoring(hash)
     try {
       const restored = await adapter.restoreVersion(project.id, hash)
-      onProjectChange(restored)
+      // Server-authored, already persisted — apply without a save or undo push.
+      sync.applyExternal(restored)
     } catch (e) {
       console.error(e)
     } finally {
@@ -177,8 +274,7 @@ function PendingSurface<P extends Project>({
           {hasTrimmedClips ? (
             <PreviewPlayer
               project={project}
-              currentTime={currentTime}
-              onTimeUpdate={setCurrentTime}
+              clock={clock}
               compileOverlay={adapter.compileOverlay}
               clearOverlayCache={adapter.clearOverlayCache}
               watchFile={adapter.watchFile}
@@ -238,11 +334,10 @@ function PendingSurface<P extends Project>({
         <div className="shrink-0 border-t border-[var(--editor-border)] bg-[var(--editor-surface)]">
           <Timeline
             project={project}
-            currentTime={currentTime}
-            onTimeUpdate={setCurrentTime}
+            clock={clock}
             getWaveformChunks={getWaveformChunks}
             resolveFilePath={resolveFilePath}
-            onSaveProject={(p) => adapter.saveProject(p.id, p as P)}
+            onSaveProject={(p) => sync.mutate(() => p as P)}
           />
         </div>
       </div>
@@ -260,33 +355,43 @@ function PendingSurface<P extends Project>({
 // ── Draft / final surface (former ReviewView) ────────────────────────────────
 
 function ReviewSurface<P extends Project>({
-  project,
+  sync,
+  emit,
   adapter,
-  onProjectChange,
   slots,
   assetsPlacement = 'right',
   renderProgressView = 'phases',
   getWaveformChunks,
   resolveFilePath,
-  save,
   renderClipInspector,
   renderSubcutRegen,
   regenEnabled,
   isClipQueued,
   onProvideRenderTrigger,
 }: SurfaceProps<P> & {
+  emit: (p: P) => void
   renderClipInspector?: VideoEditorProps<P>['renderClipInspector']
   renderSubcutRegen?: VideoEditorProps<P>['renderSubcutRegen']
   regenEnabled?: boolean
   isClipQueued?: (itemId: string) => boolean
 }) {
-  const [currentTime, setCurrentTime] = useState(0)
-  const [canUndo, setCanUndo]         = useState(false)
-  const historyRef = useRef<P[]>([])
+  const project = sync.project
+  // Playhead in an external store, not useState — ~60Hz ticks re-render only the
+  // leaves that display time (preview, scrubber, transcript) instead of the whole
+  // review surface (toolbar + timeline + every context consumer).
+  const clockRef = useRef<PlaybackClock | null>(null)
+  if (!clockRef.current) clockRef.current = createPlaybackClock()
+  const clock = clockRef.current
   // Multi-select: all currently-selected timeline item ids. Single-select
   // consumers (canvas preview, cut/split) use selectedIds[0] as the primary.
   const [selectedIds, setSelectedIds] = useState<string[]>([])
   const primarySelectedId = selectedIds[0] ?? null
+  // Selected caption segment id. Deliberately owned here rather than inside the
+  // preview: it is shared selection state. The preview draws the selection box /
+  // drag handles for it, and the timeline's caption row (later task) highlights
+  // and seeks to the same segment — that sibling only needs `selectedCaptionId`
+  // and `setSelectedCaptionId` passed down, no lifting required.
+  const [selectedCaptionId, setSelectedCaptionId] = useState<string | null>(null)
   const [rippleMode, setRippleMode]   = useState(false)
   const [showControls, setShowControls] = useState(false)
   // Source-crop mode: when on, the VideoSourceCropModal opens for the selected
@@ -299,34 +404,54 @@ function ReviewSurface<P extends Project>({
   const [inspecting, setInspecting]   = useState<{ kind: 'clip' | 'audio'; id: string } | null>(null)
 
   // Render trigger — marks the project final, saves, and opens the RenderModal.
-  // Kept stable (latest project/onChange/save read via refs) so a host that
-  // places Render in its own header (onProvideRenderTrigger) can store the
-  // callback once without it going stale.
-  const projectRef         = useRef(project);         projectRef.current = project
-  const onProjectChangeRef = useRef(onProjectChange); onProjectChangeRef.current = onProjectChange
-  const saveRef            = useRef(save);            saveRef.current = save
+  // Kept stable (the sync mutators/ref are stable; `emit` read via ref) so a host
+  // that places Render in its own header (onProvideRenderTrigger) can store the
+  // callback once without it going stale. `emit(final)` fires synchronously so
+  // the host's chrome flips to "final" immediately; the queued `mutate` makes it
+  // canonical and persists it.
+  const { mutate: syncMutate, projectRef: syncProjectRef } = sync
+  const emitRef = useRef(emit); emitRef.current = emit
   const openRender = useCallback(() => {
-    const final = { ...projectRef.current, status: 'final' } as P
-    onProjectChangeRef.current(final)
-    saveRef.current(final)
+    const final = { ...syncProjectRef.current, status: 'final' } as P
+    emitRef.current(final)
+    void syncMutate(() => final)
     setRenderOpen(true)
-  }, [])
+  }, [syncMutate, syncProjectRef])
   useEffect(() => { onProvideRenderTrigger?.(openRender) }, [onProvideRenderTrigger, openRender])
 
   const { versions, restoring, setRestoring } = useVersionHistory(adapter, project)
 
   // Repair caption segments whose words[] text has diverged from edited seg.text.
   // Inline caption edits update seg.text but not seg.words; this normalizes the
-  // data so PreviewPlayer's word-level timing is correct. Runs once per project.id.
+  // data so PreviewPlayer's word-level timing is correct.
+  //
+  // Keyed on BOTH project.id and project.captions — mirrors the id-backfill
+  // effect above for the identical reason: `CaptionRegenModal`'s `onDone`
+  // replaces project.captions via applyExternal WITHOUT changing project.id, so
+  // an id-keyed-only effect would miss mid-session caption regeneration and
+  // freshly regenerated captions would skip repair until a remount.
+  //
+  // Applied via `applyExternal` (no save, no undo push): it's a local
+  // reconciliation, not a user edit — pushing an undo entry on load would make the
+  // operator's first Cmd-Z undo the repair, and the normalized captions persist on
+  // the next real save anyway.
+  //
+  // Loop-proof: `repairCaptionWords` returns `null` (a true no-op) once every
+  // segment's words[] already matches its text — see captionRepair.ts, which
+  // whitespace-normalizes the comparison specifically so this holds even when
+  // the edited/regenerated text itself contains irregular internal spacing
+  // (without that normalization, repairing never reaches a fixed point and this
+  // effect would applyExternal forever). The pass that follows our own
+  // applyExternal (which necessarily produces a new `captions` reference, and
+  // therefore re-fires this effect exactly once) finds nothing left to repair
+  // and stops. Every other re-fire — one per caption edit — is a cheap no-op scan.
   useEffect(() => {
     const captions = project.captions
     if (!captions?.segments?.length) return
     const repaired = repairCaptionWords(captions)
     if (!repaired) return
-    const next = { ...project, captions: repaired } as P
-    onProjectChange(next)
-    void adapter.saveProject(next.id, next)
-  }, [project.id]) // intentionally keyed on project.id only — runs once per project load
+    sync.applyExternal({ ...project, captions: repaired } as P)
+  }, [project.id, project.captions])
 
   const clips      = project.tracks?.[0] ?? []
   const hasContent = clips.length > 0 || (project.tracks?.slice(1).flat().length ?? 0) > 0 || (project.captions?.segments?.length ?? 0) > 0
@@ -343,91 +468,146 @@ function ReviewSurface<P extends Project>({
     if (!cropTarget && cropMode) setCropMode(false)
   }, [cropTarget, cropMode])
 
-  function pushHistory(prev: P) {
-    historyRef.current = [...historyRef.current.slice(-49), prev]
-    setCanUndo(true)
-  }
+  // Overlay props dialog — opened from the preview (double-click), the controls
+  // bar, or the timeline block. VideoEditor owns the state so all three surfaces
+  // share one modal. Edits ride the sync core's transient/commit gesture path
+  // (live preview + one undo step on Save).
+  const [editingOverlayId, setEditingOverlayId] = useState<string | null>(null)
+  // Project snapshot taken when the dialog opens, so Cancel reverts to the
+  // pre-edit state even though edits preview live in between.
+  const editOriginalRef = useRef<P | null>(null)
+  const requestEditOverlay = useCallback((id: string) => {
+    editOriginalRef.current = syncProjectRef.current
+    setEditingOverlayId(id)
+  }, [syncProjectRef])
+  const allVisualItems = (project.tracks ?? []).flat()
+  const editingOverlayItem = editingOverlayId
+    ? allVisualItems.find(i => i.id === editingOverlayId) ?? null
+    : null
 
-  // Edits coming from the timeline (drag/move/track changes): snapshot for undo,
-  // notify host, persist.
-  function handleProjectChange(p: Project) {
-    pushHistory(project)
-    onProjectChange(p as P)
-    save(p as P)
+  function withItemProps(base: P, id: string, nextProps: Record<string, unknown>): P {
+    return {
+      ...base,
+      tracks: (base.tracks ?? []).map(track =>
+        track.map(item => (item.id !== id ? item : { ...item, props: nextProps })),
+      ),
+    } as P
   }
+  // Live preview: reflect the in-progress edit locally (transient — no save, no
+  // undo push) so the overlay re-renders as the operator tweaks. `commit()` on
+  // Save persists the accumulated transient state as one undo step.
+  function previewOverlayProps(id: string, nextProps: Record<string, unknown>) {
+    sync.mutateTransient(p => withItemProps(p, id, nextProps))
+  }
+  // Commit on Save: the last preview already applied the final props transiently,
+  // so committing persists them and records one undo step (the pre-edit baseline).
+  function commitOverlayEdit() {
+    void sync.commit()
+    editOriginalRef.current = null
+    setEditingOverlayId(null)
+  }
+  // Cancel/Esc/close: discard the live preview by restoring the pre-edit snapshot
+  // (no save, no undo push).
+  function cancelOverlayEdit() {
+    if (editOriginalRef.current) sync.applyExternal(editOriginalRef.current)
+    editOriginalRef.current = null
+    setEditingOverlayId(null)
+  }
+  // The primary-selected JSX overlay, if any — drives the controls-bar edit button.
+  const selectedOverlayItem = primarySelectedId
+    ? allVisualItems.find(i => i.id === primarySelectedId && i.type === 'overlay' && !!i.src) ?? null
+    : null
 
-  function handleUndo() {
-    const hist = historyRef.current
-    if (!hist.length) return
-    const prev = hist[hist.length - 1]
-    historyRef.current = hist.slice(0, -1)
-    setCanUndo(hist.length > 1)
-    onProjectChange(prev)
-    save(prev)
+  // Edits coming from the timeline (drag/move/track changes): route through the
+  // sync core — one undo step + queued save + rollback-on-failure.
+  function handleProjectChange(p: Project) {
+    void sync.mutate(() => p as P)
   }
 
   function handleCut(cut: { start: number; end: number }) {
-    pushHistory(project)
-    let updated = primarySelectedId
-      ? applyCutToItem(project, primarySelectedId, cut)
-      : applyCutToTracks(project, cut)
-    if (rippleMode) updated = collapseGaps(updated)
-    onProjectChange(updated as P)
-    save(updated as P)
+    void sync.mutate(p => {
+      let updated = primarySelectedId
+        ? applyCutToItem(p, primarySelectedId, cut)
+        : applyCutToTracks(p, cut)
+      if (rippleMode) updated = collapseGaps(updated)
+      return updated as P
+    })
     setSelectedIds([])
   }
 
-  function handleOverlayChange(id: string, changes: { offsetX?: number; offsetY?: number; scale?: number; rotation?: number; fit?: 'cover' | 'contain' | 'fill'; sourceCrop?: { x: number; y: number; w: number; h: number }; sourceWidth?: number; sourceHeight?: number }) {
-    pushHistory(project)
-    const updated = {
-      ...project,
-      tracks: (project.tracks ?? []).map(track =>
+  function handleOverlayChange(id: string, changes: OverlayChanges) {
+    void sync.mutate(p => ({
+      ...p,
+      tracks: (p.tracks ?? []).map(track =>
         track.map(item => item.id !== id ? item : { ...item, ...changes })
       ),
-    } as P
-    onProjectChange(updated)
-    save(updated)
+    } as P))
   }
 
+  // Commit a per-segment caption change (preview drag → offsetX/offsetY/scale).
+  // Routed through `makeCaptionEdit` so there is exactly one project-mutation
+  // path for caption edits — it addresses the segment by id and leaves the
+  // fields the patch omits alone — and through `sync.mutate` so a finished drag
+  // lands as one undo step plus a queued save, same as a timeline caption edit.
+  // Only ONE of makeCaptionEdit's two callbacks is supplied: both are invoked
+  // with the same updated project, so passing both would mutate twice.
+  const handleCaptionSegmentChange = useCallback((segmentId: string, patch: CaptionEditPatch) => {
+    makeCaptionEdit(segmentId, syncProjectRef.current, (p) => void syncMutate(() => p as P))(patch)
+  }, [syncProjectRef, syncMutate])
+
+  // Selecting a caption segment and selecting a normal timeline item are
+  // mutually exclusive selection models — never show both sets of handles at
+  // once (see CaptionTrackRow's file header). A caption can be selected from
+  // either the preview (click the selection box) or the timeline's caption
+  // row, so this wrapper — not Timeline — is the one place that must clear
+  // `selectedIds` on every caption selection; Timeline's own
+  // `handleSelectItem` handles the reverse (selecting an item clears this).
+  const handleSelectCaption = useCallback((id: string | null) => {
+    setSelectedCaptionId(id)
+    if (id !== null) setSelectedIds([])
+  }, [])
+
   function handleSplit(at?: number) {
-    const updated = splitAtTime(project, at ?? currentTime, primarySelectedId ?? null)
-    if (updated === project) return
-    pushHistory(project)
-    onProjectChange(updated as P)
-    save(updated as P)
+    const base = syncProjectRef.current
+    const updated = splitAtTime(base, at ?? clock.get(), primarySelectedId ?? null)
+    if (updated === base) return
+    void sync.mutate(() => updated as P)
   }
 
   function handleRippleToggle() {
     const next = !rippleMode
     setRippleMode(next)
     if (next) {
-      const collapsed = collapseGaps(project)
-      if (collapsed !== project) {
-        pushHistory(project)
-        onProjectChange(collapsed as P)
-        save(collapsed as P)
-      }
+      const base = syncProjectRef.current
+      const collapsed = collapseGaps(base)
+      if (collapsed !== base) void sync.mutate(() => collapsed as P)
     }
   }
 
-  // Keyboard: split (S) and undo (cmd/ctrl-Z). Guarded against text inputs.
+  // Keyboard: split (S), undo (cmd/ctrl-Z), redo (cmd/ctrl-shift-Z or cmd/ctrl-Y).
+  // Guarded against text inputs.
   useEffect(() => {
     const onKey = (e: KeyboardEvent) => {
       const el = e.target as HTMLElement
       if (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA' || el.isContentEditable) return
-      if (e.key === 's' || e.key === 'S') { e.preventDefault(); handleSplit() }
-      if ((e.metaKey || e.ctrlKey) && e.key === 'z') { e.preventDefault(); handleUndo() }
+      if (e.key === 's' || e.key === 'S') { e.preventDefault(); handleSplit(); return }
+      const mod = e.metaKey || e.ctrlKey
+      if (!mod) return
+      const key = e.key.toLowerCase()
+      if (key === 'z' && !e.shiftKey) { e.preventDefault(); sync.undo() }
+      else if ((key === 'z' && e.shiftKey) || key === 'y') { e.preventDefault(); sync.redo() }
     }
     document.addEventListener('keydown', onKey)
     return () => document.removeEventListener('keydown', onKey)
-  }, [project, currentTime, primarySelectedId, canUndo])
+  }, [project, primarySelectedId, sync])
 
   async function handleRestoreVersion(hash: string) {
     if (!adapter.restoreVersion) return
     setRestoring(hash)
     try {
       const restored = await adapter.restoreVersion(project.id, hash)
-      onProjectChange(restored)
+      // Server-authored, already persisted — apply without a save or undo push.
+      sync.applyExternal(restored)
     } catch (e) {
       console.error(e)
     } finally {
@@ -449,15 +629,18 @@ function ReviewSurface<P extends Project>({
             >
               <PreviewPlayer
                 project={project}
-                currentTime={currentTime}
-                onTimeUpdate={setCurrentTime}
+                clock={clock}
                 selectedOverlayId={primarySelectedId ?? undefined}
                 onOverlayChange={handleOverlayChange}
+                onEditOverlay={requestEditOverlay}
                 compileOverlay={adapter.compileOverlay}
                 clearOverlayCache={adapter.clearOverlayCache}
                 watchFile={adapter.watchFile}
                 fileUrl={adapter.fileUrl}
                 resolveCaptionTemplate={adapter.resolveCaptionTemplate}
+                selectedCaptionId={selectedCaptionId ?? undefined}
+                onSelectCaption={handleSelectCaption}
+                onCaptionSegmentChange={handleCaptionSegmentChange}
               />
             </div>
           ) : (
@@ -465,7 +648,7 @@ function ReviewSurface<P extends Project>({
           )}
         </div>
 
-        {/* Track controls bar — info + split + ripple + render */}
+        {/* Track controls bar — info + undo/redo + split + ripple + render */}
         <div className="shrink-0 flex items-center justify-end gap-1.5 px-3 py-1 border-t border-[var(--editor-border)] bg-[var(--editor-surface)]">
           <button
             onClick={() => setShowControls(true)}
@@ -476,14 +659,23 @@ function ReviewSurface<P extends Project>({
             <Info size={12} />
           </button>
           <button
-            onClick={handleUndo}
-            disabled={!canUndo}
+            onClick={sync.undo}
+            disabled={!sync.canUndo}
             title="Undo (Cmd/Ctrl+Z)"
             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-30 disabled:cursor-not-allowed"
           >
             <Undo2 size={12} />
           </button>
+          <button
+            onClick={sync.redo}
+            disabled={!sync.canRedo}
+            title="Redo (Cmd/Ctrl+Shift+Z)"
+            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-30 disabled:cursor-not-allowed"
+          >
+            <Redo2 size={12} />
+          </button>
           <button
             onClick={() => handleSplit()}
             title="Split at playhead (S) — selected item or all clips"
@@ -524,6 +716,16 @@ function ReviewSurface<P extends Project>({
           >
             <Crop size={12} />
           </button>
+          {selectedOverlayItem && (
+            <button
+              onClick={() => requestEditOverlay(selectedOverlayItem.id)}
+              title="Edit overlay — text, colors, and other properties"
+              aria-label="Edit overlay"
+              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)]"
+            >
+              <Pencil size={12} />
+            </button>
+          )}
           {/* Default placement. A host that sets onProvideRenderTrigger renders
               Render in its own chrome instead, so the toolbar button is hidden. */}
           {!onProvideRenderTrigger && (
@@ -539,18 +741,21 @@ function ReviewSurface<P extends Project>({
         <div className="shrink-0 border-t border-[var(--editor-border)] bg-[var(--editor-surface)]">
           <Timeline
             project={project}
-            currentTime={currentTime}
-            onTimeUpdate={setCurrentTime}
+            clock={clock}
             onProjectChange={handleProjectChange}
-            onCaptionEdit={(p) => { onProjectChange(p as P); save(p as P) }}
-            onOverlayEdit={(p) => { onProjectChange(p as P); save(p as P) }}
+            onCaptionEdit={(p) => void sync.mutate(() => p as P)}
+            onOverlayEdit={(p) => void sync.mutate(() => p as P)}
+            onEditOverlay={requestEditOverlay}
             selectedIds={selectedIds}
             onSelectIds={setSelectedIds}
+            selectedCaptionId={selectedCaptionId}
+            onSelectCaption={handleSelectCaption}
+            onCaptionSegmentChange={handleCaptionSegmentChange}
             onSplit={handleSplit}
             onCut={handleCut}
             onInspectClip={(id) => setInspecting({ kind: 'clip', id })}
             onInspectAudio={(id) => setInspecting({ kind: 'audio', id })}
-            onSaveProject={(p) => adapter.saveProject(p.id, p as P)}
+            onSaveProject={(p) => sync.mutate(() => p as P)}
             rippleMode={rippleMode}
             getWaveformChunks={getWaveformChunks}
             resolveFilePath={resolveFilePath}
@@ -654,22 +859,37 @@ function ReviewSurface<P extends Project>({
       )}
 
       {/* Caption regen modal — adapter.generateCaptions stream. On done we patch
-          project.captions via onProjectChange only. We deliberately do NOT call
-          save(): montaj persists the regenerated captions server-side and the
-          SSE subscribe frame reconciles, so a saveProject here would double-write. */}
+          project.captions via applyExternal only. We deliberately do NOT save:
+          montaj persists the regenerated captions server-side and the SSE frame
+          reconciles, so a saveProject here would double-write. applyExternal keeps
+          it out of the undo stack (server-authored, not a user edit). */}
       {regenCaptionsOpen && adapter.generateCaptions && (
         <CaptionRegenModal
           adapter={adapter}
           projectId={project.id}
           onClose={() => setRegenCaptionsOpen(false)}
           onDone={(captions) => {
-            const next = { ...project, captions } as P
-            onProjectChange(next)
+            sync.applyExternal({ ...syncProjectRef.current, captions } as P)
             setRegenCaptionsOpen(false)
           }}
         />
       )}
 
+      {/* Overlay props dialog — edits the selected overlay's primitive props
+          (text, colors, numbers, toggles). Opened from the preview double-click,
+          the controls bar, or a timeline block. Edits preview live (transient) and
+          undo as one step on Save. */}
+      {editingOverlayItem && (
+        <OverlayPropsModal
+          itemProps={editingOverlayItem.props ?? {}}
+          fileUrl={adapter.fileUrl}
+          uploadFile={(file) => adapter.uploadFile(file, project.id)}
+          onPreview={(next) => previewOverlayProps(editingOverlayItem.id, next)}
+          onSave={() => commitOverlayEdit()}
+          onClose={cancelOverlayEdit}
+        />
+      )}
+
       {/* Clip / audio inspector — host-rendered via render-prop seam. */}
       {inspecting && renderClipInspector?.({
         item: inspecting,