@cueframe/kernel 0.0.1

package/dist/_members/composition-ops/materializeGrid.d.ts

@@ -0,0 +1,56 @@
+import type { Marker } from '../composition/validators/index.js';
+/** The three grid kinds a clip's source media can carry. */
+export type GridKind = 'beat' | 'word' | 'shot';
+/** The author-fixable failure classes, matching the error-registry codes. */
+export type GridErrorCode = 'grid_unavailable' | 'shot_grid_unavailable' | 'grid_cap_exceeded' | 'grid_target_invalid';
+/**
+ * Fail-loud carrier for the materializeGrid guards. `code` is a registered
+ * ErrorCode the op route re-throws as an `ApiError` (422) or folds into a
+ * `dry_run` verdict. `opIndex` is stamped by the route (it knows the batch
+ * position); the pure mapper leaves it undefined.
+ */
+export declare class GridError extends Error {
+    readonly code: GridErrorCode;
+    opIndex?: number | undefined;
+    constructor(code: GridErrorCode, message: string, opIndex?: number | undefined);
+}
+/** Default marker cap (soft — a caller may raise it up to the hard ceiling). */
+export declare const GRID_DEFAULT_MAX_MARKERS = 500;
+/** Hard ceiling on markers materialized from one grid (never exceeded). */
+export declare const GRID_HARD_MAX_MARKERS = 2000;
+/** The subset of a media clip's placement the projection reads. */
+export interface GridPlacement {
+    /** Timeline seconds where the clip starts. */
+    startTime: number;
+    /** Timeline seconds the clip occupies. */
+    duration: number;
+    /** Source-seconds trim window; absent = whole source from 0. */
+    trim?: {
+        start: number;
+        end: number;
+    };
+    /** Source→timeline speed; absent = 1. */
+    playbackRate?: number;
+    /** Source-seconds spans excluded (sorted, non-overlapping). */
+    excludedRanges?: Array<{
+        start: number;
+        end: number;
+    }>;
+}
+/**
+ * Project media-time grid points (ms, in the source's own time) onto the
+ * timeline through `placement`, minting one marker per VISIBLE point. Points
+ * outside the clip's visible window (before/after the trim, or inside an
+ * excluded range) are SKIPPED. Markers are named deterministically
+ * (`<grid>-<n>`, id `grid-<grid>-<clipId>-<n>`, `n` = the running visible index)
+ * so a re-run reproduces the exact set; `metadata.sourceClipId` records the
+ * origin clip so the route can replace a prior materialization idempotently.
+ *
+ * Fails loud (`grid_cap_exceeded`) when the visible count exceeds `maxMarkers`
+ * (default 500) — no silent truncation.
+ */
+export declare function materializeGridMarkers(placement: GridPlacement, gridPointsMs: readonly number[], opts: {
+    grid: GridKind;
+    clipId: string;
+    maxMarkers?: number;
+}): Marker[];

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

