@cueframe/kernel 0.1.0 → 0.1.2

package/dist/_members/composition/brief/contract.d.ts

@@ -1,91 +1,21 @@
-/**
- * The BRIEF CONTRACT — what the customer pinned, and what no downstream stage may undo.
- *
- * ── AUTHORITY ────────────────────────────────────────────────────────────────────────────
- * The brief owns WHAT CONTENT EXISTS. The planner owns HOW IT IS FRAMED. A planner that
- * deletes footage is not making a framing decision — it is exercising the brief's authority,
- * and no downstream guard can ever repair that.
- *
- * On 2026-07-13 the planner shipped 52.9s against a brief pinning 87.1s. It deleted the
- * product demo and the call-to-action, reasoning "No subject detected — cut for pace". Nothing
- * objected, because the contract was never even THREADED to the director: the beats are
- * resolved by `deriveBriefComposeSource` and then thrown away, and `DirectorInput.compose`
- * carries the brief flattened into a "suggestion" (caption / hook / motionStyle). The planner
- * could not honor a contract it was never shown.
- *
- * A beat's `source` window is documented as "honored TO THE FRAME or refused". So on the brief
- * path, deleting pinned footage is a contract violation, full stop.
- *
- * ── WHY 'trim' IS EFFECTIVELY FORBIDDEN HERE ─────────────────────────────────────────────
- * Brief creation ALREADY refuses a `durationSec` that differs from the pinned window by more
- * than ±1.5s (`brief_duration_unhonorable`). So by construction the contracted duration IS the
- * pinned window — the customer has declared there is no filler. Any deletion beyond the
- * tolerance therefore breaks the duration contract. A customer who wants footage cut pins
- * tighter beats; that is the channel for it.
- *
- * `'keep'` (SHOW this span AS-IS, no reframe) is the legal move for footage with nothing to
- * track. It was added 2026-07-12 for exactly this, and the planner still reaches for 'trim'.
- * A vocabulary the model may ignore is not a constraint — hence this module.
- *
- * Pure arithmetic, zero runtime imports (structural param types only), so it is safe in BOTH
- * the Convex V8 isolate (brief-creation gate) and the Temporal workflow sandbox (the plan
- * gate). One definition of the tolerances, no drift.
- */
-/** Gap tolerance between adjacent pinned beats — a larger gap means the [min,max] hull would
- *  include footage the client never pinned. */
 export declare const BEAT_CONTIGUITY_TOLERANCE_S = 0.75;
-/** Per-beat tolerance used by BRIEF CREATION: a sourced beat's own `durationSec` must match its
- *  own window to within this. (Not the plan gate's rule — see BEAT_MAX_LOSS_FRACTION.) */
 export declare const BEAT_DURATION_TOLERANCE_S = 0.5;
-/** How far the whole output may drift from the contracted duration. THE contract (documented,
- *  customer-facing) — and, because deletions only ever shrink the output, it already caps how
- *  much a plan can remove in ABSOLUTE terms. */
 export declare const BRIEF_DURATION_TOLERANCE_S = 1.5;
-/**
- * The most of ITSELF a single pinned beat may lose. A FRACTION, deliberately — not an absolute.
- *
- * Rule B already caps total deletion at ±1.5s, so no beat can lose much in absolute terms. What
- * Rule B cannot see is a SHORT beat being erased outright: a 1.5s beat deleted whole still
- * clears the aggregate. That is the only gap Rule A exists to close, so it must be expressed as
- * "did this beat survive recognisably", not as a stopwatch.
- *
- * An absolute 0.5s was tried first and was WRONG — it refused the planner's removal of a 1.44s
- * HARD PAUSE between two sentences (measured 2026-07-13). Cutting dead air is editing, which the
- * planner owns; deleting the product demo is content, which it does not. A rule that cannot tell
- * those apart is not enforcing authority, it is just being obstructive.
- */
 export declare const BEAT_MAX_LOSS_FRACTION = 0.5;
