@clipkit/editor-core 1.0.0

package/dist/timeline-utils.js

@@ -0,0 +1,211 @@
+// Pure helpers for the Timeline — time ↔ px math, layer listing,
+// snapping, and overlap detection. No React, no DOM, no store.
+// ── Element field accessors with defaults ──────────────────────────
+export function elementTime(el) {
+    return typeof el.time === 'number' ? el.time : 0;
+}
+export function elementLayer(el) {
+    return typeof el.layer === 'number' ? el.layer : 1;
+}
+export function elementDuration(el, sourceDuration) {
+    if (typeof el.duration === 'number')
+        return el.duration;
+    // 'auto' / 'end' / undefined → take what's left in the composition.
+    return Math.max(0.1, sourceDuration - elementTime(el));
+}
+export function elementLabel(el) {
+    if (el.type === 'text') {
+        const t = el.text;
+        return t ? t.slice(0, 28) : 'text';
+    }
+    if (el.type === 'shape') {
+        const s = el.shape;
+        return s ?? 'shape';
+    }
+    if (el.type === 'image' || el.type === 'video' || el.type === 'audio') {
+        const src = el.source;
+        if (src) {
+            const last = src.split('/').pop() ?? src;
+            return last.slice(0, 24);
+        }
+        return el.type;
+    }
+    if (el.type === 'caption')
+        return 'captions';
+    if (el.type === 'group') {
+        const n = (el.elements?.length ?? 0);
+        return `group · ${n}`;
+    }
+    return el.type;
+}
+// ── Layout: list used layers (ascending — layer 1 is the top row / on top) ──
+export function listUsedLayers(source) {
+    const set = new Set();
+    for (const el of source.elements)
+        set.add(elementLayer(el));
+    return Array.from(set).sort((a, b) => a - b);
+}
+// ── Edit-time layer invariant (correct-by-construction; NOT a load normalize) ──
+/** A container's elements sorted FRONT-TO-BACK (layer ascending; layer 1 = front). */
+export function byLayer(elements) {
+    return [...elements].sort((a, b) => elementLayer(a) - elementLayer(b));
+}
+/**
+ * Stamp dense, unique `layer` values onto a container from its desired
+ * FRONT-TO-BACK order: index 0 → layer 1 (front / on top), last → layer N.
+ * Run on add / reorder / delete so the editor always writes valid, uniquely
+ * layered sources — correct-by-construction at edit time, NOT a load pass.
+ * Returns new element objects (all other fields untouched).
+ */
+export function reassignLayers(frontToBack) {
+    return frontToBack.map((el, i) => ({ ...el, layer: i + 1 }));
+}
+// ── Snap math ──────────────────────────────────────────────────────
+/**
+ * Snap `value` to the nearest target within `threshold`. Returns the
+ * snapped value AND the target that won, so callers can render a
+ * visual snap indicator. If no target wins, returns the input
+ * unchanged with `target: null`.
+ */
+export function snapTo(value, targets, threshold) {
+    let bestTarget = null;
+    let bestDist = threshold;
+    for (const target of targets) {
+        const dist = Math.abs(value - target);
+        if (dist < bestDist) {
+            bestDist = dist;
+            bestTarget = target;
+        }
+    }
+    if (bestTarget === null)
+        return { value, target: null };
+    return { value: bestTarget, target: bestTarget };
+}
+/**
+ * Build the snap target list — composition bounds, the playhead, whole
+ * seconds, and every non-dragged element's start + end. Recurses into
+ * compositions.
+ */
+export function buildSnapTargets(source, sourceDuration, excludeIds, playhead) {
+    const targets = [0, sourceDuration, playhead];
+    for (let s = 0; s <= Math.ceil(sourceDuration); s++)
+        targets.push(s);
+    collectElementEdges(source.elements, sourceDuration, excludeIds, targets);
+    return targets;
+}
+function collectElementEdges(elements, sourceDuration, excludeIds, out) {
+    for (const el of elements) {
+        if (el.id && excludeIds.has(el.id))
+            continue;
+        const t = elementTime(el);
+        out.push(t, t + elementDuration(el, sourceDuration));
+        if (el.type === 'group') {
+            collectElementEdges(el.elements, sourceDuration, excludeIds, out);
+        }
+    }
+}
+// ── Overlap detection ──────────────────────────────────────────────
+/**
+ * Returns true if `[start, end)` on `layer` overlaps any non-excluded
+ * element on the same layer. Used to reject invalid drops.
+ */
+export function hasOverlapOnLayer(source, sourceDuration, layer, start, end, excludeIds) {
+    for (const el of source.elements) {
+        if (el.id && excludeIds.has(el.id))
+            continue;
+        if (elementLayer(el) !== layer)
+            continue;
+        const elStart = elementTime(el);
+        const elEnd = elStart + elementDuration(el, sourceDuration);
+        if (start < elEnd && end > elStart)
+            return true;
+    }
+    return false;
+}
+// ── Source duration (mirrors the engine's computeDuration) ─────────
+export function computeSourceDuration(source) {
+    if (typeof source.duration === 'number')
+        return source.duration;
+    let max = 0;
+    for (const el of source.elements) {
+        const t = elementTime(el);
+        const d = typeof el.duration === 'number' ? el.duration : 0;
+        if (t + d > max)
+            max = t + d;
+    }
+    return max;
+}
+// ── Ruler ticks + time formatting ───────────────────────────────────
+//
+// Shared by every shell's ruler/readout so 100s-long sources stay
+// readable at any zoom: the tick interval adapts to px-per-second and
+// labels switch to m:ss (and h:mm:ss) once times leave the seconds
+// range.
+/** Candidate major-tick intervals, seconds. */
+const TICK_STEPS = [
+    0.1, 0.25, 0.5, 1, 2, 5, 10, 15, 30, 60, 120, 300, 600, 1200, 1800, 3600,
+];
+/**
+ * Pick the smallest tick interval whose labels stay at least
+ * `minLabelPx` apart at the current zoom. `minor` subdivides each
+ * major span into 5 for unlabeled sub-ticks.
+ */
+export function chooseTickInterval(pxPerSec, minLabelPx = 64) {
+    const major = TICK_STEPS.find((s) => s * pxPerSec >= minLabelPx) ??
+        TICK_STEPS[TICK_STEPS.length - 1];
+    return { major, minor: major / 5 };
+}
+/**
+ * Format a time for display. The UNIT is chosen from `unitFor`
+ * (default: the value itself) so a readout pair like "0:02.57 /
+ * 1:46.00" stays in one consistent format — pass the larger value
+ * (total duration) as `unitFor` for both sides.
+ *
+ *   < 60s   → "2.57s"
+ *   < 1h    → "1:46.00"
+ *   ≥ 1h    → "1:02:03.00"
+ */
+export function formatTimecode(t, unitFor = t) {
+    const v = Math.max(0, t);
+    if (unitFor < 60)
+        return `${v.toFixed(2)}s`;
+    const h = Math.floor(v / 3600);
+    const m = Math.floor((v % 3600) / 60);
+    const ss = (v % 60).toFixed(2).padStart(5, '0');
+    return unitFor < 3600 && h === 0
+        ? `${m}:${ss}`
+        : `${h}:${String(m).padStart(2, '0')}:${ss}`;
+}
+/**
+ * Format a ruler tick label. Whole-unit display (no trailing
+ * decimals): "5s" / "2.5s" below a minute, "1:30" / "1:02:30" above
+ * (unit again chosen by `unitFor`, normally the source duration).
+ */
+export function formatTickLabel(t, unitFor = t, 
+/** The tick interval. When sub-second, labels gain decimals so a
+ * zoomed-in long composition shows 0.5s / 1:02.50 instead of
+ * repeating whole seconds. */
+step = 1) {
+    const sub = step < 1;
+    // Decimal places needed to represent the step exactly (0.5→1,
+    // 0.25→2, 0.1→1, ≥1→0) so labels never round a tick to a wrong value.
+    const dec = decimalPlaces(step);
+    if (unitFor < 60) {
+        return `${parseFloat(t.toFixed(dec))}s`;
+    }
+    const h = Math.floor(t / 3600);
+    const m = Math.floor((t % 3600) / 60);
+    const secRaw = t % 60;
+    const s = sub
+        ? secRaw.toFixed(dec).padStart(3 + dec, '0')
+        : String(Math.round(secRaw)).padStart(2, '0');
+    return unitFor < 3600 && h === 0
+        ? `${m}:${s}`
+        : `${h}:${String(m).padStart(2, '0')}:${s}`;
+}
+function decimalPlaces(n) {
+    const s = String(n);
+    const i = s.indexOf('.');
+    return i < 0 ? 0 : s.length - i - 1;
+}
+//# sourceMappingURL=timeline-utils.js.map

