@bycrux/editor 0.9.0 → 0.10.0

package/src/video/preview/OverlayPropsModal.tsx

@@ -0,0 +1,292 @@
+import { useEffect, useRef, useState, type ChangeEvent, type CSSProperties, type MouseEvent as ReactMouseEvent } from 'react'
+import { createPortal } from 'react-dom'
+import { cn, inspectorInputClass, SwatchInput } from '../../ui'
+import { inferOverlayPropFields, type PropField } from './overlay-prop-fields'
+
+// Remember the dialog's dragged position for the browser session, so it re-opens
+// where the operator left it instead of always at the default corner. Scoped to
+// sessionStorage (per-tab, survives reloads, clears when the tab closes) and
+// guarded so a non-browser/blocked-storage host degrades to the default.
+const POS_KEY = 'montaj.overlayPropsModal.pos'
+
+function loadSavedPos(): { x: number; y: number } | null {
+  try {
+    const raw = sessionStorage.getItem(POS_KEY)
+    if (!raw) return null
+    const p = JSON.parse(raw) as { x?: unknown; y?: unknown }
+    if (typeof p.x !== 'number' || typeof p.y !== 'number') return null
+    // Clamp into the current viewport so a saved spot never lands off-screen
+    // (e.g. after the window shrank), keeping the header grabbable.
+    return {
+      x: Math.min(Math.max(0, p.x), window.innerWidth - 120),
+      y: Math.min(Math.max(0, p.y), window.innerHeight - 60),
+    }
+  } catch {
+    return null
+  }
+}
+
+function saveSavedPos(p: { x: number; y: number }) {
+  try {
+    sessionStorage.setItem(POS_KEY, JSON.stringify(p))
+  } catch {
+    /* storage blocked/unavailable — position just won't persist */
+  }
+}
+
+interface Props {
+  itemProps: Record<string, unknown>
+  onSave: (next: Record<string, unknown>) => void
+  onClose: () => void
+  /** Live-preview every in-progress edit (no history/save) so the overlay
+   *  updates as the operator tweaks. Commit happens on Save; Cancel reverts. */
+  onPreview?: (next: Record<string, unknown>) => void
+  /** Resolve a workspace path to a servable URL (for image thumbnails). */
+  fileUrl?: (path: string) => string
+  /** Upload a picked file, returning its new workspace path (for image "change"). */
+  uploadFile?: (file: File) => Promise<string>
+}
+
+// Image prop control: a thumbnail preview plus a file picker that uploads the
+// chosen file (via the host adapter) and swaps the prop to the returned path.
+// When no uploadFile is available (non-Montaj host), it degrades to an editable
+// path text field so the value is still reachable.
+function ImageField({
+  name,
+  value,
+  fileUrl,
+  uploadFile,
+  onChange,
+}: {
+  name: string
+  value: string
+  fileUrl?: (path: string) => string
+  uploadFile?: (file: File) => Promise<string>
+  onChange: (v: string) => void
+}) {
+  const [busy, setBusy] = useState(false)
+  const [err, setErr] = useState<string | null>(null)
+  const preview = value ? (fileUrl ? fileUrl(value) : value) : ''
+
+  async function onPick(e: ChangeEvent<HTMLInputElement>) {
+    const file = e.target.files?.[0]
+    e.target.value = '' // let the same file be re-picked later
+    if (!file || !uploadFile) return
+    setBusy(true)
+    setErr(null)
+    try {
+      onChange(await uploadFile(file))
+    } catch (x) {
+      setErr(String(x))
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return (
+    <div className="flex items-center gap-3">
+      {preview ? (
+        <img
+          src={preview}
+          alt={name}
+          className="h-14 w-14 shrink-0 rounded-md border border-[var(--editor-border,#1f2937)] object-cover bg-black/20"
+        />
+      ) : (
+        <div className="flex h-14 w-14 shrink-0 items-center justify-center rounded-md border border-dashed border-[var(--editor-border,#1f2937)] text-[10px] text-[var(--editor-text)]/40">
+          none
+        </div>
+      )}
+      <div className="flex min-w-0 flex-1 flex-col gap-1">
+        <span className="truncate font-mono text-xs text-[var(--editor-text)]/70" title={value}>
+          {value ? value.split('/').pop() : '—'}
+        </span>
+        {uploadFile ? (
+          <label className="inline-flex w-fit cursor-pointer items-center gap-1.5 rounded-md border border-[var(--editor-border,#1f2937)] px-2.5 py-1 text-xs text-[var(--editor-text)]/80 hover:bg-white/5">
+            {busy ? 'Uploading…' : 'Change…'}
+            <input
+              type="file"
+              accept="image/*"
+              aria-label={name}
+              className="hidden"
+              onChange={onPick}
+              disabled={busy}
+            />
+          </label>
+        ) : (
+          <input
+            type="text"
+            aria-label={name}
+            value={value}
+            onChange={e => onChange(e.target.value)}
+            className={cn(inspectorInputClass, 'font-mono')}
+          />
+        )}
+        {err && <span className="text-[11px] text-red-400">{err}</span>}
+      </div>
+    </div>
+  )
+}
+
+export default function OverlayPropsModal({ itemProps, onSave, onClose, onPreview, fileUrl, uploadFile }: Props) {
+  const [draft, setDraft] = useState<PropField[]>(() => inferOverlayPropFields(itemProps))
+
+  // Floating, draggable panel (no dimming backdrop) so the overlay stays visible
+  // and updates live while editing. `pos` is null until first drag, then a
+  // fixed viewport position; the default anchors it top-right, off the centered
+  // preview.
+  const panelRef = useRef<HTMLDivElement>(null)
+  const [pos, setPos] = useState<{ x: number; y: number } | null>(() => loadSavedPos())
+  const [dragging, setDragging] = useState(false)
+  const grabRef = useRef({ dx: 0, dy: 0 })
+  const posRef = useRef<{ x: number; y: number } | null>(pos)
+
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose()
+    }
+    document.addEventListener('keydown', onKey)
+    return () => document.removeEventListener('keydown', onKey)
+  }, [onClose])
+
+  useEffect(() => {
+    if (!dragging) return
+    function onMove(e: MouseEvent) {
+      const np = { x: e.clientX - grabRef.current.dx, y: e.clientY - grabRef.current.dy }
+      posRef.current = np
+      setPos(np)
+    }
+    function onUp() {
+      setDragging(false)
+      if (posRef.current) saveSavedPos(posRef.current) // persist once, on drop
+    }
+    window.addEventListener('mousemove', onMove)
+    window.addEventListener('mouseup', onUp)
+    return () => {
+      window.removeEventListener('mousemove', onMove)
+      window.removeEventListener('mouseup', onUp)
+    }
+  }, [dragging])
+
+  function startDrag(e: ReactMouseEvent) {
+    const rect = panelRef.current?.getBoundingClientRect()
+    if (!rect) return
+    grabRef.current = { dx: e.clientX - rect.left, dy: e.clientY - rect.top }
+    setPos({ x: rect.left, y: rect.top })
+    setDragging(true)
+  }
+
+  function mergeProps(fields: PropField[]): Record<string, unknown> {
+    const next: Record<string, unknown> = { ...itemProps }
+    for (const f of fields) next[f.name] = f.value
+    return next
+  }
+
+  // Update one field and immediately preview the merged props (live) so the
+  // overlay reflects the edit without waiting for Save.
+  function setField(name: string, value: string | number | boolean) {
+    const nd = draft.map(f => (f.name === name ? { ...f, value } : f))
+    setDraft(nd)
+    onPreview?.(mergeProps(nd))
+  }
+
+  const panelStyle: CSSProperties = {
+    position: 'fixed',
+    ...(pos ? { left: pos.x, top: pos.y } : { top: 16, right: 16 }),
+    // The panel portals to <body>, outside the VideoEditor element that carries
+    // the --editor-* theme vars, so those are undefined here — give opaque
+    // fallbacks so the panel is solid, not see-through.
+    background: 'var(--editor-surface, #111827)',
+    borderColor: 'var(--editor-border, #1f2937)',
+    color: 'var(--editor-text, #f3f4f6)',
+  }
+
+  return createPortal(
+    <div
+      ref={panelRef}
+      className="z-50 w-96 max-h-[85vh] border rounded-xl shadow-2xl flex flex-col overflow-hidden"
+      style={panelStyle}
+    >
+      {/* Header — drag handle */}
+      <div
+        onMouseDown={startDrag}
+        className="flex cursor-move select-none items-center justify-between px-5 py-4 border-b border-[var(--editor-border,#1f2937)]"
+      >
+        <h2 className="text-sm font-semibold">Edit overlay</h2>
+        <button
+          onMouseDown={e => e.stopPropagation()}
+          onClick={onClose}
+          aria-label="Close"
+          className="opacity-55 hover:opacity-100 transition-opacity text-lg leading-none"
+        >
+          ×
+        </button>
+      </div>
+
+      {/* Fields */}
+      <div className="flex flex-col gap-3 px-5 py-4 overflow-y-auto">
+        {draft.map(f => (
+          <div key={f.name} className="flex flex-col gap-1">
+            <span className="text-[11px] uppercase tracking-wide text-[var(--editor-text)]/55">
+              {f.name}
+            </span>
+            {f.kind === 'boolean' ? (
+              <input
+                type="checkbox"
+                aria-label={f.name}
+                checked={f.value as boolean}
+                onChange={e => setField(f.name, e.target.checked)}
+                className="h-4 w-4 accent-[var(--editor-accent)]"
+              />
+            ) : f.kind === 'number' ? (
+              <input
+                type="number"
+                aria-label={f.name}
+                value={f.value as number}
+                onChange={e => setField(f.name, e.target.value === '' ? 0 : Number(e.target.value))}
+                className={cn(inspectorInputClass, 'text-right')}
+              />
+            ) : f.kind === 'color' ? (
+              <SwatchInput value={String(f.value)} ariaLabel={f.name} onChange={v => setField(f.name, v)} />
+            ) : f.kind === 'image' ? (
+              <ImageField
+                name={f.name}
+                value={String(f.value)}
+                fileUrl={fileUrl}
+                uploadFile={uploadFile}
+                onChange={v => setField(f.name, v)}
+              />
+            ) : (
+              <textarea
+                aria-label={f.name}
+                value={f.value as string}
+                rows={1}
+                onChange={e => setField(f.name, e.target.value)}
+                className={cn(inspectorInputClass, 'h-auto resize-y')}
+              />
+            )}
+          </div>
+        ))}
+        {draft.length === 0 && (
+          <p className="text-sm text-[var(--editor-text)]/55">This overlay has no editable props.</p>
+        )}
+      </div>
+
+      {/* Footer */}
+      <div className="flex items-center justify-end gap-2 px-5 py-3 border-t border-[var(--editor-border,#1f2937)]">
+        <button
+          onClick={onClose}
+          className="text-sm px-4 py-1.5 rounded-md border border-[var(--editor-border,#1f2937)] opacity-80 hover:opacity-100 hover:bg-white/5 transition-colors"
+        >
+          Cancel
+        </button>
+        <button
+          onClick={() => onSave(mergeProps(draft))}
+          className="text-sm px-4 py-1.5 rounded-md bg-[var(--editor-accent,#6366f1)] text-[var(--editor-accent-foreground,#ffffff)] hover:opacity-90 transition-colors"
+        >
+          Save
+        </button>
+      </div>
+    </div>,
+    document.body,
+  )
+}

