@cueframe/kernel 0.1.0 → 0.1.2

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

@@ -1,79 +1,11 @@
-/**
- * @cueframe/composition-ops — the composition OPERATION model (single home).
- *
- * One package owns "what an op is": the serializable `CompositionOp` discriminated
- * union, `applyOp(composition, op)` (pure — applies an op to a wire Composition),
- * and `invertOp` (the inverse, for the op-log / multiplayer undo).
- *
- * Layering (deliberate, not fragmentation):
- *  - This package = the op vocabulary + pure apply/inverse. OSS; the agent and the
- *    editor both emit + optimistically-apply ops through it.
- *  - apply logic is REUSED from `@cueframe/core` (the headless store), not forked.
- *  - The server-authoritative persistence (transactional scoped row writes + the
- *    op-log) is ONE generic Convex mutation in `the server's op applier`
- *    — a thin consumer of this package. Convex functions must live in the Convex app;
- *    that is the only piece outside this package, and it does not grow per-op.
- */
 import { z } from 'zod';
 import { Composition } from '../composition/validators/index.js';
 import type { TimelineClip as TimelineClipT, Track as TrackT } from '../composition/validators/index.js';
 import { type HeadlessStore } from '../composition/ops/index.js';
-/** A clip's track FAMILY (mirrors `Track.kind`). */
 export type ClipKind = TrackT['kind'];
-/** The three families a MEDIA item can belong to. */
 export type MediaFamily = Extract<ClipKind, 'video' | 'audio' | 'image'>;
-/**
- * The timeline family of a media item, derived from its `mimeType`.
- *
- * `mimeType` is the ONLY trustworthy statement of what a media item is: it is
- * `v.string()` (required) on the schema and byte-detected at ingest — populated
- * on 305/305 prod rows. `mediaItems.kind` is a duplicate of the same fact that
- * nobody maintains (null on every video uploaded in 2026-08) and that is
- * overloaded with provenance values (`source`, `stock`, `gif`, `asset`) which
- * are not families at all. Measured 2026-08-17: where `kind` was set it agreed
- * with the mimeType prefix in 232/232 rows. So there is one fact here, and this
- * is where it is read.
- *
- * THROWS on anything it cannot name. A media item whose type we can't determine
- * must not be silently treated as video — that is precisely how an image reached
- * the video frame-extractor and hung the render for 30s on `delayRender`.
- */
 export declare function mediaFamily(mimeType: string): MediaFamily;
-/**
- * Resolve a clip's track family — the single determinate rule:
- *   `clip.kind  ??  deriveFromSource(source.kind)  ??  track?.kind  ??  throw`.
- *
- * The `track?.kind` step is a PLACEMENT reading, not a family oracle: "this clip
- * is going on that track, so treat it as that family." It is correct here
- * because this function is PURE — it has no database, and a media clip's real
- * family lives on the media item (`mediaFamily(mimeType)`), which only a
- * DB-aware caller can read. The editor's recording store legitimately adds media
- * clips with no `kind` and a target track.
- *
- * What must NOT happen is a *server* guard treating this placement reading as
- * an assertion and then rejecting the caller for it — that was the old
- * `image_media_on_video_track`. The server stamps the true family from
- * `mediaFamily(mediaItem.mimeType)` at the Convex ingress before folding ops, so
- * by the time this runs server-side, `clip.kind` is already authoritative and
- * the track step is never reached.
- *
- * FAILS LOUD for a media source with neither `clip.kind` nor a track — there is
- * no safe default (no-fallbacks rule). Pure: no state, no side effects.
- */
 export declare function resolveClipKind(clip: Pick<TimelineClipT, 'kind' | 'source'>, track?: Pick<TrackT, 'kind'>): ClipKind;