package/dist/timeline-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline-utils.js","sourceRoot":"","sources":["../src/timeline-utils.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The dock tools that add new elements. Keep this list narrow — adding
+ * a tool means adding an `AddXView` panel and a default element shape.
+ */
+export type ToolId = 'text' | 'shape' | 'image' | 'video' | 'audio' | 'caption';
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,MAAM,MAAM,GACd,MAAM,GACN,OAAO,GACP,OAAO,GACP,OAAO,GACP,OAAO,GACP,SAAS,CAAC"}

package/dist/types.js

@@ -0,0 +1,4 @@
+// Shared editor-core types. Shell-specific types (component props,
+// layout) live in the shells.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,8BAA8B"}

package/dist/useEditor.d.ts

@@ -0,0 +1,77 @@
+import type { Element, Source } from '@clipkit/protocol';
+import type { EditorUiState } from './store.js';
+import type { ToolId } from './types.js';
+export interface UseEditorReturn {
+    /** Patch one element by id. Merges; nested objects aren't recursed. */
+    updateElement: (id: string, patch: Partial<Element>) => void;
+    /** Append an element to the top-level `elements` array. */
+    addElement: (element: Element) => void;
+    /** Patch source-level fields (composition settings). */
+    patchSource: (patch: Record<string, unknown>, opts?: {
+        skipHistory?: boolean;
+    }) => void;
+    /**
+     * Replace the WHOLE document (e.g. a JSON-pane commit). One history
+     * entry; selection clears, since ids may no longer exist in the new
+     * tree. The engine syncs through the normal source subscription.
+     */
+    replaceSource: (source: Source) => void;
+    /** Remove an element by id. Clears it from selection if selected. */
+    removeElement: (id: string) => void;
+    /**
+     * Batched element update — commit a multi-element edit as one undoable
+     * action. When `opts.skipHistory` is true, no history entry is pushed
+     * (used during live drag dispatches after `pushHistory()` was called
+     * at drag start).
+     */
+    moveElements: (updates: ReadonlyArray<{
+        id: string;
+        patch: Partial<Element>;
+    }>, opts?: {
+        skipHistory?: boolean;
+    }) => void;
+    /**
+     * Snapshot the current source into history. Call once at the start of
+     * a live interactive operation (drag, resize, rotate) — the operation
+     * dispatches with `{ skipHistory: true }` thereafter, so the whole
+     * thing is one undoable action.
+     */
+    pushHistory: () => void;
+    /**
+     * Toggle the engine's interactive mode. While true, the engine renders
+     * only the current frame on each setSource (no look-ahead buffering).
+     * Wrap drag/resize/rotate with `setInteractive(true)` … `(false)` so
+     * the canvas updates live but doesn't waste cycles producing frames
+     * the next edit invalidates.
+     */
+    setInteractive: (value: boolean) => void;
+    /**
+     * Force-sync the engine with the current store source synchronously.
+     * The Editor's normal subscription coalesces via rAF, which can leave
+     * the engine one frame behind at the end of an interactive operation
+     * (mouseup before the rAF fires). Call this at the end of a drag /
+     * resize / rotate to guarantee the engine has the latest state before
+     * `setInteractive(false)` resumes look-ahead production.
+     */
+    flushPendingSource: () => void;
+    setSelection: (ids: string[]) => void;
+    selectOne: (id: string) => void;
+    clearSelection: () => void;
+    /**
+     * Set the active dock tool. Clicking the same tool twice toggles it
+     * off. The Panel routes off this value.
+     */
+    setTool: (tool: ToolId | null) => void;
+    /** Patch the editor's UI state (panel layout, stage viewport, etc.). */
+    setUiState: (patch: Partial<EditorUiState>) => void;
+    play: () => Promise<void>;
+    pause: () => void;
+    seek: (time: number) => void;
+    togglePlay: () => Promise<void>;
+    undo: () => void;
+    redo: () => void;
+    canUndo: () => boolean;
+    canRedo: () => boolean;
+}
+export declare function useEditor(): UseEditorReturn;
+//# sourceMappingURL=useEditor.d.ts.map

