@bitmagic/cli 0.1.83-dev.2 → 0.1.83-dev.3

package/dist/vendor/hud-theme/engine/hud/validateTheme.js

@@ -0,0 +1,535 @@
+import { BACKGROUND_POSITIONS, BACKGROUND_REPEATS, BACKGROUND_SIZE_KEYWORDS, BACKGROUND_TILE_SIZE, BORDER_IMAGE_REPEATS, DECORATION_SLOT_KINDS, DEFAULT_THEME_FONT, DEFAULT_THEME_SHAPE, FONT_BODY_WEIGHTS, FONT_HEADING_WEIGHTS, GLOW_KEYS, HUD_ELEMENT_CLASSES, IMAGE_RENDERINGS, LABEL_CASES, MAX_INLINE_SVG_LENGTH, REQUIRED_THEME_COLOR_KEYS, THEME_COLOR_KEYS, THEME_ICON_KEYS, THEME_NUMBER_RANGES, isHexColor, } from './ThemeTokens.js';
+import { HUD_FONTS } from './fonts.js';
+import { HUD_DECORATIONS } from './decorations.js';
+const FONT_KEYS = Object.keys(HUD_FONTS);
+const DECORATION_KEYS = Object.keys(HUD_DECORATIONS);
+const ELEMENT_CLASSES = HUD_ELEMENT_CLASSES;
+// Not engine/utils/guards.ts' isRecord: the HUD kernel ships to the CLI and the agent
+// through @bitmagic/hud-theme, whose build refuses any engine file outside engine/hud/.
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+// Levenshtein, not character containment. The old scorer counted how many of the
+// input's characters appear ANYWHERE in a candidate, so long candidates won on
+// volume: "balloo2" suggested "rubik-mono-one"-class noise instead of "baloo-2",
+// and the suggestion an agent is meant to copy was sometimes worse than no
+// suggestion. Edit distance measures what a typo actually is. Only suggest when
+// the distance is small relative to the input — a wild guess should get the
+// full candidate list from the error message, not false confidence in one name.
+function editDistance(a, b) {
+    // Single-row DP; inputs are short catalog keys, so O(len a * len b) is fine.
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const cur = [i];
+        for (let j = 1; j <= b.length; j++) {
+            const deletion = (prev[j] ?? 0) + 1;
+            const insertion = (cur[j - 1] ?? 0) + 1;
+            const substitution = (prev[j - 1] ?? 0) + (a[i - 1] === b[j - 1] ? 0 : 1);
+            cur[j] = Math.min(deletion, insertion, substitution);
+        }
+        prev = cur;
+    }
+    return prev[b.length] ?? 0;
+}
+export function suggestClosest(value, candidates) {
+    const v = value.toLowerCase();
+    let best;
+    let bestScore = Infinity;
+    for (const c of candidates) {
+        const score = editDistance(v, c.toLowerCase());
+        if (score < bestScore) {
+            bestScore = score;
+            best = c;
+        }
+    }
+    const maxDistance = Math.max(2, Math.ceil(v.length / 3));
+    return bestScore <= maxDistance ? best : undefined;
+}
+function checkHex(ctx, path, value) {
+    if (typeof value !== 'string') {
+        ctx.errors.push({ path, message: `expected hex color string, got ${typeof value}` });
+        return null;
+    }
+    if (!isHexColor(value)) {
+        ctx.errors.push({
+            path,
+            message: `${value} is not a valid 6-digit hex color`,
+            suggestion: 'Use e.g. "#A0DAB9" — six hex digits with a leading #.',
+        });
+        return null;
+    }
+    return value;
+}
+/**
+ * `background-size`: one of the three keywords, or an explicit tile size.
+ *
+ * A repeating decoration NEEDS the explicit form. Every decoration SVG carries
+ * only a `viewBox`, which gives it no intrinsic size, so `auto` does not mean
+ * "one tile at the viewBox dimensions" — the browser scales a single copy to
+ * fill the element, and a pattern meant to tile renders as one enormous motif.
+ * With only the three keywords available, a hand-authored tiling texture could
+ * not be expressed at all. The tile pattern itself (`BACKGROUND_TILE_SIZE`) is
+ * deliberately strict; see its note in ThemeTokens.ts.
+ */
+function checkBackgroundSize(ctx, path, value) {
+    if (typeof value === 'string' && BACKGROUND_SIZE_KEYWORDS.includes(value)) {
+        return value;
+    }
+    if (typeof value === 'string' && BACKGROUND_TILE_SIZE.test(value))
+        return value;
+    ctx.errors.push({
+        path,
+        message: `${JSON.stringify(value)} is not "cover", "contain", "auto", or an explicit tile size`,
+        suggestion: 'Use "32px 32px" for a repeating pattern (a viewBox-only SVG has no intrinsic '
+            + 'size, so "auto" stretches one copy over the whole element), or one of the keywords.',
+    });
+    return null;
+}
+function checkEnum(ctx, path, value, allowed) {
+    if (typeof value !== 'string' || !allowed.includes(value)) {
+        const suggestion = typeof value === 'string' ? suggestClosest(value, allowed) : undefined;
+        ctx.errors.push({
+            path,
+            message: `${JSON.stringify(value)} is not one of: ${allowed.join(', ')}`,
+            suggestion: suggestion ? `Closest match: "${suggestion}"` : undefined,
+        });
+        return null;
+    }
+    return value;
+}
+function checkNumber(ctx, path, value, token, fallback) {
+    const [min, max] = THEME_NUMBER_RANGES[token];
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        ctx.errors.push({ path, message: `expected number in [${min}, ${max}]` });
+        return fallback;
+    }
+    if (value < min || value > max) {
+        ctx.errors.push({ path, message: `${value} outside allowed range [${min}, ${max}]` });
+        return fallback;
+    }
+    return value;
+}
+function checkFont(ctx, path, raw) {
+    if (!isObject(raw)) {
+        ctx.errors.push({ path, message: 'missing font object' });
+        return null;
+    }
+    const key = checkEnum(ctx, `${path}.key`, raw.key, FONT_KEYS);
+    if (!key)
+        return null;
+    const labelCase = raw.case === undefined
+        ? DEFAULT_THEME_FONT.case
+        : checkEnum(ctx, `${path}.case`, raw.case, LABEL_CASES) ?? DEFAULT_THEME_FONT.case;
+    const weightBody = raw.weightBody === undefined
+        ? DEFAULT_THEME_FONT.weightBody
+        : (checkEnum(ctx, `${path}.weightBody`, String(raw.weightBody), FONT_BODY_WEIGHTS.map(String))
+            ? raw.weightBody
+            : DEFAULT_THEME_FONT.weightBody);
+    const weightHeading = raw.weightHeading === undefined
+        ? DEFAULT_THEME_FONT.weightHeading
+        : (checkEnum(ctx, `${path}.weightHeading`, String(raw.weightHeading), FONT_HEADING_WEIGHTS.map(String))
+            ? raw.weightHeading
+            : DEFAULT_THEME_FONT.weightHeading);
+    const trackingLabel = raw.trackingLabel === undefined
+        ? DEFAULT_THEME_FONT.trackingLabel
+        : checkNumber(ctx, `${path}.trackingLabel`, raw.trackingLabel, 'trackingLabel', DEFAULT_THEME_FONT.trackingLabel);
+    const outlineWidth = raw.outlineWidth === undefined
+        ? DEFAULT_THEME_FONT.outlineWidth
+        : checkNumber(ctx, `${path}.outlineWidth`, raw.outlineWidth, 'outlineWidth', DEFAULT_THEME_FONT.outlineWidth);
+    // Absent stays absent — the resolved field is optional on purpose.
+    const sizeScale = raw.sizeScale === undefined
+        ? undefined
+        : checkNumber(ctx, `${path}.sizeScale`, raw.sizeScale, 'sizeScale', 1);
+    // Auto-correct case if the font doesn't support the requested case (e.g.
+    // Pacifico + 'upper' looks awkward — snap to the font's supported case
+    // and emit a warning explaining the swap). The resolved theme stored in
+    // the registry uses the corrected value, so the HUD renders cleanly even
+    // when the input was wrong.
+    const fontEntry = HUD_FONTS[key];
+    const effectiveCase = fontEntry.suitsCase.includes(labelCase)
+        ? labelCase
+        : (fontEntry.suitsCase[0] ?? labelCase);
+    if (effectiveCase !== labelCase) {
+        ctx.warnings.push({
+            path: `${path}.case`,
+            message: `font "${key}" is designed for case "${effectiveCase}" — auto-corrected from "${labelCase}". Pick a different font (e.g. "bebas-neue", "rubik-mono-one") if you want case "${labelCase}".`,
+            suggestion: `Either keep the auto-correction (case: "${effectiveCase}") or change font.key.`,
+        });
+    }
+    return {
+        key, case: effectiveCase, weightBody, weightHeading, trackingLabel, outlineWidth,
+        // Spread so an absent scale leaves the KEY absent, not set to undefined.
+        ...(sizeScale === undefined ? {} : { sizeScale }),
+    };
+}
+function checkColors(ctx, path, raw) {
+    if (!isObject(raw)) {
+        ctx.errors.push({ path, message: 'missing colors object' });
+        return null;
+    }
+    const required = REQUIRED_THEME_COLOR_KEYS;
+    const result = {};
+    let allRequiredOk = true;
+    for (const field of required) {
+        const hex = checkHex(ctx, `${path}.${field}`, raw[field]);
+        if (hex)
+            result[field] = hex;
+        else
+            allRequiredOk = false;
+    }
+    for (const field of ['warning', 'success', 'textMuted']) {
+        if (raw[field] !== undefined) {
+            const hex = checkHex(ctx, `${path}.${field}`, raw[field]);
+            if (hex)
+                result[field] = hex;
+        }
+        else {
+            // Fallbacks chosen to remain on-brand without forcing the agent to fill them.
+            if (field === 'warning')
+                result.warning = result.primary ?? '#FF8200';
+            if (field === 'success')
+                result.success = result.primary ?? '#F9E547';
+            if (field === 'textMuted')
+                result.textMuted = '#b3b3b3';
+        }
+    }
+    // outline stays ABSENT when omitted — no fallback fill. Absence means "no outline
+    // concept" and lets base styles keep their per-element default borders.
+    if (raw.outline !== undefined) {
+        const hex = checkHex(ctx, `${path}.outline`, raw.outline);
+        if (hex)
+            result.outline = hex;
+    }
+    if (!allRequiredOk)
+        return null;
+    return result;
+}
+function checkShape(ctx, path, raw) {
+    if (raw === undefined)
+        return { ...DEFAULT_THEME_SHAPE };
+    if (!isObject(raw)) {
+        ctx.errors.push({ path, message: 'expected shape object' });
+        return { ...DEFAULT_THEME_SHAPE };
+    }
+    const radiusPill = raw.radiusPill === undefined
+        ? DEFAULT_THEME_SHAPE.radiusPill
+        : checkNumber(ctx, `${path}.radiusPill`, raw.radiusPill, 'radiusPill', DEFAULT_THEME_SHAPE.radiusPill);
+    const radiusCard = raw.radiusCard === undefined
+        ? DEFAULT_THEME_SHAPE.radiusCard
+        : checkNumber(ctx, `${path}.radiusCard`, raw.radiusCard, 'radiusCard', DEFAULT_THEME_SHAPE.radiusCard);
+    const glow = raw.glow === undefined
+        ? DEFAULT_THEME_SHAPE.glow
+        : checkEnum(ctx, `${path}.glow`, raw.glow, GLOW_KEYS) ?? DEFAULT_THEME_SHAPE.glow;
+    const imageRendering = raw.imageRendering === undefined
+        ? DEFAULT_THEME_SHAPE.imageRendering
+        : checkEnum(ctx, `${path}.imageRendering`, raw.imageRendering, IMAGE_RENDERINGS) ??
+            DEFAULT_THEME_SHAPE.imageRendering;
+    const borderWidth = raw.borderWidth === undefined
+        ? DEFAULT_THEME_SHAPE.borderWidth
+        : checkNumber(ctx, `${path}.borderWidth`, raw.borderWidth, 'borderWidth', DEFAULT_THEME_SHAPE.borderWidth);
+    const bevel = raw.bevel === undefined
+        ? DEFAULT_THEME_SHAPE.bevel
+        : checkNumber(ctx, `${path}.bevel`, raw.bevel, 'bevel', DEFAULT_THEME_SHAPE.bevel);
+    const gloss = raw.gloss === undefined
+        ? DEFAULT_THEME_SHAPE.gloss
+        : checkNumber(ctx, `${path}.gloss`, raw.gloss, 'gloss', DEFAULT_THEME_SHAPE.gloss);
+    // Absent stays absent — like colors.outline, absence is meaningful (keyed glow).
+    const glowColor = raw.glowColor === undefined
+        ? undefined
+        : checkHex(ctx, `${path}.glowColor`, raw.glowColor) ?? undefined;
+    // No warning for glow:'none' + glowColor: the explicit hex simply wins,
+    // including over 'none'. An agent patching glowColor onto a zero-glow theme
+    // is asking for a glow in one edit — making 'none' veto it would turn the
+    // most direct ask ("purple neon") into a two-token puzzle. Turning a glow
+    // OFF again is deleting glowColor.
+    return {
+        radiusPill, radiusCard, glow, imageRendering, borderWidth, bevel, gloss,
+        ...(glowColor === undefined ? {} : { glowColor }),
+    };
+}
+function checkBorderImageValue(ctx, path, raw) {
+    if (typeof raw === 'string') {
+        return checkEnum(ctx, path, raw, DECORATION_KEYS);
+    }
+    if (isObject(raw) && typeof raw.svg === 'string') {
+        if (raw.svg.length > MAX_INLINE_SVG_LENGTH) {
+            ctx.errors.push({ path: `${path}.svg`, message: `inline SVG exceeds 16kb limit` });
+            return null;
+        }
+        const borderSlice = checkNumber(ctx, `${path}.borderSlice`, raw.borderSlice ?? 30, 'borderSlice', 30);
+        const repeat = checkEnum(ctx, `${path}.repeat`, raw.repeat ?? 'stretch', BORDER_IMAGE_REPEATS) ?? 'stretch';
+        return { svg: raw.svg, borderSlice, repeat };
+    }
+    ctx.errors.push({ path, message: 'expected curated decoration key string or inline SVG object' });
+    return null;
+}
+function checkBackgroundValue(ctx, path, raw) {
+    if (typeof raw === 'string') {
+        return checkEnum(ctx, path, raw, DECORATION_KEYS);
+    }
+    if (isObject(raw) && typeof raw.svg === 'string') {
+        if (raw.svg.length > MAX_INLINE_SVG_LENGTH) {
+            ctx.errors.push({ path: `${path}.svg`, message: `inline SVG exceeds 16kb limit` });
+            return null;
+        }
+        const size = checkBackgroundSize(ctx, `${path}.size`, raw.size ?? 'auto') ?? 'auto';
+        const position = checkEnum(ctx, `${path}.position`, raw.position ?? 'center', BACKGROUND_POSITIONS) ?? 'center';
+        const repeat = checkEnum(ctx, `${path}.repeat`, raw.repeat ?? 'no-repeat', BACKGROUND_REPEATS) ?? 'no-repeat';
+        return { svg: raw.svg, size, position, repeat };
+    }
+    ctx.errors.push({ path, message: 'expected curated decoration key string or inline SVG object' });
+    return null;
+}
+function checkDecorationSlots(ctx, path, raw) {
+    if (!isObject(raw))
+        return {};
+    const slots = {};
+    for (const kind of DECORATION_SLOT_KINDS) {
+        if (raw[kind] === undefined)
+            continue;
+        const value = kind === 'borderImage'
+            ? checkBorderImageValue(ctx, `${path}.${kind}`, raw[kind])
+            : checkBackgroundValue(ctx, `${path}.${kind}`, raw[kind]);
+        if (value !== null) {
+            if (typeof value === 'string') {
+                const entry = HUD_DECORATIONS[value];
+                if (!entry.suitsSlots.includes(kind)) {
+                    ctx.warnings.push({
+                        path: `${path}.${kind}`,
+                        message: `decoration "${value}" isn't designed for slot "${kind}" (suits: ${entry.suitsSlots.join(', ')})`,
+                    });
+                }
+            }
+            // Workaround for noUncheckedIndexedAccess narrowing on the union literal.
+            slots[kind] = value;
+        }
+    }
+    return slots;
+}
+function checkDecorations(ctx, path, raw) {
+    if (raw === undefined)
+        return {};
+    if (!isObject(raw)) {
+        ctx.errors.push({ path, message: 'expected decorations object' });
+        return {};
+    }
+    const out = {};
+    for (const key of Object.keys(raw)) {
+        if (!ELEMENT_CLASSES.includes(key)) {
+            ctx.errors.push({
+                path: `${path}.${key}`,
+                message: `unknown HUD element class "${key}"`,
+                suggestion: `Known: ${ELEMENT_CLASSES.join(', ')}.`,
+            });
+            continue;
+        }
+        out[key] = checkDecorationSlots(ctx, `${path}.${key}`, raw[key]);
+    }
+    return out;
+}
+// Per-element override leaves are validated as WARN-AND-DROP, not as errors.
+// These blocks used to be raw casts, so `elements.healthBar.colors.background:
+// "bright-green"` sailed through validation and produced broken CSS with no
+// message anywhere — the quietest possible failure. Errors would be the wrong
+// fix: an error rejects the WHOLE theme, and already-published games carry
+// frozen inline themes this validator must keep accepting. Dropping the one bad
+// leaf keeps the theme rendering exactly as it did before, and the warning
+// finally names the field. (The agent-side validator is deliberately stricter —
+// at WRITE time a bad leaf is an error; at LOAD time it cannot be.)
+function dropLeaf(ctx, path, message, suggestion) {
+    ctx.warnings.push({ path, message: `${message} — ignoring this override`, ...(suggestion ? { suggestion } : {}) });
+    return undefined;
+}
+function checkPartialColors(ctx, path, raw) {
+    if (!isObject(raw)) {
+        dropLeaf(ctx, path, 'expected a colors object');
+        return null;
+    }
+    const KNOWN = THEME_COLOR_KEYS;
+    const out = {};
+    for (const key of Object.keys(raw)) {
+        if (!KNOWN.includes(key)) {
+            dropLeaf(ctx, `${path}.${key}`, `unknown color token "${key}"`, `Known: ${KNOWN.join(', ')}.`);
+            continue;
+        }
+        const value = raw[key];
+        if (!isHexColor(value)) {
+            dropLeaf(ctx, `${path}.${key}`, `${JSON.stringify(value)} is not a valid 6-digit hex color`);
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+}
+function partialNumber(ctx, path, value, token) {
+    const [min, max] = THEME_NUMBER_RANGES[token];
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max) {
+        return dropLeaf(ctx, path, `${JSON.stringify(value)} is not a number in [${min}, ${max}]`);
+    }
+    return value;
+}
+function checkPartialShape(ctx, path, raw) {
+    if (!isObject(raw)) {
+        dropLeaf(ctx, path, 'expected a shape object');
+        return null;
+    }
+    const out = {};
+    if (raw.radiusPill !== undefined)
+        out.radiusPill = partialNumber(ctx, `${path}.radiusPill`, raw.radiusPill, 'radiusPill');
+    if (raw.radiusCard !== undefined)
+        out.radiusCard = partialNumber(ctx, `${path}.radiusCard`, raw.radiusCard, 'radiusCard');
+    if (raw.borderWidth !== undefined)
+        out.borderWidth = partialNumber(ctx, `${path}.borderWidth`, raw.borderWidth, 'borderWidth');
+    if (raw.bevel !== undefined)
+        out.bevel = partialNumber(ctx, `${path}.bevel`, raw.bevel, 'bevel');
+    if (raw.glow !== undefined) {
+        if (typeof raw.glow === 'string' && GLOW_KEYS.includes(raw.glow))
+            out.glow = raw.glow;
+        else
+            dropLeaf(ctx, `${path}.glow`, `${JSON.stringify(raw.glow)} is not one of: ${GLOW_KEYS.join(', ')}`);
+    }
+    if (raw.imageRendering !== undefined) {
+        if (IMAGE_RENDERINGS.includes(raw.imageRendering))
+            out.imageRendering = raw.imageRendering;
+        else
+            dropLeaf(ctx, `${path}.imageRendering`, `${JSON.stringify(raw.imageRendering)} is not "auto" or "pixelated"`);
+    }
+    if (raw.gloss !== undefined)
+        out.gloss = partialNumber(ctx, `${path}.gloss`, raw.gloss, 'gloss');
+    if (raw.glowColor !== undefined) {
+        if (isHexColor(raw.glowColor))
+            out.glowColor = raw.glowColor;
+        else
+            dropLeaf(ctx, `${path}.glowColor`, `${JSON.stringify(raw.glowColor)} is not a valid 6-digit hex color`);
+    }
+    return out;
+}
+function checkPartialFont(ctx, path, raw) {
+    if (!isObject(raw)) {
+        dropLeaf(ctx, path, 'expected a font object');
+        return null;
+    }
+    const out = {};
+    if (raw.key !== undefined) {
+        if (typeof raw.key === 'string' && FONT_KEYS.includes(raw.key))
+            out.key = raw.key;
+        else {
+            const close = typeof raw.key === 'string' ? suggestClosest(raw.key, FONT_KEYS) : undefined;
+            dropLeaf(ctx, `${path}.key`, `${JSON.stringify(raw.key)} is not a curated font key`, close ? `Closest match: "${close}"` : undefined);
+        }
+    }
+    if (raw.case !== undefined) {
+        if (LABEL_CASES.includes(raw.case))
+            out.case = raw.case;
+        else
+            dropLeaf(ctx, `${path}.case`, `${JSON.stringify(raw.case)} is not "upper" or "normal"`);
+    }
+    if (raw.trackingLabel !== undefined)
+        out.trackingLabel = partialNumber(ctx, `${path}.trackingLabel`, raw.trackingLabel, 'trackingLabel');
+    if (raw.outlineWidth !== undefined)
+        out.outlineWidth = partialNumber(ctx, `${path}.outlineWidth`, raw.outlineWidth, 'outlineWidth');
+    if (raw.sizeScale !== undefined)
+        out.sizeScale = partialNumber(ctx, `${path}.sizeScale`, raw.sizeScale, 'sizeScale');
+    if (raw.weightBody !== undefined) {
+        if (FONT_BODY_WEIGHTS.includes(raw.weightBody))
+            out.weightBody = raw.weightBody;
+        else
+            dropLeaf(ctx, `${path}.weightBody`, `${JSON.stringify(raw.weightBody)} is not one of ${FONT_BODY_WEIGHTS.join(', ')}`);
+    }
+    if (raw.weightHeading !== undefined) {
+        if (FONT_HEADING_WEIGHTS.includes(raw.weightHeading))
+            out.weightHeading = raw.weightHeading;
+        else
+            dropLeaf(ctx, `${path}.weightHeading`, `${JSON.stringify(raw.weightHeading)} is not one of ${FONT_HEADING_WEIGHTS.join(', ')}`);
+    }
+    return out;
+}
+function checkPartialTheme(ctx, path, raw) {
+    if (!isObject(raw)) {
+        ctx.errors.push({ path, message: 'expected partial theme object' });
+        return { font: null, colors: null, shape: null, decorations: null };
+    }
+    return {
+        font: raw.font === undefined ? null : checkPartialFont(ctx, `${path}.font`, raw.font),
+        colors: raw.colors === undefined ? null : checkPartialColors(ctx, `${path}.colors`, raw.colors),
+        shape: raw.shape === undefined ? null : checkPartialShape(ctx, `${path}.shape`, raw.shape),
+        decorations: raw.decorations === undefined
+            ? null
+            : checkDecorationSlots(ctx, `${path}.decorations`, raw.decorations),
+    };
+}
+function checkElements(ctx, path, raw) {
+    if (raw === undefined)
+        return {};
+    if (!isObject(raw)) {
+        ctx.errors.push({ path, message: 'expected elements object' });
+        return {};
+    }
+    const out = {};
+    for (const key of Object.keys(raw)) {
+        if (!ELEMENT_CLASSES.includes(key)) {
+            ctx.errors.push({ path: `${path}.${key}`, message: `unknown HUD element class "${key}"` });
+            continue;
+        }
+        out[key] = checkPartialTheme(ctx, `${path}.${key}`, raw[key]);
+    }
+    return out;
+}
+function checkIcons(ctx, path, raw) {
+    if (raw === undefined || raw === null)
+        return {};
+    if (!isObject(raw)) {
+        ctx.errors.push({ path, message: 'icons must be an object with optional heart/mouse/arrow SVG strings' });
+        return {};
+    }
+    const ICON_SLOTS = THEME_ICON_KEYS;
+    const out = {};
+    for (const key of Object.keys(raw)) {
+        if (!ICON_SLOTS.includes(key)) {
+            ctx.errors.push({
+                path: `${path}.${key}`,
+                message: `unknown icon slot "${key}"`,
+                suggestion: `Known: ${ICON_SLOTS.join(', ')}`,
+            });
+            continue;
+        }
+        const value = raw[key];
+        if (value === undefined || value === null)
+            continue;
+        if (typeof value !== 'string') {
+            ctx.errors.push({ path: `${path}.${key}`, message: 'icon SVG must be a string' });
+            continue;
+        }
+        if (value.length > MAX_INLINE_SVG_LENGTH) {
+            ctx.errors.push({ path: `${path}.${key}`, message: `icon SVG exceeds 16kb limit` });
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+}
+export function validateAndResolveTheme(input) {
+    const ctx = { errors: [], warnings: [] };
+    if (!isObject(input)) {
+        ctx.errors.push({ path: '', message: 'theme must be an object' });
+        return { ok: false, errors: ctx.errors, warnings: ctx.warnings };
+    }
+    const name = typeof input.name === 'string' && input.name.length > 0 ? input.name : null;
+    if (!name) {
+        ctx.errors.push({ path: 'name', message: 'name is required and must be non-empty' });
+    }
+    const font = checkFont(ctx, 'font', input.font);
+    const colors = checkColors(ctx, 'colors', input.colors);
+    const shape = checkShape(ctx, 'shape', input.shape);
+    const decorations = checkDecorations(ctx, 'decorations', input.decorations);
+    const elements = checkElements(ctx, 'elements', input.elements);
+    const icons = checkIcons(ctx, 'icons', input.icons);
+    if (ctx.errors.length > 0 || !name || !font || !colors) {
+        return { ok: false, errors: ctx.errors, warnings: ctx.warnings };
+    }
+    return {
+        ok: true,
+        theme: { name, font, colors, shape, decorations, elements, icons },
+        warnings: ctx.warnings,
+    };
+}

package/dist/vendor/hud-theme/index.js

@@ -0,0 +1,26 @@
+/**
+ * @bitmagic/hud-theme — the HUD theme kernel for tools (the hosted agent and the `bitmagic` CLI).
+ *
+ * Two halves, one copy each:
+ *
+ * - The engine half is the engine's own DOM-free theme files in game/src/engine/hud/ (tokens and
+ *   their vocabulary lists, colour maths, the font and decoration catalogues, the lenient
+ *   load-time validator, the presets, resolveWorldTheme). This package compiles them; it does not
+ *   copy them. The engine re-exports the same modules from `engine/hud/index.js`, and the engine
+ *   tarball ships them under `engine/hud/` as it always has, so a vendored project needs nothing
+ *   from this package.
+ * - The tool half lives in src/: the catalogue view, the strict write-time validator, the RFC 7386
+ *   merge patch, the theme report and the stored-theme resolver.
+ *
+ * The CLI bundles this package into its own dist/ (cli/scripts/bundle-hud-theme.mjs), because a
+ * published CLI runs against vendored engines of other versions and cannot import theirs.
+ */
+export { DEFAULT_THEME_FONT, DEFAULT_THEME_SHAPE, GLOW_KEYS, HEX_COLOR, isHexColor, MAX_INLINE_SVG_LENGTH, THEME_NUMBER_RANGES, THEME_COLOR_KEYS, REQUIRED_THEME_COLOR_KEYS, THEME_SHAPE_KEYS, DECORATION_SLOT_KINDS, THEME_ICON_KEYS, } from './engine/hud/ThemeTokens.js';
+export { relLuminance, contrastRatio, mixHex, readableTextColor, inkOnSurface, mutedInkOnSurface, accentInkOn, ON_SURFACE_MIN_CONTRAST, ACCENT_INK_MIN_CONTRAST, } from './engine/hud/colorMath.js';
+export { validateAndResolveTheme, } from './engine/hud/validateTheme.js';
+export { resolveWorldTheme, HUD_THEME_LOG_MARKER, HUD_UNKNOWN_PRESET_PHRASE, HUD_INVALID_THEME_PHRASE, } from './engine/hud/resolveWorldTheme.js';
+export { HUD_FONTS, HUD_DECORATIONS, HUD_ELEMENT_CLASSES, HUD_PRESET_NAMES, isHudPresetName, HUD_PRESET_THEMES, presetTheme, HUD_PRESET_INFO, DEFAULT_THEME_TOKENS, HUD_DECORATION_SVGS, HUD_GLOW_KEYS, HUD_SHAPE_TOKENS, HUD_COLOR_TOKENS, HUD_REQUIRED_COLORS, HUD_DECORATION_SLOTS, HUD_ICON_SLOTS, HUD_ICON_KEYS, } from './catalog.js';
+export { validateThemeStrict, isEngineFatalIssue, suggestClosest, } from './validate-strict.js';
+export { applyMergePatch, diffThemes, deleteAtPath } from './merge.js';
+export { buildThemeReport } from './report.js';
+export { resolveStoredTheme } from './stored.js';

package/dist/{theme/theme-merge.js → vendor/hud-theme/merge.js}

@@ -78,4 +78,3 @@ export function deleteAtPath(target, dottedPath) {
     delete node[leaf];
     return true;
 }
-//# sourceMappingURL=theme-merge.js.map

package/dist/{theme/theme-report.js → vendor/hud-theme/report.js}

@@ -8,10 +8,10 @@
  *   changed:  leaf-level diff of what the write actually did — the confirmation
  *             of the intended edit AND of anything a full replace changed
  *             without meaning to.
- *   contrast: the derived-ink pairings computed with EXACTLY the engine's
- *             arithmetic (theme-color-math mirrors engine colorMath, gate-
- *             checked), so "SUBSTITUTED -> renders #X" is a promise about the
- *             pixels, not an estimate.
+ *   contrast: the derived-ink pairings computed with the engine's own
+ *             colorMath module (compiled into this package, not copied), so
+ *             "SUBSTITUTED -> renders #X" is a promise about the pixels, not an
+ *             estimate.
  *
  * Deliberately report-only: the engine self-heals every pairing marked
  * SUBSTITUTED, so nothing here blocks a write. The report exists so the agent
@@ -19,12 +19,12 @@
  * renders as forest green might be exactly right, or reason to pick a colour
  * the ground can carry.
  */
-import { accentInkOn, contrastRatio, inkOnSurface, mutedInkOnSurface, readableTextColor, } from './theme-color-math.js';
-import { diffThemes } from './theme-merge.js';
-const HEX = /^#[0-9a-fA-F]{6}$/;
+import { accentInkOn, contrastRatio, inkOnSurface, mutedInkOnSurface, readableTextColor, } from './engine/hud/colorMath.js';
+import { isHexColor } from './engine/hud/ThemeTokens.js';
+import { diffThemes } from './merge.js';
 const MAX_DIFF_LINES = 12;
 function hex(value) {
-    return typeof value === 'string' && HEX.test(value) ? value : null;
+    return isHexColor(value) ? value : null;
 }
 function ratio(a, b) {
     return `${(Math.round(contrastRatio(a, b) * 10) / 10).toFixed(1)}:1`;
@@ -139,4 +139,3 @@ export function buildThemeReport(after, options) {
     }
     return lines.join('\n');
 }
-//# sourceMappingURL=theme-report.js.map

package/dist/{theme/theme-stored.js → vendor/hud-theme/stored.js}

@@ -3,14 +3,12 @@
  * logic both lanes need before a patch (the base), a report (the `before`
  * side), or a verdict (`show`/`check`) can exist.
  *
- * It lived twice: the write tool's currentEffectiveTheme and the CLI's
- * readStoredTheme each hand-rolled the stored-value→tokens mapping, and they
- * had already diverged — the CLI copy named an unknown preset truthfully while
- * the agent copy silently folded it into "the engine default". A new stored
- * form (or a label fix) had to land twice with nothing watching. This file is
- * part of the byte-identical kit mirror, so the gate now watches.
+ * It used to live twice (the write tool's currentEffectiveTheme and the CLI's
+ * readStoredTheme), and the copies had diverged: one named an unknown preset
+ * truthfully, the other folded it into "the engine default". Both lanes now
+ * call this one.
  */
-import { DEFAULT_THEME_TOKENS, HUD_PRESETS, presetTheme } from './hud-theme-catalog.js';
+import { DEFAULT_THEME_TOKENS, isHudPresetName, presetTheme } from './catalog.js';
 /** Resolve a raw `worldProfileData.hud.theme` value to what the engine renders. */
 export function resolveStoredTheme(stored) {
     if (stored === undefined || stored === null) {
@@ -21,7 +19,7 @@ export function resolveStoredTheme(stored) {
         };
     }
     if (typeof stored === 'string') {
-        if (HUD_PRESETS.includes(stored)) {
+        if (isHudPresetName(stored)) {
             return {
                 kind: 'preset',
                 tokens: presetTheme(stored),
@@ -47,4 +45,3 @@ export function resolveStoredTheme(stored) {
         label: `the engine default (hud.theme has unexpected type ${typeof stored})`,
     };
 }
-//# sourceMappingURL=theme-stored.js.map