@cueframe/kernel 0.0.1

package/dist/chunk-NV4I6GJV.js

@@ -0,0 +1,1091 @@
+import {
+  Composition
+} from "./chunk-ATAF24QG.js";
+import {
+  expandToLinkGroup
+} from "./chunk-KYRDKK2D.js";
+
+// ../composition/src/ops/compositionOps.ts
+function findOrCreateTrackByKind(composition, kind) {
+  const existing = composition.tracks.find((t) => t.kind === kind);
+  if (existing) return existing;
+  const track = {
+    // UUID suffix avoids id collisions when a track of `kind` is created,
+    // deleted, then re-created at the same `tracks.length` index.
+    id: `track-${kind}-${crypto.randomUUID().slice(0, 8)}`,
+    kind,
+    contents: []
+  };
+  composition.tracks.push(track);
+  return track;
+}
+function findClipById(composition, id) {
+  for (let ti = 0; ti < composition.tracks.length; ti++) {
+    const track = composition.tracks[ti];
+    for (let ci = 0; ci < track.contents.length; ci++) {
+      const item = track.contents[ci];
+      if ("source" in item && item.id === id) {
+        return { clip: item, trackIndex: ti, clipIndex: ci };
+      }
+    }
+  }
+  return void 0;
+}
+function findTrackContainingClipId(composition, id) {
+  for (let ti = 0; ti < composition.tracks.length; ti++) {
+    const track = composition.tracks[ti];
+    for (let ci = 0; ci < track.contents.length; ci++) {
+      const item = track.contents[ci];
+      if ("source" in item && item.id === id) {
+        return { track, trackIndex: ti, clipIndex: ci };
+      }
+    }
+  }
+  return void 0;
+}
+function findMarkerById(composition, id) {
+  const markers = composition.markers ?? [];
+  for (let i = 0; i < markers.length; i++) {
+    if (markers[i].id === id) return { marker: markers[i], index: i };
+  }
+  return void 0;
+}
+function trimSourceFor(source, clipRelStart, clipRelEnd) {
+  if (source.kind !== "media") return source;
+  const baseStart = source.trim?.start ?? 0;
+  return {
+    ...source,
+    trim: { start: baseStart + clipRelStart, end: baseStart + clipRelEnd }
+  };
+}
+function cutTimedRange(start, end, cutStart, cutEnd) {
+  const span = cutEnd - cutStart;
+  if (start >= cutEnd) {
+    return { start: start - span, end: end !== void 0 ? end - span : void 0 };
+  }
+  if (start < cutStart) {
+    if (end === void 0 || end <= cutStart) return { start, end };
+    return { start, end: Math.max(start, end - span) };
+  }
+  return null;
+}
+function shiftTimedRange(start, end, from, amount) {
+  if (start < from) return null;
+  const s = Math.max(0, start + amount);
+  return { start: s, end: end !== void 0 ? Math.max(s, end + amount) : void 0 };
+}
+function selectionPatch(composition, entities) {
+  const clipIds = entities.filter((e) => e.kind === "clip").map((e) => e.clipId);
+  const overlayIds = /* @__PURE__ */ new Set();
+  for (const track of composition.tracks) {
+    if (track.kind !== "overlay") continue;
+    for (const item of track.contents) {
+      if ("source" in item) overlayIds.add(item.id);
+    }
+  }
+  return {
+    selection: [...entities],
+    selectedClipId: clipIds.find((id) => !overlayIds.has(id)) ?? null,
+    selectedOverlayId: clipIds.find((id) => overlayIds.has(id)) ?? null
+  };
+}
+function pruneSelectionInDraft(draft, removedClipIds) {
+  const kept = draft.selection.filter(
+    (e) => !("clipId" in e) || !removedClipIds.has(e.clipId)
+  );
+  const patch = selectionPatch(draft.composition, kept);
+  draft.selection = patch.selection;
+  draft.selectedClipId = patch.selectedClipId;
+  draft.selectedOverlayId = patch.selectedOverlayId;
+}
+function createCompositionOps(get, set) {
+  return {
+    // ── Clip operations ──
+    addClip: (clip, options) => {
+      set((draft) => {
+        if (options?.newTrack) {
+          const track = {
+            id: options.newTrackId ?? `track-video-${crypto.randomUUID().slice(0, 8)}`,
+            kind: "video",
+            contents: [clip]
+          };
+          draft.composition.tracks.push(track);
+        } else {
+          const track = findOrCreateTrackByKind(draft.composition, "video");
+          track.contents.push(clip);
+        }
+      });
+    },
+    /**
+     * Family-routed clip add — the single primitive behind the consolidated
+     * `clip.add` op (@cueframe/composition-ops). Routes a clip onto a track of
+     * the resolved FAMILY: either an existing track pinned by `trackId`, or a
+     * track of `kind` (created if absent, optionally with a pinned `newTrackId`
+     * for byte-faithful op-replay). Replaces the three family-specific adders
+     * (addClip/addOverlay/addAudioClip) at the OP layer — those stay for the
+     * editor's direct calls.
+     *
+     * Fails LOUD if `trackId` names a missing track, or a track of a DIFFERENT
+     * family (a clip must land on its own family — never silently mis-route).
+     */
+    addClipToTrack: (clip, target) => {
+      set((draft) => {
+        if ("trackId" in target) {
+          const track2 = draft.composition.tracks.find((t) => t.id === target.trackId);
+          if (!track2) {
+            throw new Error(`addClipToTrack: track '${target.trackId}' not found`);
+          }
+          track2.contents.push(clip);
+          return;
+        }
+        if (target.newTrack) {
+          draft.composition.tracks.push({
+            id: target.newTrackId ?? `track-${target.kind}-${crypto.randomUUID().slice(0, 8)}`,
+            kind: target.kind,
+            contents: [clip]
+          });
+          return;
+        }
+        const track = findOrCreateTrackByKind(draft.composition, target.kind);
+        track.contents.push(clip);
+      });
+    },
+    removeClip: (id) => {
+      set((draft) => {
+        for (const track of draft.composition.tracks) {
+          const idx = track.contents.findIndex((c) => "source" in c && c.id === id);
+          if (idx >= 0) {
+            track.contents.splice(idx, 1);
+            break;
+          }
+        }
+        pruneSelectionInDraft(draft, /* @__PURE__ */ new Set([id]));
+        if (draft.selectedOverlayId === id) draft.selectedOverlayId = null;
+        if (draft.composition.markers) {
+          draft.composition.markers = draft.composition.markers.filter(
+            (m) => m.kind !== "scene" || m.metadata?.clipId !== id
+          );
+        }
+      });
+    },
+    updateClip: (id, updates) => {
+      set((draft) => {
+        for (const track of draft.composition.tracks) {
+          for (let i = 0; i < track.contents.length; i++) {
+            const item = track.contents[i];
+            if ("source" in item && item.id === id) {
+              track.contents[i] = { ...item, ...updates };
+              return;
+            }
+          }
+        }
+      });
+    },
+    /** Remove every clip whose `source.mediaId === mediaId`. */
+    removeClipsByMediaId: (mediaId) => {
+      set((draft) => {
+        const removed = /* @__PURE__ */ new Set();
+        for (const track of draft.composition.tracks) {
+          track.contents = track.contents.filter((c) => {
+            if ("source" in c && c.source.kind === "media" && c.source.mediaId === mediaId) {
+              removed.add(c.id);
+              return false;
+            }
+            return true;
+          });
+        }
+        if (draft.composition.markers) {
+          draft.composition.markers = draft.composition.markers.filter(
+            (m) => m.kind !== "scene" || !removed.has(m.metadata?.clipId ?? "")
+          );
+        }
+        pruneSelectionInDraft(draft, removed);
+      });
+    },
+    selectClip: (id) => {
+      const composition = get().composition;
+      if (id === null) {
+        set(selectionPatch(composition, []));
+        return;
+      }
+      if (findClipById(composition, id)) {
+        set(
+          selectionPatch(
+            composition,
+            expandToLinkGroup(composition, [{ kind: "clip", clipId: id }])
+          )
+        );
+      }
+    },
+    /** Replace the whole selection. The multi-select entry point. */
+    setSelection: (entities) => {
+      const composition = get().composition;
+      const live = entities.filter(
+        (e) => !("clipId" in e) || !!findClipById(composition, e.clipId)
+      );
+      set(selectionPatch(composition, expandToLinkGroup(composition, live)));
+    },
+    /** Every clip on the timeline, in track then start order. */
+    selectAllClips: () => {
+      const composition = get().composition;
+      const entities = [];
+      for (const track of composition.tracks) {
+        for (const item of track.contents) {
+          if ("source" in item) {
+            entities.push({ kind: "clip", clipId: item.id });
+          }
+        }
+      }
+      set(selectionPatch(composition, entities));
+    },
+    setClipProperties: (id, props) => {
+      const found = findClipById(get().composition, id);
+      if (!found) return { rippled: false };
+      const clip = found.clip;
+      let rateChange = null;
+      if (props.playbackRate != null && clip.source.kind === "media") {
+        const oldRate = clip.source.playbackRate ?? 1;
+        if (props.playbackRate !== oldRate) {
+          const trim = clip.source.trim;
+          const sourceDuration = trim ? trim.end - trim.start : clip.duration * oldRate;
+          const newDuration = sourceDuration / props.playbackRate;
+          const oldEnd = clip.startTime + clip.duration;
+          const delta = newDuration - clip.duration;
+          rateChange = { newRate: props.playbackRate, newDuration, oldEnd, delta };
+        }
+      }
+      set((draft) => {
+        const f = findClipById(draft.composition, id);
+        if (!f) return;
+        const target = f.clip;
+        if (props.opacity !== void 0) target.opacity = props.opacity;
+        if (props.scale !== void 0) target.scale = props.scale;
+        if (props.rotation !== void 0) target.rotation = props.rotation;
+        if (props.region !== void 0) target.region = props.region;
+        if (props.fit !== void 0) target.fit = props.fit;
+        if (rateChange) {
+          if (target.source.kind === "media") {
+            target.source.playbackRate = rateChange.newRate;
+          }
+          target.duration = rateChange.newDuration;
+          if (rateChange.delta !== 0) {
+            for (const track of draft.composition.tracks) {
+              for (let i = 0; i < track.contents.length; i++) {
+                const item = track.contents[i];
+                if ("source" in item && item.id !== id && item.startTime >= rateChange.oldEnd) {
+                  item.startTime = Math.max(0, item.startTime + rateChange.delta);
+                }
+              }
+            }
+            for (const m of draft.composition.markers ?? []) {
+              if (m.startTime >= rateChange.oldEnd) {
+                m.startTime = Math.max(0, m.startTime + rateChange.delta);
+                if (m.endTime !== void 0) {
+                  m.endTime = Math.max(m.startTime, m.endTime + rateChange.delta);
+                }
+              }
+            }
+          }
+        }
+      });
+      return { rippled: rateChange ? rateChange.delta !== 0 : false };
+    },
+    // ── Overlay operations (TimelineClips on kind:'overlay' tracks) ──
+    // GUARD AT THE WRITE. An overlay source without a `primitiveId` is not a clip — it is a
+    // hole that renders as `unknown overlay primitive 'undefined'`, and the RENDERER was the
+    // first thing to notice it (2026-07-13: every capture_frames of a live compose died on
+    // this, the author went blind, and it landed zero graphics on a 90s customer pitch).
+    //
+    // `primitiveId: z.string().min(1)` is ALREADY required by the composition validator — but
+    // the in-loop capture path renders the in-memory store and never validates it, so the
+    // schema never ran. Refuse at the write instead, where the caller is still on the stack and
+    // the message can name it. (Same reasoning as compositionRender's `custom`-with-no-
+    // sourceCode guard, which patched one instance of this at the render boundary; this closes
+    // the class.)
+    addOverlay: (clip) => {
+      if (clip.source.kind === "overlay" && !clip.source.primitiveId) {
+        throw new Error(
+          `addOverlay: clip "${clip.id}" has an overlay source with no primitiveId. A built-in is placed by primitiveId (source.kind:'overlay'); an org-installed component is placed by componentId (source.kind:'component'). Use the catalog's \`placement\` hint for the id you picked \u2014 do not write one kind with the other's id.`
+        );
+      }
+      set((draft) => {
+        const track = findOrCreateTrackByKind(draft.composition, "overlay");
+        track.contents.push(clip);
+      });
+    },
+    removeOverlay: (id) => {
+      set((draft) => {
+        for (const track of draft.composition.tracks) {
+          if (track.kind !== "overlay") continue;
+          const idx = track.contents.findIndex((c) => "source" in c && c.id === id);
+          if (idx >= 0) {
+            track.contents.splice(idx, 1);
+            break;
+          }
+        }
+        if (draft.selectedOverlayId === id) draft.selectedOverlayId = null;
+      });
+    },
+    updateOverlay: (id, updates) => {
+      set((draft) => {
+        for (const track of draft.composition.tracks) {
+          if (track.kind !== "overlay") continue;
+          for (let i = 0; i < track.contents.length; i++) {
+            const item = track.contents[i];
+            if ("source" in item && item.id === id) {
+              track.contents[i] = { ...item, ...updates };
+              return;
+            }
+          }
+        }
+      });
+    },
+    selectOverlay: (id) => {
+      for (const track of get().composition.tracks) {
+        if (track.kind !== "overlay") continue;
+        if (track.contents.some((c) => "source" in c && c.id === id)) {
+          set(selectionPatch(get().composition, [{ kind: "clip", clipId: id }]));
+          return;
+        }
+      }
+    },
+    clearOverlaySelection: () => {
+      const composition = get().composition;
+      const kept = get().selection.filter((e) => {
+        if (e.kind !== "clip") return true;
+        const found = findClipById(composition, e.clipId);
+        return found ? composition.tracks[found.trackIndex].kind !== "overlay" : false;
+      });
+      set(selectionPatch(composition, kept));
+    },
+    /**
+     * (see addOverlay's guard) Replace all overlays — clears existing overlay tracks, creates
+     * one with provided clips.
+     */
+    loadOverlays: (clips) => {
+      set((draft) => {
+        draft.composition.tracks = draft.composition.tracks.filter((t) => t.kind !== "overlay");
+        if (clips.length > 0) {
+          draft.composition.tracks.push({
+            id: `track-overlay-${crypto.randomUUID().slice(0, 8)}`,
+            kind: "overlay",
+            contents: clips
+          });
+        }
+        draft.selectedOverlayId = null;
+      });
+    },
+    // ── Audio operations (TimelineClips on kind:'audio' tracks) ──
+    addAudioClip: (clip) => {
+      set((draft) => {
+        const track = findOrCreateTrackByKind(draft.composition, "audio");
+        track.contents.push(clip);
+      });
+    },
+    removeAudioClip: (id) => {
+      set((draft) => {
+        for (const track of draft.composition.tracks) {
+          if (track.kind !== "audio") continue;
+          const idx = track.contents.findIndex((c) => "source" in c && c.id === id);
+          if (idx >= 0) {
+            track.contents.splice(idx, 1);
+            break;
+          }
+        }
+      });
+    },
+    updateAudioClip: (id, updates) => {
+      set((draft) => {
+        for (const track of draft.composition.tracks) {
+          if (track.kind !== "audio") continue;
+          for (let i = 0; i < track.contents.length; i++) {
+            const item = track.contents[i];
+            if ("source" in item && item.id === id) {
+              track.contents[i] = { ...item, ...updates };
+              return;
+            }
+          }
+        }
+      });
+    },
+    // ── Marker operations ──
+    addMarker: (marker) => {
+      set((draft) => {
+        if (!draft.composition.markers) draft.composition.markers = [];
+        draft.composition.markers.push(marker);
+      });
+    },
+    removeMarker: (id) => {
+      set((draft) => {
+        if (!draft.composition.markers) return;
+        draft.composition.markers = draft.composition.markers.filter((m) => m.id !== id);
+      });
+    },
+    updateMarker: (id, updates) => {
+      set((draft) => {
+        if (!draft.composition.markers) return;
+        const m = draft.composition.markers.find((x) => x.id === id);
+        if (m) Object.assign(m, updates);
+      });
+    },
+    // ── cutAndRipple (replaces v1 deletedRanges) ──
+    cutAndRipple: (start, end) => {
+      if (!Number.isFinite(start) || !Number.isFinite(end) || start >= end) return;
+      const span = end - start;
+      set((draft) => {
+        for (const track of draft.composition.tracks) {
+          const next = [];
+          for (const item of track.contents) {
+            if (!("source" in item)) {
+              next.push(item);
+              continue;
+            }
+            const c = item;
+            const cs = c.startTime;
+            const ce = c.startTime + c.duration;
+            if (ce <= start) {
+              next.push(c);
+              continue;
+            }
+            if (cs >= end) {
+              next.push({ ...c, startTime: Math.max(0, cs - span) });
+              continue;
+            }
+            if (cs < start) {
+              const leftDuration = start - cs;
+              const leftSource = trimSourceFor(c.source, 0, leftDuration);
+              next.push({ ...c, id: c.id, duration: leftDuration, source: leftSource });
+            }
+            if (ce > end) {
+              const rightDuration = ce - end;
+              const sourceOffsetIntoOriginal = end - cs;
+              const rightSource = trimSourceFor(
+                c.source,
+                sourceOffsetIntoOriginal,
+                sourceOffsetIntoOriginal + rightDuration
+              );
+              next.push({
+                ...c,
+                id: `${c.id}-r`,
+                startTime: start,
+                duration: rightDuration,
+                source: rightSource
+              });
+            }
+          }
+          track.contents = next;
+        }
+        if (draft.composition.markers) {
+          draft.composition.markers = draft.composition.markers.flatMap((m) => {
+            const r = cutTimedRange(m.startTime, m.endTime, start, end);
+            return r ? [{ ...m, startTime: r.start, endTime: r.end }] : [];
+          });
+        }
+        if (draft.composition.captions?.source === "derived") {
+          for (const seg of draft.composition.captions.segments) {
+            seg.words = seg.words.flatMap((w) => {
+              const r = cutTimedRange(w.startMs, w.endMs, start * 1e3, end * 1e3);
+              return r ? [{ ...w, startMs: r.start, endMs: r.end ?? w.endMs }] : [];
+            });
+          }
+        }
+      });
+    },
+    // ── addExcludedRange ──
+    //
+    // Marks a range of source media on a media-source clip as excluded.
+    // Atomically: clamps to the clip's `trim` window, merges/coalesces with
+    // existing `excludedRanges` (touching ranges merge), shrinks
+    // `clip.duration` by the net delta added to Σ excluded, and ripples
+    // downstream same-track items left by that delta.
+    //
+    // Wire-shape invariant: (trim.end − trim.start) − Σexcludedrange = duration.
+    // The `trimEnd` fallback below restores trim.end from
+    // `duration + Σexcluded` when `trim` is absent — the same invariant
+    // rearranged.
+    addExcludedRange: (clipId, sourceStart, sourceEnd, reason) => {
+      if (!Number.isFinite(sourceStart) || !Number.isFinite(sourceEnd)) return;
+      if (!(sourceEnd > sourceStart)) return;
+      set((draft) => {
+        const found = findClipById(draft.composition, clipId);
+        if (!found) return;
+        const track = draft.composition.tracks[found.trackIndex];
+        if (track.kind !== "video" && track.kind !== "audio") return;
+        const target = found.clip;
+        if (target.source.kind !== "media") return;
+        const before = target.source.excludedRanges ?? [];
+        const beforeTotal = before.reduce((acc, r) => acc + (r.end - r.start), 0);
+        const trimStart = target.source.trim?.start ?? 0;
+        const trimEnd = target.source.trim?.end ?? trimStart + target.duration + beforeTotal;
+        const lo = Math.max(sourceStart, trimStart);
+        const hi = Math.min(sourceEnd, trimEnd);
+        if (!(hi > lo)) return;
+        const merged = [];
+        let inserted = false;
+        let curStart = lo;
+        let curEnd = hi;
+        let curReason = reason;
+        for (const r of before) {
+          if (r.end < curStart) {
+            merged.push(r);
+            continue;
+          }
+          if (r.start > curEnd) {
+            if (!inserted) {
+              merged.push({
+                start: curStart,
+                end: curEnd,
+                ...curReason !== void 0 ? { reason: curReason } : {}
+              });
+              inserted = true;
+            }
+            merged.push(r);
+            continue;
+          }
+          curStart = Math.min(curStart, r.start);
+          curEnd = Math.max(curEnd, r.end);
+          curReason = curReason ?? r.reason;
+        }
+        if (!inserted) {
+          merged.push({
+            start: curStart,
+            end: curEnd,
+            ...curReason !== void 0 ? { reason: curReason } : {}
+          });
+        }
+        const afterTotal = merged.reduce((acc, r) => acc + (r.end - r.start), 0);
+        const delta = afterTotal - beforeTotal;
+        if (delta <= 0) return;
+        if (target.duration - delta <= 1e-3) return;
+        target.source.excludedRanges = merged;
+        target.duration = target.duration - delta;
+        for (let i = found.clipIndex + 1; i < track.contents.length; i++) {
+          track.contents[i].startTime = Math.max(0, track.contents[i].startTime - delta);
+        }
+        const excludedBeforeLo = before.reduce(
+          (acc, r) => acc + Math.max(0, Math.min(r.end, lo) - Math.max(r.start, trimStart)),
+          0
+        );
+        const tStart = target.startTime + (lo - trimStart) - excludedBeforeLo;
+        const tEnd = tStart + delta;
+        if (draft.composition.markers) {
+          draft.composition.markers = draft.composition.markers.flatMap((m) => {
+            const r = cutTimedRange(m.startTime, m.endTime, tStart, tEnd);
+            return r ? [{ ...m, startTime: r.start, endTime: r.end }] : [];
+          });
+        }
+        if (draft.composition.captions) {
+          for (const seg of draft.composition.captions.segments) {
+            seg.words = seg.words.flatMap((w) => {
+              const r = cutTimedRange(w.startMs, w.endMs, tStart * 1e3, tEnd * 1e3);
+              return r ? [{ ...w, startMs: r.start, endMs: r.end ?? w.endMs }] : [];
+            });
+          }
+        }
+      });
+    },
+    // ── removeExcludedRange ──
+    //
+    // Inverse of addExcludedRange. Removes the excluded range at the given
+    // index, restores the clip's duration by the same amount, and ripples
+    // downstream same-track items right. When the resulting list is empty,
+    // drops the field entirely so the wire stays canonical.
+    removeExcludedRange: (clipId, rangeIdx) => {
+      set((draft) => {
+        const found = findClipById(draft.composition, clipId);
+        if (!found) return;
+        const track = draft.composition.tracks[found.trackIndex];
+        if (track.kind !== "video" && track.kind !== "audio") return;
+        const target = found.clip;
+        if (target.source.kind !== "media") return;
+        const ranges = target.source.excludedRanges;
+        if (!ranges || rangeIdx < 0 || rangeIdx >= ranges.length) return;
+        const removed = ranges[rangeIdx];
+        const restored = removed.end - removed.start;
+        if (restored <= 0) return;
+        const next = ranges.filter((_, i) => i !== rangeIdx);
+        if (next.length === 0) {
+          delete target.source.excludedRanges;
+        } else {
+          target.source.excludedRanges = next;
+        }
+        target.duration = target.duration + restored;
+        for (let i = found.clipIndex + 1; i < track.contents.length; i++) {
+          track.contents[i].startTime = track.contents[i].startTime + restored;
+        }
+      });
+    },
+    // ── setCropIntents ──
+    //
+    // Author the camera channel (`reframe`) on a media clip. Each segment
+    // carries the canonical reframe params (focus, zoom, bias, ease) the
+    // derive math honors directly — no closed-enum framing names, no
+    // hardcoded scale constants.
+    //
+    // `null`/empty clears `reframe`; the clip then renders from the raw source.
+    //
+    // Used by the agent's `set_crop_intents` tool (name kept; the arg shape is
+    // reframe) and the desktop editor's framing timeline. Replaces the deleted
+    // subject-centric cropIntents (2026-06-14 cutover).
+    setCropIntents: (clipId, segments) => {
+      set((draft) => {
+        const found = findClipById(draft.composition, clipId);
+        if (!found) return;
+        const target = found.clip;
+        if (target.source.kind !== "media") return;
+        if (segments === null || segments.length === 0) {
+          delete target.source.reframe;
+        } else {
+          target.source.reframe = { segments };
+        }
+      });
+    },
+    // ── setEffects ──
+    //
+    // Author a clip's EFFECT channel (`TimelineClip.effects`) — the registered
+    // effect primitives (+ params) the renderer stacks onto that clip. WHOLESALE:
+    // the array REPLACES whatever was there, and `[]` CLEARS the channel (the
+    // same set/clear shape setCropIntents has). `effects` has been in the
+    // validator — and accepted by `clip.add` — all along, but until the
+    // `setEffects` op there was no way to change it on an EXISTING clip except a
+    // whole-clip `clip.update` patch, which the op vocabulary explicitly steers
+    // callers away from (a partial `source` in that patch clobbers the source).
+    //
+    // Named EXACTLY like the wire op it records (`setEffects`) — the factory and
+    // the op vocabulary are one vocabulary, so there is no method→op rename table
+    // for the conformance guard to carry.
+    //
+    // Cross-track by id, like `updateClip` — the clip's family is irrelevant to
+    // its effect stack. Same merge shape as `updateClip(id, { effects })`.
+    setEffects: (clipId, effects) => {
+      set((draft) => {
+        const found = findClipById(draft.composition, clipId);
+        if (!found) return;
+        if (effects.length === 0) {
+          delete found.clip.effects;
+        } else {
+          found.clip.effects = effects;
+        }
+      });
+    },
+    // ── setCaptionStyle ──
+    //
+    // Apply the agent's caption STYLE overrides (font, size, color, position,
+    // emphasis treatment, …) onto the top-level `composition.captions.style` —
+    // the exact field the renderer consumes (compositionRender.ts) and the
+    // Captions primitive reads. Merge (not replace) so each `set_captions` call
+    // overrides only the fields it names and leaves the rest (and the
+    // transcript-sliced `words`) intact. Undefined fields are dropped so an
+    // omitted field never clobbers an existing one. If captions don't exist yet
+    // (style set before the transcript slice lands), create the container with
+    // empty words — the compose/insert path fills the words.
+    setCaptionStyle: (style) => {
+      set((draft) => {
+        const clean = Object.fromEntries(
+          Object.entries(style).filter(([, v]) => v !== void 0)
+        );
+        if (Object.keys(clean).length === 0) return;
+        const existing = draft.composition.captions;
+        if (existing) {
+          existing.style = { ...existing.style ?? {}, ...clean };
+        } else {
+          draft.composition.captions = { source: "authored", segments: [], style: clean };
+        }
+      });
+    },
+    // ── setCaptions ──
+    //
+    // Replace the caption SEGMENTS wholesale — the words layer. Until this op,
+    // caption words were populated ONLY by the compose/from-suggestion
+    // transcript-slice lanes, so a client agent holding its own word timings
+    // (e.g. a generated VO take) had no way to author the engine caption layer
+    // (memoir v4, 2026-07-21). Segments REPLACE (not merge — word timing is one
+    // coherent document); `style`, when given, merges with setCaptionStyle
+    // semantics, and an omitted style keeps the existing one.
+    setCaptions: (segments, style, derivedFrom) => {
+      set((draft) => {
+        const existing = draft.composition.captions;
+        const mergedStyle = style ? {
+          ...existing?.style ?? {},
+          ...Object.fromEntries(Object.entries(style).filter(([, v]) => v !== void 0))
+        } : existing?.style;
+        const styleField = mergedStyle && Object.keys(mergedStyle).length > 0 ? { style: mergedStyle } : {};
+        draft.composition.captions = derivedFrom ? { source: "derived", from: derivedFrom, segments, ...styleField } : { source: "authored", segments, ...styleField };
+      });
+    },
+    // ── ripple ──
+    ripple: (time, amount) => {
+      set((draft) => {
+        for (const track of draft.composition.tracks) {
+          for (const item of track.contents) {
+            if (!("source" in item)) continue;
+            const c = item;
+            if (c.startTime >= time) {
+              c.startTime = Math.max(0, c.startTime + amount);
+            } else if (c.startTime + c.duration > time && amount < 0) {
+              c.duration = Math.max(0.1, c.duration + amount);
+            }
+          }
+        }
+        for (const m of draft.composition.markers ?? []) {
+          const r = shiftTimedRange(m.startTime, m.endTime, time, amount);
+          if (r) {
+            m.startTime = r.start;
+            if (r.end !== void 0) m.endTime = r.end;
+          }
+        }
+        if (draft.composition.captions) {
+          for (const seg of draft.composition.captions.segments) {
+            for (const w of seg.words) {
+              const r = shiftTimedRange(w.startMs, w.endMs, time * 1e3, amount * 1e3);
+              if (r) {
+                w.startMs = r.start;
+                w.endMs = r.end ?? w.endMs;
+              }
+            }
+          }
+        }
+      });
+    },
+    // ── Canvas / format ──
+    //
+    // Patches `composition.format` — `aspectRatio` is required (the field
+    // has no default), `fps`, `resolution`, and `platform` fall back to the
+    // existing values on the wire. Clip start/duration values are not retimed:
+    // a 30→60 fps switch keeps the same wall-clock seconds. Layout-sensitive
+    // overlays may need re-rendering by the caller after a switch. `platform`
+    // is output-determining (safe-zone placement) — carry it forward so an
+    // aspect-only change never silently erases it.
+    setFormat: (next) => {
+      set((draft) => {
+        const prev = draft.composition.format;
+        draft.composition.format = {
+          aspectRatio: next.aspectRatio,
+          ...next.fps !== void 0 ? { fps: next.fps } : prev.fps !== void 0 ? { fps: prev.fps } : {},
+          ...next.resolution !== void 0 ? { resolution: next.resolution } : prev.resolution !== void 0 ? { resolution: prev.resolution } : {},
+          ...next.platform !== void 0 ? { platform: next.platform } : prev.platform !== void 0 ? { platform: prev.platform } : {}
+        };
+      });
+    },
+    // ── Track operations ──
+    //
+    // Capability parity: the cloud agent must be able to do everything the
+    // editor can (these were previously editor-only, in
+    // cueframe/src/store/compositionStore/compositionOps.ts). They are pure
+    // `set` mutations over `composition.tracks` + the selection fields already
+    // on `CompositionOpsState`, so they live in core unchanged. The agent's
+    // tool layer can now surface them; the editor keeps calling the same names.
+    /**
+     * Append a new track of `kind` to `composition.tracks`. If `id` is omitted
+     * a UUID-suffixed id is generated (matches `findOrCreateTrackByKind`).
+     */
+    addTrack: (kind, name, id) => {
+      set((draft) => {
+        const track = {
+          id: id ?? `track-${kind}-${crypto.randomUUID().slice(0, 8)}`,
+          kind,
+          name,
+          contents: []
+        };
+        draft.composition.tracks.push(track);
+      });
+    },
+    /** Remove a track and any clip selection that references its contents. */
+    removeTrack: (trackId) => {
+      set((draft) => {
+        const idx = draft.composition.tracks.findIndex((t) => t.id === trackId);
+        if (idx < 0) return;
+        const removed = draft.composition.tracks[idx];
+        const removedClipIds = new Set(
+          removed.contents.filter((c) => "source" in c).map((c) => c.id)
+        );
+        pruneSelectionInDraft(draft, removedClipIds);
+        if (draft.selectedOverlayId && removedClipIds.has(draft.selectedOverlayId)) {
+          draft.selectedOverlayId = null;
+        }
+        draft.composition.tracks.splice(idx, 1);
+      });
+    },
+    /** Patch a track's `name` / `enabled`. */
+    updateTrack: (trackId, updates) => {
+      set((draft) => {
+        const track = draft.composition.tracks.find((t) => t.id === trackId);
+        if (!track) return;
+        if ("name" in updates) track.name = updates.name;
+        if ("enabled" in updates) track.enabled = updates.enabled;
+        if ("volume" in updates) {
+          track.volume = updates.volume === 1 ? void 0 : updates.volume;
+        }
+      });
+    },
+    /** Move a track from `fromIndex` to `toIndex` within `composition.tracks`. */
+    reorderTracks: (fromIndex, toIndex) => {
+      set((draft) => {
+        const len = draft.composition.tracks.length;
+        if (fromIndex < 0 || fromIndex >= len) return;
+        const clamped = Math.max(0, Math.min(toIndex, len - 1));
+        if (clamped === fromIndex) return;
+        const [moved] = draft.composition.tracks.splice(fromIndex, 1);
+        draft.composition.tracks.splice(clamped, 0, moved);
+      });
+    },
+    /**
+     * Move a clip to a different track, optionally updating its startTime.
+     *
+     * The op trusts callers to validate kind-compatibility and overlap; the
+     * Fabric drag handler is responsible for snapping back when invalid. No-op
+     * if the clip isn't found, the target track doesn't exist, or target ===
+     * source. Selection stays put (the clip id is unchanged).
+     */
+    moveClipToTrack: (clipId, targetTrackId, newStartTime) => {
+      set((draft) => {
+        let sourceTrack;
+        let clipIdx = -1;
+        for (const t of draft.composition.tracks) {
+          const idx = t.contents.findIndex((c) => "source" in c && c.id === clipId);
+          if (idx >= 0) {
+            sourceTrack = t;
+            clipIdx = idx;
+            break;
+          }
+        }
+        if (!sourceTrack || clipIdx < 0) return;
+        const target = draft.composition.tracks.find((t) => t.id === targetTrackId);
+        if (!target) return;
+        if (target.id === sourceTrack.id && newStartTime === void 0) return;
+        const [moved] = sourceTrack.contents.splice(clipIdx, 1);
+        const clip = moved;
+        if (newStartTime !== void 0) clip.startTime = newStartTime;
+        target.contents.push(clip);
+        target.contents.sort((a, b) => a.startTime - b.startTime);
+      });
+    },
+    /**
+     * Duplicate a clip. The copy receives a new id and is appended to the same
+     * track immediately after the original's `[startTime + duration]` (nudged
+     * forward to avoid overlap with whatever follows).
+     */
+    duplicateClip: (id) => {
+      let newId;
+      set((draft) => {
+        for (const track of draft.composition.tracks) {
+          const idx = track.contents.findIndex((c) => "source" in c && c.id === id);
+          if (idx < 0) continue;
+          const original = track.contents[idx];
+          const clipEnd = original.startTime + original.duration;
+          let placementStart = clipEnd;
+          for (let j = idx + 1; j < track.contents.length; j++) {
+            const next = track.contents[j];
+            if (next.startTime >= placementStart + original.duration) break;
+            placementStart = next.startTime + next.duration;
+          }
+          newId = `${original.id}-dup-${crypto.randomUUID().slice(0, 6)}`;
+          const copy = { ...original, id: newId, startTime: placementStart };
+          delete copy.linkGroupId;
+          track.contents.splice(idx + 1, 0, copy);
+          break;
+        }
+      });
+      return newId;
+    }
+  };
+}
+
+// ../composition/src/ops/headlessStore.ts
+import { produce } from "immer";
+function emptyComposition() {
+  return { v: 1, format: { aspectRatio: "16:9" }, tracks: [] };
+}
+function compositionWithSourceClip(spec) {
+  const parsed = Composition.safeParse({
+    v: 1,
+    format: spec.format,
+    tracks: [
+      {
+        id: "track-video",
+        kind: "video",
+        name: "Main video",
+        contents: [
+          {
+            id: "clip-0",
+            startTime: 0,
+            duration: Math.max(0, spec.endTime - spec.startTime),
+            source: {
+              kind: "media",
+              mediaId: spec.mediaId,
+              trim: { start: spec.startTime, end: spec.endTime }
+            }
+          }
+        ]
+      }
+    ]
+  });
+  if (!parsed.success) {
+    throw new Error(
+      `compositionWithSourceClip: produced an invalid composition \u2014 ${parsed.error.message}`
+    );
+  }
+  return parsed.data;
+}
+function emptyCompositionState() {
+  return {
+    composition: emptyComposition(),
+    selection: [],
+    selectedClipId: null,
+    selectedOverlayId: null
+  };
+}
+function createHeadlessStore(initial) {
+  let state;
+  if (!initial) {
+    state = emptyCompositionState();
+  } else if ("composition" in initial) {
+    state = initial;
+  } else {
+    state = {
+      composition: initial,
+      selection: [],
+      selectedClipId: null,
+      selectedOverlayId: null
+    };
+  }
+  const get = () => state;
+  const set = (fnOrPartial) => {
+    if (typeof fnOrPartial === "function") {
+      state = produce(state, fnOrPartial);
+    } else {
+      state = { ...state, ...fnOrPartial };
+    }
+  };
+  return {
+    ...createCompositionOps(get, set),
+    getState: get,
+    batch: (fn) => fn()
+  };
+}
+
+// ../composition/src/ops/selectors.ts
+function selectAllTracks(composition) {
+  return composition.tracks;
+}
+function selectTracksByKind(composition, kind) {
+  return composition.tracks.filter((t) => t.kind === kind);
+}
+function selectAllClips(composition) {
+  return composition.tracks.filter((t) => t.kind === "video").flatMap((t) => t.contents.filter((c) => "source" in c));
+}
+function selectMediaClipAt(composition, seconds) {
+  for (const clip of selectAllClips(composition)) {
+    if (seconds < clip.startTime) continue;
+    if (seconds >= clip.startTime + clip.duration) continue;
+    if (clip.source.kind !== "media") continue;
+    return clip;
+  }
+  return null;
+}
+function selectAllOverlays(composition) {
+  return composition.tracks.filter((t) => t.kind === "overlay").flatMap((t) => t.contents.filter((c) => "source" in c));
+}
+function describeFrameAt(composition, seconds) {
+  const clip = selectMediaClipAt(composition, seconds);
+  const overlays = selectAllOverlays(composition).filter(
+    (c) => seconds >= c.startTime && seconds < c.startTime + c.duration
+  ).length;
+  return {
+    video: clip !== null && clip.source.kind === "media" ? clip.source.mediaId : null,
+    overlays
+  };
+}
+function selectAllAudioClips(composition) {
+  return composition.tracks.filter((t) => t.kind === "audio").flatMap((t) => t.contents.filter((c) => "source" in c));
+}
+function selectClipById(composition, id) {
+  for (const t of composition.tracks) {
+    for (const c of t.contents) {
+      if ("source" in c && c.id === id) return c;
+    }
+  }
+  return void 0;
+}
+function selectMarkers(composition) {
+  return composition.markers ?? [];
+}
+function selectSceneMarkers(composition) {
+  return (composition.markers ?? []).filter((m) => m.kind === "scene");
+}
+
+// ../composition/src/ops/transcript.ts
+function mergeTimelineTranscripts(clips, transcripts) {
+  const words = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const clip of clips) {
+    if (clip.source.kind !== "media") continue;
+    if (clip.source.muted) continue;
+    const mediaId = clip.source.mediaId;
+    const transcript = transcripts[mediaId];
+    if (!transcript?.segments) continue;
+    const trimStart = clip.source.trim?.start ?? 0;
+    const trimEnd = clip.source.trim?.end ?? clip.duration;
+    const rate = clip.source.playbackRate ?? 1;
+    const clippedSegments = transcript.segments.filter(
+      (seg) => seg.startTime >= trimStart && seg.startTime < trimEnd
+    );
+    for (const segment of clippedSegments) {
+      const key = `${mediaId}:${segment.startTime}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const clampedEnd = Math.min(segment.endTime, trimEnd);
+      words.push({
+        text: segment.text,
+        timelineStart: clip.startTime + (segment.startTime - trimStart) / rate,
+        timelineEnd: clip.startTime + (clampedEnd - trimStart) / rate,
+        clipId: clip.id,
+        // The v1 TimelineWord field is named `poolItemId`; v2 calls it
+        // `mediaId`. Same semantic — retain v1 name on the wire so the
+        // agent context (which reads `word.poolItemId`) keeps working.
+        poolItemId: mediaId,
+        sourceStart: segment.startTime,
+        sourceEnd: clampedEnd,
+        speakerId: segment.speakerId
+      });
+    }
+  }
+  return words.sort((a, b) => a.timelineStart - b.timelineStart);
+}
+function formatWordTimings(words, startTime, endTime) {
+  const rangeWords = words.filter(
+    (w) => w.timelineEnd > startTime && w.timelineStart < endTime
+  );
+  if (rangeWords.length === 0) {
+    return `No words found in range ${startTime.toFixed(1)}s\u2013${endTime.toFixed(1)}s`;
+  }
+  const lines = rangeWords.map(
+    (w) => `${w.text}=${w.timelineStart.toFixed(2)}-${w.timelineEnd.toFixed(2)}`
+  );
+  return `Word timings (${startTime.toFixed(1)}s\u2013${endTime.toFixed(1)}s, ${rangeWords.length} words):
+${lines.join(" | ")}`;
+}
+
+export {
+  findOrCreateTrackByKind,
+  findClipById,
+  findTrackContainingClipId,
+  findMarkerById,
+  createCompositionOps,
+  emptyComposition,
+  compositionWithSourceClip,
+  emptyCompositionState,
+  createHeadlessStore,
+  selectAllTracks,
+  selectTracksByKind,
+  selectAllClips,
+  selectMediaClipAt,
+  selectAllOverlays,
+  describeFrameAt,
+  selectAllAudioClips,
+  selectClipById,
+  selectMarkers,
+  selectSceneMarkers,
+  mergeTimelineTranscripts,
+  formatWordTimings
+};