package/dist/useEditor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useEditor.d.ts","sourceRoot":"","sources":["../src/useEditor.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAGzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,WAAW,eAAe;IAG9B,uEAAuE;IACvE,aAAa,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IAC7D,2DAA2D;IAC3D,UAAU,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACvC,wDAAwD;IACxD,WAAW,EAAE,CACX,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,KAC7B,IAAI,CAAC;IACV;;;;OAIG;IACH,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,qEAAqE;IACrE,aAAa,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC;;;;;OAKG;IACH,YAAY,EAAE,CACZ,OAAO,EAAE,aAAa,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE,CAAC,EAC/D,IAAI,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,KAC7B,IAAI,CAAC;IAEV;;;;;OAKG;IACH,WAAW,EAAE,MAAM,IAAI,CAAC;IAExB;;;;;;OAMG;IACH,cAAc,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAEzC;;;;;;;OAOG;IACH,kBAAkB,EAAE,MAAM,IAAI,CAAC;IAI/B,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IACtC,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,cAAc,EAAE,MAAM,IAAI,CAAC;IAE3B;;;OAGG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAIvC,wEAAwE;IACxE,UAAU,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,aAAa,CAAC,KAAK,IAAI,CAAC;IAIpD,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAIhC,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,OAAO,EAAE,MAAM,OAAO,CAAC;IACvB,OAAO,EAAE,MAAM,OAAO,CAAC;CACxB;AAED,wBAAgB,SAAS,IAAI,eAAe,CA4D3C"}

