@bycrux/editor 0.10.0 → 0.11.0

package/src/video/preview/captionDragState.ts

@@ -0,0 +1,175 @@
+/**
+ * Pure drag maths for caption-segment positioning in the preview.
+ *
+ * Why this is NOT `useDragOverlay` generalised
+ * --------------------------------------------
+ * The two gestures look alike but their coordinate models are different, and
+ * the overlay hook is the highest-traffic drag path in the preview:
+ *
+ *  - `useDragOverlay` drives an element that is `inset-0` (frame-sized) and then
+ *    scaled from its centre, so `scale` is a *box* scale. Its edge-snap geometry
+ *    (`edgeX = (0.5 - s/2) * 100`) is derived from exactly that. A caption's
+ *    `scale` is a font-size multiplier applied to a small, content-sized anchor
+ *    box — the same formula would compute snap positions that mean nothing.
+ *  - Overlays rotate; caption segments do not (no `rotation` on CaptionSegment).
+ *  - Overlays commit through `onOverlayChange(id, changes)` into `project.tracks`;
+ *    caption segments commit through `makeCaptionEdit` into `project.captions`.
+ *
+ * The only genuinely shared logic is "screen delta ÷ preview scale → percent of
+ * frame", which is two divisions. Parameterising the overlay hook to switch off
+ * rotation and edge snapping, and to swap its commit contract, would churn that
+ * hook for no reuse worth having — so this duplicates the gesture maths
+ * deliberately, as pure functions (no React), and keeps the overlay path
+ * untouched.
+ *
+ * Coordinate convention
+ * ---------------------
+ * Offsets are **percent of frame** (`offsetX: 22` = 22% of frame width), the
+ * same unit overlay and video items use, and the unit the caption render
+ * templates consume via `captionOuterStyle`.
+ *
+ * Deltas **accumulate from the gesture start**: the segment's committed geometry
+ * and the pointer position are both captured in `CaptionDragState` at mousedown,
+ * and every subsequent move recomputes `initOffset + (pointer - initPointer)`.
+ * Nothing is derived from an absolute cursor position, and no intermediate
+ * result is fed back in — so a gesture is idempotent for a given pointer
+ * position and cannot accumulate rounding drift over a long drag.
+ */
+
+import type { CaptionSegment } from '../../schema'
+
+export type CaptionCorner = 'nw' | 'ne' | 'sw' | 'se'
+export type CaptionDragType = 'move' | `resize-${CaptionCorner}`
+
+/** Everything captured at mousedown. Immutable for the life of the gesture. */
+export interface CaptionDragState {
+  /** `CaptionSegment.id` of the segment being dragged. */
+  id: string
+  type: CaptionDragType
+  /** Pointer position at gesture start, in client (screen) px. */
+  initX: number
+  initY: number
+  /** The segment's committed geometry at gesture start. */
+  initOffsetX: number
+  initOffsetY: number
+  initScale: number
+}
+
+/** A caption segment's positioning geometry, with schema defaults filled in. */
+export interface CaptionGeometry {
+  offsetX: number
+  offsetY: number
+  scale: number
+}
+
+/**
+ * The preview's design-resolution mapping.
+ *
+ * `previewScale` is CaptionPreview's ResizeObserver value: on-screen frame width
+ * ÷ `renderW`. Callers MUST pass the same `renderW` that produced `previewScale`
+ * — the width terms then cancel exactly (`px / previewScale / renderW` ≡
+ * `px / onScreenWidth`), which is what makes the conversion independent of
+ * window size.
+ */
+export interface CaptionFrameMetrics {
+  previewScale: number
+  renderW: number
+  renderH: number
+}
+
+// Bounds on the font-size multiplier. Below ~0.1 the caption is unreadable and
+// its selection box becomes too small to grab back; above 5 it is larger than
+// the frame in every template. Mirrors the overlay hook's `Math.max(0.1, …)`
+// floor, with a ceiling added because a caption's scale grows text, not a box,
+// so there is no self-limiting geometry.
+export const CAPTION_MIN_SCALE = 0.1
+export const CAPTION_MAX_SCALE = 5
+
+/**
+ * Click slop, in screen px. The same mousedown both selects a segment and arms
+ * a move, so a click that wobbles a couple of pixels must not nudge the caption
+ * (and must not push an undo step). Until the pointer travels this far the
+ * gesture is treated as a click, and returning inside the radius cancels it
+ * again — so a drag that comes back to where it started commits nothing.
+ */
+export const CAPTION_DRAG_SLOP_PX = 3
+
+/** Has the pointer moved far enough from the mousedown to count as a drag? */
+export function hasEscapedClickSlop(drag: CaptionDragState, clientX: number, clientY: number): boolean {
+  return Math.hypot(clientX - drag.initX, clientY - drag.initY) > CAPTION_DRAG_SLOP_PX
+}
+
+/** Read a segment's geometry, applying the schema defaults (0 / 0 / 1). */
+export function readCaptionGeometry(seg: Pick<CaptionSegment, 'offsetX' | 'offsetY' | 'scale'> | null | undefined): CaptionGeometry {
+  return {
+    offsetX: seg?.offsetX ?? 0,
+    offsetY: seg?.offsetY ?? 0,
+    scale:   seg?.scale   ?? 1,
+  }
+}
+
+/**
+ * Convert a screen-pixel delta to percent of frame.
+ *
+ *   screen px → design px:  px / previewScale
+ *   design px → percent:    designPx / renderW * 100   (renderH for Y)
+ *
+ * Returns a zero delta for degenerate metrics (scale not measured yet, zero-size
+ * canvas) rather than NaN/Infinity, so a drag that starts before the first
+ * ResizeObserver callback is inert instead of catapulting the segment offscreen.
+ */
+export function screenDeltaToFramePercent(
+  dxPx: number,
+  dyPx: number,
+  { previewScale, renderW, renderH }: CaptionFrameMetrics,
+): { dx: number; dy: number } {
+  if (!(previewScale > 0) || !(renderW > 0) || !(renderH > 0)) return { dx: 0, dy: 0 }
+  return {
+    dx: (dxPx / previewScale) / renderW * 100,
+    dy: (dyPx / previewScale) / renderH * 100,
+  }
+}
+
+/**
+ * Geometry for the current pointer position, given the gesture captured at
+ * mousedown. `move` translates; `resize-<corner>` scales and leaves the offsets
+ * alone (the inner anchor box scales around its own centre, so a scaled caption
+ * stays put — see captionInnerStyle in overlay-runtime/position.js).
+ */
+export function captionDragGeometry(
+  drag: CaptionDragState,
+  clientX: number,
+  clientY: number,
+  metrics: CaptionFrameMetrics,
+): CaptionGeometry {
+  const { dx, dy } = screenDeltaToFramePercent(clientX - drag.initX, clientY - drag.initY, metrics)
+
+  if (drag.type === 'move') {
+    return { offsetX: drag.initOffsetX + dx, offsetY: drag.initOffsetY + dy, scale: drag.initScale }
+  }
+
+  // Resize from a corner: project the pointer delta onto the corner's outward
+  // diagonal so dragging away from the box grows it and toward it shrinks it.
+  // Percent-of-frame ÷ 100 = fraction of frame, used as a proportional nudge on
+  // the starting scale — same shape as the overlay hook's corner resize.
+  const corner = drag.type.slice('resize-'.length) as CaptionCorner
+  const sx = corner.includes('e') ? 1 : -1
+  const sy = corner.includes('s') ? 1 : -1
+  const delta = (dx * sx + dy * sy) / 100
+  const scale = Math.min(CAPTION_MAX_SCALE, Math.max(CAPTION_MIN_SCALE, drag.initScale * (1 + delta)))
+  return { offsetX: drag.initOffsetX, offsetY: drag.initOffsetY, scale }
+}
+
+/**
+ * The patch to commit on mouseup — only the fields the gesture actually
+ * changed, so a move never rewrites `scale` (and vice versa) and the resulting
+ * undo step reads as what the operator did.
+ */
+export function captionDragPatch(
+  drag: CaptionDragState,
+  geom: CaptionGeometry,
+): Pick<CaptionSegment, 'offsetX' | 'offsetY' | 'scale'> {
+  return drag.type === 'move'
+    ? { offsetX: geom.offsetX, offsetY: geom.offsetY }
+    : { scale: geom.scale }
+}

