@jgengine/react 0.11.0 → 0.13.0

package/dist/characterSheet.js

@@ -0,0 +1,134 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import {} from "react";
+import { EquipmentSlots } from "./slots.js";
+import { HudFrame } from "./hudFrame.js";
+const DEFAULT_ARRANGEMENT = [
+    { id: "head", label: "Head", position: "left" },
+    { id: "chest", label: "Chest", position: "left" },
+    { id: "hands", label: "Hands", position: "left" },
+    { id: "legs", label: "Legs", position: "left" },
+    { id: "feet", label: "Feet", position: "left" },
+    { id: "mainHand", label: "Main Hand", position: "right" },
+    { id: "offHand", label: "Off Hand", position: "right" },
+    { id: "ring1", label: "Ring", position: "right" },
+    { id: "ring2", label: "Ring", position: "right" },
+    { id: "trinket", label: "Trinket", position: "right" },
+];
+/**
+ * A sensible default paperdoll arrangement — worn armor down the left flank, held gear and jewelry
+ * down the right — that the game fills by passing worn items keyed by slot id. Every id is optional;
+ * unfilled slots render empty. Games that need a different slot set pass their own {@link EquipSlotLayout}.
+ */
+export function defaultEquipLayout(items = {}) {
+    return DEFAULT_ARRANGEMENT.map((slot) => ({
+        id: slot.id,
+        label: slot.label,
+        item: items[slot.id] ?? null,
+        position: slot.position,
+    }));
+}
+function SlotLabel({ children }) {
+    return (_jsx("span", { style: {
+            fontSize: 9,
+            letterSpacing: 0.6,
+            fontVariant: "small-caps",
+            textTransform: "lowercase",
+            color: "var(--jg-bar-text, #f4f6fb)",
+            opacity: 0.62,
+            whiteSpace: "nowrap",
+        }, children: children }));
+}
+function EquipSlotCell({ slot, slotSize, align, onSlotActivate, }) {
+    const interactive = onSlotActivate !== undefined;
+    const activate = interactive ? () => onSlotActivate(slot.id) : undefined;
+    return (_jsxs("div", { "data-equip-slot": slot.id, role: "group", "aria-label": slot.label, tabIndex: interactive ? 0 : undefined, ...(activate === undefined ? {} : { onClick: activate }), ...(activate === undefined
+            ? {}
+            : {
+                onKeyDown: (event) => {
+                    if (event.key === "Enter" || event.key === " ") {
+                        event.preventDefault();
+                        activate();
+                    }
+                },
+            }), style: {
+            display: "flex",
+            flexDirection: "column",
+            alignItems: align === "center" ? "center" : align === "right" ? "flex-end" : "flex-start",
+            gap: 3,
+            cursor: interactive ? "pointer" : undefined,
+        }, children: [_jsx(EquipmentSlots, { items: [slot.item], size: slotSize }), _jsx(SlotLabel, { children: slot.label })] }));
+}
+function Silhouette({ size }) {
+    return (_jsx("div", { "data-paperdoll-silhouette": "", "aria-hidden": true, style: {
+            width: size,
+            height: Math.round(size * 2.6),
+            borderRadius: "var(--jg-slot-radius, 9px)",
+            background: "var(--jg-slot-bg, rgba(12,14,20,0.5))",
+            border: "var(--jg-slot-border, 1px solid rgba(255,255,255,0.1))",
+            boxShadow: "inset 0 2px 10px rgba(0,0,0,0.5)",
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            color: "var(--jg-bar-text, #f4f6fb)",
+            opacity: 0.28,
+            fontSize: Math.round(size * 0.9),
+            boxSizing: "border-box",
+        }, children: _jsx("span", { "aria-hidden": true, children: "\u265F" }) }));
+}
+/**
+ * Arranges caller-supplied equip slots as a paperdoll — worn gear in two flanking columns around a
+ * center `portrait` (or a silhouette placeholder), with any `bottom` slots in a row beneath it. Each
+ * slot reuses the atomic {@link EquipmentSlots} tile (filled icon or themed empty placeholder), carries
+ * a label, and is a focusable `role="group"` with an `aria-label`; `onSlotActivate` fires on
+ * click/Enter/Space so games can wire drag or an equip picker. Composition and skin stay the game's.
+ *
+ * @capability character-paperdoll equip-slot paperdoll — flanking columns around a portrait, activatable slots
+ */
+export function Paperdoll({ slots, portrait, slotSize = 44, onSlotActivate, className, style }) {
+    const left = slots.filter((s) => (s.position ?? "left") === "left");
+    const right = slots.filter((s) => s.position === "right");
+    const bottom = slots.filter((s) => s.position === "bottom");
+    const column = (cells, align) => (_jsx("div", { style: { display: "flex", flexDirection: "column", gap: 10, alignItems: align === "right" ? "flex-end" : "flex-start" }, children: cells.map((slot) => (_jsx(EquipSlotCell, { slot: slot, slotSize: slotSize, align: align, ...(onSlotActivate === undefined ? {} : { onSlotActivate }) }, slot.id))) }));
+    return (_jsxs("div", { "data-paperdoll": "", className: className, style: { display: "flex", flexDirection: "column", alignItems: "center", gap: 12, ...style }, children: [_jsxs("div", { style: { display: "flex", gap: 16, alignItems: "flex-start", justifyContent: "center" }, children: [column(left, "right"), _jsx("div", { "data-paperdoll-portrait": "", style: { display: "flex", alignItems: "center", justifyContent: "center", alignSelf: "stretch" }, children: portrait ?? _jsx(Silhouette, { size: slotSize * 1.4 }) }), column(right, "left")] }), bottom.length > 0 ? (_jsx("div", { style: { display: "flex", gap: 12, justifyContent: "center" }, children: bottom.map((slot) => (_jsx(EquipSlotCell, { slot: slot, slotSize: slotSize, align: "center", ...(onSlotActivate === undefined ? {} : { onSlotActivate }) }, slot.id))) })) : null] }));
+}
+function StatListRow({ row }) {
+    return (_jsxs("div", { "data-stat-row": row.id, style: { display: "flex", justifyContent: "space-between", alignItems: "baseline", gap: 12, padding: "2px 0" }, children: [_jsx("span", { style: { fontSize: 11, fontVariant: "small-caps", letterSpacing: 0.5, color: "var(--jg-bar-text, #f4f6fb)", opacity: 0.72 }, children: row.label }), _jsxs("span", { style: { fontSize: 12, fontWeight: 700, fontVariantNumeric: "tabular-nums", color: "var(--jg-accent, #38bdf8)" }, children: [row.value, row.hint !== undefined ? (_jsx("span", { style: { marginLeft: 5, fontWeight: 500, color: "var(--jg-bar-text, #f4f6fb)", opacity: 0.5 }, children: row.hint })) : null] })] }));
+}
+/**
+ * Renders derived character stats as clean small-caps label→value rows, token-themed. Rows carrying a
+ * `group` field are bucketed under a small uppercase header (consecutive same-group rows share one).
+ * Pure and prop-driven — the game supplies the rows (from `useEntityStat`/derived values); the engine
+ * ships no stat list of its own.
+ *
+ * @capability character-statlist derived-stat readout — grouped small-caps label→value rows, token-themed
+ */
+export function StatList({ stats, className, style }) {
+    const groups = [];
+    for (const row of stats) {
+        const last = groups[groups.length - 1];
+        if (last !== undefined && last.name === row.group)
+            last.rows.push(row);
+        else
+            groups.push({ name: row.group, rows: [row] });
+    }
+    return (_jsx("div", { "data-stat-list": "", className: className, style: { display: "flex", flexDirection: "column", gap: 4, ...style }, children: groups.map((group, index) => (_jsxs("div", { "data-stat-group": group.name ?? "", children: [group.name !== undefined ? (_jsx("div", { style: {
+                        fontSize: 9,
+                        letterSpacing: 1.4,
+                        textTransform: "uppercase",
+                        opacity: 0.55,
+                        margin: "6px 0 2px",
+                        color: "var(--jg-bar-text, #f4f6fb)",
+                    }, children: group.name })) : null, group.rows.map((row) => (_jsx(StatListRow, { row: row }, row.id)))] }, index))) }));
+}
+/**
+ * Drop-in character sheet: a {@link HudFrame} wrapping an optional name/subtitle/portrait header, the
+ * equip-slot {@link Paperdoll}, and the derived-stat {@link StatList}. The game supplies slots, stats,
+ * header content, and the activation callback, and owns the window that toggles it (this component does
+ * not manage its own open/close). Pure composition over existing primitives and HudTheme tokens.
+ *
+ * @capability character-sheet drop-in paperdoll + derived-stat sheet in a HudFrame — game supplies slots/stats
+ */
+export function CharacterSheet({ slots, stats, name, subtitle, portrait, header, title = "Character", variation = "themed", slotSize, onSlotActivate, className, style, }) {
+    const hasHeader = header !== undefined || name !== undefined || subtitle !== undefined;
+    return (_jsx(HudFrame, { variation: variation, title: title, interactive: true, padding: 14, ...(className === undefined ? {} : { className }), ...(style === undefined ? {} : { style }), children: _jsxs("div", { "data-character-sheet": "", style: { display: "flex", flexDirection: "column", gap: 12, minWidth: 260 }, children: [hasHeader ? (_jsx("div", { "data-character-header": "", style: { display: "flex", flexDirection: "column", gap: 1 }, children: header ?? (_jsxs(_Fragment, { children: [name !== undefined ? _jsx("div", { style: { fontSize: 16, fontWeight: 800, letterSpacing: 0.2 }, children: name }) : null, subtitle !== undefined ? (_jsx("div", { style: { fontSize: 11, opacity: 0.65, fontVariant: "small-caps", letterSpacing: 0.4 }, children: subtitle })) : null] })) })) : null, _jsxs("div", { style: { display: "flex", gap: 18, alignItems: "flex-start", flexWrap: "wrap" }, children: [_jsx(Paperdoll, { slots: slots, ...(portrait === undefined ? {} : { portrait }), ...(slotSize === undefined ? {} : { slotSize }), ...(onSlotActivate === undefined ? {} : { onSlotActivate }) }), _jsx(StatList, { stats: stats, style: { flex: "1 1 140px", minWidth: 140 } })] })] }) }));
+}