package/dist/useEditor.js

@@ -0,0 +1,74 @@
+// useEditor — the facade hook every consumer (UI components,
+// programmatic embedders) uses to drive the editor.
+//
+// Wraps the store's low-level mutators with engine-aware behavior and
+// presents a clean action surface. Splits cleanly from state reads:
+//
+//   const { updateElement, play, undo } = useEditor();          // actions
+//   const source = useEditorStore((s) => s.source);              // state
+//
+// Don't reach for `engineRef.current.foo()` in components. Add a
+// method here instead.
+import { useMemo } from 'react';
+import { useEditorContext } from './context.js';
+import { computeElementPatches } from './source-diff.js';
+export function useEditor() {
+    const { store, engine } = useEditorContext();
+    // The store object reference is stable; getState/setState are stable.
+    // We memoize the action surface so destructuring doesn't churn on
+    // every render of the consuming component.
+    return useMemo(() => ({
+        updateElement: (id, patch) => store.getState()._updateElement(id, patch),
+        addElement: (element) => store.getState()._addElement(element),
+        patchSource: (patch, opts) => store.getState()._patchSource(patch, opts),
+        replaceSource: (source) => store.getState()._setSource(source),
+        removeElement: (id) => store.getState()._removeElement(id),
+        moveElements: (updates, opts) => store.getState()._moveElements(updates, opts),
+        pushHistory: () => store.getState()._pushHistory(),
+        setInteractive: (value) => engine?.setInteractive(value),
+        flushPendingSource: () => {
+            if (!engine)
+                return;
+            const state = store.getState();
+            if (!state.playback.ready)
+                return;
+            const source = state.source;
+            if (source === engine.source)
+                return;
+            const patches = computeElementPatches(engine.source, source);
+            if (patches === null) {
+                void engine.setSource(source);
+            }
+            else if (patches.length > 0) {
+                engine.patchElements(source, patches);
+            }
+        },
+        setSelection: (ids) => store.getState()._setSelection(ids),
+        selectOne: (id) => store.getState()._setSelection([id]),
+        clearSelection: () => store.getState()._setSelection([]),
+        setTool: (tool) => {
+            const current = store.getState().tool;
+            store.getState()._setTool(current === tool ? null : tool);
+        },
+        setUiState: (patch) => store.getState()._setUiState(patch),
+        play: async () => {
+            if (engine)
+                await engine.play();
+        },
+        pause: () => engine?.pause(),
+        seek: (time) => engine?.seek(time),
+        togglePlay: async () => {
+            if (!engine)
+                return;
+            if (engine.playing)
+                engine.pause();
+            else
+                await engine.play();
+        },
+        undo: () => store.getState()._undo(),
+        redo: () => store.getState()._redo(),
+        canUndo: () => store.getState().history.past.length > 0,
+        canRedo: () => store.getState().history.future.length > 0,
+    }), [store, engine]);
+}
+//# sourceMappingURL=useEditor.js.map

package/dist/useEditor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useEditor.js","sourceRoot":"","sources":["../src/useEditor.ts"],"names":[],"mappings":"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"}

package/dist/useEditorStore.d.ts

@@ -0,0 +1,3 @@
+import type { EditorState } from './store.js';
+export declare function useEditorStore<T>(selector: (state: EditorState) => T): T;
+//# sourceMappingURL=useEditorStore.d.ts.map

