@bitmagic/cli 0.1.59-dev.2 → 0.1.59-dev.4

package/dist/theme/theme-io.js

@@ -0,0 +1,190 @@
+/**
+ * The rules behind `bitmagic theme show | check | set | patch` — everything that
+ * is not flags and printing. Split from the command file the way `levels/`
+ * splits registry from command, so tests exercise the rules without a
+ * filesystem or a citty run.
+ *
+ * The vocabulary, validator, merge semantics and report come from `src/theme/`,
+ * a byte-identical mirror of game-play-agent's theme kit (the drift gate in
+ * game-play-agent/scripts/check-hud-catalog.ts enforces the byte identity
+ * against both the engine and this copy). Same inputs, same verdicts, same
+ * report text in both lanes.
+ */
+import { CliError } from '../errors.js';
+import { DEFAULT_THEME_TOKENS, HUD_PRESETS, isEngineFatalIssue, presetTheme, suggestClosest, validateThemeStrict, } from './hud-theme-catalog.js';
+import { resolveStoredTheme } from './theme-stored.js';
+import { applyMergePatch, deleteAtPath } from './theme-merge.js';
+import { buildThemeReport } from './theme-report.js';
+/** worldProfileData.hud.theme — the ONLY path the engine reads a theme from. */
+export function readStoredTheme(world) {
+    const profile = world.worldProfileData;
+    const hud = typeof profile === 'object' && profile !== null
+        ? profile.hud
+        : undefined;
+    const stored = typeof hud === 'object' && hud !== null ? hud.theme : undefined;
+    // The stored-value→tokens mapping lives in the gated kit (theme-stored.ts),
+    // shared with the hosted write tool — this wrapper only digs the value out
+    // of the world shape and keeps it for `show`.
+    const resolved = resolveStoredTheme(stored);
+    return {
+        kind: resolved.kind,
+        stored: stored === undefined ? null : stored,
+        effective: resolved.tokens,
+        label: resolved.label,
+    };
+}
+/**
+ * Parse a `set`/`patch` argument: a preset name, inline JSON, `@file`, or (for
+ * `set`) the literal `null`. Files keep long inline themes off the shell line,
+ * where quoting mangles them.
+ */
+export function parseThemeArgument(raw, readFile) {
+    if (raw === 'null' || raw === 'default')
+        return { kind: 'reset' };
+    const text = raw.startsWith('@') ? readFile(raw.slice(1)) : raw;
+    const trimmed = text.trim();
+    if (!trimmed.startsWith('{')) {
+        if (HUD_PRESETS.includes(trimmed)) {
+            return { kind: 'preset', name: trimmed };
+        }
+        const close = suggestClosest(trimmed, HUD_PRESETS);
+        throw new CliError(`"${trimmed}" is not a preset name, JSON object, @file, or null. `
+            + `Presets: ${HUD_PRESETS.join(', ')}.${close ? ` Closest match: "${close}".` : ''}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch (error) {
+        throw new CliError(`Not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new CliError('Expected a JSON object (the theme, or a merge patch in the theme\'s shape).');
+    }
+    return { kind: 'object', value: parsed };
+}
+/** Validation failure formatted the way every issue leaves this command. */
+function rejected(errors) {
+    const lines = errors.map(e => `  ${e.path}: ${e.message}${e.suggestion ? ` (${e.suggestion})` : ''}`);
+    return new CliError(`Theme rejected — nothing was written:\n${lines.join('\n')}`);
+}
+/** `set`: full replace with a preset name, inline object, or null. */
+export function prepareSet(argument, current) {
+    if (argument.kind === 'reset') {
+        // RESET writes the default tokens INLINE rather than clearing the key.
+        // `null` cannot be stored: the GameData schema types worldProfileData.hud.theme
+        // as anyOf [string, object] (shared/world-forger .../game-data-schema.ts), so the
+        // applier's post-write schema gate rejects it and nothing lands. Deleting the key
+        // is not available either — `remove` in both world.json editors filters ARRAY
+        // entries by predicate and cannot drop an object key. Writing the default tokens
+        // is schema-valid and renders the identical default look; the difference is that
+        // the values are now explicit, which also means an agent can read and patch them.
+        const tokens = structuredClone(DEFAULT_THEME_TOKENS);
+        return {
+            value: tokens,
+            effective: tokens,
+            baseLabel: 'the engine default look (reset)',
+            warnings: [],
+        };
+    }
+    if (argument.kind === 'preset') {
+        return {
+            value: argument.name,
+            effective: presetTheme(argument.name),
+            baseLabel: `preset ${argument.name}`,
+            warnings: [],
+        };
+    }
+    const theme = structuredClone(argument.value);
+    const result = validateThemeStrict(theme);
+    if (!result.ok) {
+        // The one mistake worth a dedicated redirect: a partial object passed to
+        // `set` where `patch` was meant.
+        const errors = result.errors.map(e => e.message.includes('required')
+            ? { ...e, suggestion: `${e.suggestion ? `${e.suggestion} ` : ''}If you meant to change just these fields, use \`bitmagic theme patch\` — set replaces the whole theme.` }
+            : e);
+        throw rejected(errors);
+    }
+    void current;
+    return { value: theme, effective: theme, baseLabel: 'inline theme', warnings: result.warnings };
+}
+/** `patch`: merge onto the current effective theme, validate the whole result. */
+export function preparePatch(patch, current) {
+    const base = structuredClone(current.effective);
+    // A stored custom base may carry pre-strict-era leaves the engine already
+    // ignores (unknown color tokens, bad per-element leaves). Left in place they
+    // would fail validation of the merged result at paths the patch never
+    // touched — prune them with a warning instead; they render as nothing today,
+    // so removing them changes no pixels. Same behaviour as the hosted tool.
+    const prunedWarnings = [];
+    if (current.kind === 'custom') {
+        const baseCheck = validateThemeStrict(structuredClone(base));
+        for (const issue of baseCheck.errors) {
+            if (deleteAtPath(base, issue.path)) {
+                prunedWarnings.push({
+                    path: issue.path,
+                    message: `pre-existing issue in the stored theme (${issue.message}) — the engine was already ignoring this leaf; it was removed so your patch could apply`,
+                });
+            }
+        }
+    }
+    const merged = applyMergePatch(base, patch);
+    const result = validateThemeStrict(merged);
+    if (!result.ok)
+        throw rejected(result.errors);
+    return {
+        value: merged,
+        effective: merged,
+        baseLabel: `${current.label} + patch`,
+        warnings: [...prunedWarnings, ...result.warnings],
+    };
+}
+/** The report both lanes print — identical text to the hosted tool's. */
+export function themeReport(prepared, before) {
+    return buildThemeReport(prepared.effective, {
+        before: before.effective,
+        baseLabel: prepared.baseLabel,
+    });
+}
+/** `check`/`show`: verdict + report for what is stored right now. */
+export function checkStoredTheme(current) {
+    if (current.kind === 'unknown-preset') {
+        const close = typeof current.stored === 'string'
+            ? suggestClosest(current.stored, HUD_PRESETS)
+            : undefined;
+        return {
+            valid: false,
+            problems: [
+                `hud.theme is "${String(current.stored)}", which is not a preset — the game silently renders the default look.`
+                    + `${close ? ` Closest match: "${close}".` : ''} Presets: ${HUD_PRESETS.join(', ')}.`,
+            ],
+            report: buildThemeReport(current.effective, { baseLabel: current.label }),
+        };
+    }
+    if (current.kind === 'custom') {
+        const probe = structuredClone(current.effective);
+        const result = validateThemeStrict(probe);
+        // Only ENGINE-FATAL errors mean the theme will not apply. The strict
+        // validator also errors on leaves the engine warn-and-drops (per-element
+        // colors/shape/font) or ignores outright (unknown color tokens) — the
+        // theme renders fine minus those, and failing `check` over them blocks a
+        // working theme in CI and misleads agents into repairing it.
+        const fatal = result.errors.filter(isEngineFatalIssue);
+        const droppable = result.errors.filter(e => !isEngineFatalIssue(e));
+        const format = (e) => `${e.path}: ${e.message}${e.suggestion ? ` (${e.suggestion})` : ''}`;
+        return {
+            valid: fatal.length === 0,
+            problems: [
+                ...fatal.map(format),
+                ...droppable.map(e => `${format(e)} [leaf issue — the engine drops this leaf and still renders the theme]`),
+            ],
+            report: buildThemeReport(current.effective, { baseLabel: current.label }),
+        };
+    }
+    return {
+        valid: true,
+        problems: [],
+        report: buildThemeReport(current.effective, { baseLabel: current.label }),
+    };
+}
+//# sourceMappingURL=theme-io.js.map

package/dist/theme/theme-io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-io.js","sourceRoot":"","sources":["../../src/theme/theme-io.ts"],"names":[],"mappings":"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"}

package/dist/theme/theme-merge.d.ts

@@ -0,0 +1,36 @@
+/**
+ * RFC 7386 JSON merge patch, for HUD theme edits.
+ *
+ * Why merge patch and not path-based `{path, value}` edits: a merge patch IS
+ * the theme's own shape — `{ colors: { primary: "#FF8800" } }` — so the model
+ * emits the one notation it already knows from reading themes, instead of
+ * inventing dotted path strings it can typo. Deletion is `null` at the key
+ * (RFC 7386), which is how "remove the outline" and "clear glowColor" are
+ * expressed without a second vocabulary.
+ *
+ * The patch applies to a base and the MERGED result is validated as a whole
+ * theme, so a patch can never sneak an invalid leaf past the checks that a
+ * full write would catch.
+ */
+export declare function applyMergePatch(base: unknown, patch: unknown): unknown;
+export interface ThemeDiffEntry {
+    path: string;
+    from: unknown;
+    to: unknown;
+}
+/**
+ * Leaf-level differences between two themes, as dotted paths. Feeds the
+ * report's `changed:` line — the model's confirmation of what its edit
+ * actually did (and, on a full replace, of everything it changed without
+ * meaning to).
+ */
+export declare function diffThemes(before: unknown, after: unknown, prefix?: string): ThemeDiffEntry[];
+/**
+ * Delete the leaf at a dotted validator path ("elements.healthBar.colors.background").
+ * Returns false when the path does not resolve — the caller then leaves the
+ * error in place rather than pretending it fixed something. Companion to the
+ * patch flows: a STORED base can carry pre-strict-era leaves the engine already
+ * ignores, and pruning them (with a warning) is what lets an unrelated patch
+ * apply instead of failing at paths it never touched.
+ */
+export declare function deleteAtPath(target: Record<string, unknown>, dottedPath: string): boolean;

package/dist/theme/theme-merge.js

@@ -0,0 +1,81 @@
+/**
+ * RFC 7386 JSON merge patch, for HUD theme edits.
+ *
+ * Why merge patch and not path-based `{path, value}` edits: a merge patch IS
+ * the theme's own shape — `{ colors: { primary: "#FF8800" } }` — so the model
+ * emits the one notation it already knows from reading themes, instead of
+ * inventing dotted path strings it can typo. Deletion is `null` at the key
+ * (RFC 7386), which is how "remove the outline" and "clear glowColor" are
+ * expressed without a second vocabulary.
+ *
+ * The patch applies to a base and the MERGED result is validated as a whole
+ * theme, so a patch can never sneak an invalid leaf past the checks that a
+ * full write would catch.
+ */
+export function applyMergePatch(base, patch) {
+    // Per RFC 7386: a non-object patch replaces the target outright.
+    if (typeof patch !== 'object' || patch === null || Array.isArray(patch))
+        return patch;
+    const target = typeof base === 'object' && base !== null && !Array.isArray(base)
+        ? { ...base }
+        : {};
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === null) {
+            delete target[key];
+        }
+        else {
+            target[key] = applyMergePatch(target[key], value);
+        }
+    }
+    return target;
+}
+/**
+ * Leaf-level differences between two themes, as dotted paths. Feeds the
+ * report's `changed:` line — the model's confirmation of what its edit
+ * actually did (and, on a full replace, of everything it changed without
+ * meaning to).
+ */
+export function diffThemes(before, after, prefix = '') {
+    if (Object.is(before, after))
+        return [];
+    const bothObjects = typeof before === 'object' && before !== null && !Array.isArray(before)
+        && typeof after === 'object' && after !== null && !Array.isArray(after);
+    if (!bothObjects) {
+        // Arrays and scalars diff as one leaf; deep-equal arrays are not a change.
+        if (JSON.stringify(before) === JSON.stringify(after))
+            return [];
+        return [{ path: prefix || '(root)', from: before, to: after }];
+    }
+    const b = before;
+    const a = after;
+    const out = [];
+    for (const key of new Set([...Object.keys(b), ...Object.keys(a)])) {
+        const childPrefix = prefix ? `${prefix}.${key}` : key;
+        out.push(...diffThemes(b[key], a[key], childPrefix));
+    }
+    return out;
+}
+/**
+ * Delete the leaf at a dotted validator path ("elements.healthBar.colors.background").
+ * Returns false when the path does not resolve — the caller then leaves the
+ * error in place rather than pretending it fixed something. Companion to the
+ * patch flows: a STORED base can carry pre-strict-era leaves the engine already
+ * ignores, and pruning them (with a warning) is what lets an unrelated patch
+ * apply instead of failing at paths it never touched.
+ */
+export function deleteAtPath(target, dottedPath) {
+    const segments = dottedPath.split('.');
+    let node = target;
+    for (const segment of segments.slice(0, -1)) {
+        const next = node[segment];
+        if (typeof next !== 'object' || next === null || Array.isArray(next))
+            return false;
+        node = next;
+    }
+    const leaf = segments[segments.length - 1];
+    if (leaf === undefined || !(leaf in node))
+        return false;
+    delete node[leaf];
+    return true;
+}
+//# sourceMappingURL=theme-merge.js.map

