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

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

@@ -0,0 +1,71 @@
+/**
+ * The HUD theme catalog as the tools see it: what `get-hud-catalog` returns, what
+ * `bitmagic theme` offers, and the vocabulary the strict validator checks against.
+ *
+ * Nothing here is a copy. Every list and every value is read from the engine's own
+ * kernel modules (game/src/engine/hud/), which this package compiles, so a preset,
+ * font, decoration, glow key or element class added in the engine reaches the agent
+ * and the CLI with no second edit. The only data authored here is tool-facing prose
+ * (the icon slot descriptions).
+ */
+import { DECORATION_SLOT_KINDS, GLOW_KEYS, HUD_ELEMENT_CLASSES, REQUIRED_THEME_COLOR_KEYS, THEME_COLOR_KEYS, THEME_ICON_KEYS, THEME_SHAPE_KEYS, } from './engine/hud/ThemeTokens.js';
+import { HUD_FONTS } from './engine/hud/fonts.js';
+import { HUD_DECORATIONS } from './engine/hud/decorations.js';
+import { DEFAULT_THEME_DATA, PRESET_NAMES, PRESET_THEME_DATA } from './engine/hud/presets.js';
+export { HUD_FONTS, HUD_DECORATIONS, HUD_ELEMENT_CLASSES };
+/** The five selectable presets, in catalogue order. */
+export const HUD_PRESET_NAMES = PRESET_NAMES;
+export function isHudPresetName(value) {
+    return typeof value === 'string' && PRESET_NAMES.includes(value);
+}
+/**
+ * Each preset's RAW data, the same shape as an inline theme plus its `evokes` label.
+ *
+ * This exists because the promoted customization flow — "preset X but with orange
+ * accents" — needs the preset's real values to patch. Use `presetTheme(name)` rather
+ * than reading this directly: it strips `evokes`, which describes the style rather
+ * than rendering it.
+ */
+export const HUD_PRESET_THEMES = PRESET_THEME_DATA;
+/**
+ * A preset's tokens as a writable inline theme, minus the `evokes` label.
+ *
+ * The intended patch flow: `const base = presetTheme('nexus')`, apply the user's
+ * change, then write the result.
+ */
+export function presetTheme(name) {
+    const { evokes: _evokes, ...tokens } = PRESET_THEME_DATA[name];
+    return structuredClone(tokens);
+}
+/** The one-line mood label per preset — the field an agent picks a preset by. */
+export const HUD_PRESET_INFO = Object.fromEntries(PRESET_NAMES.map((name) => [name, { evokes: PRESET_THEME_DATA[name].evokes }]));
+/**
+ * The engine's DEFAULT theme (bitmagic) as raw data — the base a patch applies to
+ * when the game has no theme set. Deliberately not among the presets: it is the
+ * fallback, not a selectable style.
+ */
+export const DEFAULT_THEME_TOKENS = DEFAULT_THEME_DATA;
+/**
+ * The curated decorations' SVG source, served through `get-hud-catalog`'s
+ * `decorationSvg` input as adaptation reference: an agent authoring a custom inline
+ * decoration copies the closest curated one and edits it.
+ */
+export const HUD_DECORATION_SVGS = Object.fromEntries(Object.entries(HUD_DECORATIONS).map(([key, entry]) => [key, entry.svg]));
+export const HUD_GLOW_KEYS = GLOW_KEYS;
+export const HUD_SHAPE_TOKENS = THEME_SHAPE_KEYS;
+export const HUD_COLOR_TOKENS = THEME_COLOR_KEYS;
+export const HUD_REQUIRED_COLORS = REQUIRED_THEME_COLOR_KEYS;
+export const HUD_DECORATION_SLOTS = DECORATION_SLOT_KINDS;
+const ICON_DESCRIPTIONS = {
+    heart: 'Health label icon (shown next to "HP" on the player health bar). Default: filled heart.',
+    mouse: 'Pointer-lock overlay icon ("Click to play" screen). Default: outlined mouse.',
+    arrow: 'Movement-key arrow used in the controls overlay. ONE SVG — CSS rotates it for down/left/right. Default: thin chevron pointing up.',
+};
+/**
+ * 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 colour, or the `__primary__` / `__danger__` / etc. colour tokens
+ * that decorations use — the engine substitutes them at apply time.
+ */
+export const HUD_ICON_SLOTS = THEME_ICON_KEYS.map((key) => ({ key, description: ICON_DESCRIPTIONS[key] }));
+export const HUD_ICON_KEYS = THEME_ICON_KEYS;

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

