@jgengine/react 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -10,7 +10,53 @@ 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
 

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

@@ -61,9 +61,15 @@ export declare function usePanels(defs: readonly PanelDef[], options?: UsePanels
  * 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
+ * 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, className, windowClassName, windowStyle, bodyStyle, }: {
+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;
@@ -73,6 +79,8 @@ export declare function PanelHost({ manager, render, panels, variation, shape, w
     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;

package/dist/panels.js

@@ -186,12 +186,18 @@ function cascade(index) {
  * 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
+ * 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, className, windowClassName, windowStyle, bodyStyle, }) {
+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, 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))) }));
+    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 —

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/react",
-  "version": "0.13.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.13.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.
@@ -43,7 +45,7 @@ World content routes editor-first: any request that adds, moves, restyles, or re
 Within each selected domain:
 
 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.
+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.

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.13.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.14.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -220,7 +220,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.13.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.14.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine-ui/SKILL.md

@@ -16,7 +16,7 @@ Search [capabilities.md](capabilities.md), use [api.md](api.md) for signatures,
 1. Write the game's UI art direction first (see [reference.md](reference.md) §1) — fantasy, shape/material language, hierarchy, forbidden patterns. Stock glass widgets are not a stand-in for this step.
 2. Define the real UI states: attract, main menu (the game's front-end), character create/select where relevant, live play, pause, settings, credits, results, empty/error, and relevant overlays.
 3. Read state through selectors/hooks; keep simulation mutation behind commands.
-4. Compose this game's UI, reaching first for the shipped building blocks — `InventoryGrid`, `usePanels`/`PanelHost`/`Window`, `CharacterSheet`/`Paperdoll`, and the action/selection bars — and composing + reskinning them; only hand-roll custom markup where no building block fits. Toggleable windows (bag `B`, character `C`, etc.) come from `usePanels`, not hand-rolled open/close state. Prefer headless data + game-owned chrome. When a second presentation is plausible, split data / renderer / chrome (minimap stack example: `useLiveMarkers` → track/renderer → game frame; see reference §6).
+4. Compose this game's UI, reaching first for the shipped building blocks — `InventoryGrid`, `usePanels`/`PanelHost`/`Window`, `CharacterSheet`/`Paperdoll`, and the action/selection bars — and composing + reskinning them; only hand-roll custom markup where no building block fits. Toggleable windows (bag `B`, character `C`, etc.) come from `usePanels`, not hand-rolled open/close state — and `PanelHost` already stacks windows above the HUD (`zIndexBase`) and wires hotkeys/ESC, so never hand-roll a `z-*` or keydown listener for them. A live 3D character-screen portrait is `EntityPreview` (`@jgengine/shell/render/EntityPreview`): it owns the nested `<Canvas>`, the `GameContextBridge` across the R3F boundary, and the `StudioStage` lighting — pass the game's own `renderEntity` as children (or a native `model`+`instanceId`) and it mirrors the live entity; don't re-derive the context bridge by hand. Prefer headless data + game-owned chrome. When a second presentation is plausible, split data / renderer / chrome (minimap stack example: `useLiveMarkers` → track/renderer → game frame; see reference §6).
 5. Make keyboard, pointer, touch, controller, focus, and screen-reader behavior explicit.
 6. Add preview fixtures using the real components for fast deterministic capture.
 7. Verify desktop and mobile layouts through `jgengine-verify`. A HUD that could pass for another game's default chrome fails visual review.
@@ -31,6 +31,8 @@ Existing React games keep their entity store and use the focused
 - **The main menu is a game front-end, not marketing.** The runner loads straight into the game's own menu; it offers the real front-end verbs the game supports — New Game, Continue/Load (save slots), Create/Choose character or class, Settings, Credits — each an authored screen in the game's art direction, not a landing page or raw scaffold. See [reference.md](reference.md) §"Main menu".
 - **Settings is game-owned and reachable from a sensible place.** Every game ships settings as *its* settings — skinned and placed inline with its UI (main menu and pause), never the engine's stock face floated into a corner. Credits are a reachable in-game screen, not attribution buried in a build artifact.
 - Engine packages ship both headless seams *and* good drop-in building blocks. The seams are layout (`HudCanvas`/`HudPanel`), data hooks, interaction models, and tokens; the building blocks are the parts almost every game needs — inventory grids (`InventoryGrid`), toggleable windows (`usePanels`/`PanelHost`/`Window`), character sheets (`CharacterSheet`/`Paperdoll`), stat/vitals bars, and action/selection bars. Composing and reskinning these is using the engine correctly, not out of policy. What stays out of scope is a whole finished game *face* or a genre theme preset shipped as the product (see [AGENTS.md](../../../AGENTS.md)).
+- **Skin the shared chrome with one `HudTheme` token object.** `hudThemeVars(theme)` emits the `--jg-*` custom properties that the atomic bars, `HudFrame variation="themed"`, painted slots, and the minimap ring all read, so one theme spread on any HUD ancestor reskins the whole subtree — palette, frame material, corner radius, glow, and slot chrome. Author your own theme (tower-guard's `fieldkitVars` is the model); `HUD_THEME_PRESETS` / `resolveHudTheme("<preset>")` are demo/scaffold starting points, never a game's identity. Caller `style`/`renderItem` overrides still win over the theme default.
+- **Paint slot icons with `IconTreatment`, never render raw `itemId` strings.** It draws a `GameIcon` glyph (or any node) over a school/element-keyed radial gradient with a gloss + vignette and optional count/keycap badges, and reads the `--jg-slot-*` / `--jg-accent` `HudTheme` tokens so a theme change reskins every treated icon. `schoolForItem`/`schoolForAction` infer the gradient from an id; `treatedItemIcon(itemId)` / `treatedActionIcon(action)` are ready adapters. Use it in hotbars and ability bars so slots read as painted icons, not debug text.
 - Never reach for a genre HUD kit, theme preset, or "default RPG/FPS chrome" as the game's *identity*. Composing the shared building blocks (bag, character, spellbook, action-bar windows) is fine and expected — it's a prefab genre *look/identity* dropped in unchanged that's discouraged. Build the look this pitch needs on top of them.
 - Layout and skin remain caller-controlled; shared primitives own reusable behavior, not product look.
 - SSR-visible output is hydration-stable; round computed SVG values at the boundary.
@@ -41,3 +43,4 @@ Existing React games keep their entity store and use the focused
 - Do not duplicate inventory, combat, quest, or selection state inside components.
 - A static facsimile preview does not test the real UI; compose production components with fixtures.
 - Visual quality is judged from rendered evidence, not component counts or prose.
+- Shown HUD UI must fit the player viewport. `HudCanvas` runs a live boundary check on every registered `HudPanel`, any element tagged `data-hud-window`, and its own direct children: if a *visible* surface crosses a viewport edge it draws a red dev overlay on the offender, `console.warn`s, and sets `data-hud-overflow` (which fails the `bun run shoot` gate). A closed/parked/hidden surface (off-screen drawer, unopened menu, `visibility:hidden`, `aria-hidden`) never trips it — only surfaces partly on screen and partly past an edge. Deliberate bleed opts out with `data-hud-allow-overflow`. Mount custom windows inside `HudCanvas` (tag deeper ones `data-hud-window`) so the check can see them.

package/skills/jgengine-ui/api.md

@@ -172,7 +172,7 @@
 - `orderedOpen` (function): function orderedOpen(state: PanelState, defs: readonly PanelDef[]): PanelDef[] — The open panels' defs sorted ascending by z — the render order for a window host (map to elements so the last, highest-z window paints on top). Defs unknown to the state are skipped.
 - `orientationGateActive` (function): function orientationGateActive(requirement: OrientationRequirement, liveOrientation: LayoutOrientation): boolean — The rotate gate blocks gameplay: a hard requirement (or `unsupported`) the live orientation doesn't satisfy.
 - `orientationHintActive` (function): function orientationHintActive(requirement: OrientationRequirement, liveOrientation: LayoutOrientation): boolean — An advisory rotate hint applies: a preference (not a hard gate) the live orientation doesn't satisfy.
-- `overflowingPanels` (function): function overflowingPanels(panels: readonly { id: string; rect: HudRect }[], viewport: HudSize, tolerance = 1.5): HudOverflow[] — Every panel rect that escapes the viewport — the data behind the HUD overflow gate.
+- `overflowingPanels` (function): function overflowingPanels(panels: readonly { id: string; rect: HudRect }[], viewport: HudSize, tolerance = 1.5): HudOverflow[] — Every panel rect that escapes the viewport — the data behind the HUD overflow gate. A rect is only reported when it is partly visible *and* crosses an edge; a fully off-screen (closed/hidden) surface is skipped, so parked drawers and unopened menus never raise a false alarm.
 - `panelByHotkey` (function): function panelByHotkey(defs: readonly PanelDef[], code: string): string | null — Find the panel whose `hotkey` matches `code`, case-insensitively — the keybind router. `code` may be a `KeyboardEvent.code` (`"KeyB"`) or key (`"b"`); it is compared verbatim to each def's `hotkey`, so author the hotkey in whichever form the caller feeds in. Returns the first match's id, or null.
 - `placePopover` (function): function placePopover(anchor: UiRect, content: UiSize, viewport: UiSize, options?: PopoverOptions): PopoverPlacement — Position a popover/tooltip of `content` size against its `anchor` rectangle inside `viewport`: open on the `preferred` side, flip to the opposite when that side lacks room and the opposite has more, then clamp the top-left so the box stays fully on screen (respecting `margin`). Pure and deterministic — no DOM reads — so it is SSR-safe and unit-testable, and the React tooltip is a thin shell over it.
 - `registerHudPanelType` (function): function registerHudPanelType(def: HudPanelTypeDef): void — Register a HUD panel type so the editor can list/add/configure it and canvas resize knows axes.
@@ -256,7 +256,7 @@
 - `HudPlatform` (type): type HudPlatform = "web" | "mobile" — Where a game is meant to be played. `"web"` alone keeps today's desktop-first HUD; adding `"mobile"` turns on design-resolution fit scaling on compact displays.
 - `HudViewportConfig` (interface): interface HudViewportConfig extends HudFitConfig — Per-game HUD viewport declaration carried on `PlayableGame.hudFit`; `mobile` overrides the fit on compact displays so the owner can tune the phone layout separately.
 - `hudScaleForViewport` (function): function hudScaleForViewport(fit: Required<HudFitConfig>, viewport: HudSize): number — The one scaling rule for every display: the ratio of the live viewport to the authored design size along the limiting axis, clamped. 1 on a viewport at or above design size; smoothly below 1 down to `minScale` on phones.
-- `overflowingPanels` (function): function overflowingPanels(panels: readonly { id: string; rect: HudRect }[], viewport: HudSize, tolerance = 1.5): HudOverflow[] — Every panel rect that escapes the viewport — the data behind the HUD overflow gate.
+- `overflowingPanels` (function): function overflowingPanels(panels: readonly { id: string; rect: HudRect }[], viewport: HudSize, tolerance = 1.5): HudOverflow[] — Every panel rect that escapes the viewport — the data behind the HUD overflow gate. A rect is only reported when it is partly visible *and* crosses an edge; a fully off-screen (closed/hidden) surface is skipped, so parked drawers and unopened menus never raise a false alarm.
 - `rectOverflow` (function): function rectOverflow(rect: HudRect, viewport: HudSize, tolerance = 1.5): Omit<HudOverflow, "id"> | null — Non-null when any edge of `rect` falls outside `viewport` by more than `tolerance` px; each field is the overflow distance past that edge (0 when inside).
 - `resolveHudFit` (function): function resolveHudFit(config: HudViewportConfig | undefined, mobile: boolean): Required<HudFitConfig> — ⚠ undocumented
 
@@ -392,6 +392,7 @@
 - `FriendRequestsList` (function): function FriendRequestsList({ className, rowClassName, acceptClassName, declineClassName, emptyState, renderRequest, }: { className?: string; rowClassName?: string; acceptClassName?: string; declineClassName?: string; emptyState?: ReactNode; renderRequest?: (request: FriendRequestEntry) => ReactNode… — ⚠ undocumented
 - `FriendRow` (function): function FriendRow({ friend, className, dotClassName, children, }: { friend: FriendEntry; className?: string; dotClassName?: string; children?: ReactNode; }): React.JSX.Element — ⚠ undocumented
 - `FriendsList` (function): function FriendsList({ className, rowClassName, dotClassName, emptyState, renderFriend, }: { className?: string; rowClassName?: string; dotClassName?: string; emptyState?: ReactNode; renderFriend?: (friend: FriendEntry) => ReactNode; }): React.JSX.Element — ⚠ undocumented
+- `GameContextBridge` (function): function GameContextBridge({ context, children, }: { context: GameContext | null; children?: ReactNode; }): 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.
 - `GameIdentityProvider` (function): function GameIdentityProvider({ source, children, }: { source: IdentitySource; children?: ReactNode; }): React.JSX.Element — ⚠ undocumented
 - `GamePreviewComponent` (type): type GamePreviewComponent = ComponentType<GamePreviewProps> — ⚠ undocumented
 - `GamePreviewProps` (type): type GamePreviewProps = { className?: string; } — ⚠ undocumented
@@ -450,7 +451,7 @@
 - `MinimapTrackPip` (interface): interface MinimapTrackPip — A point marker on the {@link MinimapTrack} rail at a 0..1 fraction (e.g. a gate, the exit, or the player).
 - `MinimapTrackProps` (interface): interface MinimapTrackProps — Props for {@link MinimapTrack}.
 - `MinimapTrackSpan` (interface): interface MinimapTrackSpan — A colored span across the {@link MinimapTrack} rail, given by 0..1 `start`/`end` fractions (e.g. from core `trackFraction`).
-- `PanelHost` (function): 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 … — 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`.
+- `PanelHost` (function): function PanelHost({ manager, render, panels, variation, shape, width, zIndexBase = 40, className, windowClassName, windowStyle, bodyStyle, }: { manager: PanelsManager; /** Content for a panel by id. Takes precedence over `panels`. */ render?: (id: string) => ReactNode; /** Static content map by pan… — 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`.
 - `PanelKeyResult` (interface): interface PanelKeyResult — 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.
 - `PanelsManager` (interface): interface PanelsManager — The live panel manager returned by {@link usePanels} and consumed by {@link PanelHost}.
 - `Paperdoll` (function): function Paperdoll({ slots, portrait, slotSize = 44, onSlotActivate, className, style }: PaperdollProps): ReactNode — 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.
@@ -949,7 +950,7 @@
 
 ## @jgengine/react/panels
 
-- `PanelHost` (function): 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 … — 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`.
+- `PanelHost` (function): function PanelHost({ manager, render, panels, variation, shape, width, zIndexBase = 40, className, windowClassName, windowStyle, bodyStyle, }: { manager: PanelsManager; /** Content for a panel by id. Takes precedence over `panels`. */ render?: (id: string) => ReactNode; /** Static content map by pan… — 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`.
 - `PanelKeyResult` (interface): interface PanelKeyResult — 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.
 - `PanelsManager` (interface): interface PanelsManager — The live panel manager returned by {@link usePanels} and consumed by {@link PanelHost}.
 - `UsePanelsOptions` (interface): interface UsePanelsOptions — Options for {@link usePanels}.
@@ -965,6 +966,7 @@
 
 ## @jgengine/react/provider
 
+- `GameContextBridge` (function): function GameContextBridge({ context, children, }: { context: GameContext | null; children?: ReactNode; }): 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.
 - `GameProvider` (function): function GameProvider({ context, children }: { context: GameContext; children?: ReactNode }): React.JSX.Element — ⚠ undocumented
 - `useGameContext` (function): function useGameContext(): GameContext — ⚠ undocumented
 - `useOptionalGameContext` (function): function useOptionalGameContext(): GameContext | null — The game context if a `GameProvider` is present, otherwise `null` — for chrome that may render outside a running game (showcases, previews).
@@ -1494,6 +1496,13 @@
 
 - `createGradePass` (function): function createGradePass(config: GradeConfig = {}): ShaderPass — Build the display-space colour-grade pass (lift/gain/gamma, saturation, vignette, grain). Advance `uniforms.uTime.value` each frame to animate the grain.
 
+## @jgengine/shell/postfx/postfxOverlay
+
+- `POSTFX_OVERLAY_USERDATA` (const): const POSTFX_OVERLAY_USERDATA: { readonly jgPostfxOverlay: true } — Spread onto a group's `userData` to mark its subtree as a screen/world overlay effect — additive glows, telegraphs, tracers, debug gizmos — that post-processing scene prepasses (GTAO's normal/depth render, DOF's depth render) must skip. Those prepasses render the scene with `overrideMaterial`, which turns transparent overlay quads into opaque stamps in the AO/DOF buffers (visible as black squares over hit sparks). The shell marks its own combat VFX and collision-debug mounts; games mark custom overlay effects the same way.
+- `hidePostfxOverlays` (function): function hidePostfxOverlays(scene: THREE.Object3D, out: THREE.Object3D[]): void — Hide every currently visible marked object under `scene`, recording what was hidden into `out` (cleared first, no allocation on the hot path) so {@link restorePostfxOverlays} can undo exactly that set.
+- `isPostfxOverlay` (function): function isPostfxOverlay(object: { userData?: Record<string, unknown> }): boolean — True when the object opted out of postfx scene prepasses via {@link POSTFX_OVERLAY_USERDATA}.
+- `restorePostfxOverlays` (function): function restorePostfxOverlays(hidden: THREE.Object3D[]): void — Restore visibility for the objects hidden by {@link hidePostfxOverlays} and clear the list.
+
 ## @jgengine/shell/registry
 
 - `GameRegistry` (type): type GameRegistry = Record<string, () => Promise<PlayableGame>> — ⚠ undocumented
@@ -1502,6 +1511,11 @@
 - `RenderObject` (type): type RenderObject = (object: SceneObject) => ReactNode — ⚠ undocumented
 - `resolveGameLoader` (function): function resolveGameLoader(registry: GameRegistry, gameId: string, fallbackGameId?: string): (() => Promise<PlayableGame>) | undefined — ⚠ undocumented
 
+## @jgengine/shell/render/EntityPreview
+
+- `EntityPreview` (function): function EntityPreview({ children, model, instanceId, mood = "studio", backdrop, turntable = 0, faceCamera = false, forward, environment = true, cameraPosition = [0, 1, 3], fov = 35, dpr = [1, 2], className, style, }: EntityPreviewProps): React.JSX.Element — Drop-in live 3D preview of a single entity — the character-screen portrait, unit inspector, or loadout viewer. It owns all the plumbing a game would otherwise re-derive by hand: a nested `<Canvas>`, the {@link GameContextBridge} that carries the running `GameContext` across the R3F reconciler boundary (so the subject's `useEntityRenderCues` / `useGameContext` hooks resolve and it mirrors the live game), a {@link StudioStage} 3-point lighting rig with optional turntable / face-camera, and a capture-friendly GL surface. The game keeps ownership of its `renderEntity`: pass it as `children`, or hand a native `model` (+ `instanceId`) for an engine-composed body. Bound to a live `instanceId`, the portrait walks, flinches, and topples in lockstep with the world instead of a canned spin.
+- `EntityPreviewProps` (interface): interface EntityPreviewProps — Props for {@link EntityPreview}.
+
 ## @jgengine/shell/render/PartMotion
 
 - `PartMotionRig` (function): function PartMotionRig({ parts, model, instanceId, renderPart, children, }: { parts: readonly ModelPart[]; model: ModelConfig; instanceId?: string; /** Renders one part's model content (the shell passes its part renderer to avoid an import cycle). */ renderPart: (part: ModelPart, index: number) => R… — Procedural motion rig for a rig-less part-composed character (`ModelPart.role` — see `@jgengine/core/game/partAnimation`). Wraps the whole composition in a root group that bobs, breathes, flinches on `combat.hitReaction`, and topples on `entity.died`, while each role-tagged part swings around its authored transform — legs/arms counter-phase from the entity's live movement speed, head counter-sway, tail wag, wing flap. Untagged parts render as static kit pieces. Children are the base model content (primitive, attachments).
@@ -1531,6 +1545,12 @@
 - `measureLocalBounds` (function): function measureLocalBounds(root: THREE.Object3D): MeasuredLocalBounds | null — Measure the meshes under `root` in `root`'s own frame (root's transform is the measuring frame, children compose their local matrices below it). Returns `null` when nothing measurable is mounted. Skinned meshes measure at bind pose — the standard engine approximation.
 - `reportMeasuredBounds` (function): function reportMeasuredBounds(ctx: GameContext, target: "entity" | "object", key: string, bounds: MeasuredLocalBounds): void — Forward a measured result into the context (entity kind or object catalog id), deduping repeat reports of the same shape so remounts and multi-instance kinds don't churn collider resolution.
 
+## @jgengine/shell/render/measureCollisionMesh
+
+- `MeasuredCollisionTriangles` (interface): interface MeasuredCollisionTriangles extends CollisionMeshSource — Entity-local triangle soup of the meshes under a measured root, plus the contributing mesh count (same async fill-in detection as measured bounds). Satisfies {@link CollisionMeshSource}.
+- `measureLocalCollisionTriangles` (function): function measureLocalCollisionTriangles(root: THREE.Object3D, transform?: { scale: number; offset: readonly [number, number, number] }): MeasuredCollisionTriangles | null — Collect the triangle soup of the meshes under `root` in `root`'s own frame — the mesh-accurate counterpart to `measureLocalBounds`, with the same visibility/sprite/{@link MEASURE_EXCLUDE_KEY} exclusions (skinned meshes contribute their bind pose). An optional uniform `scale` + `offset` maps the result into entity-local space when the caller mounts the root scaled/translated (the model-primitive path). Returns `null` when nothing is measurable or the soup exceeds the triangle budget — callers keep their box fallback.
+- `reportMeasuredCollisionMesh` (function): function reportMeasuredCollisionMesh(ctx: GameContext, target: "entity" | "object", key: string, triangles: MeasuredCollisionTriangles): void — Forward measured triangles into the context (entity kind or object catalog id), deduping repeat reports of the same soup so remounts and multi-instance kinds don't rebuild the BVH.
+
 ## @jgengine/shell/render/modelRender
 
 - `MaterialCache` (interface): interface MaterialCache — ⚠ undocumented

package/skills/jgengine-ui/capabilities.md

@@ -65,6 +65,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `EntityPortrait` (function) · `import { EntityPortrait } from "@jgengine/react"`
 
+## entity-preview — live 3D entity portrait — nested Canvas + context bridge + studio stage, driven by the game's own renderEntity
+
+- `EntityPreview` (function) · `import { EntityPreview } from "@jgengine/shell/render/EntityPreview"`
+
 ## entity-render-cues — live velocity/bob/fire/reload/hit/death cues for a custom renderEntity or viewmodel component
 
 - `useEntityRenderCues` (function) · `import { useEntityRenderCues } from "@jgengine/shell/render/useEntityRenderCues"`
@@ -77,6 +81,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `useEventMeter` (function) · `import { useEventMeter } from "@jgengine/react"`
 
+## game-context-bridge — re-provide the GameContext across a nested Canvas/reconciler boundary
+
+- `GameContextBridge` (function) · `import { GameContextBridge } from "@jgengine/react"`
+
 ## heightfield-mesh-update — in-place partial update of a displaced ground plane mesh
 
 - `displaceHeightfieldGeometry` (function) · `import { displaceHeightfieldGeometry } from "@jgengine/shell/terrain"`
@@ -186,7 +194,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `focusPanel` (function) · `import { focusPanel } from "@jgengine/core/ui"`
 
-## panel-host — render a manager's open windows as draggable, closable, z-stacked dialogs
+## panel-host — render a manager's open windows as draggable, closable, z-stacked dialogs above the HUD
 
 - `PanelHost` (function) · `import { PanelHost } from "@jgengine/react"`