package/dist/useEditorStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useEditorStore.d.ts","sourceRoot":"","sources":["../src/useEditorStore.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,wBAAgB,cAAc,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,CAAC,GAAG,CAAC,CAGxE"}

package/dist/useEditorStore.js

@@ -0,0 +1,15 @@
+// useEditorStore — public state-reading hook. Components select the
+// slices they need; Zustand handles fine-grained subscriptions.
+//
+//   const source = useEditorStore((s) => s.source);
+//   const selection = useEditorStore((s) => s.selection);
+//   const time = useEditorStore((s) => s.playback.time);
+//
+// Pair with `useEditor()` for dispatching actions.
+import { useStore } from 'zustand';
+import { useEditorContext } from './context.js';
+export function useEditorStore(selector) {
+    const { store } = useEditorContext();
+    return useStore(store, selector);
+}
+//# sourceMappingURL=useEditorStore.js.map

package/dist/useEditorStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useEditorStore.js","sourceRoot":"","sources":["../src/useEditorStore.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,gEAAgE;AAChE,EAAE;AACF,oDAAoD;AACpD,0DAA0D;AAC1D,yDAAyD;AACzD,EAAE;AACF,mDAAmD;AAEnD,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGhD,MAAM,UAAU,cAAc,CAAI,QAAmC;IACnE,MAAM,EAAE,KAAK,EAAE,GAAG,gBAAgB,EAAE,CAAC;IACrC,OAAO,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AACnC,CAAC"}

package/dist/usePlaybackSession.d.ts

@@ -0,0 +1,20 @@
+import { type RefObject } from 'react';
+import { PlaybackEngine } from '@clipkit/playback';
+import type { Source } from '@clipkit/protocol';
+import type { EditorStore } from './store.js';
+export interface PlaybackSessionOptions {
+    /**
+     * Override the renderer's backend selection. Defaults to `'auto'`
+     * (WebGPU → WebGL2 fallback). Forced backends are mostly useful for
+     * debugging.
+     */
+    backend?: 'auto' | 'webgpu' | 'webgl2';
+    /**
+     * Fired whenever a source change is dispatched to the engine — after
+     * every mutation, undo, or external setSource. Use this to persist
+     * user edits.
+     */
+    onSourceChange?: (source: Source) => void;
+}
+export declare function usePlaybackSession(store: EditorStore, canvasRef: RefObject<HTMLCanvasElement | null>, options?: PlaybackSessionOptions): PlaybackEngine | null;
+//# sourceMappingURL=usePlaybackSession.d.ts.map

package/dist/usePlaybackSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePlaybackSession.d.ts","sourceRoot":"","sources":["../src/usePlaybackSession.ts"],"names":[],"mappings":"AAQA,OAAO,EAAuB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACvC;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3C;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,SAAS,CAAC,iBAAiB,GAAG,IAAI,CAAC,EAC9C,OAAO,GAAE,sBAA2B,GACnC,cAAc,GAAG,IAAI,CAqHvB"}

package/dist/usePlaybackSession.js