-/**
- * The serializable composition operation. One discriminated union; every writer
- * (agent, editor) emits these; the server validates with this schema at the
- * boundary. Local-only ops (selectClip/selectOverlay/clearOverlaySelection) are
- * deliberately ABSENT — selection is UI state, never persisted.
- *
- * Cross-field/ripple ops (`cutAndRipple`, `ripple`, `add/removeExcludedRange`)
- * are server-AUTHORITATIVE: the server mutation recomputes downstream timeline
- * state within one transaction (they do not free-merge). They are still
- * expressed here so all writers share one vocabulary. (A `playbackRate` change
- * is also cross-field — it lives at `source.playbackRate` and ripples downstream
- * clips — which is exactly why it is NOT a `clip.update` patch field.)
- */
 export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     type: z.ZodLiteral<"clip.add">;
     clip: z.ZodObject<{
@@ -444,7 +376,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -512,7 +444,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -797,7 +729,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -938,7 +870,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -1085,7 +1017,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -1232,7 +1164,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -1709,7 +1641,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -1777,7 +1709,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -2063,7 +1995,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -2204,7 +2136,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -2349,7 +2281,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -2494,7 +2426,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -2966,7 +2898,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -3034,7 +2966,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -3319,7 +3251,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -3460,7 +3392,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -3604,7 +3536,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -3748,7 +3680,7 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
                     } | undefined;
                 }[];
             } | undefined;
