@cueframe/kernel 0.1.1 → 0.1.2

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

@@ -1,31 +1,5 @@
-/**
- * Graphics-plan IR — the structure-first authoring contract (plan
- * 2026-07-07-structure-first-graphics-pipeline). Instead of the designer
- * authoring Remotion JSX blind, it produces these three inspectable,
- * versioned artifacts; a compiler turns them into brand-bound, animatable
- * Remotion. The SAME schema is the client-agent CHECKPOINT payload AND the
- * compiler input — no translation layer to drift.
- *
- * Split by concern so each stage boundary is a review/edit point:
- *   ContentPlan  — WHAT to say (editorial, text-owned; never pixels).
- *   LayoutPlan   — WHERE it sits (spatial structure, content-aware: element
- *                  boxes are solved CLEAR of the face keep-outs the
- *                  composition-floor already computes → text-over-face is
- *                  impossible by construction, not by prompt).
- *   MotionPlan   — HOW it animates (entrance / emphasis / exit intent).
- *
- * `styleRole` binds to brand tokens (never a raw hex/font) so off-brand
- * output is impossible; the compiler resolves it via the same `$brand:`
- * mechanism as packages/authoring/src/tools/brandTokens.ts.
- */
 import { z } from "zod";
-/** Bump when a field's meaning changes; the compiler + checkpoint clients
- *  branch on it. Kept a literal so an old client sees a hard mismatch, not a
- *  silent misread. */
 export declare const GRAPHICS_PLAN_VERSION = "gp-1";