package/dist/components.d.ts

@@ -12,7 +12,14 @@ export declare function SlotGrid({ inventoryId, className, renderSlot, }: {
     className?: string;
     renderSlot?: (slot: InventorySlot, index: number) => ReactNode;
 }): import("react").JSX.Element;
-export declare function HealthBar({ instanceId, statId, className, fillClassName, }: {
+/**
+ * A headless, unstyled stat meter — an accessible `role="progressbar"` you paint entirely through
+ * `className`/`fillClassName`. This is the class-hook primitive for teams supplying their own CSS;
+ * for a batteries-included themed bar use the atomic, token-styled components in
+ * `@jgengine/react/bars` (`HealthBar`, `ShieldBar`, …). Renamed from `HealthBar` in #1033 so the
+ * purpose-named atomic bar owns that name and no two components share it.
+ */
+export declare function StatMeter({ instanceId, statId, className, fillClassName, }: {
     instanceId: string;
     statId: string;
     className?: string;

package/dist/components.js

@@ -17,7 +17,14 @@ export function SlotGrid({ inventoryId, className, renderSlot, }) {
                     ? `${slot.itemId} x${slot.count}`
                     : null }, index))) }));
 }
-export function HealthBar({ instanceId, statId, className, fillClassName, }) {
+/**
+ * A headless, unstyled stat meter — an accessible `role="progressbar"` you paint entirely through
+ * `className`/`fillClassName`. This is the class-hook primitive for teams supplying their own CSS;
+ * for a batteries-included themed bar use the atomic, token-styled components in
+ * `@jgengine/react/bars` (`HealthBar`, `ShieldBar`, …). Renamed from `HealthBar` in #1033 so the
+ * purpose-named atomic bar owns that name and no two components share it.
+ */
+export function StatMeter({ instanceId, statId, className, fillClassName, }) {
     const stat = useEntityStat(instanceId, statId);
     if (stat === null)
         return null;

package/dist/hooks.d.ts

@@ -1,4 +1,6 @@
+import { type DependencyList } from "react";
 import { AxisChannel, type AxisChannelConfig } from "@jgengine/core/input/axisInput";
+import { type MarkerSet } from "@jgengine/core/world/markers";
 import type { GameContext } from "@jgengine/core/runtime/gameContext";
 import type { AbilityKit, AbilitySlotSnapshot } from "@jgengine/core/combat/abilityKit";
 import type { EventMeter } from "@jgengine/core/stats/eventMeter";
@@ -53,6 +55,17 @@ export declare function useNearestWorldItem(radius: number): WorldItemRecord | n
 export declare function useEntityStat(instanceId: string, statId: string): StatValue | null;
 export declare function useTarget(fromInstanceId: string): string | null;
 export declare function useInventory(inventoryId: string): readonly InventorySlot[];
+/** Live slots plus `move`/`split` actions bound to `inventoryId`, routed through the notifying `inventory.move`/`inventory.split` commands so React re-renders. */
+export interface InventoryGridBinding {
+    slots: readonly InventorySlot[];
+    move(from: number, to: number): void;
+    split(slot: number, amount: number, toSlot?: number): void;
+}
+/**
+ * Binds a live inventory to a HUD grid: `slots` from {@link useInventory}, and `move`/`split` that run
+ * the built-in `inventory.move`/`inventory.split` commands (which notify, so the grid re-renders).
+ */
+export declare function useInventoryGrid(inventoryId: string): InventoryGridBinding;
 export declare function useCurrency(currencyId: string): number;
 export declare function useFeed({ action, limit }: {
     action: string;
@@ -123,6 +136,24 @@ export interface EventMeterView {
  * @capability event-meter-hud render a core event/heat meter's live value, fraction, tier, and ready state in a HUD gauge
  */
 export declare function useEventMeter(meter: EventMeter, options?: AbilitySlotBindingOptions): EventMeterView;
+/**
+ * A self-ticking {@link MarkerSet} kept in sync with the live scene: on a
+ * heartbeat (default 100ms, and once immediately) it clears the set and calls
+ * `rebuild(markers, ctx)` to repopulate it from the current scene, so a HUD map
+ * never hand-rolls a `setInterval` + `markers.clear()` + rescan. Each heartbeat
+ * also re-renders the calling component, so player-centered props derived from
+ * the live scene each tick (`center`, `facingYaw`, zone name) stay fresh — this
+ * fully subsumes the hand-rolled ticker, not just the marker rebuild. The set is
+ * stable across renders and re-seeded whenever `ctx`, `intervalMs`, or the
+ * supplied `deps` change. SSR-safe: the heartbeat only arms when `window` is
+ * available.
+ *
+ * @capability live-markers a self-ticking MarkerSet kept in sync from the live scene each HUD tick — pass a rebuild(markers, ctx) that clears+repopulates, no hand-rolled setInterval
+ */
+export declare function useLiveMarkers(rebuild: (markers: MarkerSet, ctx: GameContext) => void, options?: {
+    intervalMs?: number;
+    deps?: DependencyList;
+}): MarkerSet;
 type HeldKeyEventTarget = Pick<Window, "addEventListener" | "removeEventListener">;
 export declare function createHeldKeyTracker(target: HeldKeyEventTarget): {
     isDown: (code: string) => boolean;

package/dist/hooks.js

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { AxisChannel } from "@jgengine/core/input/axisInput";
+import { createMarkerSet } from "@jgengine/core/world/markers";
 import { browseSessions, } from "@jgengine/core/multiplayer/matchmaking";
 import { resolveActivePrompt, } from "@jgengine/core/interaction/proximityPrompt";
 import { gamePhase, setGamePhase } from "@jgengine/core/game/gamePhase";
@@ -86,6 +87,21 @@ export function useTarget(fromInstanceId) {
 export function useInventory(inventoryId) {
     return useGameStore((ctx) => ctx.player.inventory.state(inventoryId).slots);
 }
+/**
+ * Binds a live inventory to a HUD grid: `slots` from {@link useInventory}, and `move`/`split` that run
+ * the built-in `inventory.move`/`inventory.split` commands (which notify, so the grid re-renders).
+ */
+export function useInventoryGrid(inventoryId) {
+    const slots = useInventory(inventoryId);
+    const { commands } = useGame();
+    const move = useCallback((from, to) => {
+        commands.run("inventory.move", { inventoryId, from, to });
+    }, [commands, inventoryId]);
+    const split = useCallback((slot, amount, toSlot) => {
+        commands.run("inventory.split", toSlot === undefined ? { inventoryId, slot, amount } : { inventoryId, slot, amount, toSlot });
+    }, [commands, inventoryId]);
+    return useMemo(() => ({ slots, move, split }), [slots, move, split]);
+}
 export function useCurrency(currencyId) {
     return useGameStore((ctx) => ctx.game.economy.balance(ctx.player.userId, currencyId));
 }
@@ -275,6 +291,43 @@ export function useEventMeter(meter, options) {
     previous.current = view;
     return view;
 }
+/**
+ * A self-ticking {@link MarkerSet} kept in sync with the live scene: on a
+ * heartbeat (default 100ms, and once immediately) it clears the set and calls
+ * `rebuild(markers, ctx)` to repopulate it from the current scene, so a HUD map
+ * never hand-rolls a `setInterval` + `markers.clear()` + rescan. Each heartbeat
+ * also re-renders the calling component, so player-centered props derived from
+ * the live scene each tick (`center`, `facingYaw`, zone name) stay fresh — this
+ * fully subsumes the hand-rolled ticker, not just the marker rebuild. The set is
+ * stable across renders and re-seeded whenever `ctx`, `intervalMs`, or the
+ * supplied `deps` change. SSR-safe: the heartbeat only arms when `window` is
+ * available.
+ *
+ * @capability live-markers a self-ticking MarkerSet kept in sync from the live scene each HUD tick — pass a rebuild(markers, ctx) that clears+repopulates, no hand-rolled setInterval
+ */
+export function useLiveMarkers(rebuild, options) {
+    const ctx = useGameContext();
+    const markers = useMemo(() => createMarkerSet(() => ctx.time.now()), [ctx]);
+    const rebuildRef = useRef(rebuild);
+    rebuildRef.current = rebuild;
+    const intervalMs = options?.intervalMs ?? 100;
+    const deps = options?.deps ?? [];
+    const [, forceTick] = useState(0);
+    useEffect(() => {
+        const run = () => {
+            markers.clear();
+            rebuildRef.current(markers, ctx);
+            forceTick((value) => (value + 1) % 1_000_000);
+        };
+        run();
+        if (intervalMs <= 0 || typeof window === "undefined")
+            return undefined;
+        const id = window.setInterval(run, intervalMs);
+        return () => window.clearInterval(id);
+        // deps is spread so callers can re-seed on their own inputs.
+    }, [markers, ctx, intervalMs, ...deps]);
+    return markers;
+}
 export function createHeldKeyTracker(target) {
     const held = new Set();
     const onKeyDown = (event) => held.add(event.code);

package/dist/hud.d.ts

@@ -7,6 +7,13 @@ export type StatTone = keyof typeof TONES;
  * 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 declare function StatBar({ statId, entityId, tone, label, showValue, width, icon, style, className, }: {
     statId?: string;
@@ -20,14 +27,20 @@ export declare function StatBar({ statId, entityId, tone, label, showValue, widt
     className?: string;
 }): import("react").JSX.Element | null;
 /**
- * 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 declare function Hotbar({ inventoryId, activeSlot, keys, slotSize, style, className, }: {
+export declare function Hotbar({ inventoryId, activeSlot, keys, slotSize, itemIcon, style, className, }: {
     inventoryId: string;
     activeSlot?: number;
     keys?: readonly string[];
     slotSize?: number;
+    /** Caller-supplied item id → icon registry; return null/undefined to fall back to the default glyph. */
+    itemIcon?: (itemId: string) => ReactNode;
     style?: CSSProperties;
     className?: string;
 }): import("react").JSX.Element;
@@ -49,6 +62,8 @@ export declare function Speedometer({ entityId, scale, unit, max, size, style, c
  * 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 declare function Clock({ format, showDay, controls, style, className, }: {
     format?: "24h" | "12h";
@@ -68,7 +83,9 @@ export declare function WaveBanner({ wave, label, subtitle, style, className, }:
     style?: CSSProperties;
     className?: string;
 }): import("react").JSX.Element;
-/** 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 declare function Coins({ currencyId, icon, style, className, }: {
     currencyId: string;
     icon?: ReactNode;

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;