@cueframe/kernel 0.0.1

package/dist/_members/composition/graphics-plan/compile.js

@@ -0,0 +1,221 @@
+import { resolveBrandRefsDeep } from "../projection/brandKit.js";
+// Brand-ref leaves (see brandKit ResolvedBrandKit). Fonts MUST use `.family`.
+const B = {
+    textOnMedia: "$brand:colors.textOnMedia",
+    textOnAccent: "$brand:colors.textOnAccent",
+    textOnSurface: "$brand:colors.textOnSurface",
+    accent: "$brand:colors.accent",
+    overlay: "$brand:colors.overlay",
+    surface: "$brand:colors.surface",
+    fontHeading: "$brand:fonts.heading.family",
+    fontBody: "$brand:fonts.body.family",
+    motionEasing: "$brand:motion.easing",
+    motionEntrance: "$brand:motion.entrance",
+};
+function textColorRef(styleRole) {
+    return styleRole === "on-accent" ? B.textOnAccent : styleRole === "on-surface" ? B.textOnSurface : B.textOnMedia;
+}
+function fontRef(styleRole) {
+    return styleRole === "body" ? B.fontBody : B.fontHeading;
+}
+/** Font px from a box's height so the text FITS its box (leaves line room). */
+function fontPx(boxH, frameH, fill = 0.62) {
+    return Math.round(Math.max(16, Math.min(240, boxH * frameH * fill)));
+}
+/** Bounding box of the front element boxes (clear of the face iff each is). */
+function unionBox(rects) {
+    const x = Math.min(...rects.map((r) => r.x));
+    const y = Math.min(...rects.map((r) => r.y));
+    const x2 = Math.max(...rects.map((r) => r.x + r.w));
+    const y2 = Math.max(...rects.map((r) => r.y + r.h));
+    return { x, y, w: x2 - x, h: y2 - y };
+}
+/** 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 function parseStatValue(raw) {
+    const m = raw.trim().match(/^(\D*)(\d[\d,]*(?:\.\d+)?)(.*)$/);
+    if (!m)
+        return null;
+    const value = Number(m[2].replace(/,/g, ""));
+    if (!Number.isFinite(value))
+        return null;
+    return { value, prefix: m[1].trim(), suffix: m[3] };
+}
+const asSource = (s) => s;
+/** True iff two rects overlap. */
+const overlaps = (a, b) => a.x < b.x + b.w && a.x + a.w > b.x && a.y < b.y + b.h && a.y + a.h > b.y;
+/** Compile one beat (its content role + solved layout) into overlay clips. */
+export function compileBeat(beat, layout, _motion, opts = {}) {
+    const prefix = opts.idPrefix ?? "gfx";
+    const frameH = layout.frame.h;
+    const kit = opts.brandKit;
+    // Resolve nested $brand: refs to literals at compile time when a kit is given
+    // (the render inflater only does top-level). Identity passthrough otherwise.
+    const finalize = (s) => kit ? { ...s, params: resolveBrandRefsDeep(s.params, kit) } : s;
+    const src = (s) => asSource(finalize(s));
+    // The behind-subject hero (heroText) — RE-ENABLED 2026-07-29. It was
+    // denylisted 2026-07-08 for "matte compositing desyncs lip movement"; the
+    // root cause was the matte bake re-timing the co-view at average fps (fixed
+    // by the CFR timing invariant — plan 2026-07-28-cfr-timing-invariant), not
+    // this emission. heroText is world-locked (zPlane, no authored anchor) so
+    // the silhouette gate places it — not the plan. Cross-beat duplicate
+    // protection (the OTHER disable reason: an agent plan authored two
+    // overlapping hero beats 0.14s apart) lives in compileGraphicsPlan.
+    // Text is REQUIRED: heroText's schema is min(1), and a Copy.headline of ""
+    // is schema-legal upstream (the solver omits `text` for falsy copy) — an
+    // unguarded emission would compile a clip the write boundary/render rejects
+    // for the whole plan. A textless hero drops out like other non-emitted roles.
+    const hero = layout.elements.find((e) => e.z === "behind-subject" && e.text?.trim());
+    // Only TEXT-emitting front roles composite here; logo/accent-shape/backdrop
+    // are non-text decoration (P1 skips them rather than emitting a blank title).
+    const front = layout.elements.filter((e) => e.z !== "behind-subject" && e.role !== "logo" && e.role !== "accent-shape" && e.role !== "backdrop");
+    const clips = [];
+    if (hero) {
+        clips.push({
+            id: `${prefix}-${beat.id}-hero`,
+            startTime: beat.atSec,
+            duration: beat.durSec,
+            kind: "overlay",
+            source: src({
+                kind: "overlay",
+                primitiveId: "heroText",
+                params: { text: hero.text, fontSizePct: 14, textColor: B.textOnMedia, fontFamily: B.fontHeading, entrance: B.motionEntrance, easing: B.motionEasing },
+                zPlane: "behind-subject",
+            }),
+        });
+    }
+    if (front.length === 0)
+        return clips;
+    const region = unionBox(front.map((e) => e.box));
+    // GUARD: the union of individually-clear boxes could still span the face (a
+    // split layout). If it does, skip the front graphic rather than composite it
+    // OVER the speaker — the invariant holds even when the solver doesn't stack
+    // contiguously (e.g. a future agent-proposed layout).
+    if (layout.keepOut.some((ko) => overlaps(region, ko)))
+        return clips;
+    // A text graphic MUST have a primary line (headline/value). No fallback to
+    // front[0] — a beat with only a subtitle is malformed; fail loud.
+    const head = front.find((e) => e.role === "headline" || e.role === "value");
+    if (!head) {
+        throw new Error(`graphics-plan: beat "${beat.id}" (role ${beat.role}) has front elements but no headline/value line — malformed copy.`);
+    }
+    // sub must be a DISTINCT element from head (else a subtitle-only beat would
+    // render the same string twice).
+    const sub = front.find((e) => (e.role === "sublabel" || e.role === "label") && e !== head);
+    const headFont = fontPx(head.box.h, frameH);
+    // Subtitle never larger than the headline (hierarchy), regardless of box math.
+    const subFont = sub ? Math.min(fontPx(sub.box.h, frameH), Math.round(headFont * 0.8)) : undefined;
+    const base = { id: `${prefix}-${beat.id}`, startTime: beat.atSec, duration: beat.durSec, kind: "overlay", region };
+    const titleSource = (styleRole) => ({
+        kind: "overlay",
+        primitiveId: "cinematic-title",
+        params: {
+            text: head.text ?? "",
+            ...(sub?.text ? { subtitle: sub.text } : {}),
+            tokens: { fontSize: headFont, ...(subFont ? { subtextFontSize: subFont } : {}), textColor: textColorRef(styleRole), accentColor: B.accent, fontFamily: fontRef(styleRole) },
+        },
+    });
+    switch (beat.role) {
+        case "title-card":
+            clips.push({ ...base, source: src(titleSource(head.styleRole)) });
+            break;
+        case "lower-third":
+            clips.push({
+                ...base,
+                source: src({
+                    kind: "overlay",
+                    primitiveId: "lower-third",
+                    params: {
+                        text: head.text ?? "",
+                        ...(sub?.text ? { subtitle: sub.text } : {}),
+                        tokens: { fontSize: headFont, ...(subFont ? { subtitleFontSize: subFont } : {}), textColor: B.textOnMedia, accentColor: B.accent, backgroundColor: B.overlay, fontFamily: B.fontBody },
+                    },
+                }),
+            });
+            break;
+        case "stat": {
+            const parsed = head.text ? parseStatValue(head.text) : null;
+            if (parsed) {
+                clips.push({
+                    ...base,
+                    source: src({
+                        kind: "overlay",
+                        primitiveId: "stat-counter",
+                        params: { value: parsed.value, ...(parsed.prefix ? { prefix: parsed.prefix } : {}), ...(parsed.suffix ? { suffix: parsed.suffix } : {}), ...(sub?.text ? { label: sub.text } : {}), accentColor: B.accent },
+                    }),
+                });
+            }
+            else {
+                // A stat REQUIRES a leading number — no silent degrade to a title card.
+                throw new Error(`graphics-plan: beat "${beat.id}" role "stat" has non-numeric value "${head.text}" — a stat needs a leading number (e.g. "5 yrs", "100%", "498").`);
+            }
+            break;
+        }
+        case "pull-quote":
+            clips.push({ ...base, source: src({ kind: "overlay", primitiveId: "quote-card", params: { text: head.text ?? "", ...(sub?.text ? { subtext: sub.text } : {}), accentColor: B.accent } }) });
+            break;
+        case "enumeration":
+        case "sequence":
+        case "comparison":
+            // The ARGUMENT roles are DESIGNER-AUTHORED, by design. There is no deterministic
+            // role→primitive mapping for them and there should not be: an `enumeration` might be
+            // three badges, a numbered list or a build-on-reveal, and a `sequence` might be
+            // `reasoning-trace`, `tool-call-stack` or a bespoke component — that choice is the
+            // designer's job, made with eyes on the frame and the whole catalog in hand.
+            //
+            // This deterministic FC5 compiler was DEMOTED to critics in any case (director.ts: "they
+            // no longer COMPILE the design") and `compilePlanGraphics` has no live callers. It is kept
+            // for an optional deterministic seed. Failing loud HERE — rather than silently rendering a
+            // title card — is the honest behaviour if it is ever re-promoted.
+            throw new Error(`graphics-plan: beat "${beat.id}" role "${beat.role}" is a DESIGNER-AUTHORED argument role ` +
+                `(enumeration / sequence / comparison). It has no deterministic primitive mapping by ` +
+                `design — the designer picks the component from the catalog or writes one. This ` +
+                `compiler only handles the text-shaped roles.`);
+        default:
+            // hero/logo-tag never reach here (no front text elements); any role that
+            // does is unhandled — fail loud instead of silently rendering a title.
+            throw new Error(`graphics-plan: beat "${beat.id}" role "${beat.role}" reached the compiler with front text but no handler.`);
+    }
+    return clips;
+}
+/** Compile a whole GraphicsPlan (all beats) into overlay clips. */
+export function compileGraphicsPlan(plan, opts = {}) {
+    const motionByBeat = new Map(plan.motions.map((m) => [m.beatId, m]));
+    const layoutByBeat = new Map(plan.layouts.map((l) => [l.beatId, l]));
+    const clips = [];
+    for (const beat of plan.content.beats) {
+        const layout = layoutByBeat.get(beat.id);
+        if (!layout)
+            continue;
+        clips.push(...compileBeat(beat, layout, motionByBeat.get(beat.id), opts));
+    }
+    return dedupeOverlappingHeroes(clips);
+}
+/**
+ * MECHANICAL guard for the hero param-snag that co-motivated the 2026-07-08
+ * disable: the 2026-07-07 prod e2e produced TWO overlapping heroText beats
+ * (7.93s & 8.07s) — stacked display phrases rendering over each other. One
+ * hero at a time is the grammar ("ration it hard: ONE hero beat per clip"),
+ * so enforce it here rather than trusting the planner prompt: when two
+ * compiled heroText windows overlap in time, the EARLIER one wins and the
+ * later duplicate is dropped. Non-overlapping heroes (distinct moments in a
+ * long film) all survive.
+ */
+function dedupeOverlappingHeroes(clips) {
+    const isHero = (c) => c.source?.primitiveId === "heroText";
+    const heroes = clips
+        .filter(isHero)
+        .sort((a, b) => a.startTime - b.startTime || a.id.localeCompare(b.id));
+    const dropped = new Set();
+    let lastEnd = -Infinity;
+    for (const h of heroes) {
+        if (h.startTime < lastEnd) {
+            dropped.add(h.id);
+            continue;
+        }
+        lastEnd = h.startTime + h.duration;
+    }
+    return dropped.size === 0 ? clips : clips.filter((c) => !dropped.has(c.id));
+}

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

