@cueframe/kernel 0.0.1

package/dist/_members/composition/ops/compositionOps.js

@@ -0,0 +1,1056 @@
+/**
+ * compositionOps — pure shared core for v2 wire-shape composition mutations.
+ *
+ * All operations are side-effect-free: no persistence, no logging. Only
+ * state mutations via set/get on the wire-shape Composition.
+ *
+ * Mirrors the desktop store's v2 ops (cueframe/src/store/compositionStore/
+ * compositionOps.ts). The OSS module drops desktop-only concerns
+ * (corrections, transcriptDoc) — those live on the desktop envelope.
+ */
+import { expandToLinkGroup } from '../timeline/link';
+// ── Track-walking helpers ──
+/** Find the first track of `kind`, creating one if absent. Mutates `composition`. */
+export 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;
+}
+/** Find a clip by id across every track. Returns undefined if not found. */
+export 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 undefined;
+}
+/** Find the track containing the clip with given id. */
+export 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 undefined;
+}
+/** Find a marker by id. */
+export 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 undefined;
+}
+/**
+ * For a media-source clip, narrow the source's `trim` window to
+ * `[clipRelStart, clipRelEnd]` (seconds within the clip's existing
+ * timeline duration). For non-media sources, return the source
+ * unchanged — overlay/effect/component sources don't trim.
+ */
+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 },
+    };
+}
+/**
+ * Ripple one timed range through a deleted window `[cutStart, cutEnd)`: a range
+ * starting at/after the window shifts left by the span; a range starting before
+ * it is kept (its end clamped if it straddles the cut start); a range fully
+ * inside is dropped (`null`). `end` may be undefined (a point). Unit-agnostic —
+ * the caller passes the window in the item's own unit. Shared by `cutAndRipple`
+ * for markers (seconds) and caption words (ms) so the algorithm lives once.
+ */
+function cutTimedRange(start, end, cutStart, cutEnd) {
+    const span = cutEnd - cutStart;
+    if (start >= cutEnd) {
+        return { start: start - span, end: end !== undefined ? end - span : undefined };
+    }
+    if (start < cutStart) {
+        if (end === undefined || end <= cutStart)
+            return { start, end };
+        return { start, end: Math.max(start, end - span) };
+    }
+    return null; // fully inside the cut → dropped
+}
+/**
+ * Shift one timed range that starts at/after `from` by `amount` (start clamped
+ * ≥0; end never precedes start). `null` when unchanged (starts before `from`).
+ * Unit-agnostic. Shared by `ripple` for markers and caption words.
+ */
+function shiftTimedRange(start, end, from, amount) {
+    if (start < from)
+        return null;
+    const s = Math.max(0, start + amount);
+    return { start: s, end: end !== undefined ? Math.max(s, end + amount) : undefined };
+}
+// ── Ops factory ──
+/**
+ * THE ONLY WRITER of selection state.
+ *
+ * `selection` is the truth; `selectedClipId` / `selectedOverlayId` are mirrors
+ * derived from it here and nowhere else. Two independently-written
+ * representations of the same fact is how they end up disagreeing, so there is
+ * exactly one function that can set any of the three.
+ */
+function selectionPatch(composition, entities) {
+    const clipIds = entities.filter((e) => e.kind === 'clip').map((e) => e.clipId);
+    const overlayIds = 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,
+    };
+}
+/**
+ * Drop every selection entity naming a now-gone clip, AND recompute the derived
+ * mirrors from what survives.
+ *
+ * Recomputing is the whole point. The first cut of this pruned `selection` and
+ * left the mirrors to their old "null it if it was the removed id" logic, so
+ * deleting clip A out of a selection of {A, B} left `selection: [B]` beside
+ * `selectedClipId: null` — the two representations disagreeing within one op,
+ * which is the exact failure the single-writer rule exists to stop. Caught by
+ * `selection.test.ts`.
+ */
+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;
+}
+export function createCompositionOps(get, set) {
+    return {
+        // ── Clip operations ──
+        addClip: (clip, options) => {
+            set((draft) => {
+                if (options?.newTrack) {
+                    // Layered placement (b-roll over A-roll, picture-in-picture, etc.)
+                    // — create a fresh `video` track so z-order separates the new clip
+                    // from the existing source video. `newTrackId` lets a caller PIN the
+                    // generated id (the op-recording seam passes it so a recorded op
+                    // replays to the identical track); otherwise a uuid suffix is minted
+                    // (matches the `findOrCreateTrackByKind` convention).
+                    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 track = draft.composition.tracks.find((t) => t.id === target.trackId);
+                    if (!track) {
+                        throw new Error(`addClipToTrack: track '${target.trackId}' not found`);
+                    }
+                    track.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, 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 = 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;
+            // Entities naming a clip that is not on the timeline are dropped rather
+            // than stored — a selection that points at nothing is how a verb ends up
+            // acting on a ghost.
+            const live = entities.filter((e) => !('clipId' in e) || !!findClipById(composition, e.clipId));
+            // LINK EXPANSION HAPPENS HERE, once, between selection and every verb.
+            // Putting it inside each verb would work until someone adds a verb and
+            // forgets — and that failure is silent: picture moves, sound does not.
+            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;
+            // Pre-compute whether a rate change applies. Rate-handling and
+            // transform-handling are independent paths so opacity/scale/rotation are
+            // never silently dropped, regardless of source kind or whether the new
+            // rate equals the old (M4, M5).
+            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;
+                // Always apply transform fields if provided — independent of the
+                // rate-handling branch.
+                if (props.opacity !== undefined)
+                    target.opacity = props.opacity;
+                if (props.scale !== undefined)
+                    target.scale = props.scale;
+                if (props.rotation !== undefined)
+                    target.rotation = props.rotation;
+                // Output-space placement primitive (PiP / inset / banner / split-screen).
+                if (props.region !== undefined)
+                    target.region = props.region;
+                if (props.fit !== undefined)
+                    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 !== undefined) {
+                                    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 — 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 }] : [];
+                    });
+                }
+                // Captions ride the same ripple as the clips they caption (in ms).
+                // Without this, a leading/interior cut moves the clip's source `trim`
+                // (which seconds play) while the frozen top-level caption words stay put
+                // — desyncing video and captions by the cut span.
+                // DERIVED ONLY. Rippling is an incremental re-derivation: correct for
+                // words that are a projection of the clip, and vandalism for words a
+                // human or agent wrote. Before captions carried provenance this could
+                // not tell the two apart and silently rewrote both.
+                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 * 1000, end * 1000);
+                            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 !== undefined ? { 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 !== undefined ? { reason: curReason } : {}),
+                    });
+                }
+                const afterTotal = merged.reduce((acc, r) => acc + (r.end - r.start), 0);
+                const delta = afterTotal - beforeTotal;
+                if (delta <= 0)
+                    return;
+                // Refuse to shrink to zero duration — wire shape requires duration > 0.
+                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);
+                }
+                // Ripple top-level markers + captions the same `delta` so they stay
+                // aligned with the now-shorter source — parity with cutAndRipple's
+                // "captions ride clip cuts" invariant (commit 2fac4cf), but WITHOUT
+                // fragmenting the clip. The removed timeline span is [tStart, tStart+delta]
+                // where tStart is the timeline position of the newly-excluded source start:
+                // clip.startTime + played-source-before-lo. `excludedBeforeLo` is the
+                // source already excluded in [trimStart, lo], so the mapping accounts for
+                // prior exclusions and is order-independent across calls.
+                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 * 1000, tEnd * 1000);
+                            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 !== undefined));
+                if (Object.keys(clean).length === 0)
+                    return;
+                const existing = draft.composition.captions;
+                if (existing) {
+                    existing.style = { ...(existing.style ?? {}), ...clean };
+                }
+                else {
+                    // A style with no words is `authored`: the caller stated an intent
+                    // about captions that do not exist yet. It cannot be `derived` —
+                    // there is no clip to name as its source, and inventing one would
+                    // create a projection of nothing that the next clip edit would
+                    // "re-derive" into surprise captions.
+                    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, 
+        /**
+         * WHERE THESE WORDS CAME FROM. Omitted ⇒ `authored`: a caller handed us
+         * literal words and owns them, so nothing rewrites them. Pass
+         * `{ clipId }` when the words are a PROJECTION of that clip's transcript
+         * — then every later edit to the clip re-derives them instead of leaving
+         * a stale snapshot behind (which is what shipped: words timed to 4.4s
+         * inside a 2.4s composition).
+         */
+        derivedFrom) => {
+            set((draft) => {
+                const existing = draft.composition.captions;
+                const mergedStyle = style
+                    ? {
+                        ...(existing?.style ?? {}),
+                        ...Object.fromEntries(Object.entries(style).filter(([, v]) => v !== undefined)),
+                    }
+                    : 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);
+                        }
+                    }
+                }
+                // Markers and caption words ride the shift too (M3) — shift each range
+                // starting at/after `time` by `amount`, in their own unit.
+                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 !== undefined)
+                            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 * 1000, amount * 1000);
+                            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 !== undefined ? { fps: next.fps } : prev.fps !== undefined ? { fps: prev.fps } : {}),
+                    ...(next.resolution !== undefined
+                        ? { resolution: next.resolution }
+                        : prev.resolution !== undefined
+                            ? { resolution: prev.resolution }
+                            : {}),
+                    ...(next.platform !== undefined
+                        ? { platform: next.platform }
+                        : prev.platform !== undefined
+                            ? { 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;
+                // Unity is stored as ABSENT, not as 1 — so a composition nobody has
+                // mixed carries no mixer state at all and diffs stay quiet.
+                if ('volume' in updates) {
+                    track.volume = updates.volume === 1 ? undefined : 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 === undefined)
+                    return;
+                const [moved] = sourceTrack.contents.splice(clipIdx, 1);
+                const clip = moved;
+                if (newStartTime !== undefined)
+                    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;
+                    // Find the earliest gap >= clipEnd on this track for placement; fallback = clipEnd.
+                    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 };
+                    // A single-clip duplicate cannot preserve pairness — and inheriting
+                    // the group id is WORSE than losing it: the copy joins the ORIGINAL'S
+                    // link group, so moving the duplicate drags the original's partner
+                    // with it (review pass 2, 2026-08-24 — the same defect family paste
+                    // had). The duplicate arrives unlinked.
+                    delete copy.linkGroupId;
+                    track.contents.splice(idx + 1, 0, copy);
+                    break;
+                }
+            });
+            return newId;
+        },
+    };
+}