package/src/video/preview/PreviewPlayer.tsx

@@ -5,8 +5,10 @@ import type { OverlayFactory } from '../../types'
 import CaptionPreview from './CaptionPreview'
 import { getOverlayDesignCanvas } from '../design-canvas'
 import { useDragOverlay } from './useDragOverlay'
+import type { OverlayChanges } from './useDragOverlay'
 import OverlayItemsLayer from './OverlayItemsLayer'
 import { useVideoPlayback } from './useVideoPlayback'
+import { usePlaybackTime, type PlaybackClock } from '../playback-clock'
 import { sourceCropVideoStyle } from './sourceCropStyle'
 import CarouselPreview from './CarouselPreview'
 
@@ -14,10 +16,10 @@ import CarouselPreview from './CarouselPreview'
 
 interface PreviewPlayerProps {
   project: Project
-  currentTime: number
-  onTimeUpdate: (t: number) => void
+  clock: PlaybackClock
   selectedOverlayId?: string
-  onOverlayChange?: (id: string, changes: { offsetX?: number; offsetY?: number; scale?: number; rotation?: number; fit?: 'cover' | 'contain' | 'fill' }) => void
+  onOverlayChange?: (id: string, changes: OverlayChanges) => void
+  onEditOverlay?: (id: string) => void
   // Adapter-injected capabilities
   compileOverlay: (src: string) => Promise<OverlayFactory>
   clearOverlayCache?: (src?: string) => void
@@ -28,10 +30,10 @@ interface PreviewPlayerProps {
 
 export default function PreviewPlayer({
   project,
-  currentTime,
-  onTimeUpdate,
+  clock,
   selectedOverlayId,
   onOverlayChange,
+  onEditOverlay,
   compileOverlay,
   clearOverlayCache,
   watchFile,
@@ -40,6 +42,11 @@ export default function PreviewPlayer({
 }: PreviewPlayerProps) {
   if (project.projectType === 'carousel') return <CarouselPreview project={project} />
 
+  // Subscribe to the playhead store. PreviewPlayer legitimately re-renders per
+  // tick — activeClip/cropStyle memos and the video/overlay/caption children all
+  // depend on the current time.
+  const currentTime = usePlaybackTime(clock)
+
   const [RENDER_W, RENDER_H] = getOverlayDesignCanvas(project.settings?.resolution)
 
   const containerRef = useRef<HTMLDivElement>(null)
@@ -86,7 +93,7 @@ export default function PreviewPlayer({
     clips,
     tracks0NonVideo,
     overlayTracks,
-  } = useVideoPlayback(project, currentTime, onTimeUpdate, fileUrl)
+  } = useVideoPlayback(project, currentTime, clock.set, fileUrl)
 
   const captionTrack = useMemo(() => project.captions, [project])
 
@@ -302,6 +309,7 @@ export default function PreviewPlayer({
         renderScale={renderScale}
         selectedOverlayId={selectedOverlayId}
         onOverlayChange={onOverlayChange}
+        onEditOverlay={onEditOverlay}
         containerRef={containerRef}
         dragState={dragState}
         setDragState={setDragState}

package/src/video/preview/__tests__/OverlayItemsLayer.edit.test.tsx

@@ -0,0 +1,106 @@
+/// <reference types="vitest/globals" />
+import { render, screen, fireEvent } from '@testing-library/react'
+import type { EditorProject, VisualItem } from '../../../schema'
+import type { OverlayFactory } from '../../../types'
+import OverlayItemsLayer from '../OverlayItemsLayer'
+
+// Mounts OverlayItemsLayer in isolation with the minimal prop surface it needs.
+// Mirrors the fake-adapter capability shims from VideoEditor.test.tsx
+// (compileOverlay resolves to a no-op factory), driving the preview layer
+// directly so the double-click → onEditOverlay routing is exercisable. The
+// props dialog itself now lives in VideoEditor, so the layer only reports the
+// intent via onEditOverlay.
+const emptySnap = { x: false, y: false, left: false, right: false, top: false, bottom: false }
+
+function makeProject(): EditorProject {
+  return {
+    id: 'p',
+    status: 'draft',
+    settings: { resolution: [1080, 1920], fps: 30 },
+    tracks: [[]],
+  } as unknown as EditorProject
+}
+
+function renderLayer(item: VisualItem, opts: { selected?: boolean } = {}) {
+  const onEditOverlay = vi.fn()
+  const onOverlayChange = vi.fn()
+  const containerRef = { current: document.createElement('div') }
+  const utils = render(
+    <OverlayItemsLayer
+      project={makeProject()}
+      currentTime={1}
+      isPlaying={false}
+      isCanvasProject={false}
+      overlayTracks={[[item]]}
+      tracks0NonVideo={[]}
+      renderScale={0.2}
+      selectedOverlayId={opts.selected === false ? undefined : item.id}
+      onOverlayChange={onOverlayChange}
+      onEditOverlay={onEditOverlay}
+      containerRef={containerRef}
+      dragState={null}
+      setDragState={vi.fn()}
+      liveOffset={null}
+      liveScale={null}
+      liveRotation={null}
+      snapGuides={emptySnap}
+      snapRotation={null}
+      compileOverlay={vi.fn(async (): Promise<OverlayFactory> => () => null)}
+      fileUrl={(pth: string) => pth}
+    />,
+  )
+  return { ...utils, onEditOverlay, onOverlayChange }
+}
+
+// The overlay's async compileOverlay resolves after each test's assertions,
+// flushing a CustomOverlay state update outside act(). Harmless fake-compiler
+// artifact; silence the console noise the way VideoEditor.test does.
+beforeEach(() => {
+  vi.spyOn(console, 'warn').mockImplementation(() => {})
+  vi.spyOn(console, 'error').mockImplementation(() => {})
+})
+afterEach(() => vi.restoreAllMocks())
+
+const overlayItem = (over: Partial<VisualItem> = {}): VisualItem => ({
+  id: 'overlay-1',
+  type: 'overlay',
+  src: 'o.jsx',
+  start: 0,
+  end: 10,
+  props: { homeName: 'x' },
+  ...over,
+} as VisualItem)
+
+describe('OverlayItemsLayer — double-click to edit overlay', () => {
+  it('double-clicking a selected JSX overlay requests the props dialog', () => {
+    const { container, onEditOverlay } = renderLayer(overlayItem())
+
+    // The overlay wrapper (outermost div) carries the onDoubleClick handler.
+    const wrapper = container.querySelector('div') as HTMLDivElement
+    fireEvent.dblClick(wrapper)
+
+    expect(onEditOverlay).toHaveBeenCalledWith('overlay-1')
+  })
+
+  it('does not request editing when the overlay is not selected', () => {
+    const { container, onEditOverlay } = renderLayer(overlayItem(), { selected: false })
+
+    const wrapper = container.querySelector('div') as HTMLDivElement
+    fireEvent.dblClick(wrapper)
+
+    expect(onEditOverlay).not.toHaveBeenCalled()
+  })
+
+  it('no longer renders an inline text editor or an in-layer pencil / modal', () => {
+    const { container } = renderLayer(overlayItem({ props: { text: 'Hi' } }))
+
+    const wrapper = container.querySelector('div') as HTMLDivElement
+    fireEvent.dblClick(wrapper)
+
+    // The dialog is owned by VideoEditor now: the layer neither inline-edits nor
+    // renders the modal or a floating pencil itself.
+    expect(screen.queryByRole('textbox')).toBeNull()
+    expect(screen.queryByRole('heading', { name: 'Edit overlay' })).toBeNull()
+    expect(screen.queryByRole('button', { name: 'Edit overlay props' })).toBeNull()
+  })
+})

package/src/video/preview/__tests__/OverlayPropsModal.test.tsx

@@ -0,0 +1,32 @@
+/// <reference types="vitest/globals" />
+import { render, screen, fireEvent } from '@testing-library/react'
+import OverlayPropsModal from '../OverlayPropsModal'
+
+const props = { homeName: 'Colombia', homeScore: 2, accent: '#FCD116', players: [{ n: 1 }] }
+
+test('renders a field per primitive prop and commits merged props', () => {
+  const onSave = vi.fn()
+  render(<OverlayPropsModal itemProps={props} onSave={onSave} onClose={() => {}} />)
+
+  const name = screen.getByLabelText('homeName')
+  fireEvent.change(name, { target: { value: 'Argentina' } })
+  const score = screen.getByLabelText('homeScore')
+  fireEvent.change(score, { target: { value: '3' } })
+  fireEvent.click(screen.getByRole('button', { name: /save/i }))
+
+  expect(onSave).toHaveBeenCalledWith({
+    homeName: 'Argentina',
+    homeScore: 3,            // number kind round-trips as number
+    accent: '#FCD116',
+    players: [{ n: 1 }],     // non-primitive prop preserved untouched
+  })
+})
+
+test('escape closes without saving', () => {
+  const onSave = vi.fn()
+  const onClose = vi.fn()
+  render(<OverlayPropsModal itemProps={props} onSave={onSave} onClose={onClose} />)
+  fireEvent.keyDown(document, { key: 'Escape' })
+  expect(onClose).toHaveBeenCalled()
+  expect(onSave).not.toHaveBeenCalled()
+})

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/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