-            kenBurns?: "in" | "out" | "pan-l" | "pan-r" | "none" | undefined;
+            kenBurns?: "none" | "in" | "out" | "pan-l" | "pan-r" | undefined;
             excludedRanges?: {
                 start: number;
                 end: number;
@@ -4386,6 +4318,15 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
         annotationColor?: string | undefined;
         maxWidthPercent?: number | undefined;
     };
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"setCaptionDepth">;
+    zPlane: z.ZodEnum<["front", "behind-subject"]>;
+}, "strict", z.ZodTypeAny, {
+    type: "setCaptionDepth";
+    zPlane: "front" | "behind-subject";
+}, {
+    type: "setCaptionDepth";
+    zPlane: "front" | "behind-subject";
 }>, z.ZodObject<{
     type: z.ZodLiteral<"setCaptions">;
     segments: z.ZodArray<z.ZodObject<{
@@ -4868,70 +4809,8 @@ export declare const CompositionOp: z.ZodDiscriminatedUnion<"type", [z.ZodObject
     rangeIdx: number;
 }>]>;
 export type CompositionOp = z.infer<typeof CompositionOp>;
-/**
- * Apply an op to a wire Composition, returning the new Composition (pure).
- * Reuses `@cueframe/core`'s tested op logic via a headless store — no fork.
- */
 export declare function applyOp(composition: Composition, op: CompositionOp): Composition;
-/**
- * Dispatch ONE op onto a LIVE store — the op→method switch, extracted from
- * `applyOp` so there is exactly one of it.
- *
- * `applyOp` is pure: it mints a throwaway headless store, folds, and hands back
- * a new Composition. That serves every caller that OWNS the composition value
- * (the Convex mutation, the local-harness store, the ensemble author). It does
- * NOT serve a caller whose composition lives inside somebody else's store —
- * desktop's zustand `CompositionState`, which has no whole-composition setter
- * and whose op-recorder/undo trail only sees writes that go through its
- * methods. Handing that caller a fresh Composition value would be a dead end;
- * the only way in is the methods, which is precisely what this switch calls.
- *
- * So: `HeadlessStore` here is a STRUCTURAL contract (`CompositionOps` + a
- * `getState`), not a concrete class — `@cueframe/authoring`'s `CompositionStore`
- * and the desktop store satisfy it, and `LocalExecutor` (apps/studio/src/llm) folds
- * a validated batch through it op-by-op. Writing a second switch for that lane
- * is what "one vocabulary" exists to prevent: it would drift silently the first
- * time an op is added here and forgotten there.
- *
- * NOT transactional on its own — it applies ONE op and a throw leaves the store
- * wherever it got to. A caller wanting the server's all-or-nothing contract
- * validates the whole batch on a scratch fold (`ops.reduce(applyOp, current)`)
- * FIRST, and only then commits through this.
- */
 export declare function applyOpToStore(store: HeadlessStore, op: CompositionOp): void;
-/**
- * The inverse op (for the op-log → selective multiplayer undo / diff / audit).
- *
- * `invertOp(before, op)` returns the op that, applied to `applyOp(before, op)`,
- * restores `before`. It needs the PRE-image to capture the value the forward op
- * overwrote (the patched fields, the replaced reframe segments, the removed
- * clip, …).
- *
- * Coverage (value-restoring): clip.add↔clip.remove, clip.update (prior fields),
- * markers (add/remove/update), setCropIntents (prior segments), setEffects (prior
- * effect stack), setFormat (prior values), addTrack↔removeTrack, updateTrack
- * (prior name/enabled), reorderTracks (reversed), moveClipToTrack (move back),
- * duplicateClip (clip.remove of the PINNED newClipId).
- *
- * DEFERRED — these THROW (fail loud; a wrong inverse silently corrupts undo, so
- * we never fake one):
- *  - cutAndRipple / ripple / addExcludedRange / removeExcludedRange — server-
- *    authoritative cross-field timeline recomputes (clips split/merge, durations
- *    and downstream startTimes recompute, markers + caption words ripple). No
- *    clean single-op inverse; restoring them is a snapshot-restore concern.
- *  - removeTrack — removes a track AND its clips at a position; there is no
- *    op to re-insert a populated track at an index (addTrack appends an EMPTY
- *    track), so the pre-image can't be restored as one op.
- *  - removeClipsByMediaId / loadOverlays — whole-channel replace/clear (multiple
- *    clips across tracks, with positions and scene-marker side effects); no
- *    single restoring op.
- *  - setCaptionStyle — MERGES (and creates the captions container when absent)
- *    with no clear/drop op, so a forward call that adds a style key (or the
- *    container) can't be exactly reverted.
- *  - duplicateClip WITHOUT `newClipId` — the copy's id is store-minted
- *    (non-deterministic), so there is no clip id to remove. Pin `newClipId` for a
- *    deterministic inverse.
- */
 export declare function invertOp(before: Composition, op: CompositionOp): CompositionOp;
 export { createRecordingStore, type RecordingStore } from './recordingStore.js';
 export { wrapWithOpRecorder, type RecordableOps, type OpRecorderOpts } from './opRecorder.js';

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

@@ -1,54 +1,26 @@
 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;

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

@@ -1,24 +1,5 @@
-/**
- * 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 (apps/studio/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;
@@ -55,23 +36,8 @@ export interface RecordableOps {
     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/recordingStore.d.ts

@@ -1,23 +1,7 @@
-/**
- * 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/replaceRegion.d.ts

@@ -1,65 +1,17 @@
-/**
- * `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/testFixtures.d.ts

@@ -1,19 +1,5 @@
-/**
- * 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;

package/dist/_members/convex-api/api.d.ts

@@ -1,5 +1,2 @@
 import type { api as GeneratedApi } from "./api.generated.js";
-/** The client-facing function-reference proxy. Runtime-identical to the
- *  backend's generated `api` (which IS `anyApi`); typed by the vendored
- *  declarations with the internal.* surface stripped. */
 export declare const api: typeof GeneratedApi;

package/dist/_members/convex-api/dataModel.d.ts

@@ -1,6 +1,4 @@
 import type { GenericId } from "convex/values";
 import type { SystemTableNames } from "convex/server";
-/** Table NAMES only — the vendored surface deliberately omits document
- *  shapes (Doc/DataModel). Public consumers use exclusively `Id<...>`. */
 export type TableNames = "agentMessages" | "agentThreads" | "apiAuditLog" | "billingPlanState" | "brandKits" | "briefs" | "checkpoints" | "clips" | "clipSuggestionRuns" | "componentVersions" | "composeJobs" | "compositionEvents" | "compositionRuns" | "compositions" | "compositionVersions" | "contextFiles" | "conversations" | "corrections" | "critics" | "dashboardInsights" | "directorProfiles" | "directorWorkflows" | "enrichmentCandidates" | "exports" | "idempotencyKeys" | "installedComponents" | "jobs" | "markers" | "mediaItems" | "mediaUnderstanding" | "overlays" | "pricingPolicy" | "processingEvents" | "projects" | "providerStates" | "renderJobs" | "resourceQueryCache" | "resourceRateBuckets" | "restorePoints" | "runs" | "searchQueries" | "sessions" | "sessionTokens" | "settings" | "socialAccounts" | "socialInsights" | "socialMediaItems" | "templateEmbeddings" | "templates" | "timelineClips" | "tracks" | "transcripts" | "uploadTokens" | "usageEvents" | "userSettings" | "videoChunkEmbeddings" | "webhookDeliveries" | "webhookProjectUpdateDebounce" | "webhooks" | "x402Payments";
 export type Id<TableName extends TableNames | SystemTableNames> = GenericId<TableName>;

package/dist/_members/core/index.d.ts

@@ -1,3 +1,3 @@
 export * from './types.js';
-export { buildEmphasisSet, isEmphasized, extractCaptionWordsFromDoc, DEFAULT_FPS, DEFAULT_WIDTH, DEFAULT_HEIGHT, DEFAULT_RENDER_SETTINGS, FORMAT_PRESETS, RESOLUTION_PRESETS, bppToCrf, computeExportDimensions, ensureEven, } from './render/index.js';
+export { buildEmphasisSet, isEmphasized, extractCaptionWordsFromDoc, DEFAULT_FPS, DEFAULT_WIDTH, DEFAULT_HEIGHT, DEFAULT_RENDER_SETTINGS, FORMAT_PRESETS, RESOLUTION_PRESETS, bppToCrf, ensureEven, } from './render/index.js';
 export type { RenderInput, CompositionClip, CompositionOverlay, CompositionAudioTrack, CaptionWord, CaptionStyle, EmphasisWord, DocNode, ExportFormat, ExportQuality, ExportResolution, FormatPreset, RenderSettings, } from './render/index.js';

package/dist/_members/core/render/bookends.d.ts

@@ -1,60 +1,16 @@
-/**
- * Brand intro/outro BOOKEND timeline math — pure, fps-driven, never throws.
- *
- * Phase 2 of the brand-consistent demo pipeline: when the resolved brand kit
- * carries an `intro`/`outro` bumper, the render prepends the intro and appends
- * the outro to the body composition. This module owns the ONE timeline
- * calculation both sides of the render share:
- *
- *   - `compositionToRenderInput` (this package) reads it FORWARD — body duration
- *     in, extended total out — to size the Remotion composition's
- *     `durationInFrames`.
- *   - `MainComposition` (cueframe renderer) reads `bookendFrames` to place the
- *     intro at frame 0, shift the body forward by the intro, and append the
- *     outro — so the math can't diverge between "how long is the video" and
- *     "where does each piece sit."
- *
- * SOFT by construction (mirrors the brand cascade's "never crash the render"
- * rule): a missing/odd bumper, a video bumper with no source, or a non-positive
- * fps yields 0 reserved frames — no bookend, never a throw, never negative.
- * Fail-loud belongs at BrandKit PUT-time validation, not render-time placement.
- */
 import type { ResolvedBrandKit } from "../../composition/projection/index.js";
-/** Card bumper default length when the kit didn't set one (mirrors the resolver). */
 export declare const CARD_BOOKEND_DEFAULT_MS = 1500;
-/**
- * Video bumper fallback length when the kit set no `durationMs`. The resolver
- * forces no default for `kind:'video'` ("clip length governs"), but the pure
- * timeline math can't probe the clip's intrinsic length, so the renderer
- * reserves this deterministic window. A kit that sets `durationMs` overrides it.
- */
 export declare const VIDEO_BOOKEND_DEFAULT_MS = 3000;
 type Bumper = NonNullable<ResolvedBrandKit["intro"]>;
-/**
- * Frames a single intro/outro bumper reserves on the timeline, or 0 when it is
- * absent/odd (soft). `card` always reserves (defaults to 1.5s); `video` reserves
- * only with a usable `src` (else there is nothing to play).
- */
 export declare function bookendFrames(bumper: ResolvedBrandKit["intro"] | undefined, fps: number): number;
 export interface BookendTimeline {
-    /** Frames the intro reserves at the head (0 = no intro). */
     introFrames: number;
-    /** Frames the outro reserves at the tail (0 = no outro). */
     outroFrames: number;
-    /** First body frame on the extended timeline (= introFrames). */
     bodyStartFrames: number;
-    /** Body length in frames — unchanged from the un-bookended timeline. */
     bodyFrames: number;
-    /** First outro frame (= introFrames + bodyFrames). */
     outroStartFrames: number;
-    /** Extended composition total: intro + body + outro. */
     totalFrames: number;
 }
-/**
- * Forward timeline math: given the resolved kit's bumpers and the body's frame
- * length, place the bookends and compute the extended total. fps-driven; a
- * non-positive body folds to 0 (the total is then just the bookends).
- */
 export declare function resolveBookendTimeline(brandKit: {
     intro?: ResolvedBrandKit["intro"];
     outro?: ResolvedBrandKit["outro"];