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

package/dist/{theme/theme-color-math.js → vendor/hud-theme/engine/hud/colorMath.js}

@@ -1,15 +1,15 @@
 /**
- * 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.
+ * The WCAG colour arithmetic behind the derived HUD inks — relative luminance,
+ * contrast ratios, and the substitution rules that make `--hud-color-on-surface`,
+ * `--hud-color-accent-ink` and friends safe to derive.
  *
- * 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.
+ * A separate module for one load-bearing reason: it is PURE. No DOM, and nothing
+ * outside `engine/hud/` — so `@bitmagic/hud-theme` compiles this exact file and
+ * the theme report the agent and the CLI print computes its contrast pairings
+ * with the arithmetic the engine applies. A SUBSTITUTED line in that report is a
+ * promise about what will render, not an estimate.
  */
+import { isHexColor } from './ThemeTokens.js';
 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)
@@ -30,7 +30,7 @@ export function mixHex(from, to, amount) {
     return `#${channel(1)}${channel(3)}${channel(5)}`;
 }
 export function readableTextColor(hex) {
-    if (!/^#[0-9a-fA-F]{6}$/.test(hex))
+    if (!isHexColor(hex))
         return '#ffffff';
     return relLuminance(hex) > 0.5 ? '#000000' : '#ffffff';
 }
@@ -54,7 +54,7 @@ export function readableTextColor(hex) {
 // 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))
+    if (!isHexColor(surface) || !isHexColor(preferred))
         return preferred;
     if (contrastRatio(preferred, surface) >= ON_SURFACE_MIN_CONTRAST)
         return preferred;
@@ -66,7 +66,7 @@ export function inkOnSurface(surface, preferred) {
 // 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))
+    if (!isHexColor(ground) || !isHexColor(accent))
         return null;
     if (contrastRatio(accent, ground) >= ACCENT_INK_MIN_CONTRAST)
         return null;
@@ -84,7 +84,7 @@ export function accentInkOn(ground, accent) {
     return readableTextColor(ground);
 }
 export function mutedInkOnSurface(surface, preferred) {
-    if (!/^#[0-9a-fA-F]{6}$/.test(surface) || !/^#[0-9a-fA-F]{6}$/.test(preferred))
+    if (!isHexColor(surface) || !isHexColor(preferred))
         return preferred;
     if (contrastRatio(preferred, surface) >= ON_SURFACE_MIN_CONTRAST)
         return preferred;
@@ -96,4 +96,3 @@ export function mutedInkOnSurface(surface, preferred) {
     // the full ink beside it.
     return mixHex(readableTextColor(surface), surface, 0.78);
 }
-//# sourceMappingURL=theme-color-math.js.map

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

@@ -0,0 +1,179 @@
+// Compact SVGs (each <500 bytes). Color tokens get substituted at apply time.
+const DRIP_BORDER_SVG = `<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>`;
+const PIXEL_CORNERS_SVG = `<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>`;
+const SCANLINE_SVG = `<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>`;
+const VINE_CORNER_SVG = `<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>`;
+const GLOW_AURA_SVG = `<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>`;
+const BRACKET_FRAME_SVG = `<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>`;
+const RIBBON_EDGE_SVG = `<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>`;
+const CIRCUIT_TRACE_SVG = `<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>`;
+// A single soft-edged highlight bowing across the top. The flat-opacity ellipse
+// this replaced had a hard rim, so at any size above a small chip it stopped
+// reading as light and started reading as a grey shape sitting on the element.
+const CANDY_GLOSS_SVG = `<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>`;
+const ORNATE_CORNER_SVG = `<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>`;
+const ROYAL_FRAME_SVG = `<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>`;
+const HAZARD_STRIPES_SVG = `<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>`;
+const PIXEL_FRAME_SVG = `<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>`;
+const GRAIN_TEXTURE_SVG = `<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_DECORATIONS = {
+    'drip-border': {
+        key: 'drip-border',
+        svg: DRIP_BORDER_SVG,
+        suitsSlots: ['borderImage', 'decorationAfter'],
+        borderImage: { borderSlice: 20, repeat: 'repeat' },
+        // Explicit tile width for the same reason as `circuit-trace` below, with
+        // one extra twist: this SVG also carries `preserveAspectRatio="none"`,
+        // so it has no intrinsic RATIO either. Under `background-size: auto`
+        // that resolves to 100% 100% — a single drip motif stretched across the
+        // whole strip, which is the opposite of drips repeating along an edge.
+        // `100%` for the height is deliberate: the strip is 12px and the drips
+        // should fill it.
+        background: { size: '60px 100%', position: 'bottom', repeat: 'repeat-x' },
+        evokes: 'Horror drips on edges',
+    },
+    'pixel-corners': {
+        key: 'pixel-corners',
+        svg: PIXEL_CORNERS_SVG,
+        suitsSlots: ['borderImage'],
+        borderImage: { borderSlice: 4, repeat: 'stretch' },
+        evokes: '8-bit pixel corner brackets',
+    },
+    scanline: {
+        key: 'scanline',
+        svg: SCANLINE_SVG,
+        suitsSlots: ['backdrop'],
+        // Explicit tile size: a viewBox-only SVG has no intrinsic size, so
+        // `auto` scales ONE copy to the element instead of tiling. See the
+        // note on `circuit-trace`.
+        background: { size: '4px 4px', position: 'center', repeat: 'repeat' },
+        evokes: 'CRT scanlines tiled across the surface',
+    },
+    'vine-corner': {
+        key: 'vine-corner',
+        svg: VINE_CORNER_SVG,
+        suitsSlots: ['borderImage', 'decorationBefore'],
+        borderImage: { borderSlice: 20, repeat: 'stretch' },
+        background: { size: 'auto', position: 'bottom-left', repeat: 'no-repeat' },
+        evokes: 'Tropical vines / leaves in corners',
+    },
+    'glow-aura': {
+        key: 'glow-aura',
+        svg: GLOW_AURA_SVG,
+        suitsSlots: ['backdrop', 'decorationBefore', 'decorationAfter'],
+        background: { size: 'cover', position: 'center', repeat: 'no-repeat' },
+        evokes: 'Soft radial glow halo behind the element',
+    },
+    'bracket-frame': {
+        key: 'bracket-frame',
+        svg: BRACKET_FRAME_SVG,
+        suitsSlots: ['borderImage'],
+        borderImage: { borderSlice: 8, repeat: 'stretch' },
+        evokes: 'Sci-fi targeting brackets on each corner',
+    },
+    'ribbon-edge': {
+        key: 'ribbon-edge',
+        svg: RIBBON_EDGE_SVG,
+        suitsSlots: ['decorationAfter', 'decorationBefore'],
+        background: { size: '30px 100%', position: 'bottom', repeat: 'repeat-x' },
+        evokes: 'Bunting / banner saw-tooth edge',
+    },
+    'circuit-trace': {
+        key: 'circuit-trace',
+        svg: CIRCUIT_TRACE_SVG,
+        suitsSlots: ['backdrop'],
+        // The tile size is EXPLICIT, and has to be. An inline SVG carrying only
+        // a `viewBox` has no intrinsic size, so `background-size: auto` does not
+        // mean "32x32" — it scales ONE copy to fill the element. This pattern
+        // shipped that way and drew a handful of giant crosshairs across the
+        // controls overlay instead of a fine circuit texture.
+        //
+        // Any tiling decoration added here needs the same treatment: state the
+        // tile size, or give the SVG width/height attributes.
+        background: { size: '32px 32px', position: 'center', repeat: 'repeat' },
+        evokes: 'PCB / circuit board trace pattern',
+    },
+    'candy-gloss': {
+        key: 'candy-gloss',
+        svg: CANDY_GLOSS_SVG,
+        suitsSlots: ['backdrop', 'decorationBefore'],
+        // A FIXED-HEIGHT band, not `cover` and not `100% 100%`.
+        //
+        // `cover` was the shipped value and was simply wrong: this SVG carries
+        // preserveAspectRatio="none", i.e. it is built to be stretched, while
+        // `cover` honours the viewBox's 100:40 intrinsic ratio. On a tall element
+        // (a CONTROLS panel is ~220px high and ~180 wide) that scaled the image to
+        // 550x220 and centred it, so what you saw was the middle of a hugely
+        // magnified ellipse — a grey blob across the top third of the panel.
+        //
+        // `100% 100%` fixes the blob and is still wrong, because it makes the
+        // highlight a PROPORTION of the element. On that same panel the gloss then
+        // covers the top ~100px and the first rows of key text sit inside it:
+        // measured 2.22:1 and 2.92:1 against the muted label colour. A highlight
+        // is cast by a light source, so its size is set by the light and not by
+        // the object — a fixed band is both the physical answer and the one that
+        // cannot swallow a tall element. 56px reads as a full candy gloss on a
+        // 36-46px chip and as a sheen along the top edge of a panel.
+        background: { size: '100% 56px', position: 'top', repeat: 'no-repeat' },
+        evokes: 'Glossy sugar highlight across the top — candy button shine',
+    },
+    'ornate-corner': {
+        key: 'ornate-corner',
+        svg: ORNATE_CORNER_SVG,
+        suitsSlots: ['borderImage'],
+        borderImage: { borderSlice: 14, repeat: 'stretch' },
+        evokes: 'Gothic filigree corner frame — dark fantasy, dungeon',
+    },
+    'royal-frame': {
+        key: 'royal-frame',
+        svg: ROYAL_FRAME_SVG,
+        suitsSlots: ['borderImage'],
+        borderImage: { borderSlice: 12, repeat: 'stretch' },
+        evokes: 'Double gold-trim picture frame with corner studs — epic fantasy',
+    },
+    'hazard-stripes': {
+        key: 'hazard-stripes',
+        svg: HAZARD_STRIPES_SVG,
+        suitsSlots: ['backdrop'],
+        // Explicit tile size: a viewBox-only SVG has no intrinsic size, so
+        // `auto` scales ONE copy to the element instead of tiling. See the
+        // note on `circuit-trace`.
+        background: { size: '16px 16px', position: 'center', repeat: 'repeat' },
+        evokes: 'Faint diagonal caution stripes — military / sci-fi warning panel',
+    },
+    'pixel-frame': {
+        key: 'pixel-frame',
+        svg: PIXEL_FRAME_SVG,
+        suitsSlots: ['borderImage'],
+        borderImage: { borderSlice: 5, repeat: 'round' },
+        evokes: 'NES dialog double-ring pixel border',
+    },
+    'grain-texture': {
+        key: 'grain-texture',
+        svg: GRAIN_TEXTURE_SVG,
+        suitsSlots: ['backdrop'],
+        // Explicit tile size: a viewBox-only SVG has no intrinsic size, so
+        // `auto` scales ONE copy to the element instead of tiling. See the
+        // note on `circuit-trace`.
+        background: { size: '40px 40px', position: 'center', repeat: 'repeat' },
+        evokes: 'Subtle parchment / leather grain tooth',
+    },
+};
+// Substitutes `__primary__` / `__danger__` etc. with hex codes from the active theme.
+// Unknown tokens are left as-is so non-token usages of double-underscored strings
+// (none in our SVGs today, but defensive) don't get mangled.
+export function substituteThemeColors(svg, colors) {
+    return svg.replace(/__([a-zA-Z][a-zA-Z0-9]*)__/g, (match, name) => {
+        const key = name;
+        // `?? match` also covers optional colors (outline): a token for a color the
+        // theme doesn't define stays as-is instead of substituting "undefined".
+        const value = Object.prototype.hasOwnProperty.call(colors, key) ? colors[key] : undefined;
+        return value ?? match;
+    });
+}
+// Wraps SVG markup as a CSS url(...) data URI. The encoder uses encodeURIComponent
+// (not base64) because SVG-as-data-URI is smaller that way and renders identically.
+export function svgToDataUri(svg) {
+    const cleaned = svg.replace(/[\r\n]+/g, '').replace(/\s{2,}/g, ' ');
+    return `url("data:image/svg+xml;utf8,${encodeURIComponent(cleaned)}")`;
+}

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

@@ -0,0 +1,147 @@
+export const HUD_FONTS = {
+    'red-hat-display': {
+        key: 'red-hat-display',
+        family: 'Red Hat Display',
+        weights: [300, 400, 500, 700],
+        suitsCase: ['upper', 'normal'],
+        evokes: 'Default Bitmagic — warm, technical, modern sans',
+    },
+    'chakra-petch': {
+        key: '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': {
+        key: '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': {
+        key: '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': {
+        key: 'bebas-neue',
+        family: 'Bebas Neue',
+        weights: [400],
+        suitsCase: ['upper', 'normal'],
+        evokes: 'Tall, bold display — sports, action, news ticker',
+    },
+    'press-start-2p': {
+        key: 'press-start-2p',
+        family: 'Press Start 2P',
+        weights: [400],
+        suitsCase: ['upper', 'normal'],
+        evokes: 'Retro arcade pixel — 8-bit, NES, chiptune',
+    },
+    creepster: {
+        key: 'creepster',
+        family: 'Creepster',
+        weights: [400],
+        suitsCase: ['normal'],
+        evokes: 'Horror, halloween, dripping — already display-styled',
+    },
+    pacifico: {
+        key: 'pacifico',
+        family: 'Pacifico',
+        weights: [400],
+        suitsCase: ['normal'],
+        evokes: 'Handwritten cursive — tropical, beachy, casual',
+    },
+    'space-grotesk': {
+        key: 'space-grotesk',
+        family: 'Space Grotesk',
+        weights: [400, 500, 700],
+        suitsCase: ['upper', 'normal'],
+        evokes: 'Geometric sans — sci-fi, technical, modern',
+    },
+    'rubik-mono-one': {
+        key: 'rubik-mono-one',
+        family: 'Rubik Mono One',
+        weights: [400],
+        suitsCase: ['upper', 'normal'],
+        evokes: 'Heavy, slabby display — bold, blocky, attention-grabbing',
+    },
+    vt323: {
+        key: 'vt323',
+        family: 'VT323',
+        weights: [400],
+        suitsCase: ['upper', 'normal'],
+        evokes: 'CRT terminal monospace — retro computer, hacker, glitch',
+    },
+    orbitron: {
+        key: 'orbitron',
+        family: 'Orbitron',
+        weights: [400, 500, 700, 900],
+        suitsCase: ['upper', 'normal'],
+        evokes: 'Futuristic geometric — sci-fi, cyber, racing HUD',
+    },
+    shrikhand: {
+        key: 'shrikhand',
+        family: 'Shrikhand',
+        weights: [400],
+        suitsCase: ['normal'],
+        evokes: 'Italic display — celebratory, party, energetic',
+    },
+    'baloo-2': {
+        key: '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': {
+        key: 'lilita-one',
+        family: 'Lilita One',
+        weights: [400],
+        suitsCase: ['upper', 'normal'],
+        evokes: 'Chunky rounded comic display — cartoon battler, toon town',
+    },
+    fredoka: {
+        key: 'fredoka',
+        family: 'Fredoka',
+        weights: [300, 400, 500, 700],
+        suitsCase: ['upper', 'normal'],
+        evokes: 'Soft rounded bubble sans — candy, casual mobile, sweet',
+    },
+    'grenze-gotisch': {
+        key: 'grenze-gotisch',
+        family: 'Grenze Gotisch',
+        weights: [400, 500, 700, 900],
+        suitsCase: ['normal'],
+        evokes: 'Readable blackletter — dark fantasy, gothic dungeon',
+    },
+    cinzel: {
+        key: 'cinzel',
+        family: 'Cinzel',
+        weights: [400, 500, 700, 900],
+        suitsCase: ['upper', 'normal'],
+        evokes: 'Carved Roman caps — epic fantasy, ancient temple',
+    },
+};
+export const DEFAULT_FONT_STACK_OPTIONS = {
+    fallback: '"Helvetica Neue", Helvetica, Arial, system-ui, sans-serif',
+};
+export function getFontCssStack(key, opts = DEFAULT_FONT_STACK_OPTIONS) {
+    const entry = HUD_FONTS[key];
+    return `"${entry.family}", ${opts.fallback}`;
+}
+// Builds the Google Fonts CSS URL for a single font with the weights the theme needs.
+// Published games only ever load the active theme's font, so this URL is the sole
+// font request on the page.
+export function buildGoogleFontsUrl(key, weights) {
+    const entry = HUD_FONTS[key];
+    const allowed = new Set(entry.weights);
+    const filtered = weights.filter(w => allowed.has(w));
+    const useWeights = filtered.length > 0 ? filtered : entry.weights;
+    const family = entry.family.replace(/ /g, '+');
+    const wtParam = useWeights.length > 0 ? `:wght@${[...useWeights].sort((a, b) => a - b).join(';')}` : '';
+    return `https://fonts.googleapis.com/css2?family=${family}${wtParam}&display=swap`;
+}

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

@@ -0,0 +1,80 @@
+import { BITMAGIC_THEME_DATA } from './themes/bitmagic.js';
+import { RIFT_RAIDER_THEME_DATA } from './themes/rift-raider.js';
+import { VILLAGE_KEEP_THEME_DATA } from './themes/village-keep.js';
+import { NEXUS_THEME_DATA } from './themes/nexus.js';
+import { SIMULATOR_THEME_DATA } from './themes/simulator.js';
+import { RACING_THEME_DATA } from './themes/racing.js';
+import { validateAndResolveTheme } from './validateTheme.js';
+// Built-in theme presets — THE FIVE SELECTABLE STYLES. Each preset's raw data
+// lives in its own TS module (themes/*.ts) and goes through
+// validateAndResolveTheme — so the same path that user themes go through
+// catches preset bugs at engine boot.
+//
+// `bitmagic` is deliberately NOT in this set. It is the engine's DEFAULT/
+// FALLBACK look (what a game with no `hud.theme` — or an invalid one — renders
+// with), exported as DEFAULT_HUD_THEME. Listing it as a preset made every "cycle
+// all styles" feature show six looks and every agent catalogue advertise a
+// style that is really the absence of one.
+//
+// Built-in presets are TS modules, not .json files, because the engine runtime
+// loads modules from /dist/ where tsc doesn't copy non-TS files. User-authored
+// themes ship as theme.json on disk (next to world.json) and are fetched +
+// validated at game load time.
+/** The five selectable presets, in catalogue order. `PresetName` is derived from this list. */
+export const PRESET_NAMES = ['rift-raider', 'village-keep', 'nexus', 'simulator', 'racing'];
+/**
+ * Each preset's RAW data — the inline-theme shape, plus its `evokes` label — before
+ * validation. Tools that patch a preset start from this ("preset X but with orange
+ * accents"): it can be spread, edited and written back as an inline theme.
+ */
+export const PRESET_THEME_DATA = {
+    'rift-raider': RIFT_RAIDER_THEME_DATA,
+    'village-keep': VILLAGE_KEEP_THEME_DATA,
+    nexus: NEXUS_THEME_DATA,
+    simulator: SIMULATOR_THEME_DATA,
+    racing: RACING_THEME_DATA,
+};
+/** The default look's raw data (`bitmagic`) — the patch base when a game sets no theme. */
+export const DEFAULT_THEME_DATA = BITMAGIC_THEME_DATA;
+/**
+ * The one-line mood label each preset carries beside its tokens.
+ *
+ * Exported separately because `evokes` is deliberately NOT part of `ThemeTokens`
+ * — it is authoring metadata for whoever (or whatever) is choosing a preset, not
+ * a rendering token, and `validateAndResolveTheme` drops it on the way through.
+ * The agent's catalogue reads it from here, so a style and its description are
+ * one edit.
+ */
+export const PRESET_EVOKES = {
+    'rift-raider': PRESET_THEME_DATA['rift-raider'].evokes,
+    'village-keep': PRESET_THEME_DATA['village-keep'].evokes,
+    nexus: PRESET_THEME_DATA.nexus.evokes,
+    simulator: PRESET_THEME_DATA.simulator.evokes,
+    racing: PRESET_THEME_DATA.racing.evokes,
+};
+function resolvePreset(raw, name) {
+    const result = validateAndResolveTheme(raw);
+    if (!result.ok) {
+        throw new Error(`Built-in preset "${name}" failed validation: ` +
+            result.errors.map(e => `${e.path}: ${e.message}`).join('; '));
+    }
+    return result.theme;
+}
+/**
+ * The engine's default look — applied when a game sets no `hud.theme`, and the
+ * fallback when a theme is unknown or fails validation. Not a selectable preset.
+ */
+export const BITMAGIC_THEME = resolvePreset(BITMAGIC_THEME_DATA, 'bitmagic');
+export const DEFAULT_HUD_THEME = BITMAGIC_THEME;
+export const RIFT_RAIDER_THEME = resolvePreset(RIFT_RAIDER_THEME_DATA, 'rift-raider');
+export const VILLAGE_KEEP_THEME = resolvePreset(VILLAGE_KEEP_THEME_DATA, 'village-keep');
+export const NEXUS_THEME = resolvePreset(NEXUS_THEME_DATA, 'nexus');
+export const SIMULATOR_THEME = resolvePreset(SIMULATOR_THEME_DATA, 'simulator');
+export const RACING_THEME = resolvePreset(RACING_THEME_DATA, 'racing');
+export const HUD_PRESETS = {
+    'rift-raider': RIFT_RAIDER_THEME,
+    'village-keep': VILLAGE_KEEP_THEME,
+    nexus: NEXUS_THEME,
+    simulator: SIMULATOR_THEME,
+    racing: RACING_THEME,
+};

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

@@ -0,0 +1,66 @@
+import { DEFAULT_HUD_THEME, HUD_PRESETS } from './presets.js';
+import { suggestClosest, validateAndResolveTheme } from './validateTheme.js';
+// Resolve a `hud.theme` value from world.json into a ThemeTokens.
+//
+//   - undefined / null / unknown shape → DEFAULT_HUD_THEME (the engine's default look)
+//   - string matching a preset name    → the preset
+//   - string not matching any preset   → DEFAULT_HUD_THEME + console warning
+//                                        (this includes legacy names such as
+//                                        'bitmagic' and 'horror' — the first
+//                                        IS the default, so it is visually a
+//                                        no-op; the second no longer ships)
+//   - object                           → validateAndResolveTheme(obj). On success,
+//                                        the resolved theme. On failure, DEFAULT_HUD_THEME
+//                                        + console warning that includes field paths.
+//
+// This is the single integration point: don't bypass it. The engine calls it
+// once per loadGame() after world data is parsed. Failures never block the game
+// from loading — a broken theme is recoverable; failing the load is not.
+/**
+ * The marker on every theme-resolution console warning, and the two phrases that say which
+ * failure it was. `bitmagic verify` parses them out of the console (it imports these constants
+ * through `@bitmagic/hud-theme`), and it reads warnings from engines of every vendored version, so
+ * the wording is frozen: never reword these, only append detail after them.
+ */
+export const HUD_THEME_LOG_MARKER = '[HUD]';
+/** The phrase after the marker when `hud.theme` is a string that names no preset. */
+export const HUD_UNKNOWN_PRESET_PHRASE = 'Unknown theme preset';
+/** The phrase after the marker when `hud.theme` is an object the validator rejected. */
+export const HUD_INVALID_THEME_PHRASE = 'Custom theme failed validation';
+function isPresetName(value) {
+    return value in HUD_PRESETS;
+}
+export function resolveWorldTheme(value) {
+    if (value === undefined || value === null)
+        return DEFAULT_HUD_THEME;
+    if (typeof value === 'string') {
+        if (isPresetName(value))
+            return HUD_PRESETS[value];
+        // The closest-match hint catches the two real spelling traps: the
+        // unhyphenated internal style keys (`riftraider`) and plain typos.
+        const close = suggestClosest(value, Object.keys(HUD_PRESETS));
+        console.warn(`${HUD_THEME_LOG_MARKER} ${HUD_UNKNOWN_PRESET_PHRASE} "${value}". Known presets: ${Object.keys(HUD_PRESETS).join(', ')}.`
+            + `${close ? ` Closest match: "${close}".` : ''} Falling back to the default theme.`);
+        return DEFAULT_HUD_THEME;
+    }
+    const result = validateAndResolveTheme(value);
+    // Suggestions ride in parentheses INSIDE each issue. The validator's
+    // `suggestion` field carries the actionable half of every message — the
+    // closest-match name, the font-case remedy — and this warn used to format
+    // only `path: message`, so the hint was computed and then thrown away at
+    // the last hop. This console line is the ONLY channel the CLI lane has
+    // (`bitmagic verify` parses it; there is no write-tool there to return
+    // suggestions), so dropping it here dropped it everywhere.
+    // The marker and the two leading phrases are `bitmagic verify`'s parse
+    // contract (see the constants above) — the suggestion text extends the
+    // detail and must never reword them.
+    const formatIssue = (issue) => `${issue.path}: ${issue.message}${issue.suggestion ? ` (${issue.suggestion})` : ''}`;
+    if (!result.ok) {
+        console.warn(`${HUD_THEME_LOG_MARKER} ${HUD_INVALID_THEME_PHRASE}; falling back to the default theme. Errors:`, result.errors.map(formatIssue).join('; '));
+        return DEFAULT_HUD_THEME;
+    }
+    if (result.warnings.length > 0) {
+        console.warn(`${HUD_THEME_LOG_MARKER} Custom theme has warnings:`, result.warnings.map(formatIssue).join('; '));
+    }
+    return result.theme;
+}

package/dist/vendor/hud-theme/engine/hud/themes/bitmagic.js

@@ -0,0 +1,29 @@
+// Bitmagic theme — the default. Mirrors creator/DESIGN.md (Aquamarine primary,
+// Shocking Pink danger, etc.). Goes through validateAndResolveTheme in presets.ts
+// so any drift between this object and the schema fails at engine boot.
+export const BITMAGIC_THEME_DATA = {
+    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',
+    },
+};

package/dist/vendor/hud-theme/engine/hud/themes/nexus.js

@@ -0,0 +1,69 @@
+// Nexus theme — holographic sci-fi conventions (the "Nexus" kit style):
+// hairline cyan on near-black, chamfer-small radii, wide-tracked tech caps,
+// corner brackets and a circuitry backdrop. Depth is carried by glow alone —
+// hairline PANELS; buttons carry a bevel and a 2px rim. Threat states run orange.
+export const NEXUS_THEME_DATA = {
+    name: 'Nexus',
+    // One-line mood label, read by the agent catalogue so an AI picks the right
+    // preset without trying each one. It lives HERE, beside the tokens it
+    // describes, so that changing the style and changing its description are the
+    // same edit — it drifted badly when it lived only in the agent mirror. The
+    // engine validator ignores unknown top-level keys, so this never reaches
+    // ThemeTokens; `PRESET_EVOKES` in presets.ts is what exposes it.
+    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,
+        // 1.4, not 2.5: orbitron is the widest face in the catalogue and at
+        // 2.5px per glyph a label like "RIFT PROGRESS" nearly fills the corner
+        // anchor budget on a phone, breaking mid-word. Wide tracking also costs
+        // word cohesion at HUD sizes — the opposite defect from the lab's Nexus.
+        trackingLabel: 1.4,
+        outlineWidth: 0,
+    },
+    colors: {
+        primary: '#4FD8E8',
+        danger: '#FF6B4A',
+        warning: '#F0A22E',
+        success: '#6FD9A4',
+        background: '#04070C',
+        surface: '#0A121A',
+        text: '#E6F6FA',
+        // Lifted from '#7EA3B2'. Checked against the panel's LIT header band
+        // rather than its nominal face — a secondary label that clears on the
+        // flat colour can still miss where the face gradient is brightest.
+        textMuted: '#9DBBC8',
+        outline: '#2E9FB5',
+    },
+    shape: {
+        // Buttons are OBJECTS even when the panels are flat: `bevel` paints the
+        // white-top/dark-bottom gradient over buttons, counters and bars, and a
+        // 2px border in colors.outline follows the radius. The plates keep their
+        // hairline language — only the controls gain relief.
+        radiusPill: 6,
+        radiusCard: 4,
+        glow: 'cyan',
+        imageRendering: 'auto',
+        borderWidth: 2,
+        bevel: 0.5,
+    },
+    // NO `controls` backdrop. `circuit-trace` used to sit here and rendered as
+    // GIANT CROSSHAIRS across the controls overlay rather than the fine PCB
+    // texture it is meant to be — see the sizing note on the decoration itself.
+    // The pattern is fixed now, but this style does not need it: the corner
+    // brackets already carry the scanner language, and a texture behind the
+    // control hints competed with the type sitting on top of it.
+    decorations: {
+        progressBar: { borderImage: 'bracket-frame' },
+        counter: { borderImage: 'bracket-frame' },
+        // `backdrop`, not `decorationBefore`. The before/after slots are 12px
+        // strips hung OUTSIDE the element, so what this asked for was a glow
+        // floating above the crosshair rather than around it — and glow-aura's
+        // whole intent is "soft radial glow halo BEHIND the element". It never
+        // showed either way, because the slot itself could not render (see
+        // buildSlotCss), so the mistake was invisible until the slot was fixed.
+        reticle: { backdrop: 'glow-aura' },
+    },
+};