package/src/video/timeline/CaptionTrackRow.tsx

@@ -0,0 +1,235 @@
+// CaptionTrackRow — the caption track's own row in the timeline.
+//
+// Captions are NOT part of `tracks[]` (see schema.ts / the plan) — this row
+// reads and writes `project.captions` directly, keeping that special-track
+// data model intact. One block per segment, positioned on the shared timeline
+// scale exactly like VisualTrackRow/AudioTrackRow (same `pct()` + context —
+// never a locally-computed px-per-second).
+//
+// Selection is unified with the preview's caption selection box
+// (`selectedCaptionId`/`onSelectCaption`, both owned by VideoEditor — see
+// ReviewSurface) and is mutually exclusive with the normal item-selection
+// model (`selectedIds`): the two never show handles at once. This row only
+// owns the caption→item half of that rule at the CALL site (clicking a block
+// below calls `onSelectCaption`, same as the preview's click); the actual
+// "also clear selectedIds" side effect lives in VideoEditor's wrapped
+// `onSelectCaption`, since a caption can be selected from the preview too,
+// outside this row entirely. Timeline.handleSelectItem owns the other half
+// (clearing `selectedCaptionId` when a normal item is selected).
+//
+// Editing a segment's text (double-click) and retiming it (drag an edge) both
+// funnel through the single `onCaptionSegmentChange(id, patch)` callback
+// (VideoEditor's `handleCaptionSegmentChange`, which wraps `makeCaptionEdit` +
+// `sync.mutate`). That function pushes ONE undo entry and enqueues ONE save
+// PER CALL, so — unlike VisualTrackRow, which calls its per-tick
+// `onProjectChange` on every mousemove during a resize — a drag here stays
+// entirely in local state (`live`) until mouseup, where `onCaptionSegmentChange`
+// fires exactly once. This mirrors CaptionPreview's drag lifecycle (the
+// sibling caption-editing surface), which does the same for the same reason.
+import { useEffect, useRef, useState } from 'react'
+import type { CaptionSegment, Captions } from '../../schema'
+import { pct, trackRow } from './utils'
+import { useTimelineContext } from './TimelineContext'
+import PlayheadLine from './PlayheadLine'
+import { useItemDragDrop } from './useItemDragDrop'
+import type { Draggable, DragEventContext } from './useItemDragDrop'
+import { EditableSegment } from './EditableSegment'
+import type { CaptionEditPatch } from './makeCaptionEdit'
+
+interface CaptionTrackRowProps {
+  captionTrack: Captions | undefined
+  /** Project frame rate — needed only to make the click-seek land INSIDE the
+   *  clicked segment once the preview quantizes the clock (see the click
+   *  handler below). */
+  fps: number
+  /** Shared selection id — see the file header. Null when nothing is selected. */
+  selectedCaptionId: string | null
+  onSelectCaption?: (id: string | null) => void
+  /** The single commit channel for both text edits and retiming. */
+  onCaptionSegmentChange?: (segmentId: string, patch: CaptionEditPatch) => void
+}
+
+export default function CaptionTrackRow({ captionTrack, fps, selectedCaptionId, onSelectCaption, onCaptionSegmentChange }: CaptionTrackRowProps) {
+  const { totalDuration, snapBoundaries, scrollRef, zoomRef, overlayDraggedRef, clock } = useTimelineContext()
+  const { beginResize } = useItemDragDrop({
+    totalDuration,
+    snapBoundaries,
+    scrollRef,
+    zoomRef,
+    draggedFlagRef: overlayDraggedRef,
+  })
+
+  // In-flight edge-drag geometry for the dragged segment only, keyed by id so a
+  // stale `live` from a previous gesture can never leak onto a different
+  // segment. Never written to the project mid-drag — see file header.
+  const [live, setLive] = useState<{ id: string; start: number; end: number } | null>(null)
+  // Which segment's text is currently in the contentEditable state (double-
+  // click to enter, blur to exit). At most one at a time — no multi-edit.
+  const [editingId, setEditingId] = useState<string | null>(null)
+
+  const segments = captionTrack?.segments ?? []
+
+  // Empty state: no `project.captions`, or a track with zero segments. Still
+  // rendered (not `null`) so the operator can see captions exist as a concept
+  // even before any exist.
+  if (segments.length === 0) {
+    return (
+      <div className={trackRow}>
+        <PlayheadLine />
+        <div className="absolute inset-0 flex items-center px-2 pointer-events-none">
+          <span className="text-[10px] text-gray-500 italic select-none">Captions</span>
+        </div>
+      </div>
+    )
+  }
+
+  function handleEdgeDrag(e: React.MouseEvent, seg: CaptionSegment, edge: 'start' | 'end') {
+    if (!seg.id || !onCaptionSegmentChange) return
+    const segId = seg.id
+    const origStart = seg.start
+    const origEnd = seg.end
+    let committedValue = edge === 'start' ? origStart : origEnd
+
+    beginResize(e, seg as Draggable, edge, {
+      onLivePreview: ({ item: resized }: DragEventContext) => {
+        // `resized` is the hook's `{ ...seg, [edge]: <new value> }` — it spreads
+        // the full segment (text, words, offsets) because the hook is generic
+        // and doesn't know it's a caption. Read ONLY the one numeric field that
+        // changed; the rest of `resized` is discarded, never persisted.
+        committedValue = edge === 'start' ? resized.start : resized.end
+        setLive({
+          id: segId,
+          start: edge === 'start' ? committedValue : origStart,
+          end: edge === 'end' ? committedValue : origEnd,
+        })
+      },
+      onCommit: () => {
+        // `beginResize` commits unconditionally on mouseup — unlike `beginDrag`
+        // it has no travel threshold — so a bare click on the 6px edge handle
+        // lands here with the edge untouched. Committing that would push an
+        // undo entry and queue a save for an unchanged project, since
+        // onCaptionSegmentChange is a full `sync.mutate` (see file header).
+        if (committedValue === (edge === 'start' ? origStart : origEnd)) {
+          setLive(null)
+          return
+        }
+        // Patch carries ONLY the dragged edge — never `text` — so
+        // makeCaptionEdit never respreads word timings on a pure retime.
+        onCaptionSegmentChange(segId, edge === 'start' ? { start: committedValue } : { end: committedValue })
+        setLive(null)
+      },
+    })
+  }
+
+  return (
+    <div className={trackRow}>
+      <PlayheadLine />
+      {segments.map((seg) => {
+        // `live` must be checked for null FIRST: an id-less segment (seg.id
+        // === undefined, e.g. before backfillCaptionIds runs) would otherwise
+        // compare equal to a null `live` (undefined === undefined), making
+        // isLive true and dereferencing null on the next two lines.
+        const isLive = live !== null && live.id === seg.id
+        const start = isLive ? live.start : seg.start
+        const end = isLive ? live.end : seg.end
+        const isSelected = !!seg.id && selectedCaptionId === seg.id
+        const isEditing = !!seg.id && editingId === seg.id
+        // A segment briefly lacks an id in the window before VideoEditor's
+        // backfillCaptionIds effect mints one — `handleCaptionSegmentChange`
+        // only accepts a string id, so stay non-interactive until then (same
+        // guard CaptionPreview uses for its selection box).
+        const canInteract = !!seg.id
+
+        return (
+          <div
+            key={seg.id ?? `${seg.start}-${seg.end}`}
+            className={`absolute top-1 bottom-1 rounded flex items-center overflow-hidden
+              ${canInteract ? 'cursor-pointer' : ''}
+              ${isSelected ? 'bg-purple-600/70 ring-1 ring-inset ring-purple-300/80' : 'bg-purple-700/40 hover:bg-purple-600/50 border border-purple-500/40'}`}
+            style={{ left: `${pct(start, totalDuration)}%`, width: `${pct(end - start, totalDuration)}%` }}
+            onClick={(e) => {
+              e.stopPropagation()
+              if (!canInteract || overlayDraggedRef.current) return
+              onSelectCaption?.(seg.id!)
+              // Seek to the segment on a fresh select (not on re-clicking an
+              // already-selected block). Load-bearing: the preview only shows
+              // drag handles for the segment active AT THE PLAYHEAD, so
+              // selecting from here without seeking would select a segment the
+              // preview can't yet act on.
+              //
+              // Half a frame IN, not to `start` itself. CaptionPreview snaps the
+              // clock to the frame grid before running the templates' own
+              // `t >= start && t < end` test (`t = Math.round(currentTime * fps)
+              // / fps`), and caption starts are arbitrary floats out of Whisper.
+              // Seeking to exactly `start` rounds DOWN into the PREVIOUS segment
+              // whenever `start * fps` has a fractional part below 0.5 — about
+              // half of all segments (e.g. start 3.44 at 30fps → frame 103 →
+              // t 3.4333 < 3.44). `start + 0.5 / fps` puts `t` in
+              // [start, start + 1/fps), always inside: `beginResize` enforces a
+              // 0.1s floor on segment duration, so no segment is under a frame.
+              if (!isSelected) clock.set(start + 0.5 / fps)
+            }}
+            onDoubleClick={(e) => {
+              e.stopPropagation()
+              if (!canInteract) return
+              setEditingId(seg.id!)
+            }}
+          >
+            {canInteract && (
+              <div
+                className="absolute left-0 top-0 bottom-0 w-1.5 cursor-ew-resize z-10 hover:bg-purple-300/40"
+                onMouseDown={(e) => handleEdgeDrag(e, seg, 'start')}
+              />
+            )}
+            <span className="text-[10px] text-purple-100 truncate flex-1 min-w-0 px-2">
+              {isEditing ? (
+                <EditableSegmentAutofocus
+                  seg={seg}
+                  onEdit={(text) => onCaptionSegmentChange?.(seg.id!, { text })}
+                  onDone={() => setEditingId(null)}
+                />
+              ) : (
+                seg.text
+              )}
+            </span>
+            {canInteract && (
+              <div
+                className="absolute right-0 top-0 bottom-0 w-1.5 cursor-ew-resize z-10 hover:bg-purple-300/40"
+                onMouseDown={(e) => handleEdgeDrag(e, seg, 'end')}
+              />
+            )}
+          </div>
+        )
+      })}
+    </div>
+  )
+}
+
+// Wraps EditableSegment (unmodified — the same component TranscriptPanel uses)
+// with focus-on-mount. Double-click swaps a plain label for this contentEditable
+// span on the NEXT render, by which point the browser's native dblclick text
+// selection has already resolved against the old, non-editable element — so
+// without this the operator would need a third click just to place a cursor.
+function EditableSegmentAutofocus({ seg, onEdit, onDone }: { seg: CaptionSegment; onEdit: (text: string) => void; onDone: () => void }) {
+  const wrapRef = useRef<HTMLSpanElement>(null)
+
+  useEffect(() => {
+    const el = wrapRef.current?.querySelector<HTMLElement>('[contenteditable]')
+    if (!el) return
+    el.focus()
+    // Place the caret at the end rather than leaving it at the browser default
+    // (start), so continuing to type appends instead of interrupting mid-word.
+    const range = document.createRange()
+    range.selectNodeContents(el)
+    range.collapse(false)
+    const sel = window.getSelection()
+    sel?.removeAllRanges()
+    sel?.addRange(range)
+  }, [])
+
+  return (
+    <span ref={wrapRef} onBlur={onDone} onClick={(e) => e.stopPropagation()} onMouseDown={(e) => e.stopPropagation()}>
+      <EditableSegment seg={seg} onEdit={onEdit} />
+    </span>
+  )
+}

