@bycrux/editor 0.10.0 → 0.11.1

package/src/video/preview/CaptionPreview.tsx

@@ -10,28 +10,156 @@
  * The caption layer is sized at the native render resolution (1080 × 1920) and
  * scaled down to fit the player via ResizeObserver so pixel values are 1:1 with
  * the render output.
+ *
+ * Per-segment positioning
+ * -----------------------
+ * The caption layer itself stays `pointer-events-none` at all times — the
+ * template DOM is arbitrary per style AND changes per frame (word-by-word swaps
+ * its content every few frames), so it is not something that can be hit-tested
+ * reliably. Instead the rendered caption's bounding box is *measured* and a
+ * separate interactive selection box is drawn over it (z 50, the same layer the
+ * overlay handles use). That box is the only interactive element: clicking it
+ * selects the segment active at the playhead, dragging it moves the segment
+ * (offsetX/offsetY), and dragging a corner scales it (scale).
  */
 
-import { useEffect, useRef, useState } from 'react'
+import { useEffect, useLayoutEffect, useRef, useState } from 'react'
 import type { Captions } from '../../schema'
 import type { OverlayFactory } from '../../types'
 import OverlayErrorBoundary from '../../carousel/OverlayErrorBoundary'
+import type { CaptionEditPatch } from '../timeline/makeCaptionEdit'
+import {
+  captionDragGeometry,
+  captionDragPatch,
+  hasEscapedClickSlop,
+  readCaptionGeometry,
+  type CaptionDragState,
+  type CaptionGeometry,
+} from './captionDragState'
 
 const RENDER_W = 1080
 const RENDER_H = 1920
 
