@bycrux/editor 0.9.0 → 0.11.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,11 @@ import type { OverlayFactory } from '../../types'
 import CaptionPreview from './CaptionPreview'
 import { getOverlayDesignCanvas } from '../design-canvas'
 import { useDragOverlay } from './useDragOverlay'
+import type { OverlayChanges } from './useDragOverlay'
+import type { CaptionEditPatch } from '../timeline/makeCaptionEdit'
 import OverlayItemsLayer from './OverlayItemsLayer'
 import { useVideoPlayback } from './useVideoPlayback'
+import { usePlaybackTime, type PlaybackClock } from '../playback-clock'
 import { sourceCropVideoStyle } from './sourceCropStyle'
 import CarouselPreview from './CarouselPreview'
 
@@ -14,32 +17,46 @@ 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
   watchFile?: (path: string, onChange: () => void) => () => void
   fileUrl: (path: string) => string
   resolveCaptionTemplate?: (style: string) => string
+  // Caption selection/positioning — pass-through to CaptionPreview. All optional:
+  // a host that omits them (PendingSurface) gets the historical passive,
+  // click-through caption layer.
+  selectedCaptionId?: string
+  onSelectCaption?: (id: string | null) => void
+  onCaptionSegmentChange?: (segmentId: string, patch: CaptionEditPatch) => void
 }
 
 export default function PreviewPlayer({
   project,
-  currentTime,
-  onTimeUpdate,
+  clock,
   selectedOverlayId,
   onOverlayChange,
+  onEditOverlay,
   compileOverlay,
   clearOverlayCache,
   watchFile,
   fileUrl,
   resolveCaptionTemplate,
+  selectedCaptionId,
+  onSelectCaption,
+  onCaptionSegmentChange,
 }: 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 +103,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 +319,7 @@ export default function PreviewPlayer({
         renderScale={renderScale}
         selectedOverlayId={selectedOverlayId}
         onOverlayChange={onOverlayChange}
+        onEditOverlay={onEditOverlay}
         containerRef={containerRef}
         dragState={dragState}
         setDragState={setDragState}
@@ -326,6 +344,9 @@ export default function PreviewPlayer({
           fps={project.settings?.fps ?? 30}
           compileOverlay={compileOverlay}
           resolveCaptionTemplate={resolveCaptionTemplate}
+          selectedCaptionId={selectedCaptionId}
+          onSelectCaption={onSelectCaption}
+          onCaptionSegmentChange={onCaptionSegmentChange}
         />
       )}
     </div>

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__/captionDragState.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect } from 'vitest'
+import {
+  CAPTION_DRAG_SLOP_PX,
+  CAPTION_MAX_SCALE,
+  CAPTION_MIN_SCALE,
+  captionDragGeometry,
+  captionDragPatch,
+  hasEscapedClickSlop,
+  readCaptionGeometry,
+  screenDeltaToFramePercent,
+  type CaptionDragState,
+  type CaptionFrameMetrics,
+} from '../captionDragState'
+
+const RENDER_W = 1080
+const RENDER_H = 1920
+
+/** Preview scale for a player rendered `px` wide (the ResizeObserver value). */
+function metrics(onScreenWidth: number): CaptionFrameMetrics {
+  return { previewScale: onScreenWidth / RENDER_W, renderW: RENDER_W, renderH: RENDER_H }
+}
+
+function drag(over: Partial<CaptionDragState> = {}): CaptionDragState {
+  return {
+    id: 'cap-0', type: 'move',
+    initX: 100, initY: 200,
+    initOffsetX: 0, initOffsetY: 0, initScale: 1,
+    ...over,
+  }
+}
+
+describe('readCaptionGeometry', () => {
+  it('applies the schema defaults', () => {
+    expect(readCaptionGeometry(undefined)).toEqual({ offsetX: 0, offsetY: 0, scale: 1 })
+    expect(readCaptionGeometry({})).toEqual({ offsetX: 0, offsetY: 0, scale: 1 })
+  })
+
+  it('preserves explicit zeros rather than falling back to the default', () => {
+    expect(readCaptionGeometry({ offsetX: 0, offsetY: -12, scale: 0.5 }))
+      .toEqual({ offsetX: 0, offsetY: -12, scale: 0.5 })
+  })
+})
+
+describe('screenDeltaToFramePercent', () => {
+  it('divides by the preview scale then converts to percent of frame', () => {
+    // Half-size preview: 54 screen px = 108 design px = 10% of 1080.
+    const { dx, dy } = screenDeltaToFramePercent(54, 96, metrics(540))
+    expect(dx).toBeCloseTo(10, 10)
+    expect(dy).toBeCloseTo(10, 10)
+  })
+
+  it('is independent of window size — the same fraction of the player is the same percent', () => {
+    // A drag of 25% of the player width must read 25% at any preview size.
+    for (const w of [270, 540, 1080, 1600]) {
+      const { dx } = screenDeltaToFramePercent(w * 0.25, 0, metrics(w))
+      expect(dx).toBeCloseTo(25, 10)
+    }
+  })
+
+  it('uses the frame HEIGHT for the vertical axis (non-square frames)', () => {
+    // 192 screen px at 1:1 = 192 design px = 10% of 1920, not 17.8% of 1080.
+    const { dy } = screenDeltaToFramePercent(0, 192, metrics(RENDER_W))
+    expect(dy).toBeCloseTo(10, 10)
+  })
+
+  it('returns a zero delta for degenerate metrics instead of NaN/Infinity', () => {
+    expect(screenDeltaToFramePercent(50, 50, { previewScale: 0, renderW: RENDER_W, renderH: RENDER_H })).toEqual({ dx: 0, dy: 0 })
+    expect(screenDeltaToFramePercent(50, 50, { previewScale: 1, renderW: 0, renderH: RENDER_H })).toEqual({ dx: 0, dy: 0 })
+    expect(screenDeltaToFramePercent(50, 50, { previewScale: NaN, renderW: RENDER_W, renderH: RENDER_H })).toEqual({ dx: 0, dy: 0 })
+  })
+})
+
+describe('captionDragGeometry — move', () => {
+  it('adds the total delta to the offset captured at drag start', () => {
+    const d = drag({ initOffsetX: 5, initOffsetY: -10 })
+    // 270 screen px right at half scale = 540 design px = 50% of 1080.
+    const g = captionDragGeometry(d, d.initX + 270, d.initY + 192, metrics(540))
+    expect(g.offsetX).toBeCloseTo(5 + 50, 10)
+    expect(g.offsetY).toBeCloseTo(-10 + 20, 10)
+    expect(g.scale).toBe(1)
+  })
+
+  it('accumulates from the gesture start, not from the previous sample (no drift)', () => {
+    const d = drag({ initOffsetX: 5 })
+    const m = metrics(540)
+    // Sampling the same pointer position twice, and sampling it after a detour,
+    // must both give the same answer — the function is a pure map from pointer
+    // position to geometry.
+    const a = captionDragGeometry(d, 400, 200, m)
+    captionDragGeometry(d, 999, 999, m)
+    const b = captionDragGeometry(d, 400, 200, m)
+    expect(b).toEqual(a)
+  })
+
+  it('is a no-op at the starting pointer position', () => {
+    const d = drag({ initOffsetX: 12, initOffsetY: 34, initScale: 1.5 })
+    expect(captionDragGeometry(d, d.initX, d.initY, metrics(540)))
+      .toEqual({ offsetX: 12, offsetY: 34, scale: 1.5 })
+  })
+})
+
+describe('captionDragGeometry — corner resize', () => {
+  const m = metrics(RENDER_W)  // 1:1, so screen px == design px
+
+  it('grows when dragging a corner outward and shrinks when dragging inward', () => {
+    const se = drag({ type: 'resize-se' })
+    expect(captionDragGeometry(se, se.initX + 108, se.initY, m).scale).toBeCloseTo(1.1, 10)
+    expect(captionDragGeometry(se, se.initX - 108, se.initY, m).scale).toBeCloseTo(0.9, 10)
+
+    // The NW corner's outward direction is up-left, so the signs invert.
+    const nw = drag({ type: 'resize-nw' })
+    expect(captionDragGeometry(nw, nw.initX - 108, nw.initY, m).scale).toBeCloseTo(1.1, 10)
+    expect(captionDragGeometry(nw, nw.initX + 108, nw.initY, m).scale).toBeCloseTo(0.9, 10)
+  })
+
+  it('sums both axes and scales proportionally from the starting scale', () => {
+    const d = drag({ type: 'resize-se', initScale: 2 })
+    // +10% of width and +10% of height → delta 0.2 → 2 * 1.2.
+    const g = captionDragGeometry(d, d.initX + 108, d.initY + 192, m)
+    expect(g.scale).toBeCloseTo(2.4, 10)
+  })
+
+  it('leaves the offsets untouched', () => {
+    const d = drag({ type: 'resize-ne', initOffsetX: 7, initOffsetY: -3 })
+    const g = captionDragGeometry(d, d.initX + 500, d.initY - 500, m)
+    expect(g.offsetX).toBe(7)
+    expect(g.offsetY).toBe(-3)
+  })
+
+  it('clamps to the scale bounds', () => {
+    const shrink = drag({ type: 'resize-se', initScale: 1 })
+    expect(captionDragGeometry(shrink, shrink.initX - 100_000, shrink.initY, m).scale).toBe(CAPTION_MIN_SCALE)
+    const grow = drag({ type: 'resize-se', initScale: 1 })
+    expect(captionDragGeometry(grow, grow.initX + 100_000, grow.initY, m).scale).toBe(CAPTION_MAX_SCALE)
+  })
+})
+
+describe('hasEscapedClickSlop', () => {
+  it('treats a small wobble as a click, not a drag', () => {
+    const d = drag()
+    expect(hasEscapedClickSlop(d, d.initX, d.initY)).toBe(false)
+    expect(hasEscapedClickSlop(d, d.initX + 2, d.initY + 2)).toBe(false)   // 2.83px
+    expect(hasEscapedClickSlop(d, d.initX + 3, d.initY + 3)).toBe(true)    // 4.24px
+  })
+
+  it('measures radially, not per axis', () => {
+    const d = drag()
+    expect(hasEscapedClickSlop(d, d.initX, d.initY + CAPTION_DRAG_SLOP_PX + 1)).toBe(true)
+    expect(hasEscapedClickSlop(d, d.initX - CAPTION_DRAG_SLOP_PX - 1, d.initY)).toBe(true)
+  })
+})
+
+describe('captionDragPatch', () => {
+  it('a move writes only the offsets', () => {
+    expect(captionDragPatch(drag(), { offsetX: 3, offsetY: 4, scale: 2 }))
+      .toEqual({ offsetX: 3, offsetY: 4 })
+  })
+
+  it('a resize writes only the scale', () => {
+    expect(captionDragPatch(drag({ type: 'resize-sw' }), { offsetX: 3, offsetY: 4, scale: 2 }))
+      .toEqual({ scale: 2 })
+  })
+})