@jgengine/react 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -10,7 +10,79 @@ let consumers pick up the better stuff, not just to list what moved.
 Agents building on the published SDK can also read this programmatically:
 `import { VERSION, CHANGELOG } from "@jgengine/core/meta/changelog"` gives the
 same data as typed values, so an updater can diff its installed version against
-the latest and surface the migration steps.
+the latest and surface the migration steps. Easier still: `npx jgengine upgrade`
+run inside a game project diffs the installed `@jgengine/*` versions against the
+latest release and prints every Migrate step and Adopt-worthy addition in
+between (`--json` for structured output).
+
+## [Unreleased]
+
+<!--
+Every PR that changes `packages/*/src` records its consumer-facing change here, so
+the next release's notes are complete by construction. Add a bullet under the right
+subhead below. `bun run check-changelog` fails a source PR whose `[Unreleased]` block
+is untouched; pure refactors/tests bypass with `[skip changelog]` in a commit message.
+At publish, rename this heading to the new version and mirror the entries into
+`packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
+-->
+
+### Migrate
+
+- _Nothing yet._
+
+### Added
+
+### Changed
+
+### Removed
+
+## 0.14.0
+
+### Migrate
+
+- **Nothing required** — this release is additive drop-in primitives, editor authoring, CLI discovery, and fixes. Bump `@jgengine/*` pins to `^0.14.0` (CLI `jgengine` is 0.11.0; `@jgengine/github` unchanged at 0.1.0) and rebuild.
+- One behavior fix to know about: in a `rig: "chase"` game, on-foot movement and aim are now camera-relative (the chase rig reports its yaw to the shell like every other rig). If a game somehow relied on world-yaw-0 movement under a chase camera, that was the bug this fixes.
+
+### Added
+
+- One authoring gesture for scatterable coverage: `@jgengine/core/world/scatterCoverage` owns shared density/budget semantics (per-kind unit, requested→count→capped, one clamp-and-warn phrasing) for `grass_field`/`scatter`/`city`; the editor inspector leads each kind with the same Area → Assets → Density coverage section, scatter truncates to the shared 250k instance budget, and city single-sources its 2,600-lot cap.
+- **Created games ship a drive/playtest script** (#1248) — `npx jgengine create` scaffolds now include `scripts/drive.mjs` (`bun run drive`): dependency-free headless play/testing of the running game — ordered `--click`/`--key`/`--wait`/`--shot`/`--rpc` steps against the agent bridge, plus `--playtest --strict` progress/softlock verdicts off `capture.probe`. Shared Chrome/CDP machinery lives in `scripts/browser.mjs`; `scripts/shoot.mjs` is unchanged in behavior, now a thin CLI over it.
+- Editor: viewport clip preview for rigged assets (Animation dock "Clips" mode — pick a rig or placed instance, play/scrub/loop/speed any catalog clip) and an Inspector "Animation" section that authors a placement's `ModelConfig.animation` (role→clip dropdowns, auto/none, walk/run/fade, one-shot event bindings) as undoable `marker.meta.animation` edits. New subpaths: `@jgengine/editor/shell/clipPreview`, `@jgengine/editor/modelAnimationAuthoring`, `@jgengine/editor/ClipPreviewLayer`.
+- **`npx jgengine find <intent>`** — active capability discovery: searches every shipped domain's `capabilities.md` (staged inside the CLI tarball, so it works regardless of which `@jgengine/*` packages a project installed) and prints the drop-in primitive + its import for an intent like `"toggleable window"`, `inventory`, or `minimap`. Scaffolded games are now briefed (in `AGENTS.md` and the `jgengine` intake skill) to reach for it before hand-rolling a HUD/inventory/window/rig.
+- **`EntityPreview`** (`@jgengine/shell/render/EntityPreview`) — drop-in live 3D entity portrait for character screens, unit inspectors, and loadout viewers. Owns the nested `<Canvas>`, the `GameContextBridge`, and a `StudioStage` lighting rig with optional turntable / face-camera; the game passes its own `renderEntity` as children (or a native `model` + `instanceId`) and, bound to a live entity, the portrait walks/flinches/topples in sync with the world.
+- **`GameContextBridge`** (`@jgengine/react`) — re-provide the running `GameContext` across a nested React reconciler boundary (the R3F `<Canvas>`), so a game building its own preview canvas no longer re-derives the bridge by hand.
+
+### Changed
+
+- **Chase rig reports its yaw to the shell** — `ChaseRig` now writes the camera yaw back to the shared yaw ref like every other player-facing rig, so on-foot movement and aim in a `rig: "chase"` game are camera-relative instead of frozen to world yaw 0 (WASD no longer fights the camera the moment it swings behind the player). Interior views (cockpit/hood/rear) report the vehicle heading.
+- **Combat VFX no longer render as black squares under AO/DOF post-processing** (#1247) — GTAO/Bokeh scene prepasses skip overlay effects. Games with custom additive overlay effects opt out the same way: spread `POSTFX_OVERLAY_USERDATA` (`@jgengine/shell/postfx/postfxOverlay`) onto the overlay group's `userData`.
+- **`PanelHost` windows stack above the HUD by default** (`@jgengine/react`) — the host establishes its own stacking context at `zIndexBase` (default 40), so open windows always paint over stat bars / nameplates / frames instead of bleeding through. Overridable per instance.
+
+## 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
 

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/hudLayout.js

@@ -22,6 +22,91 @@ const EDIT_BAR_Z = 100000;
 const REGION_GAP = 10;
 const COMPACT_HUD_SCALE = 0.85;
 const HUD_ANCHORS = Object.keys(HUD_ANCHOR_FRACTIONS);
+/**
+ * Attribute a game puts on any HUD surface it *wants* to bleed past the viewport
+ * (a full-bleed backdrop, a deliberately clipped ticker), so the boundary check
+ * skips it. Opt-out, on purpose: the default is that shown UI must fit on screen.
+ */
+const ALLOW_OVERFLOW_ATTR = "data-hud-allow-overflow";
+/** Opt-in marker for a custom window mounted deeper than a direct HudCanvas child. */
+const WINDOW_ATTR = "data-hud-window";
+/**
+ * Dev-only, prod-safe. The on-screen boundary overlay must never reach players,
+ * so anything we cannot positively identify as a dev build resolves to `false`.
+ */
+function isDevBuild() {
+    try {
+        const meta = import.meta;
+        if (meta.env?.DEV === true)
+            return true;
+        if (meta.env?.PROD === true)
+            return false;
+    }
+    catch {
+        /* import.meta.env unavailable under this bundler */
+    }
+    const nodeEnv = globalThis.process
+        ?.env?.NODE_ENV;
+    if (typeof nodeEnv === "string")
+        return nodeEnv !== "production";
+    return false;
+}
+/** True unless the element (or an ancestor) is hidden, collapsed, or removed from the a11y tree. */
+function isSurfaceShown(el) {
+    if (el.closest('[aria-hidden="true"]') !== null)
+        return false;
+    const checkable = el;
+    if (typeof checkable.checkVisibility === "function") {
+        return checkable.checkVisibility({
+            contentVisibilityAuto: true,
+            opacityProperty: true,
+            visibilityProperty: true,
+        });
+    }
+    if (typeof getComputedStyle !== "function")
+        return true;
+    const style = getComputedStyle(el);
+    return style.visibility !== "hidden" && style.display !== "none" && Number(style.opacity) > 0.01;
+}
+function surfaceId(el) {
+    return (el.getAttribute("data-hud-panel") ??
+        el.getAttribute(WINDOW_ATTR) ??
+        el.getAttribute("data-hud-id") ??
+        el.getAttribute("aria-label") ??
+        (el.id.length > 0 ? el.id : null) ??
+        "<ui>");
+}
+/**
+ * Every HUD surface whose bounds we hold to the viewport: registered panels,
+ * any element tagged as a window, and the game's own direct children of the
+ * canvas (custom modals dropped straight into the HUD layer). Opted-out and
+ * hidden surfaces are dropped here so a closed drawer never reaches the check.
+ */
+function collectBoundarySurfaces(canvas) {
+    const seen = new Set();
+    const out = [];
+    const consider = (el) => {
+        if (seen.has(el))
+            return;
+        seen.add(el);
+        if (el.closest(`[${ALLOW_OVERFLOW_ATTR}]`) !== null)
+            return;
+        if (!isSurfaceShown(el))
+            return;
+        out.push({ id: surfaceId(el), el });
+    };
+    for (const el of canvas.querySelectorAll(`[data-hud-panel],[${WINDOW_ATTR}]`))
+        consider(el);
+    for (const el of Array.from(canvas.children)) {
+        if (el.hasAttribute("data-hud-region") ||
+            el.hasAttribute("data-hud-edit-bar") ||
+            el.hasAttribute("data-hud-overflow-overlay")) {
+            continue;
+        }
+        consider(el);
+    }
+    return out;
+}
 function sizeStyle(panel) {
     if (panel === undefined)
         return {};
@@ -200,6 +285,7 @@ export function HudCanvas({ layout, editChord, compactScale, showDuring, classNa
     const fitEnabled = hudViewport?.fitEnabled === true;
     const [viewport, setViewport] = useState(null);
     const [regions, setRegions] = useState({});
+    const [offenders, setOffenders] = useState([]);
     const regionRefs = useMemo(() => {
         const refs = {};
         for (const anchor of HUD_ANCHORS) {
@@ -285,18 +371,20 @@ export function HudCanvas({ layout, editChord, compactScale, showDuring, classNa
             return;
         let frame = 0;
         let lastReport = "";
+        const dev = isDevBuild();
         const check = () => {
             frame = 0;
             const hostRect = host.getBoundingClientRect();
             if (hostRect.width <= 0 || hostRect.height <= 0)
                 return;
-            const panels = [];
-            for (const el of canvas.querySelectorAll("[data-hud-panel]")) {
-                const rect = el.getBoundingClientRect();
+            const viewportSize = { width: hostRect.width, height: hostRect.height };
+            const surfaces = [];
+            for (const surface of collectBoundarySurfaces(canvas)) {
+                const rect = surface.el.getBoundingClientRect();
                 if (rect.width === 0 && rect.height === 0)
                     continue;
-                panels.push({
-                    id: el.getAttribute("data-hud-panel") ?? "?",
+                surfaces.push({
+                    id: surface.id,
                     rect: {
                         x: rect.left - hostRect.left,
                         y: rect.top - hostRect.top,
@@ -305,8 +393,10 @@ export function HudCanvas({ layout, editChord, compactScale, showDuring, classNa
                     },
                 });
             }
-            const offenders = overflowingPanels(panels, { width: hostRect.width, height: hostRect.height });
-            const report = offenders.length === 0 ? "" : JSON.stringify(offenders);
+            // overflowingPanels reports only surfaces that are partly on screen *and*
+            // cross an edge — a closed/parked/off-screen menu is never an offender.
+            const escaped = overflowingPanels(surfaces, viewportSize);
+            const report = escaped.length === 0 ? "" : JSON.stringify(escaped);
             if (report === lastReport)
                 return;
             lastReport = report;
@@ -315,7 +405,13 @@ export function HudCanvas({ layout, editChord, compactScale, showDuring, classNa
             }
             else {
                 canvas.setAttribute("data-hud-overflow", report);
-                console.warn(`[jgengine] HUD panels overflow the ${Math.round(hostRect.width)}x${Math.round(hostRect.height)} viewport: ${report}`);
+                console.warn(`[jgengine] HUD UI escapes the ${Math.round(hostRect.width)}x${Math.round(hostRect.height)} viewport: ${report}`);
+            }
+            if (dev) {
+                setOffenders(escaped.map((overflow) => {
+                    const rect = surfaces.find((s) => s.id === overflow.id)?.rect;
+                    return { ...overflow, x: rect?.x ?? 0, y: rect?.y ?? 0, width: rect?.width ?? 0, height: rect?.height ?? 0 };
+                }));
             }
         };
         const schedule = () => {
@@ -365,7 +461,40 @@ export function HudCanvas({ layout, editChord, compactScale, showDuring, classNa
                         pointerEvents: "none",
                         zIndex: 1,
                         ...REGION_LAYOUT[anchor],
-                    } }, anchor))), children, editing ? _jsx(HudEditBar, { layout: layout }) : null] }) }));
+                    } }, anchor))), children, offenders.length > 0 ? (_jsx("div", { "data-hud-overflow-overlay": "", style: { position: "absolute", inset: 0, pointerEvents: "none", zIndex: EDIT_BAR_Z - 1 }, children: offenders.map((o) => (_jsx("div", { style: {
+                            position: "absolute",
+                            left: o.x / scale,
+                            top: o.y / scale,
+                            width: o.width / scale,
+                            height: o.height / scale,
+                            border: "2px solid rgba(255, 64, 64, 0.95)",
+                            boxShadow: "0 0 0 2px rgba(255, 64, 64, 0.3)",
+                            boxSizing: "border-box",
+                        }, children: _jsxs("span", { style: {
+                                position: "absolute",
+                                left: 0,
+                                bottom: "100%",
+                                marginBottom: 2,
+                                padding: "2px 6px",
+                                borderRadius: 4,
+                                background: "rgba(180, 20, 20, 0.95)",
+                                color: "#fff",
+                                font: "600 10px/1.4 system-ui, sans-serif",
+                                whiteSpace: "nowrap",
+                            }, children: ["\u26A0 ", o.id, " escapes viewport (", overflowEdges(o), ")"] }) }, o.id))) })) : null, editing ? _jsx(HudEditBar, { layout: layout }) : null] }) }));
+}
+/** Human-readable edge list for the dev boundary badge, e.g. `right +260 · bottom +56`. */
+function overflowEdges(overflow) {
+    const parts = [];
+    if (overflow.left > 0)
+        parts.push(`left +${overflow.left}`);
+    if (overflow.top > 0)
+        parts.push(`top +${overflow.top}`);
+    if (overflow.right > 0)
+        parts.push(`right +${overflow.right}`);
+    if (overflow.bottom > 0)
+        parts.push(`bottom +${overflow.bottom}`);
+    return parts.length > 0 ? parts.join(" · ") : "edge";
 }
 function chipAlignment(anchor) {
     if (anchor.endsWith("right"))

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;