-/** A beat the customer pinned. SOURCE-absolute seconds (the brief's own frame of reference). */
 export interface BriefBeatWindow {
     id: string;
     startSec: number;
     endSec: number;
-    /**
-     * Structured graphics MANDATE on this beat (brief `beats[].graphic`): the plan
-     * must carry a `graphics` request of this `role` whose window OVERLAPS the
-     * beat (overlap, not exact pin — the planner keeps timing latitude), and any
-     * mandated `items` must appear verbatim in the request's copy. Prose
-     * mustIncludes cannot be gate-checked; this is the checkable form. `role` is
-     * structurally a string here (zero runtime imports — the zod GraphicRole
-     * enum validates at the brief door).
-     */
     graphic?: {
         role: string;
         items?: readonly string[];
     };
 }
-/** What the plan gate needs in order to know what it may not undo. */
 export interface BriefContract {
-    /** The customer's pinned beats, SOURCE-absolute. */
     beats: readonly BriefBeatWindow[];
-    /** The A-roll clip's trim start (source seconds). Converts beats → CLIP-RELATIVE, which is
-     *  the frame of reference the plan is authored in. This offset is the single most common
-     *  way a plan goes wrong; it is applied here once, centrally. */
     windowStartSec: number;
-    /** The contracted output duration = the pinned window span (see the header). */
     targetDurationSec: number;
 }
