@devbycrux/editor 0.1.0

package/src/gestures/helpers/snap.ts

@@ -0,0 +1,64 @@
+export type SnapGuide = { axis: 'x' | 'y'; at: number };
+
+export type SnapResult = {
+  position: { x: number; y: number };
+  guides: SnapGuide[];
+};
+
+// `threshold` is in the SAME units as proposed/slide (logical, unscaled).
+// Callers that want a screen-pixel-relative feel should pass roughly
+// `desired_screen_px / scale`. Default is a conservative ~0.7% of a 1080-unit
+// slide — tight enough that snap doesn't trap a near-aligned element at rest,
+// loose enough to still feel magnetic on deliberate alignment passes.
+export function snapToSlide(
+  proposed: { x: number; y: number; w: number; h: number },
+  slide: { w: number; h: number },
+  threshold: number = 8,
+): SnapResult {
+  const thresholdX = threshold;
+  const thresholdY = threshold;
+  const guides: SnapGuide[] = [];
+  let { x, y } = proposed;
+
+  // X-axis snap candidates: element-left/center/right vs slide-left/center/right.
+  const elCenterX = proposed.x + proposed.w / 2;
+  const elRightX = proposed.x + proposed.w;
+  const slideCenterX = slide.w / 2;
+  const xCandidates: Array<{ at: number; dx: number }> = [
+    { at: 0, dx: -proposed.x }, // align element left to slide left
+    { at: slideCenterX, dx: slideCenterX - elCenterX }, // center
+    { at: slide.w, dx: slide.w - elRightX }, // align element right to slide right
+  ];
+  let bestX = { dx: Infinity, at: 0 };
+  for (const c of xCandidates) {
+    if (Math.abs(c.dx) < Math.abs(bestX.dx) && Math.abs(c.dx) <= thresholdX) {
+      bestX = c;
+    }
+  }
+  if (bestX.dx !== Infinity) {
+    x = proposed.x + bestX.dx;
+    guides.push({ axis: 'x', at: bestX.at });
+  }
+
+  // Y-axis snap (mirror).
+  const elCenterY = proposed.y + proposed.h / 2;
+  const elBottomY = proposed.y + proposed.h;
+  const slideCenterY = slide.h / 2;
+  const yCandidates: Array<{ at: number; dy: number }> = [
+    { at: 0, dy: -proposed.y },
+    { at: slideCenterY, dy: slideCenterY - elCenterY },
+    { at: slide.h, dy: slide.h - elBottomY },
+  ];
+  let bestY = { dy: Infinity, at: 0 };
+  for (const c of yCandidates) {
+    if (Math.abs(c.dy) < Math.abs(bestY.dy) && Math.abs(c.dy) <= thresholdY) {
+      bestY = c;
+    }
+  }
+  if (bestY.dy !== Infinity) {
+    y = proposed.y + bestY.dy;
+    guides.push({ axis: 'y', at: bestY.at });
+  }
+
+  return { position: { x, y }, guides };
+}

package/src/gestures/hooks/useOverlayDrag.ts

