@bycrux/editor 0.9.0 → 0.11.0

package/src/video/preview/__tests__/overlay-prop-fields.test.ts

@@ -0,0 +1,44 @@
+/// <reference types="vitest/globals" />
+import { inferOverlayPropFields } from '../overlay-prop-fields'
+
+test('infers kinds from values', () => {
+  const fields = inferOverlayPropFields({
+    homeName: 'Colombia',
+    homeScore: 2,
+    accent: '#FCD116',
+    muted: false,
+    players: [{ name: 'x' }],       // non-primitive: skipped
+    onClick: () => {},              // non-primitive: skipped
+    homeSrc: '/path/to/crest.png',  // image path → image kind
+  })
+  expect(fields).toEqual([
+    { name: 'homeName', kind: 'text', value: 'Colombia' },
+    { name: 'homeScore', kind: 'number', value: 2 },
+    { name: 'accent', kind: 'color', value: '#FCD116' },
+    { name: 'muted', kind: 'boolean', value: false },
+    { name: 'homeSrc', kind: 'image', value: '/path/to/crest.png' },
+  ])
+})
+
+test('detects image paths (extensions, query/hash, data URLs) vs plain text', () => {
+  const f = inferOverlayPropFields({
+    a: '/assets/logo.PNG',
+    b: 'https://cdn.x/y.jpg?v=2',
+    c: 'photo.webp#frag',
+    d: 'inline.svg',
+    e: 'data:image/png;base64,AAAA',
+    f: '/notes/readme.txt',   // not an image
+    g: 'just some words',     // not an image
+  })
+  expect(f.map(x => x.kind)).toEqual(['image', 'image', 'image', 'image', 'image', 'text', 'text'])
+})
+
+test('preserves insertion order and handles empty/absent props', () => {
+  expect(inferOverlayPropFields({})).toEqual([])
+  expect(inferOverlayPropFields(undefined)).toEqual([])
+})
+
+test('color detection is strict hex only', () => {
+  const f = inferOverlayPropFields({ a: '#ff0', b: '#FFAA00CC', c: '#xyz', d: 'red' })
+  expect(f.map(x => x.kind)).toEqual(['color', 'color', 'text', 'text'])
+})

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/preview/overlay-prop-fields.ts