package/dist/theme/theme-merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-merge.js","sourceRoot":"","sources":["../../src/theme/theme-merge.ts"],"names":[],"mappings":"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"}

package/dist/theme/theme-report.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The text report that rides every successful theme read/write — the model's
+ * eyes. An LLM cannot see the rendered HUD, so the one moment it can learn
+ * "your literal value will not render" or "your edit also changed X" is inside
+ * the tool response, in text, immediately.
+ *
+ * Two sections:
+ *   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.
+ *
+ * Deliberately report-only: the engine self-heals every pairing marked
+ * SUBSTITUTED, so nothing here blocks a write. The report exists so the agent
+ * can decide whether the substitute serves the user's ask — a lime accent that
+ * renders as forest green might be exactly right, or reason to pick a colour
+ * the ground can carry.
+ */
+export interface ThemeReportOptions {
+    /** The theme before this write, for the diff section. Omit for read-only reports. */
+    before?: unknown;
+    /** How the written theme was produced, e.g. `preset rift-raider + patch`. */
+    baseLabel: string;
+}
+export declare function buildThemeReport(after: unknown, options: ThemeReportOptions): string;

package/dist/theme/theme-report.js

@@ -0,0 +1,142 @@
+/**
+ * The text report that rides every successful theme read/write — the model's
+ * eyes. An LLM cannot see the rendered HUD, so the one moment it can learn
+ * "your literal value will not render" or "your edit also changed X" is inside
+ * the tool response, in text, immediately.
+ *
+ * Two sections:
+ *   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.
+ *
+ * Deliberately report-only: the engine self-heals every pairing marked
+ * SUBSTITUTED, so nothing here blocks a write. The report exists so the agent
+ * can decide whether the substitute serves the user's ask — a lime accent that
+ * 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}$/;
+const MAX_DIFF_LINES = 12;
+function hex(value) {
+    return typeof value === 'string' && HEX.test(value) ? value : null;
+}
+function ratio(a, b) {
+    return `${(Math.round(contrastRatio(a, b) * 10) / 10).toFixed(1)}:1`;
+}
+function formatValue(v) {
+    if (typeof v === 'string')
+        return v;
+    if (typeof v === 'number' || typeof v === 'boolean')
+        return String(v);
+    if (v === undefined)
+        return '(absent)';
+    const json = JSON.stringify(v) ?? '(absent)';
+    return json.length > 40 ? `${json.slice(0, 37)}…` : json;
+}
+function formatDiff(entries) {
+    if (entries.length === 0)
+        return 'changed: nothing — the write produced the same theme';
+    const shown = entries.slice(0, MAX_DIFF_LINES)
+        .map(e => `${e.path} ${formatValue(e.from)}→${formatValue(e.to)}`);
+    const more = entries.length > MAX_DIFF_LINES ? `; +${entries.length - MAX_DIFF_LINES} more` : '';
+    return `changed: ${shown.join('; ')}${more}`;
+}
+function pair(label, ink, ground, substituted) {
+    const shown = substituted ?? ink;
+    const verdict = substituted === null ? 'OK' : `SUBSTITUTED -> renders ${substituted}`;
+    return { label, detail: `${ratio(shown, ground)} ${verdict}` };
+}
+function contrastSection(theme) {
+    const c = theme.colors ?? {};
+    const background = hex(c.background);
+    const surface = hex(c.surface);
+    const text = hex(c.text);
+    const textMuted = hex(c.textMuted);
+    const primary = hex(c.primary);
+    const danger = hex(c.danger);
+    const pairings = [];
+    if (text !== null && surface !== null) {
+        const derived = inkOnSurface(surface, text);
+        pairings.push(pair('text on elements', text, surface, derived === text ? null : derived));
+    }
+    if (textMuted !== null && surface !== null) {
+        const derived = mutedInkOnSurface(surface, textMuted);
+        pairings.push(pair('muted text on elements', textMuted, surface, derived === textMuted ? null : derived));
+    }
+    if (text !== null && background !== null) {
+        // The ground pairing has no engine substitute — `text` IS the ground ink —
+        // so a low value here is the one the agent must fix by hand.
+        const r = contrastRatio(text, background);
+        pairings.push({
+            label: 'text on panels',
+            detail: `${ratio(text, background)} ${r >= 4.5 ? 'OK' : 'LOW — no auto-fix for this pairing; adjust colors.text or colors.background'}`,
+        });
+    }
+    if (primary !== null) {
+        // The engine picks the label by luminance threshold, not by best
+        // contrast, so mid-luminance fills (a strong orange, a mid blue) can
+        // land the label on the LOW side. That is what will render — surface
+        // it instead of blessing it. 3:1 is the large-text floor; button
+        // labels are display-scale.
+        const label = readableTextColor(primary);
+        const r = contrastRatio(label, primary);
+        pairings.push({
+            label: `button label (auto ${label} on primary)`,
+            detail: `${ratio(label, primary)} ${r >= 3 ? 'OK' : 'LOW — the auto label lands on the low-contrast side of this fill; nudge colors.primary lighter or darker so the derived label clears'}`,
+        });
+    }
+    if (primary !== null && background !== null) {
+        const derived = accentInkOn(background, primary);
+        pairings.push(pair('primary as heading/type', primary, background, derived));
+    }
+    if (danger !== null && background !== null) {
+        const derived = accentInkOn(background, danger);
+        pairings.push(pair('danger as error text', danger, background, derived));
+    }
+    if (primary !== null) {
+        // Bar fill against its trough. Nothing engine-side heals this pairing, so
+        // it is advisory: below 2:1 a fill cannot be told from its own channel.
+        const trough = hex(theme.elements?.progressBar?.colors?.background) ?? background;
+        if (trough !== null) {
+            const r = contrastRatio(primary, trough);
+            pairings.push({
+                label: 'bar fill vs its track',
+                detail: `${ratio(primary, trough)} ${r >= 2 ? 'OK' : 'LOW — the fill will blend into its track; darken the track via elements.progressBar.colors.background'}`,
+            });
+        }
+    }
+    const healthTrough = hex(theme.elements?.healthBar?.colors?.background);
+    const healthDanger = hex(theme.elements?.healthBar?.colors?.danger) ?? danger;
+    if (healthTrough !== null && healthDanger !== null) {
+        const r = contrastRatio(healthDanger, healthTrough);
+        pairings.push({
+            label: 'healthBar critical fill vs its track',
+            detail: `${ratio(healthDanger, healthTrough)} ${r >= 2 ? 'OK' : 'LOW'}`,
+        });
+    }
+    if (pairings.length === 0)
+        return [];
+    const width = Math.max(...pairings.map(p => p.label.length));
+    return ['contrast:', ...pairings.map(p => `  ${p.label.padEnd(width)}  ${p.detail}`)];
+}
+export function buildThemeReport(after, options) {
+    const theme = (typeof after === 'object' && after !== null ? after : {});
+    const name = typeof theme.name === 'string' ? theme.name : '(unnamed)';
+    const lines = [];
+    const diff = options.before === undefined ? null : diffThemes(options.before, after);
+    lines.push(`theme: "${name}" (${options.baseLabel}${diff ? `, ${diff.length} change${diff.length === 1 ? '' : 's'}` : ''})`);
+    if (diff)
+        lines.push(formatDiff(diff));
+    lines.push(...contrastSection(theme));
+    if (lines.some(l => l.includes('SUBSTITUTED'))) {
+        lines.push('SUBSTITUTED = the engine will not render your literal value there; it derives the shown replacement. Patch the colour only if the substitute is wrong for the ask.');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=theme-report.js.map

package/dist/theme/theme-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-report.js","sourceRoot":"","sources":["../../src/theme/theme-report.ts"],"names":[],"mappings":"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"}

package/dist/theme/theme-stored.d.ts

@@ -0,0 +1,21 @@
+/**
+ * One resolver for "what does this stored hud.theme value render as" — the
+ * 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.
+ */
+export interface ResolvedStoredTheme {
+    kind: 'preset' | 'custom' | 'none' | 'unknown-preset';
+    /** The tokens the engine renders for this stored value. */
+    tokens: Record<string, unknown>;
+    /** Human-readable description of where `tokens` came from. */
+    label: string;
+}
+/** Resolve a raw `worldProfileData.hud.theme` value to what the engine renders. */
+export declare function resolveStoredTheme(stored: unknown): ResolvedStoredTheme;