@@ -0,0 +1,106 @@
+import { useCallback, useRef, useState } from 'react';
+import { startDrag, nextDragPosition, type DragState } from '../helpers/drag';
+import { snapToSlide, type SnapGuide } from '../helpers/snap';
+
+// Cursor must travel this many screen pixels from pointer-down before snap
+// engages. Prevents the element from being trapped at a snap target that
+// happens to align with its starting position (e.g. an element whose bottom
+// edge sits exactly on the slide's bottom edge would otherwise re-snap on
+// every pointer event until the user crosses the threshold).
+const DEAD_ZONE_PX = 12;
+
+// Screen-pixel-relative snap distance. Converted to logical units per move
+// using the current scale; floored at 1 logical unit so very-zoomed-out views
+// still snap meaningfully.
+const SNAP_PX = 6;
+
+export type UseOverlayDragArgs = {
+  scale: number;
+  slide: { w: number; h: number };
+  // Called on every pointer move with the latest position and current rotation.
+  // Consumers should perform a cheap, side-effect-only update here (e.g. mutate
+  // DOM style) — do NOT trigger React state updates, since this fires at
+  // pointer-event rate.
+  onPreview: (elementId: string, x: number, y: number, rotation: number) => void;
+  // Called once on pointer up with the final position. This is where React
+  // state should be committed and persistence should be triggered.
+  onCommit?: (elementId: string, x: number, y: number) => void | Promise<void>;
+};
+
+export type UseOverlayDragReturn = {
+  guides: SnapGuide[];
+  onPointerDown: (
+    elementId: string,
+    cursor: { x: number; y: number },
+    element: { x: number; y: number; w: number; h: number; rotation?: number },
+  ) => void;
+  onPointerMove: (cursor: { x: number; y: number }) => void;
+  onPointerUp: () => void;
+};
+
+export function useOverlayDrag({ scale, slide, onPreview, onCommit }: UseOverlayDragArgs): UseOverlayDragReturn {
+  const [guides, setGuides] = useState<SnapGuide[]>([]);
+  const stateRef = useRef<DragState | null>(null);
+  const sizeRef = useRef<{ w: number; h: number } | null>(null);
+  const latestRef = useRef<{ id: string; x: number; y: number } | null>(null);
+  const rotationRef = useRef<number>(0);
+
+  const onPointerDown = useCallback(
+    (
+      elementId: string,
+      cursor: { x: number; y: number },
+      element: { x: number; y: number; w: number; h: number; rotation?: number },
+    ) => {
+      stateRef.current = startDrag(elementId, cursor, element);
+      sizeRef.current = { w: element.w, h: element.h };
+      rotationRef.current = element.rotation ?? 0;
+      latestRef.current = { id: elementId, x: element.x, y: element.y };
+    },
+    [],
+  );
+
+  const onPointerMove = useCallback(
+    (cursor: { x: number; y: number }) => {
+      const s = stateRef.current;
+      const size = sizeRef.current;
+      if (!s || !size) return;
+      const raw = nextDragPosition(s, cursor, scale);
+
+      // Skip snapping until the cursor has cleared the dead-zone. This is a
+      // gesture-level escape hatch: elements that start at a snap target can
+      // never get unstuck otherwise (every move re-snaps them back).
+      const cursorDx = cursor.x - s.startCursor.x;
+      const cursorDy = cursor.y - s.startCursor.y;
+      const cursorDistSq = cursorDx * cursorDx + cursorDy * cursorDy;
+      const inDeadZone = cursorDistSq < DEAD_ZONE_PX * DEAD_ZONE_PX;
+
+      const snap = inDeadZone
+        ? { position: raw, guides: [] as SnapGuide[] }
+        : snapToSlide(
+            { x: raw.x, y: raw.y, w: size.w, h: size.h },
+            slide,
+            Math.max(SNAP_PX / scale, 1),
+          );
+
+      setGuides(snap.guides);
+      latestRef.current = { id: s.elementId, x: snap.position.x, y: snap.position.y };
+      onPreview(s.elementId, snap.position.x, snap.position.y, rotationRef.current);
+    },
+    [scale, slide, onPreview],
+  );
+
+  const onPointerUp = useCallback(() => {
+    const final = latestRef.current;
+    // Idempotent — `pointercancel` and `pointerup` can both fire for the same
+    // gesture (especially after `setPointerCapture`); the second arrival sees
+    // null state and exits before re-committing.
+    if (!final) return;
+    stateRef.current = null;
+    sizeRef.current = null;
+    latestRef.current = null;
+    setGuides([]);
+    void onCommit?.(final.id, final.x, final.y);
+  }, [onCommit]);
+
+  return { guides, onPointerDown, onPointerMove, onPointerUp };
+}

package/src/gestures/hooks/useOverlayResize.ts

