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

package/dist/theme/hud-theme-catalog.js

@@ -0,0 +1,386 @@
+// Agent-side mirror of the engine's HUD theme catalog. Kept in sync by hand —
+// agent tools can't import from `game/src/engine/` because the two projects
+// have separate tsconfig include sets. When you add a font/decoration/preset
+// in `game/src/engine/hud/`, mirror it here so the agent's catalog tool and
+// validator see it.
+//
+// What the agent uses these for:
+//   - `get_hud_catalog` returns this verbatim so the agent can list what's
+//     available without reading source files.
+//   - `write_hud_theme` validates that font/decoration references resolve
+//     against this catalog before writing to world.json.
+//
+// What's NOT here:
+//   - Full theme schema validation (the engine's `resolveWorldTheme` falls
+//     back to the default look with a console warning if a written theme is structurally
+//     bad — that's the safety net).
+//   - Per-decoration SVG markup (not needed at write time).
+export const HUD_PRESETS = [
+    'rift-raider',
+    'village-keep',
+    'nexus',
+    'simulator',
+    'racing',
+];
+// Agent-only choose-metadata: one-line vibe per preset so the agent can match a
+// user's brief to a preset without trial and error (same species as the fonts'
+// `evokes` labels). The engine has no counterpart field — deliberately NOT part
+// of the drift-checked mirror surface.
+/**
+ * The five presets' ACTUAL token values, mirrored from `game/src/engine/hud/themes/*.ts`.
+ *
+ * This exists because the promoted customization flow — "preset X but with
+ * orange accents" — was unimplementable without it. `read-hud-theme` returns a
+ * preset's NAME, `write-hud-theme` does a full replace rather than a merge, and
+ * the engine source that holds the values is not readable from the hosted agent.
+ * So an agent asked to tweak an active preset had nothing to patch and had to
+ * invent a whole theme "in that preset's spirit", which is how a tweak request
+ * silently became a redesign.
+ *
+ * Each entry is the RAW preset data, which is the same shape as an inline theme
+ * — so it can be spread, edited and written straight back through
+ * `write-hud-theme`. Use `presetTheme(name)` rather than reading this directly:
+ * it strips `evokes`, which is authoring metadata and not a theme token.
+ *
+ * Hand-mirrored and drift-checked by `scripts/check-hud-catalog.ts`, which deep
+ * compares every value against the engine modules.
+ */
+export const HUD_PRESET_THEMES = {
+    "rift-raider": {
+        name: 'Rift Raider',
+        evokes: 'Mobile action-RPG — cast-gold medallion frames on dark indigo glass, chunky cream type with a dark ink ring, royal borders (Diablo-style)',
+        font: {
+            key: 'baloo-2',
+            case: 'upper',
+            weightBody: 500,
+            weightHeading: 700,
+            trackingLabel: 0.8,
+            outlineWidth: 2,
+        },
+        colors: {
+            primary: '#F0B23A',
+            danger: '#D6332E',
+            warning: '#E07A28',
+            success: '#5FB35A',
+            background: '#0B0716',
+            surface: '#191228',
+            text: '#FFF6E2',
+            textMuted: '#B9A889',
+            outline: '#5A3D0C',
+        },
+        shape: {
+            radiusPill: 14,
+            radiusCard: 14,
+            glow: 'gold',
+            imageRendering: 'auto',
+            borderWidth: 2,
+            bevel: 0.85,
+        },
+        decorations: {
+            progressBar: {
+                borderImage: 'royal-frame',
+            },
+            healthBar: {
+                borderImage: 'royal-frame',
+            },
+            toast: {
+                borderImage: 'royal-frame',
+            },
+            controls: {
+                backdrop: 'grain-texture',
+            },
+        },
+    },
+    "village-keep": {
+        name: 'Village Keep',
+        evokes: 'Cartoon strategy — light parchment panels with darker moulded HUD chips over a sunny world, candy-green glossy buttons, ink-outlined type, zero glow (Clash-style)',
+        font: {
+            key: 'fredoka',
+            case: 'upper',
+            weightBody: 500,
+            weightHeading: 700,
+            trackingLabel: 0.6,
+            outlineWidth: 2,
+        },
+        colors: {
+            primary: '#9BDB4F',
+            danger: '#FFA898',
+            warning: '#FFC46B',
+            success: '#A5E27E',
+            background: '#E9E1CE',
+            surface: '#6E5C44',
+            text: '#413A2C',
+            textMuted: '#585040',
+            outline: '#3A6212',
+        },
+        shape: {
+            radiusPill: 14,
+            radiusCard: 18,
+            glow: 'none',
+            imageRendering: 'auto',
+            borderWidth: 3,
+            bevel: 0.9,
+        },
+        decorations: {
+            toast: {
+                backdrop: 'candy-gloss',
+            },
+        },
+        elements: {
+            progressBar: {
+                colors: {
+                    background: '#3A3126',
+                },
+            },
+            healthBar: {
+                colors: {
+                    background: '#3A3126',
+                    danger: '#E2452F',
+                    warning: '#E89A2A',
+                },
+            },
+        },
+    },
+    "nexus": {
+        name: 'Nexus',
+        evokes: 'Holographic sci-fi — hairline cyan on near-black, corner brackets, lit teal plate buttons with a graded cyan bezel, depth by glow (Mass Effect-style)',
+        font: {
+            key: 'chakra-petch',
+            case: 'upper',
+            weightBody: 500,
+            weightHeading: 700,
+            trackingLabel: 1.4,
+            outlineWidth: 0,
+        },
+        colors: {
+            primary: '#4FD8E8',
+            danger: '#FF6B4A',
+            warning: '#F0A22E',
+            success: '#6FD9A4',
+            background: '#04070C',
+            surface: '#0A121A',
+            text: '#E6F6FA',
+            textMuted: '#9DBBC8',
+            outline: '#2E9FB5',
+        },
+        shape: {
+            radiusPill: 6,
+            radiusCard: 4,
+            glow: 'cyan',
+            imageRendering: 'auto',
+            borderWidth: 2,
+            bevel: 0.5,
+        },
+        decorations: {
+            progressBar: {
+                borderImage: 'bracket-frame',
+            },
+            counter: {
+                borderImage: 'bracket-frame',
+            },
+            reticle: {
+                backdrop: 'glow-aura',
+            },
+        },
+    },
+    "simulator": {
+        name: 'Simulator',
+        evokes: 'Serious instrument panel — flat slate, hard corners, one azure accent for state, thin meters and a bare dial, no glow or ornament (flight/truck sim)',
+        font: {
+            key: 'ibm-plex-sans',
+            case: 'upper',
+            weightBody: 400,
+            weightHeading: 700,
+            trackingLabel: 0.8,
+            outlineWidth: 0,
+        },
+        colors: {
+            primary: '#2E9BDB',
+            danger: '#C8453F',
+            warning: '#D8A32E',
+            success: '#4E9E57',
+            background: '#0E141B',
+            surface: '#161E27',
+            text: '#DDE5EC',
+            textMuted: '#A2B0BE',
+            outline: '#46586A',
+        },
+        shape: {
+            radiusPill: 4,
+            radiusCard: 2,
+            glow: 'none',
+            imageRendering: 'auto',
+            borderWidth: 1,
+            bevel: 0.35,
+        },
+    },
+    "racing": {
+        name: 'Racing',
+        evokes: 'Motorsport telemetry — white line-art chrome on black with red reserved for state, tall narrow gothic caps, amber caution / green sector',
+        font: {
+            key: 'archivo-narrow',
+            case: 'upper',
+            weightBody: 500,
+            weightHeading: 700,
+            trackingLabel: 1.2,
+            outlineWidth: 0,
+        },
+        colors: {
+            primary: '#E8EDF2',
+            danger: '#FF4D3A',
+            warning: '#FFB000',
+            success: '#22C55E',
+            background: '#07090C',
+            surface: '#0E1319',
+            text: '#F2F5F8',
+            textMuted: '#9BA4AE',
+            outline: '#C9D2DA',
+        },
+        shape: {
+            radiusPill: 4,
+            radiusCard: 2,
+            glow: 'none',
+            imageRendering: 'auto',
+            borderWidth: 2,
+            bevel: 0.5,
+        },
+    },
+};
+/**
+ * A preset's tokens as a writable inline theme — the mirror entry minus the
+ * `evokes` label, which describes the style rather than rendering it.
+ *
+ * The intended patch flow: `const base = presetTheme('nexus')`, apply the user's
+ * change, then `write-hud-theme` the result.
+ */
+export function presetTheme(name) {
+    const { evokes: _evokes, ...tokens } = HUD_PRESET_THEMES[name];
+    return structuredClone(tokens);
+}
+/**
+ * The one-line mood label per preset, DERIVED from the mirrored preset data
+ * above rather than kept as a second hand-written list.
+ *
+ * It used to be an independent map explicitly excluded from the drift gate, on
+ * the grounds that the engine had no counterpart. It then rotted: three of five
+ * labels described styles that had since been retuned, and this is the field an
+ * agent picks a preset BY. The engine presets carry `evokes` beside their tokens
+ * now, so the description and the style are one edit and one check.
+ */
+export const HUD_PRESET_INFO = Object.fromEntries(Object.keys(HUD_PRESET_THEMES).map((n) => [n, { evokes: HUD_PRESET_THEMES[n].evokes }]));
+export const HUD_FONTS = {
+    'red-hat-display': { family: 'Red Hat Display', weights: [300, 400, 500, 700], suitsCase: ['upper', 'normal'], evokes: 'Default Bitmagic — warm, technical, modern sans' },
+    'chakra-petch': { family: 'Chakra Petch', weights: [300, 400, 500, 600, 700], suitsCase: ['upper', 'normal'], evokes: 'Chamfered techno sans — holographic HUD, sci-fi console, cut corners' },
+    'ibm-plex-sans': { family: 'IBM Plex Sans', weights: [300, 400, 500, 600, 700], suitsCase: ['upper', 'normal'], evokes: 'Engineered humanist sans — instrument panel, operator console, tabular data' },
+    'archivo-narrow': { family: 'Archivo Narrow', weights: [400, 500, 600, 700], suitsCase: ['upper', 'normal'], evokes: 'Narrow gothic that keeps its ink — motorsport telemetry, broadcast overlay' },
+    'bebas-neue': { family: 'Bebas Neue', weights: [400], suitsCase: ['upper', 'normal'], evokes: 'Tall, bold display — sports, action, news ticker' },
+    'press-start-2p': { family: 'Press Start 2P', weights: [400], suitsCase: ['upper', 'normal'], evokes: 'Retro arcade pixel — 8-bit, NES, chiptune' },
+    'creepster': { family: 'Creepster', weights: [400], suitsCase: ['normal'], evokes: 'Horror, halloween, dripping — already display-styled' },
+    'pacifico': { family: 'Pacifico', weights: [400], suitsCase: ['normal'], evokes: 'Handwritten cursive — tropical, beachy, casual' },
+    'space-grotesk': { family: 'Space Grotesk', weights: [400, 500, 700], suitsCase: ['upper', 'normal'], evokes: 'Geometric sans — sci-fi, technical, modern' },
+    'rubik-mono-one': { family: 'Rubik Mono One', weights: [400], suitsCase: ['upper', 'normal'], evokes: 'Heavy, slabby display — bold, blocky, attention-grabbing' },
+    'vt323': { family: 'VT323', weights: [400], suitsCase: ['upper', 'normal'], evokes: 'CRT terminal monospace — retro computer, hacker, glitch' },
+    'orbitron': { family: 'Orbitron', weights: [400, 500, 700, 900], suitsCase: ['upper', 'normal'], evokes: 'Futuristic geometric — sci-fi, cyber, racing HUD' },
+    'shrikhand': { family: 'Shrikhand', weights: [400], suitsCase: ['normal'], evokes: 'Italic display — celebratory, party, energetic' },
+    'baloo-2': { family: 'Baloo 2', weights: [400, 500, 600, 700, 800], suitsCase: ['upper', 'normal'], evokes: 'Rounded chunky sans with a real weight range — mobile action-RPG chrome' },
+    'lilita-one': { family: 'Lilita One', weights: [400], suitsCase: ['upper', 'normal'], evokes: 'Chunky rounded comic display — cartoon battler, toon town' },
+    'fredoka': { family: 'Fredoka', weights: [300, 400, 500, 700], suitsCase: ['upper', 'normal'], evokes: 'Soft rounded bubble sans — candy, casual mobile, sweet' },
+    'grenze-gotisch': { family: 'Grenze Gotisch', weights: [400, 500, 700, 900], suitsCase: ['normal'], evokes: 'Readable blackletter — dark fantasy, gothic dungeon' },
+    'cinzel': { family: 'Cinzel', weights: [400, 500, 700, 900], suitsCase: ['upper', 'normal'], evokes: 'Carved Roman caps — epic fantasy, ancient temple' },
+};
+export const HUD_DECORATIONS = {
+    'drip-border': { suitsSlots: ['borderImage', 'decorationAfter'], evokes: 'Horror drips on edges' },
+    'pixel-corners': { suitsSlots: ['borderImage'], evokes: '8-bit pixel corner brackets' },
+    'scanline': { suitsSlots: ['backdrop'], evokes: 'CRT scanlines tiled across the surface' },
+    'vine-corner': { suitsSlots: ['borderImage', 'decorationBefore'], evokes: 'Tropical vines / leaves in corners' },
+    'glow-aura': { suitsSlots: ['backdrop', 'decorationBefore', 'decorationAfter'], evokes: 'Soft radial glow halo behind the element' },
+    'bracket-frame': { suitsSlots: ['borderImage'], evokes: 'Sci-fi targeting brackets on each corner' },
+    'ribbon-edge': { suitsSlots: ['decorationAfter', 'decorationBefore'], evokes: 'Bunting / banner saw-tooth edge' },
+    'circuit-trace': { suitsSlots: ['backdrop'], evokes: 'PCB / circuit board trace pattern' },
+    'candy-gloss': { suitsSlots: ['backdrop', 'decorationBefore'], evokes: 'Glossy sugar highlight across the top — candy button shine' },
+    'ornate-corner': { suitsSlots: ['borderImage'], evokes: 'Gothic filigree corner frame — dark fantasy, dungeon' },
+    'royal-frame': { suitsSlots: ['borderImage'], evokes: 'Double gold-trim picture frame with corner studs — epic fantasy' },
+    'hazard-stripes': { suitsSlots: ['backdrop'], evokes: 'Faint diagonal caution stripes — military / sci-fi warning panel' },
+    'pixel-frame': { suitsSlots: ['borderImage'], evokes: 'NES dialog double-ring pixel border' },
+    'grain-texture': { suitsSlots: ['backdrop'], evokes: 'Subtle parchment / leather grain tooth' },
+};
+// The engine's DEFAULT theme (bitmagic) as raw preset data — the base a patch
+// applies to when the game has no theme set. Mirrors BITMAGIC_THEME_DATA in
+// game/src/engine/hud/themes/bitmagic.ts, drift-checked like the presets. It is
+// deliberately NOT in HUD_PRESET_THEMES: bitmagic is the fallback, not a
+// selectable preset, and listing it would put it back in the catalog the agent
+// offers users.
+export const DEFAULT_THEME_TOKENS = {
+    name: 'Bitmagic',
+    font: {
+        key: 'red-hat-display',
+        case: 'upper',
+        weightBody: 400,
+        weightHeading: 700,
+        trackingLabel: 1.6,
+    },
+    colors: {
+        primary: '#A0DAB9',
+        danger: '#E0218A',
+        warning: '#FF8200',
+        success: '#F9E547',
+        background: '#0b0b0b',
+        surface: '#181818',
+        text: '#ffffff',
+        textMuted: '#b3b3b3',
+    },
+    shape: {
+        radiusPill: 500,
+        radiusCard: 8,
+        glow: 'aqua',
+        imageRendering: 'auto',
+    },
+};
+// The curated decorations' SVG SOURCE, verbatim from game/src/engine/hud/
+// decorations.ts and drift-checked byte-for-byte. Exposed through
+// get-hud-catalog's decorationSvg input as ADAPTATION REFERENCE: an agent
+// authoring a custom inline decoration copies the closest curated one and
+// edits, instead of inventing SVG from nothing — sizing rules included.
+export const HUD_DECORATION_SVGS = {
+    'drip-border': "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 60 60\" preserveAspectRatio=\"none\"><rect x=\"0\" y=\"0\" width=\"60\" height=\"2\" fill=\"__primary__\"/><rect x=\"0\" y=\"0\" width=\"2\" height=\"60\" fill=\"__primary__\"/><rect x=\"58\" y=\"0\" width=\"2\" height=\"60\" fill=\"__primary__\"/><path d=\"M0,58 L60,58 L60,50 Q54,60 48,52 Q42,62 36,53 Q30,64 24,54 Q18,60 12,52 Q6,62 0,52 Z\" fill=\"__primary__\"/></svg>",
+    'pixel-corners': "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 12 12\" shape-rendering=\"crispEdges\"><path d=\"M0,0 H4 V2 H2 V4 H0 Z M8,0 H12 V4 H10 V2 H8 Z M0,8 H2 V10 H4 V12 H0 Z M10,8 H12 V12 H8 V10 H10 Z\" fill=\"__primary__\"/></svg>",
+    'scanline': "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 4 4\" preserveAspectRatio=\"none\"><rect width=\"4\" height=\"1\" fill=\"__primary__\" opacity=\"0.15\"/></svg>",
+    'vine-corner': "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 40 40\"><path d=\"M0,40 Q0,20 8,12 Q16,4 24,8 Q20,16 12,16 Q4,20 4,40 Z\" fill=\"__success__\" opacity=\"0.7\"/><circle cx=\"10\" cy=\"14\" r=\"2\" fill=\"__success__\"/><circle cx=\"16\" cy=\"10\" r=\"1.5\" fill=\"__success__\"/></svg>",
+    'glow-aura': "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 100 100\"><defs><radialGradient id=\"g\"><stop offset=\"0%\" stop-color=\"__primary__\" stop-opacity=\"0.5\"/><stop offset=\"60%\" stop-color=\"__primary__\" stop-opacity=\"0.1\"/><stop offset=\"100%\" stop-color=\"__primary__\" stop-opacity=\"0\"/></radialGradient></defs><rect width=\"100\" height=\"100\" fill=\"url(#g)\"/></svg>",
+    'bracket-frame': "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path d=\"M0,0 H8 V1 H1 V8 H0 Z M16,0 H24 V8 H23 V1 H16 Z M0,16 H1 V23 H8 V24 H0 Z M16,24 V23 H23 V16 H24 V24 Z\" fill=\"__primary__\"/></svg>",
+    'ribbon-edge': "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 30 8\" preserveAspectRatio=\"none\"><path d=\"M0,0 L30,0 L30,4 L26,8 L22,4 L18,8 L14,4 L10,8 L6,4 L2,8 L0,4 Z\" fill=\"__primary__\"/></svg>",
+    'circuit-trace': "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 32 32\"><path d=\"M0,16 H10 M22,16 H32 M16,0 V10 M16,22 V32\" stroke=\"__primary__\" stroke-width=\"1\" fill=\"none\"/><circle cx=\"16\" cy=\"16\" r=\"2\" fill=\"none\" stroke=\"__primary__\" stroke-width=\"1\"/></svg>",
+    'candy-gloss': "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 100 40\" preserveAspectRatio=\"none\"><radialGradient id=\"cgh\" cx=\".5\" cy=\".28\" r=\".72\"><stop offset=\"0\" stop-color=\"#fff\" stop-opacity=\".38\"/><stop offset=\".55\" stop-color=\"#fff\" stop-opacity=\".15\"/><stop offset=\"1\" stop-color=\"#fff\" stop-opacity=\"0\"/></radialGradient><ellipse cx=\"50\" cy=\"8\" rx=\"48\" ry=\"13\" fill=\"url(#cgh)\"/></svg>",
+    'ornate-corner': "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 48 48\"><defs><g id=\"f\"><path d=\"M2 14 Q2 2 14 2\" fill=\"none\" stroke=\"__primary__\" stroke-width=\"2\"/><path d=\"M8 8 L11 5 L14 8 L11 11 Z\" fill=\"__primary__\"/></g></defs><rect x=\"5\" y=\"5\" width=\"38\" height=\"38\" fill=\"none\" stroke=\"__primary__\" stroke-width=\"1.5\"/><use href=\"#f\"/><use href=\"#f\" transform=\"rotate(90 24 24)\"/><use href=\"#f\" transform=\"rotate(180 24 24)\"/><use href=\"#f\" transform=\"rotate(270 24 24)\"/></svg>",
+    'royal-frame': "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 48 48\"><rect x=\"3\" y=\"3\" width=\"42\" height=\"42\" rx=\"6\" fill=\"none\" stroke=\"__primary__\" stroke-width=\"2\"/><rect x=\"8\" y=\"8\" width=\"32\" height=\"32\" rx=\"3\" fill=\"none\" stroke=\"__primary__\" stroke-width=\"1\" opacity=\"0.6\"/><circle cx=\"6\" cy=\"6\" r=\"2.4\" fill=\"__primary__\"/><circle cx=\"42\" cy=\"6\" r=\"2.4\" fill=\"__primary__\"/><circle cx=\"6\" cy=\"42\" r=\"2.4\" fill=\"__primary__\"/><circle cx=\"42\" cy=\"42\" r=\"2.4\" fill=\"__primary__\"/></svg>",
+    'hazard-stripes': "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 16 16\"><path d=\"M-4 4 L4 -4 M0 16 L16 0 M12 20 L20 12\" stroke=\"__warning__\" stroke-width=\"4\" opacity=\"0.12\" fill=\"none\"/></svg>",
+    'pixel-frame': "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 16 16\" shape-rendering=\"crispEdges\"><path fill-rule=\"evenodd\" d=\"M0 0 H16 V16 H0 Z M1 1 V15 H15 V1 Z\" fill=\"__text__\"/><path fill-rule=\"evenodd\" d=\"M3 3 H13 V13 H3 Z M4 4 V12 H12 V4 Z\" fill=\"__primary__\"/></svg>",
+    'grain-texture': "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 40 40\"><g fill=\"__text__\" opacity=\"0.07\"><rect x=\"3\" y=\"5\" width=\"1\" height=\"1\"/><rect x=\"11\" y=\"2\" width=\"1\" height=\"1\"/><rect x=\"19\" y=\"9\" width=\"1\" height=\"1\"/><rect x=\"27\" y=\"4\" width=\"1\" height=\"1\"/><rect x=\"35\" y=\"12\" width=\"1\" height=\"1\"/><rect x=\"6\" y=\"17\" width=\"1\" height=\"1\"/><rect x=\"15\" y=\"22\" width=\"1\" height=\"1\"/><rect x=\"24\" y=\"18\" width=\"1\" height=\"1\"/><rect x=\"33\" y=\"26\" width=\"1\" height=\"1\"/><rect x=\"2\" y=\"29\" width=\"1\" height=\"1\"/><rect x=\"12\" y=\"34\" width=\"1\" height=\"1\"/><rect x=\"22\" y=\"31\" width=\"1\" height=\"1\"/><rect x=\"30\" y=\"37\" width=\"1\" height=\"1\"/><rect x=\"38\" y=\"33\" width=\"1\" height=\"1\"/></g></svg>",
+};
+export const HUD_GLOW_KEYS = ['aqua', 'pink', 'warm', 'horror-red', 'gold', 'cyan', 'none'];
+export const HUD_ELEMENT_CLASSES = ['progressBar', 'healthBar', 'counter', 'iconText', 'timer', 'toast', 'controls', 'reticle', 'mobileControls'];
+// ThemeShape's field names, for the drift gate's membership check — a new shape
+// token added engine-side without reaching this list (and the validator, and
+// get-hud-catalog's ranges) is a loud CI failure instead of a knob agents
+// cannot see.
+export const HUD_SHAPE_TOKENS = ['radiusPill', 'radiusCard', 'glow', 'imageRendering', 'borderWidth', 'bevel', 'gloss', 'glowColor'];
+export const HUD_COLOR_TOKENS = ['primary', 'danger', 'warning', 'success', 'background', 'surface', 'text', 'textMuted', 'outline'];
+export const HUD_REQUIRED_COLORS = ['primary', 'danger', 'background', 'surface', 'text'];
+export const HUD_DECORATION_SLOTS = ['borderImage', 'backdrop', 'decorationBefore', 'decorationAfter'];
+// Built-in icon slots a theme can override with custom SVG markup. Each value
+// is inline SVG (≤16kb). SVGs may use `currentColor` so the icon follows the
+// surrounding text color, OR the same `__primary__` / `__danger__` / etc.
+// color tokens that decorations use — the engine substitutes them at apply time.
+export const HUD_ICON_SLOTS = [
+    { key: 'heart', description: 'Health label icon (shown next to "HP" on the player health bar). Default: filled heart.' },
+    { key: 'mouse', description: 'Pointer-lock overlay icon ("Click to play" screen). Default: outlined mouse.' },
+    { key: 'arrow', description: 'Movement-key arrow used in the controls overlay. ONE SVG — CSS rotates it for down/left/right. Default: thin chevron pointing up.' },
+];
+export const HUD_ICON_KEYS = HUD_ICON_SLOTS.map(s => s.key);
+// The strict validator lives in theme-validate.ts — everything the old
+// lightValidateTheme checked plus glow keys, numeric ranges, the elements
+// block, slot suitability and decoration size/position/repeat. Re-exported
+// under the old name so existing imports keep working; new code should import
+// validateThemeStrict directly.
+export { validateThemeStrict, validateThemeStrict as lightValidateTheme, isEngineFatalIssue, suggestClosest } from './theme-validate.js';
+//# sourceMappingURL=hud-theme-catalog.js.map