@@ -0,0 +1,39 @@
+export type PropFieldKind = 'text' | 'number' | 'boolean' | 'color' | 'image'
+
+export interface PropField {
+  name: string
+  kind: PropFieldKind
+  value: string | number | boolean
+}
+
+const HEX_COLOR = /^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i
+// A string prop that points at an image: a workspace/URL path ending in a known
+// image extension (optionally with a query/hash), or a data: image URL. These
+// render as a thumbnail + file picker instead of a raw path text field.
+const IMAGE_PATH = /\.(?:png|jpe?g|webp|gif|svg|avif|bmp)(?:[?#].*)?$/i
+
+function stringKind(value: string): PropFieldKind {
+  if (HEX_COLOR.test(value)) return 'color'
+  if (IMAGE_PATH.test(value) || value.startsWith('data:image/')) return 'image'
+  return 'text'
+}
+
+/**
+ * Editable fields for an overlay item, inferred from its stored props.
+ * Primitive values only — objects, arrays, functions, null are skipped
+ * (they stay untouched in the props object on save). No schema needed,
+ * so AI-written profile overlays work the same as shipped templates.
+ *
+ * String values are sub-typed by shape: `#hex` → color picker, an image path
+ * → thumbnail + file picker, everything else → text.
+ */
+export function inferOverlayPropFields(props: Record<string, unknown> | undefined): PropField[] {
+  if (!props) return []
+  const fields: PropField[] = []
+  for (const [name, value] of Object.entries(props)) {
+    if (typeof value === 'boolean') fields.push({ name, kind: 'boolean', value })
+    else if (typeof value === 'number' && Number.isFinite(value)) fields.push({ name, kind: 'number', value })
+    else if (typeof value === 'string') fields.push({ name, kind: stringKind(value), value })
+  }
+  return fields
+}

package/src/video/preview/useDragOverlay.ts

@@ -1,8 +1,28 @@
 import { useEffect, useRef, useState } from 'react'
+import type { VisualItem } from '../../schema'
 
 export type Corner = 'nw' | 'ne' | 'sw' | 'se'
 export type DragType = 'move' | `resize-${Corner}` | 'rotate'
 
+// Shared shape for `onOverlayChange` across the preview layer: drag/resize/rotate
+// gestures (useDragOverlay) only ever populate the geometric subset; content-editing
+// callers (crop modal, future props/text editors) populate the rest. Callers pass a
+// partial — VideoEditor.handleOverlayChange merges whatever arrives into the item.
+export interface OverlayChanges {
+  offsetX?: number
+  offsetY?: number
+  scale?: number
+  rotation?: number
+  fit?: 'cover' | 'contain' | 'fill'
+  sourceCrop?: VisualItem['sourceCrop']
+  sourceWidth?: number
+  sourceHeight?: number
+  /** Full replacement for item.props (content editing). */
+  props?: Record<string, unknown>
+  /** Legacy text overlay items only. */
+  text?: string
+}
+
 const SNAP_THRESHOLD = 2.5  // % of container
 const ROT_SNAP_ANGLES = [0, 90, 180, 270]
 const ROT_ATTRACT_DEG = 5   // snap in within ±5°
@@ -25,7 +45,7 @@ interface DragState {
 
 export function useDragOverlay(
   containerRef: React.RefObject<HTMLDivElement | null>,
-  onOverlayChange?: (id: string, changes: { offsetX?: number; offsetY?: number; scale?: number; rotation?: number; fit?: 'cover' | 'contain' | 'fill' }) => void,
+  onOverlayChange?: (id: string, changes: OverlayChanges) => void,
 ) {
   const [dragState, setDragState] = useState<DragState | null>(null)
 

package/src/video/preview/useVideoPlayback.ts

@@ -291,15 +291,24 @@ export function useVideoPlayback(
     applyClipVolume(clip)
   }, [clips, activeSlot])
 
+  // maxEnd for the canvas rAF clock — the furthest overlay/caption end. Kept in
+  // a ref, updated by its own cheap effect, so the rAF effect below doesn't tear
+  // down and rebuild on every project spread (only isPlaying/onTimeUpdate matter
+  // to it). onTimeUpdate is the stable clock.set identity.
+  const canvasMaxEndRef = useRef(0)
   useEffect(() => {
-    if (!isCanvasProject) return
     const captionEnd = (project.captions?.segments ?? []).reduce((m: number, s) => Math.max(m, s.end), 0)
-    const maxEnd = Math.max(
+    canvasMaxEndRef.current = Math.max(
       overlayTracks.flat().reduce((m, i) => Math.max(m, i.end), 0),
       captionEnd,
     )
+  }, [overlayTracks, project.captions])
+
+  useEffect(() => {
+    if (!isCanvasProject) return
 
     function tick(ms: number) {
+      const maxEnd = canvasMaxEndRef.current
       if (rafLastMs.current !== null) {
         const dt   = (ms - rafLastMs.current) / 1000
         const next = Math.min(lastTimeRef.current + dt, maxEnd)
@@ -327,7 +336,7 @@ export function useVideoPlayback(
     return () => {
       if (rafRef.current) cancelAnimationFrame(rafRef.current)
     }
-  }, [isPlaying, isCanvasProject, overlayTracks, project, onTimeUpdate])
+  }, [isPlaying, isCanvasProject, onTimeUpdate])
 
   // ── Multi-track audio management ───────────────────────────────────────────
   // Derive unmuted tracks. The full tracks array is a new reference on every

package/src/video/timeline/AudioTrackRow.tsx

@@ -5,12 +5,13 @@
 // cross-lane drag, edge trim, mute toggle, inline volume, delete,
 // click-to-select, and inspect button.
 
-import { useEffect, useRef, useState } from 'react'
+import { memo, useEffect, useRef, useState } from 'react'
 import { Volume2, VolumeX, Trash2, Info } from 'lucide-react'
 import type { AudioTrack } from '../../schema'
 import type { Project } from '../../types'
 import { pct } from './utils'
 import { useTimelineContext } from './TimelineContext'
+import PlayheadLine from './PlayheadLine'
 import { useItemDragDrop } from './useItemDragDrop'
 import type { Draggable, DragEventContext } from './useItemDragDrop'
 import AudioWaveformLayer from './AudioWaveformLayer'
@@ -46,7 +47,7 @@ function updateAudioTrack(project: Project, trackId: string, changes: Partial<Au
   }
 }
 
-export default function AudioTrackRow({
+function AudioTrackRow({
   tracks,
   laneIndex,
   laneCount,
@@ -61,7 +62,6 @@ export default function AudioTrackRow({
 }: AudioTrackRowProps) {
   const {
     totalDuration,
-    currentTime,
     snapBoundaries,
     scrollRef,
     overlayDraggedRef,
@@ -78,11 +78,7 @@ export default function AudioTrackRow({
 
   return (
     <div className="relative h-10 bg-gray-100 dark:bg-gray-900 rounded overflow-hidden cursor-pointer">
-      {/* Playhead line */}
-      <div
-        className="absolute top-0 bottom-0 w-[2px] bg-red-500 pointer-events-none z-10"
-        style={{ left: `${pct(currentTime, totalDuration)}%` }}
-      />
+      <PlayheadLine />
       {tracks.map(track => (
         <AudioTrackItem
           key={track.id}
@@ -139,6 +135,8 @@ export default function AudioTrackRow({
   )
 }
 
+export default memo(AudioTrackRow)
+
 // ── Single audio item within a lane ──────────────────────────────────────────
 
 interface AudioTrackItemProps {

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/PlayheadLine.tsx

@@ -0,0 +1,18 @@
+import { useTimelineContext } from './TimelineContext'
+import { usePlaybackTime } from '../playback-clock'
+import { pct } from './utils'
+
+/** Leaf playhead indicator: the ONLY per-tick subscriber inside track rows.
+ *  Isolating the clock subscription here means VisualTrackRow/AudioTrackRow
+ *  (and everything else in a row) no longer re-render on every playback tick. */
+export default function PlayheadLine() {
+  const { clock, totalDuration } = useTimelineContext()
+  const currentTime = usePlaybackTime(clock)
+  if (totalDuration === 0) return null
+  return (
+    <div
+      className="absolute top-0 bottom-0 w-[2px] bg-red-500 pointer-events-none z-10"
+      style={{ left: `${pct(currentTime, totalDuration)}%` }}
+    />
+  )
+}