@@ -0,0 +1,67 @@
+import { useCallback, useRef } from 'react';
+import { startResize, nextResizeBox, type ResizeState, type ResizeHandle } from '../helpers/resize';
+
+export type UseOverlayResizeArgs = {
+  scale: number;
+  // Called on every pointer move with the new box and current rotation. Use for
+  // cheap, side-effect-only previews (e.g. direct DOM mutation) — do NOT trigger
+  // React state updates here.
+  onPreview: (
+    elementId: string,
+    box: { x: number; y: number; w: number; h: number },
+    rotation: number,
+  ) => void;
+  // Called once on pointer up with the final box. Commit React state here.
+  onCommit?: (elementId: string, box: { x: number; y: number; w: number; h: number }) => void | Promise<void>;
+};
+
+export type UseOverlayResizeReturn = {
+  onPointerDown: (
+    elementId: string,
+    handle: ResizeHandle,
+    cursor: { x: number; y: number },
+    box: { x: number; y: number; w: number; h: number; rotation?: number },
+  ) => void;
+  onPointerMove: (cursor: { x: number; y: number }) => void;
+  onPointerUp: () => void;
+};
+
+export function useOverlayResize({ scale, onPreview, onCommit }: UseOverlayResizeArgs): UseOverlayResizeReturn {
+  const stateRef = useRef<ResizeState | null>(null);
+  const latestRef = useRef<{ id: string; box: { x: number; y: number; w: number; h: number } } | null>(null);
+  const rotationRef = useRef<number>(0);
+
+  const onPointerDown = useCallback(
+    (
+      elementId: string,
+      handle: ResizeHandle,
+      cursor: { x: number; y: number },
+      box: { x: number; y: number; w: number; h: number; rotation?: number },
+    ) => {
+      stateRef.current = startResize(elementId, handle, cursor, box);
+      rotationRef.current = box.rotation ?? 0;
+      latestRef.current = { id: elementId, box };
+    },
+    [],
+  );
+
+  const onPointerMove = useCallback(
+    (cursor: { x: number; y: number }) => {
+      const s = stateRef.current;
+      if (!s) return;
+      const box = nextResizeBox(s, cursor, scale);
+      latestRef.current = { id: s.elementId, box };
+      onPreview(s.elementId, box, rotationRef.current);
+    },
+    [scale, onPreview],
+  );
+
+  const onPointerUp = useCallback(() => {
+    const final = latestRef.current;
+    stateRef.current = null;
+    latestRef.current = null;
+    if (final) void onCommit?.(final.id, final.box);
+  }, [onCommit]);
+
+  return { onPointerDown, onPointerMove, onPointerUp };
+}

package/src/gestures/hooks/useOverlayRotate.ts

@@ -0,0 +1,64 @@
+import { useCallback, useRef } from 'react';
+import { startRotate, nextRotation, type RotateState } from '../helpers/rotate';
+
+export type UseOverlayRotateArgs = {
+  // Called on every pointer move with the new rotation and the element's (x, y).
+  // Use for cheap, side-effect-only previews (e.g. direct DOM mutation) — do NOT
+  // trigger React state updates here.
+  onPreview: (elementId: string, rotation: number, x: number, y: number) => void;
+  // Called once on pointer up with the final rotation. Commit React state here.
+  onCommit?: (elementId: string, rotation: number) => void | Promise<void>;
+};
+
+export type UseOverlayRotateReturn = {
+  onPointerDown: (
+    elementId: string,
+    center: { x: number; y: number },
+    cursor: { x: number; y: number },
+    currentRotation: number,
+    position: { x: number; y: number },
+  ) => void;
+  onPointerMove: (cursor: { x: number; y: number }) => void;
+  onPointerUp: () => void;
+};
+
+export function useOverlayRotate({ onPreview, onCommit }: UseOverlayRotateArgs): UseOverlayRotateReturn {
+  const stateRef = useRef<RotateState | null>(null);
+  const latestRef = useRef<{ id: string; rotation: number } | null>(null);
+  const positionRef = useRef<{ x: number; y: number }>({ x: 0, y: 0 });
+
+  const onPointerDown = useCallback(
+    (
+      elementId: string,
+      center: { x: number; y: number },
+      cursor: { x: number; y: number },
+      currentRotation: number,
+      position: { x: number; y: number },
+    ) => {
+      stateRef.current = startRotate(elementId, center, cursor, currentRotation);
+      positionRef.current = position;
+      latestRef.current = { id: elementId, rotation: currentRotation };
+    },
+    [],
+  );
+
+  const onPointerMove = useCallback(
+    (cursor: { x: number; y: number }) => {
+      const s = stateRef.current;
+      if (!s) return;
+      const rotation = nextRotation(s, cursor);
+      latestRef.current = { id: s.elementId, rotation };
+      onPreview(s.elementId, rotation, positionRef.current.x, positionRef.current.y);
+    },
+    [onPreview],
+  );
+
+  const onPointerUp = useCallback(() => {
+    const final = latestRef.current;
+    stateRef.current = null;
+    latestRef.current = null;
+    if (final) void onCommit?.(final.id, final.rotation);
+  }, [onCommit]);
+
+  return { onPointerDown, onPointerMove, onPointerUp };
+}