@@ -0,0 +1,99 @@
+/**
+ * materializeGrid — the pure media-time → timeline-time grid projection.
+ *
+ * A temporal GRID (beat map / word onsets / shot boundaries) lives in a media
+ * item's own SOURCE time. To land cuts and transition midpoints on it, the grid
+ * points must be mapped THROUGH a clip's placement (startTime, trim, playbackRate,
+ * excludedRanges) into the composition's timeline, and written as markers.
+ *
+ * This module owns the pure projection + the marker minting; the DB-bound work
+ * (reading the clip's source media evidence, idempotent marker replace) is the
+ * route's — `services/convex/api/routes/materializeGrid.ts` — because the op is
+ * route-materialized (the pure engine has no media reader), exactly like
+ * `applyMotionPreset`.
+ *
+ * Source-time↔timeline mapping is NOT reinvented: the visible-window geometry
+ * reuses `playableSpans` (@cueframe/core/render — the SAME trim-minus-excluded
+ * span split the renderer projects), and the per-point timeline formula is the
+ * one `mergeTimelineTranscripts` uses (`startTime + playedSource / playbackRate`),
+ * extended to accumulate played source ACROSS excluded gaps.
+ */
+import { playableSpans } from '@cueframe/core/render';
+/**
+ * Fail-loud carrier for the materializeGrid guards. `code` is a registered
+ * ErrorCode the op route re-throws as an `ApiError` (422) or folds into a
+ * `dry_run` verdict. `opIndex` is stamped by the route (it knows the batch
+ * position); the pure mapper leaves it undefined.
+ */
+export class GridError extends Error {
+    code;
+    opIndex;
+    constructor(code, message, opIndex) {
+        super(message);
+        this.code = code;
+        this.opIndex = opIndex;
+        this.name = 'GridError';
+    }
+}
+/** Default marker cap (soft — a caller may raise it up to the hard ceiling). */
+export const GRID_DEFAULT_MAX_MARKERS = 500;
+/** Hard ceiling on markers materialized from one grid (never exceeded). */
+export const GRID_HARD_MAX_MARKERS = 2000;
+/**
+ * Project media-time grid points (ms, in the source's own time) onto the
+ * timeline through `placement`, minting one marker per VISIBLE point. Points
+ * outside the clip's visible window (before/after the trim, or inside an
+ * excluded range) are SKIPPED. Markers are named deterministically
+ * (`<grid>-<n>`, id `grid-<grid>-<clipId>-<n>`, `n` = the running visible index)
+ * so a re-run reproduces the exact set; `metadata.sourceClipId` records the
+ * origin clip so the route can replace a prior materialization idempotently.
+ *
+ * Fails loud (`grid_cap_exceeded`) when the visible count exceeds `maxMarkers`
+ * (default 500) — no silent truncation.
+ */
+export function materializeGridMarkers(placement, gridPointsMs, opts) {
+    const { grid, clipId } = opts;
+    const cap = opts.maxMarkers ?? GRID_DEFAULT_MAX_MARKERS;
+    const rate = placement.playbackRate ?? 1;
+    const trimStart = placement.trim?.start ?? 0;
+    // Rate-correct source window when trim is absent: the clip plays
+    // `duration * rate` source-seconds from `trimStart`.
+    const trimEnd = placement.trim?.end ?? trimStart + placement.duration * rate;
+    const spans = playableSpans(trimStart, trimEnd, placement.excludedRanges);
+    const markers = [];
+    let n = 0;
+    for (const ms of gridPointsMs) {
+        const sourceSec = ms / 1000;
+        // Accumulate played source-seconds before this point, walking visible spans
+        // in order. A point that falls in a gap (excluded range) or past the last
+        // span is not visible → skipped (no marker, index not advanced).
+        let playedBefore = 0;
+        let visible = false;
+        for (const span of spans) {
+            if (sourceSec < span.start)
+                break; // in a gap before this span → invisible
+            if (sourceSec < span.end) {
+                playedBefore += sourceSec - span.start;
+                visible = true;
+                break;
+            }
+            playedBefore += span.end - span.start; // whole span is before the point
+        }
+        if (!visible)
+            continue;
+        markers.push({
+            id: `grid-${grid}-${clipId}-${n}`,
+            startTime: placement.startTime + playedBefore / rate,
+            kind: grid,
+            name: `${grid}-${n}`,
+            metadata: { sourceClipId: clipId },
+        });
+        n++;
+    }
+    if (markers.length > cap) {
+        throw new GridError('grid_cap_exceeded', `materializeGrid: ${markers.length} '${grid}' markers fall inside clip '${clipId}' — ` +
+            `over the cap of ${cap}. Raise maxMarkers (≤ ${GRID_HARD_MAX_MARKERS}) or narrow the ` +
+            `clip's visible window (trim / excludedRanges) so fewer grid points land.`);
+    }
+    return markers;
+}

package/dist/_members/composition-ops/opRecorder.d.ts