package/dist/theme/theme-stored.js

@@ -0,0 +1,50 @@
+/**
+ * One resolver for "what does this stored hud.theme value render as" — the
+ * 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.
+ */
+import { DEFAULT_THEME_TOKENS, HUD_PRESETS, presetTheme } from './hud-theme-catalog.js';
+/** Resolve a raw `worldProfileData.hud.theme` value to what the engine renders. */
+export function resolveStoredTheme(stored) {
+    if (stored === undefined || stored === null) {
+        return {
+            kind: 'none',
+            tokens: structuredClone(DEFAULT_THEME_TOKENS),
+            label: 'the engine default (no theme set)',
+        };
+    }
+    if (typeof stored === 'string') {
+        if (HUD_PRESETS.includes(stored)) {
+            return {
+                kind: 'preset',
+                tokens: presetTheme(stored),
+                label: `preset ${stored}`,
+            };
+        }
+        return {
+            kind: 'unknown-preset',
+            tokens: structuredClone(DEFAULT_THEME_TOKENS),
+            label: `the engine default (unknown preset "${stored}")`,
+        };
+    }
+    if (typeof stored === 'object' && !Array.isArray(stored)) {
+        return {
+            kind: 'custom',
+            tokens: stored,
+            label: 'the current custom theme',
+        };
+    }
+    return {
+        kind: 'unknown-preset',
+        tokens: structuredClone(DEFAULT_THEME_TOKENS),
+        label: `the engine default (hud.theme has unexpected type ${typeof stored})`,
+    };
+}
+//# sourceMappingURL=theme-stored.js.map

