@cueframe/kernel 0.1.0 → 0.1.1

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

@@ -1,482 +0,0 @@
-/**
- * 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 ?? '',
-    };
-}