@jgengine/react 0.11.0 → 0.12.0

package/dist/hud.js

@@ -1,26 +1,20 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo } from "react";
 import { groundSpeed } from "@jgengine/core/scene/entityStore";
+import { iconForItemId } from "./gameIcons.js";
+import { hudFrameStyle } from "./hudFrame.js";
+import { IconTreatment, schoolForItem } from "./iconTreatment.js";
 import { useCurrency, useEntityStat, useGameClock, useGameStore, useInventory, localPlayerEntity } from "./hooks.js";
 /**
- * Drop-in HUD components — good-looking with zero styling, and fully opt-in: a game imports only the
- * pieces it wants (`StatBar`, `Hotbar`, `Speedometer`, `Clock`, `WaveBanner`, `Coins`, `Crosshair`)
- * and places them itself. The engine imposes none of these; there is no forced HUD. Styling is
- * self-contained inline CSS (no Tailwind `@source` needed) with a shared dark-glass look; pass
+ * Optional HUD building blocks bound to live game state — not a finished game face. Every game
+ * owns custom presentation (see AGENTS.md); import these only as temporary scaffolding, previews,
+ * or under game-owned chrome. Prefer headless hooks + game markup for shipped UI. The engine
+ * mounts none of these by default. Styling is self-contained dark-glass for demos; pass
  * `style`/`className` to override. Anything reading the player defaults to the local player entity.
  *
- * @capability hud-components opt-in drop-in health/hotbar/speed/clock/wave/currency HUD widgets
+ * @capability hud-components optional health/hotbar/speed/clock/wave/currency building blocks — games own custom chrome
  */