@@ -0,0 +1,77 @@
+/**
+ * wrapWithOpRecorder — THE mutation→op mapping, extracted from
+ * recordingStore so it has exactly one home and two consumers:
+ *
+ *   - `createRecordingStore` (compose bench/eval): wraps the headless store.
+ *   - the EDITOR's compositionOps delegate (cueframe/src/store): wraps the
+ *     zustand-backed op surface, so every user gesture records the same wire
+ *     op an agent would send — the P0.5 "editor writes are ops" seam.
+ *
+ * The wrapper intercepts every mutation of the shared op surface: records
+ * the corresponding {@link CompositionOp} (with the BEFORE composition, for
+ * invertOp), then applies to `base` (optimistic local fold, unchanged UX). Replay contracts (id pinning, track
+ * pre-emit, the family-stamp on addClip, the playbackRate refusal) are the
+ * SAME rules recordingStore always enforced — see the per-method comments.
+ */
+import type { Composition, TimelineClip, Marker, Track, Format, ReframeSegment, CaptionSegment, CaptionStyle, PerClipEffect } from '../composition/validators/index.js';
+import type { CompositionOp } from './index.js';
+/** The mutation surface the recorder knows how to map (the shared op set). No
+ *  count here on purpose: it went stale ("31") the moment ops were consolidated,
+ *  and the authoritative pairing is enforced by GUARD 1
+ *  (`opFactoryVocabulary.test.ts`), not by a number in a comment. */
+export interface RecordableOps {
+    addClip(clip: TimelineClip, options?: {
+        newTrack?: boolean;
+        newTrackId?: string;
+    }): void;
+    removeClip(id: string): void;
+    updateClip(id: string, updates: Partial<TimelineClip>): void;
+    removeClipsByMediaId(mediaId: string): void;
+    setClipProperties(id: string, props: Record<string, unknown>): unknown;
+    addOverlay(clip: TimelineClip): void;
+    removeOverlay(id: string): void;
+    updateOverlay(id: string, updates: Partial<TimelineClip>): void;
+    loadOverlays(clips: TimelineClip[]): void;
+    addAudioClip(clip: TimelineClip): void;
+    removeAudioClip(id: string): void;
+    updateAudioClip(id: string, updates: Partial<TimelineClip>): void;
+    addMarker(marker: Marker): void;
+    removeMarker(id: string): void;
+    updateMarker(id: string, updates: Partial<Marker>): void;
+    setCropIntents(clipId: string, segments: ReframeSegment[] | null): void;
+    setEffects(clipId: string, effects: PerClipEffect[]): void;
+    setCaptionStyle(style: CaptionStyle): void;
+    setCaptions(segments: CaptionSegment[], style?: CaptionStyle): void;
+    setFormat(format: Pick<Format, 'aspectRatio' | 'fps' | 'resolution'>): void;
+    addTrack(kind: Track['kind'], name?: string, id?: string): void;
+    removeTrack(trackId: string): void;
+    updateTrack(trackId: string, updates: Partial<Pick<Track, 'name' | 'enabled'>>): void;
+    reorderTracks(fromIndex: number, toIndex: number): void;
+    moveClipToTrack(clipId: string, targetTrackId: string, newStartTime?: number): void;
+    duplicateClip(id: string): unknown;
+    cutAndRipple(start: number, end: number): void;
+    ripple(time: number, amount: number): void;
+    addExcludedRange(clipId: string, sourceStart: number, sourceEnd: number, reason?: string): void;
+    removeExcludedRange(clipId: string, rangeIdx: number): void;
+}
+export interface OpRecorderOpts {
+    /**
+     * Called for every recorded op with the composition AS OF BEFORE the op
+     * applied — consumers that need inverses compute `invertOp(before, op)`
+     * without replaying history. Ops are recorded BEFORE the base mutation
+     * runs (every mapping derives from args + before-state only), so `before`
+     * is simply the current composition at call time.
+     */
+    record: (op: CompositionOp, before: Composition) => void;
+    /** Current composition — pre-emit checks + the `before` snapshot read it. */
+    getComposition: () => Composition;
+    /**
+     * A mutation the op vocabulary cannot serialize (today: setClipProperties
+     * with playbackRate — a cross-field ripple). When provided, the mutation
+     * APPLIES locally and this fires instead of an op (the editor journals a
+     * guarded snapshot barrier). When absent, the wrapper THROWS — the compose
+     * bench's op-log must stay byte-faithfully replayable.
+     */
+    onUnjournalable?: (reason: string) => void;
+}
+export declare function wrapWithOpRecorder<T extends RecordableOps>(base: T, opts: OpRecorderOpts): T;

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