+// Screen-px padding added around the measured text so the selection box is
+// comfortably grabbable and its outline clears the templates' glyph shadows.
+const BOX_PAD = 6
+
+// Corner handles, as [corner, x fraction, y fraction] of the selection box.
+const CORNERS = [['nw', 0, 0], ['ne', 1, 0], ['sw', 0, 1], ['se', 1, 1]] as const
+
+// Screen px of the selection box that must stay inside the frame — see the
+// clamp in the layout effect for why a fully-offscreen box is unrecoverable.
+const BOX_KEEP_VISIBLE = 24
+
+/**
+ * Clamp one axis of the selection box so at least `BOX_KEEP_VISIBLE` px of it
+ * overlaps the frame. `pos` is the box's leading edge relative to the frame,
+ * `size` its extent on that axis, `extent` the frame's.
+ *
+ * A box entirely inside the frame is returned untouched: the clamp range
+ * [KEEP - size, extent - KEEP] contains every such position, since a fitting
+ * box has 0 >= KEEP - size and pos <= extent - size <= extent - KEEP.
+ */
+export function clampVisible(pos: number, size: number, extent: number): number {
+  const min = BOX_KEEP_VISIBLE - size
+  const max = extent - BOX_KEEP_VISIBLE
+  // A frame smaller than the keep-visible margin inverts the range; leave the
+  // position alone rather than snapping it to a meaningless bound.
+  if (max < min) return pos
+  return Math.max(min, Math.min(max, pos))
+}
+
+interface Rect { left: number; top: number; width: number; height: number }
+
+/**
+ * Union of the client rects of every painted text run (and replaced element)
+ * under `root`.
+ *
+ * Deliberately NOT `root.getBoundingClientRect()`: the template's own outermost
+ * element is a frame-sized `position: fixed; inset: 0` box (captionOuterStyle),
+ * so its rect — and the rect of any wrapper we put around it — is the entire
+ * preview, which would put the selection box around the whole frame. Walking to
+ * the text nodes is the only markup-agnostic way to find where the caption
+ * actually paints, and it costs nothing on a subtree this small.
+ *
+ * Returns null when nothing is painted (e.g. `pop` renders no word between two
+ * word windows), which is the signal to hide the selection box entirely.
+ */
+export function measureCaptionContentRect(root: HTMLElement): Rect | null {
+  const doc = root.ownerDocument
+  const walker = doc.createTreeWalker(root, NodeFilter.SHOW_TEXT | NodeFilter.SHOW_ELEMENT)
+  const range = doc.createRange()
+  let left = Infinity, top = Infinity, right = -Infinity, bottom = -Infinity
+
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    let rect: DOMRect | null = null
+    if (node.nodeType === Node.TEXT_NODE) {
+      if (!node.nodeValue?.trim()) continue
+      range.selectNodeContents(node)
+      rect = range.getBoundingClientRect()
+    } else {
+      // Replaced elements paint without text nodes. Everything else is a
+      // container whose box is either the frame-sized outer wrapper or a
+      // full-width anchor box — including them would defeat the point.
+      const tag = (node as Element).tagName?.toUpperCase()
+      if (tag !== 'IMG' && tag !== 'SVG' && tag !== 'VIDEO' && tag !== 'CANVAS') continue
+      rect = (node as Element).getBoundingClientRect()
+    }
+    if (!rect || (!rect.width && !rect.height)) continue
+    left   = Math.min(left,   rect.left)
+    top    = Math.min(top,    rect.top)
+    right  = Math.max(right,  rect.right)
+    bottom = Math.max(bottom, rect.bottom)
+  }
+
+  if (!Number.isFinite(left)) return null
+  return { left, top, width: right - left, height: bottom - top }
+}
+
 interface CaptionPreviewProps {
   track:                    Captions
   currentTime:              number
   fps:                      number
   compileOverlay:           (src: string) => Promise<OverlayFactory>
   resolveCaptionTemplate?:  (style: string) => string
+  /** Currently-selected caption segment id (shared with the timeline row). */
+  selectedCaptionId?:       string
+  /** Click on the selection box — selects the segment active at the playhead.
+   *  Accepts null for symmetry with the timeline row's copy of this callback
+   *  (VideoEditor supplies one handler to both); the preview only ever passes
+   *  an id, since it has no deselect affordance of its own. */
+  onSelectCaption?:         (id: string | null) => void
+  /** Commit a finished drag/resize onto one segment. */
+  onCaptionSegmentChange?:  (segmentId: string, patch: CaptionEditPatch) => void
 }
 
