@jgengine/react 0.11.0 → 0.13.0

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;

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

package/dist/iconTreatment.d.ts

@@ -0,0 +1,50 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type GameIconName } from "./gameIcons.js";
+/**
+ * `IconTreatment` (#1035): a procedural painted-icon face — a glyph over a school-keyed radial
+ * gradient, with a vignette inset shadow, a top gloss highlight, and optional count/keycap badges.
+ * Turns the engine's flat white `GameIcon` glyphs (and game-icons.net SVGs) into painted ability /
+ * item icons that read as AAA slots, not debug UI. Theme-aware: the frame reads the `--jg-slot-*`
+ * and `--jg-accent` `HudTheme` tokens (#1034), so a theme change re-skins every treated icon.
+ *
+ * @capability hud-icons painted-icon treatment for hotbar/action slots — glyph + gradient + count badge
+ */
+/** Element/school palette key — drives the radial gradient behind the glyph. */
+export type IconSchool = "fire" | "frost" | "arcane" | "nature" | "holy" | "tech" | "shadow" | "steel" | "neutral";
+/** Infers an {@link IconSchool} from an item id (keyword match); `neutral` when nothing matches. */
+export declare function schoolForItem(itemId: string): IconSchool;
+/** Infers an {@link IconSchool} from an action id (keyword match); `neutral` when nothing matches. */
+export declare function schoolForAction(action: string): IconSchool;
+/** Props for {@link IconTreatment}. */
+export interface IconTreatmentProps {
+    /** A `GameIcon` name to render as the glyph. */
+    icon?: GameIconName;
+    /** Or an explicit glyph node (a game-icons.net SVG, an `<img>`, custom art). Wins over `icon`. */
+    glyph?: ReactNode;
+    /** School/element gradient behind the glyph. Default `neutral`. */
+    school?: IconSchool;
+    /** Face size in px. Default 44. */
+    size?: number;
+    /** Stack count — a badge is drawn when > 1. */
+    count?: number;
+    /** Keycap/hotkey drawn top-left. */
+    keycap?: string;
+    /** Active/selected ring using `--jg-accent`. */
+    active?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+/** A painted icon face — gradient + vignette + gloss behind a glyph, with count/keycap badges. */
+export declare function IconTreatment({ icon, glyph, school, size, count, keycap, active, className, style, }: IconTreatmentProps): import("react").JSX.Element;
+/** Maps an item id to a treated icon — resolves a `GameIcon` glyph and an inferred school. */
+export declare function treatedItemIcon(itemId: string, options?: {
+    size?: number;
+    count?: number;
+    keycap?: string;
+}): ReactNode;
+/** A ready-made `ActionButton` `renderIcon` that paints the action's `GameIcon` with a treatment. */
+export declare function treatedActionIcon(action: {
+    id?: string;
+    label?: string;
+    icon?: ReactNode;
+}, size?: number): ReactNode;

package/dist/iconTreatment.js

@@ -0,0 +1,84 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import {} from "react";
+import { GameIcon, iconForAction, iconForItemId } from "./gameIcons.js";
+const SCHOOL_GRADIENT = {
+    fire: ["#ff8a3d", "#661805"],
+    frost: ["#8fe3ff", "#0e3357"],
+    arcane: ["#c58cff", "#341552"],
+    nature: ["#8fe36b", "#194013"],
+    holy: ["#ffe08a", "#6b4d0f"],
+    tech: ["#5fe0c8", "#0c3f3a"],
+    shadow: ["#9a7bd0", "#1b0d2b"],
+    steel: ["#c8d0da", "#333b45"],
+    neutral: ["#9aa3ad", "#242a31"],
+};
+const SCHOOL_RULES = [
+    [["fire", "flame", "burn", "lava", "ember", "molotov", "torch"], "fire"],
+    [["frost", "ice", "freeze", "snow", "water", "aqua", "chill"], "frost"],
+    [["arcane", "magic", "mana", "rune", "spell", "mystic", "void"], "arcane"],
+    [["nature", "leaf", "poison", "vine", "earth", "herb", "wood", "beast"], "nature"],
+    [["holy", "light", "heal", "divine", "bless", "sun", "cleric"], "holy"],
+    [["tech", "laser", "cyber", "robot", "energy", "plasma", "gadget"], "tech"],
+    [["shadow", "dark", "curse", "necro", "death", "blood", "demon"], "shadow"],
+    [["sword", "axe", "hammer", "spear", "dagger", "armor", "shield", "gun", "bow", "metal", "steel"], "steel"],
+];
+function schoolFrom(text) {
+    const lower = text.toLowerCase();
+    for (const [keys, school] of SCHOOL_RULES) {
+        if (keys.some((key) => lower.includes(key)))
+            return school;
+    }
+    return "neutral";
+}
+/** Infers an {@link IconSchool} from an item id (keyword match); `neutral` when nothing matches. */
+export function schoolForItem(itemId) {
+    return schoolFrom(itemId);
+}
+/** Infers an {@link IconSchool} from an action id (keyword match); `neutral` when nothing matches. */
+export function schoolForAction(action) {
+    return schoolFrom(action);
+}
+/** A painted icon face — gradient + vignette + gloss behind a glyph, with count/keycap badges. */
+export function IconTreatment({ icon, glyph, school = "neutral", size = 44, count, keycap, active = false, className, style, }) {
+    const [g0, g1] = SCHOOL_GRADIENT[school];
+    const content = glyph ?? (icon !== undefined ? _jsx(GameIcon, { name: icon, size: Math.round(size * 0.58), color: "#fdfdff" }) : null);
+    return (_jsxs("div", { className: className, "data-icon-treatment": school, style: {
+            position: "relative",
+            width: size,
+            height: size,
+            borderRadius: "var(--jg-slot-radius, 9px)",
+            background: `radial-gradient(circle at 38% 30%, ${g0}, ${g1})`,
+            border: active ? "1px solid var(--jg-accent, #38bdf8)" : "var(--jg-slot-border, 1px solid rgba(255,255,255,0.16))",
+            boxShadow: active
+                ? "0 0 0 1px var(--jg-accent, #38bdf8), 0 0 10px rgba(56,189,248,0.5), inset 0 -6px 12px rgba(0,0,0,0.5)"
+                : "inset 0 -7px 13px rgba(0,0,0,0.55), inset 0 2px 3px rgba(255,255,255,0.2)",
+            overflow: "hidden",
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            boxSizing: "border-box",
+            ...style,
+        }, children: [_jsx("div", { style: { position: "absolute", inset: 0, background: "linear-gradient(180deg, rgba(255,255,255,0.3), rgba(255,255,255,0) 46%)", pointerEvents: "none" } }), _jsx("div", { style: { position: "absolute", inset: 0, borderRadius: "inherit", boxShadow: "inset 0 0 12px rgba(0,0,0,0.55)", pointerEvents: "none" } }), content, keycap !== undefined ? (_jsx("span", { style: { position: "absolute", top: 1, left: 4, fontSize: 9, fontWeight: 700, color: "#fff", opacity: 0.75, textShadow: "0 1px 2px rgba(0,0,0,0.9)" }, children: keycap })) : null, count !== undefined && count > 1 ? (_jsx("span", { "data-count": true, style: {
+                    position: "absolute",
+                    bottom: 1,
+                    right: 3,
+                    fontSize: 11,
+                    fontWeight: 800,
+                    color: "#fff",
+                    fontVariantNumeric: "tabular-nums",
+                    textShadow: "0 1px 2px #000, 0 0 3px #000",
+                }, children: count })) : null] }));
+}
+/** Maps an item id to a treated icon — resolves a `GameIcon` glyph and an inferred school. */
+export function treatedItemIcon(itemId, options = {}) {
+    const icon = iconForItemId(itemId) ?? undefined;
+    return (_jsx(IconTreatment, { ...(icon === undefined ? {} : { icon }), school: schoolForItem(itemId), ...(options.size === undefined ? {} : { size: options.size }), ...(options.count === undefined ? {} : { count: options.count }), ...(options.keycap === undefined ? {} : { keycap: options.keycap }) }));
+}
+/** A ready-made `ActionButton` `renderIcon` that paints the action's `GameIcon` with a treatment. */
+export function treatedActionIcon(action, size = 40) {
+    const key = action.id ?? action.label ?? "";
+    const named = iconForAction(key);
+    if (named === null)
+        return action.icon ?? null;
+    return _jsx(IconTreatment, { icon: named, school: schoolForAction(key), size: size });
+}

package/dist/iconsPreview.d.ts

@@ -0,0 +1,4 @@
+/** Renders the school-gradient row and a treated-icon hotbar — the deterministic #1035 fixture. */
+export declare function IconsPreview({ className }: {
+    className?: string;
+}): import("react").JSX.Element;

package/dist/iconsPreview.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { IconTreatment } from "./iconTreatment.js";
+/**
+ * A deterministic showcase of the painted {@link IconTreatment} (#1035): a school row (one gradient
+ * each) and a mock hotbar of treated item icons with count badges and an active slot. Static, so it
+ * screenshots identically every time. This is the before/after evidence vs. raw `itemId` text slots.
+ */
+const SCHOOLS = [
+    ["fire", "bomb"],
+    ["frost", "wand"],
+    ["arcane", "staff"],
+    ["nature", "bow"],
+    ["holy", "shield"],
+    ["tech", "gun"],
+    ["shadow", "dagger"],
+    ["steel", "sword"],
+];
+const HOTBAR = [
+    { icon: "sword", school: "steel" },
+    { icon: "bow", school: "nature" },
+    { icon: "bomb", school: "fire", count: 12 },
+    { icon: "shield", school: "holy" },
+    { icon: "staff", school: "arcane" },
+    { icon: "wand", school: "frost", count: 3 },
+];
+/** Renders the school-gradient row and a treated-icon hotbar — the deterministic #1035 fixture. */
+export function IconsPreview({ className }) {
+    return (_jsxs("div", { "data-icons-preview": true, className: className, style: { display: "flex", flexDirection: "column", gap: 22, padding: 26, background: "#0e1216", fontFamily: "system-ui, sans-serif", color: "#e8edf2" }, children: [_jsxs("div", { children: [_jsx("div", { style: { fontSize: 11, fontWeight: 700, letterSpacing: 0.6, textTransform: "uppercase", opacity: 0.6, marginBottom: 8 }, children: "school gradients" }), _jsx("div", { style: { display: "flex", gap: 10 }, children: SCHOOLS.map(([school, icon]) => (_jsx(IconTreatment, { icon: icon, school: school, size: 52 }, school))) })] }), _jsxs("div", { children: [_jsx("div", { style: { fontSize: 11, fontWeight: 700, letterSpacing: 0.6, textTransform: "uppercase", opacity: 0.6, marginBottom: 8 }, children: "hotbar \u2014 treated icons + count badges (slot 1 active)" }), _jsx("div", { style: { display: "flex", gap: 6 }, children: HOTBAR.map((entry, index) => (_jsx(IconTreatment, { icon: entry.icon, school: entry.school, size: 50, keycap: String(index + 1), active: index === 0, ...(entry.count === undefined ? {} : { count: entry.count }) }, index))) })] })] }));
+}

package/dist/index.d.ts

@@ -10,6 +10,17 @@ export * from "./settings.js";
 export * from "./save.js";
 export * from "./components.js";
 export * from "./hud.js";
+export * from "./bars.js";
+export * from "./barsPreview.js";
+export * from "./iconTreatment.js";
+export * from "./iconsPreview.js";
+export * from "./slots.js";
+export * from "./inventoryGrid.js";
+export * from "./panels.js";
+export * from "./characterSheet.js";
+export * from "./hudTheme.js";
+export * from "./hudThemePreview.js";
+export * from "./hudFrame.js";
 export * from "./keyHint.js";
 export * from "./startScreen.js";
 export * from "./engineStore.js";
@@ -18,6 +29,7 @@ export * from "./cards.js";
 export * from "./actionHud.js";
 export * from "./selectionHud.js";
 export * from "./hudLayout.js";
+export * from "./hudLayoutPersist.js";
 export * from "./hudViewport.js";
 export * from "./gameViewport.js";
 export * from "./rotateDevice.js";

package/dist/index.js

@@ -10,6 +10,17 @@ export * from "./settings.js";
 export * from "./save.js";
 export * from "./components.js";
 export * from "./hud.js";
+export * from "./bars.js";
+export * from "./barsPreview.js";
+export * from "./iconTreatment.js";
+export * from "./iconsPreview.js";
+export * from "./slots.js";
+export * from "./inventoryGrid.js";
+export * from "./panels.js";
+export * from "./characterSheet.js";
+export * from "./hudTheme.js";
+export * from "./hudThemePreview.js";
+export * from "./hudFrame.js";
 export * from "./keyHint.js";
 export * from "./startScreen.js";
 export * from "./engineStore.js";
@@ -18,6 +29,7 @@ export * from "./cards.js";
 export * from "./actionHud.js";
 export * from "./selectionHud.js";
 export * from "./hudLayout.js";
+export * from "./hudLayoutPersist.js";
 export * from "./hudViewport.js";
 export * from "./gameViewport.js";
 export * from "./rotateDevice.js";

package/dist/inventoryGrid.d.ts

@@ -0,0 +1,20 @@
+import { type CSSProperties, type ReactNode } from "react";
+/** Props for {@link InventoryGrid}. */
+export interface InventoryGridProps {
+    /** The declared inventory id to bind (its slot count sets the tile count). */
+    inventoryId: string;
+    /** Grid columns; default derives a squarish grid from the slot count. */
+    columns?: number;
+    /** Tile size in px. Default 44. */
+    size?: number;
+    /** Gap between tiles in px. Default 6. */
+    gap?: number;
+    /** Caller-supplied item id → icon/glyph registry; return null/undefined to fall back to the default `GameIcon`. */
+    itemIcon?: (itemId: string) => ReactNode;
+    /** Invoked when a filled slot is activated (double-click) — e.g. use/equip the item. */
+    onActivate?: (slot: number) => void;
+    className?: string;
+    style?: CSSProperties;
+}
+/** A drop-in inventory grid with drag/swap/stack-merge/split and full keyboard control, bound to `inventoryId`. */
+export declare function InventoryGrid({ inventoryId, columns, size, gap, itemIcon, onActivate, className, style, }: InventoryGridProps): import("react").JSX.Element;