@@ -0,0 +1,196 @@
+const genTrackId = (kind) => `track-${kind}-${crypto.randomUUID().slice(0, 8)}`;
+export function wrapWithOpRecorder(base, opts) {
+    const { record, getComposition } = opts;
+    const wrapped = {
+        // ── clips ──
+        // clip.add is family-self-routing; a bare `media` source is ambiguous, so
+        // the editor's video-lane addClip stamps kind:'video' (replay byte-faithful:
+        // the SAME object goes to the base store and the op). Every mapping derives
+        // from ARGS + BEFORE-state only, so ops record BEFORE the base mutation —
+        // `before` is exact and a throwing base never leaves a phantom op behind
+        // (record throws first on invalid input; base throws are surfaced to the
+        // caller with the op already journaled, which the flush's server apply
+        // would then reject loudly — never silently).
+        addClip: (clip, options) => {
+            const before = getComposition();
+            const c = clip.kind ? clip : { ...clip, kind: 'video' };
+            if (options?.newTrack) {
+                const newTrackId = options.newTrackId ?? genTrackId('video');
+                record({ type: 'clip.add', clip: c, newTrack: true, newTrackId }, before);
+                base.addClip(c, { newTrack: true, newTrackId });
+            }
+            else {
+                record({ type: 'clip.add', clip: c }, before);
+                base.addClip(c);
+            }
+        },
+        removeClip: (id) => {
+            record({ type: 'clip.remove', clipId: id }, getComposition());
+            base.removeClip(id);
+        },
+        updateClip: (id, updates) => {
+            record({ type: 'clip.update', clipId: id, patch: updates }, getComposition());
+            base.updateClip(id, updates);
+        },
+        removeClipsByMediaId: (mediaId) => {
+            record({ type: 'removeClipsByMediaId', mediaId }, getComposition());
+            base.removeClipsByMediaId(mediaId);
+        },
+        setClipProperties: (id, props) => {
+            // playbackRate is a cross-field ripple (source.playbackRate), NOT a free
+            // clip.update merge. Editor lane: apply locally (the store's ripple is
+            // correct) + signal unjournalable (→ snapshot barrier). Bench lane
+            // (no handler): throw — its op-log must replay byte-faithfully.
+            const { playbackRate, ...patch } = props;
+            if (playbackRate !== undefined) {
+                if (opts.onUnjournalable) {
+                    const result = base.setClipProperties(id, props);
+                    opts.onUnjournalable('setClipProperties.playbackRate');
+                    return result;
+                }
+                throw new Error('opRecorder.setClipProperties: playbackRate is not serializable as a clip.update op ' +
+                    '(source.playbackRate triggers a cross-field ripple). Use the server-authoritative ripple path.');
+            }
+            record({ type: 'clip.update', clipId: id, patch: patch }, getComposition());
+            return base.setClipProperties(id, props);
+        },
+        // ── overlays (pre-emit the overlay track on first add: pinned id, targeted clip.add) ──
+        addOverlay: (clip) => {
+            const before = getComposition();
+            const track = before.tracks.find((t) => t.kind === 'overlay');
+            let trackId = track?.id;
+            if (!trackId) {
+                trackId = genTrackId('overlay');
+                record({ type: 'addTrack', kind: 'overlay', id: trackId }, before);
+                base.addTrack('overlay', undefined, trackId);
+            }
+            record({ type: 'clip.add', clip, trackId }, getComposition());
+            base.addOverlay(clip);
+        },
+        removeOverlay: (id) => {
+            record({ type: 'clip.remove', clipId: id }, getComposition());
+            base.removeOverlay(id);
+        },
+        updateOverlay: (id, updates) => {
+            record({ type: 'clip.update', clipId: id, patch: updates }, getComposition());
+            base.updateOverlay(id, updates);
+        },
+        loadOverlays: (clips) => {
+            record({ type: 'loadOverlays', clips }, getComposition());
+            base.loadOverlays(clips);
+        },
+        // ── audio (same pre-emit rule) ──
+        addAudioClip: (clip) => {
+            const before = getComposition();
+            const track = before.tracks.find((t) => t.kind === 'audio');
+            let trackId = track?.id;
+            if (!trackId) {
+                trackId = genTrackId('audio');
+                record({ type: 'addTrack', kind: 'audio', id: trackId }, before);
+                base.addTrack('audio', undefined, trackId);
+            }
+            record({ type: 'clip.add', clip, trackId }, getComposition());
+            base.addAudioClip(clip);
+        },
+        removeAudioClip: (id) => {
+            record({ type: 'clip.remove', clipId: id }, getComposition());
+            base.removeAudioClip(id);
+        },
+        updateAudioClip: (id, updates) => {
+            record({ type: 'clip.update', clipId: id, patch: updates }, getComposition());
+            base.updateAudioClip(id, updates);
+        },
+        // ── markers ──
+        addMarker: (marker) => {
+            record({ type: 'addMarker', marker }, getComposition());
+            base.addMarker(marker);
+        },
+        removeMarker: (id) => {
+            record({ type: 'removeMarker', markerId: id }, getComposition());
+            base.removeMarker(id);
+        },
+        updateMarker: (id, updates) => {
+            record({ type: 'updateMarker', markerId: id, updates }, getComposition());
+            base.updateMarker(id, updates);
+        },
+        // ── crop / effects / captions / format ──
+        setCropIntents: (clipId, segments) => {
+            record({ type: 'setCropIntents', clipId, segments }, getComposition());
+            base.setCropIntents(clipId, segments);
+        },
+        // Wholesale array — `[]` records the clear, same as any other set.
+        setEffects: (clipId, effects) => {
+            record({ type: 'setEffects', clipId, effects }, getComposition());
+            base.setEffects(clipId, effects);
+        },
+        setCaptionStyle: (style) => {
+            record({ type: 'setCaptionStyle', style }, getComposition());
+            base.setCaptionStyle(style);
+        },
+        setCaptions: (segments, style) => {
+            record({ type: 'setCaptions', segments, ...(style !== undefined ? { style } : {}) }, getComposition());
+            base.setCaptions(segments, style);
+        },
+        setFormat: (format) => {
+            record({ type: 'setFormat', format }, getComposition());
+            base.setFormat(format);
+        },
+        // ── tracks (always pin the id) ──
+        addTrack: (kind, name, id) => {
+            const useId = id ?? genTrackId(kind);
+            record({ type: 'addTrack', kind, ...(name !== undefined ? { name } : {}), id: useId }, getComposition());
+            base.addTrack(kind, name, useId);
+        },
+        removeTrack: (trackId) => {
+            record({ type: 'removeTrack', trackId }, getComposition());
+            base.removeTrack(trackId);
+        },
+        updateTrack: (trackId, updates) => {
+            record({ type: 'updateTrack', trackId, updates }, getComposition());
+            base.updateTrack(trackId, updates);
+        },
+        reorderTracks: (fromIndex, toIndex) => {
+            record({ type: 'reorderTracks', fromIndex, toIndex }, getComposition());
+            base.reorderTracks(fromIndex, toIndex);
+        },
+        moveClipToTrack: (clipId, targetTrackId, newStartTime) => {
+            record({
+                type: 'moveClipToTrack',
+                clipId,
+                targetTrackId,
+                ...(newStartTime !== undefined ? { newStartTime } : {}),
+            }, getComposition());
+            base.moveClipToTrack(clipId, targetTrackId, newStartTime);
+        },
+        duplicateClip: (id) => {
+            record({ type: 'duplicateClip', clipId: id }, getComposition());
+            return base.duplicateClip(id);
+        },
+        // ── server-authoritative (cross-field timeline recompute) ──
+        cutAndRipple: (start, end) => {
+            record({ type: 'cutAndRipple', start, end }, getComposition());
+            base.cutAndRipple(start, end);
+        },
+        ripple: (time, amount) => {
+            record({ type: 'ripple', time, amount }, getComposition());
+            base.ripple(time, amount);
+        },
+        addExcludedRange: (clipId, sourceStart, sourceEnd, reason) => {
+            record({
+                type: 'addExcludedRange',
+                clipId,
+                sourceStart,
+                sourceEnd,
+                ...(reason !== undefined ? { reason } : {}),
+            }, getComposition());
+            base.addExcludedRange(clipId, sourceStart, sourceEnd, reason);
+        },
+        removeExcludedRange: (clipId, rangeIdx) => {
+            record({ type: 'removeExcludedRange', clipId, rangeIdx }, getComposition());
+            base.removeExcludedRange(clipId, rangeIdx);
+        },
+    };
+    // Non-mutation members (getState, selection passthroughs, …) fall through to
+    // base untouched; the wrapped mutations shadow them.
+    return { ...base, ...wrapped };
+}