package/dist/theme/hud-theme-catalog.js.map

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

package/dist/theme/theme-color-math.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Hand-mirror of game/src/engine/hud/colorMath.ts — the WCAG arithmetic behind
+ * the derived HUD inks. The theme report computes its contrast pairings with
+ * EXACTLY the maths the engine will apply, so a SUBSTITUTED line in the report
+ * is a promise about what will render, not an estimate.
+ *
+ * Mirrored by hand because agent tools cannot import engine source (separate
+ * tsconfig include sets). Drift-checked BEHAVIOURALLY by scripts/
+ * check-hud-catalog.ts: the gate imports both copies under tsx and compares
+ * their outputs over every preset palette plus adversarial pairs, so a changed
+ * threshold or mix factor on either side goes red in CI.
+ */
+export declare function relLuminance(hex: string): number;
+export declare function contrastRatio(a: string, b: string): number;
+export declare function mixHex(from: string, to: string, amount: number): string;
+export declare function readableTextColor(hex: string): string;
+export declare const ON_SURFACE_MIN_CONTRAST = 3;
+export declare function inkOnSurface(surface: string, preferred: string): string;
+export declare const ACCENT_INK_MIN_CONTRAST = 4.5;
+export declare function accentInkOn(ground: string, accent: string): string | null;
+export declare function mutedInkOnSurface(surface: string, preferred: string): string;