@@ -0,0 +1,11 @@
+/**
+ * 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";
+export * from "./compile.js";
+export { instantiateMotif, MotifInstantiationError } from "./instantiateMotif.js";
+export type { ReproducedMotif } from "./instantiateMotif.js";

package/dist/_members/composition/graphics-plan/index.js

@@ -0,0 +1,10 @@
+/**
+ * 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";
+export * from "./compile.js";
+export { instantiateMotif, MotifInstantiationError } from "./instantiateMotif.js";

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

@@ -0,0 +1,51 @@
+/**
+ * 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: {
+        kind: "card";
+        html: string;
+        tokens?: Record<string, string>;
+    } | {
+        kind: "overlay";
+        primitiveId: string;
+        params?: Record<string, unknown>;
+    } | {
+        kind: "component";
+        componentId: string;
+        props?: Record<string, unknown>;
+    };
+    motion?: {
+        preset: string;
+        enterMs?: number;
+        exitMs?: number;
+        staggerMs?: number;
+    };
+    zone?: {
+        x: number;
+        y: number;
+        w: number;
+        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/instantiateMotif.js

@@ -0,0 +1,44 @@
+/**
+ * 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 class MotifInstantiationError extends Error {
+}
+const SLOT_RE = /(<[^>]*\bdata-slot="([^"]+)"[^>]*>)([\s\S]*?)(<\/)/g;
+const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+/** Fill a reproduced card skin's slots with the graphic's copy. Throws
+ *  MotifInstantiationError on any deviation from the convention. */
+export function instantiateMotif(motif, copy) {
+    if (motif.coverage !== "reproduced") {
+        throw new MotifInstantiationError(`motif coverage is '${motif.coverage}' — only 'reproduced' skins instantiate; approximated/skipped motifs go to the designer`);
+    }
+    if (motif.body.kind !== "card") {
+        throw new MotifInstantiationError(`v1 instantiates card bodies only (got '${motif.body.kind}')`);
+    }
+    const seen = new Set();
+    const html = motif.body.html.replace(SLOT_RE, (_m, open, slot, inner, close) => {
+        if (/[<>]/.test(inner)) {
+            throw new MotifInstantiationError(`slot '${slot}' contains nested markup — skins must keep slots text-only`);
+        }
+        if (!(slot in copy)) {
+            throw new MotifInstantiationError(`slot '${slot}' not filled — copy carries [${Object.keys(copy).join(", ")}]`);
+        }
+        seen.add(slot);
+        return `${open}${escapeHtml(copy[slot])}${close}`;
+    });
+    for (const key of Object.keys(copy)) {
+        if (!seen.has(key)) {
+            throw new MotifInstantiationError(`copy has no slot '${key}' in the skin`);
+        }
+    }
+    return { html, ...(motif.body.tokens ? { tokens: motif.body.tokens } : {}) };
+}

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

