@cueframe/kernel 0.0.1

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

@@ -0,0 +1,482 @@
+/**
+ * BrandKit cascade — resolve a sparse BrandKit into a fully-materialized
+ * ResolvedBrandKit by applying the derivation table from data-model.md
+ * § BrandKit.
+ *
+ * Pure function. No I/O. Same input → same output.
+ *
+ * The wire BrandKit stays sparse on disk — only the tokens the user
+ * explicitly set are persisted. The derivation table is what makes
+ * `colors.textMuted = colorMix(text, background, 40%)` happen at
+ * resolve time without forcing every kit to enumerate every token.
+ *
+ * Resolution always runs against a composition-format width so the
+ * width-anchored derivations (spacing.base, sizing.fontSizeHeading,
+ * etc.) get concrete pixel values. Callers that don't have a
+ * Composition in scope pass the format's render width directly.
+ *
+ * Failure mode: never throws on missing tokens. Every derivation
+ * either has a direct fallback (the primitive's
+ * PrimitiveRegistryEntry.tokens[].fallback) or a width-anchored
+ * default. The brand cascade's job is to NEVER crash the render —
+ * "loud failures at boundaries" applies to BrandKit PUT-time
+ * validation (rejecting invalid easing, etc.), not to render-time
+ * resolution. See data-model.md § BrandKit "every declared token
+ * carries a primitive-side fallback."
+ *
+ * Reserved (per data-model.md § Reserved → specializes): when a
+ * BrandKit carries `specializes: parentKitId`, resolve() walks the
+ * chain bottom-up before applying the derivation table. Today's
+ * BrandKit shape does NOT carry `specializes`; reservation noted so
+ * this function's signature stays compatible when the field lands.
+ */
+import { deriveContrastSafe, clampToFloor, FLOORS } from "@cueframe/brand-derivation";
+/**
+ * Default overlay-asset normalization values. The wire kit stays sparse; the
+ * cascade fills these so downstream render/compose consume a concrete shape.
+ * data-model.md § BrandKit only specs `logo: { src, alt? }` (no placement/
+ * sizePct) and does NOT spec intro/outro/watermark at all — these defaults are
+ * chosen here (corner anchor, subtle size, 1.5s card bumper, half-opacity mark).
+ */
+const LOGO_DEFAULT_PLACEMENT = "br";
+const LOGO_DEFAULT_SIZE_PCT = 8;
+const INTRO_OUTRO_CARD_DEFAULT_MS = 1500;
+const WATERMARK_DEFAULT_OPACITY = 0.5;
+const WATERMARK_DEFAULT_PLACEMENT = "br";
+/**
+ * Normalize an intro/outro bumper. A `card` with no `durationMs` defaults to
+ * 1.5s; a `video`'s length governs its own duration, so no default is forced
+ * (and a video without `src` carries through — fail-loud belongs at PUT time).
+ */
+function resolveIntroOutro(io) {
+    if (!io)
+        return undefined;
+    const durationMs = io.durationMs ?? (io.kind === "card" ? INTRO_OUTRO_CARD_DEFAULT_MS : undefined);
+    return {
+        kind: io.kind,
+        ...(io.src != null ? { src: io.src } : {}),
+        ...(io.title != null ? { title: io.title } : {}),
+        ...(io.subtitle != null ? { subtitle: io.subtitle } : {}),
+        ...(durationMs != null ? { durationMs } : {}),
+    };
+}
+/**
+ * Resolve a sparse BrandKit against a composition's render width.
+ * The width drives the spacing + sizing derivations (font sizes
+ * scale to the canvas, not absolute pixels).
+ */
+export function resolveBrandKit(kit, compositionWidth) {
+    // ── Colors ─────────────────────────────────────────────────────
+    // deriveContrastSafe applies a FORWARD-ONLY APCA floor: a legible brand is
+    // returned unchanged, a hostile one is clamped UP to the body floor over its
+    // own background (never lowered). `safe.text` is the floor-safe body color;
+    // captionFg/captionScrim is an unconditional caption plate; captionFg doubles
+    // as textOnMedia (legible text over arbitrary media via the scrim plate).
+    // primary/secondary fall back to accent (per derivation table).
+    // textMuted = colorMix(text, background, 40%) — a DE-EMPHASIS derivation
+    // (faded toward background), computed over the contrast-safe base so it
+    // inherits the floor's correction. (deriveContrastSafe's own `textMuted`
+    // only enforces the non-body floor and does NOT mute — for any legible brand
+    // it collapses to `text`, which is not what this token is for.)
+    // border = colorMix(text, background, 15%) — sharper, more visible.
+    const safe = deriveContrastSafe({
+        background: kit.colors.background,
+        text: kit.colors.text,
+        accent: kit.colors.accent,
+    });
+    const colors = {
+        primary: kit.colors.primary ?? kit.colors.accent,
+        secondary: kit.colors.secondary ?? kit.colors.accent,
+        accent: kit.colors.accent,
+        background: safe.background,
+        text: safe.text,
+        // De-emphasis mix faded toward background, RE-CLAMPED to the non-body floor:
+        // for a hostile (near-floor) brand the 40% fade can drop below Lc60, so the
+        // clamp forward-corrects it back up to legibility. For a legible brand the
+        // mix already clears the floor and the clamp is a no-op.
+        textMuted: kit.colors.textMuted ??
+            clampToFloor(colorMix(safe.text, safe.background, 0.4), safe.background, FLOORS.nonBody),
+        border: kit.colors.border ?? colorMix(safe.text, safe.background, 0.15),
+        textOnMedia: safe.captionFg,
+        // Tier-2 core: author override wins, else the contrast-safe derived value.
+        surface: kit.colors.surface ?? safe.surface,
+        card: kit.colors.card ?? safe.card,
+        gridLine: kit.colors.gridLine ?? safe.gridLine,
+        accentMuted: kit.colors.accentMuted ?? safe.accentMuted,
+        textOnAccent: kit.colors.textOnAccent ?? safe.textOnAccent,
+        textOnSurface: kit.colors.textOnSurface ?? safe.textOnSurface,
+    };
+    // ── Fonts ──────────────────────────────────────────────────────
+    // body falls back to heading; caption falls back to body, then heading.
+    const fonts = {
+        heading: kit.fonts.heading,
+        body: kit.fonts.body ?? kit.fonts.heading,
+        caption: kit.fonts.caption ?? kit.fonts.body ?? kit.fonts.heading,
+    };
+    // ── Spacing (width-anchored) ───────────────────────────────────
+    const spacing = {
+        base: kit.spacing?.base ?? compositionWidth * 0.03,
+        lg: kit.spacing?.lg ?? compositionWidth * 0.06,
+        sm: kit.spacing?.sm ?? compositionWidth * 0.015,
+    };
+    // ── Sizing (width-anchored) ────────────────────────────────────
+    const sizing = {
+        fontSizeHeading: kit.sizing?.fontSizeHeading ?? compositionWidth * 0.06,
+        fontSizeBody: kit.sizing?.fontSizeBody ?? compositionWidth * 0.035,
+        fontSizeLabel: kit.sizing?.fontSizeLabel ?? compositionWidth * 0.025,
+        borderRadius: kit.sizing?.borderRadius ?? compositionWidth * 0.01,
+    };
+    // ── Motion ─────────────────────────────────────────────────────
+    // Defaults mirror the primitives' calibrated fallbacks so an un-authored kit
+    // renders identically to today (entrance off; stagger/exit = Captions defaults).
+    const motion = {
+        duration: kit.motion?.duration ?? 200,
+        easing: kit.motion?.easing ?? "ease-out",
+        entrance: kit.motion?.entrance ?? "none",
+        staggerMs: kit.motion?.staggerMs ?? 90,
+        exitMs: kit.motion?.exitMs ?? 0,
+    };
+    // ── Caption ────────────────────────────────────────────────────
+    // Caption legibility is an UNCONDITIONAL APCA floor. scrim is the opaque
+    // plate composited behind caption text over media; captionFg clears the body
+    // floor over that scrim by construction. An authored emphasis color
+    // (captionProfile.emphasisColor) is CLAMPED to the body floor over that scrim
+    // (task #26) — a creator-set accent that fails APCA is forward-corrected up to
+    // legibility, never rendered below the floor. Absent an override, the
+    // contrast-safe captionFg is the default.
+    // The base caption face: the creator's explicit caption font, else the
+    // resolved caption font family (fonts.caption → body → heading).
+    const captionBaseFamily = kit.captionProfile?.fontFamily ?? fonts.caption.family;
+    const cp = kit.captionProfile;
+    const caption = {
+        fg: cp?.emphasisColor
+            ? clampToFloor(cp.emphasisColor, safe.captionScrim, FLOORS.body)
+            : safe.captionFg,
+        scrim: safe.captionScrim,
+        // Base + highlight color are forward-corrected to the body floor over the
+        // scrim, same guard as emphasisColor→fg (an authored accent that fails APCA
+        // is clamped UP to legibility, never rendered below the floor).
+        ...(cp?.color
+            ? { color: clampToFloor(cp.color, safe.captionScrim, FLOORS.body) }
+            : {}),
+        ...(cp?.highlightColor
+            ? { highlightColor: clampToFloor(cp.highlightColor, safe.captionScrim, FLOORS.body) }
+            : {}),
+        ...(cp?.plate ? { plate: cp.plate } : {}),
+        ...(cp?.entrance ? { entrance: cp.entrance } : {}),
+        ...(cp?.entranceMs != null ? { entranceMs: cp.entranceMs } : {}),
+        ...(cp?.entranceStaggerMs != null ? { entranceStaggerMs: cp.entranceStaggerMs } : {}),
+        ...(cp?.exitMs != null ? { exitMs: cp.exitMs } : {}),
+        ...(captionBaseFamily ? { fontFamily: captionBaseFamily } : {}),
+        ...(cp?.emphasisFontFamily ? { emphasisFontFamily: cp.emphasisFontFamily } : {}),
+        ...(cp?.emphasisScale != null ? { emphasisScale: cp.emphasisScale } : {}),
+        ...(cp?.emphasisFontWeight != null ? { emphasisFontWeight: cp.emphasisFontWeight } : {}),
+        ...(cp?.emphasisFontStyle ? { emphasisFontStyle: cp.emphasisFontStyle } : {}),
+        ...(cp?.emphasisTextTransform ? { emphasisTextTransform: cp.emphasisTextTransform } : {}),
+        ...(cp?.emphasisLetterSpacing != null
+            ? { emphasisLetterSpacing: cp.emphasisLetterSpacing }
+            : {}),
+        ...(cp?.emphasisPlate != null ? { emphasisPlate: cp.emphasisPlate } : {}),
+        ...(cp?.emphasisPlateColor ? { emphasisPlateColor: cp.emphasisPlateColor } : {}),
+        ...(cp?.emphasisPlateTextColor
+            ? { emphasisPlateTextColor: cp.emphasisPlateTextColor }
+            : {}),
+    };
+    // ── Overlay assets (logo / intro / outro / watermark) ──────────
+    // Normalize placement + sizes; carry author-set fields through. Each is
+    // present in the resolved kit only when the wire kit declared it.
+    const logo = kit.logo
+        ? {
+            src: kit.logo.src,
+            ...(kit.logo.alt != null ? { alt: kit.logo.alt } : {}),
+            placement: kit.logo.placement ?? LOGO_DEFAULT_PLACEMENT,
+            sizePct: kit.logo.sizePct ?? LOGO_DEFAULT_SIZE_PCT,
+        }
+        : undefined;
+    const intro = resolveIntroOutro(kit.intro);
+    const outro = resolveIntroOutro(kit.outro);
+    const watermark = kit.watermark
+        ? {
+            src: kit.watermark.src,
+            opacity: kit.watermark.opacity ?? WATERMARK_DEFAULT_OPACITY,
+            placement: kit.watermark.placement ?? WATERMARK_DEFAULT_PLACEMENT,
+        }
+        : undefined;
+    // ── Language (built FROM INSPIRATION) ──────────────────────────
+    // Carried untransformed — exemplar/motif reference data the maker + judge
+    // condition on, keyed off the presence of exemplar frames. Present only when
+    // the kit was built from inspiration; NOT a `$brand:` token root.
+    const language = kit.exemplarKeys && kit.exemplarKeys.length > 0
+        ? {
+            exemplarKeys: kit.exemplarKeys,
+            ...(kit.contactSheetKey ? { contactSheetKey: kit.contactSheetKey } : {}),
+            motifs: kit.motifs ?? [],
+            ...(kit.styleRubric ? { styleRubric: kit.styleRubric } : {}),
+            ...(kit.density ? { density: kit.density } : {}),
+        }
+        : undefined;
+    return {
+        id: kit.id,
+        name: kit.name,
+        colors,
+        caption,
+        fonts,
+        spacing,
+        sizing,
+        motion,
+        ...(logo ? { logo } : {}),
+        ...(intro ? { intro } : {}),
+        ...(outro ? { outro } : {}),
+        ...(watermark ? { watermark } : {}),
+        ...(language ? { language } : {}),
+        ...(kit.audio ? { audio: kit.audio } : {}),
+    };
+}
+/**
+ * The DESIGN-TOKEN sub-trees of a ResolvedBrandKit whose leaves are bindable as
+ * `$brand:<path>` param values. We deliberately exclude `id`/`name` (metadata,
+ * not design tokens) and the optional overlay assets (`logo`/`intro`/`outro`/
+ * `watermark`/`fontAssets` — present only when a kit declares them, and not a
+ * param-binding surface).
+ */
+export const BRAND_TOKEN_ROOT_KEYS = [
+    "colors",
+    "caption",
+    "fonts",
+    "spacing",
+    "sizing",
+    "motion",
+];
+/**
+ * Reference wire kit used ONLY to materialize the canonical token SHAPE. The
+ * values are throwaway (real hex so the contrast derivations run); only the
+ * resolved object's LEAF PATHS are read. Width is arbitrary — spacing/sizing
+ * paths are present at any width (their VALUES scale; their KEYS don't).
+ */
+const BRAND_TOKEN_REFERENCE_KIT = {
+    id: "reference",
+    name: "reference",
+    colors: {
+        primary: "#3b82f6",
+        accent: "#22c55e",
+        background: "#0b0b0f",
+        text: "#f5f5f7",
+    },
+    fonts: { heading: { kind: "system", family: "Inter" } },
+};
+const BRAND_TOKEN_REFERENCE_WIDTH = 1920;
+function collectBrandLeafPaths(value, prefix, out) {
+    if (value === null || value === undefined)
+        return;
+    if (typeof value === "object") {
+        // Arrays aren't a `$brand:` ref target (refs resolve to scalar leaves only).
+        if (Array.isArray(value))
+            return;
+        for (const [k, v] of Object.entries(value)) {
+            collectBrandLeafPaths(v, prefix ? `${prefix}.${k}` : k, out);
+        }
+        return;
+    }
+    out.push(prefix);
+}
+function buildBrandTokenRefs() {
+    const ref = resolveBrandKit(BRAND_TOKEN_REFERENCE_KIT, BRAND_TOKEN_REFERENCE_WIDTH);
+    const paths = [];
+    for (const root of BRAND_TOKEN_ROOT_KEYS) {
+        collectBrandLeafPaths(ref[root], root, paths);
+    }
+    return paths.map((p) => `$brand:${p}`).sort();
+}
+/**
+ * The canonical set of bindable `$brand:` token refs a param value may carry —
+ * the COMPLETE design-token leaf vocabulary of a ResolvedBrandKit, DERIVED at
+ * module load from a reference resolution so it can NEVER drift from the
+ * resolver: add a token to ResolvedBrandKit and it appears here automatically;
+ * remove one and it disappears. Surfaced on the component catalog as
+ * `brandTokens` so an agent discovers e.g. `$brand:colors.accent` (a valid value
+ * for an accent-color param) without reading source. Colors + fonts are the
+ * common bindings; spacing/sizing/motion/caption round out the full vocabulary.
+ */
+export const BRAND_TOKEN_REFS = Object.freeze(buildBrandTokenRefs());
+/**
+ * Mix two hex colors by ratio. ratio=0 returns `a` unchanged;
+ * ratio=1 returns `b`; ratio=0.4 returns a 60% a + 40% b mix.
+ *
+ * Accepts both `#RRGGBB` and `#RGB` short form. Rejects non-hex
+ * inputs (rgb()/hsl()/named colors) by returning `a` unchanged —
+ * the brand cascade NEVER crashes on a malformed input; primitives
+ * fall back to their declared fallback for the affected token.
+ *
+ * Returns `#RRGGBB` form, lowercase.
+ */
+export function colorMix(a, b, ratio) {
+    const aRgb = parseHex(a);
+    const bRgb = parseHex(b);
+    if (!aRgb || !bRgb)
+        return a;
+    const clamped = Math.max(0, Math.min(1, ratio));
+    const inv = 1 - clamped;
+    const r = Math.round(aRgb.r * inv + bRgb.r * clamped);
+    const g = Math.round(aRgb.g * inv + bRgb.g * clamped);
+    const blue = Math.round(aRgb.b * inv + bRgb.b * clamped);
+    return "#" + [r, g, blue].map((v) => v.toString(16).padStart(2, "0")).join("");
+}
+function parseHex(input) {
+    if (typeof input !== "string")
+        return null;
+    const s = input.trim().toLowerCase();
+    if (!s.startsWith("#"))
+        return null;
+    const hex = s.slice(1);
+    if (hex.length === 3) {
+        return {
+            r: parseInt(hex[0] + hex[0], 16),
+            g: parseInt(hex[1] + hex[1], 16),
+            b: parseInt(hex[2] + hex[2], 16),
+        };
+    }
+    if (hex.length === 6) {
+        return {
+            r: parseInt(hex.slice(0, 2), 16),
+            g: parseInt(hex.slice(2, 4), 16),
+            b: parseInt(hex.slice(4, 6), 16),
+        };
+    }
+    return null;
+}
+/**
+ * Resolve a `$brand:<dot-path>` reference against a ResolvedBrandKit.
+ * Returns the value at the path, or `null` if the path doesn't exist
+ * or the value isn't a primitive. Primitives use the returned `null`
+ * to fall back to their declared `PrimitiveRegistryEntry.tokens[].fallback`.
+ *
+ * Examples:
+ *   resolveBrandRef("$brand:colors.accent", kit) → "#ff0066"
+ *   resolveBrandRef("$brand:fonts.heading.family", kit) → "Inter" | undefined
+ *   resolveBrandRef("$brand:motion.duration", kit) → 200
+ *   resolveBrandRef("not-a-ref", kit) → null (not a ref form)
+ *   resolveBrandRef("$brand:colors.nonexistent", kit) → null
+ *
+ * Escape rule (per data-model.md § `$brand:` ref syntax): a value
+ * starting with `\$brand:` is the literal string — strip the leading
+ * `\` and treat as text, not a ref. This function returns `null` for
+ * escaped forms; the caller (params resolver) handles the strip.
+ */
+export function resolveBrandRef(refOrValue, kit) {
+    if (typeof refOrValue !== "string")
+        return null;
+    if (!refOrValue.startsWith("$brand:"))
+        return null;
+    const path = refOrValue.slice("$brand:".length);
+    if (!path)
+        return null;
+    const segments = path.split(".");
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let cursor = kit;
+    for (const seg of segments) {
+        if (cursor == null || typeof cursor !== "object")
+            return null;
+        cursor = cursor[seg];
+    }
+    // Only primitive leaves resolve; object/array means the path
+    // pointed at a sub-tree, which is a malformed ref.
+    if (cursor == null)
+        return null;
+    if (typeof cursor === "object")
+        return null;
+    return cursor;
+}
+/**
+ * Walk an arbitrary value tree (typically `OverlaySource.params` or
+ * `EffectSource.params`) and replace every `$brand:` ref string with
+ * its resolved value from the kit. Non-string leaves pass through.
+ * Refs that don't resolve are replaced with the provided per-token
+ * fallback if any, else the original ref string is preserved so the
+ * primitive's tokens[].fallback can apply at render time.
+ *
+ * Operates immutably — does NOT mutate the input.
+ */
+export function resolveBrandRefsDeep(value, kit) {
+    if (Array.isArray(value)) {
+        return value.map((v) => resolveBrandRefsDeep(v, kit));
+    }
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = resolveBrandRefsDeep(v, kit);
+        }
+        return out;
+    }
+    if (typeof value === "string") {
+        // Escape: \$brand:... → literal string with the leading \ stripped.
+        if (value.startsWith("\\$brand:")) {
+            return value.slice(1);
+        }
+        if (value.startsWith("$brand:")) {
+            const resolved = resolveBrandRef(value, kit);
+            // Resolution failure: preserve the ref string so a downstream
+            // consumer (or the primitive's fallback handler) can decide.
+            // Returning the original string here is the documented
+            // contract — primitives' tokens[].fallback applies at the
+            // primitive boundary, not here.
+            return resolved ?? value;
+        }
+        return value;
+    }
+    return value;
+}
+/**
+ * Card token layer → CSS custom properties. Resolves `$brand:` refs through
+ * `resolveBrandRefsDeep`, then emits every resolved string leaf as a `--cf-<k>`
+ * var; unresolved refs are DROPPED (the card html's own `var(--cf-x, fallback)`
+ * applies). The ONE copy of this logic — the render's OverlayContent card
+ * branch and the local harness both consume it (extracted 2026-07-16; each
+ * previously carried a mirror).
+ */
+export function cssLayoutVars(tokens, kit) {
+    if (!tokens)
+        return {};
+    const resolved = kit ? resolveBrandRefsDeep(tokens, kit) : tokens;
+    const vars = {};
+    for (const [k, v] of Object.entries(resolved)) {
+        if (typeof v === "string" && !v.startsWith("$brand:"))
+            vars[`--cf-${k}`] = v;
+    }
+    return vars;
+}
+/**
+ * Component brand palette — the resolved kit an authored `create_component`
+ * graphic reads from `props.brand.*`. This is the COMPONENT-medium analog of a
+ * card's `cssLayoutVars` (`var(--cf-*)`): a card is freeform HTML that cascades
+ * CSS custom properties; a component receives brand through its PROPS, so we hand
+ * it one FLAT, already-resolved object. AUTO-INJECTED at the brand-meets-props
+ * seam (`resolveBrandProps` / the ship snapshot) so a component binds to the kit
+ * with ZERO prop declaration — `style={{ color: props.brand.accent, fontFamily:
+ * props.brand.heading }}`. Flat by design: one dereference, no nested paths to
+ * author, no `$brand:` refs to declare (the authoring cost that made the
+ * ref-per-token approach ~2.4× slower per design attempt).
+ */
+export function componentBrandPalette(kit) {
+    return {
+        primary: kit.colors.primary,
+        secondary: kit.colors.secondary,
+        accent: kit.colors.accent,
+        accentMuted: kit.colors.accentMuted,
+        background: kit.colors.background,
+        surface: kit.colors.surface,
+        card: kit.colors.card,
+        border: kit.colors.border,
+        gridLine: kit.colors.gridLine,
+        text: kit.colors.text,
+        textMuted: kit.colors.textMuted,
+        textOnMedia: kit.colors.textOnMedia,
+        textOnAccent: kit.colors.textOnAccent,
+        textOnSurface: kit.colors.textOnSurface,
+        // A FontRef family can be undefined (unresolved) — hand the component an empty
+        // string so `fontFamily: props.brand.heading` falls to the browser default,
+        // never the literal "undefined". Mirrors cssLayoutVars dropping unresolved refs.
+        heading: kit.fonts.heading.family ?? '',
+        body: kit.fonts.body.family ?? '',
+        caption: kit.fonts.caption.family ?? '',
+    };
+}

package/dist/_members/composition/projection/cardTokens.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ */
+import { type ResolvedBrandKit } from "./brandKit.js";
+/**
+ * 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 declare const CARD_MOTION_VAR_NAMES: readonly ["--cf-frame", "--cf-t", "--cf-fps", "--cf-duration", "--cf-progress", "--cf-ease", "--cf-enter", "--cf-exit"];
+export type CardMotionVarName = (typeof CARD_MOTION_VAR_NAMES)[number];
+/**
+ * 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 declare function detectDroppedBrandTokens(value: unknown, kit: ResolvedBrandKit | undefined): string[];
+export declare function detectUnresolvedCardTokens(value: unknown): string[];