@cueframe/kernel 0.1.1 → 0.1.2

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

@@ -1,26 +1,12 @@
 export type PrimitiveCategory = 'text' | 'effects' | 'transitions' | 'layouts' | 'backgrounds' | 'ui-blocks' | 'scenes';
 export type PrimitiveKind = 'component' | 'transition' | 'scene';
-/** Curation tier — mirrors the public ComponentResponse contract. */
 export type PrimitiveTier = 'recommended' | 'standard' | 'niche';
-/** Editorial use-case tags — mirrors the public ComponentResponse contract. */
 export type PrimitiveUseCase = 'intro' | 'outro' | 'full-scene' | 'title-over-footage' | 'transition' | 'background' | 'grade' | 'emphasis' | 'explainer' | 'social-cut';
-/** A JSON-Schema (draft-07 subset) object describing a primitive's props. */
 export type JsonSchemaObject = Record<string, unknown>;
-/**
- * A theme-token binding declared by a primitive (the React-free mirror of the
- * execution-side `TokenBinding`). `brandKitPath` (when set) is the
- * `ResolvedBrandKit` dot-path the param tracks — i.e. the param accepts a
- * `$brand:<brandKitPath>` value to follow the project brand kit. The catalog
- * projection turns these into the public `brandBindings` hint.
- */
 export interface PrimitiveTokenBinding {
-    /** The param field this token themes (e.g. 'accent'). */
     propPath: string;
-    /** CSS custom property the render binds (e.g. '--cf-accent'). */
     cssVar: string;
-    /** Value used when neither a brand kit nor an explicit param is supplied. */
     fallback?: string;
-    /** ResolvedBrandKit dot-path the param brand-binds to (e.g. 'colors.accent'). */
     brandKitPath?: string;
 }
 export interface PrimitiveExample {
@@ -30,94 +16,30 @@ export interface PrimitiveExample {
     description?: string;
 }
 export interface PrimitiveCatalogMeta {
-    /** Stable kebab-case id, globally unique in the registry. */
     id: string;
     name: string;
     category: PrimitiveCategory;
     kind: PrimitiveKind;
     version: string;
-    /**
-     * SELECTION CONTRACT (mirrored to the public ComponentResponse facets):
-     * a verb naming what this primitive accomplishes (e.g. 'reveal-text',
-     * 'product-trailer'). Match it against the beat you are authoring.
-     */
     intent?: string;
     description?: string;
-    /**
-     * When to reach for this primitive AND when not to. The negative guidance
-     * is load-bearing — it stops a wrong pick before a render proves it wrong.
-     */
     useWhen?: string;
-    /** Other primitive ids that COMPOSE well after/around this one (authoring guidance). */
     pairsWith?: string[];
-    /** Other primitive ids that CONFLICT with this one — do not place together. */
     avoidWith?: string[];
     tags?: string[];
-    /** Mood/vibe tags — filter to match the edit's tone (e.g. 'cinematic', 'minimal'). */
     mood?: string[];
-    /**
-     * Curation tier — a QUALITY/applicability RANKING, not a flag. Prefer
-     * `recommended` (battle-tested, broadly applicable); reach for `niche` only
-     * when its specific use-case is exactly the beat. Set on a config when curated.
-     */
     tier?: PrimitiveTier;
-    /**
-     * Editorial use-case tags — the edit ROLE(s) this primitive fills (the
-     * dimension to filter by for a beat: 'intro' / 'title-over-footage' /
-     * 'full-scene' / 'grade' / …). Set on a config when curated.
-     */
     useCase?: PrimitiveUseCase[];
-    /**
-     * On-screen strings this primitive BAKES — the read-side counterpart to
-     * `propSchema`. These literals render regardless of params; no param can
-     * change them (fork the source via get_component_source to edit them). The
-     * machine signal that "not in propSchema = baked" copy actually exists, so
-     * an agent sees someone-else's marketing copy at author time, not at render.
-     */
     fixedCopy?: string[];
-    /**
-     * Param field accepting the primitive's primary text payload.
-     * `null` = primitive explicitly declines a single text slot (e.g. karaoke).
-     * `undefined` = no declared text contract.
-     *
-     * ABI NOTE — this is a TWO-STRING contract (textParam + subtextParam) for the
-     * canonical title/subtitle slots only. MULTI-ELEMENT / STRUCTURED scene copy
-     * (tiers, feature lines, code lines, beats) is NOT expressed here — it is
-     * expressed via the primitive's OWN `propSchema` params (e.g. changelog-bite's
-     * `oldLines`/`newLines: string[]`). When you need rich copy, read the
-     * `propSchema` for an array/object param; don't expect it on this 2-string ABI.
-     */
     textParam?: string | null;
-    /** Same contract for a secondary text payload (subtitle/byline). See textParam's ABI note. */
     subtextParam?: string | null;
-    /**
-     * Theme-token bindings declared by this primitive (mirrored from its config's
-     * `tokens`). The catalog projection derives the public `brandBindings` hint
-     * from the entries whose `brandKitPath` is set.
-     */
     tokens?: PrimitiveTokenBinding[];
-    /** Materialized literal defaults (literal-extractable subset). */
     propDefaults?: Record<string, unknown>;
-    /** Few-shot examples (literal-extractable subset). */
     examples?: PrimitiveExample[];
-    /** JSON Schema (draft-07) for this primitive's params, generated from its Zod paramsSchema. */
     propSchema?: JsonSchemaObject;
-    /**
-     * Explicit per-primitive opt-out from the write-boundary CLOSED-KEY param
-     * check (see paramValidation.ts). Set on a config ONLY when the primitive
-     * legitimately accepts free-form / caller-defined keys beyond its declared
-     * `propSchema.properties`. NOT a blanket bypass — typed checks on declared
-     * keys still run. No first-party config sets this today (every primitive
-     * declares a closed prop set); the hook exists so a future free-form
-     * primitive opts out declaratively instead of weakening the guard globally.
-     */
     freeformParams?: boolean;
-    /** Scene/primitive intrinsic runtime in frames (scenes set this; overlays omit). */
     durationInFrames?: number;
-    /** Intrinsic fps (scenes). */
     fps?: number;
-    /** Canonical authoring width in px (scenes). */
     width?: number;
-    /** Canonical authoring height in px (scenes). */
     height?: number;
 }

package/dist/_members/composition/projection/behind-placement.d.ts

@@ -1,34 +1,8 @@
-/**
- * Launch-grade behind-text placement (spec §6). Derives a SCENE-space anchor from
- * the matte geometry sidecar: lateral center of the clip-union silhouette; vertical
- * in the shoulder band (head-top + a fraction) so the bite is rounded and partial,
- * never the flat torso wall; minTextWidth guarantees the line reads past the
- * silhouette on both sides. Pure; all values source-normalized [0,1].
- *
- * The sidecar is the person-matte bake's `.geometry.json` artifact (one record
- * per frame: subject bbox + 16-bucket column/row coverage marginals, computed
- * from the smoothed alpha — see person_matting.py `_frame_geometry`). The
- * orchestration activity downloads + camelCases it into `MatteGeometryLike`;
- * this module never does I/O.
- */
-/** Minimum fraction of bake-window frames with a detected subject before the
- *  behind treatment is even considered (relocated `captionsBehindEligible`
- *  principle — composition-floor's MIN_ACTIVE_SPEAKER_PRESENCE sibling). Below
- *  this the clip reads as b-roll / no-speaker → no anchor, degrade to front. */
 export declare const MIN_PRESENCE_FOR_BEHIND = 0.6;
-/** Shoulder-band shape. `headLambda` drops the anchor a frame-height fraction
- *  below the union head-top so the silhouette bites the line from below-the-chin
- *  (rounded head + shoulders), not the flat torso wall. `widthPad` widens the
- *  minimum text width past the union silhouette so the line reads on BOTH sides
- *  of the body. Calibration constants — Phase-7 fixtures tune them. */
 export declare const BEHIND_BAND: {
     readonly headLambda: 0.18;
     readonly widthPad: 1.25;
 };
-/** One frame of the matte geometry sidecar. `bbox` is [x0, y0, x1, y1]
- *  source-normalized, x1/y1 exclusive; null when no subject that frame.
- *  `cols`/`rows` are 16-bucket coverage marginals: cols[i] = fraction of that
- *  column band covered by the subject (and rows[j] likewise per row band). */
 export interface MatteGeometryFrame {
     f: number;
     present: boolean;
@@ -36,29 +10,15 @@ export interface MatteGeometryFrame {
     cols: number[];
     rows: number[];
 }
-/** The sidecar's geometry payload, camelCased by the consuming activity. */
 export interface MatteGeometryLike {
     srcW: number;
     srcH: number;
     presenceFraction: number;
     frames: MatteGeometryFrame[];
 }
-/** A derived behind-text anchor, source-normalized. `x`/`y` center the line;
- *  `minTextWidth` is the floor on the rendered line's width so it clears the
- *  silhouette laterally (already clamped ≤ 0.95). */
 export interface BehindAnchor {
     x: number;
     y: number;
     minTextWidth: number;
 }
-/**
- * Derive the behind-text anchor from a clip's matte geometry. Returns null when
- * the clip has no stable subject to be behind (presence below the floor, or no
- * frame ever produced a bbox) — the caller degrades the overlay to front.
- *
- * Placement: lateral center of the UNION bbox across all present frames (stable
- * against per-frame jitter); vertical at union head-top + the shoulder-band
- * lambda, capped at MAX_ANCHOR_Y; minTextWidth = union silhouette width padded
- * by `widthPad` so the line extends past the body on both sides.
- */
 export declare function deriveBehindAnchor(g: MatteGeometryLike): BehindAnchor | null;

package/dist/_members/composition/projection/behind-readiness.d.ts

@@ -1,47 +1,15 @@
-/**
- * CAN THIS OVERLAY ACTUALLY GO BEHIND THE SUBJECT — answered in the editor,
- * before a render is paid for.
- *
- * The render already decides this, in the director's `resolveBehindPlacement`:
- * a behind-subject overlay whose clip has no matte, no geometry sidecar, or too
- * little subject presence is DEGRADED — `zPlane` flipped back to `front` and the
- * authored `anchor` deleted — and the reason is recorded in a `degraded[]` array
- * that both of its callers discard. So the user flips the toggle, pays for a
- * render, and finds out from the output.
- *
- * This module answers the same question from data the editor already has on the
- * media row, so the toggle can tell the truth at the moment it is flipped.
- *
- * ── IT IS ONLY WORTH ANYTHING IF IT AGREES WITH THE SERVER ──────────────────
- * Every rule below mirrors a specific server rule, named at its call site. Two
- * helpers are currently duplicated from the private `@cueframe/shared/
- * variant-keys` (`hashMatteIntent`, `clipOverlapsBehindWindow`); they live here
- * because this package is the shared one, and the private copies become
- * re-exports of these when the fact-record work lands. Until then the agreement
- * is held by `__tests__/behind-readiness.test.ts`, whose key fixture is a hash
- * taken from PRODUCTION rather than invented.
- *
- * ── WHAT IT CANNOT ANSWER ───────────────────────────────────────────────────
- * The server has a FOURTH degrade path — the occlusion budget — which needs the
- * `.geometry.json` sidecar from R2, and the client has no presigned URL for it.
- * So `subject-present` means "the preconditions hold", NOT "this is guaranteed
- * to render behind", and UI copy must not promise more.
- */
-/** A matte intent: the clip's SOURCE window plus what is being cut out.
- *  Mirrors `MatteIntentLike` in the private variant-keys. */
 export interface MatteIntentLike {
     startSec: number;
     endSec: number;
     subjectClass: "person" | "product";
 }
-/** The fields this module reads off a `mediaItems.mattes[hash]` entry — the
- *  same two `resolveBehindPlacement` reads out of its `matteGeometry` map. */
 export interface MatteEntryLike {
     geometryR2Key?: string;
     presenceFraction?: number;
+    matteR2Key?: string;
+    matteUrl?: string;
+    bakeVersion?: string;
 }
-/** The clip an overlay will be placed against, and the source window whose
- *  matte answers for it. */
 export interface BehindTarget {
     mediaId: string;
     window: {
@@ -49,12 +17,6 @@ export interface BehindTarget {
         endSec: number;
     };
 }
-/**
- * Why a behind-subject overlay will or will not survive the render. The three
- * failing states correspond 1:1 to the server's degrade reasons: `no-clip` and
- * `no-subject` both degrade as `"no-subject"` there, `no-matte` as
- * `"no-geometry"`.
- */
 export type BehindReadiness = {
     state: "no-clip";
 } | {
@@ -68,60 +30,23 @@ export type BehindReadiness = {
     state: "subject-present";
     target: BehindTarget;
 };
-/**
- * Content-address a matte intent, byte-identically to the server's
- * `hashMatteIntent`. Milliseconds-rounded so float jitter cannot miss a cached
- * matte; 12 hex chars. Async because `crypto.subtle` is — available in the
- * webview and in Node alike.
- *
- * The bake VERSION is deliberately not hashed (it segments the R2 key instead),
- * so this key is stable across model bumps.
- */
 export declare function matteIntentKey(intent: MatteIntentLike): Promise<string>;
-/**
- * The clip a behind-subject overlay anchors against: **the first media clip on
- * a VIDEO track, in track→content order, whose timeline range overlaps the
- * overlay**. This is `resolveBehindPlacement`'s rule, and it is deliberately
- * NOT `computeMatteWindowsByMediaId`'s — that one also scans audio and image
- * tracks, because it answers a different question (which mattes to bake).
- * Mirroring the wrong one of the two would put the editor and the render into
- * exactly the disagreement this module exists to remove.
- *
- * The returned `window` is the clip's SOURCE trim, defaulted the way
- * `renders.ts` defaults it: `trim.start ?? 0`, `trim.end ?? start + duration`.
- * That is the window the matte is keyed by.
- *
- * Returns null when the overlay is unknown, or floats over no video clip —
- * which the server degrades as `"no-subject"`.
- */
 export declare function primaryClipForOverlay(composition: unknown, overlayId: string): BehindTarget | null;
 export interface BehindReadinessInput {
-    /** The wire-shape composition currently open in the editor. */
     composition: unknown;
-    /** The overlay being inspected. It need NOT already be behind-subject — the
-     *  editor asks this to decide what to show BEFORE the toggle is flipped. */
     overlayId: string;
-    /** `mediaItems.mattes`, per media id, exactly as it arrives from Convex. */
     mattesByMediaId: Record<string, Record<string, MatteEntryLike> | undefined>;
 }
-/**
- * Will this overlay actually render behind the subject? Mirrors the first three
- * of `resolveBehindPlacement`'s four gates, in the same order:
- *
- *   1. no primary clip                  → server: degrade("no-subject")
- *   2. no matte / no geometry sidecar   → server: degrade("no-geometry")
- *   3. presence below the floor         → server: degrade("no-subject")
- *
- * The fourth (occlusion budget) is not knowable client-side — see the header.
- */
 export declare function behindReadinessForOverlay(input: BehindReadinessInput): Promise<BehindReadiness>;
-/**
- * The same verdict from an ALREADY-RESOLVED target — the half that actually
- * costs something (a SHA-256) split from the half that is a pure walk.
- *
- * The editor calls this one. `primaryClipForOverlay` is sync, so a component
- * can memoize the target on the composition and then depend only on the
- * window's two numbers plus the media's matte record — instead of re-hashing on
- * every keystroke that produces a new composition reference.
- */
 export declare function behindReadinessForTarget(target: BehindTarget | null, mattes: Record<string, MatteEntryLike> | undefined): Promise<BehindReadiness>;
+export interface BehindWindowLike {
+    startMs: number;
+    endMs: number;
+}
+export declare function clipOverlapsBehind(clipStartSec: number, clipDurationSec: number, windows: readonly BehindWindowLike[]): boolean;
+export declare function matteWindowsByMediaId(composition: unknown, behindWindows: readonly BehindWindowLike[]): Map<string, {
+    startSec: number;
+    endSec: number;
+}>;
+export declare function behindWindowsOf(composition: unknown): BehindWindowLike[];
+export declare function captionBehindWindowsOf(composition: unknown): BehindWindowLike[];

package/dist/_members/composition/projection/brandKit.d.ts

@@ -1,34 +1,11 @@
 import type { BrandKit, EasingValue, FontRef, Motif } from "../validators/brandKit.js";
-/**
- * A brand font the render must MATERIALIZE — the render sandbox installs only the
- * Liberation faces and has no font egress, so every brand face is staged like any
- * other asset (renderInputAssets `font` role → materializeSources → @font-face).
- * This is the manifest TYPE only. The director's `resolveRenderEnvironment` maps
- * the resolved kit's font families → their woff2 R2 keys (the curated font
- * library) and presigns them — env-specific resolution (storage + creds) that does
- * NOT belong in this pure deriver. `url`: R2 key → presigned URL → loopback URL
- * across resolve → materialize, same lifecycle as a source/matte URL.
- */
 export interface FontAsset {
     family: string;
     weight: number;
     style?: "normal" | "italic";
     url: string;
 }
-/**
- * A reproduced inspiration motif, carried untransformed from the wire kit onto
- * the resolved kit's `language`. Identical to the wire `Motif` shape — the
- * language payload is exemplar/motif REFERENCE data the maker + judge condition
- * on, not a derived design token, so the cascade never rewrites it.
- */
 export type ResolvedBrandMotif = Motif;
-/**
- * The language payload of a kit built FROM INSPIRATION (spec 2026-07-14) —
- * exemplar frame keys, reproduced motifs, the style rubric, and density
- * budget. Present on `ResolvedBrandKit.language` only when the kit carries
- * exemplars; carried through resolution untransformed (NOT a `$brand:` token
- * root — see BRAND_TOKEN_ROOT_KEYS).
- */
 export interface ResolvedBrandLanguage {
     exemplarKeys: string[];
     contactSheetKey?: string;
@@ -39,12 +16,6 @@ export interface ResolvedBrandLanguage {
         maxSimultaneous: number;
     };
 }
-/**
- * A fully-materialized BrandKit. Every token has a value: either the
- * author's explicit setting, or the derived/default value the brand
- * cascade computed. Primitives consume this shape directly via
- * `$brand:<path>` resolution.
- */
 export interface ResolvedBrandKit {
     id: string;
     name: string;
@@ -90,12 +61,6 @@ export interface ResolvedBrandKit {
         body: FontRef;
         caption: FontRef;
     };
-    /**
-     * Brand faces the render must MATERIALIZE — a render manifest the harness' `font`
-     * role + materializeSources stage and the renderer @font-faces. POPULATED by the
-     * director's `resolveRenderEnvironment` (family → R2 key → presigned), NOT by this
-     * pure deriver — undefined until the render environment is resolved.
-     */
     fontAssets?: FontAsset[];
     spacing: {
         base: number;
@@ -115,14 +80,6 @@ export interface ResolvedBrandKit {
         staggerMs: number;
         exitMs: number;
     };
-    /**
-     * Brand overlay assets — present only when the kit declares them. The cascade
-     * NORMALIZES (defaults placement/sizePct/durationMs/opacity) but does NOT
-     * place-render: pixel placement is the render binding's job (a later task).
-     * Missing on the wire kit → `undefined` here (never an error). A `kind:'video'`
-     * intro/outro with no `src` carries through unchanged — PUT-time validation,
-     * not render-time resolution, is where a missing video source fails loud.
-     */
     logo?: {
         src: string;
         alt?: string;
@@ -148,22 +105,7 @@ export interface ResolvedBrandKit {
         opacity: number;
         placement: "tl" | "tr" | "bl" | "br";
     };
-    /**
-     * Language payload (built FROM INSPIRATION) — present only when the wire kit
-     * carries exemplar frames. Carried untransformed (see resolveBrandKit); NOT a
-     * `$brand:` token root, so invisible to resolveBrandRefsDeep.
-     */
     language?: ResolvedBrandLanguage;
-    /**
-     * Brand audio identity (audio design spec 2026-07-20) — carried VERBATIM from
-     * the wire kit (like `language`; not a `$brand:` token root). Consumed by the
-     * compose sfx/music pass, never by the renderer directly.
-     *
-     * Brand SOUND kit (audio-substrate Phase 5): the sonic logo, UI-sound-set
-     * overrides, and the bed/ambience preferences ride through untransformed —
-     * refs are resolved to placeable clips at compose time (sonicLogo/uiSoundSet)
-     * or surfaced for driving agents (bedStyle/ambiencePreference).
-     */
     audio?: {
         sfxIntensity?: "off" | "light" | "standard" | "dense";
         musicEnabled?: boolean;
@@ -195,84 +137,13 @@ export interface ResolvedBrandKit {
         } | null;
     };
 }
-/**
- * Resolve a sparse BrandKit against a composition's render width.
- * The width drives the spacing + sizing derivations (font sizes
- * scale to the canvas, not absolute pixels).
- */
 export declare function resolveBrandKit(kit: BrandKit, compositionWidth: number): ResolvedBrandKit;
-/**
- * The DESIGN-TOKEN sub-trees of a ResolvedBrandKit whose leaves are bindable as
- * `$brand:<path>` param values. We deliberately exclude `id`/`name` (metadata,
- * not design tokens) and the optional overlay assets (`logo`/`intro`/`outro`/
- * `watermark`/`fontAssets` — present only when a kit declares them, and not a
- * param-binding surface).
- */
 export declare const BRAND_TOKEN_ROOT_KEYS: readonly ["colors", "caption", "fonts", "spacing", "sizing", "motion"];
-/**
- * The canonical set of bindable `$brand:` token refs a param value may carry —
- * the COMPLETE design-token leaf vocabulary of a ResolvedBrandKit, DERIVED at
- * module load from a reference resolution so it can NEVER drift from the
- * resolver: add a token to ResolvedBrandKit and it appears here automatically;
- * remove one and it disappears. Surfaced on the component catalog as
- * `brandTokens` so an agent discovers e.g. `$brand:colors.accent` (a valid value
- * for an accent-color param) without reading source. Colors + fonts are the
- * common bindings; spacing/sizing/motion/caption round out the full vocabulary.
- */
 export declare const BRAND_TOKEN_REFS: readonly string[];
-/**
- * Mix two hex colors by ratio. ratio=0 returns `a` unchanged;
- * ratio=1 returns `b`; ratio=0.4 returns a 60% a + 40% b mix.
- *
- * Accepts both `#RRGGBB` and `#RGB` short form. Rejects non-hex
- * inputs (rgb()/hsl()/named colors) by returning `a` unchanged —
- * the brand cascade NEVER crashes on a malformed input; primitives
- * fall back to their declared fallback for the affected token.
- *
- * Returns `#RRGGBB` form, lowercase.
- */
 export declare function colorMix(a: string, b: string, ratio: number): string;
-/**
- * Resolve a `$brand:<dot-path>` reference against a ResolvedBrandKit.
- * Returns the value at the path, or `null` if the path doesn't exist
- * or the value isn't a primitive. Primitives use the returned `null`
- * to fall back to their declared `PrimitiveRegistryEntry.tokens[].fallback`.
- *
- * Examples:
- *   resolveBrandRef("$brand:colors.accent", kit) → "#ff0066"
- *   resolveBrandRef("$brand:fonts.heading.family", kit) → "Inter" | undefined
- *   resolveBrandRef("$brand:motion.duration", kit) → 200
- *   resolveBrandRef("not-a-ref", kit) → null (not a ref form)
- *   resolveBrandRef("$brand:colors.nonexistent", kit) → null
- *
- * Escape rule (per data-model.md § `$brand:` ref syntax): a value
- * starting with `\$brand:` is the literal string — strip the leading
- * `\` and treat as text, not a ref. This function returns `null` for
- * escaped forms; the caller (params resolver) handles the strip.
- */
 export declare function resolveBrandRef(refOrValue: unknown, kit: ResolvedBrandKit): unknown;
-/**
- * Walk an arbitrary value tree (typically `OverlaySource.params` or
- * `EffectSource.params`) and replace every `$brand:` ref string with
- * its resolved value from the kit. Non-string leaves pass through.
- * Refs that don't resolve are replaced with the provided per-token
- * fallback if any, else the original ref string is preserved so the
- * primitive's tokens[].fallback can apply at render time.
- *
- * Operates immutably — does NOT mutate the input.
- */
 export declare function resolveBrandRefsDeep(value: unknown, kit: ResolvedBrandKit): unknown;
-/**
- * Card token layer → CSS custom properties. Resolves `$brand:` refs through
- * `resolveBrandRefsDeep`, then emits every resolved string leaf as a `--cf-<k>`
- * var; unresolved refs are DROPPED (the card html's own `var(--cf-x, fallback)`
- * applies). The ONE copy of this logic — the render's OverlayContent card
- * branch and the local harness both consume it (extracted 2026-07-16; each
- * previously carried a mirror).
- */
 export declare function cssLayoutVars(tokens: Record<string, unknown> | undefined, kit: ResolvedBrandKit | undefined): Record<string, string>;
-/** The flat brand palette an authored `create_component` graphic reads from
- *  `props.brand.*` — the COMPONENT analog of a card's `var(--cf-*)`. */
 export interface ComponentBrandPalette {
     primary: string;
     secondary: string;
@@ -288,21 +159,8 @@ export interface ComponentBrandPalette {
     textOnMedia: string;
     textOnAccent: string;
     textOnSurface: string;
-    /** Resolved font FAMILIES (not FontRefs) — drop straight into `fontFamily`. */
     heading: string;
     body: string;
     caption: string;
 }
-/**
- * Component brand palette — the resolved kit an authored `create_component`
- * graphic reads from `props.brand.*`. This is the COMPONENT-medium analog of a
- * card's `cssLayoutVars` (`var(--cf-*)`): a card is freeform HTML that cascades
- * CSS custom properties; a component receives brand through its PROPS, so we hand
- * it one FLAT, already-resolved object. AUTO-INJECTED at the brand-meets-props
- * seam (`resolveBrandProps` / the ship snapshot) so a component binds to the kit
- * with ZERO prop declaration — `style={{ color: props.brand.accent, fontFamily:
- * props.brand.heading }}`. Flat by design: one dereference, no nested paths to
- * author, no `$brand:` refs to declare (the authoring cost that made the
- * ref-per-token approach ~2.4× slower per design attempt).
- */
 export declare function componentBrandPalette(kit: ResolvedBrandKit): ComponentBrandPalette;

package/dist/_members/composition/projection/cardTokens.d.ts

@@ -1,70 +1,5 @@
-/**
- * The card token contract, and the lint that enforces it at authoring time.
- *
- * A card's `tokens` map is projected to CSS custom properties by `cssLayoutVars`
- * (./brandKit): key `x` becomes `--cf-x`, so the authored html must read it as
- * `var(--cf-x)`. That one rule is the whole contract, and it was invisible on
- * every agent-facing surface until 2026-08-05.
- *
- * WHY THIS EXISTS. A real session authored 65 cards binding `tokens: {"--p":
- * …, "--f": …}` and reading them as `var(--p)` / `var(--f)`. Key `--p` projects
- * to `--cf---p`, so `var(--p)` was undefined, and CSS "invalid at
- * computed-value time" took over: `background: var(--p)` fell back to
- * transparent (the plate vanished, leaving only its box-shadow as a dark
- * smear) and `color: var(--f)` inherited black. `apply_composition` accepted
- * all 65 silently and returned 86 bytes; the render succeeded; the USER was the
- * first entity in the system to look at a pixel, 34 minutes and 3 renders in.
- *
- * ADVISORY only — same `(input) => string[]` contract as `detectNoAudioTrack`
- * (../audio/mixStaging). Reading an undefined custom property is legal CSS and
- * can be deliberate, so this never blocks an apply.
- *
- * KNOWN LIMIT: a `$brand:` token whose ref does not resolve is DROPPED by
- * `cssLayoutVars`, so `var(--cf-x)` can still be undefined at render even when
- * this lint passes. Catching that needs the org's resolved brand kit; the
- * checks here are deliberately kit-free so they cost nothing (no extra read) on
- * the apply path.
- */
 import { type ResolvedBrandKit } from "./brandKit.js";
-/**
- * The frame-driven vars `cardMotionVars` injects on EVERY card wrapper, on top
- * of the token vars. SSOT for the names — `packages/execution/render-entry/src/components/
- * cardMotion.ts` types its return against `CardMotionVarName`, so the two
- * cannot drift. The lint must treat these as always-defined or every
- * motion-authored card warns falsely.
- */
 export declare const CARD_MOTION_VAR_NAMES: readonly ["--cf-frame", "--cf-t", "--cf-fps", "--cf-duration", "--cf-progress", "--cf-ease", "--cf-enter", "--cf-exit"];
 export type CardMotionVarName = (typeof CARD_MOTION_VAR_NAMES)[number];
-/**
- * Lint every card in `value` (an ops array, a composition, a single clip — any
- * shape) and return zero, one or two advisory strings.
- *
- * Two distinct defects, because they need different fixes:
- *   `card_token_prefix`     — a tokens KEY that already starts with `--`, so it
- *                             double-prefixes to `--cf---p`. Zero false
- *                             positives; this is always a mistake.
- *   `card_token_unresolved` — html reads `var(--x)` that nothing defines. Only
- *                             fires when the name is not a `--cf-<tokens key>`,
- *                             not a motion var, not declared in the card's own
- *                             CSS, and the reference supplies no fallback.
- */
-/**
- * THE KIT-AWARE HALF, and the reason `detectUnresolvedCardTokens` cannot cover
- * it. That lint is deliberately kit-free so it costs no extra read on the apply
- * path, and its own header records the consequence: "a `$brand:` token whose ref
- * does not resolve is DROPPED by `cssLayoutVars`, so `var(--cf-x)` can still be
- * undefined at render even when this lint passes."
- *
- * That limit was cheap while every org had a brand kit. Signed out is now a
- * SUPPORTED state with no kit at all, so it stopped being an edge: on
- * 2026-08-16 every card in a composition rendered as unstyled black-on-nothing
- * text — 16px, top-left, no background — because each token was a `$brand:` ref
- * with nothing to resolve against, and nothing anywhere said so. The agent
- * looking at those stills concluded the card renderer "strips inline styles".
- *
- * Given the kit that will actually be used, this reports the card tokens that
- * will be DROPPED. Empty kit and empty result are different answers: a card with
- * literal values is fine without a kit.
- */
 export declare function detectDroppedBrandTokens(value: unknown, kit: ResolvedBrandKit | undefined): string[];
 export declare function detectUnresolvedCardTokens(value: unknown): string[];