@bycrux/editor 0.6.4 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bycrux/editor",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "private": false,
   "type": "module",
   "exports": {

package/src/crop/VideoSourceCropModal.tsx

@@ -0,0 +1,276 @@
+import * as React from 'react'
+import { Crop, RectangleHorizontal, RectangleVertical, Square } from 'lucide-react'
+import type { VisualItem } from '../schema'
+import {
+  renderedSourceRect,
+  fractionToWrapperPx,
+  applyCropHandleDrag,
+  aspectLockedCornerResize,
+  translateCropPx,
+  type CropFraction,
+  type CropHandle,
+} from './crop-math'
+
+// Crop-proper modal for a tracks[0] video item. Its ONLY job is choosing which
+// rectangle of the SOURCE footage to keep (`sourceCrop`). Positioning and zoom of
+// the clip on the output canvas are NOT here — those are direct-manipulation
+// transforms on the preview (drag + resize handles), the same as overlays.
+//
+// Controls: drag the crop window to move it; drag handles to resize. "Free" gives
+// 8-handle free-form resize; the aspect presets lock the crop's shape (corner
+// handles only, aspect maintained). Commits `sourceCrop` on Apply; Cancel discards.
+
+const FREE_HANDLES: CropHandle[] = ['nw', 'n', 'ne', 'w', 'e', 'sw', 's', 'se']
+const CORNER_HANDLES: CropHandle[] = ['nw', 'ne', 'sw', 'se']
+const HANDLE_OFFSET: Record<CropHandle, { dx: 0 | 0.5 | 1; dy: 0 | 0.5 | 1; cursor: string }> = {
+  nw: { dx: 0,   dy: 0,   cursor: 'nw-resize' },
+  n:  { dx: 0.5, dy: 0,   cursor: 'n-resize'  },
+  ne: { dx: 1,   dy: 0,   cursor: 'ne-resize' },
+  w:  { dx: 0,   dy: 0.5, cursor: 'w-resize'  },
+  e:  { dx: 1,   dy: 0.5, cursor: 'e-resize'  },
+  sw: { dx: 0,   dy: 1,   cursor: 'sw-resize' },
+  s:  { dx: 0.5, dy: 1,   cursor: 's-resize'  },
+  se: { dx: 1,   dy: 1,   cursor: 'se-resize' },
+}
+
+const DEFAULT_CROP: CropFraction = { x: 0, y: 0, w: 1, h: 1 }
+
+// Shape locks for the crop rectangle (not output framing). `aspect` is the crop's
+// pixel width/height; null = free-form.
+type ShapeKey = 'free' | '1:1' | '16:9' | '9:16'
+const SHAPES: { key: ShapeKey; label: string; aspect: number | null; Icon: typeof Crop }[] = [
+  { key: 'free', label: 'Free', aspect: null,   Icon: Crop },
+  { key: '1:1',  label: '1:1',  aspect: 1,      Icon: Square },
+  { key: '16:9', label: '16:9', aspect: 16 / 9, Icon: RectangleHorizontal },
+  { key: '9:16', label: '9:16', aspect: 9 / 16, Icon: RectangleVertical },
+]
+
+const clamp01 = (v: number) => Math.min(1, Math.max(0, v))
+function clampFraction(c: CropFraction): CropFraction {
+  const x = clamp01(c.x)
+  const y = clamp01(c.y)
+  return { x, y, w: Math.min(1 - x, Math.max(0, c.w)), h: Math.min(1 - y, Math.max(0, c.h)) }
+}
+const cropCenter = (c: CropFraction) => ({ x: c.x + c.w / 2, y: c.y + c.h / 2 })
+
+export type VideoSourceCropModalProps = {
+  item: VisualItem
+  /** Resolve the clip's preview URL — `(item) => adapter.fileUrl(item.nobg_preview_src ?? item.normalizedSrc ?? item.src)`. */
+  resolveSrc: (item: VisualItem) => string
+  /** Commit the final crop (source fractions). */
+  onApply: (next: CropFraction) => void
+  /** Persist source intrinsic dims once known (when the item doesn't carry them). */
+  onSrcDimsLoaded: (dims: { width: number; height: number }) => void
+  /** Close without committing. */
+  onClose: () => void
+}
+
+export function VideoSourceCropModal({
+  item,
+  resolveSrc,
+  onApply,
+  onSrcDimsLoaded,
+  onClose,
+}: VideoSourceCropModalProps) {
+  const srcUrl = resolveSrc(item)
+
+  const [loadedDims, setLoadedDims] = React.useState<{ width: number; height: number } | null>(null)
+  const srcDims =
+    item.sourceWidth && item.sourceHeight
+      ? { width: item.sourceWidth, height: item.sourceHeight }
+      : loadedDims
+
+  const [crop, setCrop] = React.useState<CropFraction>(item.sourceCrop ?? DEFAULT_CROP)
+  const [shape, setShape] = React.useState<ShapeKey>('free')
+
+  const frameRef = React.useRef<HTMLDivElement>(null)
+  const [frameBox, setFrameBox] = React.useState<{ w: number; h: number }>({ w: 0, h: 0 })
+  React.useEffect(() => {
+    const el = frameRef.current
+    if (!el) return
+    const obs = new ResizeObserver(([entry]) => setFrameBox({ w: entry.contentRect.width, h: entry.contentRect.height }))
+    obs.observe(el)
+    return () => obs.disconnect()
+  }, [])
+
+  const rendered =
+    srcDims && frameBox.w > 0 && frameBox.h > 0
+      ? renderedSourceRect({ wrapperW: frameBox.w, wrapperH: frameBox.h, srcWidth: srcDims.width, srcHeight: srcDims.height })
+      : null
+  const windowPx = rendered ? fractionToWrapperPx({ crop, rendered }) : null
+
+  const aspectOf = (k: ShapeKey) => SHAPES.find(s => s.key === k)?.aspect ?? null
+  const lockedAspect = aspectOf(shape)
+
+  function selectShape(key: ShapeKey) {
+    const aspect = aspectOf(key)
+    setShape(key)
+    if (aspect == null || !srcDims) return // free: keep current crop
+    // Snap the current crop to the locked aspect, keeping its center; derive height
+    // from width so the crop's pixel aspect matches, then clamp into bounds.
+    const srcAspect = srcDims.width / srcDims.height
+    const center = cropCenter(crop)
+    let w = crop.w
+    let h = (w * srcAspect) / aspect
+    if (h > 1) { h = 1; w = (aspect * h) / srcAspect }
+    if (w > 1) { w = 1; h = (w * srcAspect) / aspect }
+    const x = Math.min(1 - w, Math.max(0, center.x - w / 2))
+    const y = Math.min(1 - h, Math.max(0, center.y - h / 2))
+    setCrop({ x, y, w, h })
+  }
+
+  // ── Pointer drag: pan (inside window) + resize (handles) ──
+  const drag = React.useRef<
+    | { kind: 'pan'; startClient: { x: number; y: number }; startCrop: CropFraction }
+    | { kind: 'handle'; handle: CropHandle; startClient: { x: number; y: number }; startCrop: CropFraction }
+    | null
+  >(null)
+
+  const onPanDown = (e: React.PointerEvent) => {
+    e.stopPropagation()
+    e.currentTarget.setPointerCapture?.(e.pointerId)
+    drag.current = { kind: 'pan', startClient: { x: e.clientX, y: e.clientY }, startCrop: crop }
+  }
+  const onHandleDown = (handle: CropHandle) => (e: React.PointerEvent) => {
+    e.stopPropagation()
+    e.currentTarget.setPointerCapture?.(e.pointerId)
+    drag.current = { kind: 'handle', handle, startClient: { x: e.clientX, y: e.clientY }, startCrop: crop }
+  }
+  const onPointerMove = (e: React.PointerEvent) => {
+    const d = drag.current
+    if (!d || !srcDims) return
+    const deltaPx = { x: e.clientX - d.startClient.x, y: e.clientY - d.startClient.y }
+    const common = { wrapperW: frameBox.w, wrapperH: frameBox.h, srcWidth: srcDims.width, srcHeight: srcDims.height }
+    if (d.kind === 'pan') {
+      setCrop(translateCropPx({ crop: d.startCrop, deltaPx, ...common }))
+    } else if (lockedAspect != null && (d.handle === 'nw' || d.handle === 'ne' || d.handle === 'sw' || d.handle === 'se')) {
+      setCrop(aspectLockedCornerResize({ handle: d.handle, initialCrop: d.startCrop, deltaPx, aspect: lockedAspect, ...common }))
+    } else {
+      setCrop(clampFraction(applyCropHandleDrag({ handle: d.handle, initialCrop: d.startCrop, deltaPx, ...common })))
+    }
+  }
+  const onPointerUp = () => { drag.current = null }
+
+  const handles = lockedAspect != null ? CORNER_HANDLES : FREE_HANDLES
+  const ready = !!rendered && !!windowPx
+
+  return (
+    <div
+      className="fixed inset-0 z-[300] flex items-center justify-center bg-black/70 p-6"
+      onPointerDown={onClose}
+    >
+      <div
+        className="flex w-full max-w-3xl flex-col gap-4 rounded-xl border border-[var(--editor-border)] bg-[var(--editor-surface)] p-5 shadow-2xl"
+        onPointerDown={(e) => e.stopPropagation()}
+      >
+        <div className="flex items-center justify-between">
+          <h2 className="text-sm font-semibold text-[var(--editor-text)]">Crop source</h2>
+          <span className="text-xs text-[var(--editor-text)]/50">Pick the part of the footage to keep — position &amp; zoom live on the canvas</span>
+        </div>
+
+        {/* Source frame + crop window */}
+        <div
+          ref={frameRef}
+          className="relative w-full overflow-hidden rounded-lg bg-black"
+          style={{ height: '56vh' }}
+          onPointerMove={onPointerMove}
+          onPointerUp={onPointerUp}
+        >
+          <video
+            src={srcUrl}
+            muted
+            playsInline
+            preload="auto"
+            onLoadedMetadata={(e) => {
+              const v = e.currentTarget
+              const dims = { width: v.videoWidth, height: v.videoHeight }
+              setLoadedDims(dims)
+              onSrcDimsLoaded(dims)
+            }}
+            style={{ position: 'absolute', inset: 0, width: '100%', height: '100%', objectFit: 'contain', pointerEvents: 'none' }}
+          />
+
+          {ready && windowPx && (
+            <>
+              <div
+                style={{
+                  position: 'absolute', inset: 0, background: 'rgba(0,0,0,0.55)', pointerEvents: 'none',
+                  clipPath: `polygon(0 0, 100% 0, 100% 100%, 0 100%, 0 0,
+                    ${windowPx.x}px ${windowPx.y}px,
+                    ${windowPx.x}px ${windowPx.y + windowPx.h}px,
+                    ${windowPx.x + windowPx.w}px ${windowPx.y + windowPx.h}px,
+                    ${windowPx.x + windowPx.w}px ${windowPx.y}px,
+                    ${windowPx.x}px ${windowPx.y}px)`,
+                }}
+              />
+              <div
+                onPointerDown={onPanDown}
+                style={{
+                  position: 'absolute', left: windowPx.x, top: windowPx.y, width: windowPx.w, height: windowPx.h,
+                  outline: '2px solid var(--editor-selection)', cursor: 'move', touchAction: 'none',
+                }}
+              />
+              {handles.map((handle) => {
+                const o = HANDLE_OFFSET[handle]
+                return (
+                  <div
+                    key={handle}
+                    data-testid={`crop-handle-${handle}`}
+                    onPointerDown={onHandleDown(handle)}
+                    style={{
+                      position: 'absolute',
+                      left: windowPx.x + o.dx * windowPx.w - 6,
+                      top: windowPx.y + o.dy * windowPx.h - 6,
+                      width: 12, height: 12, backgroundColor: '#fff',
+                      border: '1.5px solid var(--editor-selection)', borderRadius: 2,
+                      cursor: o.cursor, zIndex: 10, touchAction: 'none',
+                    }}
+                  />
+                )
+              })}
+            </>
+          )}
+        </div>
+
+        {/* Shape locks (constrain the crop rectangle; not output framing) */}
+        <div className="flex items-center gap-2">
+          {SHAPES.map(({ key, label, Icon }) => {
+            const active = shape === key
+            return (
+              <button
+                key={key}
+                onClick={() => selectShape(key)}
+                title={key === 'free' ? 'Free-form crop' : `Lock crop to ${label}`}
+                className={`flex items-center gap-1.5 rounded-md border px-3 py-1.5 text-xs font-medium transition-colors ${
+                  active
+                    ? 'border-[var(--editor-selection)] bg-[var(--editor-selection)]/15 text-[var(--editor-text)]'
+                    : 'border-[var(--editor-border)] text-[var(--editor-text)]/70 hover:text-[var(--editor-text)]'
+                }`}
+              >
+                <Icon size={14} />
+                {label}
+              </button>
+            )
+          })}
+        </div>
+
+        {/* Actions */}
+        <div className="flex items-center justify-end gap-2 pt-1">
+          <button
+            onClick={onClose}
+            className="rounded-md px-3 py-1.5 text-xs font-medium text-[var(--editor-text)]/70 hover:text-[var(--editor-text)] transition-colors"
+          >
+            Cancel
+          </button>
+          <button
+            onClick={() => { onApply(clampFraction(crop)); onClose() }}
+            disabled={!ready}
+            className="rounded-md bg-[var(--editor-accent)] px-3.5 py-1.5 text-xs font-medium text-[var(--editor-accent-foreground)] hover:opacity-90 disabled:opacity-40 transition-colors"
+          >
+            Apply crop
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/crop/__tests__/crop-math.test.ts

@@ -1,5 +1,5 @@
 /// <reference types="vitest/globals" />
-import { renderedSourceRect } from '../crop-math'
+import { renderedSourceRect, translateCropPx, cropForAspect, maxZoomForAspect, aspectLockedCornerResize } from '../crop-math'
 import { fractionToWrapperPx, wrapperPxToFraction } from '../crop-math'
 
 describe('renderedSourceRect', () => {
@@ -187,3 +187,96 @@ describe('applyCropHandleDrag', () => {
     expect(next.h).toBeCloseTo(0.5)
   })
 })
+
+describe('translateCropPx (pan)', () => {
+  const SRC = { wrapperW: 400, wrapperH: 400, srcWidth: 1000, srcHeight: 1000 } // square, no letterbox
+
+  it('moves the crop by the pixel delta in fractions', () => {
+    const next = translateCropPx({
+      crop: { x: 0.2, y: 0.2, w: 0.4, h: 0.4 },
+      deltaPx: { x: 40, y: -20 }, // 40/400 = +0.1 x, -20/400 = -0.05 y
+      ...SRC,
+    })
+    expect(next.x).toBeCloseTo(0.3)
+    expect(next.y).toBeCloseTo(0.15)
+    expect(next.w).toBeCloseTo(0.4)
+    expect(next.h).toBeCloseTo(0.4)
+  })
+
+  it('clamps so the crop stays fully inside the source (no size change)', () => {
+    const next = translateCropPx({
+      crop: { x: 0.7, y: 0.7, w: 0.4, h: 0.4 }, // right/bottom edge at 1.1 — already overflowing intent
+      deltaPx: { x: 1000, y: 1000 },
+      ...SRC,
+    })
+    // pinned to the far corner: x = 1 - w, y = 1 - h
+    expect(next.x).toBeCloseTo(0.6)
+    expect(next.y).toBeCloseTo(0.6)
+    expect(next.w).toBeCloseTo(0.4)
+    expect(next.h).toBeCloseTo(0.4)
+  })
+})
+
+describe('cropForAspect + maxZoomForAspect', () => {
+  it('9:16 crop from a 16:9 source → full height, narrow centered width', () => {
+    // source 1920x1080 (aspect 1.778), target 9/16=0.5625 < srcAspect → full height
+    const c = cropForAspect({ aspect: 9 / 16, zoom: 1, srcWidth: 1920, srcHeight: 1080 })
+    expect(c.h).toBeCloseTo(1)
+    // w = aspect/srcAspect = 0.5625 / 1.7778 = 0.3164
+    expect(c.w).toBeCloseTo((9 / 16) / (1920 / 1080), 3)
+    expect(c.x).toBeCloseTo((1 - c.w) / 2) // centered
+    expect(c.y).toBeCloseTo(0)
+  })
+
+  it('16:9 crop from a 16:9 source → the whole frame at zoom 1', () => {
+    const c = cropForAspect({ aspect: 16 / 9, zoom: 1, srcWidth: 1920, srcHeight: 1080 })
+    expect(c.w).toBeCloseTo(1)
+    expect(c.h).toBeCloseTo(1)
+  })
+
+  it('zoom shrinks the crop around its center', () => {
+    const c1 = cropForAspect({ aspect: 1, zoom: 1, srcWidth: 1000, srcHeight: 1000 })
+    const c2 = cropForAspect({ aspect: 1, zoom: 2, srcWidth: 1000, srcHeight: 1000 })
+    expect(c1.w).toBeCloseTo(1)
+    expect(c2.w).toBeCloseTo(0.5) // half size at 2×
+    expect(c2.x).toBeCloseTo(0.25) // still centered
+    expect(c2.y).toBeCloseTo(0.25)
+  })
+
+  it('maxZoomForAspect keeps the crop at/above the 2% floor', () => {
+    // 1:1 on a square source: base w=h=1, floor 0.02 → max zoom 50
+    const z = maxZoomForAspect({ aspect: 1, srcWidth: 1000, srcHeight: 1000 })
+    expect(z).toBeCloseTo(50)
+  })
+})
+
+describe('aspectLockedCornerResize', () => {
+  it('keeps the locked pixel aspect and anchors the opposite corner (se drag)', () => {
+    // square source 1000x1000 in a 400x400 frame → rendered fills the frame.
+    const next = aspectLockedCornerResize({
+      handle: 'se',
+      initialCrop: { x: 0.2, y: 0.2, w: 0.2, h: 0.2 }, // nw corner anchored at (0.2,0.2)
+      deltaPx: { x: 100, y: 0 },                        // drag se corner right
+      wrapperW: 400, wrapperH: 400, srcWidth: 1000, srcHeight: 1000,
+      aspect: 16 / 9,
+    })
+    expect(next.x).toBeCloseTo(0.2) // anchor held
+    expect(next.y).toBeCloseTo(0.2)
+    const pixelAspect = (next.w * 1000) / (next.h * 1000)
+    expect(pixelAspect).toBeCloseTo(16 / 9, 2)
+  })
+
+  it('shrinks to fit when the locked box would overflow the source bounds', () => {
+    const next = aspectLockedCornerResize({
+      handle: 'se',
+      initialCrop: { x: 0.1, y: 0.1, w: 0.2, h: 0.2 },
+      deltaPx: { x: 100000, y: 0 }, // absurd outward drag
+      wrapperW: 400, wrapperH: 400, srcWidth: 1000, srcHeight: 1000,
+      aspect: 16 / 9,
+    })
+    // stays within [0,1] and keeps the aspect
+    expect(next.x + next.w).toBeLessThanOrEqual(1.0001)
+    expect(next.y + next.h).toBeLessThanOrEqual(1.0001)
+    expect((next.w * 1000) / (next.h * 1000)).toBeCloseTo(16 / 9, 2)
+  })
+})

package/src/crop/crop-math.ts

@@ -123,3 +123,128 @@ export function applyCropHandleDrag(args: {
     rendered,
   })
 }
+
+// Move (pan) the crop window by a pixel delta, keeping its size and clamping so
+// it stays fully inside the rendered source rect. Used by the crop modal's
+// drag-to-reposition.
+export function translateCropPx(args: {
+  crop: CropFraction
+  deltaPx: { x: number; y: number }
+  wrapperW: number
+  wrapperH: number
+  srcWidth: number
+  srcHeight: number
+}): CropFraction {
+  const { crop, deltaPx, wrapperW, wrapperH, srcWidth, srcHeight } = args
+  const rendered = renderedSourceRect({ wrapperW, wrapperH, srcWidth, srcHeight })
+  const px = fractionToWrapperPx({ crop, rendered })
+
+  const minLeft = rendered.offsetX
+  const minTop = rendered.offsetY
+  const maxLeft = rendered.offsetX + rendered.width - px.w
+  const maxTop = rendered.offsetY + rendered.height - px.h
+
+  const left = Math.min(maxLeft, Math.max(minLeft, px.x + deltaPx.x))
+  const top = Math.min(maxTop, Math.max(minTop, px.y + deltaPx.y))
+
+  return wrapperPxToFraction({ px: { x: left, y: top, w: px.w, h: px.h }, rendered })
+}
+
+// Aspect-locked CORNER resize for the crop modal's shape-lock presets. Because
+// `renderedSourceRect` scales x and y uniformly, a crop's wrapper-px aspect equals
+// its source-pixel aspect — so we can lock the aspect directly in wrapper px. The
+// corner opposite the dragged handle stays fixed; the dragged corner follows the
+// pointer's dominant axis, and the other dimension is derived from `aspect`. Edge
+// handles aren't supported here (the modal hides them when an aspect is locked).
+export function aspectLockedCornerResize(args: {
+  handle: 'nw' | 'ne' | 'sw' | 'se'
+  initialCrop: CropFraction
+  deltaPx: { x: number; y: number }
+  wrapperW: number
+  wrapperH: number
+  srcWidth: number
+  srcHeight: number
+  aspect: number // target pixel aspect w/h
+}): CropFraction {
+  const { handle, initialCrop, deltaPx, wrapperW, wrapperH, srcWidth, srcHeight, aspect } = args
+  const rendered = renderedSourceRect({ wrapperW, wrapperH, srcWidth, srcHeight })
+  const px = fractionToWrapperPx({ crop: initialCrop, rendered })
+
+  const isW = handle === 'nw' || handle === 'sw'
+  const isN = handle === 'nw' || handle === 'ne'
+  // Opposite corner stays fixed.
+  const fixedX = isW ? px.x + px.w : px.x
+  const fixedY = isN ? px.y + px.h : px.y
+  // Dragged corner after the pointer delta.
+  const dragX = (isW ? px.x : px.x + px.w) + deltaPx.x
+
+  // Width is driven by the horizontal drag; height derived from the locked aspect.
+  const minW = MIN_FRACTION * rendered.width
+  let cw = Math.max(minW, Math.abs(dragX - fixedX))
+  let ch = cw / aspect
+
+  // Clamp the box to the rendered source bounds, preserving aspect (shrink to fit).
+  const dirX = isW ? -1 : 1
+  const dirY = isN ? -1 : 1
+  const maxW = dirX < 0 ? fixedX - rendered.offsetX : rendered.offsetX + rendered.width - fixedX
+  const maxH = dirY < 0 ? fixedY - rendered.offsetY : rendered.offsetY + rendered.height - fixedY
+  if (cw > maxW) { cw = maxW; ch = cw / aspect }
+  if (ch > maxH) { ch = maxH; cw = ch * aspect }
+
+  const left = dirX < 0 ? fixedX - cw : fixedX
+  const top = dirY < 0 ? fixedY - ch : fixedY
+  return wrapperPxToFraction({ px: { x: left, y: top, w: cw, h: ch }, rendered })
+}
+
+// Compute a centered crop with a fixed OUTPUT aspect (width/height in *pixels*,
+// e.g. 9/16) at a given zoom. `zoom` >= 1: 1 is the largest crop with that aspect
+// that fits the source; higher zooms shrink the crop (magnifying the output).
+// `center` (source fractions) is preserved where possible, then clamped so the
+// crop stays inside [0, 1]. Used by the crop modal's preset + zoom controls.
+export function cropForAspect(args: {
+  aspect: number
+  zoom: number
+  srcWidth: number
+  srcHeight: number
+  center?: { x: number; y: number }
+}): CropFraction {
+  const { aspect, srcWidth, srcHeight } = args
+  const srcAspect = srcWidth / srcHeight
+
+  // Largest crop fractions whose pixel aspect (w·srcW)/(h·srcH) equals `aspect`.
+  let w: number
+  let h: number
+  if (aspect >= srcAspect) {
+    // Crop is wider than the source → full source width, letterbox vertically.
+    w = 1
+    h = srcAspect / aspect
+  } else {
+    // Crop is taller than the source → full source height, pillarbox horizontally.
+    h = 1
+    w = aspect / srcAspect
+  }
+
+  const z = Math.max(1, args.zoom)
+  w = Math.min(1, w / z)
+  h = Math.min(1, h / z)
+
+  const cx = args.center?.x ?? 0.5
+  const cy = args.center?.y ?? 0.5
+  const x = Math.min(1 - w, Math.max(0, cx - w / 2))
+  const y = Math.min(1 - h, Math.max(0, cy - h / 2))
+  return { x, y, w, h }
+}
+
+// The smallest zoom (>= 1) that keeps a crop of the given aspect at or above the
+// 2% min-fraction floor on both axes — i.e. the max useful zoom for the slider.
+export function maxZoomForAspect(args: {
+  aspect: number
+  srcWidth: number
+  srcHeight: number
+}): number {
+  const base = cropForAspect({ ...args, zoom: 1 })
+  // base.w / z >= MIN_FRACTION  →  z <= base.w / MIN_FRACTION (same for h)
+  const zByW = base.w / MIN_FRACTION
+  const zByH = base.h / MIN_FRACTION
+  return Math.max(1, Math.min(zByW, zByH))
+}

package/src/types.ts

@@ -503,6 +503,20 @@ export interface VideoEditorProps<P extends Project = Project> {
    */
   assetsPlacement?: 'sidebar' | 'right' | 'bottom'
 
+  /**
+   * Opt a host OUT of the package's built-in toolbar Render button so it can
+   * place Render in its own chrome (e.g. the desktop OS editor's top header).
+   * When provided, the package: (a) hides the toolbar Render button, and (b)
+   * calls this callback once with a stable `openRender()` trigger that marks the
+   * project final, saves, and opens the package's RenderModal. The host stores
+   * that trigger and wires it to its own Render button.
+   *
+   * Default (prop omitted): the package renders Render in its toolbar — so Hub
+   * clients, which deliberately keep no render button in their own headers, are
+   * unaffected.
+   */
+  onProvideRenderTrigger?: (openRender: () => void) => void
+
   // ── Host-supplied Montaj-specific UI (render-prop seams) ──────────────────
   // The clip/audio inspector and the subcut-regeneration tool read host-only
   // fields (regenQueue, storyboard, the host's full Project) the package types

package/src/video/VideoEditor.tsx

@@ -1,7 +1,7 @@
-import { useEffect, useRef, useState } from 'react'
+import { useCallback, useEffect, useRef, useState } from 'react'
 import { Crop, Magnet } from 'lucide-react'
 import type { Project, VideoEditorProps } from '../types'
-import { VideoSourceCropOverlay } from '../crop/VideoSourceCropOverlay'
+import { VideoSourceCropModal } from '../crop/VideoSourceCropModal'
 import { getOverlayDesignCanvas } from './design-canvas'
 import { applyTheme, defaultMontajTheme } from '../theme'
 import { applyCutToItem, applyCutToTracks, collapseGaps, splitAtTime } from './cuts'
@@ -45,6 +45,7 @@ export default function VideoEditor<P extends Project = Project>({
   renderSubcutRegen,
   regenEnabled,
   isClipQueued,
+  onProvideRenderTrigger,
 }: Props<P>) {
   const emit = onProjectChange ?? (() => {})
 
@@ -93,6 +94,7 @@ export default function VideoEditor<P extends Project = Project>({
         renderSubcutRegen={renderSubcutRegen}
         regenEnabled={regenEnabled}
         isClipQueued={isClipQueued}
+        onProvideRenderTrigger={onProvideRenderTrigger}
       />
     </div>
   )
@@ -122,6 +124,7 @@ interface SurfaceProps<P extends Project> {
   getWaveformChunks?: VideoEditorProps<P>['adapter']['getWaveformChunks']
   resolveFilePath: (path: string) => string
   save: (p: P) => void
+  onProvideRenderTrigger?: VideoEditorProps<P>['onProvideRenderTrigger']
 }
 
 function PendingSurface<P extends Project>({
@@ -265,6 +268,7 @@ function ReviewSurface<P extends Project>({
   renderSubcutRegen,
   regenEnabled,
   isClipQueued,
+  onProvideRenderTrigger,
 }: SurfaceProps<P> & {
   renderClipInspector?: VideoEditorProps<P>['renderClipInspector']
   renderSubcutRegen?: VideoEditorProps<P>['renderSubcutRegen']
@@ -279,8 +283,8 @@ function ReviewSurface<P extends Project>({
   const [selectedIds, setSelectedIds] = useState<string[]>([])
   const primarySelectedId = selectedIds[0] ?? null
   const [rippleMode, setRippleMode]   = useState(false)
-  // Source-crop mode: when on, a VideoSourceCropOverlay is mounted over the
-  // preview for the selected tracks[0] video item. Cleared when selection changes.
+  // Source-crop mode: when on, the VideoSourceCropModal opens for the selected
+  // tracks[0] video item. Cleared when selection changes.
   const [cropMode, setCropMode]       = useState(false)
   const [renderOpen, setRenderOpen]   = useState(false)
   const [regenCaptionsOpen, setRegenCaptionsOpen] = useState(false)
@@ -288,22 +292,22 @@ function ReviewSurface<P extends Project>({
   // callbacks. A Montaj-agnostic { kind, id } selector, not a project entity.
   const [inspecting, setInspecting]   = useState<{ kind: 'clip' | 'audio'; id: string } | null>(null)
 
-  const { versions, restoring, setRestoring } = useVersionHistory(adapter, project)
+  // Render trigger — marks the project final, saves, and opens the RenderModal.
+  // Kept stable (latest project/onChange/save read via refs) so a host that
+  // places Render in its own header (onProvideRenderTrigger) can store the
+  // callback once without it going stale.
+  const projectRef         = useRef(project);         projectRef.current = project
+  const onProjectChangeRef = useRef(onProjectChange); onProjectChangeRef.current = onProjectChange
+  const saveRef            = useRef(save);            saveRef.current = save
+  const openRender = useCallback(() => {
+    const final = { ...projectRef.current, status: 'final' } as P
+    onProjectChangeRef.current(final)
+    saveRef.current(final)
+    setRenderOpen(true)
+  }, [])
+  useEffect(() => { onProvideRenderTrigger?.(openRender) }, [onProvideRenderTrigger, openRender])
 
-  // Measured pixel size of the preview's rendered video rect — fed to the crop
-  // overlay as its wrapper dims so renderedSourceRect letterboxes correctly.
-  const previewBoxRef = useRef<HTMLDivElement>(null)
-  const [previewBox, setPreviewBox] = useState<{ w: number; h: number }>({ w: 0, h: 0 })
-  useEffect(() => {
-    if (!cropMode) return
-    const el = previewBoxRef.current
-    if (!el) return
-    const obs = new ResizeObserver(([entry]) => {
-      setPreviewBox({ w: entry.contentRect.width, h: entry.contentRect.height })
-    })
-    obs.observe(el)
-    return () => obs.disconnect()
-  }, [cropMode])
+  const { versions, restoring, setRestoring } = useVersionHistory(adapter, project)
 
   // Repair caption segments whose words[] text has diverged from edited seg.text.
   // Inline caption edits update seg.text but not seg.words; this normalizes the
@@ -434,7 +438,6 @@ function ReviewSurface<P extends Project>({
         <div className="flex-1 flex items-center justify-center bg-black overflow-hidden p-2">
           {hasContent ? (
             <div
-              ref={previewBoxRef}
               className="relative h-full max-w-full"
               style={{ aspectRatio: (() => { const [w, h] = getOverlayDesignCanvas(project.settings?.resolution); return `${w} / ${h}` })() }}
             >
@@ -450,30 +453,6 @@ function ReviewSurface<P extends Project>({
                 fileUrl={adapter.fileUrl}
                 resolveCaptionTemplate={adapter.resolveCaptionTemplate}
               />
-              {/* Source-crop overlay — mounted over the preview for the selected
-                  tracks[0] video. Persists sourceCrop through handleOverlayChange. */}
-              {cropMode && cropTarget && (
-                <div className="absolute inset-0" style={{ zIndex: 200 }}>
-                  <VideoSourceCropOverlay
-                    item={cropTarget}
-                    resolveSrc={(it) => adapter.fileUrl(it.nobg_preview_src ?? it.src ?? '')}
-                    wrapperWidth={previewBox.w}
-                    wrapperHeight={previewBox.h}
-                    onChange={(next) => handleOverlayChange(cropTarget.id, {
-                      sourceCrop: {
-                        x: Math.min(1, Math.max(0, next.x)),
-                        y: Math.min(1, Math.max(0, next.y)),
-                        w: Math.min(1, Math.max(0, next.w)),
-                        h: Math.min(1, Math.max(0, next.h)),
-                      },
-                    })}
-                    onSrcDimsLoaded={(dims) => {
-                      if (cropTarget.sourceWidth && cropTarget.sourceHeight) return
-                      handleOverlayChange(cropTarget.id, { sourceWidth: dims.width, sourceHeight: dims.height })
-                    }}
-                  />
-                </div>
-              )}
             </div>
           ) : (
             <p className="text-[var(--editor-text)]/60 text-sm">No clips</p>
@@ -522,17 +501,16 @@ function ReviewSurface<P extends Project>({
           >
             <Crop size={12} />
           </button>
-          <button
-            onClick={() => {
-              const final = { ...project, status: 'final' } as P
-              onProjectChange(final)
-              save(final)
-              setRenderOpen(true)
-            }}
-            className="text-xs px-2.5 py-1 rounded-md bg-[var(--editor-accent)] text-[var(--editor-accent-foreground)] hover:opacity-90 transition-colors"
-          >
-            Render →
-          </button>
+          {/* Default placement. A host that sets onProvideRenderTrigger renders
+              Render in its own chrome instead, so the toolbar button is hidden. */}
+          {!onProvideRenderTrigger && (
+            <button
+              onClick={openRender}
+              className="text-xs px-2.5 py-1 rounded-md bg-[var(--editor-accent)] text-[var(--editor-accent-foreground)] hover:opacity-90 transition-colors"
+            >
+              Render →
+            </button>
+          )}
         </div>
 
         <div className="shrink-0 border-t border-[var(--editor-border)] bg-[var(--editor-surface)]">
@@ -606,6 +584,31 @@ function ReviewSurface<P extends Project>({
         </div>
       )}
 
+      {/* Source-crop modal — drag-to-pan, aspect presets, zoom. Commits
+          sourceCrop (+ source dims) to the selected tracks[0] video on Apply. */}
+      {cropMode && cropTarget && (
+        <VideoSourceCropModal
+          item={cropTarget}
+          // Prefer the conformed per-window cache (short, starts at the clip's
+          // first frame → loads instantly and shows a representative frame).
+          // Falls back to the bg-removed proxy, then the raw source.
+          resolveSrc={(it) => adapter.fileUrl(it.nobg_preview_src ?? it.normalizedSrc ?? it.src ?? '')}
+          onApply={(next) => handleOverlayChange(cropTarget.id, {
+            sourceCrop: {
+              x: Math.min(1, Math.max(0, next.x)),
+              y: Math.min(1, Math.max(0, next.y)),
+              w: Math.min(1, Math.max(0, next.w)),
+              h: Math.min(1, Math.max(0, next.h)),
+            },
+          })}
+          onSrcDimsLoaded={(dims) => {
+            if (cropTarget.sourceWidth && cropTarget.sourceHeight) return
+            handleOverlayChange(cropTarget.id, { sourceWidth: dims.width, sourceHeight: dims.height })
+          }}
+          onClose={() => setCropMode(false)}
+        />
+      )}
+
       {/* Render modal — adapter.render stream + host export controls */}
       {renderOpen && (
         <RenderModal

package/src/video/preview/PreviewPlayer.tsx

@@ -1,4 +1,5 @@
-import { useEffect, useMemo, useRef, useState } from 'react'
+import { useEffect, useMemo, useRef, useState, type PointerEvent as ReactPointerEvent, type WheelEvent as ReactWheelEvent } from 'react'
+import { videoTransformContainerStyle, videoTransformBoxPct, type VideoTransform } from './transformStyle'
 import type { EditorProject as Project } from '../../schema'
 import type { OverlayFactory } from '../../types'
 import CaptionPreview from './CaptionPreview'
@@ -119,6 +120,71 @@ export default function PreviewPlayer({
     ? { ...cropStyle }
     : { position: 'absolute' as const, inset: 0, width: '100%', height: '100%', objectFit: 'contain' as const }
 
+  // ── Base-video on-canvas transform (position + zoom) ─────────────────────────
+  // The selected tracks[0] video shows drag/resize handles like an overlay: drag
+  // to move (offsetX/offsetY), corner-drag or scroll to scale. Live during a
+  // pointer drag, committed on pointer-up via onOverlayChange; scroll commits
+  // directly. The <video> container reflects it (WYSIWYG with the renderer).
+  const selectedClip = useMemo(
+    () => clips.find(c => c.id === selectedOverlayId) ?? null,
+    [clips, selectedOverlayId],
+  )
+  const showVideoTransform = !isCanvasProject && !!selectedClip && selectedClip.id === activeClip?.id
+  const [liveXf, setLiveXf] = useState<VideoTransform | null>(null)
+  const xfDragRef = useRef<
+    | { kind: 'move'; startClient: { x: number; y: number }; start: VideoTransform }
+    | { kind: 'scale'; center: { x: number; y: number }; startDist: number; start: VideoTransform }
+    | null
+  >(null)
+  const baseXf: VideoTransform = {
+    scale: activeClip?.scale ?? 1,
+    offsetX: activeClip?.offsetX ?? 0,
+    offsetY: activeClip?.offsetY ?? 0,
+  }
+  const xf = liveXf ?? baseXf
+  const transformContainerStyle = videoTransformContainerStyle(xf)
+  const xfBox = videoTransformBoxPct(xf)
+
+  const onXfMoveDown = (e: ReactPointerEvent) => {
+    e.stopPropagation(); e.currentTarget.setPointerCapture?.(e.pointerId)
+    xfDragRef.current = { kind: 'move', startClient: { x: e.clientX, y: e.clientY }, start: baseXf }
+  }
+  const onXfScaleDown = (e: ReactPointerEvent) => {
+    e.stopPropagation(); e.currentTarget.setPointerCapture?.(e.pointerId)
+    const r = containerRef.current?.getBoundingClientRect()
+    if (!r) return
+    const center = { x: r.left + r.width / 2, y: r.top + r.height / 2 }
+    const startDist = Math.hypot(e.clientX - center.x, e.clientY - center.y) || 1
+    xfDragRef.current = { kind: 'scale', center, startDist, start: baseXf }
+  }
+  const onXfMove = (e: ReactPointerEvent) => {
+    const d = xfDragRef.current
+    if (!d) return
+    if (d.kind === 'move') {
+      const ox = (d.start.offsetX ?? 0) + ((e.clientX - d.startClient.x) / (frameSize.w || 1)) * 100
+      const oy = (d.start.offsetY ?? 0) + ((e.clientY - d.startClient.y) / (frameSize.h || 1)) * 100
+      setLiveXf({ ...d.start, offsetX: ox, offsetY: oy })
+    } else {
+      const dist = Math.hypot(e.clientX - d.center.x, e.clientY - d.center.y)
+      const s = Math.min(8, Math.max(0.2, (d.start.scale ?? 1) * (dist / d.startDist)))
+      setLiveXf({ ...d.start, scale: s })
+    }
+  }
+  const onXfUp = () => {
+    const live = liveXf
+    xfDragRef.current = null
+    setLiveXf(null)
+    if (live && selectedClip && onOverlayChange) {
+      onOverlayChange(selectedClip.id, { offsetX: live.offsetX, offsetY: live.offsetY, scale: live.scale })
+    }
+  }
+  const onXfWheel = (e: ReactWheelEvent) => {
+    if (!showVideoTransform || !selectedClip || !onOverlayChange) return
+    const factor = e.deltaY < 0 ? 1.06 : 1 / 1.06
+    const s = Math.min(8, Math.max(0.2, (activeClip?.scale ?? 1) * factor))
+    onOverlayChange(selectedClip.id, { scale: s })
+  }
+
   return (
     <div ref={containerRef} className="relative bg-black h-full max-w-full overflow-hidden rounded" style={{ aspectRatio: `${RENDER_W} / ${RENDER_H}`, isolation: 'isolate' }}>
       {isCanvasProject ? (
@@ -128,7 +194,10 @@ export default function PreviewPlayer({
           No clips
         </div>
       ) : (
-        <>
+        // Transform container — applies the active clip's scale/offset to both
+        // slots (the inactive one is invisible). The frame's overflow-hidden clips
+        // anything pushed outside. Mirrors the renderer's crop→scale→position.
+        <div className="absolute inset-0" style={transformContainerStyle}>
           {/* Slot 0 */}
           <video
             ref={video0Ref}
@@ -161,7 +230,45 @@ export default function PreviewPlayer({
             playsInline
             style={{ ...baseVideoStyle, opacity: showVideo && activeSlot === 1 ? 1 : 0, pointerEvents: activeSlot === 1 ? 'auto' : 'none', zIndex: activeSlot === 1 ? 1 : 0 }}
           />
-        </>
+        </div>
+      )}
+
+      {/* Base-video transform handles — drag to move, corner-drag or scroll to
+          zoom. Shown only when the on-screen clip is selected. Above the
+          play-toggle (z 10), below overlays (z 12+). */}
+      {showVideoTransform && (
+        <div className="absolute inset-0 pointer-events-none" style={{ zIndex: 11 }}>
+          <div
+            onPointerDown={onXfMoveDown}
+            onPointerMove={onXfMove}
+            onPointerUp={onXfUp}
+            onWheel={onXfWheel}
+            style={{
+              position: 'absolute',
+              left: `${xfBox.left}%`, top: `${xfBox.top}%`, width: `${xfBox.width}%`, height: `${xfBox.height}%`,
+              outline: '2px solid var(--editor-selection)', cursor: 'move', pointerEvents: 'auto', touchAction: 'none',
+            }}
+          />
+          {([['nw', 0, 0], ['ne', 1, 0], ['sw', 0, 1], ['se', 1, 1]] as const).map(([k, dx, dy]) => (
+            <div
+              key={k}
+              onPointerDown={onXfScaleDown}
+              onPointerMove={onXfMove}
+              onPointerUp={onXfUp}
+              style={{
+                position: 'absolute',
+                // Clamp into the frame so corners stay grabbable even when the box
+                // is scaled beyond the frame (scale uses pointer-distance, not the
+                // handle's position, so a clamped grab still scales correctly).
+                left: `calc(${Math.min(98, Math.max(2, xfBox.left + dx * xfBox.width))}% - 6px)`,
+                top: `calc(${Math.min(98, Math.max(2, xfBox.top + dy * xfBox.height))}% - 6px)`,
+                width: 12, height: 12, backgroundColor: '#fff',
+                border: '1.5px solid var(--editor-selection)', borderRadius: 2,
+                cursor: 'nwse-resize', pointerEvents: 'auto', touchAction: 'none',
+              }}
+            />
+          ))}
+        </div>
       )}
 
 

package/src/video/preview/__tests__/transformStyle.test.ts

@@ -0,0 +1,34 @@
+/// <reference types="vitest/globals" />
+import { videoTransformContainerStyle, videoTransformBoxPct } from '../transformStyle'
+
+describe('videoTransformContainerStyle', () => {
+  it('identity transform → empty style (no-op)', () => {
+    expect(videoTransformContainerStyle({})).toEqual({})
+    expect(videoTransformContainerStyle({ scale: 1, offsetX: 0, offsetY: 0 })).toEqual({})
+  })
+
+  it('scale + offset → translate then scale, origin center', () => {
+    const s = videoTransformContainerStyle({ scale: 2, offsetX: 10, offsetY: -5 })
+    expect(s.transform).toBe('translate(10%, -5%) scale(2)')
+    expect(s.transformOrigin).toBe('center center')
+  })
+})
+
+describe('videoTransformBoxPct', () => {
+  it('scale 1, no offset → fills the frame', () => {
+    expect(videoTransformBoxPct({})).toEqual({ width: 100, height: 100, left: 0, top: 0 })
+  })
+
+  it('scale 2 centered → 200% box, centered (offset -50%)', () => {
+    expect(videoTransformBoxPct({ scale: 2 })).toEqual({ width: 200, height: 200, left: -50, top: -50 })
+  })
+
+  it('scale 0.5 → 50% box centered at 25%,25%', () => {
+    expect(videoTransformBoxPct({ scale: 0.5 })).toEqual({ width: 50, height: 50, left: 25, top: 25 })
+  })
+
+  it('offset shifts the centered box by frame percent', () => {
+    expect(videoTransformBoxPct({ scale: 2, offsetX: 10, offsetY: -5 }))
+      .toEqual({ width: 200, height: 200, left: -40, top: -55 })
+  })
+})

package/src/video/preview/transformStyle.ts

@@ -0,0 +1,44 @@
+// Pure geometry for the base video's on-canvas TRANSFORM (position + zoom),
+// distinct from its sourceCrop (which sub-rect of the footage). Mirrors the
+// renderer (encode-segment.js buildVideoItemFilterParts): the cropped/contained
+// video is fit into a box of size (canvas × scale), centered, then shifted by
+// offsetX/offsetY which are percentages of the frame — `overlay=x=vw*(0.5*(1-s)
+// + offsetX/100)`. The frame's overflow-hidden clips anything outside.
+//
+// Both helpers are expressed in frame-relative units so they're pixel-size
+// independent: the container transform uses CSS translate %, which is relative to
+// the container's own (frame) size, and scale() around center.
+
+import type { CSSProperties } from 'react'
+
+export interface VideoTransform {
+  scale?: number
+  offsetX?: number // percent of frame width
+  offsetY?: number // percent of frame height
+}
+
+// CSS transform for a frame-sized container wrapping the <video>. translate() %
+// is relative to the container (= frame), matching the renderer's frame-percent
+// offset; scale() is around center, matching the renderer's centered box.
+export function videoTransformContainerStyle(t: VideoTransform): CSSProperties {
+  const s = t.scale ?? 1
+  const ox = t.offsetX ?? 0
+  const oy = t.offsetY ?? 0
+  if (s === 1 && ox === 0 && oy === 0) return {}
+  return { transform: `translate(${ox}%, ${oy}%) scale(${s})`, transformOrigin: 'center center' }
+}
+
+// The transform box as a frame-relative % rect (left/top/width/height in %).
+// This is the canvas-aspect box the cropped video is contained within; the crop
+// handles for the on-canvas transform are drawn on it.
+export function videoTransformBoxPct(t: VideoTransform): { left: number; top: number; width: number; height: number } {
+  const s = t.scale ?? 1
+  const ox = t.offsetX ?? 0
+  const oy = t.offsetY ?? 0
+  return {
+    width: s * 100,
+    height: s * 100,
+    left: ((1 - s) / 2) * 100 + ox,
+    top: ((1 - s) / 2) * 100 + oy,
+  }
+}

package/src/video/preview/useVideoPlayback.ts

@@ -610,6 +610,14 @@ export function useVideoPlayback(
           gapNextIdxRef.current = nextIdx
           getActiveVideo()?.pause()
           gapRAFRef.current     = requestAnimationFrame(tickGap)
+        } else {
+          // Scrubbed PAST the last clip into trailing empty space — there is no
+          // next clip to advance to. Without this the active <video> keeps
+          // playing under the hidden (showVideo=false) frame: the picture goes
+          // dark but its audio keeps going. Stop playback outright.
+          getActiveVideo()?.pause()
+          setIsPlaying(false)
+          syncAudioTracks(currentTime, false)
         }
       }
       return

package/src/crop/VideoSourceCropOverlay.tsx

@@ -1,249 +0,0 @@
-import * as React from 'react'
-import type { VisualItem } from '../schema'
-import {
-  renderedSourceRect,
-  fractionToWrapperPx,
-  applyCropHandleDrag,
-  type CropFraction,
-  type CropHandle,
-} from './crop-math'
-
-// Sibling of CanvasCropOverlay, typed to a tracks[0] VisualItem (video) instead
-// of an ImageElement. The full source clip is letterboxed into the preview via a
-// muted <video>, an 8-handle free-form crop window is drawn on top, and handle
-// drags emit the updated `sourceCrop` as source fractions clamped to [0, 1].
-//
-// Source dims come either from the item (sourceWidth/sourceHeight, set on a prior
-// crop) or from the <video>'s videoWidth/videoHeight on loadedmetadata — exactly
-// analogous to CanvasCropOverlay reading naturalWidth/Height from <img> onLoad.
-
-const CROP_HANDLES: CropHandle[] = ['nw', 'n', 'ne', 'w', 'e', 'sw', 's', 'se']
-
-const HANDLE_OFFSET: Record<CropHandle, { dx: 0 | 0.5 | 1; dy: 0 | 0.5 | 1; cursor: string }> = {
-  nw: { dx: 0,   dy: 0,   cursor: 'nw-resize' },
-  n:  { dx: 0.5, dy: 0,   cursor: 'n-resize'  },
-  ne: { dx: 1,   dy: 0,   cursor: 'ne-resize' },
-  w:  { dx: 0,   dy: 0.5, cursor: 'w-resize'  },
-  e:  { dx: 1,   dy: 0.5, cursor: 'e-resize'  },
-  sw: { dx: 0,   dy: 1,   cursor: 'sw-resize' },
-  s:  { dx: 0.5, dy: 1,   cursor: 's-resize'  },
-  se: { dx: 1,   dy: 1,   cursor: 'se-resize' },
-}
-
-const DEFAULT_CROP: CropFraction = { x: 0, y: 0, w: 1, h: 1 }
-
-function clampFraction(c: CropFraction): CropFraction {
-  const x = Math.min(1, Math.max(0, c.x))
-  const y = Math.min(1, Math.max(0, c.y))
-  return {
-    x,
-    y,
-    w: Math.min(1 - x, Math.max(0, c.w)),
-    h: Math.min(1 - y, Math.max(0, c.h)),
-  }
-}
-
-export type VideoSourceCropOverlayProps = {
-  /** The tracks[0] video item being cropped. */
-  item: VisualItem
-  /**
-   * Host-supplied resolver for the clip's preview URL. Implement on the caller
-   * side as `(item) => adapter.fileUrl(item.nobg_preview_src ?? item.src)`.
-   */
-  resolveSrc: (item: VisualItem) => string
-  /** Wrapper width in CSS px (the rect the overlay fills — the preview area). */
-  wrapperWidth: number
-  /** Wrapper height in CSS px. */
-  wrapperHeight: number
-  /** Called once on pointer-up (drag end) with the final clamped [0,1] fractions. */
-  onChange: (next: CropFraction) => void
-  /** Called once when the <video> fires loadedmetadata with the source's intrinsic dims. */
-  onSrcDimsLoaded: (dims: { width: number; height: number }) => void
-}
-
-export function VideoSourceCropOverlay({
-  item,
-  resolveSrc,
-  wrapperWidth,
-  wrapperHeight,
-  onChange,
-  onSrcDimsLoaded,
-}: VideoSourceCropOverlayProps) {
-  const srcUrl = resolveSrc(item)
-
-  // Local mirror of dims loaded from the <video> when the item doesn't already
-  // carry them, so the crop window renders as soon as metadata arrives.
-  const [loadedDims, setLoadedDims] = React.useState<{ width: number; height: number } | null>(null)
-  const srcDims =
-    item.sourceWidth && item.sourceHeight
-      ? { width: item.sourceWidth, height: item.sourceHeight }
-      : loadedDims
-
-  // Prop-driven crop (source of truth when not dragging)
-  const propCrop = item.sourceCrop ?? DEFAULT_CROP
-
-  // In-flight drag crop — non-null only during an active handle drag.
-  // While dragging, the rendered window follows this local state for smoothness.
-  // On pointer-up it's cleared after calling onChange once with the final value.
-  const [liveCrop, setLiveCrop] = React.useState<CropFraction | null>(null)
-  // Ref mirror so onHandlePointerUp always reads the latest value regardless of closure age.
-  const liveCropRef = React.useRef<CropFraction | null>(null)
-
-  // The crop we actually render: live state during drag, props otherwise.
-  const localCrop = liveCrop ?? propCrop
-
-  const rendered =
-    srcDims && wrapperWidth > 0 && wrapperHeight > 0
-      ? renderedSourceRect({
-          wrapperW: wrapperWidth,
-          wrapperH: wrapperHeight,
-          srcWidth: srcDims.width,
-          srcHeight: srcDims.height,
-        })
-      : null
-  const windowPx = rendered ? fractionToWrapperPx({ crop: localCrop, rendered }) : null
-
-  const dragStateRef = React.useRef<{
-    handle: CropHandle
-    startClient: { x: number; y: number }
-    startCrop: CropFraction
-  } | null>(null)
-
-  const onHandlePointerDown = (handle: CropHandle, e: React.PointerEvent<HTMLDivElement>) => {
-    e.stopPropagation()
-    e.currentTarget.setPointerCapture?.(e.pointerId)
-    dragStateRef.current = {
-      handle,
-      startClient: { x: e.clientX, y: e.clientY },
-      startCrop: propCrop,
-    }
-  }
-
-  const onHandlePointerMove = (e: React.PointerEvent<HTMLDivElement>) => {
-    const drag = dragStateRef.current
-    if (!drag || !srcDims) return
-    const dx = e.clientX - drag.startClient.x
-    const dy = e.clientY - drag.startClient.y
-    const next = applyCropHandleDrag({
-      handle: drag.handle,
-      initialCrop: drag.startCrop,
-      deltaPx: { x: dx, y: dy },
-      wrapperW: wrapperWidth,
-      wrapperH: wrapperHeight,
-      srcWidth: srcDims.width,
-      srcHeight: srcDims.height,
-    })
-    // Accumulate in local state for smooth visual feedback — do NOT call onChange yet.
-    const clamped = clampFraction(next)
-    liveCropRef.current = clamped
-    setLiveCrop(clamped)
-  }
-
-  const onHandlePointerUp = () => {
-    const drag = dragStateRef.current
-    dragStateRef.current = null
-    const final = liveCropRef.current
-    liveCropRef.current = null
-    setLiveCrop(null)
-    if (drag && final !== null) {
-      // Call onChange exactly once with the final value.
-      onChange(final)
-    }
-  }
-
-  return (
-    <div
-      style={{ position: 'absolute', inset: 0, overflow: 'hidden', pointerEvents: 'auto' }}
-      onPointerDown={(e) => {
-        e.stopPropagation()
-      }}
-    >
-      {/* Letterbox preview of the full source clip */}
-      <video
-        src={srcUrl}
-        muted
-        playsInline
-        preload="metadata"
-        onLoadedMetadata={(e) => {
-          const v = e.currentTarget
-          const dims = { width: v.videoWidth, height: v.videoHeight }
-          setLoadedDims(dims)
-          onSrcDimsLoaded(dims)
-        }}
-        style={{
-          position: 'absolute',
-          inset: 0,
-          width: '100%',
-          height: '100%',
-          objectFit: 'contain',
-          pointerEvents: 'none',
-        }}
-      />
-
-      {windowPx && (
-        <>
-          {/* Dark dimming mask outside the crop window */}
-          <div
-            data-testid="crop-dim"
-            style={{
-              position: 'absolute',
-              inset: 0,
-              background: 'rgba(0, 0, 0, 0.55)',
-              clipPath: `polygon(
-                0 0, 100% 0, 100% 100%, 0 100%, 0 0,
-                ${windowPx.x}px ${windowPx.y}px,
-                ${windowPx.x}px ${windowPx.y + windowPx.h}px,
-                ${windowPx.x + windowPx.w}px ${windowPx.y + windowPx.h}px,
-                ${windowPx.x + windowPx.w}px ${windowPx.y}px,
-                ${windowPx.x}px ${windowPx.y}px
-              )`,
-              pointerEvents: 'none',
-            }}
-          />
-
-          {/* Crop window border */}
-          <div
-            data-testid="crop-window"
-            style={{
-              position: 'absolute',
-              left: windowPx.x,
-              top: windowPx.y,
-              width: windowPx.w,
-              height: windowPx.h,
-              outline: '2px solid var(--editor-selection)',
-              pointerEvents: 'none',
-            }}
-          />
-
-          {/* 8 resize handles */}
-          {CROP_HANDLES.map((handle) => {
-            const o = HANDLE_OFFSET[handle]
-            return (
-              <div
-                key={handle}
-                data-testid={`crop-handle-${handle}`}
-                onPointerDown={(e) => onHandlePointerDown(handle, e)}
-                onPointerMove={onHandlePointerMove}
-                onPointerUp={onHandlePointerUp}
-                style={{
-                  position: 'absolute',
-                  left: windowPx.x + o.dx * windowPx.w - 6,
-                  top: windowPx.y + o.dy * windowPx.h - 6,
-                  width: 12,
-                  height: 12,
-                  backgroundColor: '#fff',
-                  border: '1.5px solid var(--editor-selection)',
-                  borderRadius: 2,
-                  cursor: o.cursor,
-                  zIndex: 10,
-                  pointerEvents: 'auto',
-                  touchAction: 'none',
-                }}
-              />
-            )
-          })}
-        </>
-      )}
-    </div>
-  )
-}

package/src/crop/__tests__/VideoSourceCropOverlay.test.tsx

@@ -1,105 +0,0 @@
-import { describe, it, expect, vi, afterEach } from 'vitest'
-import { fireEvent, render, cleanup } from '@testing-library/react'
-import type { VisualItem } from '../../schema'
-import { VideoSourceCropOverlay } from '../VideoSourceCropOverlay'
-
-afterEach(() => cleanup())
-
-// Aspect-matched fixture: wrapper 400×500, source 800×1000. The rendered source
-// fills the wrapper with no letterbox, so crop fractions map 1:1 onto wrapper px
-// (x over 400, y over 500). Initial crop (0.2,0.2,0.6,0.6) → px rect (80,100)–(320,400).
-function makeItem(overrides: Partial<VisualItem> = {}): VisualItem {
-  return {
-    id: 'v1',
-    type: 'video',
-    src: '/clip.mov',
-    start: 0,
-    end: 5,
-    sourceWidth: 800,
-    sourceHeight: 1000,
-    sourceCrop: { x: 0.2, y: 0.2, w: 0.6, h: 0.6 },
-    ...overrides,
-  }
-}
-
-describe('VideoSourceCropOverlay', () => {
-  it('renders the 8 crop handles for a video item with known source dims', () => {
-    const { getByTestId } = render(
-      <VideoSourceCropOverlay
-        item={makeItem()}
-        resolveSrc={() => '/clip.mov'}
-        wrapperWidth={400}
-        wrapperHeight={500}
-        onChange={vi.fn()}
-        onSrcDimsLoaded={vi.fn()}
-      />,
-    )
-    for (const h of ['nw', 'n', 'ne', 'w', 'e', 'sw', 's', 'se']) {
-      expect(getByTestId(`crop-handle-${h}`)).toBeTruthy()
-    }
-  })
-
-  it('emits onChange exactly once on pointer-up (not per move) with the final clamped [0,1] fractions', () => {
-    const onChange = vi.fn()
-    const { getByTestId } = render(
-      <VideoSourceCropOverlay
-        item={makeItem()}
-        resolveSrc={() => '/clip.mov'}
-        wrapperWidth={400}
-        wrapperHeight={500}
-        onChange={onChange}
-        onSrcDimsLoaded={vi.fn()}
-      />,
-    )
-
-    const se = getByTestId('crop-handle-se')
-    // Simulate a full drag sequence: pointerdown → multiple pointermoves → pointerup.
-    // jsdom has no PointerEvent constructor, so fireEvent.pointer* drops
-    // clientX/Y. Dispatch MouseEvents under the pointer* type names instead —
-    // MouseEvent carries clientX/Y and React listens on the event type string.
-    se.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true, clientX: 320, clientY: 400 }))
-    // Multiple intermediate moves — onChange must NOT be called during these.
-    se.dispatchEvent(new MouseEvent('pointermove', { bubbles: true, clientX: 290, clientY: 400 }))
-    se.dispatchEvent(new MouseEvent('pointermove', { bubbles: true, clientX: 270, clientY: 400 }))
-
-    // onChange must not fire during move — only after release.
-    expect(onChange).not.toHaveBeenCalled()
-
-    // Release — final position: SE handle moved left 50 px from start (320 → 270).
-    se.dispatchEvent(new MouseEvent('pointerup', { bubbles: true, clientX: 270, clientY: 400 }))
-
-    // onChange called exactly once on pointer-up.
-    expect(onChange).toHaveBeenCalledTimes(1)
-
-    const next = onChange.mock.calls[0][0]
-    // dx = -50 px over a 400-px-wide rendered source = -0.125 fractions.
-    expect(next.x).toBeCloseTo(0.2)
-    expect(next.y).toBeCloseTo(0.2)
-    expect(next.w).toBeCloseTo(0.6 - 50 / 400) // 0.475
-    expect(next.h).toBeCloseTo(0.6)
-    // All emitted fractions stay within [0, 1].
-    for (const v of [next.x, next.y, next.w, next.h]) {
-      expect(v).toBeGreaterThanOrEqual(0)
-      expect(v).toBeLessThanOrEqual(1)
-    }
-  })
-
-  it('reads source dims from the <video> loadedmetadata when not supplied on the item', () => {
-    const onSrcDimsLoaded = vi.fn()
-    const { container } = render(
-      <VideoSourceCropOverlay
-        item={makeItem({ sourceWidth: undefined, sourceHeight: undefined })}
-        resolveSrc={() => '/clip.mov'}
-        wrapperWidth={400}
-        wrapperHeight={500}
-        onChange={vi.fn()}
-        onSrcDimsLoaded={onSrcDimsLoaded}
-      />,
-    )
-    const video = container.querySelector('video') as HTMLVideoElement
-    Object.defineProperty(video, 'videoWidth', { value: 800, configurable: true })
-    Object.defineProperty(video, 'videoHeight', { value: 1000, configurable: true })
-    fireEvent.loadedMetadata(video)
-    expect(onSrcDimsLoaded).toHaveBeenCalledWith({ width: 800, height: 1000 })
-  })
-})