@cueframe/kernel 0.1.1 → 0.1.2

package/dist/_members/composition/ops/compositionOps.d.ts

@@ -1,53 +1,13 @@
-/**
- * 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 (apps/studio/src/store/compositionStore/
- * compositionOps.ts). The OSS module drops desktop-only concerns
- * (corrections, transcriptDoc) — those live on the desktop envelope.
- */
-import type { Composition, Track, TimelineClip, Marker, ReframeSegment, CaptionSegment, CaptionStyle, Format, PerClipEffect } from '../validators/index.js';
-import type { OpsSet, OpsGet, ClipPropertyUpdates } from './types.js';
+import type { CaptionSegment, CaptionStyle, Format, Marker, PerClipEffect, ReframeSegment, TimelineClip, Track } from '../validators/index.js';
+import type { ClipPropertyUpdates, OpsGet, OpsSet } from './types.js';
 import type { TimelineEntity } from '../timeline/plan.js';
-export type TrackKind = Track['kind'];
-/** Find the first track of `kind`, creating one if absent. Mutates `composition`. */
-export declare function findOrCreateTrackByKind(composition: Composition, kind: TrackKind): Track;
-/** Find a clip by id across every track. Returns undefined if not found. */
-export declare function findClipById(composition: Composition, id: string): {
-    clip: TimelineClip;
-    trackIndex: number;
-    clipIndex: number;
-} | undefined;
-/** Find the track containing the clip with given id. */
-export declare function findTrackContainingClipId(composition: Composition, id: string): {
-    track: Track;
-    trackIndex: number;
-    clipIndex: number;
-} | undefined;
-/** Find a marker by id. */
-export declare function findMarkerById(composition: Composition, id: string): {
-    marker: Marker;
-    index: number;
-} | undefined;
+import { type TrackKind } from './compositionOps.shared.js';
+export { findClipById, findMarkerById, findOrCreateTrackByKind, findTrackContainingClipId, type TrackKind, } from './compositionOps.shared.js';
 export declare function createCompositionOps(get: OpsGet, set: OpsSet): {
     addClip: (clip: TimelineClip, options?: {
         newTrack?: boolean;
         newTrackId?: string;
     }) => void;
-    /**
-     * 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: TimelineClip, target: {
         trackId: string;
     } | {
@@ -57,12 +17,9 @@ export declare function createCompositionOps(get: OpsGet, set: OpsSet): {
     }) => void;
     removeClip: (id: string) => void;
     updateClip: (id: string, updates: Partial<TimelineClip>) => void;
-    /** Remove every clip whose `source.mediaId === mediaId`. */
     removeClipsByMediaId: (mediaId: string) => void;
     selectClip: (id: string | null) => void;
-    /** Replace the whole selection. The multi-select entry point. */
     setSelection: (entities: readonly TimelineEntity[]) => void;
-    /** Every clip on the timeline, in track then start order. */
     selectAllClips: () => void;
     setClipProperties: (id: string, props: ClipPropertyUpdates) => {
         rippled: boolean;
@@ -72,10 +29,6 @@ export declare function createCompositionOps(get: OpsGet, set: OpsSet): {
     updateOverlay: (id: string, updates: Partial<TimelineClip>) => void;
     selectOverlay: (id: string) => void;
     clearOverlaySelection: () => void;
-    /**
-     * (see addOverlay's guard) Replace all overlays — clears existing overlay tracks, creates
-     * one with provided clips.
-     */
     loadOverlays: (clips: TimelineClip[]) => void;
     addAudioClip: (clip: TimelineClip) => void;
     removeAudioClip: (id: string) => void;
@@ -100,31 +53,11 @@ export declare function createCompositionOps(get: OpsGet, set: OpsSet): {
         resolution?: Format["resolution"];
         platform?: Format["platform"];
     }) => void;
-    /**
-     * Append a new track of `kind` to `composition.tracks`. If `id` is omitted
-     * a UUID-suffixed id is generated (matches `findOrCreateTrackByKind`).
-     */
     addTrack: (kind: Track["kind"], name?: string, id?: string) => void;
-    /** Remove a track and any clip selection that references its contents. */
     removeTrack: (trackId: string) => void;
-    /** Patch a track's `name` / `enabled`. */
     updateTrack: (trackId: string, updates: Partial<Pick<Track, "name" | "enabled" | "volume">>) => void;
-    /** Move a track from `fromIndex` to `toIndex` within `composition.tracks`. */
     reorderTracks: (fromIndex: number, toIndex: number) => void;
-    /**
-     * 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: string, targetTrackId: string, newStartTime?: number) => void;
-    /**
-     * 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: string) => string | undefined;
 };
 export type CompositionOps = ReturnType<typeof createCompositionOps>;

package/dist/_members/composition/ops/compositionOps.shared.d.ts

@@ -0,0 +1,30 @@
+import type { ClipSource, Composition, Marker, TimelineClip, Track } from '../validators/index.js';
+import type { TimelineEntity } from '../timeline/plan.js';
+import type { CompositionOpsState } from './types.js';
+export type TrackKind = Track['kind'];
+export declare function findOrCreateTrackByKind(composition: Composition, kind: TrackKind): Track;
+export declare function findClipById(composition: Composition, id: string): {
+    clip: TimelineClip;
+    trackIndex: number;
+    clipIndex: number;
+} | undefined;
+export declare function findTrackContainingClipId(composition: Composition, id: string): {
+    track: Track;
+    trackIndex: number;
+    clipIndex: number;
+} | undefined;
+export declare function findMarkerById(composition: Composition, id: string): {
+    marker: Marker;
+    index: number;
+} | undefined;
+export declare function trimSourceFor(source: ClipSource, clipRelStart: number, clipRelEnd: number): ClipSource;
+export declare function cutTimedRange(start: number, end: number | undefined, cutStart: number, cutEnd: number): {
+    start: number;
+    end: number | undefined;
+} | null;
+export declare function shiftTimedRange(start: number, end: number | undefined, from: number, amount: number): {
+    start: number;
+    end: number | undefined;
+} | null;
+export declare function selectionPatch(composition: Composition, entities: readonly TimelineEntity[]): Pick<CompositionOpsState, 'selection' | 'selectedClipId' | 'selectedOverlayId'>;
+export declare function pruneSelectionInDraft(draft: CompositionOpsState, removedClipIds: ReadonlySet<string>): void;

package/dist/_members/composition/ops/headlessStore.d.ts

@@ -3,38 +3,14 @@ import { type CompositionOps } from './compositionOps.js';
 import type { CompositionOpsState } from './types.js';
 export interface HeadlessStore extends CompositionOps {
     getState: () => CompositionOpsState;
-    /** Transaction grouping — a headless store has no history, so this is
-     *  just `fn()`; it exists so HeadlessStore stays structurally a
-     *  CompositionStore (the apply lane's contract). */
     batch: (fn: () => void) => void;
 }
 export declare function emptyComposition(): Composition;
-/**
- * Initial composition seeded with the source A-roll clip on a video track.
- *
- * Compose-from-suggestion hydrates a *fresh* project → an empty composition (no
- * clips). But the agent's `set_crop_intents` / `enable_captions_behind_speaker`
- * operate on the store's video clip — with no clip they're rejected ("No video
- * track") and the crop/captions-behind silently never land. The source clip is
- * a GIVEN (the suggestion window), so it belongs in the initial state, not as an
- * agent edit. Seed it here (matches the canonical serializer's `clip-0`:
- * id `clip-0`, startTime 0, duration = window length, `media` source + trim).
- *
- * Built loosely then `safeParse`d (the serializer's pattern) so the raw id
- * string brands to the wire-shape Convex Id through the schema — no hand-written
- * type cast — and the seed is runtime-validated as a bonus.
- */
 export declare function compositionWithSourceClip(spec: {
     mediaId: string;
-    /** Source-relative seconds — the clip's `trim` window. */
     startTime: number;
     endTime: number;
     format: Composition['format'];
 }): Composition;
 export declare function emptyCompositionState(): CompositionOpsState;
-/**
- * Headless wrapper used server-side (Director worker, tests). Accepts either
- * a full `CompositionOpsState` or a bare `Composition` (which is then wrapped
- * with default selection state).
- */
 export declare function createHeadlessStore(initial?: Composition | CompositionOpsState): HeadlessStore;

package/dist/_members/composition/ops/selectors.d.ts

@@ -1,80 +1,14 @@
-/**
- * Selectors for the v2 wire-shape Composition. Mirrors the desktop store's
- * selectors so headless callers (agent, Director worker, tests) get the same
- * flattened views without re-implementing track-walking everywhere.
- */
 import type { Composition, Track, TimelineClip, Marker } from '../validators/index.js';
-/** All tracks in declared order. The Timeline UI projects these 1:1 to `TimelineRow`s. */
 export declare function selectAllTracks(composition: Composition): Track[];
-/** Tracks of a given kind, declared order preserved. */
 export declare function selectTracksByKind(composition: Composition, kind: Track['kind']): Track[];
-/** Flatten all video-track clips into a single array, in track + content order. */
 export declare function selectAllClips(composition: Composition): TimelineClip[];
-/**
- * THE MEDIA CLIP ON SCREEN AT `seconds` — the clip whose bytes a still drawn at
- * that instant comes from, or `null` when nothing media-backed covers it (a
- * gap, a card-only stretch, past the end).
- *
- * ONE RULE, TWO READERS, and that is why it lives in the kernel rather than in
- * either of them. The desktop's frame capture resolves the video file to
- * extract from this clip; the verb plane routes that capture by the SAME clip's
- * media residency BEFORE calling it, so that a still is never asked for from
- * bytes the machine cannot open. Two spellings of "which clip is on screen"
- * would let the router clear a frame the renderer then draws from something
- * else.
- *
- * VIDEO TRACKS, in track + content order, and a non-media clip is SKIPPED
- * rather than ending the search: a card sitting over a video does not replace
- * the pixels underneath it.
- *
- * Half-open `[startTime, startTime + duration)` — a clip's last instant belongs
- * to whatever follows it, which is the boundary the renderer draws.
- */
 export declare function selectMediaClipAt(composition: Composition, seconds: number): TimelineClip | null;
-/** Flatten all overlay-track clips. */
 export declare function selectAllOverlays(composition: Composition): TimelineClip[];
-/** What a frame drawn at one instant is actually made of. */
 export interface FrameLayers {
-    /**
-     * `mediaId` of the media clip covering this instant, or `null` when nothing
-     * media-backed does — a gap, a card-only stretch, or a timeline with no
-     * footage in it at all.
-     */
     video: string | null;
-    /** How many overlay-track clips are active at this instant. */
     overlays: number;
 }
-/**
- * THE LAYER CENSUS AT `seconds` — what a still drawn here contains, stated in
- * words rather than left for the reader to infer from pixels.
- *
- * WHY THIS EXISTS. A preview is an agent's only evidence about a composition,
- * and pixels alone cannot distinguish "my edit did not land" from "there is no
- * footage under this timestamp". On 2026-08-14 a desktop run applied ops and
- * previewed ten times against an EMPTY library: every capture succeeded, every
- * still came back 200 OK, and the only record that the frames had no video in
- * them was a `console.warn` in the app's own log — invisible to the agent that
- * needed it. It kept editing something that was never going to be a video, then
- * gave up. The frames were not broken; the instrument simply never said what it
- * had drawn.
- *
- * This is the same correction `geometry` made for SIZE (2026-08-13, after an
- * agent measured text in a quarter-scale still and rewrote a video to avoid
- * cards): when a preview omits a fact about itself, an agent will infer a wrong
- * one. State it.
- *
- * IN THE KERNEL, because both preview lanes must answer this identically. The
- * desktop plane draws its own stills and the cloud route renders them through
- * Modal, but an agent moving between the two reads ONE shape — the property the
- * plane exists to hold. A second spelling of "what is on screen" is exactly the
- * drift that makes local and cloud disagree.
- *
- * `overlays` is a COUNT, not a judgement: a frame with no video and one overlay
- * is a legitimate card — not an error, and deliberately not refused. The agent
- * is told what is there and decides for itself.
- */
 export declare function describeFrameAt(composition: Composition, seconds: number): FrameLayers;
-/** Flatten all audio-track clips. */
 export declare function selectAllAudioClips(composition: Composition): TimelineClip[];
 export declare function selectClipById(composition: Composition, id: string): TimelineClip | undefined;
 export declare function selectMarkers(composition: Composition): Marker[];

package/dist/_members/composition/ops/timeline-word.d.ts

@@ -1,8 +1,3 @@
-/**
- * Timeline word + timed-word attrs — relocated from @cueframe/core (2026-06-10).
- * Computed (transcript projected onto the timeline), read by authoring/the editor.
- * Composition is the SSOT, so these live here, not in the renderer (core/execution).
- */
 export interface TimelineWord {
     text: string;
     timelineStart: number;

package/dist/_members/composition/ops/transcript.d.ts

@@ -1,18 +1,3 @@
-/**
- * Pure functions for merging per-clip transcripts into timeline-ordered words.
- * Lives in @cueframe/core because it operates on composition data (clips +
- * transcripts) with no dependency on stores, DOM, or runtime environment.
- *
- * v2 wire-shape: walks `TimelineClip`s straight off composition tracks. Each
- * clip references its source via `source: { kind: 'media', mediaId, trim?,
- * playbackRate?, muted? }`; cuts are baked into clip startTime/duration so
- * there is no deletion-range filtering step.
- *
- * Output is the v1-shape `TimelineWord` from `@cueframe/core/types` so the
- * agent context layer (which still reads `word.poolItemId`) keeps working.
- * The "poolItemId" field carries the wire-shape `mediaId` value — same
- * semantic, retained name for back-compat.
- */
 import type { TimelineClip } from '../validators/index.js';
 import type { TimelineWord } from './timeline-word.js';
 export interface TranscriptSegment {
@@ -24,19 +9,7 @@ export interface TranscriptSegment {
 export interface Transcript {
     segments: TranscriptSegment[];
 }
-/**
- * Merges transcripts from multiple clips into a single timeline-ordered word list.
- * Each clip's transcript segments are filtered to its source range and re-mapped
- * to timeline positions.
- *
- * Deduplication: segments with the same (mediaId, sourceStartTime) pair are emitted
- * only once, preventing duplicates when clips have overlapping source ranges.
- */
 export declare function mergeTimelineTranscripts(clips: TimelineClip[], transcripts: Record<string, Transcript>): TimelineWord[];
-/**
- * Format word timings for a given time range into a human-readable string.
- * Used by the Director's TranscriptProvider.getWordTimings() capability.
- */
 export declare function formatWordTimings(words: Array<{
     text: string;
     timelineStart: number;

package/dist/_members/composition/ops/types.d.ts

@@ -1,71 +1,20 @@
-/**
- * Composition types — v2 wire-shape.
- *
- * The OSS shared composition module mirrors the desktop store's v2
- * shape (apps/studio/src/store/compositionStore/types.ts) minus desktop-only
- * envelope concerns (corrections, transcriptDoc, isLoaded).
- *
- * Used by:
- * - @cueframe/authoring — handlers + capability shape
- * - Director worker (the Director worker) — server-side composition
- *
- * Canonical state lives on `composition: Composition` (from
- * `../validators`). All ops walk `composition.tracks`
- * and `composition.markers`.
- */
 import type { Composition, Region, ClipFit } from '../validators/index.js';
-/**
- * Per-clip property updates the editor/agent can apply via `setClipProperties`.
- * `playbackRate` triggers ripple recompute; the rest are pure visual props
- * patched in place — `opacity`/`scale`/`rotation` (the animation channel) and
- * `region`/`fit` (the output-space placement primitive: PiP / inset / banner /
- * split-screen pane).
- */
 export interface ClipPropertyUpdates {
     playbackRate?: number;
     opacity?: number;
     scale?: number;
     rotation?: number;
-    /** Output-space placement rect (fractions of the frame). Omit = full frame. */
     region?: Region;
-    /** How the source fills `region` (default 'cover'). */
     fit?: ClipFit;
 }
-/** Setter for compositionOps — accepts an immer draft mutator or a partial. */
 export type OpsSet = (fn: ((draft: CompositionOpsState) => void) | Partial<CompositionOpsState>) => void;
-/** Getter for compositionOps — returns the current state (read-only). */
 export type OpsGet = () => CompositionOpsState;
 import type { TimelineEntity } from "../timeline/plan.js";
-/** The undo-tracked data slice. */
 export interface CompositionData {
     composition: Composition;
 }
-/**
- * State shape for compositionOps — composition + selection.
- * Used by both the desktop zustand wrapper and the headless Temporal-side
- * wrapper. Selection lives here because both wrappers care about
- * "selected clip / overlay" UX and want it captured in the same patch
- * stream as content edits.
- */
 export interface CompositionOpsState extends CompositionData {
-    /**
-     * SELECTION, as a set. Any number of entities, and not only clips —
-     * keyframes and transitions are addressable the same way, which is what lets
-     * ONE selection model serve all of them instead of a field per kind.
-     *
-     * It rides the patch stream with the content edits (see the note above), so
-     * undo restores what was selected as well as what changed.
-     */
     selection: TimelineEntity[];
-    /**
-     * DERIVED MIRRORS of `selection`, maintained by `setSelection` and nothing
-     * else. They exist because ~90 call sites across 13 files read them, and a
-     * flag day across all of those is how a selection bug gets shipped. New code
-     * reads `selection`; these go away when the last reader does.
-     *
-     * `selectedClipId` is the first non-overlay clip in the selection;
-     * `selectedOverlayId` the first overlay clip.
-     */
     selectedClipId: string | null;
     selectedOverlayId: string | null;
 }

package/dist/_members/composition/primitive-catalog/catalogQuery.d.ts

@@ -1,18 +1,3 @@
-/**
- * catalogQuery — the LANE-NEUTRAL list_catalog read (executor-contract spec
- * §1: capability glue lives in the kernel; route handlers stay thin).
- *
- * Everything about filtering, recommend-ordering, and paging the component
- * catalog lives here, so the cloud route (the `/v1` routes
- * components.ts) and the desktop LocalExecutor serve IDENTICAL behavior from
- * the same code. The lanes differ only in the catalog they pass in (cloud:
- * defaults merged with the org's installed rows; desktop signed-out: defaults
- * only) and the org-scoped extras the cloud attaches (the audio palette).
- *
- * The cursor codec is IN this module (not services' api/pagination.ts, which
- * the app cannot import): clients must see the same opaque base64url wrapper
- * on both lanes, or the cursor becomes a lane-divergence an agent can trip on.
- */
 import type { ComponentCatalogEntry } from './projection.js';
 export type CatalogFilters = {
     category?: string;
@@ -26,25 +11,17 @@ export declare const CATALOG_CATEGORY_VALUES: Set<string>;
 export declare const CATALOG_KIND_VALUES: Set<string>;
 export declare const CATALOG_TIER_VALUES: Set<string>;
 export declare const CATALOG_USE_CASE_VALUES: Set<string>;
-/** A bad filter enum value — both lanes map this to their 400 invalid_query. */
 export declare class CatalogFilterError extends Error {
     readonly field: string;
     readonly value: string;
     readonly allowed: readonly string[];
     constructor(field: string, value: string, allowed: readonly string[]);
 }
-/** A cursor that decodes to no catalog entry — both lanes map to invalid_cursor. */
 export declare class CatalogCursorError extends Error {
     constructor(message?: string);
 }
-/**
- * Validate raw query values into CatalogFilters. `q` and `intent` are aliases
- * (free-text vs recommend-by-intent framing); both fold into the same match.
- */
 export declare function validateCatalogFilters(raw: Partial<Record<'category' | 'kind' | 'tier' | 'useCase' | 'mood' | 'q' | 'intent', string | undefined>>): CatalogFilters;
-/** True if ANY facet/free-text filter is set (drives recommend-first ordering). */
 export declare function hasAnyCatalogFilter(f: CatalogFilters): boolean;
-/** Apply facet + free-text filters to a catalog. */
 export declare function filterCatalog(catalog: ComponentCatalogEntry[], f: CatalogFilters): ComponentCatalogEntry[];
 declare function b64urlEncode(raw: string): string;
 export declare const encodeCatalogCursor: typeof b64urlEncode;
@@ -57,19 +34,10 @@ export interface CatalogPage {
         prevCursor: null;
     };
 }
-/**
- * The whole read: filter → recommend-order (only when filtered) → page.
- * `limit` undefined returns the WHOLE filtered catalog in one page (an agent
- * must never silently see a partial slice); `after` is the OPAQUE cursor from
- * a previous page. Throws CatalogCursorError on an unknown/undecodable cursor.
- */
 export declare function queryCatalog(catalog: ComponentCatalogEntry[], filters: CatalogFilters, opts?: {
     limit?: number;
     after?: string;
 }): CatalogPage;
-/** The curated CC0 SFX pack projected to the agent-legible browse shape
- *  (drops content-audit internals — sha256, structured source). First-page
- *  attachment on both lanes. */
 export declare function serializeSfxCatalog(): {
     soundId: string;
     family: import("../audio/index.js").SfxFamily;

package/dist/_members/composition/primitive-catalog/disabled.d.ts

@@ -1,3 +1,2 @@
 export declare const DISABLED_PRIMITIVE_IDS: ReadonlySet<string>;
-/** True when a primitive id is on the disabled denylist (not offered / not admitted). */
 export declare function isPrimitiveDisabled(id: string): boolean;

package/dist/_members/composition/primitive-catalog/index.d.ts

@@ -2,24 +2,13 @@ import { PRIMITIVE_META } from './generated/meta.js';
 import type { PrimitiveCatalogMeta, PrimitiveCategory } from './types.js';
 export type { PrimitiveCatalogMeta, PrimitiveCategory, PrimitiveKind, PrimitiveExample, } from './types.js';
 export { PRIMITIVE_META };
-/** List primitives filtered by category. Used by `list_effect_styles` + discovery. */
 export declare function listPrimitivesByCategory(category: PrimitiveCategory): PrimitiveCatalogMeta[];
-/**
- * The primitive's declared text-param name.
- * - string  → the field accepting a single text payload (e.g. 'text').
- * - null    → the primitive explicitly declines text (e.g. karaoke).
- * - undefined → unknown id, or no declared text contract.
- */
 export declare function getPrimitiveTextParam(id: string): string | null | undefined;
-/** Secondary text-param name. Same string/null/undefined semantics. */
 export declare function getPrimitiveSubtextParam(id: string): string | null | undefined;
-/** Lookup a primitive's catalog metadata by id. */
 export declare function getPrimitiveCatalogMeta(id: string): PrimitiveCatalogMeta | undefined;
-/** All registered primitive ids. */
 export declare function listPrimitiveIds(): string[];
 export { projectToComponentCatalog, projectToRegistryOverlays, derivePlacement, } from './projection.js';
 export type { ComponentCatalogEntry, ComponentPlacement, SceneFormat, RegistryOverlayEntry, RegistryOverlayCategory, } from './projection.js';
-/** JSON Schema for a primitive's props, or undefined if unknown. */
 export declare function getPrimitivePropSchema(id: string): import("./types.js").JsonSchemaObject | undefined;
 export { validatePrimitiveParams, validateParamsAgainstSchema, } from './paramValidation.js';
 export type { ParamSchemaValidationResult, PrimitiveParamValidationResult, ParamTypeMismatch, } from './paramValidation.js';

package/dist/_members/composition/primitive-catalog/paramValidation.d.ts

@@ -1,76 +1,26 @@
 import type { JsonSchemaObject } from './types.js';
 export interface ParamTypeMismatch {
-    /** The provided param key whose value type disagrees with the schema. */
     key: string;
-    /** Declared JSON-Schema type (or `a|b` for a union of primitive types). */
     expected: string;
-    /** Observed runtime JSON type of the provided value. */
     actual: string;
 }
-/** A provided value that is the right TYPE but violates a value constraint
- *  (string length, numeric bound, or enum membership) declared in the baked
- *  propSchema — the class the renderer's full-Zod inflate would otherwise throw
- *  on (e.g. a lower-third `subtitle` longer than its 60-char max). */
 export interface ParamConstraintViolation {
-    /** The provided param key whose value breaks a declared constraint. */
     key: string;
-    /** Which constraint was broken. */
     constraint: 'maxLength' | 'minLength' | 'minimum' | 'maximum' | 'exclusiveMinimum' | 'exclusiveMaximum' | 'minItems' | 'maxItems' | 'enum';
-    /** The declared bound: the numeric limit, or the allowed enum set. */
     limit: number | Array<string | number | boolean>;
-    /** The observed magnitude: string length / numeric value / the invalid enum value. */
     actual: number | string | boolean;
 }
 export interface ParamSchemaValidationResult {
-    /**
-     * `propSchema` was absent or not a usable `{ type:'object', properties }`
-     * schema. Callers MUST fail loud on this (registry drift) — never silently
-     * pass. Distinct from "unknown primitive" (see `validatePrimitiveParams`).
-     */
     missingPropSchema: boolean;
-    /** Provided param keys that are NOT declared properties (typo'd/unsupported). */
     unknownKeys: string[];
-    /** The full declared property-name set (sorted) — the valid/expressible keys. */
     allowedKeys: string[];
-    /** Provided keys whose value's JSON type disagrees with the declared type. */
     typeMismatches: ParamTypeMismatch[];
-    /** Provided keys whose (correctly-typed) value violates a declared value
-     *  constraint (maxLength/minLength/minimum/maximum/enum). */
     constraintViolations: ParamConstraintViolation[];
 }
 export interface PrimitiveParamValidationResult extends ParamSchemaValidationResult {
-    /**
-     * `false` when `primitiveId` is not in the registry catalog at all — the
-     * membership guard (`validatePrimitiveMembership`) owns reporting those, so
-     * the param-shape caller skips them rather than double-flagging.
-     */
     known: boolean;
 }
-/**
- * Validate a params object against an EXPLICIT JSON-Schema `propSchema`. The
- * low-level core: pure, no registry lookup, so the "missing propSchema → fail
- * loud" branch is directly unit-testable (pass `undefined`).
- *
- * - CLOSED-KEY: every provided key must be a declared property; otherwise it
- *   lands in `unknownKeys` (with `allowedKeys` = the valid set). Suppressed when
- *   `opts.freeform` (the per-primitive opt-out) is set — typed checks still run.
- * - TYPED: each provided KNOWN key is checked against its declared primitive
- *   `type` (string, or an array-of-strings union). Properties with no concrete
- *   primitive `type` (anyOf/enum-only/$ref) skip the typed check — closed-key
- *   still applies, deep shape is the renderer's full-Zod job.
- */
 export declare function validateParamsAgainstSchema(params: unknown, propSchema: JsonSchemaObject | undefined, opts?: {
     freeform?: boolean;
 }): ParamSchemaValidationResult;
-/**
- * Resolve a registry primitive's baked `propSchema` and validate `params`
- * against it (closed-key + typed). The SSOT-resolving wrapper over
- * `validateParamsAgainstSchema`.
- *
- * - `known:false` when `primitiveId` is absent from the catalog — the
- *   membership guard owns reporting unknown ids; the param-shape caller skips.
- * - `missingPropSchema:true` when a KNOWN primitive carries no usable
- *   propSchema (registry drift) — the caller fails loud.
- * - Honours the per-primitive `freeformParams` opt-out (no config sets it today).
- */
 export declare function validatePrimitiveParams(primitiveId: string, params: unknown): PrimitiveParamValidationResult;

package/dist/_members/composition/primitive-catalog/projection.d.ts

@@ -1,11 +1,4 @@
 import type { PrimitiveCatalogMeta, PrimitiveCategory, PrimitiveKind, PrimitiveExample, JsonSchemaObject, PrimitiveTier, PrimitiveUseCase } from './types.js';
-/**
- * A param that follows the project brand kit: `param` accepts the `brandToken`
- * value (a `$brand:<path>` ref) to track the brand instead of a literal. Derived
- * from a primitive's declared `tokens` (only the entries that carry a
- * `brandKitPath`). Surfaced so an agent can both DISCOVER which params are
- * brand-bindable and EXPRESS the binding without reading source.
- */
 export type ComponentBrandBinding = {
     param: string;
     brandToken: string;
@@ -15,35 +8,10 @@ export type SceneFormat = {
     fps?: 24 | 30 | 60;
     resolution?: 'hd' | 'fhd' | '4k';
 };
-/**
- * How to PLACE a catalog entry on the timeline as a ClipSource.
- *
- * Resolves the `kind:'component'` name collision: a catalog entry's `kind`
- * (component|transition|scene) is its RENDER kind, NOT its ClipSource variant.
- * The ClipSource union ALSO has a `kind:'component'` — but that is reserved for
- * org-INSTALLED custom components keyed by `componentId`. A built-in primitive
- * referenced by `componentId` will NOT resolve. This hint names the exact
- * ClipSource `kind` + the id field to key it by:
- *   - built-in text/ui-block/background/layout/SCENE (source:'default')
- *     → { clipSourceKind:'overlay', refField:'primitiveId' } (OverlayClipSource)
- *   - built-in effect/transition (source:'default')
- *     → { clipSourceKind:'effect',  refField:'primitiveId' } (EffectClipSource)
- *   - org-INSTALLED custom component (source:'installed')
- *     → { clipSourceKind:'component', refField:'componentId' } (ComponentClipSource)
- *
- * It also resolves the "scenes are invisible as clips" gap: a `kind:'scene'`
- * primitive has NO `scene` ClipSource — it is placed as `{kind:'overlay',
- * primitiveId}`, which this hint states explicitly.
- */
 export type ComponentPlacement = {
     clipSourceKind: 'overlay' | 'effect' | 'component';
     refField: 'primitiveId' | 'componentId';
 };
-/**
- * Derive the timeline-placement hint for a catalog entry from its provenance +
- * category. Fail-loud: an unmapped category means a new `PrimitiveCategory`
- * landed without a placement rule — a silent default would mis-author the clip.
- */
 export declare function derivePlacement(args: {
     source: 'default' | 'installed';
     category: PrimitiveCategory;
@@ -71,15 +39,8 @@ export type ComponentCatalogEntry = {
     tier?: PrimitiveTier;
     useCase?: PrimitiveUseCase[];
     examples?: PrimitiveExample[];
-    /** On-screen strings the primitive BAKES (no param changes them). Counterpart to propSchema. */
     fixedCopy?: string[];
-    /**
-     * Params that can follow the project brand kit: each `{param, brandToken}`
-     * says "set `param` to `brandToken` (a `$brand:` ref) to track the brand".
-     * Derived from the primitive's `tokens`; omitted when nothing is brand-bound.
-     */
     brandBindings?: ComponentBrandBinding[];
-    /** How to author this entry as a ClipSource on the timeline (resolves the kind:component collision). */
     placement: ComponentPlacement;
 };
 export declare function projectToComponentCatalog(metas: PrimitiveCatalogMeta[]): ComponentCatalogEntry[];