package/src/video/timeline/Timeline.tsx

@@ -11,7 +11,9 @@ import Scrubber from './Scrubber'
 import TranscriptPanel from './TranscriptPanel'
 import TranscriptModal from './TranscriptModal'
 import VisualTrackRow from './VisualTrackRow'
+import CaptionTrackRow from './CaptionTrackRow'
 import { deleteSelection, toggleSelection } from './multiSelectOps'
+import type { CaptionEditPatch } from './makeCaptionEdit'
 
 interface TimelineProps {
   project: Project
@@ -25,6 +27,13 @@ interface TimelineProps {
   /** Unified selection — covers both visual items and audio tracks. */
   selectedIds?: string[]
   onSelectIds?: (ids: string[]) => void
+  /** Selected caption segment id — shared with the preview's selection box.
+   *  Mutually exclusive with `selectedIds` (see CaptionTrackRow). */
+  selectedCaptionId?: string | null
+  onSelectCaption?: (id: string | null) => void
+  /** Commit a caption segment patch — text edit or edge-drag retime. Threaded
+   *  straight to CaptionTrackRow (see makeCaptionEdit.ts). */
+  onCaptionSegmentChange?: (segmentId: string, patch: CaptionEditPatch) => void
   onSplit?: (at: number) => void
   onCut?: (cut: { start: number; end: number }) => void
   onInspectClip?: (id: string) => void
@@ -57,12 +66,22 @@ interface TimelineProps {
 }
 
 
-export default function Timeline({ project, clock, onProjectChange, onCaptionEdit, onOverlayEdit, onEditOverlay, selectedIds = [], onSelectIds, onSplit, onCut, onInspectClip, onInspectAudio, rippleMode = false, getWaveformChunks, resolveFilePath, regenEnabled, isClipQueued, renderSubcutRegen, onRegenerateCaptions }: TimelineProps) {
+export default function Timeline({ project, clock, onProjectChange, onCaptionEdit, onOverlayEdit, onEditOverlay, selectedIds = [], onSelectIds, selectedCaptionId = null, onSelectCaption, onCaptionSegmentChange, onSplit, onCut, onInspectClip, onInspectAudio, rippleMode = false, getWaveformChunks, resolveFilePath, regenEnabled, isClipQueued, renderSubcutRegen, onRegenerateCaptions }: TimelineProps) {
   const primarySelectedId = selectedIds[0] ?? null
 
   // Click/shift-click handler — additive selection on shift or meta (cmd/ctrl).
+  // Also enforces the item→caption half of the two selection models' mutual
+  // exclusivity: selecting a real item clears `selectedCaptionId`, and so does
+  // clicking empty track space (id === null) — otherwise a "deselect all" click
+  // would clear the item handles but leave the caption's preview handles up,
+  // and since nothing else clears caption selection there would be no way to
+  // put a caption down at all. The other half (caption select clears
+  // `selectedIds`) lives in VideoEditor's wrapped `onSelectCaption`, since a
+  // caption can be selected from the preview too — outside Timeline entirely —
+  // not just from CaptionTrackRow.
   function handleSelectItem(id: string | null, additive: boolean) {
     if (!onSelectIds) return
+    onSelectCaption?.(null)
     if (id === null) { onSelectIds([]); return }
     onSelectIds(toggleSelection(selectedIds, id, additive))
   }
@@ -291,6 +310,17 @@ export default function Timeline({ project, clock, onProjectChange, onCaptionEdi
             <span>ffmpeg render — overlays are preview only, final text is burned by ffmpeg</span>
           </div>
         )}
+        {/* ── Caption track — its own row above the visual tracks. NOT part of
+            tracks[]; reads/writes project.captions directly (see
+            CaptionTrackRow's file header for the special-track rationale). ── */}
+        <CaptionTrackRow
+          captionTrack={captionTrack}
+          fps={project.settings?.fps ?? 30}
+          selectedCaptionId={selectedCaptionId}
+          onSelectCaption={onSelectCaption}
+          onCaptionSegmentChange={onCaptionSegmentChange}
+        />
+
         {[...allTracks].reverse().map((trackItems, reversedIdx) => {
           const trackIdx = allTracks.length - 1 - reversedIdx
           return (
@@ -388,7 +418,6 @@ export default function Timeline({ project, clock, onProjectChange, onCaptionEdi
           clock={clock}
           project={project}
           captionTrack={captionTrack}
-          onProjectChange={onProjectChange}
           onCaptionEdit={onCaptionEdit}
           onClose={() => setTranscriptModalOpen(false)}
         />

package/src/video/timeline/TranscriptModal.tsx

@@ -9,12 +9,17 @@ interface TranscriptModalProps {
   captionTrack: Project['captions'] | undefined
   currentTime: number
   project: Project
-  onProjectChange?: (project: Project) => void
+  // `onProjectChange` deliberately NOT accepted here: `makeCaptionEdit` fires
+  // both callbacks it's given with the same updated project (see
+  // makeCaptionEdit.ts), and a text edit only fires once (on blur), so there is
+  // no live-preview gesture to route through a second channel — only
+  // `onCaptionEdit` (the commit path) is needed. Accepting-but-ignoring it would
+  // invite a future call site to re-introduce the double-commit bug this fixed.
   onCaptionEdit?: (project: Project) => void
   onClose: () => void
 }
 
-export default function TranscriptModal({ captionTrack, currentTime, project, onProjectChange, onCaptionEdit, onClose }: TranscriptModalProps) {
+export default function TranscriptModal({ captionTrack, currentTime, project, onCaptionEdit, onClose }: TranscriptModalProps) {
   useEffect(() => {
     const onKey = (e: globalThis.KeyboardEvent) => { if (e.key === 'Escape') onClose() }
     document.addEventListener('keydown', onKey)
@@ -50,7 +55,9 @@ export default function TranscriptModal({ captionTrack, currentTime, project, on
               >
                 <span className="text-gray-600 text-[10px] font-mono shrink-0 w-12 pt-px">{formatTime(seg.start)}</span>
                 <span className={`text-sm leading-snug ${isActive ? 'text-white' : 'text-gray-300'}`}>
-                  <EditableSegment seg={seg} onEdit={makeCaptionEdit(i, project, onProjectChange, onCaptionEdit)} />
+                  {/* Commit-only — see the file-header note on why `onProjectChange`
+                      isn't accepted/passed here. */}
+                  <EditableSegment seg={seg} onEdit={makeCaptionEdit(i, project, undefined, onCaptionEdit)} />
                 </span>
               </div>
             )

package/src/video/timeline/TranscriptPanel.tsx

@@ -213,7 +213,13 @@ export default function TranscriptPanel({ project, captionTrack, currentTime, on
                 {vi > 0 && ' '}
                 <span className="text-gray-500 text-[10px] font-mono mr-1">{formatTime(seg.start)}</span>
                 <span className={isActive ? 'text-gray-900 dark:text-white' : 'text-gray-500 dark:text-gray-400'}>
-                  <EditableSegment seg={seg} onEdit={makeCaptionEdit(i, project, onProjectChange, onCaptionEdit)} />
+                  {/* Commit-only: `onProjectChange` is this component's LIVE-preview
+                      channel (see the fontsize/color controls above) — but a text
+                      edit fires once, on blur, and is already a complete, discrete
+                      change, not a continuous gesture. Passing both callbacks here
+                      would double-fire `sync.mutate` for one edit (two undo entries,
+                      two queued saves); `onCaptionEdit` is the single commit path. */}
+                  <EditableSegment seg={seg} onEdit={makeCaptionEdit(i, project, undefined, onCaptionEdit)} />
                 </span>
               </span>
             )