package/dist/theme/theme-color-math.js

@@ -0,0 +1,99 @@
+/**
+ * Hand-mirror of game/src/engine/hud/colorMath.ts — the WCAG arithmetic behind
+ * the derived HUD inks. The theme report computes its contrast pairings with
+ * EXACTLY the maths the engine will apply, so a SUBSTITUTED line in the report
+ * is a promise about what will render, not an estimate.
+ *
+ * Mirrored by hand because agent tools cannot import engine source (separate
+ * tsconfig include sets). Drift-checked BEHAVIOURALLY by scripts/
+ * check-hud-catalog.ts: the gate imports both copies under tsx and compares
+ * their outputs over every preset palette plus adversarial pairs, so a changed
+ * threshold or mix factor on either side goes red in CI.
+ */
+export function relLuminance(hex) {
+    const lin = (v) => (v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4));
+    return 0.2126 * lin(parseInt(hex.slice(1, 3), 16) / 255)
+        + 0.7152 * lin(parseInt(hex.slice(3, 5), 16) / 255)
+        + 0.0722 * lin(parseInt(hex.slice(5, 7), 16) / 255);
+}
+export function contrastRatio(a, b) {
+    const la = relLuminance(a);
+    const lb = relLuminance(b);
+    return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+export function mixHex(from, to, amount) {
+    const channel = (i) => {
+        const f = parseInt(from.slice(i, i + 2), 16);
+        const t = parseInt(to.slice(i, i + 2), 16);
+        return Math.round(f * amount + t * (1 - amount)).toString(16).padStart(2, '0');
+    };
+    return `#${channel(1)}${channel(3)}${channel(5)}`;
+}
+export function readableTextColor(hex) {
+    if (!/^#[0-9a-fA-F]{6}$/.test(hex))
+        return '#ffffff';
+    return relLuminance(hex) > 0.5 ? '#000000' : '#ffffff';
+}
+// The ink for anything painted ON `surface`, plus its muted companion.
+//
+// Same species as --hud-color-on-primary: the engine picks the readable pair so a
+// theme author does not have to hand-author contrast per element. It exists
+// because `text` carries TWO jobs that only agree on a uniformly dark theme. It is
+// the ink on the `background` canvas — a game's own dialogs paint themselves with
+// that pair — AND the ink on every counter, timer, toast, bubble and panel filled
+// with `surface`. A style whose big UI is a light canvas and whose HUD furniture is
+// darker cannot satisfy both from one value: with a single ink the furniture caps
+// out around #9E9276, which is 1.4:1 against a sunny world and so not furniture at
+// all. Village Keep spent three rounds oscillating between a washed-out HUD and a
+// uniformly dark one for exactly this reason.
+//
+// It PREFERS the theme's own ink, because a tinted parchment or a cold cyan is part
+// of a style's identity and must survive. It substitutes only where the declared
+// pairing is unusable — below 3:1, the WCAG floor for large text, and far below
+// every pairing in the catalog: the presets measure 9.6 to 17.8 for `text` and 5.7
+// to 9.3 for `textMuted`, so this cannot fire on a theme that was already coherent.
+export const ON_SURFACE_MIN_CONTRAST = 3;
+export function inkOnSurface(surface, preferred) {
+    if (!/^#[0-9a-fA-F]{6}$/.test(surface) || !/^#[0-9a-fA-F]{6}$/.test(preferred))
+        return preferred;
+    if (contrastRatio(preferred, surface) >= ON_SURFACE_MIN_CONTRAST)
+        return preferred;
+    return readableTextColor(surface);
+}
+// Target 4.5:1 rather than the 3:1 the on-surface inks use: this one paints
+// headings and status lines, which are body-scale on some surfaces, and the
+// margin is free — the lowest any shipped preset measures is 6.02:1, so raising
+// the bar cannot make the token fire on a theme that was already fine.
+export const ACCENT_INK_MIN_CONTRAST = 4.5;
+export function accentInkOn(ground, accent) {
+    if (!/^#[0-9a-fA-F]{6}$/.test(ground) || !/^#[0-9a-fA-F]{6}$/.test(accent))
+        return null;
+    if (contrastRatio(accent, ground) >= ACCENT_INK_MIN_CONTRAST)
+        return null;
+    // Walk the accent toward the ground's opposite pole and stop at the FIRST value
+    // that clears, so the result keeps as much of the accent as the ground allows.
+    // Mixing toward black or white preserves the HUE, which is the part that makes
+    // an accent an accent: village-keep's candy lime lands on a forest green rather
+    // than on brown, and a forest green on parchment is what the reference draws.
+    const pole = relLuminance(ground) > 0.5 ? '#000000' : '#ffffff';
+    for (let keep = 0.95; keep > 0.05; keep -= 0.05) {
+        const candidate = mixHex(accent, pole, keep);
+        if (contrastRatio(candidate, ground) >= ACCENT_INK_MIN_CONTRAST)
+            return candidate;
+    }
+    return readableTextColor(ground);
+}
+export function mutedInkOnSurface(surface, preferred) {
+    if (!/^#[0-9a-fA-F]{6}$/.test(surface) || !/^#[0-9a-fA-F]{6}$/.test(preferred))
+        return preferred;
+    if (contrastRatio(preferred, surface) >= ON_SURFACE_MIN_CONTRAST)
+        return preferred;
+    // A secondary label steps BACK toward its own backdrop rather than taking the
+    // full-strength ink — otherwise the substitution would make muted text the
+    // loudest thing on the element it was meant to sit quietly on. 0.78 is the
+    // point where it still clears AA on the lightest surface that can reach this
+    // branch at all (a mid-brown at 4.65:1) while reading as clearly quieter than
+    // the full ink beside it.
+    return mixHex(readableTextColor(surface), surface, 0.78);
+}
+//# sourceMappingURL=theme-color-math.js.map

package/dist/theme/theme-color-math.js.map

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

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

@@ -0,0 +1,49 @@
+import type { JsonObject } from '../project/world-json.js';
+export interface StoredTheme {
+    kind: 'preset' | 'custom' | 'none' | 'unknown-preset';
+    stored: unknown;
+    /** The tokens the engine renders for this stored value. */
+    effective: Record<string, unknown>;
+    /** Human-readable description of where `effective` came from. */
+    label: string;
+}
+/** worldProfileData.hud.theme — the ONLY path the engine reads a theme from. */
+export declare function readStoredTheme(world: JsonObject): StoredTheme;
+/**
+ * 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 declare function parseThemeArgument(raw: string, readFile: (path: string) => string): {
+    kind: 'preset';
+    name: string;
+} | {
+    kind: 'reset';
+} | {
+    kind: 'object';
+    value: Record<string, unknown>;
+};
+export interface PreparedWrite {
+    /** What to store at worldProfileData.hud.theme. */
+    value: unknown;
+    /** The tokens that value renders as (for the report). */
+    effective: Record<string, unknown>;
+    baseLabel: string;
+    warnings: Array<{
+        path: string;
+        message: string;
+        suggestion?: string;
+    }>;
+}
+/** `set`: full replace with a preset name, inline object, or null. */
+export declare function prepareSet(argument: ReturnType<typeof parseThemeArgument>, current: StoredTheme): PreparedWrite;
+/** `patch`: merge onto the current effective theme, validate the whole result. */
+export declare function preparePatch(patch: Record<string, unknown>, current: StoredTheme): PreparedWrite;
+/** The report both lanes print — identical text to the hosted tool's. */
+export declare function themeReport(prepared: PreparedWrite, before: StoredTheme): string;
+/** `check`/`show`: verdict + report for what is stored right now. */
+export declare function checkStoredTheme(current: StoredTheme): {
+    valid: boolean;
+    problems: string[];
+    report: string;
+};