@jgengine/react 0.12.0 → 0.14.0

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,115 @@
+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`.
+ *
+ * The host establishes its own stacking context at `zIndexBase` (default 40) so windows always paint
+ * *above* the HUD (stat bars, nameplates, frames typically sit at z 10–30) — no game should have to
+ * rediscover "my vitals bar bleeds through the open window" and wrap this in a `z-*` of its own. Per-
+ * window focus order still resolves inside that context, so clicking a window raises it over its peers.
+ * Raise `zIndexBase` to sit above a full-screen modal, or lower it to tuck windows beneath one.
+ *
+ * @capability panel-host render a manager's open windows as draggable, closable, z-stacked dialogs above the HUD
+ */
+export declare function PanelHost({ manager, render, panels, variation, shape, width, zIndexBase, 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;
+    /** z-index of the host's stacking context — the floor every window paints above. Default 40 (above the HUD). */
+    zIndexBase?: number;
+    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;

package/dist/panels.js

@@ -0,0 +1,221 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState, } from "react";
+import { closePanel, closeTopPanel, createPanelState, focusPanel, isOpen as isPanelOpen, movePanel, openPanel, orderedOpen, panelByHotkey, } from "@jgengine/core/ui/panelModel";
+import { HudFrame } from "./hudFrame.js";
+/**
+ * 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 function panelKeyAction(defs, state, event) {
+    if (event.key === "Escape" || event.code === "Escape") {
+        return closeTopPanel(state) === state ? { handled: false } : { handled: true, type: "closeTop" };
+    }
+    const id = (event.code !== undefined ? panelByHotkey(defs, event.code) : null) ??
+        (event.key !== undefined ? panelByHotkey(defs, event.key) : null);
+    return id === null ? { handled: false } : { handled: true, type: "toggle", id };
+}
+/** @internal True when a key event targets a text input / textarea / contenteditable, where hotkeys must not fire. */
+function isEditableTarget(target) {
+    const el = target;
+    if (el === null || typeof el.tagName !== "string")
+        return false;
+    const tag = el.tagName.toLowerCase();
+    return tag === "input" || tag === "textarea" || tag === "select" || el.isContentEditable === true;
+}
+/**
+ * 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 function usePanels(defs, options) {
+    const [state, setState] = useState(() => createPanelState(defs));
+    const stateRef = useRef(state);
+    stateRef.current = state;
+    const defsRef = useRef(defs);
+    defsRef.current = defs;
+    const onOpenRef = useRef(options?.onOpen);
+    onOpenRef.current = options?.onOpen;
+    const onCloseRef = useRef(options?.onClose);
+    onCloseRef.current = options?.onClose;
+    const open = useCallback((id) => {
+        const wasOpen = isPanelOpen(stateRef.current, id);
+        setState((s) => openPanel(s, id));
+        if (!wasOpen)
+            onOpenRef.current?.(id);
+    }, []);
+    const close = useCallback((id) => {
+        const wasOpen = isPanelOpen(stateRef.current, id);
+        setState((s) => closePanel(s, id));
+        if (wasOpen)
+            onCloseRef.current?.(id);
+    }, []);
+    const toggle = useCallback((id) => {
+        if (isPanelOpen(stateRef.current, id))
+            close(id);
+        else
+            open(id);
+    }, [open, close]);
+    const focus = useCallback((id) => setState((s) => focusPanel(s, id)), []);
+    const move = useCallback((id, pos) => setState((s) => movePanel(s, id, pos)), []);
+    const byHotkey = useCallback((code) => panelByHotkey(defsRef.current, code), []);
+    const hotkeysEnabled = options?.hotkeys !== false;
+    useEffect(() => {
+        if (!hotkeysEnabled || typeof window === "undefined")
+            return undefined;
+        const onKeyDown = (event) => {
+            if (event.defaultPrevented)
+                return;
+            if (event.key !== "Escape" && isEditableTarget(event.target))
+                return;
+            const result = panelKeyAction(defsRef.current, stateRef.current, {
+                code: event.code,
+                key: event.key,
+            });
+            if (!result.handled)
+                return;
+            event.preventDefault();
+            if (result.type === "closeTop") {
+                const topId = topClosableOpen(stateRef.current);
+                setState((s) => closeTopPanel(s));
+                if (topId !== null)
+                    onCloseRef.current?.(topId);
+            }
+            else if (result.type === "toggle" && result.id !== undefined) {
+                toggle(result.id);
+            }
+        };
+        window.addEventListener("keydown", onKeyDown);
+        return () => window.removeEventListener("keydown", onKeyDown);
+    }, [hotkeysEnabled, toggle]);
+    return {
+        state,
+        defs,
+        isOpen: (id) => isPanelOpen(state, id),
+        open,
+        close,
+        toggle,
+        focus,
+        move,
+        byHotkey,
+    };
+}
+/** @internal The id the next ESC would close, so the caller can fire `onClose` with it. */
+function topClosableOpen(state) {
+    const next = closeTopPanel(state);
+    if (next === state)
+        return null;
+    for (const id of Object.keys(state.open)) {
+        if (next.open[id] !== true)
+            return id;
+    }
+    return null;
+}
+// ---- Window chrome ---------------------------------------------------------
+/** @internal Begin a pointer drag from the title bar, streaming new positions to `onMove` until release. */
+function beginWindowDrag(event, origin, onMove) {
+    if (typeof window === "undefined")
+        return;
+    const startX = event.clientX;
+    const startY = event.clientY;
+    const base = { x: origin.x, y: origin.y };
+    const onPointerMove = (moveEvent) => {
+        onMove({ x: base.x + (moveEvent.clientX - startX), y: base.y + (moveEvent.clientY - startY) });
+    };
+    const onPointerUp = () => {
+        window.removeEventListener("pointermove", onPointerMove);
+        window.removeEventListener("pointerup", onPointerUp);
+        window.removeEventListener("pointercancel", onPointerUp);
+    };
+    window.addEventListener("pointermove", onPointerMove);
+    window.addEventListener("pointerup", onPointerUp);
+    window.addEventListener("pointercancel", onPointerUp);
+}
+const TITLEBAR_STYLE = {
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "space-between",
+    gap: 8,
+    padding: "6px 8px 6px 10px",
+    cursor: "grab",
+    touchAction: "none",
+    userSelect: "none",
+    fontSize: 12,
+    fontWeight: 600,
+    letterSpacing: 0.3,
+    borderBottom: "var(--jg-frame-border, 1px solid rgba(255,255,255,0.10))",
+};
+const CLOSE_BUTTON_STYLE = {
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+    width: 20,
+    height: 20,
+    padding: 0,
+    borderRadius: 6,
+    border: "1px solid transparent",
+    background: "transparent",
+    color: "inherit",
+    font: "inherit",
+    lineHeight: 1,
+    cursor: "pointer",
+    opacity: 0.75,
+};
+/** @internal Shared, fully-controlled window view — title bar (drag + close) plus a HudFrame body. */
+function WindowView({ title, ariaLabel, closable, onClose, onFocus, onMove, pos, z, width, variation, shape, className, style, bodyStyle, children, }) {
+    return (_jsx("div", { role: "dialog", "aria-label": ariaLabel, "data-jg-window": "", className: className, onPointerDown: () => onFocus?.(), style: { position: "absolute", left: pos.x, top: pos.y, zIndex: z, pointerEvents: "auto", ...style }, children: _jsxs(HudFrame, { variation: variation, shape: shape, width: width, padding: 0, interactive: true, children: [_jsxs("div", { "data-jg-window-titlebar": "", onPointerDown: (event) => {
+                        if (event.button !== 0)
+                            return;
+                        onFocus?.();
+                        if (onMove !== undefined)
+                            beginWindowDrag(event, pos, onMove);
+                    }, style: TITLEBAR_STYLE, children: [_jsx("span", { "data-jg-window-title": "", children: title }), closable ? (_jsx("button", { type: "button", "data-jg-window-close": "", "aria-label": "Close", onClick: onClose, onPointerDown: (event) => event.stopPropagation(), style: CLOSE_BUTTON_STYLE, children: "\u2715" })) : null] }), _jsx("div", { "data-jg-window-body": "", style: { padding: 10, ...bodyStyle }, children: children })] }) }));
+}
+/** @internal Fallback cascade position for a window whose state has no override yet. */
+function cascade(index) {
+    return { x: 56 + index * 28, y: 56 + index * 28 };
+}
+/**
+ * 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`.
+ *
+ * The host establishes its own stacking context at `zIndexBase` (default 40) so windows always paint
+ * *above* the HUD (stat bars, nameplates, frames typically sit at z 10–30) — no game should have to
+ * rediscover "my vitals bar bleeds through the open window" and wrap this in a `z-*` of its own. Per-
+ * window focus order still resolves inside that context, so clicking a window raises it over its peers.
+ * Raise `zIndexBase` to sit above a full-screen modal, or lower it to tuck windows beneath one.
+ *
+ * @capability panel-host render a manager's open windows as draggable, closable, z-stacked dialogs above the HUD
+ */
+export function PanelHost({ manager, render, panels, variation, shape, width, zIndexBase = 40, className, windowClassName, windowStyle, bodyStyle, }) {
+    const open = orderedOpen(manager.state, manager.defs);
+    const content = (id) => render !== undefined ? render(id) : (panels?.[id] ?? null);
+    return (_jsx("div", { "data-jg-panel-host": "", className: className, style: { position: "absolute", inset: 0, zIndex: zIndexBase, pointerEvents: "none" }, children: open.map((def, index) => (_jsx(WindowView, { title: def.title ?? def.id, ariaLabel: def.title ?? def.id, closable: def.closable !== false, onClose: () => manager.close(def.id), onFocus: () => manager.focus(def.id), onMove: (pos) => manager.move(def.id, pos), pos: manager.state.pos[def.id] ?? cascade(index), z: manager.state.z[def.id] ?? 1, width: width, variation: variation, shape: shape, className: windowClassName, style: windowStyle, bodyStyle: bodyStyle, children: content(def.id) }, def.id))) }));
+}
+/**
+ * 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 function Window({ title, ariaLabel, closable = true, onClose, x, y, onMove, z, width, variation, shape, className, style, bodyStyle, children, }) {
+    const controlled = x !== undefined && y !== undefined && onMove !== undefined;
+    const [localPos, setLocalPos] = useState({ x: x ?? 56, y: y ?? 56 });
+    const pos = controlled ? { x: x, y: y } : localPos;
+    const handleMove = useCallback((next) => {
+        if (!controlled)
+            setLocalPos(next);
+        onMove?.(next);
+    }, [controlled, onMove]);
+    const label = ariaLabel ?? (typeof title === "string" ? title : undefined);
+    return (_jsx(WindowView, { title: title, ariaLabel: label, closable: closable, onClose: onClose, onMove: handleMove, pos: pos, z: z, width: width, variation: variation, shape: shape, className: className, style: style, bodyStyle: bodyStyle, children: children }));
+}

package/dist/provider.d.ts

@@ -4,6 +4,21 @@ export declare function GameProvider({ context, children }: {
     context: GameContext;
     children?: ReactNode;
 }): import("react").JSX.Element;
+/**
+ * Re-provide a captured {@link GameContext} across a nested React reconciler boundary. The `<Canvas>`
+ * of `@react-three/fiber` renders its children in a *separate* React root, so a `GameProvider` in the
+ * outer tree does NOT reach inside it — hooks like `useGameContext` / `useEntityRenderCues` throw. The
+ * fix the shell already uses internally: capture the context outside the boundary (with
+ * {@link useOptionalGameContext}) and wrap the inner tree in `GameContextBridge`. A `null` context
+ * renders children unchanged, so the same code works in showcases with no running game. This is the
+ * seam behind `EntityPreview` — reach for it directly when building a bespoke nested canvas.
+ *
+ * @capability game-context-bridge re-provide the GameContext across a nested Canvas/reconciler boundary
+ */
+export declare function GameContextBridge({ context, children, }: {
+    context: GameContext | null;
+    children?: ReactNode;
+}): import("react").JSX.Element;
 export declare function useGameContext(): GameContext;
 /** The game context if a `GameProvider` is present, otherwise `null` — for chrome that may render outside a running game (showcases, previews). */
 export declare function useOptionalGameContext(): GameContext | null;