-const PANEL = {
-    background: "rgba(10,12,16,0.62)",
-    backdropFilter: "blur(6px)",
-    WebkitBackdropFilter: "blur(6px)",
-    border: "1px solid rgba(255,255,255,0.10)",
-    borderRadius: 10,
-    color: "#f4f6fb",
-    fontFamily: "ui-sans-serif, system-ui, -apple-system, sans-serif",
-    boxShadow: "0 4px 16px rgba(0,0,0,0.35)",
-};
+const PANEL = hudFrameStyle("glass");
 /** Named color ramps for {@link StatBar} tones. `fn` maps fill fraction (0..1) → gradient stops. */
 const TONES = {
     health: (t) => (t > 0.5 ? ["#22c55e", "#4ade80"] : t > 0.25 ? ["#f59e0b", "#fbbf24"] : ["#dc2626", "#f87171"]),
@@ -37,6 +31,13 @@ function useLocalPlayerId(entityId) {
  * A polished stat bar (health/mana/stamina/shield/xp) — a rounded, glassy meter with a tone-colored
  * fill and an optional value readout. Reads `statId` off `entityId` (defaults to the local player).
  * Renders nothing until the stat exists.
+ *
+ * @deprecated The `tone`-switched umbrella is being retired (#1033). Use the atomic, purpose-named,
+ * token-themed bars from `@jgengine/react/bars` instead — `HealthBar`, `ShieldBar`, `ManaBar`,
+ * `StaminaBar`, `ExperienceBar`, `SoulBar`, `BossBar`, `AmmoCounter` — each does one readout and is
+ * restyled globally via the shared `--jg-*` tokens (`barTokens`). Kept as a thin shim during migration.
+  *
+ * @capability hud-stat-bar optional stat-bound bar building block (health, mana, stamina) — prefer game-owned chrome
  */
 export function StatBar({ statId = "health", entityId, tone = "health", label, showValue = true, width = 200, icon, style, className, }) {
     const id = useLocalPlayerId(entityId);
@@ -49,24 +50,30 @@ export function StatBar({ statId = "health", entityId, tone = "health", label, s
     return (_jsxs("div", { className: className, style: { ...PANEL, padding: "6px 8px", width, ...style }, "data-stat": statId, children: [(label !== undefined || icon !== undefined || showValue) && (_jsxs("div", { style: { display: "flex", alignItems: "center", gap: 6, marginBottom: 4, fontSize: 11, fontWeight: 600, letterSpacing: 0.3 }, children: [icon, _jsx("span", { style: { textTransform: "uppercase", opacity: 0.75 }, children: label ?? statId }), showValue ? (_jsxs("span", { style: { marginLeft: "auto", fontVariantNumeric: "tabular-nums", opacity: 0.9 }, children: [Math.round(stat.current), _jsxs("span", { style: { opacity: 0.5 }, children: [" / ", Math.round(stat.max)] })] })) : null] })), _jsx("div", { style: { height: 8, borderRadius: 999, background: "rgba(255,255,255,0.10)", overflow: "hidden" }, children: _jsx("div", { style: { width: `${fraction * 100}%`, height: "100%", borderRadius: 999, background: `linear-gradient(90deg, ${from}, ${to})`, transition: "width 160ms ease" } }) })] }));
 }
 /**
- * A numbered hotbar bound to an inventory — glassy slots, an active-slot highlight, item id + count,
- * and a keycap per slot. Place it and pass the `inventoryId`; `activeSlot` highlights the equipped one.
+ * A numbered hotbar bound to an inventory — painted iconed slots (a `GameIcon` glyph over a
+ * school-keyed gradient with a count badge, #1035), an active-slot highlight, and a keycap per slot.
+ * Place it and pass the `inventoryId`; `activeSlot` highlights the equipped one. Supply `itemIcon` to
+ * map your item ids to your own glyphs — the default resolves a `GameIcon` from the item id.
+  *
+ * @capability hud-hotbar optional inventory hotbar building block — games own slot chrome
  */
-export function Hotbar({ inventoryId, activeSlot, keys, slotSize = 46, style, className, }) {
+export function Hotbar({ inventoryId, activeSlot, keys, slotSize = 46, itemIcon, style, className, }) {
     const slots = useInventory(inventoryId);
     return (_jsx("div", { className: className, style: { display: "flex", gap: 6, ...style }, "data-inventory": inventoryId, children: slots.map((slot, index) => {
             const active = index === activeSlot;
-            return (_jsxs("div", { "data-slot": index, style: {
-                    ...PANEL,
+            const keycap = keys?.[index] ?? String(index + 1);
+            const custom = slot !== null ? itemIcon?.(slot.itemId) : undefined;
+            return (_jsx("div", { "data-slot": index, style: {
                     width: slotSize,
                     height: slotSize,
                     position: "relative",
-                    display: "flex",
-                    alignItems: "center",
-                    justifyContent: "center",
-                    borderColor: active ? "rgba(56,189,248,0.9)" : "rgba(255,255,255,0.10)",
-                    boxShadow: active ? "0 0 0 1px rgba(56,189,248,0.7), 0 4px 16px rgba(0,0,0,0.35)" : PANEL.boxShadow,
-                }, children: [_jsx("span", { style: { position: "absolute", top: 2, left: 4, fontSize: 9, fontWeight: 700, opacity: 0.55 }, children: keys?.[index] ?? index + 1 }), slot !== null ? (_jsxs("span", { style: { fontSize: 10, textAlign: "center", lineHeight: 1.1, padding: "0 2px", wordBreak: "break-word" }, children: [slot.itemId, slot.count > 1 ? _jsxs("span", { style: { display: "block", opacity: 0.6 }, children: ["\u00D7", slot.count] }) : null] })) : null] }, index));
+                }, children: slot !== null ? (custom !== undefined && custom !== null ? (_jsx(IconTreatment, { glyph: custom, size: slotSize, count: slot.count, keycap: keycap, active: active })) : (_jsx(IconTreatment, { ...(iconForItemId(slot.itemId) === null ? {} : { icon: iconForItemId(slot.itemId) }), school: schoolForItem(slot.itemId), size: slotSize, count: slot.count, keycap: keycap, active: active }))) : (_jsx("div", { style: {
+                        ...PANEL,
+                        width: slotSize,
+                        height: slotSize,
+                        position: "relative",
+                        borderColor: active ? "rgba(56,189,248,0.9)" : "rgba(255,255,255,0.10)",
+                    }, children: _jsx("span", { style: { position: "absolute", top: 2, left: 4, fontSize: 9, fontWeight: 700, opacity: 0.55 }, children: keycap }) })) }, index));
         }) }));
 }
 /**
@@ -98,6 +105,8 @@ export function Speedometer({ entityId, scale = 3.6, unit = "km/h", max = 60, si
  * A time-of-day clock reading the sim calendar — `Day N · HH:MM`, 24h or 12h. `controls` adds
  * pause + the game's speed multipliers as clickable pills (the "fast-forward" bar), off by default so
  * a game opts into letting the player scrub time.
+  *
+ * @capability hud-clock in-game time-of-day readout bound to the sim clock
  */
 export function Clock({ format = "24h", showDay = true, controls = false, style, className, }) {
     const clock = useGameClock();
@@ -132,7 +141,9 @@ function ClockPill({ label, active, onClick }) {
 export function WaveBanner({ wave, label = "Wave", subtitle, style, className, }) {
     return (_jsxs("div", { className: className, style: { ...PANEL, padding: "6px 16px", textAlign: "center", display: "inline-block", ...style }, children: [_jsx("div", { style: { fontSize: 10, letterSpacing: 2, textTransform: "uppercase", opacity: 0.65 }, children: label }), _jsx("div", { style: { fontSize: 24, fontWeight: 800, lineHeight: 1.1 }, children: wave }), subtitle !== undefined ? _jsx("div", { style: { fontSize: 11, opacity: 0.7, marginTop: 2 }, children: subtitle }) : null] }));
 }
-/** A currency counter — an icon (emoji/char, default a coin) plus the live amount for `currencyId`. */
+/** A currency counter — an icon (emoji/char, default a coin) plus the live amount for `currencyId`.  *
+ * @capability hud-coins currency counter widget bound to a currency id
+ */
 export function Coins({ currencyId, icon = "🪙", style, className, }) {
     const amount = useCurrency(currencyId);
     return (_jsxs("span", { className: className, style: { ...PANEL, padding: "3px 10px", display: "inline-flex", alignItems: "center", gap: 6, fontWeight: 700, fontVariantNumeric: "tabular-nums", ...style }, "data-currency": currencyId, children: [_jsx("span", { "aria-hidden": true, children: icon }), amount] }));

package/dist/hudFrame.d.ts

@@ -0,0 +1,47 @@
+import type { CSSProperties, ReactNode } from "react";
+/** Frame skin — `glass` (the shared dark-glass panel), `plate` (a heavier opaque plate), `retro` (a hard black-outlined frame), or `themed` (driven by the `--jg-frame-*` `HudTheme` tokens). */
+export type HudFrameVariation = "glass" | "plate" | "retro" | "themed";
+/** Frame corner shape — `rounded` (the variation's default radius), `circle` (fully round), or `square` (no radius). */
+export type HudFrameShape = "rounded" | "circle" | "square";
+/**
+ * Bare style object for a HUD frame's look (no wrapper element) — spread it onto
+ * a widget that already owns its element when it just needs the chrome CSS. The
+ * `glass` variation is byte-for-byte the shared dark-glass panel used across the
+ * built-in HUD widgets; `plate` is a heavier opaque plate; `retro` is a hard
+ * black-outlined frame. `shape` overrides the corner radius.
+ *
+ * @internal helper behind {@link HudFrame} (and the built-in HUD `PANEL`); widgets normally use `HudFrame`.
+ */
+export declare function hudFrameStyle(variation?: HudFrameVariation, shape?: HudFrameShape): CSSProperties;
+/** Props for {@link HudFrame}. */
+export interface HudFrameProps {
+    /** Frame skin (default `glass`). */
+    variation?: HudFrameVariation;
+    /** Corner shape (default `rounded`). */
+    shape?: HudFrameShape;
+    /** Small uppercase header label rendered at the top-left of the frame. */
+    title?: ReactNode;
+    /** Header content rendered at the top-right, opposite `title` (e.g. a readout or cardinal). */
+    aside?: ReactNode;
+    /** Inner padding of the frame. */
+    padding?: number | string;
+    /** Fixed frame width. */
+    width?: number | string;
+    /** Accept pointer events (default off, so the frame never eats clicks meant for the game). */
+    interactive?: boolean;
+    /** Extra class on the frame element. */
+    className?: string;
+    /** Style overrides merged last, so callers can pin exact gradients/colors. */
+    style?: CSSProperties;
+    /** Frame body. */
+    children?: ReactNode;
+}
+/**
+ * Optional framed panel primitive — a single `<div data-hud-frame>` with a `glass`,
+ * `plate`, `retro`, or `themed` skin, optional `title`/`aside` header, and caller
+ * `style` merged last. Shared building block for demos and token-themed widgets;
+ * games own product chrome and art direction (see AGENTS.md).
+ *
+ * @capability hud-frame optional framed panel skins (glass/plate/retro/themed) — games own product chrome
+ */
+export declare function HudFrame({ variation, shape, title, aside, padding, width, interactive, className, style, children, }: HudFrameProps): ReactNode;

package/dist/hudFrame.js

@@ -0,0 +1,80 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Bare style object for a HUD frame's look (no wrapper element) — spread it onto
+ * a widget that already owns its element when it just needs the chrome CSS. The
+ * `glass` variation is byte-for-byte the shared dark-glass panel used across the
+ * built-in HUD widgets; `plate` is a heavier opaque plate; `retro` is a hard
+ * black-outlined frame. `shape` overrides the corner radius.
+ *
+ * @internal helper behind {@link HudFrame} (and the built-in HUD `PANEL`); widgets normally use `HudFrame`.
+ */
+export function hudFrameStyle(variation = "glass", shape = "rounded") {
+    const base = variation === "themed"
+        ? {
+            background: "var(--jg-frame-bg, rgba(10,12,16,0.62))",
+            border: "var(--jg-frame-border, 1px solid rgba(255,255,255,0.10))",
+            borderRadius: "var(--jg-frame-radius, 10px)",
+            boxShadow: "var(--jg-frame-glow, 0 4px 16px rgba(0,0,0,0.35))",
+            color: "var(--jg-bar-text, #f4f6fb)",
+            fontFamily: "ui-sans-serif, system-ui, -apple-system, sans-serif",
+        }
+        : variation === "retro"
+            ? {
+                border: "2px solid #000",
+                borderRadius: 4,
+                boxShadow: "4px 4px 0 #000",
+                color: "#fff",
+            }
+            : variation === "plate"
+                ? {
+                    background: "rgba(16,18,24,0.92)",
+                    border: "1px solid rgba(255,255,255,0.10)",
+                    borderRadius: 10,
+                    color: "#f4f6fb",
+                    fontFamily: "ui-sans-serif, system-ui, -apple-system, sans-serif",
+                    boxShadow: "0 6px 20px rgba(0,0,0,0.45)",
+                }
+                : {
+                    background: "rgba(10,12,16,0.62)",
+                    backdropFilter: "blur(6px)",
+                    WebkitBackdropFilter: "blur(6px)",
+                    border: "1px solid rgba(255,255,255,0.10)",
+                    borderRadius: 10,
+                    color: "#f4f6fb",
+                    fontFamily: "ui-sans-serif, system-ui, -apple-system, sans-serif",
+                    boxShadow: "0 4px 16px rgba(0,0,0,0.35)",
+                };
+    if (shape === "circle")
+        return { ...base, borderRadius: 9999 };
+    if (shape === "square")
+        return { ...base, borderRadius: 0 };
+    return base;
+}
+/**
+ * Optional framed panel primitive — a single `<div data-hud-frame>` with a `glass`,
+ * `plate`, `retro`, or `themed` skin, optional `title`/`aside` header, and caller
+ * `style` merged last. Shared building block for demos and token-themed widgets;
+ * games own product chrome and art direction (see AGENTS.md).
+ *
+ * @capability hud-frame optional framed panel skins (glass/plate/retro/themed) — games own product chrome
+ */
+export function HudFrame({ variation = "glass", shape = "rounded", title, aside, padding, width, interactive, className, style, children, }) {
+    const hasHeader = title !== undefined || aside !== undefined;
+    return (_jsxs("div", { className: className, "data-hud-frame": true, style: {
+            ...hudFrameStyle(variation, shape),
+            padding,
+            width,
+            pointerEvents: interactive === true ? "auto" : undefined,
+            ...style,
+        }, children: [hasHeader ? (_jsxs("div", { "data-hud-frame-header": true, style: {
+                    display: "flex",
+                    justifyContent: "space-between",
+                    alignItems: "center",
+                    gap: 8,
+                    marginBottom: 6,
+                    fontSize: 10,
+                    letterSpacing: 1.4,
+                    textTransform: "uppercase",
+                    opacity: 0.75,
+                }, children: [_jsx("span", { children: title }), aside !== undefined ? _jsx("span", { children: aside }) : null] })) : null, children] }));
+}

package/dist/hudLayout.d.ts

@@ -15,6 +15,11 @@ 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;
@@ -24,7 +29,10 @@ export declare function useHudLayout(options?: {
      * When provided, hydrates the layout store (and wins over legacy localStorage).
      */
     documentUi?: EditorUiDocument;
-    /** When true (default), canvas moves/resizes write undoable `setUiPanel` patches to a live editor host. */
+    /**
+     * 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;
 /**
@@ -33,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;
@@ -51,6 +61,8 @@ 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, width, height, type, className, style, children, }: {
     id: string;

package/dist/hudLayout.js

@@ -9,6 +9,7 @@ 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) {
@@ -21,17 +22,6 @@ const EDIT_BAR_Z = 100000;
 const REGION_GAP = 10;
 const COMPACT_HUD_SCALE = 0.85;
 const HUD_ANCHORS = Object.keys(HUD_ANCHOR_FRACTIONS);
-function patchDocumentUi(id, panel) {
-    if (typeof window === "undefined")
-        return;
-    const host = window.__jgengineEditorHost;
-    if (host === undefined)
-        return;
-    host.handle({
-        method: "dispatch",
-        command: { type: "setUiPanel", id, patch: panel },
-    });
-}
 function sizeStyle(panel) {
     if (panel === undefined)
         return {};
@@ -60,17 +50,29 @@ function ResizeHandles({ axes, onResizeStart, }) {
                 ? 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,
-            onDocumentPatch: documentPatches ? patchDocumentUi : undefined,
+            onDocumentPatch: documentPatches
+                ? (id, panel) => {
+                    onPanelCommitRef.current?.(id, panel);
+                }
+                : undefined,
         });
         if (documentUi !== undefined) {
             store.applyDocumentUi(documentUi);
@@ -187,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);
@@ -400,6 +404,8 @@ 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, width, height, type, className, style, children, }) {
     const ctx = useContext(HudCanvasContext);

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;