@@ -0,0 +1,120 @@
+// usePlaybackSession — constructs the PlaybackEngine against a mounted
+// canvas and wires it to the editor store: engine events → playback
+// state, source changes → two-tier engine dispatch, loop toggle →
+// engine. Extracted verbatim from the basic editor's root so every
+// shell shares one engine-sync implementation.
+'use client';
+import { useEffect, useState } from 'react';
+import { PlaybackEngine } from '@clipkit/playback';
+import { computeElementPatches } from './source-diff.js';
+export function usePlaybackSession(store, canvasRef, options = {}) {
+    const { backend = 'auto', onSourceChange } = options;
+    const [engine, setEngine] = useState(null);
+    // ── Construct the engine once the canvas is mounted ────────────────
+    useEffect(() => {
+        const canvas = canvasRef.current;
+        if (!canvas)
+            return;
+        const nextEngine = new PlaybackEngine({
+            displayCanvas: canvas,
+            source: store.getState().source,
+            backend,
+        });
+        setEngine(nextEngine);
+        const offTime = nextEngine.onTime((t) => store.getState()._setPlaybackState({ time: t }));
+        const offPlaying = nextEngine.onPlayingChange((p) => store.getState()._setPlaybackState({ playing: p }));
+        const offError = nextEngine.onError((e) => store.getState()._setPlaybackState({ error: e.message }));
+        nextEngine.ready
+            .then(() => store.getState()._setPlaybackState({
+            ready: true,
+            duration: nextEngine.duration,
+        }))
+            .catch((err) => store.getState()._setPlaybackState({
+            error: err instanceof Error ? err.message : String(err),
+        }));
+        return () => {
+            offTime();
+            offPlaying();
+            offError();
+            nextEngine.dispose();
+            setEngine(null);
+        };
+    }, [store, backend, canvasRef]);
+    // ── Push source changes into the engine ────────────────────────────
+    //
+    // Two-tier dispatch path:
+    //   1. Diff the new source against the engine's current source.
+    //   2. If only patchable fields changed → engine.patchElements(...).
+    //      Tiny payload, no audio reschedule, no preload, no full
+    //      runtime reload of the source dictionary.
+    //   3. Otherwise (structural / timing / asset change) →
+    //      engine.setSource(next) — the full path with preload + audio.
+    //
+    // rAF coalescing: multiple store updates within the same animation
+    // frame collapse into one dispatch. Only the latest source reaches
+    // the engine.
+    useEffect(() => {
+        if (!engine)
+            return;
+        let scheduled = null;
+        let rafId = null;
+        // Flat stage view (lens rule) drops the camera from the source the
+        // PREVIEW engine sees — orthographic, gizmo-correct editing — while
+        // the store's source (and persistence) keep the camera untouched.
+        const forEngine = (s) => store.getState().ui.stageView === 'flat' && s.camera
+            ? { ...s, camera: undefined }
+            : s;
+        const flush = () => {
+            rafId = null;
+            const next = scheduled;
+            scheduled = null;
+            if (next === null)
+                return;
+            if (!store.getState().playback.ready)
+                return;
+            const engineNext = forEngine(next);
+            const patches = computeElementPatches(engine.source, engineNext);
+            if (patches === null) {
+                // Structural / timing / asset change — full path.
+                void engine.setSource(engineNext);
+            }
+            else if (patches.length > 0) {
+                // Visual-only change — patch path (engine swaps source ref,
+                // sends only the deltas to the worker).
+                engine.patchElements(engineNext, patches);
+            }
+            // patches.length === 0 → nothing to do (already in sync).
+            // Persist the REAL source (with camera), not the preview variant.
+            onSourceChange?.(next);
+        };
+        const unsubscribe = store.subscribe((state, prev) => {
+            // Re-push on a source change OR a stage-view toggle (flat⇄camera
+            // adds/removes the camera the preview engine sees).
+            if (state.source === prev.source && state.ui.stageView === prev.ui.stageView)
+                return;
+            scheduled = state.source;
+            if (rafId === null)
+                rafId = requestAnimationFrame(flush);
+        });
+        return () => {
+            unsubscribe();
+            if (rafId !== null)
+                cancelAnimationFrame(rafId);
+        };
+    }, [engine, store, onSourceChange]);
+    // ── Loop toggle → engine ───────────────────────────────────────────
+    // Subscribe to ui.loop and forward to the engine. Cheaper than
+    // reading from a hook in a child (would re-render the whole shell
+    // on every loop toggle).
+    useEffect(() => {
+        if (!engine)
+            return;
+        engine.setLoop(store.getState().ui.loop);
+        return store.subscribe((state, prev) => {
+            if (state.ui.loop !== prev.ui.loop)
+                engine.setLoop(state.ui.loop);
+        });
+    }, [engine, store]);
+    return engine;
+}
+//# sourceMappingURL=usePlaybackSession.js.map

package/dist/usePlaybackSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePlaybackSession.js","sourceRoot":"","sources":["../src/usePlaybackSession.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@clipkit/editor-core",
+  "version": "1.0.0",
+  "description": "Clipkit editor core — the shared data layer under every editor shell: document store (undo/redo, selection), engine-sync session hook, source diffing, and the pure stage/timeline math. UI-free.",
+  "license": "Apache-2.0",
+  "repository": { "type": "git", "url": "git+https://github.com/clipkit-video/clipkit.git", "directory": "packages/editor-core" },
+  "homepage": "https://clipkit.dev",
+  "bugs": "https://github.com/clipkit-video/clipkit/issues",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@clipkit/playback": "^1.0.0",
+    "@clipkit/protocol": "^1.0.0",
+    "immer": "^10.1.0",
+    "zustand": "^5.0.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  }
+}