package/dist/_members/composition-ops/recordingStore.d.ts

@@ -0,0 +1,23 @@
+/**
+ * createRecordingStore — the op-recording seam over the HEADLESS store.
+ *
+ * The mutation→op mapping itself lives in {@link wrapWithOpRecorder}
+ * (opRecorder.ts) — ONE mapping shared with the editor's compositionOps
+ * delegate (P0.5: editor writes are ops). This module only binds it to
+ * `createHeadlessStore` and exposes the accumulated log.
+ *
+ * The recorded op-log replays byte-faithfully:
+ * `ops.reduce(applyOp, seed)` reproduces `getState().composition` exactly —
+ * the wrapper PINS ids the store would otherwise mint (addClip newTrackId,
+ * overlay/audio track pre-emit, addTrack id). Selection ops pass through
+ * unrecorded (UI state, not in the op vocabulary). `duplicateClip` replays
+ * render-equivalent, not byte-identical (non-pinned minted id).
+ */
+import type { Composition } from '../composition/validators/index.js';
+import { type HeadlessStore, type CompositionOpsState } from '../composition/ops/index.js';
+import type { CompositionOp } from './index.js';
+export interface RecordingStore extends HeadlessStore {
+    /** The faithful op-log of every mutation, in order. */
+    getOps(): CompositionOp[];
+}
+export declare function createRecordingStore(initial?: Composition | CompositionOpsState): RecordingStore;

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