-/** The plan shape this reads. Structural, so no import of the zod model. */
 interface PlanLike {
     framing: ReadonlyArray<{
         startSec: number;
@@ -98,7 +28,6 @@ interface PlanLike {
         endSec: number;
         reason?: string;
     }>;
-    /** PlanGraphicRequest, structurally (Rule C reads role/window/copy.items). */
     graphics?: ReadonlyArray<{
         id: string;
         atSec: number;
@@ -109,24 +38,5 @@ interface PlanLike {
         };
     }>;
 }
-/**
- * Every way this plan breaks the brief's content contract, as planner-addressed messages.
- * Empty array ⇒ the plan honors the brief.
- *
- * Three rules, and ALL are needed:
- *  - Rule A (per beat): a pinned beat may not be deleted. Catches surgical beat removal that
- *    Rule B could mask by keeping filler elsewhere.
- *  - Rule B (aggregate): the contracted duration must survive. Catches death by a thousand
- *    cuts that individually clear the per-beat tolerance.
- *  - Rule C (per mandated beat): a beat's graphics MANDATE must be planned — same
- *    honor-or-refuse as A/B. Before this, a graphics-less plan against a graphics-mandating
- *    brief sailed through and cost a full plan→assemble→eval cycle for the judge to discover
- *    what the brief said in writing (prod 2026-07-14, rs7fanev…) — and with one candidate
- *    attempt there is no critique retry to rescue it: this gate is the only line of defense.
- *
- * The messages ARE the fix: each names the beat, quotes the planner's own reason back at it,
- * and prescribes the exact shape — because `runPlanPhase` feeds these straight back as the
- * planner's next-turn instruction.
- */
 export declare function planBriefViolations(plan: PlanLike, contract: BriefContract): string[];
 export {};

package/dist/_members/composition/color-grade.d.ts

@@ -1,14 +1,3 @@
-/**
- * Derive a `colorMood` (fed to `pickColorGradePreset`) from a brand kit's
- * signature colour, so a compose with NO explicit `motionStyle.colorMood` still
- * anchors the footage toward the brand instead of shipping ungraded (the Waverly
- * bug: empty colorMood → no grade → bright off-brand footage never anchored).
- *
- * Reads the brand's PRIMARY hue (falls back to accent): warm hues → "warm",
- * cool hues → "cool", else "cinematic" (a mild, safe default). Achromatic /
- * unparseable → "cinematic". Deliberately coarse — a mild anchor, not a
- * palette-exact regrade (that would need a brand-tint param on the primitive).
- */
 export declare function colorMoodFromBrand(colors: {
     primary?: string;
     accent?: string;

package/dist/_members/composition/depth.d.ts

@@ -1,23 +1,4 @@
-/**
- * Behind-subject depth predicate — the SINGLE source of truth for "does this clip
- * source render at behind-subject depth (under the subject matte)". Pure and
- * zod-free, so it's safe to import into the CF-Worker / Temporal bundles that
- * deliberately keep the zod validators out (see variant-keys.ts type-only imports).
- *
- * BOTH designed text overlays (`kind:'overlay'`) and baked custom graphics
- * (`kind:'alpha-layer'`) carry `zPlane` and MUST gate the subject matte
- * identically. Every behind-subject consumer routes through this predicate so the
- * gates can never diverge again:
- *   - collectBehindWindows / detectMattelessBehindOverlays  (@cueframe/shared)
- *   - isBehindSubjectOverlay  (@cueframe/evaluation composeEval)
- *   - resolveBehindPlacement  (director — degrade-to-front occlusion budget)
- * Anchor world-locking stays overlay-only INSIDE resolveBehindPlacement:
- * alpha-layer graphics self-position and carry no `anchor` field.
- *
- * See plan 2026-07-03-alpha-layer-behind-subject-lockstep.
- */
 import type { ClipSource } from './validators/composition.js';
-/** The two depth-bearing source kinds (text overlay + baked custom graphic). */
 export type BehindSubjectDepthSource = Extract<ClipSource, {
     kind: 'overlay' | 'alpha-layer';
 }>;

package/dist/_members/composition/fixtures/agentErrored.d.ts

@@ -1,25 +1,2 @@
-/**
- * Compositions authored by a gateway agent on 2026-06-17 that were
- * REJECTED by `PUT /v1/projects/:id/composition` (and would be by the
- * `POST /v1/composition/validate` dry-run verb) with the canonical
- * `Composition` validator.
- *
- * The API surfaced only `{"code":"validation_error","message":"","details":{}}`
- * — an EMPTY error — because `zodJson` (the API layer)
- * runs the Standard-Schema issues through `fromError(new ZodError(issues)).toString()`
- * which collapses to "". The per-field reasons exist server-side but never reach
- * the wire, so the agent could not self-correct.
- *
- * These fixtures are the raw wire payloads, captured verbatim. They are typed as
- * `unknown` (NOT `Composition`) because they are invalid by design — feed them to
- * `Composition.safeParse` to read the real `issues[]` the API swallowed, and to
- * pin the behaviour both before and after the empty-message fix.
- */
-/** First attempt — three separate portrait clips, each with its own reframe segment. */
 export declare const agentErroredCompositionV1: unknown;
-/**
- * Second attempt — the gateway agent's own "fixed" version after we reported the failure:
- * merged the three portrait clips into one 27s clip carrying all three reframe
- * segments, renamed the tracks. Still rejected with the same empty error.
- */
 export declare const agentErroredCompositionV2: unknown;

package/dist/_members/composition/fonts.d.ts

@@ -1,68 +1,6 @@
-/**
- * The font families the render sandbox actually has, and the advisory that
- * fires when a composition asks for one it doesn't.
- *
- * SSOT. This list used to exist as two hand-kept mirrors — `FONT_FAMILIES` in
- * `packages/execution/render-entry/src/fonts.ts` (which does the loading) and
- * `VENDORED_FONT_FAMILIES` in `the `/v1/components` routes` (which
- * does the component advisory) — under a comment claiming "there is no shared
- * package the app (Vite) and Convex (V8 isolate) both import". That stopped
- * being true once both imported `@cueframe/composition`, so the list lives here
- * and both sides import it.
- *
- * DEPENDENCY-FREE ON PURPOSE: the Remotion webpack bundle traverses the render
- * app's fonts.ts, so anything it pulls in must stay import-light. This module
- * has no value imports at all.
- *
- * WHY THE ADVISORY EXISTS. A real session authored 65 cards specifying
- * `font-family:'Fredoka','Nunito','Baloo 2',sans-serif`. None of the three is
- * vendored, the sandbox has no font egress, and `FONT_REGISTRY` is empty by
- * design — so every card rendered in Liberation Sans and nothing said a word.
- * The user, looking at the finished 3:17 video, attributed the result to "font
- * is too big".
- */
-/**
- * Families vendored into the render page as committed woff2 binaries. A stack
- * containing one of these rasterizes IDENTICALLY on all three render Chromiums
- * (bake box / Lambda / Modal).
- */
 export declare const VENDORED_FONT_FAMILIES: readonly ["Inter", "Space Mono", "Montserrat", "Roboto", "Poppins", "Oswald", "Playfair Display", "Bebas Neue", "Instrument Serif", "National Park", "Bricolage Grotesque", "Schibsted Grotesk"];
 export type VendoredFontFamily = (typeof VENDORED_FONT_FAMILIES)[number];
-/**
- * Families that are not raw woff2 but ARE registered as an `@font-face` alias
- * backed by a vendored binary (`Georgia` → Gelasio, the metric-compatible
- * replacement). Host-stable, so they are not advisory hits.
- */
 export declare const ALIASED_FONT_FAMILIES: readonly ["Georgia"];
-/** True when the render sandbox can rasterize this exact family name. */
 export declare function isAvailableFontFamily(family: string): boolean;
-/** Split a CSS `font-family` value into its families, quotes stripped. */
 export declare function parseFontStack(value: string): string[];
-/**
- * Advisory (never blocking) for font stacks the sandbox cannot satisfy.
- *
- * Fires only when NO family in a stack is available — i.e. the render is
- * guaranteed to land on the generic fallback nobody chose. A stack whose
- * primary is unavailable but which names a vendored family after it
- * (`'Fredoka', 'Inter', sans-serif`) is an author's deliberate fallback and is
- * NOT flagged; that is the difference between "you did not get what you asked
- * for" and "you got something you never named", and only the second is a
- * silent failure worth interrupting for.
- *
- * `$brand:` refs are skipped — run this on the BRAND-RESOLVED composition and
- * they will already be real family names. Pure: no I/O, no kit needed.
- *
- * NOTE this is about availability, not registration: `FONT_REGISTRY` in the
- * director's render-env resolver is `{}` DELIBERATELY (registering a built-in
- * there routes it through a `delayRender` that never clears on Lambda and kills
- * the render at 28s). So a custom brand font does not become available by being
- * on a brand kit — the fix for a hit here is always "use a vendored family".
- *
- * UNRESOLVED, deliberately not asserted in the message: the `search_fonts` tool
- * description tells agents "the render box has network" and to `@import` a
- * family inside card HTML, while `resolveRenderEnvironment` states the sandbox
- * "has no font egress". Both cannot be true. The advisory therefore claims only
- * what is certain — the vendored set is what is GUARANTEED — and does not
- * declare @import futile. See Issues/2026-08-05-render-font-egress-contradiction.
- */
 export declare function detectUnavailableFonts(value: unknown): string[];

package/dist/_members/composition/graphics-plan/compile.d.ts

@@ -1,28 +1,6 @@
-/**
- * Compile stage: GraphicsPlan → overlay TimelineClips. ROLE-DRIVEN and
- * COMPOSITE: a beat maps to ONE primitive that renders its whole content
- * (cinematic-title with text+subtitle, stat-counter with value+label, …), NOT
- * one overlay per line — so sub-lines use the primitive's own sub-slot instead
- * of a separate mis-sized text primitive (the P1-proof overflow bug).
- *
- * The overlay is placed at the UNION box of the beat's front elements (guarded
- * against the face) via the clip's typed `region`. Font sizes are derived from
- * each element's solved box height (so text FITS its box). Style params are
- * authored as `$brand:` refs (font refs use the `.family` leaf); with a
- * `brandKit` in opts they are resolved to LITERAL kit values at compile time
- * (deep — the render inflater only resolves TOP-LEVEL refs, so nested `tokens.*`
- * would otherwise reach the primitive unresolved). Any hex emitted is therefore
- * kit-DERIVED, never free-authored. heroText is world-locked (zPlane, no
- * authored anchor) so the silhouette gate places it — not the plan; overlapping
- * hero windows dedupe to the earliest (compileGraphicsPlan).
- */
 import type { TimelineClip } from "../validators/composition.js";
 import { type ResolvedBrandKit } from "../projection/brandKit.js";
 import type { ContentBeat, GraphicsPlan, LayoutPlan, MotionPlan } from "./schemas.js";
-/** Parse a stat string ("5 yrs", "100%", "$0 raised", "3,000 downloads") into
- *  stat-counter's numeric value + prefix/suffix. Non-digit prefix is greedy so a
- *  hyphen after letters ("Top-10") is NOT read as a negative; thousands commas
- *  are stripped from the number. null ⇒ no leading number. */
 export declare function parseStatValue(raw: string): {
     value: number;
     prefix: string;
@@ -30,14 +8,7 @@ export declare function parseStatValue(raw: string): {
 } | null;
 export interface CompileOptions {
     idPrefix?: string;
-    /** When provided, $brand: refs are resolved to LITERAL values at compile time
-     *  (deep — including nested `tokens.*`). REQUIRED for correctness: the
-     *  render-time inflater only resolves TOP-LEVEL refs, so nested token refs
-     *  (cinematic-title/lower-third colors+fonts) would otherwise reach the
-     *  primitive unresolved and fall back to its off-brand default. */
     brandKit?: ResolvedBrandKit;
 }
-/** Compile one beat (its content role + solved layout) into overlay clips. */
 export declare function compileBeat(beat: ContentBeat, layout: LayoutPlan, _motion: MotionPlan | undefined, opts?: CompileOptions): TimelineClip[];
-/** Compile a whole GraphicsPlan (all beats) into overlay clips. */
 export declare function compileGraphicsPlan(plan: GraphicsPlan, opts?: CompileOptions): TimelineClip[];

package/dist/_members/composition/graphics-plan/index.d.ts

@@ -1,8 +1,3 @@
-/**
- * Graphics-plan IR — public surface. See ./schemas.ts for the contract and
- * brain/Projects/CueFrame/plans/2026-07-07-structure-first-graphics-pipeline.md
- * for the design.
- */
 export * from "./schemas.js";
 export * from "./solve.js";
 export * from "./motion.js";

package/dist/_members/composition/graphics-plan/instantiateMotif.d.ts

@@ -1,20 +1,5 @@
-/**
- * Deterministic instantiation of a REPRODUCED brand-kit motif skin — Lane A of
- * the two-lane graphics agent (plan 2026-07-16). A skin is the motif's verified
- * authored form (`brandMotif.body`, pixel-diffed against the reference at
- * ingestion); at compose time the graphic's copy is slotted into it with NO
- * LLM: pure text replacement under the slot convention.
- *
- * SLOT CONVENTION (defined here, enforced here, authored by the reproduction
- * loop): copy-bearing elements carry `data-slot="<copyKey>"` and contain ONLY
- * text. That constraint is what makes regex replacement sound — no HTML parser
- * dependency enters the composition leaf. Every violation FAILS LOUD; a silent
- * redesign is exactly the variance this lane exists to remove.
- */
 export declare class MotifInstantiationError extends Error {
 }
-/** The subset of the wire `brandMotif` this function consumes (kept structural
- *  so callers can pass the Convex projection or a local fixture verbatim). */
 export interface ReproducedMotif {
     coverage: "reproduced" | "approximated" | "skipped";
     body: {
@@ -43,8 +28,6 @@ export interface ReproducedMotif {
         h: number;
     };
 }
-/** Fill a reproduced card skin's slots with the graphic's copy. Throws
- *  MotifInstantiationError on any deviation from the convention. */
 export declare function instantiateMotif(motif: ReproducedMotif, copy: Record<string, string>): {
     html: string;
     tokens?: Record<string, string>;

package/dist/_members/composition/graphics-plan/motion.d.ts

@@ -1,19 +1,2 @@
-/**
- * Motion stage: LayoutPlan → MotionPlan. Assigns a sensible default
- * entrance/emphasis/exit per element role, staggered so elements don't all
- * arrive at once. This is the inspectable MOTION artifact of the plan (a
- * checkpoint surface, and what an agent revises).
- *
- * NOTE (honest status): the compiler does NOT yet consume MotionPlan — the
- * primitives currently animate from their own `$brand:motion` defaults
- * (entrance/duration/easing). Wiring MotionPlan → per-primitive animation
- * params is a follow-up (FC3). Until then this plan is descriptive, not
- * yet the driver.
- */
 import { type LayoutPlan, type MotionPlan } from "./schemas.js";
-/**
- * Build the motion plan for a laid-out beat. Entrances stagger by element order;
- * everything fades out together in the last ~350ms of the beat so a graphic never
- * hard-cuts. `durSec` is the beat length (from the ContentPlan beat).
- */
 export declare function planMotion(layout: LayoutPlan, durSec: number): MotionPlan;