-export default function CaptionPreview({ track, currentTime, fps, compileOverlay, resolveCaptionTemplate }: CaptionPreviewProps) {
+export default function CaptionPreview({
+  track,
+  currentTime,
+  fps,
+  compileOverlay,
+  resolveCaptionTemplate,
+  selectedCaptionId,
+  onSelectCaption,
+  onCaptionSegmentChange,
+}: CaptionPreviewProps) {
   const wrapRef            = useRef<HTMLDivElement>(null)
+  const contentRef         = useRef<HTMLDivElement>(null)
+  const boxRef             = useRef<HTMLDivElement>(null)
   const [scale, setScale]  = useState<number | null>(null)
   const [factory, setFactory] = useState<OverlayFactory | null>(null)
+  const [hovered, setHovered] = useState(false)
+
+  // In-flight gesture + its live geometry. `live` is applied to the segment we
+  // hand the template (not to the project) so the caption moves under the
+  // cursor; the project is written once, on mouseup.
+  const [drag, setDrag] = useState<CaptionDragState | null>(null)
+  const [live, setLive] = useState<({ id: string } & CaptionGeometry) | null>(null)
+  const liveRef = useRef<typeof live>(null)
+  // Read through a ref so a host that passes a fresh callback identity per
+  // render can't re-subscribe the document listeners mid-gesture.
+  const changeRef = useRef(onCaptionSegmentChange)
+  changeRef.current = onCaptionSegmentChange
 
   // Scale the 1080×1920 render layer to fit the actual player size
   useEffect(() => {
@@ -59,6 +187,25 @@ export default function CaptionPreview({ track, currentTime, fps, compileOverlay
   const frame    = Math.round(currentTime * fps)
   const lastSeg  = track.segments[track.segments.length - 1]
 
+  // The segment the template is showing. Computed from `frame / fps` (not from
+  // currentTime) with the templates' own `>= start && < end` predicate, so the
+  // selection box can never address a different segment than the one on screen.
+  const t = fps > 0 ? frame / fps : 0
+  const activeSeg = track.segments.find(s => t >= s.start && t < s.end) ?? null
+
+  // Interactivity requires a stable segment id (backfilled by VideoEditor) and a
+  // host that wired at least one caption callback. Without both, the layer stays
+  // exactly as it was: a passive, click-through caption overlay.
+  const activeId    = activeSeg?.id
+  const canInteract = !!activeId && !!(onSelectCaption || onCaptionSegmentChange)
+  const isSelected  = canInteract && selectedCaptionId === activeId
+
+  // The box unmounts when the playhead leaves a segment, so a pending
+  // mouseleave never arrives and the hover hairline would carry over onto the
+  // next segment's box. Drop it whenever the target segment changes; a pointer
+  // that really is over the new box gets its mouseenter back on the next move.
+  useEffect(() => { setHovered(false) }, [activeId])
+
   // Theme props for the template: everything on the track except style/segments
   // (handled separately) and googleFonts (a render-time font-loading hint, not
   // a template prop). Normalize the legacy lowercase `fontsize` key to the
@@ -67,10 +214,114 @@ export default function CaptionPreview({ track, currentTime, fps, compileOverlay
   const themeProps: Record<string, unknown> = { ...theme }
   if (fontsize != null) themeProps.fontSize = fontsize
 
+  // Live drag preview: overlay the in-flight geometry onto the dragged segment
+  // only. The templates read offsetX/offsetY/scale straight off the segment, so
+  // this is all it takes for the caption to follow the cursor.
+  const segments = live
+    ? track.segments.map(s => (s.id === live.id ? { ...s, offsetX: live.offsetX, offsetY: live.offsetY, scale: live.scale } : s))
+    : track.segments
+
   const element  = (factory && scale !== null)
-    ? factory(frame, fps, Math.round((lastSeg?.end ?? 0) * fps), { segments: track.segments, ...themeProps })
+    ? factory(frame, fps, Math.round((lastSeg?.end ?? 0) * fps), { segments, ...themeProps })
     : null
 
+  // ── Gesture lifecycle ──────────────────────────────────────────────────────
+  // Mirrors useDragOverlay's shape (document-level listeners for the life of the
+  // gesture, live state during, one commit on mouseup) — see captionDragState.ts
+  // for why the maths is duplicated rather than shared.
+  useEffect(() => {
+    const d = drag
+    // `scale === null` is defensive only — a gesture can start only from the
+    // box, which renders only when `element` exists, which requires a measured
+    // scale. Kept so the metrics below can never be built from a null scale.
+    if (!d || scale === null) return
+    const metrics = { previewScale: scale, renderW: RENDER_W, renderH: RENDER_H }
+
+    function onMove(e: MouseEvent) {
+      // Inside the click slop the press is still just a selection click, so
+      // clear any live geometry — that also makes "drag out and back" cancel.
+      const next = hasEscapedClickSlop(d!, e.clientX, e.clientY)
+        ? { id: d!.id, ...captionDragGeometry(d!, e.clientX, e.clientY, metrics) }
+        : null
+      setLive(next)
+      liveRef.current = next
+    }
+    function onUp() {
+      // Only commit if the pointer actually moved — a bare click selects and
+      // must not push an undo step or queue a save.
+      const l = liveRef.current
+      if (l) changeRef.current?.(l.id, captionDragPatch(d!, l))
+      setDrag(null)
+      setLive(null)
+      liveRef.current = null
+    }
+
+    document.addEventListener('mousemove', onMove)
+    document.addEventListener('mouseup', onUp)
+    return () => {
+      document.removeEventListener('mousemove', onMove)
+      document.removeEventListener('mouseup', onUp)
+    }
+  }, [drag, scale])
+
+  function startGesture(type: CaptionDragState['type'], e: React.MouseEvent) {
+    if (!activeId) return
+    // Keep the mousedown from starting a text selection and from reaching the
+    // player's play/pause layer underneath.
+    e.preventDefault()
+    e.stopPropagation()
+    // Select and begin the gesture in the same press: unlike overlays (selected
+    // from the timeline) the preview box IS the caption's selection affordance,
+    // so requiring a separate click first would just cost a click.
+    if (selectedCaptionId !== activeId) onSelectCaption?.(activeId)
+    if (!onCaptionSegmentChange) return
+    const g = readCaptionGeometry(activeSeg)
+    setDrag({
+      id: activeId, type,
+      initX: e.clientX, initY: e.clientY,
+      initOffsetX: g.offsetX, initOffsetY: g.offsetY, initScale: g.scale,
+    })
+  }
+
+  // ── Selection box placement ────────────────────────────────────────────────
+  // Positioned imperatively (style writes on a ref) rather than through state:
+  // the caption content is re-measured after every render — which for
+  // word-by-word means every frame of playback — and routing that through
+  // setState would cost an extra render per frame and risk a measure→render→
+  // measure loop. No dependency array on purpose: it must run after *every*
+  // commit, since any of them (new frame, resize, live drag) can move the text.
+  useLayoutEffect(() => {
+    const box = boxRef.current
+    const root = wrapRef.current
+    const content = contentRef.current
+    if (!box || !root || !content) return
+    const rect = measureCaptionContentRect(content)
+    if (!rect || rect.width <= 0 || rect.height <= 0) {
+      box.style.display = 'none'
+      return
+    }
+    // Both rects are in client coords; the root is inset-0 of the player frame,
+    // so subtracting it gives offsets in the box's own positioning context.
+    const rootRect = root.getBoundingClientRect()
+    const w = rect.width  + BOX_PAD * 2
+    const h = rect.height + BOX_PAD * 2
+    // Keep a grabbable sliver of the box inside the frame. offsetX/offsetY are
+    // unbounded and there is no numeric reset control for captions (unlike
+    // overlays, which have OverlayPropsModal), so a segment dragged fully past
+    // the frame edge would have BOTH its text and its selection box clipped
+    // away by this wrapper's `overflow-hidden` — leaving no way to drag it back
+    // short of hand-editing project.json. Dragging is delta-based (see
+    // captionDragState.ts), so a clamped box still moves the segment correctly.
+    // Captions inside the frame are never clamped, so nothing else changes.
+    const left = clampVisible(rect.left - rootRect.left - BOX_PAD, w, rootRect.width)
+    const top  = clampVisible(rect.top  - rootRect.top  - BOX_PAD, h, rootRect.height)
+    box.style.display = 'block'
+    box.style.left    = `${left}px`
+    box.style.top     = `${top}px`
+    box.style.width   = `${w}px`
+    box.style.height  = `${h}px`
+  })
+
   return (
     // zIndex 45 keeps captions above the active <video> (z 1) and overlay items
     // (z `trackIdx + 12`, ≈12–20) — mirroring the final render, where the caption
@@ -81,7 +332,7 @@ export default function CaptionPreview({ track, currentTime, fps, compileOverlay
     <div ref={wrapRef} className="absolute inset-0 pointer-events-none overflow-hidden" style={{ zIndex: 45 }}>
       <OverlayErrorBoundary label={`caption: ${track.style}`} resetKey={track.style}>
         {element && scale !== null && (
-          <div style={{
+          <div ref={contentRef} style={{
             position:        'absolute',
             top: 0, left: 0,
             width:           RENDER_W,
@@ -93,6 +344,61 @@ export default function CaptionPreview({ track, currentTime, fps, compileOverlay
           </div>
         )}
       </OverlayErrorBoundary>
+
+      {/* Centre/middle snap guides. Same amber hairlines, same z 50, and the
+          same `drag.type === 'move'` gate the overlay layer uses, so a snapped
+          caption reads identically to a snapped overlay. Only the centre pair
+          exists here — caption edge snap is deliberately not implemented (its
+          geometry does not transfer; see captionDragState.ts). */}
+      {drag?.type === 'move' && live?.snapX && (
+        <div className="absolute top-0 bottom-0 left-1/2 w-px bg-amber-400 pointer-events-none" style={{ zIndex: 50 }} />
+      )}
+      {drag?.type === 'move' && live?.snapY && (
+        <div className="absolute left-0 right-0 top-1/2 h-px bg-amber-400 pointer-events-none" style={{ zIndex: 50 }} />
+      )}
+
+      {/* Selection box — the only interactive part of the caption layer. z 50
+          matches the overlay selection handles (see the layering note above);
+          the wrapper stays click-through so only the box itself catches events. */}
+      {element && canInteract && (
+        <div className="absolute inset-0" style={{ zIndex: 50, pointerEvents: 'none' }}>
+          <div
+            ref={boxRef}
+            onMouseDown={(e) => startGesture('move', e)}
+            onMouseEnter={() => setHovered(true)}
+            onMouseLeave={() => setHovered(false)}
+            style={{
+              // left/top/width/height are written by the layout effect above.
+              position:      'absolute',
+              display:       'none',
+              pointerEvents: 'auto',
+              touchAction:   'none',
+              cursor:        isSelected ? (drag?.type === 'move' ? 'grabbing' : 'grab') : 'pointer',
+              // Unselected captions show a hairline on hover only — a permanent
+              // outline around every caption would be noise during review.
+              outline:       isSelected ? '2px solid var(--editor-selection)'
+                           : hovered    ? '1px dashed var(--editor-selection)'
+                           : 'none',
+            }}
+          >
+            {isSelected && onCaptionSegmentChange && CORNERS.map(([corner, fx, fy]) => (
+              <div
+                key={corner}
+                onMouseDown={(e) => startGesture(`resize-${corner}`, e)}
+                style={{
+                  position: 'absolute',
+                  left: `calc(${fx * 100}% - 6px)`,
+                  top:  `calc(${fy * 100}% - 6px)`,
+                  width: 12, height: 12, backgroundColor: '#fff',
+                  border: '1.5px solid var(--editor-selection)', borderRadius: 2,
+                  cursor: corner === 'nw' || corner === 'se' ? 'nwse-resize' : 'nesw-resize',
+                  pointerEvents: 'auto', touchAction: 'none',
+                }}
+              />
+            ))}
+          </div>
+        </div>
+      )}
     </div>
   )
 }

package/src/video/preview/PreviewPlayer.tsx

@@ -6,6 +6,7 @@ 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'
@@ -26,6 +27,12 @@ interface PreviewPlayerProps {
   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({
@@ -39,6 +46,9 @@ export default function PreviewPlayer({
   watchFile,
   fileUrl,
   resolveCaptionTemplate,
+  selectedCaptionId,
+  onSelectCaption,
+  onCaptionSegmentChange,
 }: PreviewPlayerProps) {
   if (project.projectType === 'carousel') return <CarouselPreview project={project} />
 
@@ -334,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__/captionDragState.test.ts

@@ -0,0 +1,168 @@
+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', () => {
+    // 12/34 are both well outside the centre-snap radius, so the geometry is
+    // the untouched starting offsets. The move branch also reports whether each
+    // axis is currently snapped (see captionSnap.test.ts) — asserted here as
+    // false so this stays a genuine no-op check rather than an assertion about
+    // the return shape.
+    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, snapX: false, snapY: false })
+  })
+})
+
+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 })
+  })
+})