@@ -0,0 +1,14 @@
+import { createHeadlessStore, } from '@cueframe/composition/ops';
+import { wrapWithOpRecorder } from './opRecorder';
+export function createRecordingStore(initial) {
+    const base = createHeadlessStore(initial);
+    const ops = [];
+    const wrapped = wrapWithOpRecorder(base, {
+        record: (op, _before) => ops.push(op),
+        getComposition: () => base.getState().composition,
+    });
+    return {
+        ...wrapped,
+        getOps: () => [...ops],
+    };
+}

package/dist/_members/composition-ops/replaceRegion.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `replaceRegion` — the NON-RIPPLING cut/overlay lowering (selector-abstraction
+ * spec §6.2). The genuinely-new timeline primitive the switch instance needs:
+ * neither existing authoring mode fits a same-track temporal cut —
+ *   - `add_clip mode:"layer"` makes a FRESH track (b-roll over A-roll), and
+ *   - `add_clip mode:"ripple-insert"` SHIFTS downstream content.
+ * A multicam switch is an OVERWRITE: A→B→C occupy the SAME region of the SAME
+ * track, back to back, with nothing rippling.
+ *
+ * PLACEMENT: this lives in `@cueframe/composition-ops` (NOT framework-bound; it
+ * already depends on `@cueframe/composition` + `@cueframe/core`). It does NOT
+ * import the Selector core — it consumes a plain `CutSchedule` (the resolver's
+ * lowered advisory), so the source-only concepts (`programAudioSourceId`, cut vs
+ * overlay, source-window placement) live HERE, never in the core.
+ *
+ * Two kinds (spec §6.2):
+ *  - `kind:"cut"` (synced angles): video follows the chosen source; AUDIO FOLLOWS
+ *    the video UNLESS `programAudioSourceId` is set, in which case audio is pinned
+ *    to one continuous bed on a separate audio track while video cuts (topology-i).
+ *  - `kind:"overlay"` (b-roll cutaway): video-over on a NEW overlay/video track,
+ *    primary audio continues (this defers to the existing layer semantics; the
+ *    presence-gate authored its windows). The switch instance authors `cut`.
+ *
+ * Validates fail-loud: the authored segments tile the region without overlap/gap
+ * (the `Gap.strict()` lesson) and every source window is in-media; the result
+ * round-trips `Composition.parse` + `validateComposition`. Pure + deterministic.
+ */
+import { type Composition } from '../composition/validators/index.js';
+/** One authored cut span (the resolver's lowered advisory, source-only shape). */
+export interface CutSpan {
+    startSec: number;
+    endSec: number;
+    /** The chosen angle's stable id (legible, round-trips as the clip's mediaId's
+     *  companion — used only for diagnostics here). */
+    candidateId: string;
+    /** The branded mediaItems id of the chosen angle's source. */
+    mediaId: string;
+    /** The chosen angle's SOURCE window (timebase already resolved by the resolver). */
+    sourceInSec: number;
+    sourceOutSec: number;
+}
+export interface ReplaceRegionInput {
+    /** The base composition to author onto. */
+    composition: Composition;
+    /** The video cut schedule (tiles [regionStart, regionEnd), back-to-back). */
+    cutSchedule: CutSpan[];
+    /**
+     * GROUP-SCOPED program audio (spec A1): when set, the video cuts A→B→C but the
+     * audio is PINNED to this one source for the whole region on a separate audio
+     * track (topology-i — one continuous mic over multicam). When omitted, audio
+     * FOLLOWS the video (the `kind:"cut"` literal meaning) — each cut clip carries
+     * its own audio.
+     */
+    programAudioSourceId?: string;
+    /**
+     * Source duration per mediaId (seconds) — for the audio-bed clip's window + the
+     * in-media guard on the pinned audio. The resolver supplies it.
+     */
+    durationByMediaId: Record<string, number>;
+    /** Track name for the authored video cut track. */
+    trackName?: string;
+}
+/** Author a non-rippling cut schedule (+ optional pinned audio bed) onto a fresh
+ *  video track of the composition. Returns the new composition (pure). */
+export declare function replaceRegion(input: ReplaceRegionInput): Composition;

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