package/src/gestures/index.ts

@@ -0,0 +1,16 @@
+export { buildElementTransform } from './helpers/element-transform';
+export { startDrag, nextDragPosition } from './helpers/drag';
+export type { DragState } from './helpers/drag';
+export { startResize, nextResizeBox } from './helpers/resize';
+export type { ResizeHandle, ResizeState } from './helpers/resize';
+export { startRotate, nextRotation } from './helpers/rotate';
+export type { RotateState } from './helpers/rotate';
+export { snapToSlide } from './helpers/snap';
+export type { SnapGuide, SnapResult } from './helpers/snap';
+
+export { useOverlayDrag } from './hooks/useOverlayDrag';
+export type { UseOverlayDragArgs, UseOverlayDragReturn } from './hooks/useOverlayDrag';
+export { useOverlayResize } from './hooks/useOverlayResize';
+export type { UseOverlayResizeArgs, UseOverlayResizeReturn } from './hooks/useOverlayResize';
+export { useOverlayRotate } from './hooks/useOverlayRotate';
+export type { UseOverlayRotateArgs, UseOverlayRotateReturn } from './hooks/useOverlayRotate';

package/src/index.ts

@@ -0,0 +1,112 @@
+// @devbycrux/editor — public API.
+//
+// The package owns the host-agnostic carousel editor: the editor-facing schema,
+// the adapter/theme contracts, and the host-agnostic PIECES (state, gestures,
+// crop, text, preview, overlays). Hosts (Montaj's UI, Hub clients) import from
+// here and supply an EditorAdapter to drive it.
+
+// ── Schema (single source of truth for project/slide/element shapes) ──────────
+export type {
+  Word,
+  AudioTrack,
+  CaptionSegment,
+  Captions,
+  VisualItem,
+  Asset,
+  ImageElement,
+  OverlayElement,
+  CarouselElement,
+  Slide,
+  EditorProject,
+} from './schema'
+
+// ── Contracts (adapter, theme, render, media, component props) ────────────────
+// Schema types are sourced from './schema' above; here we export only the
+// symbols types.ts itself owns, plus the `Project` alias (= EditorProject) that
+// the ported state/reducer code is typed against.
+export type {
+  Project,
+  OverlayFactory,
+  RenderEvent,
+  RenderOptions,
+  MediaScope,
+  MediaItem,
+  GlobalOverlay,
+  GlobalOverlayProp,
+  EditorAdapter,
+  EditorTheme,
+  EditorSlots,
+  CarouselEditorProps,
+} from './types'
+
+// ── Theme ─────────────────────────────────────────────────────────────────────
+export { defaultMontajTheme, applyTheme } from './theme'
+
+// ── State ───────────────────────────────────────────────────────────────────
+export { useProjectState } from './state/use-project-state'
+export type { Connection, UseProjectState } from './state/use-project-state'
+export { projectReducer } from './state/project-reducer'
+export type { Action, ProjectStatus } from './state/project-reducer'
+export { createMutationQueue } from './state/mutation-queue'
+export type { MutationQueue } from './state/mutation-queue'
+
+// ── Gestures ──────────────────────────────────────────────────────────────────
+export * from './gestures'
+
+// ── Crop ──────────────────────────────────────────────────────────────────────
+export {
+  renderedSourceRect,
+  fractionToWrapperPx,
+  wrapperPxToFraction,
+  applyCropHandleDrag,
+} from './crop/crop-math'
+export type {
+  RenderedRect,
+  CropFraction,
+  WrapperPxRect,
+  CropHandle,
+} from './crop/crop-math'
+export { CanvasCropOverlay } from './crop/CanvasCropOverlay'
+export type { CanvasCropOverlayProps } from './crop/CanvasCropOverlay'
+
+// ── Text ──────────────────────────────────────────────────────────────────────
+export {
+  FONT_OPTIONS,
+  findFontOption,
+  FontFamilyPicker,
+  FontSizePicker,
+} from './text/FontPicker'
+export type { FontOption } from './text/FontPicker'
+export { InlineTextEditor } from './text/InlineTextEditor'
+export type { InlineTextEditorProps } from './text/InlineTextEditor'
+export {
+  HEX_PATTERN,
+  isColorProp,
+  isBold,
+  isItalic,
+  nextCase,
+  isStyleProp,
+  nonColorTextEntries,
+  TextFormattingToolbar,
+} from './text/TextFormattingToolbar'
+export type { TextFormattingToolbarProps } from './text/TextFormattingToolbar'
+
+// ── Preview ─────────────────────────────────────────────────────────────────
+export { OverlayPreview } from './preview/OverlayPreview'
+export type { OverlayPreviewProps } from './preview/OverlayPreview'
+
+// ── Overlays ──────────────────────────────────────────────────────────────────
+export {
+  STANDARD_TEXT_PROPS,
+  getSupportedProps,
+  readPropAsString,
+} from './overlays/contract'
+
+// ── Assembled carousel editor ───────────────────────────────────────────────
+export { default as CarouselEditor } from './carousel/CarouselEditor'
+
+// ── Public carousel sub-components ────────────────────────────────────────────
+// Hosts consume these beyond the assembled editor — Montaj's preview/caption
+// components render SlideCanvas thumbnails and wrap overlays in the boundary.
+export { default as SlideCanvas, resolveAsset } from './carousel/SlideCanvas'
+export { default as OverlayErrorBoundary } from './carousel/OverlayErrorBoundary'

