@cueframe/kernel 0.1.0 → 0.1.2

package/dist/_members/composition-ops/index.js

@@ -1,637 +0,0 @@
-/**
- * @cueframe/composition-ops — the composition OPERATION model (single home).
- *
- * One package owns "what an op is": the serializable `CompositionOp` discriminated
- * union, `applyOp(composition, op)` (pure — applies an op to a wire Composition),
- * and `invertOp` (the inverse, for the op-log / multiplayer undo).
- *
- * Layering (deliberate, not fragmentation):
- *  - This package = the op vocabulary + pure apply/inverse. OSS; the agent and the
- *    editor both emit + optimistically-apply ops through it.
- *  - apply logic is REUSED from `@cueframe/core` (the headless store), not forked.
- *  - The server-authoritative persistence (transactional scoped row writes + the
- *    op-log) is ONE generic Convex mutation in `services/convex/composition/applyOp.ts`
- *    — a thin consumer of this package. Convex functions must live in the Convex app;
- *    that is the only piece outside this package, and it does not grow per-op.
- */
-import { z } from 'zod';
-import { TimelineClip, Marker, Track, Format, ReframeSegment, CaptionSegment, CaptionStyle, PerClipEffect, } from '@cueframe/composition/validators';
-import { createHeadlessStore, findClipById, findTrackContainingClipId, findMarkerById, } from '@cueframe/composition/ops';
-/**
- * The timeline family of a media item, derived from its `mimeType`.
- *
- * `mimeType` is the ONLY trustworthy statement of what a media item is: it is
- * `v.string()` (required) on the schema and byte-detected at ingest — populated
- * on 305/305 prod rows. `mediaItems.kind` is a duplicate of the same fact that
- * nobody maintains (null on every video uploaded in 2026-08) and that is
- * overloaded with provenance values (`source`, `stock`, `gif`, `asset`) which
- * are not families at all. Measured 2026-08-17: where `kind` was set it agreed
- * with the mimeType prefix in 232/232 rows. So there is one fact here, and this
- * is where it is read.
- *
- * THROWS on anything it cannot name. A media item whose type we can't determine
- * must not be silently treated as video — that is precisely how an image reached
- * the video frame-extractor and hung the render for 30s on `delayRender`.
- */
-export function mediaFamily(mimeType) {
-    const top = mimeType.split('/')[0]?.trim().toLowerCase();
-    if (top === 'video')
-        return 'video';
-    if (top === 'audio')
-        return 'audio';
-    if (top === 'image')
-        return 'image';
-    throw new Error(`mediaFamily: cannot derive a timeline family from mimeType ${JSON.stringify(mimeType)} — ` +
-        `expected a video/*, audio/* or image/* type.`);
-}
-/**
- * Map an unambiguous `source.kind` to its track family. `media` is the ONLY
- * ambiguous source — a media clip can be video | audio | image, so it returns
- * `undefined` (the family must come from `clip.kind` or a target track). The
- * non-media sources each pin exactly one family.
- */
-function deriveFromSource(sourceKind) {
-    switch (sourceKind) {
-        case 'overlay':
-            return 'overlay';
-        case 'effect':
-            return 'effect';
-        case 'component':
-            return 'overlay';
-        case 'alpha-layer':
-            return 'overlay';
-        case 'card':
-            return 'overlay';
-        case 'media':
-            return undefined; // ambiguous — caller must disambiguate
-        case 'composition':
-            // A compound clip is video-family by definition: it flattens to the
-            // child's tracks at projection, and it PLACES on a video lane
-            // (isSourceKindCompatible pins video ↔ composition).
-            return 'video';
-        default: {
-            const _exhaustive = sourceKind;
-            throw new Error(`deriveFromSource: unknown source kind ${String(_exhaustive)}`);
-        }
-    }
-}
-/**
- * Resolve a clip's track family — the single determinate rule:
- *   `clip.kind  ??  deriveFromSource(source.kind)  ??  track?.kind  ??  throw`.
- *
- * The `track?.kind` step is a PLACEMENT reading, not a family oracle: "this clip
- * is going on that track, so treat it as that family." It is correct here
- * because this function is PURE — it has no database, and a media clip's real
- * family lives on the media item (`mediaFamily(mimeType)`), which only a
- * DB-aware caller can read. The editor's recording store legitimately adds media
- * clips with no `kind` and a target track.
- *
- * What must NOT happen is a *server* guard treating this placement reading as
- * an assertion and then rejecting the caller for it — that was the old
- * `image_media_on_video_track`. The server stamps the true family from
- * `mediaFamily(mediaItem.mimeType)` at the Convex ingress before folding ops, so
- * by the time this runs server-side, `clip.kind` is already authoritative and
- * the track step is never reached.
- *
- * FAILS LOUD for a media source with neither `clip.kind` nor a track — there is
- * no safe default (no-fallbacks rule). Pure: no state, no side effects.
- */
-export function resolveClipKind(clip, track) {
-    const resolved = clip.kind ?? deriveFromSource(clip.source.kind) ?? track?.kind;
-    if (!resolved) {
-        throw new Error(`resolveClipKind: clip with a 'media' source has no 'kind' and no track context — ` +
-            `cannot determine its family (video | audio | image). Set clip.kind or target a track.`);
-    }
-    return resolved;
-}
-/**
- * The serializable composition operation. One discriminated union; every writer
- * (agent, editor) emits these; the server validates with this schema at the
- * boundary. Local-only ops (selectClip/selectOverlay/clearOverlaySelection) are
- * deliberately ABSENT — selection is UI state, never persisted.
- *
- * Cross-field/ripple ops (`cutAndRipple`, `ripple`, `add/removeExcludedRange`)
- * are server-AUTHORITATIVE: the server mutation recomputes downstream timeline
- * state within one transaction (they do not free-merge). They are still
- * expressed here so all writers share one vocabulary. (A `playbackRate` change
- * is also cross-field — it lives at `source.playbackRate` and ripples downstream
- * clips — which is exactly why it is NOT a `clip.update` patch field.)
- */
-export const CompositionOp = z.discriminatedUnion('type', [
-    // ── clips ──
-    // `newTrackId` pins the id of the track created when `newTrack` is set, so a
-    // recorded op replays to the identical track (byte-faithful op-log).
-    // `.strict()` on every variant: an unknown op-level key (e.g. an LLM agent's
-    // typo) fails loud instead of being silently stripped. Scope is op-level only —
-    // nested validators (TimelineClip, Marker, …) keep their own passthrough.
-    // `clip.add` is family-self-routing: the clip's family (resolveClipKind —
-    // clip.kind, else derived from source, else the target track) picks the track.
-    // `trackId` targets an EXISTING same-family track; `newTrack`/`newTrackId`
-    // create a fresh track of the family (the id is pinned for byte-faithful
-    // op-replay — same role it played on the old `addClip`). A `media` clip with
-    // neither `clip.kind` nor `trackId` is rejected at apply time (ambiguous).
-    z.object({ type: z.literal('clip.add'), clip: TimelineClip, trackId: z.string().optional(), newTrack: z.boolean().optional(), newTrackId: z.string().optional() }).strict(),
-    // `clip.remove` is cross-family: the store locates the clip by id across every
-    // track (one locator replaces the three family-specific removers).
-    z.object({ type: z.literal('clip.remove'), clipId: z.string() }).strict(),
-    // `clip.update` is cross-family: the store locates the clip by id across every
-    // track and merges `patch` (one op replaces the three family-specific updaters
-    // updateClip/updateOverlay/updateAudioClip AND setClipProperties). The patch is
-    // `TimelineClip.partial()` — opacity/scale/rotation/region/fit are top-level
-    // TimelineClip fields, so they fold straight into the patch. This KILLS the
-    // historic region/fit silent-drop: the parallel `props` channel (a hand-kept
-    // ClipProps mirror that drifted from the validator) is gone — the patch IS the
-    // validator, so it can never miss a field. `playbackRate` is deliberately NOT
-    // here: it lives at `source.playbackRate`, not as a top-level field, and a rate
-    // change is a cross-field ripple recompute (server-authoritative), not a free
-    // merge — it does not belong in clip.update.
-    //
-    // SOURCE PATCH SEMANTICS (T2 note): the merge is SHALLOW (top-level only). A
-    // `patch.source` REPLACES the WHOLE `source` object — it does NOT deep-merge.
-    // So a partial source (e.g. `{ source: { kind: 'media', mediaId } }` to retarget
-    // media) WIPES every other source field (trim, reframe, volume, excludedRanges,
-    // …). To change ONE source channel, send the COMPLETE source object with that
-    // channel updated (read it from the current clip first). Use `setCropIntents` /
-    // `addExcludedRange` for the reframe/excluded channels instead of a source patch.
-    z.object({ type: z.literal('clip.update'), clipId: z.string(), patch: TimelineClip.partial() }).strict(),
-    z.object({ type: z.literal('removeClipsByMediaId'), mediaId: z.string() }).strict(),
-    // ── overlays (load stays; add/remove/update fold into clip.add/clip.remove/clip.update) ──
-    z.object({ type: z.literal('loadOverlays'), clips: z.array(TimelineClip) }).strict(),
-    // ── markers ──
-    z.object({ type: z.literal('addMarker'), marker: Marker }).strict(),
-    z.object({ type: z.literal('removeMarker'), markerId: z.string() }).strict(),
-    z.object({ type: z.literal('updateMarker'), markerId: z.string(), updates: Marker.partial() }).strict(),
-    // ── crop (reframe) ── op `type` kept as 'setCropIntents' so recorded op
-    // streams replay unchanged; the segment payload is now ReframeSegment[].
-    z.object({ type: z.literal('setCropIntents'), clipId: z.string(), segments: z.array(ReframeSegment).nullable() }).strict(),
-    // ── effects ── the per-clip EFFECT channel (`TimelineClip.effects`). The field
-    // was always in the validator and `clip.add` always accepted it, but nothing
-    // could CHANGE it on an existing clip: the only route was a whole-clip
-    // `clip.update`, which this vocabulary steers callers away from (a partial
-    // `source` in that patch clobbers the source). WHOLESALE set; `effects: []`
-    // clears the channel — the same set/clear shape `setCropIntents` has. The item
-    // schema is the validator's own `PerClipEffect`, reused (never re-described).
-    z.object({ type: z.literal('setEffects'), clipId: z.string(), effects: z.array(PerClipEffect) }).strict(),
-    // ── captions ── style-only overrides (font, color, position, emphasis). Reuse
-    // CaptionStyle.partial() so the op vocabulary never hand-drifts from the validator;
-    // setCaptionStyle merges (omitted fields don't clobber) onto composition.captions.style.
-    z.object({ type: z.literal('setCaptionStyle'), style: CaptionStyle.partial() }).strict(),
-    // setCaptions replaces the caption SEGMENTS wholesale (word timings are one
-    // coherent document — the only writer used to be the transcript-slice lanes,
-    // which locked the caption layer away from clients with their own VO
-    // timings); `style` merges when given, keeps the existing style when omitted.
-    z.object({ type: z.literal('setCaptions'), segments: z.array(CaptionSegment), style: CaptionStyle.partial().optional() }).strict(),
-    // ── motion ── applyMotionPreset is the PUBLIC card-shelling op: wrap a static
-    // `card` clip's approved markup in a frame-driven motion shell (layout verbatim),
-    // mint it as a live component, and swap the clip source to that component (the
-    // director's `apply_motion_preset` capability, minus the box — the live lane).
-    // It is ROUTE-MATERIALIZED: generating the shell needs a director esbuild
-    // transpile, which the pure engine / applyOp mutation can't run, so the op route
-    // (`/composition/apply`) validates + orchestrates it and rewrites it to a
-    // `clip.update` BEFORE the mutation. `applyOp` therefore never applies it (it
-    // throws — reaching the pure engine means the route path was bypassed), and its
-    // recorded/invertible form is the substituted `clip.update` (whose inverse
-    // restores the prior card source). `preset` is `z.string()` here (validated
-    // against MOTION_PRESETS at the route, which owns @cueframe/authoring — this
-    // package stays authoring-free); the OpenAPI mirror enumerates the presets.
-    z.object({ type: z.literal('applyMotionPreset'), clipId: z.string(), preset: z.string(), params: z.object({ enterMs: z.number().optional(), exitMs: z.number().optional(), staggerMs: z.number().optional() }).strict().optional() }).strict(),
-    // ── grids ── materializeGrid reads a clip's SOURCE-media temporal grid
-    // (beat map / word onsets / shot boundaries), maps each grid point from media
-    // time to TIMELINE time through the clip's placement, and writes `kind:<grid>`
-    // markers (replacing any prior materialization from the same clipId+grid).
-    // Like applyMotionPreset it is ROUTE-MATERIALIZED: the pure engine / applyOp
-    // MUTATION has no media reader, so the op route (`/composition/apply` +
-    // `/composition/ops`) resolves the grid evidence and rewrites the op to a
-    // batch of removeMarker+addMarker ops BEFORE the mutation. `applyOp` therefore
-    // never applies it (it throws — reaching the pure engine means the route path
-    // was bypassed), and its recorded/invertible form is the substituted marker
-    // ops (whose own inverses restore the prior markers). `maxMarkers` (≤ 2000)
-    // raises the default 500 cap; exceeding it fails loud with the count.
-    z.object({ type: z.literal('materializeGrid'), clipId: z.string(), grid: z.enum(['beat', 'word', 'shot']), maxMarkers: z.number().int().positive().max(2000).optional() }).strict(),
-    // `captions.fromTranscript` is a REF op: attach caption content from the
-    // media's cached transcript (optionally a source-time window), sentence-split
-    // server-side. ROUTE-MATERIALIZED like applyMotionPreset/materializeGrid: the
-    // API route resolves it to `setCaptions` BEFORE the pure applier — the agent
-    // never pastes transcript text. applyOp throws on an unresolved instance (a
-    // pure applier cannot do I/O; silent no-op is the bug class this lane kills).
-    z.object({
-        type: z.literal('captions.fromTranscript'),
-        mediaId: z.string().min(1),
-        window: z.object({ startSec: z.number().min(0), endSec: z.number().positive() }).strict().optional(),
-    }).strict(),
-    // ── format ──
-    z.object({ type: z.literal('setFormat'), format: Format.pick({ aspectRatio: true, fps: true, resolution: true }) }).strict(),
-    // ── tracks ──
-    z.object({ type: z.literal('addTrack'), kind: Track.shape.kind, name: z.string().optional(), id: z.string().optional() }).strict(),
-    z.object({ type: z.literal('removeTrack'), trackId: z.string() }).strict(),
-    // `volume` joined the pickable set with the track fader (2026-08-24). Review
-    // finding: the fader's store verb accepted it while THIS payload schema did
-    // not — so a fader move recorded into the op journal, or replayed over the
-    // REST-op path, failed validation. The store verb and the op vocabulary must
-    // widen together or the op-log lies about what the editor can do.
-    z.object({ type: z.literal('updateTrack'), trackId: z.string(), updates: Track.pick({ name: true, enabled: true, volume: true }).partial() }).strict(),
-    z.object({ type: z.literal('reorderTracks'), fromIndex: z.number(), toIndex: z.number() }).strict(),
-    z.object({ type: z.literal('moveClipToTrack'), clipId: z.string(), targetTrackId: z.string(), newStartTime: z.number().optional() }).strict(),
-    // `newClipId` PINS the id of the copy duplicateClip mints (the store otherwise
-    // mints a uuid-suffixed id internally). Pinning makes the op deterministic so
-    // `invertOp` can return a `clip.remove` of that exact id (a non-pinned
-    // duplicateClip has no determinate inverse — invertOp throws for it).
-    z.object({ type: z.literal('duplicateClip'), clipId: z.string(), newClipId: z.string().optional() }).strict(),
-    // ── server-authoritative (cross-field timeline recompute) ──
-    z.object({ type: z.literal('cutAndRipple'), start: z.number(), end: z.number() }).strict(),
-    z.object({ type: z.literal('ripple'), time: z.number(), amount: z.number() }).strict(),
-    z.object({ type: z.literal('addExcludedRange'), clipId: z.string(), sourceStart: z.number(), sourceEnd: z.number(), reason: z.string().optional() }).strict(),
-    z.object({ type: z.literal('removeExcludedRange'), clipId: z.string(), rangeIdx: z.number() }).strict(),
-]);
-/**
- * Apply an op to a wire Composition, returning the new Composition (pure).
- * Reuses `@cueframe/core`'s tested op logic via a headless store — no fork.
- */
-export function applyOp(composition, op) {
-    const store = createHeadlessStore(composition);
-    applyOpToStore(store, op);
-    return store.getState().composition;
-}
-/**
- * Dispatch ONE op onto a LIVE store — the op→method switch, extracted from
- * `applyOp` so there is exactly one of it.
- *
- * `applyOp` is pure: it mints a throwaway headless store, folds, and hands back
- * a new Composition. That serves every caller that OWNS the composition value
- * (the Convex mutation, the local-harness store, the ensemble author). It does
- * NOT serve a caller whose composition lives inside somebody else's store —
- * desktop's zustand `CompositionState`, which has no whole-composition setter
- * and whose op-recorder/undo trail only sees writes that go through its
- * methods. Handing that caller a fresh Composition value would be a dead end;
- * the only way in is the methods, which is precisely what this switch calls.
- *
- * So: `HeadlessStore` here is a STRUCTURAL contract (`CompositionOps` + a
- * `getState`), not a concrete class — `@cueframe/authoring`'s `CompositionStore`
- * and the desktop store satisfy it, and `LocalExecutor` (cueframe/src/llm) folds
- * a validated batch through it op-by-op. Writing a second switch for that lane
- * is what "one vocabulary" exists to prevent: it would drift silently the first
- * time an op is added here and forgotten there.
- *
- * NOT transactional on its own — it applies ONE op and a throw leaves the store
- * wherever it got to. A caller wanting the server's all-or-nothing contract
- * validates the whole batch on a scratch fold (`ops.reduce(applyOp, current)`)
- * FIRST, and only then commits through this.
- */
-export function applyOpToStore(store, op) {
-    const composition = store.getState().composition;
-    switch (op.type) {
-        case 'clip.add': {
-            if (op.trackId !== undefined) {
-                // Target an EXISTING track — it must be the clip's own family (a clip
-                // never silently lands on a different-family track). The target track is
-                // the family context for resolveClipKind, so an explicit clip.kind that
-                // contradicts it is caught here.
-                const track = composition.tracks.find((t) => t.id === op.trackId);
-                if (!track)
-                    throw new Error(`clip.add: track '${op.trackId}' not found`);
-                const kind = resolveClipKind(op.clip, track);
-                if (kind !== track.kind) {
-                    throw new Error(`clip.add: clip family '${kind}' does not match target track '${op.trackId}' (kind '${track.kind}')`);
-                }
-                store.addClipToTrack(op.clip, { trackId: op.trackId });
-            }
-            else {
-                // No target track: the clip self-describes its family (kind, else derived
-                // from source). A media clip with neither kind nor trackId throws here.
-                const kind = resolveClipKind(op.clip);
-                store.addClipToTrack(op.clip, op.newTrack ? { kind, newTrack: true, newTrackId: op.newTrackId } : { kind });
-            }
-            break;
-        }
-        case 'clip.remove':
-            store.removeClip(op.clipId);
-            break;
-        // `store.updateClip` is cross-family (locates the clip by id across every
-        // track, like `removeClip`), so it serves all three former family updaters
-        // AND setClipProperties' visual props (region/fit/opacity/scale/rotation +
-        // timing) — a plain partial merge of top-level TimelineClip fields.
-        case 'clip.update':
-            store.updateClip(op.clipId, op.patch);
-            break;
-        case 'removeClipsByMediaId':
-            store.removeClipsByMediaId(op.mediaId);
-            break;
-        case 'loadOverlays':
-            store.loadOverlays(op.clips);
-            break;
-        case 'addMarker':
-            store.addMarker(op.marker);
-            break;
-        case 'removeMarker':
-            store.removeMarker(op.markerId);
-            break;
-        case 'updateMarker':
-            store.updateMarker(op.markerId, op.updates);
-            break;
-        case 'setCropIntents':
-            store.setCropIntents(op.clipId, op.segments);
-            break;
-        case 'setEffects': {
-            // Fail loud on an unknown clip. The engine method (like every op on the
-            // factory) silently no-ops when the id doesn't resolve; for a WIRE op that
-            // silence is the bug — the caller gets a 200 and no effects. `clip.add`
-            // (above) sets the precedent: pre-check, then throw naming the id.
-            if (!findClipById(composition, op.clipId)) {
-                throw new Error(`setEffects: clip '${op.clipId}' not found`);
-            }
-            store.setEffects(op.clipId, op.effects);
-            break;
-        }
-        case 'setCaptionStyle':
-            store.setCaptionStyle(op.style);
-            break;
-        case 'setCaptions':
-            store.setCaptions(op.segments, op.style);
-            break;
-        case 'applyMotionPreset':
-            // Route-materialized: shelling a card needs a director esbuild transpile
-            // (the pure engine can't run it), so the op route rewrites this to a
-            // `clip.update` BEFORE the mutation folds ops. Reaching applyOp means the
-            // route path was bypassed — fail loud, never a fake apply.
-            throw new Error(`applyOp: 'applyMotionPreset' is route-materialized — it needs a director ` +
-                `transpile of the generated motion shell and is rewritten to a clip.update ` +
-                `at /composition/apply before reaching the pure engine.`);
-        case 'materializeGrid':
-            // Route-materialized: reading the clip's source-media grid evidence needs a
-            // media reader (DB), which the pure engine can't run, so the op route
-            // resolves the grid and rewrites this to removeMarker+addMarker ops BEFORE
-            // the mutation folds ops. Reaching applyOp means the route path was
-            // bypassed — fail loud, never a fake apply.
-            throw new Error(`applyOp: 'materializeGrid' is route-materialized — it reads the clip's ` +
-                `source-media grid (beat/word/shot) via a media reader and is rewritten to ` +
-                `removeMarker+addMarker ops at /composition/apply before reaching the pure engine.`);
-        case 'captions.fromTranscript':
-            // Route-materialized: resolving the media's cached transcript needs R2 +
-            // DB reads the pure engine can't run; the op route slices + sentence-
-            // splits and rewrites this to `setCaptions` BEFORE the mutation folds
-            // ops. Reaching applyOp means the route path was bypassed — fail loud.
-            throw new Error(`applyOp: 'captions.fromTranscript' is route-materialized — it is resolved to ` +
-                `setCaptions at /composition/apply before reaching the pure engine.`);
-        case 'setFormat':
-            store.setFormat(op.format);
-            break;
-        case 'addTrack':
-            store.addTrack(op.kind, op.name, op.id);
-            break;
-        case 'removeTrack':
-            store.removeTrack(op.trackId);
-            break;
-        case 'updateTrack':
-            store.updateTrack(op.trackId, op.updates);
-            break;
-        case 'reorderTracks':
-            store.reorderTracks(op.fromIndex, op.toIndex);
-            break;
-        case 'moveClipToTrack':
-            store.moveClipToTrack(op.clipId, op.targetTrackId, op.newStartTime);
-            break;
-        case 'duplicateClip': {
-            const minted = store.duplicateClip(op.clipId);
-            // Pin the copy's id when `newClipId` is supplied so the op is
-            // deterministic (replay + a deterministic clip.remove inverse). The store
-            // mints a uuid-suffixed id; rename it via a plain id patch.
-            if (op.newClipId !== undefined && minted !== undefined && minted !== op.newClipId) {
-                store.updateClip(minted, { id: op.newClipId });
-            }
-            break;
-        }
-        case 'cutAndRipple':
-            store.cutAndRipple(op.start, op.end);
-            break;
-        case 'ripple':
-            store.ripple(op.time, op.amount);
-            break;
-        case 'addExcludedRange':
-            store.addExcludedRange(op.clipId, op.sourceStart, op.sourceEnd, op.reason);
-            break;
-        case 'removeExcludedRange':
-            store.removeExcludedRange(op.clipId, op.rangeIdx);
-            break;
-        default: {
-            const _exhaustive = op;
-            throw new Error(`applyOp: unknown op ${_exhaustive.type}`);
-        }
-    }
-}
-/**
- * The inverse op (for the op-log → selective multiplayer undo / diff / audit).
- *
- * `invertOp(before, op)` returns the op that, applied to `applyOp(before, op)`,
- * restores `before`. It needs the PRE-image to capture the value the forward op
- * overwrote (the patched fields, the replaced reframe segments, the removed
- * clip, …).
- *
- * Coverage (value-restoring): clip.add↔clip.remove, clip.update (prior fields),
- * markers (add/remove/update), setCropIntents (prior segments), setEffects (prior
- * effect stack), setFormat (prior values), addTrack↔removeTrack, updateTrack
- * (prior name/enabled), reorderTracks (reversed), moveClipToTrack (move back),
- * duplicateClip (clip.remove of the PINNED newClipId).
- *
- * DEFERRED — these THROW (fail loud; a wrong inverse silently corrupts undo, so
- * we never fake one):
- *  - cutAndRipple / ripple / addExcludedRange / removeExcludedRange — server-
- *    authoritative cross-field timeline recomputes (clips split/merge, durations
- *    and downstream startTimes recompute, markers + caption words ripple). No
- *    clean single-op inverse; restoring them is a snapshot-restore concern.
- *  - removeTrack — removes a track AND its clips at a position; there is no
- *    op to re-insert a populated track at an index (addTrack appends an EMPTY
- *    track), so the pre-image can't be restored as one op.
- *  - removeClipsByMediaId / loadOverlays — whole-channel replace/clear (multiple
- *    clips across tracks, with positions and scene-marker side effects); no
- *    single restoring op.
- *  - setCaptionStyle — MERGES (and creates the captions container when absent)
- *    with no clear/drop op, so a forward call that adds a style key (or the
- *    container) can't be exactly reverted.
- *  - duplicateClip WITHOUT `newClipId` — the copy's id is store-minted
- *    (non-deterministic), so there is no clip id to remove. Pin `newClipId` for a
- *    deterministic inverse.
- */
-export function invertOp(before, op) {
-    switch (op.type) {
-        case 'clip.add':
-            // The forward add appended `op.clip`; remove it by id. (When the add
-            // auto-CREATES a track for a new family, removing the clip leaves that
-            // empty track behind — the editor/agent only ever add to existing or
-            // explicitly-pinned tracks via this op, so this is the value inverse.)
-            return { type: 'clip.remove', clipId: op.clip.id };
-        case 'clip.remove': {
-            // Restore the pre-image clip onto its ORIGINAL track (so it returns to the
-            // same family/position context). The captured clip carries its own `kind`,
-            // and we target the original trackId — the determinate add path.
-            const found = findClipById(before, op.clipId);
-            if (!found) {
-                throw new Error(`invertOp(clip.remove): clip '${op.clipId}' not in the pre-image`);
-            }
-            const track = before.tracks[found.trackIndex];
-            return { type: 'clip.add', clip: found.clip, trackId: track.id };
-        }
-        case 'clip.update': {
-            // Restore the prior value of EVERY key the patch named. A key that was
-            // absent before maps to `undefined` (the spread writes it as undefined;
-            // structural equality treats `{k: undefined}` as absent, so the pre-image
-            // is recovered).
-            const found = findClipById(before, op.clipId);
-            if (!found) {
-                throw new Error(`invertOp(clip.update): clip '${op.clipId}' not in the pre-image`);
-            }
-            const prior = found.clip;
-            const inversePatch = {};
-            for (const key of Object.keys(op.patch))
-                inversePatch[key] = prior[key];
-            return { type: 'clip.update', clipId: op.clipId, patch: inversePatch };
-        }
-        case 'addMarker':
-            return { type: 'removeMarker', markerId: op.marker.id };
-        case 'removeMarker': {
-            const found = findMarkerById(before, op.markerId);
-            if (!found) {
-                throw new Error(`invertOp(removeMarker): marker '${op.markerId}' not in the pre-image`);
-            }
-            // Re-add the pre-image marker. (addMarker appends; when the removed marker
-            // was not last, the marker is restored by VALUE but not its array index.)
-            return { type: 'addMarker', marker: found.marker };
-        }
-        case 'updateMarker': {
-            const found = findMarkerById(before, op.markerId);
-            if (!found) {
-                throw new Error(`invertOp(updateMarker): marker '${op.markerId}' not in the pre-image`);
-            }
-            const prior = found.marker;
-            const inverseUpdates = {};
-            for (const key of Object.keys(op.updates)) {
-                inverseUpdates[key] = prior[key];
-            }
-            return { type: 'updateMarker', markerId: op.markerId, updates: inverseUpdates };
-        }
-        case 'setCropIntents': {
-            // Restore the prior `reframe.segments` (or clear when there were none).
-            const found = findClipById(before, op.clipId);
-            if (!found) {
-                throw new Error(`invertOp(setCropIntents): clip '${op.clipId}' not in the pre-image`);
-            }
-            const src = found.clip.source;
-            const priorSegments = src.kind === 'media' && src.reframe ? src.reframe.segments : null;
-            return { type: 'setCropIntents', clipId: op.clipId, segments: priorSegments };
-        }
-        case 'setEffects': {
-            // Wholesale channel, so the inverse is the pre-image array (`[]` when the
-            // clip had no effects — which is exactly how the forward op CLEARS).
-            const found = findClipById(before, op.clipId);
-            if (!found) {
-                throw new Error(`invertOp(setEffects): clip '${op.clipId}' not in the pre-image`);
-            }
-            return { type: 'setEffects', clipId: op.clipId, effects: found.clip.effects ?? [] };
-        }
-        case 'setFormat': {
-            // Restore the prior aspectRatio + fps + resolution. NOTE: setFormat MERGES
-            // (carry-forward), so an omitted field keeps the CURRENT value — this
-            // inverse restores prior VALUES but cannot DROP a field that was absent
-            // before the forward op. A fully-populated prior format round-trips.
-            const f = before.format;
-            return {
-                type: 'setFormat',
-                format: {
-                    aspectRatio: f.aspectRatio,
-                    ...(f.fps !== undefined ? { fps: f.fps } : {}),
-                    ...(f.resolution !== undefined ? { resolution: f.resolution } : {}),
-                },
-            };
-        }
-        case 'addTrack':
-            // The forward addTrack pinned `id` (or one was minted); remove that track.
-            // (Our recording seam always pins addTrack's id, so `op.id` is present in
-            // practice; if absent, the inverse can't target the minted id.)
-            if (op.id === undefined) {
-                throw new Error('invertOp(addTrack): no pinned `id` — cannot target the minted track');
-            }
-            return { type: 'removeTrack', trackId: op.id };
-        case 'updateTrack': {
-            const track = before.tracks.find((t) => t.id === op.trackId);
-            if (!track) {
-                throw new Error(`invertOp(updateTrack): track '${op.trackId}' not in the pre-image`);
-            }
-            const inverseUpdates = {};
-            if ('name' in op.updates)
-                inverseUpdates.name = track.name;
-            if ('enabled' in op.updates)
-                inverseUpdates.enabled = track.enabled;
-            return { type: 'updateTrack', trackId: op.trackId, updates: inverseUpdates };
-        }
-        case 'reorderTracks': {
-            // reorderTracks splices the element out then re-inserts at clamped(toIndex);
-            // the moved element's final index is therefore clamped(toIndex). The inverse
-            // moves it from that resting index back to its original `fromIndex`.
-            const len = before.tracks.length;
-            const restingIndex = Math.max(0, Math.min(op.toIndex, len - 1));
-            return { type: 'reorderTracks', fromIndex: restingIndex, toIndex: op.fromIndex };
-        }
-        case 'moveClipToTrack': {
-            // Move the clip back to its ORIGINAL track and restore its prior startTime.
-            const found = findTrackContainingClipId(before, op.clipId);
-            if (!found) {
-                throw new Error(`invertOp(moveClipToTrack): clip '${op.clipId}' not in the pre-image`);
-            }
-            const priorClip = found.track.contents[found.clipIndex];
-            return {
-                type: 'moveClipToTrack',
-                clipId: op.clipId,
-                targetTrackId: found.track.id,
-                newStartTime: priorClip.startTime,
-            };
-        }
-        case 'duplicateClip':
-            // The copy's id is store-minted unless the op PINS `newClipId`. Without a
-            // pin there is no determinate id to remove — fail loud rather than guess.
-            if (op.newClipId === undefined) {
-                throw new Error('invertOp(duplicateClip): no `newClipId` — the copy id is store-minted and ' +
-                    'non-deterministic. Pin `newClipId` on the op for a deterministic inverse.');
-            }
-            return { type: 'clip.remove', clipId: op.newClipId };
-        // ── DEFERRED (fail loud — see the doc-comment above for why none has a
-        //    clean per-op inverse in scope). ──
-        case 'cutAndRipple':
-        case 'ripple':
-        case 'addExcludedRange':
-        case 'removeExcludedRange':
-        case 'removeTrack':
-        case 'removeClipsByMediaId':
-        case 'loadOverlays':
-        case 'setCaptionStyle':
-        case 'setCaptions':
-        // applyMotionPreset is route-materialized into a clip.update before it is
-        // recorded, so invertOp is never asked to invert it in practice; if it is
-        // (a bypassed route path), fail loud — the real inverse lives on the
-        // substituted clip.update (which restores the prior card source).
-        case 'applyMotionPreset':
-        // materializeGrid is route-materialized into removeMarker+addMarker ops
-        // before it is recorded, so invertOp never inverts it in practice; the real
-        // inverses live on those substituted marker ops. Fail loud if reached.
-        case 'materializeGrid':
-        // captions.fromTranscript is route-materialized into setCaptions before it
-        // is recorded, so invertOp never inverts it in practice; fail loud if reached.
-        case 'captions.fromTranscript':
-            throw new Error(`invertOp: '${op.type}' has no per-op inverse in scope (server-authoritative ` +
-                `cross-field recompute or whole-channel/positional restore) — fail loud, no fake inverse.`);
-        default: {
-            const _exhaustive = op;
-            throw new Error(`invertOp: unknown op ${_exhaustive.type}`);
-        }
-    }
-}
-export { createRecordingStore } from './recordingStore';
-export { wrapWithOpRecorder } from './opRecorder';
-// ── materializeGrid — the pure media-time → timeline-time grid projection ──
-// (the DB-bound evidence read + idempotent marker replace is the op route's).
-export { materializeGridMarkers, GridError, GRID_DEFAULT_MAX_MARKERS, GRID_HARD_MAX_MARKERS, } from './materializeGrid';
-// ── replaceRegion — the non-rippling cut/overlay lowering (selector switch) ──
-export { replaceRegion } from './replaceRegion';
-// The alpha-layer clip walk (pure, crypto-free) — the SSOT for finding a wire
-// composition's alpha-layer clips. Shared by the director (bake) and Convex
-// (materialize tsxSource into the stage body). The content-hash that keys the
-// bake cache stays director-side (it needs node:crypto, not V8-safe).
-export { collectAlphaLayerClips, collectLiveComponentClips, collectRawComponentClips, } from './alphaLayers';