@@ -0,0 +1,102 @@
+/**
+ * `replaceRegion` — the NON-RIPPLING cut/overlay lowering (selector-abstraction
+ * spec §6.2). The genuinely-new timeline primitive the switch instance needs:
+ * neither existing authoring mode fits a same-track temporal cut —
+ *   - `add_clip mode:"layer"` makes a FRESH track (b-roll over A-roll), and
+ *   - `add_clip mode:"ripple-insert"` SHIFTS downstream content.
+ * A multicam switch is an OVERWRITE: A→B→C occupy the SAME region of the SAME
+ * track, back to back, with nothing rippling.
+ *
+ * PLACEMENT: this lives in `@cueframe/composition-ops` (NOT framework-bound; it
+ * already depends on `@cueframe/composition` + `@cueframe/core`). It does NOT
+ * import the Selector core — it consumes a plain `CutSchedule` (the resolver's
+ * lowered advisory), so the source-only concepts (`programAudioSourceId`, cut vs
+ * overlay, source-window placement) live HERE, never in the core.
+ *
+ * Two kinds (spec §6.2):
+ *  - `kind:"cut"` (synced angles): video follows the chosen source; AUDIO FOLLOWS
+ *    the video UNLESS `programAudioSourceId` is set, in which case audio is pinned
+ *    to one continuous bed on a separate audio track while video cuts (topology-i).
+ *  - `kind:"overlay"` (b-roll cutaway): video-over on a NEW overlay/video track,
+ *    primary audio continues (this defers to the existing layer semantics; the
+ *    presence-gate authored its windows). The switch instance authors `cut`.
+ *
+ * Validates fail-loud: the authored segments tile the region without overlap/gap
+ * (the `Gap.strict()` lesson) and every source window is in-media; the result
+ * round-trips `Composition.parse` + `validateComposition`. Pure + deterministic.
+ */
+import { Composition as CompositionSchema, } from '@cueframe/composition/validators';
+const EPS = 1e-3;
+/** Author a non-rippling cut schedule (+ optional pinned audio bed) onto a fresh
+ *  video track of the composition. Returns the new composition (pure). */
+export function replaceRegion(input) {
+    const { cutSchedule, programAudioSourceId, durationByMediaId } = input;
+    if (cutSchedule.length === 0) {
+        throw new Error('replaceRegion: empty cut schedule');
+    }
+    // 1. Validate the schedule TILES its region (no gap, no overlap) — the
+    //    Gap.strict() lesson: an overlap/gap is a silent render artifact.
+    const sorted = [...cutSchedule].sort((a, b) => a.startSec - b.startSec);
+    for (let i = 0; i < sorted.length; i++) {
+        const s = sorted[i];
+        if (s.endSec <= s.startSec)
+            throw new Error(`replaceRegion: cut span '${s.candidateId}' has non-positive duration [${s.startSec},${s.endSec}]`);
+        const dur = durationByMediaId[s.mediaId];
+        if (dur !== undefined && (s.sourceInSec < -EPS || s.sourceOutSec > dur + EPS)) {
+            throw new Error(`replaceRegion: cut span '${s.candidateId}' source [${s.sourceInSec},${s.sourceOutSec}] out of media [0,${dur}]`);
+        }
+        if (i > 0) {
+            const prev = sorted[i - 1];
+            if (Math.abs(s.startSec - prev.endSec) > EPS) {
+                throw new Error(`replaceRegion: cut schedule is not contiguous — gap/overlap between ${prev.endSec} and ${s.startSec}`);
+            }
+        }
+    }
+    const regionStart = sorted[0].startSec;
+    const regionEnd = sorted[sorted.length - 1].endSec;
+    // 2. Build the video cut track — each span is one OVERWRITE clip, placed back-
+    //    to-back (no ripple). When audio is pinned, the video clips are muted (the
+    //    pinned bed carries the program audio); else audio follows (default volume).
+    const audioPinned = programAudioSourceId !== undefined;
+    // `mediaId` is a branded `Id<"mediaItems">` on the validator, but the resolver
+    // supplies a plain string. Cast the source at the boundary (the same pattern as
+    // authoring/timeline.ts `add_clip`), then the schema re-validates the whole shape.
+    const mediaClip = (id, startTime, duration, mediaId, trimStart, trimEnd, extra = {}) => ({
+        id,
+        startTime,
+        duration,
+        source: { kind: 'media', mediaId, trim: { start: trimStart, end: trimEnd }, ...extra },
+    });
+    const videoTrack = {
+        id: `switch-cut-${stableSuffix(sorted)}`,
+        kind: 'video',
+        name: input.trackName ?? 'Switch Cut',
+        contents: sorted.map((s, i) => mediaClip(`cut-${i}-${s.candidateId}`, s.startSec, s.endSec - s.startSec, s.mediaId, s.sourceInSec, s.sourceOutSec, audioPinned ? { muted: true } : {})),
+    };
+    const tracks = [...input.composition.tracks, videoTrack];
+    // 3. Pinned program audio bed (topology-i): ONE continuous clip on a separate
+    //    audio track spanning the whole region from the program source.
+    if (audioPinned) {
+        const dur = durationByMediaId[programAudioSourceId];
+        const audioOut = regionEnd - regionStart; // program audio starts at region start
+        if (dur !== undefined && audioOut > dur + EPS) {
+            throw new Error(`replaceRegion: program audio source '${programAudioSourceId}' (${dur}s) shorter than the region (${audioOut}s)`);
+        }
+        tracks.push({
+            id: `switch-audio-${programAudioSourceId}`,
+            kind: 'audio',
+            name: 'Program Audio',
+            contents: [
+                mediaClip(`program-audio-${programAudioSourceId}`, regionStart, regionEnd - regionStart, programAudioSourceId, 0, regionEnd - regionStart, { sync: 'independent' }),
+            ],
+        });
+    }
+    const next = { ...input.composition, tracks };
+    // 4. Round-trip through the canonical zod validator (Composition.parse) — the
+    //    Gap.strict() union + every per-field invariant fire here, fail-loud.
+    return CompositionSchema.parse(next);
+}
+/** A stable id suffix from the schedule (deterministic — no Date/random). */
+function stableSuffix(spans) {
+    return spans.map((s) => `${s.candidateId}@${s.startSec.toFixed(2)}`).join('_').slice(0, 48).replace(/[^a-zA-Z0-9_@.-]/g, '');
+}

package/dist/_members/composition-ops/testFixtures.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Test fixtures — minimal valid `TimelineClip`s per family, for the
+ * `clip.add` kind-dispatch tests. Each builds the smallest clip that
+ * `TimelineClip.strict()` accepts for its source kind.
+ *
+ * `kind` (the clip's family hint) is set ONLY where the source is ambiguous
+ * (a `media` source can land on video / audio / image): `mediaClip` takes an
+ * explicit family. Overlay-source clips need no `kind` — the family derives
+ * from `source.kind` (overlay → overlay).
+ */
+import type { TimelineClip } from '../composition/validators/index.js';
+/** A media-source clip with an EXPLICIT family `kind` (video|audio|image). */
+export declare const mediaClip: (id: string, kind?: "video" | "audio" | "image") => TimelineClip;
+/** An overlay-source clip — family derives from `source.kind` (no clip.kind). */
+export declare const overlayClip: (id: string) => TimelineClip;
+/** An audio clip: a media source carried on the `audio` family. */
+export declare const audioClip: (id: string) => TimelineClip;
+/** A minimal valid Marker (point marker on the timeline). */
+export declare const marker: (id: string, startTime?: number) => import("../composition/validators/index.js").Marker;