package/src/overlays/contract.ts

@@ -0,0 +1,41 @@
+import type { OverlayElement } from '../types'
+
+// The 9-prop editable-text contract. Single source of truth on the FE for
+// which prop keys the floating text toolbar knows how to write. Mirrors
+// hub/backend/src/modules/mcp/overlay-contract.ts REQUIRED_PROPS.
+export const STANDARD_TEXT_PROPS: ReadonlySet<string> = new Set([
+  'text', 'fontSize', 'fontFamily', 'fontWeight', 'fontStyle',
+  'color', 'textAlign', 'textTransform', 'bgColor',
+])
+
+/**
+ * Returns the subset of STANDARD_TEXT_PROPS present (non-null) on the
+ * element. Toolbar controls render only when their target prop is in this set.
+ *
+ * Forgiving on value type: numeric values (e.g. `fontSize: 64`) count as
+ * present. The toolbar reads them via String(value) and writes back as
+ * strings — fixing the round-trip silently rather than blocking the operator
+ * with a "this overlay isn't editable" message. Per the resolved product
+ * question, this prefers UX over strictness; non-string values on contract
+ * props are still flagged upstream by hub.write_overlay's validator.
+ */
+export function getSupportedProps(element: OverlayElement): Set<string> {
+  const props = element.overlay.props
+  const supported = new Set<string>()
+  for (const key of STANDARD_TEXT_PROPS) {
+    const value = props[key]
+    if (value !== undefined && value !== null) supported.add(key)
+  }
+  return supported
+}
+
+/**
+ * Read a contract prop's current value as a string, coercing numbers. Used
+ * by the toolbar's read paths so the displayed control value matches what's
+ * on the element regardless of its stored type.
+ */
+export function readPropAsString(element: OverlayElement, key: string): string {
+  const value = element.overlay.props[key]
+  if (value === undefined || value === null) return ''
+  return String(value)
+}

package/src/preview/OverlayPreview.tsx