@@ -0,0 +1,115 @@
+// HUD theme tokens: the theme types, and the source of truth for what validateTheme accepts.
+// Authoring rules: engine/CLAUDE.md says option fields are required + use DEFAULT_* constants.
+// Theme JSON has its own validation surface (the schema), so partial-theme inputs are
+// validated separately via validateTheme.ts before being widened into a full theme.
+//
+// Every closed vocabulary is declared ONCE here as a runtime list, and its type is derived
+// from that list. The engine's load-time validator, the strict write-time validator in
+// `@bitmagic/hud-theme` and the agent's catalog tool all read these lists, so a new glow key
+// or element class is one edit. This module and the other DOM-free kernel files (colorMath,
+// fonts, decorations, validateTheme, presets, themes/, resolveWorldTheme) are compiled into
+// that package too, which is why they import nothing outside `engine/hud/` and touch no DOM.
+/** The curated glow keys `shape.glow` accepts. */
+export const GLOW_KEYS = ['aqua', 'pink', 'warm', 'horror-red', 'gold', 'cyan', 'none'];
+export const LABEL_CASES = ['upper', 'normal'];
+export const IMAGE_RENDERINGS = ['auto', 'pixelated'];
+/** The body weights `font.weightBody` accepts. */
+export const FONT_BODY_WEIGHTS = [300, 400, 500, 700];
+/** The heading weights `font.weightHeading` accepts. */
+export const FONT_HEADING_WEIGHTS = [400, 500, 700, 900];
+/** A theme colour: six hex digits with a leading `#`. The one pattern every theme check uses. */
+export const HEX_COLOR = /^#[0-9a-fA-F]{6}$/;
+export function isHexColor(value) {
+    return typeof value === 'string' && HEX_COLOR.test(value);
+}
+/** The longest inline SVG a decoration or icon may carry, in characters. */
+export const MAX_INLINE_SVG_LENGTH = 16384;
+/**
+ * The allowed range of every numeric token, as `[min, max]`. The load-time validator, the
+ * strict write-time validator and the agent's catalog all read this table.
+ */
+export const THEME_NUMBER_RANGES = {
+    trackingLabel: [0, 4],
+    outlineWidth: [0, 3],
+    sizeScale: [0.85, 1.3],
+    radiusPill: [0, 500],
+    radiusCard: [0, 32],
+    borderWidth: [0, 6],
+    bevel: [0, 1],
+    gloss: [0, 1],
+    borderSlice: [0, 200],
+};
+export const BORDER_IMAGE_REPEATS = ['stretch', 'repeat', 'round', 'space'];
+export const BACKGROUND_POSITIONS = [
+    'top', 'top-right', 'right', 'bottom-right', 'bottom', 'bottom-left', 'left', 'top-left', 'center',
+];
+export const BACKGROUND_REPEATS = ['no-repeat', 'repeat', 'repeat-x', 'repeat-y'];
+export const BACKGROUND_SIZE_KEYWORDS = ['cover', 'contain', 'auto'];
+/**
+ * An explicit `background-size` tile: two plain lengths, `<n>px|%` each, decimals allowed.
+ *
+ * Deliberately strict rather than "any CSS length": the value is interpolated straight into a
+ * `background-size:` declaration, so anything that passes is CSS the theme author controls. No
+ * `calc()`, no `var()`, no semicolons.
+ */
+export const BACKGROUND_TILE_SIZE = /^\d{1,4}(?:\.\d{1,2})?(?:px|%) \d{1,4}(?:\.\d{1,2})?(?:px|%)$/;
+/** The HUD element classes a theme can decorate or override per element. */
+export const HUD_ELEMENT_CLASSES = [
+    'progressBar',
+    'healthBar',
+    'counter',
+    'iconText',
+    'timer',
+    'toast',
+    'controls',
+    'reticle',
+    // The touch layer: joystick + on-screen action buttons. Every game must be
+    // mobile-playable, and this is the surface that used to be unreachable by
+    // theming. The base CSS already derives the stick from --hud-color-text and
+    // the buttons from --hud-color-primary/danger/warning, so a per-element
+    // colors override restyles the whole layer with no dedicated tokens.
+    'mobileControls',
+];
+// Key lists for the interfaces above. Each is built from a Record over the interface's keys, so
+// a field added to the interface without reaching its list (or the reverse) fails to compile.
+const COLOR_KEY_SET = {
+    primary: true, danger: true, warning: true, success: true, background: true,
+    surface: true, text: true, textMuted: true, outline: true,
+};
+const SHAPE_KEY_SET = {
+    radiusPill: true, radiusCard: true, glow: true, imageRendering: true,
+    borderWidth: true, bevel: true, gloss: true, glowColor: true,
+};
+const DECORATION_SLOT_SET = {
+    borderImage: true, backdrop: true, decorationBefore: true, decorationAfter: true,
+};
+const ICON_KEY_SET = { heart: true, mouse: true, arrow: true };
+/** Every colour token a theme may set. */
+export const THEME_COLOR_KEYS = Object.keys(COLOR_KEY_SET);
+/** The colour tokens a full theme must set; the rest fall back. */
+export const REQUIRED_THEME_COLOR_KEYS = [
+    'primary', 'danger', 'background', 'surface', 'text',
+];
+/** Every shape token a theme may set. */
+export const THEME_SHAPE_KEYS = Object.keys(SHAPE_KEY_SET);
+/** The decoration slots every element class has. */
+export const DECORATION_SLOT_KINDS = Object.keys(DECORATION_SLOT_SET);
+/** The built-in icons a theme can replace. */
+export const THEME_ICON_KEYS = Object.keys(ICON_KEY_SET);
+export const DEFAULT_THEME_FONT = {
+    key: 'red-hat-display',
+    case: 'upper',
+    weightBody: 400,
+    weightHeading: 700,
+    trackingLabel: 1.4,
+    outlineWidth: 0,
+};
+export const DEFAULT_THEME_SHAPE = {
+    radiusPill: 500,
+    radiusCard: 8,
+    glow: 'aqua',
+    imageRendering: 'auto',
+    borderWidth: 0,
+    bevel: 0,
+    gloss: 0,
+};

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`;
+}