@bitmagic/cli 0.1.59-dev.1 → 0.1.59-dev.3

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;