-/** A rect in output-frame fractions [0,1] — the SAME placement vocabulary as
- *  the composition-floor `Rect` and the wire `Region` (reused so a plan box and
- *  a rendered layer can never disagree about coordinates). */
 export declare const PlanRect: z.ZodObject<{
     x: z.ZodNumber;
     y: z.ZodNumber;
@@ -43,58 +17,14 @@ export declare const PlanRect: z.ZodObject<{
     h: number;
 }>;
 export type PlanRect = z.infer<typeof PlanRect>;
-/**
- * What the beat must COMMUNICATE. An EDITORIAL vocabulary — deliberately not a list of
- * primitive names.
- *
- * The first six are named after primitive families, and that was the bug: the DESIGNER's
- * decision (which component draws this) had leaked into the PLANNER's schema. It meant the
- * vocabulary could only grow by adding primitive names, so it could never keep up with the
- * catalog — and on 2026-07-13 a brief demanding a chain-trace, comparison bars and a
- * three-item build got exactly ONE lower-third, because a lower-third was close to the most
- * the planner was ABLE to say. It was not being lazy. It had no word for what the brief wanted.
- *
- * The last three are the fix, and they name a JOB, not a picture:
- *   the planner says "this beat must show a sequence"; the DESIGNER decides whether that is
- *   `reasoning-trace`, `tool-call-stack`, or something it writes itself.
- *
- * Closed on purpose (the critics and the layout solver switch on it) — but closed around
- * editorial intent, which is a small and stable set, instead of around a 103-component catalog,
- * which is neither.
- */
 export declare const GraphicRole: z.ZodEnum<["title-card", "stat", "lower-third", "pull-quote", "hero", "logo-tag", "enumeration", "sequence", "comparison"]>;
 export type GraphicRole = z.infer<typeof GraphicRole>;
-/**
- * The words for a beat — ALWAYS plan-owned (a text-to-image model can't spell; the Remotion code
- * renders these crisply). All optional; a role uses the subset it needs
- * (stat → value+label; title-card → headline+sub; enumeration/sequence → items; comparison → series).
- *
- * `items` and `series` exist because the plan OWNS the words, and a role it cannot supply the
- * words for is a role it cannot actually request. Four scalars could not carry a list or a
- * labelled series, so even a widened role vocabulary would have had nowhere to put its content —
- * the second half of the same 2026-07-13 bug, and the one that would have silently defeated the
- * fix for the first half.
- */
 export declare const Copy: z.ZodObject<{
     headline: z.ZodOptional<z.ZodString>;
     sub: z.ZodOptional<z.ZodString>;
     value: z.ZodOptional<z.ZodString>;
     label: z.ZodOptional<z.ZodString>;
-    /** Ordered short items — an `enumeration`'s bullets, a `sequence`'s steps. */
     items: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    /**
-     * Labelled values for a `comparison`.
-     *
-     * `value` is a STRING, deliberately — not `number | string`. The plan owns the words, and a
-     * comparison's words include their units: a planner writes "10 min", "98%", "$4.2M", never
-     * 600. A number would have to be re-unitised downstream by someone who doesn't know what it
-     * meant.
-     *
-     * It is also a hard constraint: `submit_compose_plan` is a STRICT Anthropic tool
-     * (`strict: true`, schemas.ts), and a `z.union` here becomes an `anyOf` in the tool schema.
-     * That is what stalled the planner on 2026-07-13 — it ran, could not satisfy the schema, and
-     * never called the tool at all. Keep every field in this schema a single concrete type.
-     */
     series: z.ZodOptional<z.ZodArray<z.ZodObject<{
         label: z.ZodString;
         value: z.ZodString;
@@ -129,7 +59,6 @@ export declare const Copy: z.ZodObject<{
 export type Copy = z.infer<typeof Copy>;
 export declare const ContentBeat: z.ZodObject<{
     id: z.ZodString;
-    /** Clip-relative seconds. */
     atSec: z.ZodNumber;
     durSec: z.ZodNumber;
     role: z.ZodEnum<["title-card", "stat", "lower-third", "pull-quote", "hero", "logo-tag", "enumeration", "sequence", "comparison"]>;
@@ -138,21 +67,7 @@ export declare const ContentBeat: z.ZodObject<{
         sub: z.ZodOptional<z.ZodString>;
         value: z.ZodOptional<z.ZodString>;
         label: z.ZodOptional<z.ZodString>;
-        /** Ordered short items — an `enumeration`'s bullets, a `sequence`'s steps. */
         items: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        /**
-         * Labelled values for a `comparison`.
-         *
-         * `value` is a STRING, deliberately — not `number | string`. The plan owns the words, and a
-         * comparison's words include their units: a planner writes "10 min", "98%", "$4.2M", never
-         * 600. A number would have to be re-unitised downstream by someone who doesn't know what it
-         * meant.
-         *
-         * It is also a hard constraint: `submit_compose_plan` is a STRICT Anthropic tool
-         * (`strict: true`, schemas.ts), and a `z.union` here becomes an `anyOf` in the tool schema.
-         * That is what stalled the planner on 2026-07-13 — it ran, could not satisfy the schema, and
-         * never called the tool at all. Keep every field in this schema a single concrete type.
-         */
         series: z.ZodOptional<z.ZodArray<z.ZodObject<{
             label: z.ZodString;
             value: z.ZodString;
@@ -184,9 +99,7 @@ export declare const ContentBeat: z.ZodObject<{
             label: string;
         }[] | undefined;
     }>;
-    /** Editorial WHY — the beat this graphic serves (for review + the judge). */
     intent: z.ZodString;
-    /** Higher = more important; drives drop order under budget. */
     priority: z.ZodDefault<z.ZodNumber>;
 }, "strict", z.ZodTypeAny, {
     id: string;
@@ -230,7 +143,6 @@ export declare const ContentPlan: z.ZodObject<{
     version: z.ZodLiteral<"gp-1">;
     beats: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
-        /** Clip-relative seconds. */
         atSec: z.ZodNumber;
         durSec: z.ZodNumber;
         role: z.ZodEnum<["title-card", "stat", "lower-third", "pull-quote", "hero", "logo-tag", "enumeration", "sequence", "comparison"]>;
@@ -239,21 +151,7 @@ export declare const ContentPlan: z.ZodObject<{
             sub: z.ZodOptional<z.ZodString>;
             value: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
-            /** Ordered short items — an `enumeration`'s bullets, a `sequence`'s steps. */
             items: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-            /**
-             * Labelled values for a `comparison`.
-             *
-             * `value` is a STRING, deliberately — not `number | string`. The plan owns the words, and a
-             * comparison's words include their units: a planner writes "10 min", "98%", "$4.2M", never
-             * 600. A number would have to be re-unitised downstream by someone who doesn't know what it
-             * meant.
-             *
-             * It is also a hard constraint: `submit_compose_plan` is a STRICT Anthropic tool
-             * (`strict: true`, schemas.ts), and a `z.union` here becomes an `anyOf` in the tool schema.
-             * That is what stalled the planner on 2026-07-13 — it ran, could not satisfy the schema, and
-             * never called the tool at all. Keep every field in this schema a single concrete type.
-             */
             series: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 label: z.ZodString;
                 value: z.ZodString;
@@ -285,9 +183,7 @@ export declare const ContentPlan: z.ZodObject<{
                 label: string;
             }[] | undefined;
         }>;
-        /** Editorial WHY — the beat this graphic serves (for review + the judge). */
         intent: z.ZodString;
-        /** Higher = more important; drives drop order under budget. */
         priority: z.ZodDefault<z.ZodNumber>;
     }, "strict", z.ZodTypeAny, {
         id: string;
@@ -370,24 +266,15 @@ export declare const ContentPlan: z.ZodObject<{
     }[];
 }>;
 export type ContentPlan = z.infer<typeof ContentPlan>;
-/** The role of ONE element within a graphic — maps to a primitive slot. */
 export declare const ElementRole: z.ZodEnum<["headline", "value", "label", "sublabel", "logo", "accent-shape", "backdrop"]>;
 export type ElementRole = z.infer<typeof ElementRole>;
-/** Semantic style binding → resolved to `$brand:` refs by the compiler; NEVER a
- *  raw hex/font. This is the guarantee that on-brand is the only option.
- *  Mapping (compiler): heading→fonts.heading+colors.text, accent→colors.accent,
- *  body→fonts.body+colors.text, surface→colors.surface/background,
- *  on-accent→colors.textOnAccent, on-surface→colors.textOnSurface. */
 export declare const StyleRole: z.ZodEnum<["heading", "body", "accent", "surface", "on-accent", "on-surface"]>;
 export type StyleRole = z.infer<typeof StyleRole>;
-/** Depth plane — matches OverlayClipSource.zPlane. `behind-subject` is the
- *  intentional hero look (the subject cut-out bites the letters). */
 export declare const ZPlane: z.ZodEnum<["front", "behind-subject"]>;
 export type ZPlane = z.infer<typeof ZPlane>;
 export declare const LayoutElement: z.ZodObject<{
     elId: z.ZodString;
     role: z.ZodEnum<["headline", "value", "label", "sublabel", "logo", "accent-shape", "backdrop"]>;
-    /** Solved CLEAR of `keepOut` (except intentional behind-subject heroes). */
     box: z.ZodObject<{
         x: z.ZodNumber;
         y: z.ZodNumber;
@@ -406,11 +293,7 @@ export declare const LayoutElement: z.ZodObject<{
     }>;
     styleRole: z.ZodEnum<["heading", "body", "accent", "surface", "on-accent", "on-surface"]>;
     z: z.ZodDefault<z.ZodEnum<["front", "behind-subject"]>>;
-    /** The text this element renders (from the ContentPlan). Omitted for
-     *  logo / accent-shape / backdrop. */
     text: z.ZodOptional<z.ZodString>;
-    /** Index into the editorial type scale (mirrors composition-floor
-     *  Treatment.typeScaleStep) — a SCALE STEP, not a raw px guess. */
     typeScaleStep: z.ZodOptional<z.ZodNumber>;
 }, "strict", z.ZodTypeAny, {
     role: "value" | "headline" | "label" | "sublabel" | "logo" | "accent-shape" | "backdrop";
@@ -443,7 +326,6 @@ export type LayoutElement = z.infer<typeof LayoutElement>;
 export declare const LayoutPlan: z.ZodEffects<z.ZodObject<{
     version: z.ZodLiteral<"gp-1">;
     beatId: z.ZodString;
-    /** Output aspect context (pixels); placement itself is in [0,1] fractions. */
     frame: z.ZodObject<{
         w: z.ZodNumber;
         h: z.ZodNumber;
@@ -454,9 +336,6 @@ export declare const LayoutPlan: z.ZodEffects<z.ZodObject<{
         w: number;
         h: number;
     }>;
-    /** INPUT (not authored): face keep-out rects at this beat, from the
-     *  composition-floor. The layout stage MUST place `front` elements clear of
-     *  these — carried on the plan so a reviewer/compiler can verify it. */
     keepOut: z.ZodArray<z.ZodObject<{
         x: z.ZodNumber;
         y: z.ZodNumber;
@@ -473,7 +352,6 @@ export declare const LayoutPlan: z.ZodEffects<z.ZodObject<{
         w: number;
         h: number;
     }>, "many">;
-    /** INPUT: safe-zone insets (title-safe / action-safe fractions). */
     safe: z.ZodObject<{
         titleSafe: z.ZodNumber;
         actionSafe: z.ZodNumber;
@@ -487,7 +365,6 @@ export declare const LayoutPlan: z.ZodEffects<z.ZodObject<{
     elements: z.ZodArray<z.ZodObject<{
         elId: z.ZodString;
         role: z.ZodEnum<["headline", "value", "label", "sublabel", "logo", "accent-shape", "backdrop"]>;
-        /** Solved CLEAR of `keepOut` (except intentional behind-subject heroes). */
         box: z.ZodObject<{
             x: z.ZodNumber;
             y: z.ZodNumber;
@@ -506,11 +383,7 @@ export declare const LayoutPlan: z.ZodEffects<z.ZodObject<{
         }>;
         styleRole: z.ZodEnum<["heading", "body", "accent", "surface", "on-accent", "on-surface"]>;
         z: z.ZodDefault<z.ZodEnum<["front", "behind-subject"]>>;
-        /** The text this element renders (from the ContentPlan). Omitted for
-         *  logo / accent-shape / backdrop. */
         text: z.ZodOptional<z.ZodString>;
-        /** Index into the editorial type scale (mirrors composition-floor
-         *  Treatment.typeScaleStep) — a SCALE STEP, not a raw px guess. */
         typeScaleStep: z.ZodOptional<z.ZodNumber>;
     }, "strict", z.ZodTypeAny, {
         role: "value" | "headline" | "label" | "sublabel" | "logo" | "accent-shape" | "backdrop";
@@ -539,10 +412,6 @@ export declare const LayoutPlan: z.ZodEffects<z.ZodObject<{
         z?: "front" | "behind-subject" | undefined;
         typeScaleStep?: number | undefined;
     }>, "many">;
-    /** Set when the solver could NOT place a beat's graphic legally (e.g. the
-     *  face fills the legal area). Makes a drop OBSERVABLE — distinct from a
-     *  beat that legitimately had no copy (both yield elements:[]). The producer
-     *  can surface it; the compiler skips it. */
     dropped: z.ZodOptional<z.ZodObject<{
         reason: z.ZodString;
     }, "strict", z.ZodTypeAny, {
@@ -694,8 +563,6 @@ export declare const EmphasisType: z.ZodEnum<["pulse", "underline", "color-shift
 export type EmphasisType = z.infer<typeof EmphasisType>;
 export declare const ExitType: z.ZodEnum<["fade", "fall", "wipe", "cut"]>;
 export type ExitType = z.infer<typeof ExitType>;
-/** Ease vocabulary → compiler maps to real spring/interpolate. Named, not raw
- *  bezier/ms, so the brand's motion pace stays a decision not a magic number. */
 export declare const Ease: z.ZodEnum<["spring", "ease-out", "ease-in-out", "linear"]>;
 export type Ease = z.infer<typeof Ease>;
 export declare const EnterMotion: z.ZodObject<{
@@ -703,7 +570,6 @@ export declare const EnterMotion: z.ZodObject<{
     atMs: z.ZodNumber;
     durMs: z.ZodNumber;
     ease: z.ZodDefault<z.ZodEnum<["spring", "ease-out", "ease-in-out", "linear"]>>;
-    /** Per-child stagger (ms) for multi-part reveals. */
     stagger: z.ZodOptional<z.ZodNumber>;
 }, "strict", z.ZodTypeAny, {
     type: "fade" | "reveal" | "rise" | "count-up" | "wipe";
@@ -751,7 +617,6 @@ export declare const MotionElement: z.ZodObject<{
         atMs: z.ZodNumber;
         durMs: z.ZodNumber;
         ease: z.ZodDefault<z.ZodEnum<["spring", "ease-out", "ease-in-out", "linear"]>>;
-        /** Per-child stagger (ms) for multi-part reveals. */
         stagger: z.ZodOptional<z.ZodNumber>;
     }, "strict", z.ZodTypeAny, {
         type: "fade" | "reveal" | "rise" | "count-up" | "wipe";
@@ -842,7 +707,6 @@ export declare const MotionPlan: z.ZodObject<{
             atMs: z.ZodNumber;
             durMs: z.ZodNumber;
             ease: z.ZodDefault<z.ZodEnum<["spring", "ease-out", "ease-in-out", "linear"]>>;
-            /** Per-child stagger (ms) for multi-part reveals. */
             stagger: z.ZodOptional<z.ZodNumber>;
         }, "strict", z.ZodTypeAny, {
             type: "fade" | "reveal" | "rise" | "count-up" | "wipe";
@@ -970,16 +834,12 @@ export declare const MotionPlan: z.ZodObject<{
     }[];
 }>;
 export type MotionPlan = z.infer<typeof MotionPlan>;
-/** The full graphics plan for a compose run: one ContentPlan, and a
- *  Layout+Motion pair per beat (keyed by beatId). This is the object a
- *  checkpoint returns and the compiler consumes. */
 export declare const GraphicsPlan: z.ZodObject<{
     version: z.ZodLiteral<"gp-1">;
     content: z.ZodObject<{
         version: z.ZodLiteral<"gp-1">;
         beats: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
-            /** Clip-relative seconds. */
             atSec: z.ZodNumber;
             durSec: z.ZodNumber;
             role: z.ZodEnum<["title-card", "stat", "lower-third", "pull-quote", "hero", "logo-tag", "enumeration", "sequence", "comparison"]>;
@@ -988,21 +848,7 @@ export declare const GraphicsPlan: z.ZodObject<{
                 sub: z.ZodOptional<z.ZodString>;
                 value: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
-                /** Ordered short items — an `enumeration`'s bullets, a `sequence`'s steps. */
                 items: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-                /**
-                 * Labelled values for a `comparison`.
-                 *
-                 * `value` is a STRING, deliberately — not `number | string`. The plan owns the words, and a
-                 * comparison's words include their units: a planner writes "10 min", "98%", "$4.2M", never
-                 * 600. A number would have to be re-unitised downstream by someone who doesn't know what it
-                 * meant.
-                 *
-                 * It is also a hard constraint: `submit_compose_plan` is a STRICT Anthropic tool
-                 * (`strict: true`, schemas.ts), and a `z.union` here becomes an `anyOf` in the tool schema.
-                 * That is what stalled the planner on 2026-07-13 — it ran, could not satisfy the schema, and
-                 * never called the tool at all. Keep every field in this schema a single concrete type.
-                 */
                 series: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     label: z.ZodString;
                     value: z.ZodString;
@@ -1034,9 +880,7 @@ export declare const GraphicsPlan: z.ZodObject<{
                     label: string;
                 }[] | undefined;
             }>;
-            /** Editorial WHY — the beat this graphic serves (for review + the judge). */
             intent: z.ZodString;
-            /** Higher = more important; drives drop order under budget. */
             priority: z.ZodDefault<z.ZodNumber>;
         }, "strict", z.ZodTypeAny, {
             id: string;
@@ -1121,7 +965,6 @@ export declare const GraphicsPlan: z.ZodObject<{
     layouts: z.ZodArray<z.ZodEffects<z.ZodObject<{
         version: z.ZodLiteral<"gp-1">;
         beatId: z.ZodString;
-        /** Output aspect context (pixels); placement itself is in [0,1] fractions. */
         frame: z.ZodObject<{
             w: z.ZodNumber;
             h: z.ZodNumber;
@@ -1132,9 +975,6 @@ export declare const GraphicsPlan: z.ZodObject<{
             w: number;
             h: number;
         }>;
-        /** INPUT (not authored): face keep-out rects at this beat, from the
-         *  composition-floor. The layout stage MUST place `front` elements clear of
-         *  these — carried on the plan so a reviewer/compiler can verify it. */
         keepOut: z.ZodArray<z.ZodObject<{
             x: z.ZodNumber;
             y: z.ZodNumber;
@@ -1151,7 +991,6 @@ export declare const GraphicsPlan: z.ZodObject<{
             w: number;
             h: number;
         }>, "many">;
-        /** INPUT: safe-zone insets (title-safe / action-safe fractions). */
         safe: z.ZodObject<{
             titleSafe: z.ZodNumber;
             actionSafe: z.ZodNumber;
@@ -1165,7 +1004,6 @@ export declare const GraphicsPlan: z.ZodObject<{
         elements: z.ZodArray<z.ZodObject<{
             elId: z.ZodString;
             role: z.ZodEnum<["headline", "value", "label", "sublabel", "logo", "accent-shape", "backdrop"]>;
-            /** Solved CLEAR of `keepOut` (except intentional behind-subject heroes). */
             box: z.ZodObject<{
                 x: z.ZodNumber;
                 y: z.ZodNumber;
@@ -1184,11 +1022,7 @@ export declare const GraphicsPlan: z.ZodObject<{
             }>;
             styleRole: z.ZodEnum<["heading", "body", "accent", "surface", "on-accent", "on-surface"]>;
             z: z.ZodDefault<z.ZodEnum<["front", "behind-subject"]>>;
-            /** The text this element renders (from the ContentPlan). Omitted for
-             *  logo / accent-shape / backdrop. */
             text: z.ZodOptional<z.ZodString>;
-            /** Index into the editorial type scale (mirrors composition-floor
-             *  Treatment.typeScaleStep) — a SCALE STEP, not a raw px guess. */
             typeScaleStep: z.ZodOptional<z.ZodNumber>;
         }, "strict", z.ZodTypeAny, {
             role: "value" | "headline" | "label" | "sublabel" | "logo" | "accent-shape" | "backdrop";
@@ -1217,10 +1051,6 @@ export declare const GraphicsPlan: z.ZodObject<{
             z?: "front" | "behind-subject" | undefined;
             typeScaleStep?: number | undefined;
         }>, "many">;
-        /** Set when the solver could NOT place a beat's graphic legally (e.g. the
-         *  face fills the legal area). Makes a drop OBSERVABLE — distinct from a
-         *  beat that legitimately had no copy (both yield elements:[]). The producer
-         *  can surface it; the compiler skips it. */
         dropped: z.ZodOptional<z.ZodObject<{
             reason: z.ZodString;
         }, "strict", z.ZodTypeAny, {
@@ -1375,7 +1205,6 @@ export declare const GraphicsPlan: z.ZodObject<{
                 atMs: z.ZodNumber;
                 durMs: z.ZodNumber;
                 ease: z.ZodDefault<z.ZodEnum<["spring", "ease-out", "ease-in-out", "linear"]>>;
-                /** Per-child stagger (ms) for multi-part reveals. */
                 stagger: z.ZodOptional<z.ZodNumber>;
             }, "strict", z.ZodTypeAny, {
                 type: "fade" | "reveal" | "rise" | "count-up" | "wipe";

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

@@ -1,15 +1,3 @@
-/**
- * Layout stage (P1): ContentBeat → LayoutPlan. Deterministic placement that is
- * content-aware BY CONSTRUCTION — every front element is solved clear of the
- * composition-floor face keep-outs (reusing `placeInLegalArea`), so text can
- * never land on the speaker. This is the "solver snaps to legal" half of the
- * hybrid layout stage; P4 lets an agent PROPOSE boxes that this validates/snaps.
- *
- * A per-role TEMPLATE decomposes each graphic into ordered element slots; the
- * solver finds one legal vertical band for the whole stack and lays the slots
- * out within it. styleRole (→ brand token) and typeScaleStep (→ type scale) are
- * assigned per slot, so nothing off-brand or raw-px is emitted.
- */
 import { type Rect } from "../projection/composition-floor.js";
 import { type ContentBeat, type LayoutPlan } from "./schemas.js";
 export interface LayoutContext {
@@ -17,18 +5,11 @@ export interface LayoutContext {
         w: number;
         h: number;
     };
-    /** Face keep-out rects at this beat (from the composition-floor). */
     keepOut: Rect[];
     safe: {
         titleSafe: number;
         actionSafe: number;
     };
 }
-/**
- * Solve one beat's layout. Front stacks land in a legal band clear of the face;
- * behind-subject heroes intentionally ignore the keep-out (the subject occludes
- * them). An opener with no detected face centers vertically.
- */
 export declare function solveLayout(beat: ContentBeat, ctx: LayoutContext): LayoutPlan;
-/** True iff two rects overlap (used by tests + the P4 agent-proposal validator). */
 export declare function rectsOverlap(a: Rect, b: Rect): boolean;

package/dist/_members/composition/invariants/clipPlacement.d.ts

@@ -1,65 +1,6 @@
-/**
- * CLIP↔TRACK PLACEMENT — the DB-free half of the rule, in the KERNEL so both
- * lanes can run ONE implementation.
- *
- * THE GAP THIS NARROWS. `applyHandler`'s dry-run advertises itself as partial
- * (`LOCAL_VALIDATION_PARTIAL`): the server also runs `the backend
- * composition/` projection guards that the desktop cannot import, so a local
- * `valid: true` is not a promise the cloud would accept the same composition.
- * Two of those guards need nothing the desktop lacks, and their absence cost a
- * real project.
- *
- * WHAT WENT WRONG (2026-08-18, project "launch"). An agent wrote, and the local
- * lane accepted:
- *
- *     video track  start=0  duration=0   perfect-wave-…mp3
- *     video track  start=0  duration=0   perfect-wave-…mp3   (the same clip twice)
- *     video track  start=0  duration=0   mouse-click-…mp3
- *
- * Three zero-length clips stacked at 0, and MP3 AUDIO on a VIDEO track. The
- * composition's duration came out 0:00.00 — nothing to play, nothing to fix
- * from the UI, and the project was effectively dead. The cloud refuses exactly
- * this (`media_family_track_mismatch`), but that check is DB-bound there: it
- * needs the media row's kind. The desktop has that kind ALREADY, in
- * `ProjectContextPayload.media[].kind` — so the reason it was not checked here
- * is that nobody wired it, not that it could not be known.
- *
- * WHY IT LIVES HERE AND NOT IN THE DESKTOP. The first cut of this WAS a
- * desktop-only copy — which is exactly the drift this repo spends real effort
- * avoiding (the lane-conformance table exists because a rule added to ONE lane
- * is a rule the other lane does not have). `applyHandler` already prescribed
- * the fix in prose: "closing the gap for real means hoisting those validators
- * into `@cueframe/composition`". So it is hoisted, not duplicated.
- *
- * STILL OUTSTANDING, said plainly so nobody assumes otherwise: the CLOUD keeps
- * its own implementation in `the server's composition projection`. This
- * is now the shared HOME, not yet the single CALLER. Pointing the cloud guard
- * at this function is the remaining step, and until it happens the two can
- * still drift.
- *
- * DELIBERATELY NARROW. Only two facts are asserted, and both are establishable
- * without a database — which is what makes them shareable at all:
- *
- *   1. A media clip whose media KIND is known and whose family plainly
- *      contradicts the track it sits on.
- *   2. A clip with a non-positive duration.
- *
- * An UNKNOWN kind is not an error — the pool may not have probed the item yet,
- * and refusing on absence would block legitimate authoring against media that
- * is still ingesting. That is the same "absence is not evidence" rule the
- * transcript panel had to learn.
- */
 import type { Composition } from "../validators/composition.js";
 export interface ProjectionIssue {
     clipId: string;
     message: string;
 }
-/**
- * @param composition the FOLDED composition — checked on the result rather than
- *   on the ops, so it cannot be walked around by the shape of the batch (the
- *   same reasoning as the component gate beside it).
- * @param mediaKindById `mediaId -> kind`. The desktop passes
- *   `getContext().media`; a server caller passes its media rows. A missing entry
- *   means "not judged".
- */
 export declare function collectClipPlacementIssues(composition: Composition, mediaKindById: Record<string, string>): ProjectionIssue[];

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

@@ -1,9 +1,4 @@
 import type { Composition } from "../validators/composition.js";
 import type { InvariantViolation } from "./errors.js";
-/**
- * Run every structural invariant against a Composition.
- * Returns a flat list of violations; empty array = valid.
- */
 export declare function checkComposition(composition: Composition): InvariantViolation[];
-/** Convenience: duration = max(startTime + duration) across every Track's contents. */
 export declare function compositionDuration(composition: Composition): number;

package/dist/_members/composition/invariants/etag.d.ts

@@ -1,10 +1,3 @@
 import type { Composition } from "../validators/composition.js";
-/**
- * Canonicalize an object for deterministic hashing:
- * - object keys sorted lexicographically at every depth
- * - arrays preserve order
- * - undefined fields dropped (JSON semantics)
- * - null / number / string / boolean preserved as-is
- */
 export declare function canonicalJSON(value: unknown): string;
 export declare function etag(composition: Composition): string;

package/dist/_members/composition/invariants/ids.d.ts

@@ -1,9 +1,3 @@
 import type { Composition } from "../validators/composition.js";
 import type { InvariantViolation } from "./errors.js";
-/**
- * Entity ids share a single namespace within the Composition.
- * TimelineClip.id, Track.id, Gap.id, Marker.id must all be unique.
- *
- * composition_id_collision { existingKind, newKind, id }
- */
 export declare function checkIdCollisions(composition: Composition): InvariantViolation[];

package/dist/_members/composition/invariants/keyframes.d.ts

@@ -1,22 +1,3 @@
-/**
- * KEYFRAME INVARIANTS — the producers for two error codes that had none.
- *
- * `varying_keyframe_time_out_of_range` and `varying_keyframe_duplicate_time`
- * have been in `errors.ts` since before the composition had any keyframe model
- * at all. A `grep` for either returned exactly one hit each: their own
- * declaration. Somebody knew what the failures would be before there was
- * anything that could fail. This file is the other half.
- *
- * Both rules exist because of what clip-relative time makes possible:
- *
- *   OUT OF RANGE — a keyframe past the clip's duration is unreachable. It is
- *   not harmless: trim a clip shorter and its tail keyframes silently stop
- *   mattering, so the motion the author saw is not the motion that ships, with
- *   nothing in the document looking wrong.
- *
- *   DUPLICATE TIME — two values at one instant have no defined result. The
- *   interpolator would pick by sort order, which is not a decision anyone made.
- */
 import type { Composition, TimelineClip } from "../validators/composition.js";
 import type { InvariantViolation } from "./errors.js";
 export declare function checkClipKeyframes(clip: TimelineClip): InvariantViolation[];

package/dist/_members/composition/invariants/markers.d.ts

@@ -1,9 +1,3 @@
 import type { Composition } from "../validators/composition.js";
 import type { InvariantViolation } from "./errors.js";
-/**
- * Markers with `kind: 'scene'` cannot overlap (single-partition rule).
- * Other kinds (chapter, note, agent, custom) are free to overlap.
- *
- * scene_marker_overlap { markerAId, markerBId, overlapRange }
- */
 export declare function checkSceneMarkerPartition(composition: Composition): InvariantViolation[];

package/dist/_members/composition/invariants/time.d.ts

@@ -1,17 +1,9 @@
-/**
- * OTIO / native-renderer time quantization rule.
- * See data-model.md §OTIO time export rule and §Native renderer time quantization.
- */
 export declare function otioFrames(seconds: number, fps: number): number;
 export interface RationalTime {
     value: number;
     rate: number;
 }
 export declare function otioRationalTime(seconds: number, fps: number): RationalTime;
-/**
- * Per-output-frame source-frame mapping (renderer contract).
- * Matches the OTIO writer's quantization at the boundary.
- */
 export declare function sourceFrame(params: {
     outputFrame: number;
     formatFps: number;

package/dist/_members/composition/invariants/tracks.d.ts

@@ -1,58 +1,10 @@
 import type { TimelineClip, Track, Composition } from "../validators/composition.js";
 import type { InvariantViolation } from "./errors.js";
-/**
- * Clips and Gaps on a single Track cannot overlap.
- * track_clips_overlap { trackId, clipAId, clipBId, overlapRange }
- */
 export declare function checkTrackContentsNoOverlap(track: Track): InvariantViolation[];
-/**
- * A TimelineClip.source.kind must match Track.kind per the compatibility table.
- * clip_source_track_kind_mismatch { trackId, clipId, sourceKind, trackKind }
- */
 export declare function checkClipSourceTrackKind(track: Track): InvariantViolation[];
 export declare function isSourceKindCompatible(trackKind: Track["kind"], sourceKind: TimelineClip["source"]["kind"]): boolean;
-/**
- * A TimelineClip with transitionIn must have a contiguous TimelineClip predecessor on the
- * same Track (no Gap, not first element).
- *
- * transition_no_predecessor { trackId, clipId }
- * transition_too_long       { trackId, clipId, transitionDuration, available }
- */
 export declare function checkTransitions(track: Track): InvariantViolation[];
-/**
- * For each TimelineClip with a media source carrying excludedRanges, verify:
- *   - each range has end > start
- *   - every range is within the source trim window (or [0, duration] when trim absent)
- *   - ranges are sorted and non-overlapping
- *   - clip.duration === (trimEnd - trimStart) - Σ excluded, within float tolerance (1e-3)
- *
- * Coordinate space: source coordinates (same as `trim`).
- *
- * excluded_range_invalid             { trackId, clipId, index, start, end }
- * excluded_range_out_of_bounds       { trackId, clipId, index, start, end, trimStart, trimEnd }
- * excluded_range_overlap             { trackId, clipId, index, start, prevEnd }
- * excluded_range_duration_mismatch   { trackId, clipId, expected, actual, trimSpan, totalExcluded }
- */
 export declare function checkExcludedRanges(track: Track): InvariantViolation[];
-/** Combined per-track invariants. */
-/**
- * A media clip's `duration` must equal its trimmed source span divided by its
- * playback rate — for clips that have NO excluded ranges.
- *
- * `checkExcludedRanges` computes exactly this relationship, but returns early on
- * `if (!ranges || ranges.length === 0) continue`, so it only ever runs for clips
- * that HAVE excluded ranges. A plainly-trimmed clip whose duration disagrees
- * with its trim is therefore unchecked. This closes that gap; the two together
- * cover every media clip.
- *
- * HONEST PROVENANCE: found while chasing a suspected corruption that turned out
- * not to be one. A project showed `duration 2.4` against `trim {0, 3.4}`, which
- * looked inconsistent until the clip's `excludedRanges` ([1.9, 2.9]) accounted
- * for exactly the difference. The composition was fine and the existing check
- * passed it correctly. No known production case violates THIS rule — it is here
- * because the coverage hole is real, not because a bug was seen through it.
- */
 export declare function checkClipDurationMatchesTrim(track: Track): InvariantViolation[];
 export declare function checkTrack(track: Track): InvariantViolation[];
-/** Combined per-composition invariants that live at the Track level. */
 export declare function checkTracks(composition: Composition): InvariantViolation[];