@cueframe/kernel 0.1.1 → 0.1.3

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;