@@ -0,0 +1,196 @@
+/**
+ * editor-core/preview/OverlayPreview
+ *
+ * Host-agnostic React component that compiles and renders a JSX overlay
+ * template. The overlay compiler is injected via the `compileOverlay` prop so
+ * this component has no dependency on any host module (no import from
+ * '@/lib/overlay-eval'). The host wires in the compiler from its adapter.
+ *
+ * States:
+ *   - Compiling  → `loading` node (default: spinner with role="status").
+ *   - Compile or runtime error → `errorState` node (default: red badge with role="alert").
+ *   - Success    → factory output element.
+ */
+
+import React, { useEffect, useState } from 'react'
+import type { OverlayFactory } from '../types'
+
+// ── Defaults ─────────────────────────────────────────────────────────────────
+
+function DefaultSpinner(): React.ReactElement {
+  return (
+    <div
+      role="status"
+      aria-label="Loading overlay"
+      style={{
+        position: 'absolute',
+        inset: 0,
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        color: 'rgba(255, 255, 255, 0.65)',
+      }}
+    >
+      <svg
+        width="36"
+        height="36"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+      >
+        <g>
+          <path d="M21 12a9 9 0 1 1-6.219-8.56" />
+          <animateTransform
+            attributeName="transform"
+            type="rotate"
+            from="0 12 12"
+            to="360 12 12"
+            dur="0.9s"
+            repeatCount="indefinite"
+          />
+        </g>
+      </svg>
+    </div>
+  )
+}
+
+function DefaultErrorState(): React.ReactElement {
+  return (
+    <div
+      role="alert"
+      style={{
+        position: 'absolute',
+        inset: 0,
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        padding: 16,
+      }}
+    >
+      <div
+        style={{
+          display: 'inline-flex',
+          alignItems: 'center',
+          gap: 6,
+          padding: '4px 10px',
+          borderRadius: 6,
+          background: 'rgba(220, 38, 38, 0.15)',
+          color: 'rgb(220, 38, 38)',
+          fontSize: 12,
+          fontFamily: 'system-ui, -apple-system, sans-serif',
+          fontWeight: 500,
+        }}
+      >
+        <svg
+          width="14"
+          height="14"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          <circle cx="12" cy="12" r="10" />
+          <line x1="12" y1="8" x2="12" y2="12" />
+          <line x1="12" y1="16" x2="12.01" y2="16" />
+        </svg>
+        <span>overlay error</span>
+      </div>
+    </div>
+  )
+}
+
+// ── Props ─────────────────────────────────────────────────────────────────────
+
+export interface OverlayPreviewProps {
+  /**
+   * Host-supplied compiler. Receives a template path and returns a compiled
+   * OverlayFactory. Injected from the adapter so editor-core never imports
+   * the host's overlay-eval module directly.
+   */
+  compileOverlay: (template: string) => Promise<OverlayFactory>
+
+  /**
+   * Path to the overlay template file. Passed to the injected compileOverlay.
+   * Matches OverlayElement.overlay.template from Montaj's schema.
+   */
+  template: string
+
+  /**
+   * Runtime props forwarded to the overlay factory.
+   * Matches OverlayElement.overlay.props.
+   */
+  props: Record<string, unknown>
+
+  /**
+   * Frame number to render. Matches OverlayElement.frame or the caller's
+   * scrubber position.
+   */
+  frame: number
+
+  /** Frames per second. Passed to the factory alongside frame. */
+  fps: number
+
+  /**
+   * Duration in frames. Passed to the factory as `durationFrames`.
+   * Mirrors how SlideCanvas derives duration from element.overlay.props.duration.
+   */
+  duration: number
+
+  /** Shown while compileOverlay is in-flight. Default: spinner. */
+  loading?: React.ReactNode
+
+  /** Shown on compile error or factory runtime error. Default: red badge. */
+  errorState?: React.ReactNode
+}
+
+// ── Component ─────────────────────────────────────────────────────────────────
+
+export function OverlayPreview({
+  compileOverlay,
+  template,
+  props,
+  frame,
+  fps,
+  duration,
+  loading,
+  errorState,
+}: OverlayPreviewProps): React.ReactElement {
+  const [factory, setFactory] = useState<OverlayFactory | null>(null)
+  const [error, setError] = useState<Error | null>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    // Reset state when template changes so the loading spinner re-appears.
+    setFactory(null)
+    setError(null)
+
+    compileOverlay(template)
+      .then((f) => {
+        if (!cancelled) setFactory(() => f)
+      })
+      .catch((e) => {
+        if (!cancelled) setError(e instanceof Error ? e : new Error(String(e)))
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [template])
+
+  const loadingNode = loading ?? <DefaultSpinner />
+  const errorNode = errorState ?? <DefaultErrorState />
+
+  if (error) return <>{errorNode}</>
+  if (!factory) return <>{loadingNode}</>
+
+  try {
+    const out = factory(frame, fps, duration, props)
+    return out ?? <>{errorNode}</>
+  } catch {
+    return <>{errorNode}</>
+  }
+}