@bycrux/editor 0.6.3 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bycrux/editor",
-  "version": "0.6.3",
+  "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