@cueframe/kernel 0.0.1

package/dist/_members/composition/fixtures/vaayaErrored.js

@@ -0,0 +1,203 @@
+/**
+ * Compositions authored by the Vaaya 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` (services/convex/api/openapi/validate.ts)
+ * 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 const vaayaErroredCompositionV1 = {
+    v: 1,
+    format: { aspectRatio: "16:9", fps: 30, resolution: "fhd" },
+    tracks: [
+        {
+            id: "vid",
+            kind: "video",
+            contents: [
+                {
+                    id: "title_clip",
+                    startTime: 0,
+                    duration: 4,
+                    source: {
+                        kind: "media",
+                        mediaId: "jh76np6j93brgbm96f6maa0tw988x6v0",
+                        trim: { start: 0, end: 4 },
+                        kenBurns: "in",
+                    },
+                },
+                {
+                    id: "portrait_seg1",
+                    startTime: 4,
+                    duration: 8,
+                    source: {
+                        kind: "media",
+                        mediaId: "jh71xe5ygsakx664syeq3x8ys588x0gx",
+                        trim: { start: 0, end: 8 },
+                        reframe: {
+                            segments: [
+                                { startSec: 4, endSec: 12, focus: { mode: "frame-center" }, zoom: 0.85, ease: { in: 0.8, out: 0.8 } },
+                            ],
+                        },
+                    },
+                },
+                {
+                    id: "portrait_seg2",
+                    startTime: 12,
+                    duration: 7,
+                    source: {
+                        kind: "media",
+                        mediaId: "jh71xe5ygsakx664syeq3x8ys588x0gx",
+                        trim: { start: 8, end: 15 },
+                        reframe: {
+                            segments: [
+                                { startSec: 12, endSec: 19, focus: { mode: "frame-center" }, zoom: 0.75, ease: { in: 0.6, out: 0.6 } },
+                            ],
+                        },
+                    },
+                },
+                {
+                    id: "portrait_seg3",
+                    startTime: 19,
+                    duration: 8,
+                    source: {
+                        kind: "media",
+                        mediaId: "jh71xe5ygsakx664syeq3x8ys588x0gx",
+                        trim: { start: 15, end: 23 },
+                        reframe: {
+                            segments: [
+                                { startSec: 19, endSec: 27, focus: { mode: "frame-center" }, zoom: 0.65, ease: { in: 0.6, out: 0.6 } },
+                            ],
+                        },
+                    },
+                },
+                {
+                    id: "usecases_hold",
+                    startTime: 27,
+                    duration: 4,
+                    source: {
+                        kind: "media",
+                        mediaId: "jh71xe5ygsakx664syeq3x8ys588x0gx",
+                        trim: { start: 23, end: 27 },
+                        kenBurns: "in",
+                    },
+                },
+                {
+                    id: "outro_title",
+                    startTime: 31,
+                    duration: 3.5,
+                    source: { kind: "media", mediaId: "jh76np6j93brgbm96f6maa0tw988x6v0", trim: { start: 0, end: 3.5 } },
+                },
+            ],
+        },
+        {
+            id: "narr",
+            kind: "audio",
+            contents: [
+                { id: "vo", startTime: 0, duration: 33.9, source: { kind: "media", mediaId: "jh72h9exp2zbv0kr5p214gq87h88xe2p", volume: 1 } },
+            ],
+        },
+        {
+            id: "music",
+            kind: "audio",
+            contents: [
+                {
+                    id: "bed",
+                    startTime: 0,
+                    duration: 34.5,
+                    source: { kind: "media", mediaId: "jh74ahb6petnh4wrmhmpmcv0cd88w227", volume: 0.12, loop: true, fadeOutMs: 800 },
+                },
+            ],
+        },
+    ],
+};
+/**
+ * Second attempt — Vaaya'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 const vaayaErroredCompositionV2 = {
+    v: 1,
+    format: { aspectRatio: "16:9", fps: 30, resolution: "fhd" },
+    tracks: [
+        {
+            id: "video",
+            kind: "video",
+            contents: [
+                {
+                    id: "title_in",
+                    startTime: 0,
+                    duration: 4,
+                    source: {
+                        kind: "media",
+                        mediaId: "jh76np6j93brgbm96f6maa0tw988x6v0",
+                        trim: { start: 0, end: 4 },
+                        kenBurns: "in",
+                    },
+                },
+                {
+                    id: "portrait_section",
+                    startTime: 4,
+                    duration: 27,
+                    source: {
+                        kind: "media",
+                        mediaId: "jh71xe5ygsakx664syeq3x8ys588x0gx",
+                        trim: { start: 0, end: 27 },
+                        reframe: {
+                            segments: [
+                                { startSec: 4, endSec: 12, focus: { mode: "frame-center" }, zoom: 0.85, ease: { in: 0.8, out: 0.8 } },
+                                { startSec: 12, endSec: 19, focus: { mode: "frame-center" }, zoom: 0.75, ease: { in: 0.6, out: 0.6 } },
+                                { startSec: 19, endSec: 27, focus: { mode: "frame-center" }, zoom: 0.65, ease: { in: 0.6, out: 0.6 } },
+                            ],
+                        },
+                    },
+                },
+                {
+                    id: "usecases_hold",
+                    startTime: 27,
+                    duration: 4,
+                    source: {
+                        kind: "media",
+                        mediaId: "jh71xe5ygsakx664syeq3x8ys588x0gx",
+                        trim: { start: 0, end: 4 },
+                        kenBurns: "in",
+                    },
+                },
+                {
+                    id: "outro",
+                    startTime: 31,
+                    duration: 3.5,
+                    source: { kind: "media", mediaId: "jh76np6j93brgbm96f6maa0tw988x6v0", trim: { start: 0, end: 3.5 } },
+                },
+            ],
+        },
+        {
+            id: "narration",
+            kind: "audio",
+            contents: [
+                { id: "vo", startTime: 0, duration: 33.9, source: { kind: "media", mediaId: "jh72h9exp2zbv0kr5p214gq87h88xe2p", volume: 1 } },
+            ],
+        },
+        {
+            id: "music",
+            kind: "audio",
+            contents: [
+                {
+                    id: "bed",
+                    startTime: 0,
+                    duration: 34.5,
+                    source: { kind: "media", mediaId: "jh74ahb6petnh4wrmhmpmcv0cd88w227", volume: 0.12, loop: true, fadeOutMs: 800 },
+                },
+            ],
+        },
+    ],
+};

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

@@ -0,0 +1,68 @@
+/**
+ * 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/fonts.js

@@ -0,0 +1,162 @@
+/**
+ * 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 `services/convex/api/routes/components.ts` (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 const VENDORED_FONT_FAMILIES = [
+    "Inter",
+    "Space Mono",
+    "Montserrat",
+    "Roboto",
+    "Poppins",
+    "Oswald",
+    "Playfair Display",
+    "Bebas Neue",
+    "Instrument Serif",
+    "National Park",
+    "Bricolage Grotesque",
+    "Schibsted Grotesk",
+];
+/**
+ * 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 const ALIASED_FONT_FAMILIES = ["Georgia"];
+const AVAILABLE_LOWER = new Set([...VENDORED_FONT_FAMILIES, ...ALIASED_FONT_FAMILIES].map((f) => f.toLowerCase()));
+/** True when the render sandbox can rasterize this exact family name. */
+export function isAvailableFontFamily(family) {
+    return AVAILABLE_LOWER.has(family.trim().replace(/^['"]|['"]$/g, "").toLowerCase());
+}
+/** Split a CSS `font-family` value into its families, quotes stripped. */
+export function parseFontStack(value) {
+    return value
+        .split(",")
+        .map((f) => f.trim().replace(/^['"]|['"]$/g, "").trim())
+        .filter(Boolean);
+}
+/**
+ * `font-family: <stack>` inside authored CSS — a card's inline `style="…"` or a
+ * `<style>` block. Families are usually QUOTED (`'Baloo 2'`), so the value must
+ * admit quotes while still stopping at the enclosing attribute's delimiter:
+ * each family is a quoted run or a bare run, and the lazy `+?` stops at the
+ * first real terminator (`;`, `}`, a closing `"`, or end of string).
+ */
+const FONT_FAMILY_CSS = /font-family\s*:\s*((?:'[^']*'|"[^"]*"|[^;}"'])+?)\s*(?:;|}|"|$)/gi;
+/** A `fontFamily`-ish object KEY — caption style, overlay params, component props. */
+const FONT_FAMILY_KEY = /fontfamily$/i;
+/** How many distinct families to name before eliding. */
+const MAX_NAMED = 6;
+/**
+ * Collect every font stack a composition (or ops array, or clip) requests.
+ * Structural rather than schema-typed: families arrive through
+ * `captions.style.fontFamily`, `captions.style.emphasisFontFamily`, a card's
+ * html CSS, a card `tokens.fontFamily`, overlay `params.fontFamily` and
+ * component `props.fontFamily` alike, and a new carrier is covered on arrival.
+ */
+function collectFontStacks(value, out) {
+    if (Array.isArray(value)) {
+        for (const v of value)
+            collectFontStacks(v, out);
+        return;
+    }
+    if (value === null || typeof value !== "object")
+        return;
+    for (const [k, v] of Object.entries(value)) {
+        if (typeof v === "string") {
+            if (FONT_FAMILY_KEY.test(k))
+                out.push(v);
+            // Authored markup/CSS carries the request inline, not as a field. This is
+            // the case the toddler-parks session hit — the fonts were in card html.
+            for (const m of v.matchAll(FONT_FAMILY_CSS))
+                out.push(m[1]);
+            continue;
+        }
+        collectFontStacks(v, out);
+    }
+}
+/**
+ * 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 function detectUnavailableFonts(value) {
+    const stacks = [];
+    collectFontStacks(value, stacks);
+    if (stacks.length === 0)
+        return [];
+    const offenders = new Map(); // primary family → stacks requesting it
+    for (const raw of stacks) {
+        if (raw.includes("$brand:"))
+            continue; // unresolved ref, not a family name
+        const families = parseFontStack(raw);
+        if (families.length === 0)
+            continue;
+        // A dynamic value (`fontFamily: ${x}`) cannot be classified statically.
+        if (families.some((f) => f.includes("${")))
+            continue;
+        if (families.some(isAvailableFontFamily))
+            continue;
+        offenders.set(families[0], (offenders.get(families[0]) ?? 0) + 1);
+    }
+    if (offenders.size === 0)
+        return [];
+    const names = [...offenders.keys()];
+    const shown = names.slice(0, MAX_NAMED).map((n) => `\`${n}\``).join(", ");
+    const elided = names.length > MAX_NAMED ? ` (+${names.length - MAX_NAMED} more)` : "";
+    const requests = [...offenders.values()].reduce((a, b) => a + b, 0);
+    return [
+        `font_not_available — ${requests} font request${requests === 1 ? "" : "s"} name ${shown}` +
+            `${elided}, and nothing else in those stacks is vendored either. Only the vendored faces ` +
+            `are guaranteed present in the render, so naming a family alone gets you the generic ` +
+            `fallback (Liberation Sans) — no error, just the wrong typeface. ` +
+            `Guaranteed: ${VENDORED_FONT_FAMILIES.join(", ")} (plus Georgia). Note that putting the ` +
+            `family on a brand kit does NOT make it available — brand fonts resolve against the same ` +
+            `vendored set.`,
+    ];
+}

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

@@ -0,0 +1,43 @@
+/**
+ * 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;
+    suffix: 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[];