@cueframe/kernel 0.0.1

package/dist/composition-ops.js

@@ -0,0 +1,882 @@
+import {
+  createHeadlessStore,
+  findClipById,
+  findMarkerById,
+  findTrackContainingClipId
+} from "./chunk-NV4I6GJV.js";
+import "./chunk-TULRCY6U.js";
+import {
+  CaptionSegment,
+  CaptionStyle,
+  Composition,
+  Format,
+  Marker,
+  PerClipEffect,
+  TimelineClip,
+  Track
+} from "./chunk-ATAF24QG.js";
+import "./chunk-W35ZMOXB.js";
+import {
+  ReframeSegment
+} from "./chunk-EA6MYCYW.js";
+import {
+  playableSpans
+} from "./chunk-6CMVBTTP.js";
+import "./chunk-QH3YI3ND.js";
+import "./chunk-TWQOKKAF.js";
+import "./chunk-JRQVPFLF.js";
+import "./chunk-JMURQODM.js";
+import "./chunk-7PA7FGLD.js";
+import "./chunk-KYRDKK2D.js";
+import "./chunk-DENF4TPI.js";
+import "./chunk-WREYUH2E.js";
+import "./chunk-37NJ27UU.js";
+import "./chunk-2ESYSVXG.js";
+
+// ../composition-ops/src/index.ts
+import { z } from "zod";
+
+// ../composition-ops/src/opRecorder.ts
+var genTrackId = (kind) => `track-${kind}-${crypto.randomUUID().slice(0, 8)}`;
+function wrapWithOpRecorder(base, opts) {
+  const { record, getComposition } = opts;
+  const wrapped = {
+    // ── clips ──
+    // clip.add is family-self-routing; a bare `media` source is ambiguous, so
+    // the editor's video-lane addClip stamps kind:'video' (replay byte-faithful:
+    // the SAME object goes to the base store and the op). Every mapping derives
+    // from ARGS + BEFORE-state only, so ops record BEFORE the base mutation —
+    // `before` is exact and a throwing base never leaves a phantom op behind
+    // (record throws first on invalid input; base throws are surfaced to the
+    // caller with the op already journaled, which the flush's server apply
+    // would then reject loudly — never silently).
+    addClip: (clip, options) => {
+      const before = getComposition();
+      const c = clip.kind ? clip : { ...clip, kind: "video" };
+      if (options?.newTrack) {
+        const newTrackId = options.newTrackId ?? genTrackId("video");
+        record({ type: "clip.add", clip: c, newTrack: true, newTrackId }, before);
+        base.addClip(c, { newTrack: true, newTrackId });
+      } else {
+        record({ type: "clip.add", clip: c }, before);
+        base.addClip(c);
+      }
+    },
+    removeClip: (id) => {
+      record({ type: "clip.remove", clipId: id }, getComposition());
+      base.removeClip(id);
+    },
+    updateClip: (id, updates) => {
+      record({ type: "clip.update", clipId: id, patch: updates }, getComposition());
+      base.updateClip(id, updates);
+    },
+    removeClipsByMediaId: (mediaId) => {
+      record({ type: "removeClipsByMediaId", mediaId }, getComposition());
+      base.removeClipsByMediaId(mediaId);
+    },
+    setClipProperties: (id, props) => {
+      const { playbackRate, ...patch } = props;
+      if (playbackRate !== void 0) {
+        if (opts.onUnjournalable) {
+          const result = base.setClipProperties(id, props);
+          opts.onUnjournalable("setClipProperties.playbackRate");
+          return result;
+        }
+        throw new Error(
+          "opRecorder.setClipProperties: playbackRate is not serializable as a clip.update op (source.playbackRate triggers a cross-field ripple). Use the server-authoritative ripple path."
+        );
+      }
+      record({ type: "clip.update", clipId: id, patch }, getComposition());
+      return base.setClipProperties(id, props);
+    },
+    // ── overlays (pre-emit the overlay track on first add: pinned id, targeted clip.add) ──
+    addOverlay: (clip) => {
+      const before = getComposition();
+      const track = before.tracks.find((t) => t.kind === "overlay");
+      let trackId = track?.id;
+      if (!trackId) {
+        trackId = genTrackId("overlay");
+        record({ type: "addTrack", kind: "overlay", id: trackId }, before);
+        base.addTrack("overlay", void 0, trackId);
+      }
+      record({ type: "clip.add", clip, trackId }, getComposition());
+      base.addOverlay(clip);
+    },
+    removeOverlay: (id) => {
+      record({ type: "clip.remove", clipId: id }, getComposition());
+      base.removeOverlay(id);
+    },
+    updateOverlay: (id, updates) => {
+      record({ type: "clip.update", clipId: id, patch: updates }, getComposition());
+      base.updateOverlay(id, updates);
+    },
+    loadOverlays: (clips) => {
+      record({ type: "loadOverlays", clips }, getComposition());
+      base.loadOverlays(clips);
+    },
+    // ── audio (same pre-emit rule) ──
+    addAudioClip: (clip) => {
+      const before = getComposition();
+      const track = before.tracks.find((t) => t.kind === "audio");
+      let trackId = track?.id;
+      if (!trackId) {
+        trackId = genTrackId("audio");
+        record({ type: "addTrack", kind: "audio", id: trackId }, before);
+        base.addTrack("audio", void 0, trackId);
+      }
+      record({ type: "clip.add", clip, trackId }, getComposition());
+      base.addAudioClip(clip);
+    },
+    removeAudioClip: (id) => {
+      record({ type: "clip.remove", clipId: id }, getComposition());
+      base.removeAudioClip(id);
+    },
+    updateAudioClip: (id, updates) => {
+      record({ type: "clip.update", clipId: id, patch: updates }, getComposition());
+      base.updateAudioClip(id, updates);
+    },
+    // ── markers ──
+    addMarker: (marker) => {
+      record({ type: "addMarker", marker }, getComposition());
+      base.addMarker(marker);
+    },
+    removeMarker: (id) => {
+      record({ type: "removeMarker", markerId: id }, getComposition());
+      base.removeMarker(id);
+    },
+    updateMarker: (id, updates) => {
+      record({ type: "updateMarker", markerId: id, updates }, getComposition());
+      base.updateMarker(id, updates);
+    },
+    // ── crop / effects / captions / format ──
+    setCropIntents: (clipId, segments) => {
+      record({ type: "setCropIntents", clipId, segments }, getComposition());
+      base.setCropIntents(clipId, segments);
+    },
+    // Wholesale array — `[]` records the clear, same as any other set.
+    setEffects: (clipId, effects) => {
+      record({ type: "setEffects", clipId, effects }, getComposition());
+      base.setEffects(clipId, effects);
+    },
+    setCaptionStyle: (style) => {
+      record({ type: "setCaptionStyle", style }, getComposition());
+      base.setCaptionStyle(style);
+    },
+    setCaptions: (segments, style) => {
+      record({ type: "setCaptions", segments, ...style !== void 0 ? { style } : {} }, getComposition());
+      base.setCaptions(segments, style);
+    },
+    setFormat: (format) => {
+      record({ type: "setFormat", format }, getComposition());
+      base.setFormat(format);
+    },
+    // ── tracks (always pin the id) ──
+    addTrack: (kind, name, id) => {
+      const useId = id ?? genTrackId(kind);
+      record({ type: "addTrack", kind, ...name !== void 0 ? { name } : {}, id: useId }, getComposition());
+      base.addTrack(kind, name, useId);
+    },
+    removeTrack: (trackId) => {
+      record({ type: "removeTrack", trackId }, getComposition());
+      base.removeTrack(trackId);
+    },
+    updateTrack: (trackId, updates) => {
+      record({ type: "updateTrack", trackId, updates }, getComposition());
+      base.updateTrack(trackId, updates);
+    },
+    reorderTracks: (fromIndex, toIndex) => {
+      record({ type: "reorderTracks", fromIndex, toIndex }, getComposition());
+      base.reorderTracks(fromIndex, toIndex);
+    },
+    moveClipToTrack: (clipId, targetTrackId, newStartTime) => {
+      record(
+        {
+          type: "moveClipToTrack",
+          clipId,
+          targetTrackId,
+          ...newStartTime !== void 0 ? { newStartTime } : {}
+        },
+        getComposition()
+      );
+      base.moveClipToTrack(clipId, targetTrackId, newStartTime);
+    },
+    duplicateClip: (id) => {
+      record({ type: "duplicateClip", clipId: id }, getComposition());
+      return base.duplicateClip(id);
+    },
+    // ── server-authoritative (cross-field timeline recompute) ──
+    cutAndRipple: (start, end) => {
+      record({ type: "cutAndRipple", start, end }, getComposition());
+      base.cutAndRipple(start, end);
+    },
+    ripple: (time, amount) => {
+      record({ type: "ripple", time, amount }, getComposition());
+      base.ripple(time, amount);
+    },
+    addExcludedRange: (clipId, sourceStart, sourceEnd, reason) => {
+      record(
+        {
+          type: "addExcludedRange",
+          clipId,
+          sourceStart,
+          sourceEnd,
+          ...reason !== void 0 ? { reason } : {}
+        },
+        getComposition()
+      );
+      base.addExcludedRange(clipId, sourceStart, sourceEnd, reason);
+    },
+    removeExcludedRange: (clipId, rangeIdx) => {
+      record({ type: "removeExcludedRange", clipId, rangeIdx }, getComposition());
+      base.removeExcludedRange(clipId, rangeIdx);
+    }
+  };
+  return { ...base, ...wrapped };
+}
+
+// ../composition-ops/src/recordingStore.ts
+function createRecordingStore(initial) {
+  const base = createHeadlessStore(initial);
+  const ops = [];
+  const wrapped = wrapWithOpRecorder(base, {
+    record: (op, _before) => ops.push(op),
+    getComposition: () => base.getState().composition
+  });
+  return {
+    ...wrapped,
+    getOps: () => [...ops]
+  };
+}
+
+// ../composition-ops/src/materializeGrid.ts
+var GridError = class extends Error {
+  constructor(code, message, opIndex) {
+    super(message);
+    this.code = code;
+    this.opIndex = opIndex;
+    this.name = "GridError";
+  }
+};
+var GRID_DEFAULT_MAX_MARKERS = 500;
+var GRID_HARD_MAX_MARKERS = 2e3;
+function materializeGridMarkers(placement, gridPointsMs, opts) {
+  const { grid, clipId } = opts;
+  const cap = opts.maxMarkers ?? GRID_DEFAULT_MAX_MARKERS;
+  const rate = placement.playbackRate ?? 1;
+  const trimStart = placement.trim?.start ?? 0;
+  const trimEnd = placement.trim?.end ?? trimStart + placement.duration * rate;
+  const spans = playableSpans(trimStart, trimEnd, placement.excludedRanges);
+  const markers = [];
+  let n = 0;
+  for (const ms of gridPointsMs) {
+    const sourceSec = ms / 1e3;
+    let playedBefore = 0;
+    let visible = false;
+    for (const span of spans) {
+      if (sourceSec < span.start) break;
+      if (sourceSec < span.end) {
+        playedBefore += sourceSec - span.start;
+        visible = true;
+        break;
+      }
+      playedBefore += span.end - span.start;
+    }
+    if (!visible) continue;
+    markers.push({
+      id: `grid-${grid}-${clipId}-${n}`,
+      startTime: placement.startTime + playedBefore / rate,
+      kind: grid,
+      name: `${grid}-${n}`,
+      metadata: { sourceClipId: clipId }
+    });
+    n++;
+  }
+  if (markers.length > cap) {
+    throw new GridError(
+      "grid_cap_exceeded",
+      `materializeGrid: ${markers.length} '${grid}' markers fall inside clip '${clipId}' \u2014 over the cap of ${cap}. Raise maxMarkers (\u2264 ${GRID_HARD_MAX_MARKERS}) or narrow the clip's visible window (trim / excludedRanges) so fewer grid points land.`
+    );
+  }
+  return markers;
+}
+
+// ../composition-ops/src/replaceRegion.ts
+var EPS = 1e-3;
+function replaceRegion(input) {
+  const { cutSchedule, programAudioSourceId, durationByMediaId } = input;
+  if (cutSchedule.length === 0) {
+    throw new Error("replaceRegion: empty cut schedule");
+  }
+  const sorted = [...cutSchedule].sort((a, b) => a.startSec - b.startSec);
+  for (let i = 0; i < sorted.length; i++) {
+    const s = sorted[i];
+    if (s.endSec <= s.startSec) throw new Error(`replaceRegion: cut span '${s.candidateId}' has non-positive duration [${s.startSec},${s.endSec}]`);
+    const dur = durationByMediaId[s.mediaId];
+    if (dur !== void 0 && (s.sourceInSec < -EPS || s.sourceOutSec > dur + EPS)) {
+      throw new Error(`replaceRegion: cut span '${s.candidateId}' source [${s.sourceInSec},${s.sourceOutSec}] out of media [0,${dur}]`);
+    }
+    if (i > 0) {
+      const prev = sorted[i - 1];
+      if (Math.abs(s.startSec - prev.endSec) > EPS) {
+        throw new Error(`replaceRegion: cut schedule is not contiguous \u2014 gap/overlap between ${prev.endSec} and ${s.startSec}`);
+      }
+    }
+  }
+  const regionStart = sorted[0].startSec;
+  const regionEnd = sorted[sorted.length - 1].endSec;
+  const audioPinned = programAudioSourceId !== void 0;
+  const mediaClip = (id, startTime, duration, mediaId, trimStart, trimEnd, extra = {}) => ({
+    id,
+    startTime,
+    duration,
+    source: { kind: "media", mediaId, trim: { start: trimStart, end: trimEnd }, ...extra }
+  });
+  const videoTrack = {
+    id: `switch-cut-${stableSuffix(sorted)}`,
+    kind: "video",
+    name: input.trackName ?? "Switch Cut",
+    contents: sorted.map(
+      (s, i) => mediaClip(`cut-${i}-${s.candidateId}`, s.startSec, s.endSec - s.startSec, s.mediaId, s.sourceInSec, s.sourceOutSec, audioPinned ? { muted: true } : {})
+    )
+  };
+  const tracks = [...input.composition.tracks, videoTrack];
+  if (audioPinned) {
+    const dur = durationByMediaId[programAudioSourceId];
+    const audioOut = regionEnd - regionStart;
+    if (dur !== void 0 && audioOut > dur + EPS) {
+      throw new Error(`replaceRegion: program audio source '${programAudioSourceId}' (${dur}s) shorter than the region (${audioOut}s)`);
+    }
+    tracks.push({
+      id: `switch-audio-${programAudioSourceId}`,
+      kind: "audio",
+      name: "Program Audio",
+      contents: [
+        mediaClip(`program-audio-${programAudioSourceId}`, regionStart, regionEnd - regionStart, programAudioSourceId, 0, regionEnd - regionStart, { sync: "independent" })
+      ]
+    });
+  }
+  const next = { ...input.composition, tracks };
+  return Composition.parse(next);
+}
+function stableSuffix(spans) {
+  return spans.map((s) => `${s.candidateId}@${s.startSec.toFixed(2)}`).join("_").slice(0, 48).replace(/[^a-zA-Z0-9_@.-]/g, "");
+}
+
+// ../composition-ops/src/alphaLayers.ts
+function collectAlphaLayerClips(composition) {
+  const tracks = composition?.tracks;
+  if (!Array.isArray(tracks)) return [];
+  const out = [];
+  for (const track of tracks) {
+    const contents = track?.contents;
+    if (!Array.isArray(contents)) continue;
+    for (const c of contents) {
+      const src = c?.source;
+      if (!src || typeof src !== "object") continue;
+      if (src.kind !== "alpha-layer") continue;
+      const componentId = src.componentId;
+      const clipId = c.id;
+      const startTime = c.startTime;
+      const duration = c.duration;
+      if (typeof componentId !== "string" || componentId.length === 0) continue;
+      if (typeof clipId !== "string" || clipId.length === 0) continue;
+      if (typeof startTime !== "number" || typeof duration !== "number" || duration <= 0) continue;
+      const rawProps = src.props;
+      const props = rawProps && typeof rawProps === "object" && !Array.isArray(rawProps) ? rawProps : {};
+      out.push({ clipId, componentId, props, startTime, duration });
+    }
+  }
+  return out;
+}
+function collectRawComponentClips(composition) {
+  const tracks = composition?.tracks;
+  if (!Array.isArray(tracks)) return [];
+  const out = [];
+  for (const track of tracks) {
+    const contents = track?.contents;
+    if (!Array.isArray(contents)) continue;
+    for (const c of contents) {
+      const src = c?.source;
+      if (!src || typeof src !== "object") continue;
+      if (src.kind !== "component") continue;
+      const id = c.id;
+      out.push(typeof id === "string" && id.length > 0 ? id : "(unnamed clip)");
+    }
+  }
+  return out;
+}
+function collectLiveComponentClips(composition) {
+  const tracks = composition?.tracks;
+  if (!Array.isArray(tracks)) return [];
+  const out = [];
+  for (const track of tracks) {
+    const contents = track?.contents;
+    if (!Array.isArray(contents)) continue;
+    for (const c of contents) {
+      const src = c?.source;
+      if (!src || typeof src !== "object") continue;
+      if (src.kind !== "overlay") continue;
+      if (src.primitiveId !== "custom") continue;
+      const params = src.params;
+      const componentId = params && typeof params === "object" ? params.componentId : void 0;
+      const clipId = c.id;
+      if (typeof componentId !== "string" || componentId.length === 0) continue;
+      if (typeof clipId !== "string" || clipId.length === 0) continue;
+      out.push({ clipId, componentId });
+    }
+  }
+  return out;
+}
+
+// ../composition-ops/src/index.ts
+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)} \u2014 expected a video/*, audio/* or image/* type.`
+  );
+}
+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 void 0;
+    // ambiguous — caller must disambiguate
+    case "composition":
+      return "video";
+    default: {
+      const _exhaustive = sourceKind;
+      throw new Error(`deriveFromSource: unknown source kind ${String(_exhaustive)}`);
+    }
+  }
+}
+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 \u2014 cannot determine its family (video | audio | image). Set clip.kind or target a track.`
+    );
+  }
+  return resolved;
+}
+var 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(2e3).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()
+]);
+function applyOp(composition, op) {
+  const store = createHeadlessStore(composition);
+  applyOpToStore(store, op);
+  return store.getState().composition;
+}
+function applyOpToStore(store, op) {
+  const composition = store.getState().composition;
+  switch (op.type) {
+    case "clip.add": {
+      if (op.trackId !== void 0) {
+        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 {
+        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": {
+      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":
+      throw new Error(
+        `applyOp: 'applyMotionPreset' is route-materialized \u2014 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":
+      throw new Error(
+        `applyOp: 'materializeGrid' is route-materialized \u2014 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":
+      throw new Error(
+        `applyOp: 'captions.fromTranscript' is route-materialized \u2014 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);
+      if (op.newClipId !== void 0 && minted !== void 0 && 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}`);
+    }
+  }
+}
+function invertOp(before, op) {
+  switch (op.type) {
+    case "clip.add":
+      return { type: "clip.remove", clipId: op.clip.id };
+    case "clip.remove": {
+      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": {
+      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`);
+      }
+      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": {
+      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": {
+      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": {
+      const f = before.format;
+      return {
+        type: "setFormat",
+        format: {
+          aspectRatio: f.aspectRatio,
+          ...f.fps !== void 0 ? { fps: f.fps } : {},
+          ...f.resolution !== void 0 ? { resolution: f.resolution } : {}
+        }
+      };
+    }
+    case "addTrack":
+      if (op.id === void 0) {
+        throw new Error("invertOp(addTrack): no pinned `id` \u2014 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": {
+      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": {
+      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":
+      if (op.newClipId === void 0) {
+        throw new Error(
+          "invertOp(duplicateClip): no `newClipId` \u2014 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) \u2014 fail loud, no fake inverse.`
+      );
+    default: {
+      const _exhaustive = op;
+      throw new Error(`invertOp: unknown op ${_exhaustive.type}`);
+    }
+  }
+}
+export {
+  CompositionOp,
+  GRID_DEFAULT_MAX_MARKERS,
+  GRID_HARD_MAX_MARKERS,
+  GridError,
+  applyOp,
+  applyOpToStore,
+  collectAlphaLayerClips,
+  collectLiveComponentClips,
+  collectRawComponentClips,
+  createRecordingStore,
+  invertOp,
+  materializeGridMarkers,
+  mediaFamily,
+  replaceRegion,
+  resolveClipKind,
+  wrapWithOpRecorder
+};