package/dist/provider.js

@@ -1,9 +1,25 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useContext } from "react";
 const GameReactContext = createContext(null);
 export function GameProvider({ context, children }) {
     return _jsx(GameReactContext.Provider, { value: context, children: children });
 }
+/**
+ * Re-provide a captured {@link GameContext} across a nested React reconciler boundary. The `<Canvas>`
+ * of `@react-three/fiber` renders its children in a *separate* React root, so a `GameProvider` in the
+ * outer tree does NOT reach inside it — hooks like `useGameContext` / `useEntityRenderCues` throw. The
+ * fix the shell already uses internally: capture the context outside the boundary (with
+ * {@link useOptionalGameContext}) and wrap the inner tree in `GameContextBridge`. A `null` context
+ * renders children unchanged, so the same code works in showcases with no running game. This is the
+ * seam behind `EntityPreview` — reach for it directly when building a bespoke nested canvas.
+ *
+ * @capability game-context-bridge re-provide the GameContext across a nested Canvas/reconciler boundary
+ */
+export function GameContextBridge({ context, children, }) {
+    if (context === null)
+        return _jsx(_Fragment, { children: children });
+    return _jsx(GameReactContext.Provider, { value: context, children: children });
+}
 export function useGameContext() {
     const ctx = useContext(GameReactContext);
     if (ctx === null)

package/dist/slots.d.ts

@@ -3,10 +3,13 @@ import { type IconSchool } from "./iconTreatment.js";
 import type { GameIconName } from "./gameIcons.js";
 /**
  * Atomic, purpose-named slot grids (#1033): one component per category — `EquipmentSlots`,
- * `WeaponSlots`, `ArmorSlots`, `PotionSlots` — never a mega inventory that bundles every category.
- * Each renders a grid of painted {@link IconTreatment} tiles (glyph + gradient + count badge) for
- * filled slots and a themed placeholder for empty ones, all reading the shared `--jg-slot-*` /
- * `--jg-accent` HudTheme tokens (#1034). Composition stays the game's; the engine ships the grid.
+ * `WeaponSlots`, `ArmorSlots`, `PotionSlots` — for paperdoll / equip layouts where each grid holds a
+ * single gear category. A full multi-category backpack that binds to a live inventory with
+ * drag/swap/stack/split is a different, supported shape: reach for `<InventoryGrid>` (`inventoryGrid.tsx`)
+ * there, and use these atomic grids for the equip slots around it. Each renders a grid of painted
+ * {@link IconTreatment} tiles (glyph + gradient + count badge) for filled slots and a themed placeholder
+ * for empty ones, all reading the shared `--jg-slot-*` / `--jg-accent` HudTheme tokens (#1034).
+ * Composition stays the game's; the engine ships the grid.
  *
  * @capability hud-slots atomic themed equipment/weapon/armor/potion slot grids with painted icons
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/react",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "React UI layer for JGengine: GameProvider, hooks, and headless primitives over @jgengine/core.",
   "license": "Apache-2.0",
   "type": "module",
@@ -31,7 +31,7 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.12.0"
+    "@jgengine/core": "^0.14.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/skills/jgengine/SKILL.md

@@ -5,7 +5,7 @@ description: Route game work to the smallest useful JGengine guidance set.
 
 # JGengine intake and router
 
-Read the repository [README](../../../README.md) for package truth, commands, layering, and license. This skill decides what to load; it is not an engine manual.
+Read the JGengine README for package truth, commands, layering, and license — the repo-root [`README.md`](../../../README.md) in the monorepo, or [jgengine.com](https://jgengine.com) from a scaffolded consumer project (where the relative link does not resolve). This skill decides what to load; it is not an engine manual.
 
 ## 1. Establish the target
 
@@ -20,6 +20,8 @@ Treat the pitch as a unique composition of needs, not a genre to fill in — nev
 
 For a new in-repo game, scaffold with `bun run new:game "<id-or-title>"` (thin script alias for `jgengine create`, auto-detects the in-repo variant). Outside this monorepo, start with `npx jgengine create`; never copy `Games/*`.
 
+For an existing game asked to pick up a new engine release ("jgengine published a new version, grab it"), run `npx jgengine upgrade` in the project first: it diffs installed `@jgengine/*` versions against the latest release and prints every Migrate step and Adopt-worthy addition in between (`--json` for structured output). Bump, migrate oldest-first, then work the Adopt lists instead of reconstructing the changelog by hand.
+
 ## 2. Select domains
 
 Load only rows the target needs. Do not preload every domain.
@@ -42,7 +44,8 @@ World content routes editor-first: any request that adds, moves, restyles, or re
 
 Within each selected domain:
 
-1. Search `capabilities.md` by intent; it maps needs to imports.
+0. Fastest start for a common composition: `npx jgengine recipe <name>` prints a vetted, SDK-typechecked snippet (imports + wired code) for `combat-loop`, `boss-telegraph`, `loot`, `quest`, `coop-presence`, `third-person-camera`; `npx jgengine recipe` lists them. Copy that instead of reconning per-file.
+1. Search `capabilities.md` by intent; it maps needs to imports. Outside the monorepo (or before a domain skill is even loaded), `npx jgengine find <intent>` greps every shipped capability index at once and prints the primitive + import — reach for it the moment you're tempted to hand-roll a HUD window, inventory grid, paperdoll, hotkey listener, minimap, stat bar, or character motion. If you're writing a `z-index`, a `keydown` for a panel, a `<div>` inventory, or a limb bob, a shipped drop-in almost certainly exists (`usePanels`/`PanelHost`, `InventoryGrid`, `CharacterSheet`/`Paperdoll`, `PartMotionRig`, `EntityPreview`); games own the *skin*, not the re-derivation.
 2. Open `api.md` only when exact signatures or export inventory are needed.
 3. Open the linked reference only for a deeper recipe or trap.
 4. For how several primitives wire into a running loop, read the domain's `recipes/` — connected, genre-free walkthroughs organized by composition seam; this skill's own [recipes/minimal-game.md](recipes/minimal-game.md) is the default whole-game walkthrough. Prefer a recipe over reading a game's source; the games under `Games/*` are not templates or references, and a hybrid game is just a different composition of the same primitives.