@cueframe/kernel 0.1.0 → 0.1.2

package/dist/_members/composition/projection/cardTokens.js

@@ -1,209 +0,0 @@
-/**
- * The card token contract, and the lint that enforces it at authoring time.
- *
- * A card's `tokens` map is projected to CSS custom properties by `cssLayoutVars`
- * (./brandKit): key `x` becomes `--cf-x`, so the authored html must read it as
- * `var(--cf-x)`. That one rule is the whole contract, and it was invisible on
- * every agent-facing surface until 2026-08-05.
- *
- * WHY THIS EXISTS. A real session authored 65 cards binding `tokens: {"--p":
- * …, "--f": …}` and reading them as `var(--p)` / `var(--f)`. Key `--p` projects
- * to `--cf---p`, so `var(--p)` was undefined, and CSS "invalid at
- * computed-value time" took over: `background: var(--p)` fell back to
- * transparent (the plate vanished, leaving only its box-shadow as a dark
- * smear) and `color: var(--f)` inherited black. `apply_composition` accepted
- * all 65 silently and returned 86 bytes; the render succeeded; the USER was the
- * first entity in the system to look at a pixel, 34 minutes and 3 renders in.
- *
- * ADVISORY only — same `(input) => string[]` contract as `detectNoAudioTrack`
- * (../audio/mixStaging). Reading an undefined custom property is legal CSS and
- * can be deliberate, so this never blocks an apply.
- *
- * KNOWN LIMIT: a `$brand:` token whose ref does not resolve is DROPPED by
- * `cssLayoutVars`, so `var(--cf-x)` can still be undefined at render even when
- * this lint passes. Catching that needs the org's resolved brand kit; the
- * checks here are deliberately kit-free so they cost nothing (no extra read) on
- * the apply path.
- */
-// EXTENSIONLESS, and that is load-bearing rather than style. This module is
-// reachable from `projection/index.ts`, which the Remotion BUNDLE pulls in
-// (Root.tsx → MainComposition → OverlayContent → cssLayoutVars), and the bake's
-// webpack resolver has no `.js → .ts` substitution: a `./brandKit.js` here
-// resolves against nothing and fails the desktop build at `bake:remotion` —
-// AFTER a clean tsc and a clean vitest run, because neither uses that resolver.
-// Same class as the Lambda bundle's extensionless-import requirement. Every
-// other relative import in this directory is extensionless; match them.
-import { resolveBrandRefsDeep } from "./brandKit";
-/**
- * The frame-driven vars `cardMotionVars` injects on EVERY card wrapper, on top
- * of the token vars. SSOT for the names — `packages/execution/render-entry/src/components/
- * cardMotion.ts` types its return against `CardMotionVarName`, so the two
- * cannot drift. The lint must treat these as always-defined or every
- * motion-authored card warns falsely.
- */
-export const CARD_MOTION_VAR_NAMES = [
-    "--cf-frame",
-    "--cf-t",
-    "--cf-fps",
-    "--cf-duration",
-    "--cf-progress",
-    "--cf-ease",
-    "--cf-enter",
-    "--cf-exit",
-];
-/** `var(--name` — group 2 is "," when the reference supplies a fallback. */
-const VAR_REF = /var\(\s*(--[A-Za-z0-9_-]+)\s*(,?)/g;
-/** `--name:` — a custom property DECLARED in the card's own CSS. */
-const VAR_DECL = /(--[A-Za-z0-9_-]+)\s*:/g;
-/** How many distinct names to name in one advisory before eliding. */
-const MAX_NAMED = 8;
-/**
- * Walk an arbitrary value tree and collect every card source in it. Structural
- * rather than op-typed on purpose: cards reach `apply_composition` through
- * `clip.add`, `clip.update` and `applyMotionPreset` alike, and a new op that
- * carries one is linted the day it lands with no change here.
- */
-function collectCards(value, nearestId, out) {
-    if (Array.isArray(value)) {
-        for (const v of value)
-            collectCards(v, nearestId, out);
-        return;
-    }
-    if (value === null || typeof value !== "object")
-        return;
-    const obj = value;
-    // A clip carries `id`; its `source` does not. Track the closest one seen so
-    // the advisory can point at a clip rather than an ordinal.
-    const id = typeof obj.id === "string" ? obj.id : nearestId;
-    if (obj.kind === "card" && typeof obj.html === "string") {
-        const tokens = {};
-        if (obj.tokens !== null && typeof obj.tokens === "object") {
-            for (const [k, v] of Object.entries(obj.tokens)) {
-                if (typeof v === "string")
-                    tokens[k] = v;
-            }
-        }
-        out.push({ html: obj.html, tokens, ...(id !== undefined ? { id } : {}) });
-        return; // a card source never nests another card
-    }
-    for (const v of Object.values(obj))
-        collectCards(v, id, out);
-}
-const list = (names) => {
-    const all = [...names];
-    const shown = all.slice(0, MAX_NAMED).map((n) => `\`${n}\``).join(", ");
-    return all.length > MAX_NAMED ? `${shown} (+${all.length - MAX_NAMED} more)` : shown;
-};
-const cards = (n) => `${n} card clip${n === 1 ? "" : "s"}`;
-/**
- * Lint every card in `value` (an ops array, a composition, a single clip — any
- * shape) and return zero, one or two advisory strings.
- *
- * Two distinct defects, because they need different fixes:
- *   `card_token_prefix`     — a tokens KEY that already starts with `--`, so it
- *                             double-prefixes to `--cf---p`. Zero false
- *                             positives; this is always a mistake.
- *   `card_token_unresolved` — html reads `var(--x)` that nothing defines. Only
- *                             fires when the name is not a `--cf-<tokens key>`,
- *                             not a motion var, not declared in the card's own
- *                             CSS, and the reference supplies no fallback.
- */
-/**
- * THE KIT-AWARE HALF, and the reason `detectUnresolvedCardTokens` cannot cover
- * it. That lint is deliberately kit-free so it costs no extra read on the apply
- * path, and its own header records the consequence: "a `$brand:` token whose ref
- * does not resolve is DROPPED by `cssLayoutVars`, so `var(--cf-x)` can still be
- * undefined at render even when this lint passes."
- *
- * That limit was cheap while every org had a brand kit. Signed out is now a
- * SUPPORTED state with no kit at all, so it stopped being an edge: on
- * 2026-08-16 every card in a composition rendered as unstyled black-on-nothing
- * text — 16px, top-left, no background — because each token was a `$brand:` ref
- * with nothing to resolve against, and nothing anywhere said so. The agent
- * looking at those stills concluded the card renderer "strips inline styles".
- *
- * Given the kit that will actually be used, this reports the card tokens that
- * will be DROPPED. Empty kit and empty result are different answers: a card with
- * literal values is fine without a kit.
- */
-export function detectDroppedBrandTokens(value, kit) {
-    const found = [];
-    collectCards(value, undefined, found);
-    if (found.length === 0)
-        return [];
-    const droppedKeys = new Set();
-    const droppedCards = new Set();
-    found.forEach((card, i) => {
-        const resolved = kit
-            ? resolveBrandRefsDeep(card.tokens, kit)
-            : card.tokens;
-        for (const [key, v] of Object.entries(resolved)) {
-            // `cssLayoutVars` emits a var only for a string that is no longer a ref;
-            // anything still `$brand:` is dropped, so `var(--cf-<key>)` is undefined.
-            if (typeof v === "string" && v.startsWith("$brand:")) {
-                droppedKeys.add(`--cf-${key}`);
-                droppedCards.add(card.id ?? `#${i + 1}`);
-            }
-        }
-    });
-    if (droppedKeys.size === 0)
-        return [];
-    return [
-        `card_brand_tokens_dropped — ${cards(droppedCards.size)} bind ${list(droppedKeys)} to a ` +
-            `\`$brand:\` reference that ${kit ? "this brand kit does not define" : "cannot resolve, because no brand kit is bound"}. ` +
-            `\`cssLayoutVars\` drops an unresolved ref, so those custom properties are absent at render and CSS ` +
-            `treats them as invalid at computed-value time: the card draws with browser defaults — 16px text, ` +
-            `transparent background — and looks like the styling was ignored. ` +
-            `${kit ? "Bind a key the kit defines" : "Bind a brand kit that defines them"}, or give each reference a ` +
-            `literal fallback: \`var(--cf-x, #fff)\`.`,
-    ];
-}
-export function detectUnresolvedCardTokens(value) {
-    const found = [];
-    collectCards(value, undefined, found);
-    if (found.length === 0)
-        return [];
-    const dashKeys = new Set();
-    const dashCards = new Set();
-    const missingVars = new Set();
-    const missingCards = new Set();
-    found.forEach((card, i) => {
-        const label = card.id ?? `#${i + 1}`;
-        const defined = new Set(CARD_MOTION_VAR_NAMES);
-        for (const key of Object.keys(card.tokens)) {
-            defined.add(`--cf-${key}`);
-            if (key.startsWith("--")) {
-                dashKeys.add(key);
-                dashCards.add(label);
-            }
-        }
-        // Custom properties the card declares for itself are satisfied by the card.
-        for (const m of card.html.matchAll(VAR_DECL))
-            defined.add(m[1]);
-        for (const m of card.html.matchAll(VAR_REF)) {
-            if (m[2] === ",")
-                continue; // `var(--x, fallback)` is a documented-legal pattern
-            if (defined.has(m[1]))
-                continue;
-            missingVars.add(m[1]);
-            missingCards.add(label);
-        }
-    });
-    const advisories = [];
-    if (dashKeys.size > 0) {
-        advisories.push(`card_token_prefix — ${cards(dashCards.size)} declare token key(s) ${list(dashKeys)} that ` +
-            `already begin with "--". A tokens key \`x\` is projected to the CSS custom property ` +
-            `\`--cf-x\`, so \`--p\` becomes \`--cf---p\` and the card's \`var(--p)\` resolves to ` +
-            `nothing. Drop the leading dashes — \`tokens: {"p": "#f00"}\` is read as \`var(--cf-p)\`.`);
-    }
-    if (missingVars.size > 0) {
-        advisories.push(`card_token_unresolved — ${cards(missingCards.size)} read ${list(missingVars)}, which ` +
-            `nothing defines: not a \`--cf-<tokens key>\`, not a card motion var, and not declared ` +
-            `in the card's own CSS. CSS treats an undefined custom property as "invalid at ` +
-            `computed-value time", so the property falls back silently — \`background\` to ` +
-            `transparent, \`color\` to inherited (usually black) — and the card renders broken ` +
-            `with no error. Bind it through \`tokens\` and read it as \`var(--cf-<key>)\`, or give ` +
-            `the reference a fallback: \`var(--x, #fff)\`.`);
-    }
-    return advisories;
-}