package/dist/theme/theme-stored.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-stored.js","sourceRoot":"","sources":["../../src/theme/theme-stored.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,WAAW,EAAsB,MAAM,wBAAwB,CAAC;AAU5G,mFAAmF;AACnF,MAAM,UAAU,kBAAkB,CAAC,MAAe;IAC9C,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QAC1C,OAAO;YACH,IAAI,EAAE,MAAM;YACZ,MAAM,EAAE,eAAe,CAAC,oBAAoB,CAA4B;YACxE,KAAK,EAAE,mCAAmC;SAC7C,CAAC;IACN,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC7B,IAAK,WAAqC,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1D,OAAO;gBACH,IAAI,EAAE,QAAQ;gBACd,MAAM,EAAE,WAAW,CAAC,MAAuB,CAAC;gBAC5C,KAAK,EAAE,UAAU,MAAM,EAAE;aAC5B,CAAC;QACN,CAAC;QACD,OAAO;YACH,IAAI,EAAE,gBAAgB;YACtB,MAAM,EAAE,eAAe,CAAC,oBAAoB,CAA4B;YACxE,KAAK,EAAE,uCAAuC,MAAM,IAAI;SAC3D,CAAC;IACN,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACvD,OAAO;YACH,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,MAAiC;YACzC,KAAK,EAAE,0BAA0B;SACpC,CAAC;IACN,CAAC;IACD,OAAO;QACH,IAAI,EAAE,gBAAgB;QACtB,MAAM,EAAE,eAAe,CAAC,oBAAoB,CAA4B;QACxE,KAAK,EAAE,qDAAqD,OAAO,MAAM,GAAG;KAC/E,CAAC;AACN,CAAC"}