@@ -0,0 +1,19 @@
+/**
+ * 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;

package/dist/_members/composition/graphics-plan/motion.js

@@ -0,0 +1,66 @@
+/**
+ * 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 { GRAPHICS_PLAN_VERSION, } from "./schemas.js";
+/** Per-role entrance intent. Values (the number to remember) count up; supporting
+ *  text rises; the primary headline reveals; decoration fades. */
+const ENTER = {
+    headline: { type: "reveal", atMs: 0, durMs: 600, ease: "spring" },
+    value: { type: "count-up", atMs: 0, durMs: 800, ease: "spring" },
+    label: { type: "rise", atMs: 0, durMs: 500, ease: "ease-out" },
+    sublabel: { type: "fade", atMs: 0, durMs: 500, ease: "ease-out" },
+    logo: { type: "fade", atMs: 0, durMs: 400, ease: "ease-out" },
+    "accent-shape": { type: "wipe", atMs: 0, durMs: 500, ease: "ease-out" },
+    backdrop: { type: "fade", atMs: 0, durMs: 300, ease: "linear" },
+};
+/** Per-element entrance stagger (ms), applied in element order. */
+const STAGGER_MS = 120;
+/**
+ * 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 function planMotion(layout, durSec) {
+    const beatMs = Math.max(0, durSec * 1000);
+    const exitDur = Math.min(350, beatMs * 0.2);
+    const exitAt = Math.max(0, beatMs - exitDur);
+    const n = layout.elements.length;
+    // Fit ALL entrances within [0, exitAt]: an entrance must finish before the
+    // fade starts (on a short beat the nominal 800ms count-up + stagger would
+    // otherwise run past the exit or start after the beat ends). Scale the
+    // nominal durations + stagger by whatever factor makes the last entrance land
+    // by exitAt. `scale === 0` (zero-length beat) yields instantaneous entrances.
+    let nominalMaxEnd = 0;
+    layout.elements.forEach((el, i) => {
+        nominalMaxEnd = Math.max(nominalMaxEnd, i * STAGGER_MS + ENTER[el.role].durMs);
+    });
+    const scale = nominalMaxEnd > 0 && nominalMaxEnd > exitAt ? exitAt / nominalMaxEnd : 1;
+    const elements = layout.elements.map((el, i) => {
+        const base = ENTER[el.role];
+        const atMs = Math.round(i * STAGGER_MS * scale);
+        const durMs = Math.max(1, Math.round(base.durMs * scale));
+        const enter = { ...base, atMs, durMs };
+        const me = { elId: el.elId, enter };
+        // Emphasis pulse only if it fully FITS between the entrance and the exit
+        // fade (start AND end before exitAt — a pulse overrunning the fade jitters).
+        if (n > 0 && (el.role === "value" || el.role === "headline")) {
+            const emphAt = atMs + durMs + Math.round(150 * scale);
+            const emphDur = Math.round(300 * scale);
+            if (emphDur > 0 && emphAt + emphDur <= exitAt)
+                me.emphasis = { type: "pulse", atMs: emphAt, durMs: emphDur };
+        }
+        if (exitDur > 0)
+            me.exit = { type: "fade", atMs: exitAt, durMs: exitDur };
+        return me;
+    });
+    return { version: GRAPHICS_PLAN_VERSION, beatId: layout.beatId, elements };
+}