@jgengine/react 0.10.0 → 0.12.0

package/dist/hudLayout.d.ts

@@ -1,5 +1,6 @@
 import { type CSSProperties, type ReactNode } from "react";
 import { type HudAnchor, type HudLayoutStore } from "@jgengine/core/ui/hudLayout";
+import { type EditorUiDocument } from "@jgengine/core/ui/hudDocument";
 import { type HudPriority, type MobileHudBehavior } from "@jgengine/core/ui/gameLayout";
 import type { GamePhase } from "@jgengine/core/game/gamePhase";
 /** Whether a HUD element opted into `showDuring` is visible in the current phase; `undefined` = always visible (default). */
@@ -14,10 +15,25 @@ export interface HudEditChord {
     hold: string;
     press: string;
 }
+/**
+ * Layout state for `HudCanvas` — panel placements, edit-mode drag/resize, and per-game persistence.
+ *
+ * @capability hud-layout persistent, live-editable HUD panel layout state for `HudCanvas`
+ */
 export declare function useHudLayout(options?: {
     storageKey?: string;
     snap?: number;
     locked?: boolean;
+    /**
+     * Scene-document `ui` section — source of truth for panel placement/size.
+     * When provided, hydrates the layout store (and wins over legacy localStorage).
+     */
+    documentUi?: EditorUiDocument;
+    /**
+     * When true (default), canvas moves/resizes invoke the injected {@link HudLayoutPersist}
+     * port (`HudLayoutPersistProvider` / `onPanelCommit`). No-op when no host has provided one.
+     */
+    documentPatches?: boolean;
 }): HudLayoutStore;
 /**
  * Full-viewport HUD surface. Panels declared with `HudPanel` flow into nine
@@ -25,6 +41,8 @@ export declare function useHudLayout(options?: {
  * offsets, no manual clearance for sibling panels, the touch-control dock
  * (`--jg-hud-dock-clearance`), or device safe areas. On compact displays the
  * whole surface scales down and each panel applies its `compact` behavior.
+  *
+ * @capability hud-canvas the HUD root surface — design-resolution scaling plus live panel-placement editing (F2+C)
  */
 export declare function HudCanvas({ layout, editChord, compactScale, showDuring, className, style, children, }: {
     layout: HudLayoutStore;
@@ -43,8 +61,10 @@ export declare function HudCanvas({ layout, editChord, compactScale, showDuring,
  * pointers panels stay draggable through the edit chord; a dragged panel
  * leaves the flow and keeps its custom placement. On compact displays custom
  * placements are ignored and the `compact` behavior applies.
+  *
+ * @capability hud-panel anchored HUD slot — drop any widget in a named, player-movable panel
  */
-export declare function HudPanel({ id, anchor, order, compact: compactMode, chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region, className, style, children, }: {
+export declare function HudPanel({ id, anchor, order, compact: compactMode, chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region, width, height, type, className, style, children, }: {
     id: string;
     anchor?: HudAnchor;
     /** Stack position within the region, ascending outward from the screen edge. Default 0. */
@@ -55,7 +75,10 @@ export declare function HudPanel({ id, anchor, order, compact: compactMode, chip
     chip?: string;
     /** `false` lets pointer events pass through to the game (read-only panels). Default true. */
     interactive?: boolean;
-    /** Legacy pixel inset from the anchor; only used as the reset placement for dragged panels. */
+    /**
+     * Fallback pixel inset from the anchor when the scene document has no `ui.panels[id]`.
+     * Document layout is the source of truth once authored; TSX props are fallback-only.
+     */
     inset?: {
         x: number;
         y: number;
@@ -73,6 +96,12 @@ export declare function HudPanel({ id, anchor, order, compact: compactMode, chip
     collisionGroup?: string;
     /** Register this panel as a collision-tracked layout region. Default true. */
     region?: boolean;
+    /** Fallback width when the document has not authored a size. */
+    width?: number;
+    /** Fallback height when the document has not authored a size. */
+    height?: number;
+    /** Panel type id ({@link registerHudPanelType}) — drives resize axes + ParamSchema. */
+    type?: string;
     className?: string;
     style?: CSSProperties;
     children?: ReactNode;

package/dist/hudLayout.js

@@ -1,13 +1,15 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { createContext, useContext, useEffect, useMemo, useRef, useState, } from "react";
 import { createPortal } from "react-dom";
-import { HUD_ANCHOR_FRACTIONS, anchoredPlacement, createHudLayout, isPanelDraggable, } from "@jgengine/core/ui/hudLayout";
+import { HUD_ANCHOR_FRACTIONS, anchoredPlacement, createHudLayout, isPanelDraggable, registerActiveHudLayout, } from "@jgengine/core/ui/hudLayout";
+import { resizePanelSize, resolvePanelResize, } from "@jgengine/core/ui/hudDocument";
 import { hudScaleForViewport, overflowingPanels, resolveHudFit } from "@jgengine/core/ui/hudScale";
 import { isMobileMode, } from "@jgengine/core/ui/gameLayout";
 import { useDisplayProfile } from "./display.js";
 import { useEngineState } from "./engineStore.js";
 import { useGameLayoutMode, useRegisterLayoutRegion } from "./gameViewport.js";
 import { useOptionalGamePhase } from "./hooks.js";
+import { useHudLayoutPersist } from "./hudLayoutPersist.js";
 import { useHudViewport } from "./hudViewport.js";
 /** Whether a HUD element opted into `showDuring` is visible in the current phase; `undefined` = always visible (default). */
 export function hudVisibleInPhase(showDuring, phase) {
@@ -20,18 +22,74 @@ const EDIT_BAR_Z = 100000;
 const REGION_GAP = 10;
 const COMPACT_HUD_SCALE = 0.85;
 const HUD_ANCHORS = Object.keys(HUD_ANCHOR_FRACTIONS);
+function sizeStyle(panel) {
+    if (panel === undefined)
+        return {};
+    return {
+        ...(panel.width === undefined ? {} : { width: panel.width }),
+        ...(panel.height === undefined ? {} : { height: panel.height }),
+    };
+}
+function ResizeHandles({ axes, onResizeStart, }) {
+    if (axes === "none")
+        return null;
+    const handle = (edge, cursor, style) => (_jsx("div", { "data-hud-resize": edge, onPointerDown: (event) => {
+            event.stopPropagation();
+            onResizeStart(edge, event);
+        }, style: {
+            position: "absolute",
+            zIndex: 3,
+            pointerEvents: "auto",
+            background: "rgba(255, 255, 255, 0.85)",
+            cursor,
+            ...style,
+        } }, edge));
+    return (_jsxs(_Fragment, { children: [axes === "x" || axes === "both"
+                ? handle("e", "ew-resize", { top: 4, bottom: 4, right: -3, width: 6 })
+                : null, axes === "y" || axes === "both"
+                ? handle("s", "ns-resize", { left: 4, right: 4, bottom: -3, height: 6 })
+                : null, axes === "both" ? handle("se", "nwse-resize", { right: -4, bottom: -4, width: 10, height: 10 }) : null] }));
+}
+/**
+ * Layout state for `HudCanvas` — panel placements, edit-mode drag/resize, and per-game persistence.
+ *
+ * @capability hud-layout persistent, live-editable HUD panel layout state for `HudCanvas`
+ */
 export function useHudLayout(options) {
     const storageKey = options?.storageKey;
     const snap = options?.snap;
     const locked = options?.locked;
+    const documentUi = options?.documentUi;
+    const documentPatches = options?.documentPatches !== false;
+    const onPanelCommit = useHudLayoutPersist();
+    const onPanelCommitRef = useRef(onPanelCommit);
+    onPanelCommitRef.current = onPanelCommit;
     const layout = useMemo(() => {
-        const store = createHudLayout({ snap, locked });
-        if (storageKey !== undefined && typeof localStorage !== "undefined") {
+        const store = createHudLayout({
+            snap,
+            locked,
+            onDocumentPatch: documentPatches
+                ? (id, panel) => {
+                    onPanelCommitRef.current?.(id, panel);
+                }
+                : undefined,
+        });
+        if (documentUi !== undefined) {
+            store.applyDocumentUi(documentUi);
+        }
+        else if (storageKey !== undefined && typeof localStorage !== "undefined") {
             store.hydrate(localStorage.getItem(STORAGE_PREFIX + storageKey));
         }
         return store;
-    }, [storageKey, snap, locked]);
+    }, [storageKey, snap, locked, documentPatches]);
     useEffect(() => {
+        if (documentUi !== undefined) {
+            layout.applyDocumentUi(documentUi);
+        }
+    }, [layout, documentUi]);
+    useEffect(() => {
+        if (documentUi !== undefined)
+            return;
         if (storageKey === undefined || typeof localStorage === "undefined")
             return;
         let timer = null;
@@ -50,7 +108,7 @@ export function useHudLayout(options) {
                 localStorage.setItem(STORAGE_PREFIX + storageKey, layout.serialize());
             }
         };
-    }, [layout, storageKey]);
+    }, [layout, storageKey, documentUi]);
     return layout;
 }
 const HudCanvasContext = createContext(null);
@@ -131,6 +189,8 @@ function edgePad(envInset, extra, basePx, scale) {
  * offsets, no manual clearance for sibling panels, the touch-control dock
  * (`--jg-hud-dock-clearance`), or device safe areas. On compact displays the
  * whole surface scales down and each panel applies its `compact` behavior.
+  *
+ * @capability hud-canvas the HUD root surface — design-resolution scaling plus live panel-placement editing (F2+C)
  */
 export function HudCanvas({ layout, editChord, compactScale, showDuring, className, style, children, }) {
     const canvasRef = useRef(null);
@@ -160,6 +220,7 @@ export function HudCanvas({ layout, editChord, compactScale, showDuring, classNa
     }, []);
     const value = useMemo(() => ({ layout, canvasRef, regions, compact }), [layout, regions, compact]);
     const editing = useEngineState(layout).editing;
+    useEffect(() => registerActiveHudLayout(layout), [layout]);
     const chordEnabled = editChord !== false;
     const hold = editChord === false ? undefined : (editChord?.hold ?? "F2");
     const press = editChord === false ? undefined : (editChord?.press ?? "KeyC");
@@ -343,8 +404,10 @@ function HudChip({ label, anchor, children, }) {
  * pointers panels stay draggable through the edit chord; a dragged panel
  * leaves the flow and keeps its custom placement. On compact displays custom
  * placements are ignored and the `compact` behavior applies.
+  *
+ * @capability hud-panel anchored HUD slot — drop any widget in a named, player-movable panel
  */
-export function HudPanel({ id, anchor = "top-left", order, compact: compactMode = "keep", chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region = true, className, style, children, }) {
+export function HudPanel({ id, anchor = "top-left", order, compact: compactMode = "keep", chip, interactive, inset, locked, showDuring, priority, mobileBehavior, allowOverlapWith, collisionGroup, region = true, width, height, type, className, style, children, }) {
     const ctx = useContext(HudCanvasContext);
     const phase = useOptionalGamePhase();
     const layoutMode = useGameLayoutMode();
@@ -355,12 +418,18 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
     const registeredOnRef = useRef(null);
     if (registeredOnRef.current !== layout) {
         registeredOnRef.current = layout;
-        layout.register(id, anchoredPlacement(anchor, inset ?? { x: 16, y: 16 }));
+        layout.register(id, anchoredPlacement(anchor, inset ?? { x: 16, y: 16 }), {
+            width,
+            height,
+            type,
+        });
     }
     const layoutState = useEngineState(layout);
     const panel = layoutState.panels[id];
     const draggable = !compact && locked !== true && isPanelDraggable(layoutState, id);
     const editing = layoutState.editing && draggable;
+    const resizeSpec = resolvePanelResize(panel?.type ?? type);
+    const resizable = editing && resizeSpec.axes !== "none";
     const rootRef = useRef(null);
     const dragRef = useRef(null);
     const suppressClickRef = useRef(false);
@@ -368,6 +437,7 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
     const [dragging, setDragging] = useState(false);
     useEffect(() => () => detachRef.current?.(), []);
     const regionHidden = panel === undefined ||
+        panel.visible === false ||
         (compact && compactMode === "hide") ||
         (onMobile && mobileBehavior === "hidden") ||
         !hudVisibleInPhase(showDuring, phase);
@@ -383,6 +453,8 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
     const onPointerDown = (event) => {
         if (!draggable || event.button !== 0)
             return;
+        if (event.target?.closest?.("[data-hud-resize]") != null)
+            return;
         const root = rootRef.current;
         const canvas = canvasRef.current;
         if (root === null || canvas === null)
@@ -439,6 +511,44 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
         window.addEventListener("pointerup", onEnd);
         window.addEventListener("pointercancel", onEnd);
     };
+    const onResizeStart = (edge, event) => {
+        if (!resizable || event.button !== 0)
+            return;
+        const root = rootRef.current;
+        if (root === null)
+            return;
+        const startWidth = panel?.width ?? root.getBoundingClientRect().width;
+        const startHeight = panel?.height ?? root.getBoundingClientRect().height;
+        const pointerId = event.pointerId;
+        const startX = event.clientX;
+        const startY = event.clientY;
+        suppressClickRef.current = true;
+        layout.bringToFront(id);
+        const onMove = (moveEvent) => {
+            if (moveEvent.pointerId !== pointerId)
+                return;
+            const dw = edge === "s" ? 0 : moveEvent.clientX - startX;
+            const dh = edge === "e" ? 0 : moveEvent.clientY - startY;
+            const next = resizePanelSize({ width: startWidth, height: startHeight }, { dw, dh }, resizeSpec.axes, resizeSpec);
+            layout.resize(id, next);
+        };
+        const onEnd = (endEvent) => {
+            if (endEvent.pointerId !== pointerId)
+                return;
+            detachRef.current?.();
+        };
+        detachRef.current?.();
+        const detach = () => {
+            window.removeEventListener("pointermove", onMove);
+            window.removeEventListener("pointerup", onEnd);
+            window.removeEventListener("pointercancel", onEnd);
+            detachRef.current = null;
+        };
+        detachRef.current = detach;
+        window.addEventListener("pointermove", onMove);
+        window.addEventListener("pointerup", onEnd);
+        window.addEventListener("pointercancel", onEnd);
+    };
     const onClickCapture = (event) => {
         if (!suppressClickRef.current)
             return;
@@ -458,15 +568,18 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
                     color: "rgba(255, 255, 255, 0.9)",
                     font: "10px/1.5 system-ui, sans-serif",
                     whiteSpace: "nowrap",
-                }, children: id })] })) : null;
+                }, children: id }), resizable ? _jsx(ResizeHandles, { axes: resizeSpec.axes, onResizeStart: onResizeStart }) : null] })) : null;
     if (panel === undefined)
         return null;
+    if (panel.visible === false)
+        return null;
     if (compact && compactMode === "hide")
         return null;
     if (onMobile && mobileBehavior === "hidden")
         return null;
     if (!hudVisibleInPhase(showDuring, phase))
         return null;
+    const authoredSize = sizeStyle(panel);
     const flow = compact || !panel.moved;
     if (flow) {
         const regionEl = regions[compact ? anchor : panel.placement.anchor];
@@ -474,7 +587,7 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
             return null;
         const chipped = compact && compactMode === "chip";
         const passThrough = interactive === false && !editing && !chipped;
-        return createPortal(_jsxs("div", { ref: rootRef, "data-hud-panel": id, "data-dragging": dragging ? "" : undefined, "data-hud-priority": priority, "data-hud-mobile-behavior": mobileBehavior, className: className, onPointerDown: onPointerDown, onClickCapture: onClickCapture, style: {
+        return createPortal(_jsxs("div", { ref: rootRef, "data-hud-panel": id, "data-dragging": dragging ? "" : undefined, "data-hud-priority": priority, "data-hud-mobile-behavior": mobileBehavior, "data-hud-type": panel.type ?? type, className: className, onPointerDown: onPointerDown, onClickCapture: onClickCapture, style: {
                 position: "relative",
                 order: order ?? 0,
                 pointerEvents: passThrough ? "none" : "auto",
@@ -483,6 +596,8 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
                 cursor: dragging ? "grabbing" : editing ? "grab" : undefined,
                 outline: editing ? "1px dashed rgba(255, 255, 255, 0.6)" : undefined,
                 outlineOffset: editing ? 2 : undefined,
+                boxSizing: "border-box",
+                ...authoredSize,
                 ...style,
             }, children: [chipped ? (_jsx(HudChip, { label: chip ?? id, anchor: anchor, children: children })) : (children), editingChrome] }), regionEl);
     }
@@ -503,7 +618,7 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
     if (fx === 0.5 || fy === 0.5) {
         position.transform = `translate(${fx === 0.5 ? "-50%" : "0"}, ${fy === 0.5 ? "-50%" : "0"})`;
     }
-    return (_jsxs("div", { ref: rootRef, "data-hud-panel": id, "data-dragging": dragging ? "" : undefined, className: className, onPointerDown: onPointerDown, onClickCapture: onClickCapture, style: {
+    return (_jsxs("div", { ref: rootRef, "data-hud-panel": id, "data-dragging": dragging ? "" : undefined, "data-hud-type": panel.type ?? type, className: className, onPointerDown: onPointerDown, onClickCapture: onClickCapture, style: {
             position: "absolute",
             ...position,
             zIndex: panel.z,
@@ -513,6 +628,8 @@ export function HudPanel({ id, anchor = "top-left", order, compact: compactMode
             cursor: dragging ? "grabbing" : editing ? "grab" : undefined,
             outline: editing ? "1px dashed rgba(255, 255, 255, 0.6)" : undefined,
             outlineOffset: editing ? 2 : undefined,
+            boxSizing: "border-box",
+            ...authoredSize,
             ...style,
         }, children: [children, editingChrome] }));
 }

package/dist/hudLayoutPersist.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode } from "react";
+import type { EditorUiPanelLayout } from "@jgengine/core/ui/hudDocument";
+/**
+ * Host-owned callback that commits one HUD panel layout into the scene document
+ * (typically an undoable `setUiPanel` dispatch). Injected by the editor so product
+ * UI never reaches for editor globals.
+ */
+export type HudLayoutPersist = (id: string, panel: EditorUiPanelLayout) => void;
+/**
+ * Provides {@link HudLayoutPersist} / `onPanelCommit` to descendant `useHudLayout`
+ * calls. Mount around game UI when a host can accept document UI patches (editor).
+ * Absent provider → canvas moves/resizes are no-ops for document writes.
+ * @capability hud-layout-persist inject a host callback so canvas HUD edits commit into the scene document
+ */
+export declare function HudLayoutPersistProvider({ onPanelCommit, children, }: {
+    onPanelCommit: HudLayoutPersist;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Injected panel-commit port, or `null` when no host has provided one.
+ * @capability hud-layout-persist-hook read the host panel-commit port from a HUD layout widget
+ */
+export declare function useHudLayoutPersist(): HudLayoutPersist | null;

package/dist/hudLayoutPersist.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const HudLayoutPersistContext = createContext(null);
+/**
+ * Provides {@link HudLayoutPersist} / `onPanelCommit` to descendant `useHudLayout`
+ * calls. Mount around game UI when a host can accept document UI patches (editor).
+ * Absent provider → canvas moves/resizes are no-ops for document writes.
+ * @capability hud-layout-persist inject a host callback so canvas HUD edits commit into the scene document
+ */
+export function HudLayoutPersistProvider({ onPanelCommit, children, }) {
+    return (_jsx(HudLayoutPersistContext.Provider, { value: onPanelCommit, children: children }));
+}
+/**
+ * Injected panel-commit port, or `null` when no host has provided one.
+ * @capability hud-layout-persist-hook read the host panel-commit port from a HUD layout widget
+ */
+export function useHudLayoutPersist() {
+    return useContext(HudLayoutPersistContext);
+}

package/dist/hudTheme.d.ts

@@ -0,0 +1,76 @@
+import { type CSSProperties } from "react";
+/**
+ * `HudTheme` (#1034): one token object that restyles shared token-driven building blocks at once.
+ * It is the superset of the atomic-bar tokens (#1033) — `hudThemeVars(theme)` emits the same
+ * `--jg-*` custom properties the bars already read, plus frame / slot / minimap-ring tokens — so
+ * setting a **game-authored** theme on any HUD ancestor re-skins those primitives. Purely CSS-token
+ * driven (no image assets). Tokens are not a finished UI: every game still owns composition, skin,
+ * and art direction (see AGENTS.md). Built-in presets are demo/scaffold starting points only.
+ *
+ * @capability hud-theme game-authored token object for bars, frames, slots, and minimap ring
+ */
+/** Per-readout fill colors plus a shared accent/glow. */
+export interface HudThemePalette {
+    health: string;
+    healthLow: string;
+    mana: string;
+    stamina: string;
+    shield: string;
+    xp: string;
+    soul: string;
+    ammo: string;
+    boss: string;
+    /** Accent used for glow/keycap/active states. */
+    accent: string;
+}
+/** Frame material + shape tokens (panels, `HudFrame variation="themed"`). */
+export interface HudThemeFrame {
+    /** Panel background (gradient or solid). */
+    bg: string;
+    border: string;
+    /** Corner radius (any CSS length, e.g. `"10px"`, `"0"`). */
+    radius: string;
+    /** Outer glow / drop shadow. */
+    glow: string;
+}
+/** Framed-trough tokens shared by every atomic bar. */
+export interface HudThemeBar {
+    track: string;
+    frame: string;
+    height: string;
+    radius: string;
+    bevel: string;
+    text: string;
+}
+/** Action/inventory slot tokens. */
+export interface HudThemeSlot {
+    bg: string;
+    border: string;
+    radius: string;
+}
+/** A full HUD theme. */
+export interface HudTheme {
+    palette: HudThemePalette;
+    frame: HudThemeFrame;
+    bar: HudThemeBar;
+    slot: HudThemeSlot;
+    /** Minimap chrome ring color. */
+    ring: string;
+}
+/** Emits the CSS custom properties for a theme — spread onto any HUD ancestor to re-skin the subtree. */
+export declare function hudThemeVars(theme: HudTheme): CSSProperties;
+/** Default theme tokens for previews/scaffold — not a finished game look; author a custom theme. */
+export declare const defaultHudTheme: HudTheme;
+/** Built-in theme presets for demos/scaffold only — not product identity; games author their own theme. */
+export declare const HUD_THEME_PRESETS: {
+    "arcane-stone": HudTheme;
+    "survival-wood": HudTheme;
+    "military-flat": HudTheme;
+    "sleek-hex": HudTheme;
+    "elemental-circle": HudTheme;
+    "sandbox-slot": HudTheme;
+};
+/** Built-in demo/scaffold theme preset name — not a game identity. */
+export type HudThemePreset = keyof typeof HUD_THEME_PRESETS;
+/** Resolves a preset name (or a full theme) to a `HudTheme`; falls back to the default theme. */
+export declare function resolveHudTheme(theme?: HudThemePreset | HudTheme): HudTheme;

package/dist/hudTheme.js

@@ -0,0 +1,156 @@
+import {} from "react";
+/** Emits the CSS custom properties for a theme — spread onto any HUD ancestor to re-skin the subtree. */
+export function hudThemeVars(theme) {
+    const { palette, frame, bar, slot } = theme;
+    return {
+        // atomic-bar tokens (same names the bars read — #1033)
+        "--jg-health": palette.health,
+        "--jg-health-low": palette.healthLow,
+        "--jg-mana": palette.mana,
+        "--jg-stamina": palette.stamina,
+        "--jg-shield": palette.shield,
+        "--jg-xp": palette.xp,
+        "--jg-soul": palette.soul,
+        "--jg-ammo": palette.ammo,
+        "--jg-boss": palette.boss,
+        "--jg-bar-track": bar.track,
+        "--jg-bar-frame": bar.frame,
+        "--jg-bar-height": bar.height,
+        "--jg-bar-radius": bar.radius,
+        "--jg-bar-bevel": bar.bevel,
+        "--jg-bar-text": bar.text,
+        // shared chrome tokens
+        "--jg-accent": palette.accent,
+        "--jg-frame-bg": frame.bg,
+        "--jg-frame-border": frame.border,
+        "--jg-frame-radius": frame.radius,
+        "--jg-frame-glow": frame.glow,
+        "--jg-slot-bg": slot.bg,
+        "--jg-slot-border": slot.border,
+        "--jg-slot-radius": slot.radius,
+        "--jg-ring": theme.ring,
+    };
+}
+/** Default theme tokens for previews/scaffold — not a finished game look; author a custom theme. */
+export const defaultHudTheme = {
+    palette: {
+        health: "#e5484d",
+        healthLow: "#b21e23",
+        mana: "#3b82f6",
+        stamina: "#84cc16",
+        shield: "#22d3ee",
+        xp: "#a855f7",
+        soul: "#c084fc",
+        ammo: "#f8b84e",
+        boss: "#ef4444",
+        accent: "#38bdf8",
+    },
+    frame: {
+        bg: "linear-gradient(180deg, rgba(20,24,32,0.86), rgba(10,12,16,0.9))",
+        border: "1px solid rgba(255,255,255,0.12)",
+        radius: "10px",
+        glow: "0 6px 20px rgba(0,0,0,0.45)",
+    },
+    bar: {
+        track: "rgba(0,0,0,0.55)",
+        frame: "rgba(0,0,0,0.82)",
+        height: "18px",
+        radius: "4px",
+        bevel: "inset 0 2px 4px rgba(0,0,0,0.55), inset 0 -1px 2px rgba(255,255,255,0.08)",
+        text: "#f5f7fa",
+    },
+    slot: { bg: "rgba(12,14,20,0.7)", border: "1px solid rgba(255,255,255,0.12)", radius: "8px" },
+    ring: "rgba(140,170,200,0.35)",
+};
+function theme(overrides) {
+    return {
+        palette: { ...defaultHudTheme.palette, ...overrides.palette },
+        frame: { ...defaultHudTheme.frame, ...overrides.frame },
+        bar: { ...defaultHudTheme.bar, ...overrides.bar },
+        slot: { ...defaultHudTheme.slot, ...overrides.slot },
+        ring: overrides.ring ?? defaultHudTheme.ring,
+    };
+}
+/** Built-in theme presets for demos/scaffold only — not product identity; games author their own theme. */
+export const HUD_THEME_PRESETS = {
+    "arcane-stone": theme({
+        palette: { health: "#c0392b", mana: "#7c5cff", xp: "#d4a017", accent: "#b483ff", shield: "#8e7bd6" },
+        frame: {
+            bg: "linear-gradient(180deg, #3a3550, #211d33)",
+            border: "2px solid #6b5b95",
+            radius: "6px",
+            glow: "0 0 18px rgba(124,92,255,0.35)",
+        },
+        bar: { frame: "#160f28", radius: "3px", height: "20px", track: "rgba(0,0,0,0.6)", bevel: "inset 0 2px 5px rgba(0,0,0,0.6)", text: "#efe7ff" },
+        slot: { bg: "#241f38", border: "2px solid #6b5b95", radius: "5px" },
+        ring: "rgba(124,92,255,0.5)",
+    }),
+    "survival-wood": theme({
+        palette: { health: "#c0553b", stamina: "#a3b545", xp: "#e0a94b", accent: "#d9a441", shield: "#7bb0a0" },
+        frame: {
+            bg: "linear-gradient(180deg, #4a3b28, #2e2117)",
+            border: "3px solid #6b4a2c",
+            radius: "4px",
+            glow: "0 4px 10px rgba(0,0,0,0.5)",
+        },
+        bar: { frame: "#2a1c10", radius: "2px", height: "18px", track: "rgba(30,20,10,0.7)", bevel: "inset 0 2px 4px rgba(0,0,0,0.6)", text: "#f3e6cf" },
+        slot: { bg: "#3a2a1a", border: "3px solid #6b4a2c", radius: "3px" },
+        ring: "rgba(107,74,44,0.6)",
+    }),
+    "military-flat": theme({
+        palette: { health: "#3fa34d", stamina: "#a8b545", xp: "#c9b458", accent: "#7d9b4e", shield: "#5f8fae" },
+        frame: {
+            bg: "linear-gradient(180deg, #2b3126, #1c2019)",
+            border: "1px solid #4a5340",
+            radius: "2px",
+            glow: "0 2px 6px rgba(0,0,0,0.5)",
+        },
+        bar: { frame: "#161a12", radius: "0px", height: "16px", track: "rgba(0,0,0,0.6)", bevel: "inset 0 1px 2px rgba(0,0,0,0.7)", text: "#e8efdc" },
+        slot: { bg: "#232a1e", border: "1px solid #4a5340", radius: "0px" },
+        ring: "rgba(125,155,78,0.5)",
+    }),
+    "sleek-hex": theme({
+        palette: { health: "#ff5a7a", mana: "#33c9ff", xp: "#38e8c0", accent: "#33c9ff", shield: "#33c9ff" },
+        frame: {
+            bg: "linear-gradient(180deg, rgba(18,24,34,0.9), rgba(8,12,18,0.94))",
+            border: "1px solid rgba(51,201,255,0.4)",
+            radius: "3px",
+            glow: "0 0 16px rgba(51,201,255,0.3)",
+        },
+        bar: { frame: "rgba(51,201,255,0.5)", radius: "2px", height: "14px", track: "rgba(0,0,0,0.5)", bevel: "inset 0 1px 3px rgba(0,0,0,0.5)", text: "#eafaff" },
+        slot: { bg: "rgba(12,18,26,0.8)", border: "1px solid rgba(51,201,255,0.4)", radius: "3px" },
+        ring: "rgba(51,201,255,0.55)",
+    }),
+    "elemental-circle": theme({
+        palette: { health: "#ff6b3d", mana: "#4aa8ff", stamina: "#7bd451", xp: "#ffcf40", accent: "#ffcf40", shield: "#4aa8ff" },
+        frame: {
+            bg: "radial-gradient(circle at 50% 40%, #2c2a3a, #16141f)",
+            border: "2px solid #d9a441",
+            radius: "9999px",
+            glow: "0 0 20px rgba(217,164,65,0.35)",
+        },
+        bar: { frame: "#1a1626", radius: "9999px", height: "16px", track: "rgba(0,0,0,0.55)", bevel: "inset 0 2px 4px rgba(0,0,0,0.6)", text: "#fff3d6" },
+        slot: { bg: "#221f30", border: "2px solid #d9a441", radius: "9999px" },
+        ring: "rgba(217,164,65,0.6)",
+    }),
+    "sandbox-slot": theme({
+        palette: { health: "#e0524a", stamina: "#77c043", xp: "#5ac0e0", accent: "#f0c040", shield: "#5ac0e0" },
+        frame: {
+            bg: "linear-gradient(180deg, #5a5a5a, #3a3a3a)",
+            border: "3px solid #2a2a2a",
+            radius: "2px",
+            glow: "3px 3px 0 rgba(0,0,0,0.5)",
+        },
+        bar: { frame: "#1e1e1e", radius: "0px", height: "18px", track: "rgba(0,0,0,0.6)", bevel: "inset 0 2px 3px rgba(0,0,0,0.6)", text: "#f4f4f4" },
+        slot: { bg: "#4a4a4a", border: "3px solid #2a2a2a", radius: "0px" },
+        ring: "rgba(240,192,64,0.5)",
+    }),
+};
+/** Resolves a preset name (or a full theme) to a `HudTheme`; falls back to the default theme. */
+export function resolveHudTheme(theme) {
+    if (theme === undefined)
+        return defaultHudTheme;
+    if (typeof theme === "string")
+        return HUD_THEME_PRESETS[theme] ?? defaultHudTheme;
+    return theme;
+}

package/dist/hudThemePreview.d.ts

@@ -0,0 +1,4 @@
+/** Renders the default theme plus every genre preset as a deterministic matrix. */
+export declare function HudThemePreview({ className }: {
+    className?: string;
+}): import("react").JSX.Element;

package/dist/hudThemePreview.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import {} from "react";
+import { AmmoCounter, ExperienceBar, HealthBar, ManaBar, ShieldBar } from "./bars.js";
+import { HudFrame } from "./hudFrame.js";
+import { HUD_THEME_PRESETS, defaultHudTheme, hudThemeVars } from "./hudTheme.js";
+/**
+ * A deterministic preset matrix for {@link HudTheme} (#1034): every genre preset × (bars + a themed
+ * frame + a slot row), rendered from static values. One `hudThemeVars(theme)` block per cell drives
+ * the atomic bars, the `HudFrame variation="themed"`, and the slot chrome together — proof that a
+ * single theme restyles all the shared chrome at once. Renders identically every time (screenshots).
+ */
+function Slot({ index }) {
+    return (_jsx("div", { style: {
+            width: 34,
+            height: 34,
+            background: "var(--jg-slot-bg, rgba(12,14,20,0.7))",
+            border: "var(--jg-slot-border, 1px solid rgba(255,255,255,0.12))",
+            borderRadius: "var(--jg-slot-radius, 8px)",
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            fontSize: 10,
+            color: "var(--jg-bar-text, #f4f6fb)",
+            opacity: index === 0 ? 1 : 0.6,
+        }, children: index + 1 }));
+}
+function ThemeCell({ name, theme }) {
+    return (_jsx("div", { style: { ...hudThemeVars(theme), width: 260 }, children: _jsx(HudFrame, { variation: "themed", title: name, padding: 12, children: _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 7 }, children: [_jsx(HealthBar, { value: 78, max: 100, label: "HP", width: "100%" }), _jsx(ManaBar, { value: 50, max: 80, label: "MP", width: "100%" }), _jsx(ShieldBar, { value: 30, max: 60, label: "SH", width: "100%" }), _jsx(ExperienceBar, { value: 4, max: 10, segments: 10, showValue: false, label: "XP", width: "100%" }), _jsx(AmmoCounter, { loaded: 17, reserve: 90, magazine: 30, width: "100%" }), _jsx("div", { style: { display: "flex", gap: 6, marginTop: 2 }, children: [0, 1, 2, 3].map((index) => (_jsx(Slot, { index: index }, index))) })] }) }) }));
+}
+/** Renders the default theme plus every genre preset as a deterministic matrix. */
+export function HudThemePreview({ className }) {
+    const cells = [
+        ["default", defaultHudTheme],
+        ...Object.entries(HUD_THEME_PRESETS),
+    ];
+    return (_jsx("div", { "data-hud-theme-preview": true, className: className, style: { display: "flex", gap: 18, flexWrap: "wrap", padding: 22, fontFamily: "system-ui, sans-serif", background: "#0e1216" }, children: cells.map(([name, theme]) => (_jsx(ThemeCell, { name: name, theme: theme }, name))) }));
+}