package/dist/theme/theme-validate.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The strict write-time HUD theme validator.
+ *
+ * STRICTER than the engine's load-time validator on purpose, and that asymmetry
+ * is the design: at WRITE time a bad per-element leaf is an error the agent can
+ * fix in the same turn, while at LOAD time the engine must keep rendering
+ * already-published themes, so it warns and drops the leaf instead. Everything
+ * this validator accepts, the engine accepts; the reverse is not required.
+ *
+ * This replaced `lightValidateTheme`, which skipped glow keys, every numeric
+ * range, the whole `elements` block, decoration slot suitability and decoration
+ * size/position/repeat — six ways a theme could pass the write tool and then
+ * silently render as the DEFAULT look at engine load, which reads as "theming
+ * is broken" rather than "the value was wrong". Parity with the engine is
+ * enforced by scripts/check-hud-catalog.ts, which runs both validators over a
+ * fixture corpus under tsx and compares verdicts.
+ *
+ * Validation rules mirror game/src/engine/hud/validateTheme.ts; vocabulary
+ * comes from the drift-checked catalog next door.
+ */
+import { type CatalogValidationIssue } from './hud-theme-catalog.js';
+export interface StrictValidationResult {
+    ok: boolean;
+    errors: CatalogValidationIssue[];
+    warnings: CatalogValidationIssue[];
+}
+export declare function suggestClosest(value: string, candidates: ReadonlyArray<string>): string | undefined;
+/**
+ * Whether an issue would make the ENGINE reject the whole theme, or only drop a
+ * leaf while the theme keeps rendering.
+ *
+ * This validator is deliberately stricter than the engine at two spots, and the
+ * difference matters when DESCRIBING a stored theme: per-element
+ * font/colors/shape leaves are warn-and-dropped at engine load (the theme still
+ * renders minus the leaf), and unknown top-level color tokens are ignored
+ * outright. Telling a user "the engine is falling back to the default look"
+ * over one droppable leaf describes a fallback that is not happening — and an
+ * agent acting on that "repairs" a theme the user is actually seeing.
+ */
+export declare function isEngineFatalIssue(issue: CatalogValidationIssue): boolean;
+export declare function validateThemeStrict(theme: unknown): StrictValidationResult;