@jgengine/react 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -12,6 +12,32 @@ Agents building on the published SDK can also read this programmatically:
 same data as typed values, so an updater can diff its installed version against
 the latest and surface the migration steps.
 
+## 0.13.0
+
+### Migrate
+
+- **Nothing required** — this release is additive fixes, defaults, and new drop-in primitives. Bump `@jgengine/*` pins to `^0.13.0` (CLI `jgengine` is 0.10.0; `@jgengine/github` unchanged at 0.1.0) and rebuild.
+- Two defaults changed in the player's favor, both overridable: **offline games now persist to localStorage automatically** (#1207) and **rigged catalog assets animate by default** via clip metadata + semantic clip roles (#1209). If a game relied on rigged models staying frozen or on saves being memory-only, opt out explicitly; otherwise you get better behavior for free.
+
+### Added
+
+- **Drop-in inventory grid, window manager, and character sheet** (#1220) — `@jgengine/react` ships `InventoryGrid` (real drag/stack/split), a toggleable-window system (`panels`: bag, character sheet, spellbook-style windows with `@jgengine/core/ui/panelModel` state), and a `CharacterSheet` paperdoll, all HudTheme-skinnable — wire in a line or two instead of re-deriving from raw divs.
+- **Serializable runtime snapshots** (#1179) — capture/restore of live runtime state, including magazine state (`@jgengine/core/combat/magazine`) and stat modifiers, for saves and replication.
+- **Portable weapon plumbing** (#1211) — `@jgengine/core/combat/weaponFire` composes trigger → magazine → spread → projectile/hitscan as data, no game-local glue.
+- **Portable leveling** (#1206) and **portable damage-pool access** (#1208) — progression and damage pools exposed as genre-agnostic seams on the game context.
+- **Named combat VFX presets** (#1204) — `@jgengine/core/combat/vfxPresets`: a visible attack is one line.
+- **Runtime-measured render-bounds hitboxes** (#1227) — colliders wrap what the shell actually mounts, not the raw asset bounds.
+- **Character motion feel** — procedural part motion for rig-less part-composed characters (#1222) plus squash & stretch and death splat (#1229).
+- **City fabric** (#1191) — `streetGenerator` + `cityGenerator`, editor bake verb, street-aware lots, road junctions, grounding, and a web playground.
+- **`jgengine recipe` CLI** (#1214, #1231) — vetted wired compositions, compile-pinned against the SDK, listed and copied from the CLI.
+- **Editor/debug modes mirror to the URL** with a proper editor exit (#1203); game template ships a dependency-free WebGL screenshot script (#1202).
+
+### Changed
+
+- Offline games persist to localStorage by default (#1207); rigged assets animate by default (#1209).
+- RTS camera pan inversion fixed (#1228); sprite raycast warning silenced and duplicate nameplate health bars removed (#1194); scaffolded F2+E editor Tailwind `@source` renders its theme (#1195).
+- Outside-game DX: stat-pool no-op stability, camera-transparent decor, cleaner install/version output, headless UI-intent seam (#1223); new-game briefs direct engine bugs/gaps upstream (#1200).
+
 ## 0.12.0
 
 ### Migrate

package/dist/characterSheet.d.ts

@@ -0,0 +1,120 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type SlotItem } from "./slots.js";
+import { type HudFrameVariation } from "./hudFrame.js";
+/**
+ * Character-sheet / paperdoll composition (#1033 follow-up): a drop-in `<CharacterSheet>` that
+ * arranges caller-supplied equip slots as a paperdoll around a portrait and lists derived stats,
+ * all inside a {@link HudFrame}. It reuses the atomic slot rendering ({@link EquipmentSlots}) and the
+ * shared `--jg-slot-*` / `--jg-accent` HudTheme tokens (#1034) — the game owns which slots and which
+ * stats matter (both are props), the skin, and the window that toggles it open/closed. No genre list
+ * is baked in; {@link defaultEquipLayout} is a convenience arrangement the game can override wholesale.
+ */
+/** Which flank of the paperdoll a slot sits on — `left`/`right` columns, or the `bottom` row under the portrait. */
+export type EquipSlotPosition = "left" | "right" | "bottom";
+/** One named equip slot: a stable `id`, a display `label`, its worn `item` (or `null` = empty), and where it sits. */
+export interface EquipSlot {
+    /** Stable slot id passed to `onSlotActivate` (e.g. `head`, `mainHand`, `ring1`). */
+    id: string;
+    /** Human label shown under/beside the slot and used as its accessible name. */
+    label: string;
+    /** The worn item, or `null` for an empty slot (renders the themed placeholder). */
+    item: SlotItem | null;
+    /** Which flank the slot sits on. Default `left`. */
+    position?: EquipSlotPosition;
+}
+/** An ordered set of equip slots that make up a paperdoll. Caller-supplied; see {@link defaultEquipLayout}. */
+export type EquipSlotLayout = readonly EquipSlot[];
+/** Slot ids used by {@link defaultEquipLayout}'s convenience arrangement. */
+export type DefaultEquipSlotId = "head" | "chest" | "hands" | "legs" | "feet" | "mainHand" | "offHand" | "ring1" | "ring2" | "trinket";
+/**
+ * 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 declare function defaultEquipLayout(items?: Partial<Record<DefaultEquipSlotId, SlotItem | null>>): EquipSlot[];
+/** Props for {@link Paperdoll}. */
+export interface PaperdollProps {
+    /** The equip slots to arrange. Order within a flank is preserved. */
+    slots: EquipSlotLayout;
+    /** Center node — a portrait, 3D preview, or custom art. A silhouette placeholder is drawn when omitted. */
+    portrait?: ReactNode;
+    /** Slot tile size in px. Default 44. */
+    slotSize?: number;
+    /** Fired with the slot `id` on click / Enter / Space — wire drag or an equip picker here. */
+    onSlotActivate?: (id: string) => void;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * 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 declare function Paperdoll({ slots, portrait, slotSize, onSlotActivate, className, style }: PaperdollProps): ReactNode;
+/** One derived-stat row. `group` optionally buckets rows under a small header. */
+export interface StatRow {
+    /** Stable row id. */
+    id: string;
+    /** Small-caps row label (e.g. `Armor`, `Crit`). */
+    label: string;
+    /** The value to show — the game formats it (a number, `"12%"`, `"1.2/s"`). */
+    value: string | number;
+    /** Optional secondary hint shown dimmed after the value (e.g. a delta or source). */
+    hint?: string;
+    /** Optional group header this row falls under; consecutive rows sharing a group render one header. */
+    group?: string;
+}
+/** Props for {@link StatList}. */
+export interface StatListProps {
+    /** Derived stat rows, in display order. The game owns which stats matter. */
+    stats: readonly StatRow[];
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * 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 declare function StatList({ stats, className, style }: StatListProps): ReactNode;
+/** Props for {@link CharacterSheet}. */
+export interface CharacterSheetProps {
+    /** Equip slots to arrange as the paperdoll (see {@link defaultEquipLayout}). */
+    slots: EquipSlotLayout;
+    /** Derived stat rows for the {@link StatList}. */
+    stats: readonly StatRow[];
+    /** Character name shown in the header. */
+    name?: ReactNode;
+    /** Secondary header line — level, class, faction, etc. */
+    subtitle?: ReactNode;
+    /** Portrait node passed through to the {@link Paperdoll} center. */
+    portrait?: ReactNode;
+    /** Replace the whole header block (name/subtitle) with custom content. */
+    header?: ReactNode;
+    /** Frame title label. Default `Character`. */
+    title?: ReactNode;
+    /** {@link HudFrame} skin. Default `themed`. */
+    variation?: HudFrameVariation;
+    /** Slot tile size in px, forwarded to {@link Paperdoll}. */
+    slotSize?: number;
+    /** Fired with the equip slot `id` on activate. */
+    onSlotActivate?: (id: string) => void;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * 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 declare function CharacterSheet({ slots, stats, name, subtitle, portrait, header, title, variation, slotSize, onSlotActivate, className, style, }: CharacterSheetProps): ReactNode;

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/hooks.d.ts

@@ -55,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;

package/dist/hooks.js

@@ -87,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));
 }

package/dist/index.d.ts

@@ -15,6 +15,9 @@ 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";

package/dist/index.js

@@ -15,6 +15,9 @@ 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";

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;

package/dist/inventoryGrid.js

@@ -0,0 +1,135 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
+import { moveGridFocus } from "@jgengine/core/ui/actionModel";
+import { DragGhost, DraggableCard, DropZone, useDragLayer } from "./dragLayer.js";
+import { iconForItemId } from "./gameIcons.js";
+import { IconTreatment, schoolForItem } from "./iconTreatment.js";
+import { useInventoryGrid } from "./hooks.js";
+/**
+ * A drop-in NxN inventory grid bound to a live inventory: `<InventoryGrid inventoryId="bag" columns={4} />`
+ * renders every slot (painted {@link IconTreatment} tile + count badge for filled, a themed `--jg-slot-*`
+ * placeholder for empty), and wires the real mechanics on top of the engine's inventory model —
+ * drag-to-move, swap, stack-merge with remainder (all via the `inventory.move` command), and stack-split
+ * (shift/right-click a stack, via `inventory.split`). Fully keyboard-accessible: `role="grid"`, arrow-key
+ * roving focus, Enter/Space to pick up and drop. Games own placement, skin, and terminology; the engine
+ * ships the working grid.
+ *
+ * @capability inventory-grid-hud drop-in NxN inventory grid with drag/swap/stack/split bound to a live inventory
+ */
+const ARROW_DIRECTIONS = {
+    ArrowRight: "right",
+    ArrowLeft: "left",
+    ArrowUp: "up",
+    ArrowDown: "down",
+    Home: "first",
+    End: "last",
+};
+function EmptySlot({ size, picked }) {
+    return (_jsx("div", { "data-slot-empty": "", style: {
+            width: size,
+            height: size,
+            borderRadius: "var(--jg-slot-radius, 9px)",
+            background: "var(--jg-slot-bg, rgba(12,14,20,0.5))",
+            border: picked
+                ? "1px solid var(--jg-accent, #38bdf8)"
+                : "var(--jg-slot-border, 1px solid rgba(255,255,255,0.1))",
+            boxShadow: "inset 0 2px 6px rgba(0,0,0,0.45)",
+            boxSizing: "border-box",
+        } }));
+}
+/** A drop-in inventory grid with drag/swap/stack-merge/split and full keyboard control, bound to `inventoryId`. */
+export function InventoryGrid({ inventoryId, columns, size = 44, gap = 6, itemIcon, onActivate, className, style, }) {
+    const { slots, move, split } = useInventoryGrid(inventoryId);
+    const cols = columns ?? Math.max(1, Math.ceil(Math.sqrt(slots.length)));
+    const [focus, setFocus] = useState(0);
+    const [picked, setPicked] = useState(null);
+    const cellRefs = useRef(new Map());
+    const layer = useDragLayer({
+        onDrop: (info) => {
+            const target = info.target === null ? null : Number(info.target);
+            if (target !== null && Number.isInteger(target) && target !== info.payload.value) {
+                move(info.payload.value, target);
+            }
+        },
+    });
+    useEffect(() => {
+        if (focus < slots.length)
+            cellRefs.current.get(focus)?.focus();
+    }, [focus, slots.length]);
+    const splitHalf = useCallback((index) => {
+        const slot = slots[index];
+        if (slot !== null && slot !== undefined && slot.count > 1)
+            split(index, Math.floor(slot.count / 2));
+    }, [slots, split]);
+    const onKeyDown = useCallback((event) => {
+        const dir = ARROW_DIRECTIONS[event.key];
+        if (dir !== undefined) {
+            const next = moveGridFocus(focus, slots.length, cols, dir);
+            if (next >= 0) {
+                event.preventDefault();
+                setFocus(next);
+            }
+            return;
+        }
+        if (event.key === "Enter" || event.key === " " || event.key === "Spacebar") {
+            event.preventDefault();
+            if (picked === null) {
+                if (slots[focus] !== null && slots[focus] !== undefined)
+                    setPicked(focus);
+            }
+            else {
+                if (picked !== focus)
+                    move(picked, focus);
+                setPicked(null);
+            }
+            return;
+        }
+        if (event.key === "Escape" && picked !== null) {
+            event.preventDefault();
+            setPicked(null);
+        }
+    }, [focus, slots, cols, picked, move]);
+    const rows = useMemo(() => {
+        const out = [];
+        for (let i = 0; i < slots.length; i += cols) {
+            out.push(Array.from({ length: Math.min(cols, slots.length - i) }, (_, k) => i + k));
+        }
+        return out;
+    }, [slots.length, cols]);
+    const renderTile = (index) => {
+        const slot = slots[index] ?? null;
+        const isPicked = picked === index;
+        const label = slot === null
+            ? `Empty slot ${index + 1}`
+            : `${slot.itemId}${slot.count > 1 ? ` (${slot.count})` : ""}, slot ${index + 1}`;
+        const custom = slot !== null ? itemIcon?.(slot.itemId) : undefined;
+        const named = slot !== null ? iconForItemId(slot.itemId) : null;
+        return (_jsx(DropZone, { id: String(index), layer: layer, children: _jsx("div", { role: "gridcell", "aria-label": label, "aria-selected": isPicked, tabIndex: focus === index ? 0 : -1, "data-slot": index, ref: (node) => {
+                    if (node === null)
+                        cellRefs.current.delete(index);
+                    else
+                        cellRefs.current.set(index, node);
+                }, onFocus: () => setFocus(index), onKeyDown: onKeyDown, onDoubleClick: () => {
+                    if (slot !== null)
+                        onActivate?.(index);
+                }, onClick: (event) => {
+                    if (event.shiftKey) {
+                        event.preventDefault();
+                        splitHalf(index);
+                    }
+                }, onContextMenu: (event) => {
+                    if (slot !== null && slot.count > 1) {
+                        event.preventDefault();
+                        splitHalf(index);
+                    }
+                }, style: { width: size, height: size, position: "relative", cursor: slot !== null ? "grab" : "default" }, children: slot !== null ? (_jsx(DraggableCard, { id: String(index), value: index, layer: layer, onRotate: false, children: custom !== undefined && custom !== null ? (_jsx(IconTreatment, { glyph: custom, size: size, count: slot.count, active: isPicked })) : (_jsx(IconTreatment, { ...(named === null ? {} : { icon: named }), school: schoolForItem(slot.itemId), size: size, count: slot.count, active: isPicked })) })) : (_jsx(EmptySlot, { size: size, picked: isPicked })) }) }, index));
+    };
+    return (_jsxs("div", { role: "grid", "aria-label": `${inventoryId} inventory`, "aria-colcount": cols, className: className, "data-inventory-grid": inventoryId, style: { display: "grid", gap, ...style }, children: [rows.map((row, r) => (_jsx("div", { role: "row", style: { display: "grid", gridTemplateColumns: `repeat(${cols}, ${size}px)`, gap }, children: row.map(renderTile) }, r))), _jsx(DragGhost, { layer: layer, children: (payload) => {
+                    const slot = slots[payload.value] ?? null;
+                    if (slot === null)
+                        return null;
+                    const named = iconForItemId(slot.itemId);
+                    const custom = itemIcon?.(slot.itemId);
+                    return custom !== undefined && custom !== null ? (_jsx(IconTreatment, { glyph: custom, size: size, count: slot.count })) : (_jsx(IconTreatment, { ...(named === null ? {} : { icon: named }), school: schoolForItem(slot.itemId), size: size, count: slot.count }));
+                } })] }));
+}

package/dist/panels.d.ts

@@ -0,0 +1,107 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type PanelDef, type PanelPosition, type PanelState } from "@jgengine/core/ui/panelModel";
+import { type HudFrameShape, type HudFrameVariation } from "./hudFrame.js";
+/**
+ * React chrome over the headless panel/window model (`@jgengine/core/ui/panelModel`) — the toggleable,
+ * draggable, z-stacked windows a WoW-style UI is made of (B for bag, C for character, ESC to close).
+ * `usePanels` is the DATA/HOOK layer (open/close/toggle/focus + a keybind listener), `PanelHost` renders
+ * the open windows in z-order, and `Window` is a standalone one-off window. All unskinned and
+ * token-driven: games reskin via `HudTheme` tokens and by swapping the `HudFrame` variation.
+ */
+/** Intent a key press resolves to over a panel set: toggle a panel, close the top window, or ignore. */
+export interface PanelKeyResult {
+    handled: boolean;
+    type?: "toggle" | "closeTop";
+    id?: string;
+}
+/**
+ * Pure keybind resolver for a panel set: ESC resolves to `closeTop` when a closable window is open, and
+ * any other key routes through {@link panelByHotkey} (trying `code` then `key`) to a `toggle`. Returns
+ * the intent without touching the DOM, so it unit-tests headless and `usePanels` is a thin shell over it.
+ */
+export declare function panelKeyAction(defs: readonly PanelDef[], state: PanelState, event: {
+    code?: string;
+    key?: string;
+}): PanelKeyResult;
+/** Options for {@link usePanels}. */
+export interface UsePanelsOptions {
+    /** Fired when a panel transitions from closed to open (not on refocus of an already-open panel). */
+    onOpen?: (id: string) => void;
+    /** Fired when an open panel is closed. */
+    onClose?: (id: string) => void;
+    /** Set false to skip installing the window keybind/ESC listener (default true). */
+    hotkeys?: boolean;
+}
+/** The live panel manager returned by {@link usePanels} and consumed by {@link PanelHost}. */
+export interface PanelsManager {
+    state: PanelState;
+    defs: readonly PanelDef[];
+    isOpen: (id: string) => boolean;
+    open: (id: string) => void;
+    close: (id: string) => void;
+    toggle: (id: string) => void;
+    focus: (id: string) => void;
+    move: (id: string, pos: PanelPosition) => void;
+    byHotkey: (code: string) => string | null;
+}
+/**
+ * The DATA/HOOK layer: wrap the core panel model in state and install a window keybind listener —
+ * per-panel hotkeys toggle their window and ESC closes the topmost closable one. Hotkeys are ignored
+ * while the player is typing in an input/textarea/contenteditable. The listener is cleaned up on
+ * unmount and SSR-safe (armed in an effect). Feed the returned manager to {@link PanelHost}, or drive a
+ * bespoke window layout from it directly.
+ *
+ * @capability use-panels headless toggleable-window manager with keybind + ESC handling over the core panel model
+ */
+export declare function usePanels(defs: readonly PanelDef[], options?: UsePanelsOptions): PanelsManager;
+/**
+ * Renders the open panels of a {@link usePanels} manager as absolutely-positioned, draggable, closable
+ * windows in z-order — the WoW window layer. Each window uses {@link HudFrame} chrome, is dragged by its
+ * title bar, raises focus on pointer-down, and gets its content from the `render` prop (or a `panels`
+ * map). Accessible: every window is a `role="dialog"` with an `aria-label` and a focusable close button;
+ * ESC-close is wired by the manager. Unskinned — art-direct via `HudTheme` tokens and the `variation`.
+ *
+ * @capability panel-host render a manager's open windows as draggable, closable, z-stacked dialogs
+ */
+export declare function PanelHost({ manager, render, panels, variation, shape, width, className, windowClassName, windowStyle, bodyStyle, }: {
+    manager: PanelsManager;
+    /** Content for a panel by id. Takes precedence over `panels`. */
+    render?: (id: string) => ReactNode;
+    /** Static content map by panel id, used when `render` is omitted. */
+    panels?: Record<string, ReactNode>;
+    variation?: HudFrameVariation;
+    shape?: HudFrameShape;
+    /** Default window width (per-panel unless overridden by the panel content). */
+    width?: number | string;
+    className?: string;
+    windowClassName?: string;
+    windowStyle?: CSSProperties;
+    bodyStyle?: CSSProperties;
+}): import("react").JSX.Element;
+/**
+ * A single standalone window — title bar, close button, and title-bar drag over {@link HudFrame} chrome —
+ * usable without the {@link usePanels} manager for a one-off dialog. Position is uncontrolled (seeded by
+ * `x`/`y`) unless both `x`/`y` and `onMove` are supplied, in which case the caller owns placement.
+ * Accessible: `role="dialog"` with an `aria-label` and a focusable close button.
+ *
+ * @capability window standalone draggable, closable window primitive over HudFrame — no manager required
+ */
+export declare function Window({ title, ariaLabel, closable, onClose, x, y, onMove, z, width, variation, shape, className, style, bodyStyle, children, }: {
+    title: ReactNode;
+    ariaLabel?: string;
+    closable?: boolean;
+    onClose?: () => void;
+    /** Initial (uncontrolled) or current (controlled, with `onMove`) x position. Default 56. */
+    x?: number;
+    /** Initial (uncontrolled) or current (controlled, with `onMove`) y position. Default 56. */
+    y?: number;
+    onMove?: (pos: PanelPosition) => void;
+    z?: number;
+    width?: number | string;
+    variation?: HudFrameVariation;
+    shape?: HudFrameShape;
+    className?: string;
+    style?: CSSProperties;
+    bodyStyle?: CSSProperties;
+    children?: ReactNode;
+}): import("react").JSX.Element;