@jgengine/react 0.12.0 → 0.13.0

package/dist/panels.js

@@ -0,0 +1,215 @@
+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`.
+ *
+ * @capability panel-host render a manager's open windows as draggable, closable, z-stacked dialogs
+ */
+export function PanelHost({ manager, render, panels, variation, shape, width, 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))) }));
+}
+/**
+ * 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/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.13.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.13.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/skills/jgengine/SKILL.md

@@ -42,6 +42,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.
 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.

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.12.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.13.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -38,7 +38,7 @@
 - `WorldFeature` (type): type WorldFeature = | PlaceWorldFeature | ({ kind: "biomes" } & BiomesWorldConfig) | ({ kind: "voxel" } & VoxelWorldConfig) | ({ kind: "plots" } & PlotsWorldConfig) | ({ kind: "tilemap" } & TilemapWorldConfig) | EnvironmentWorldFeature | { kind: "flat" } — A declared world shape passed to `defineGame`. The preferred model is the place feature from `world()` (`@jgengine/core/world/place`): substrate + laws, with all dressing authored in the editor. The remaining members — biomes, voxel grid, plots, tilemap, environment, flat — are the legacy code-declared shapes kept for existing games.
 - `auditManifest` (function): function auditManifest(manifest: SceneOwnershipManifest): OwnershipDiagnostic[] — Audit every declaration in a manifest, keying diagnostics by each object's provenance id. An empty result means the manifest declares all of its content cleanly — every object is authored, generated, bakeable, or a reasoned runtime/transient object.
 - `biomes` (function): function biomes(config: BiomesWorldConfig): WorldFeature — Declares a biome-painted world — the whole-world alternative to a single `environment()` terrain.
-- `building` (function): function building(config: BuildingEnvironmentConfig = {}): BuildingEnvironmentDescriptor — Declares a cluster of procedurally-massed buildings for `environment()` — count, footprint, stories, style.
+- `building` (function): function building(config: BuildingEnvironmentConfig = {}): BuildingEnvironmentDescriptor — Declares a cluster of procedurally-massed buildings for `environment()` — count, footprint, stories, style. Pass `along` to line road frontage instead of gridding around `position`.
 - `classifyOwnership` (function): function classifyOwnership(declaration: SceneOwnershipDeclaration): OwnershipVerdict — Resolve one declaration into a single boundary verdict.
 - `collectOwnershipDiagnostics` (function): function collectOwnershipDiagnostics(entries: Iterable<readonly [string, SceneOwnershipDeclaration]>): OwnershipDiagnostic[] — Audit a keyed set of declarations and return one diagnostic per object that breaks the boundary contract (a `reject` verdict carrying a `violation`). Deterministic: diagnostics come back in the iteration order of `entries`.
 - `contextVerb` (function): function contextVerb(label: string, command: string, args?: Record<string, unknown>): ContextVerb — Builds a {@link ContextVerb} for a right-click menu entry.
@@ -209,11 +209,18 @@
 - `Tunable` (interface): interface Tunable<T> — Typed handle to a registered control, exposing its live value and subscribe/set/reset operations.
 - `TunableAccessor` (interface): interface TunableAccessor — Get/set accessor pair plus initial value used to bind a discovered field to a control.
 
+## @jgengine/core/devtools/urlFlags
+
+- `readUrlFlag` (function): function readUrlFlag(param: string): boolean — True when `param` is present and not an explicit off value (`0`/`false`/`off`/`no`).
+- `readUrlParam` (function): function readUrlParam(param: string): string | null — The current query value of `param`, or null when absent (or no DOM).
+- `subscribeUrlChange` (function): function subscribeUrlChange(listener: () => void): () => void — Fires `listener` whenever the query string may have changed out from under a flag — browser back/forward (`popstate`). Manual address-bar edits reload the page, so initial reads cover those; this keeps in-app state honest across history navigation. Returns an unsubscribe.
+- `writeUrlParam` (function): function writeUrlParam(param: string, value: string | null): void — Sets `param` to `value`, or removes it when `value` is null, rewriting the URL in place with `history.replaceState` so the rest of the query and the hash survive and no history entry is pushed. No-ops without a DOM, and skips the write when the URL already matches.
+
 ## @jgengine/core/meta/changelog
 
 - `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.12.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.13.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 
@@ -276,7 +283,7 @@
 - `SceneObjectContext` (interface): interface SceneObjectContext extends ObjectStore — ⚠ undocumented
 - `SceneWorldItemContext` (interface): interface SceneWorldItemContext — ⚠ undocumented
 - `TelegraphInput` (interface): interface TelegraphInput — ⚠ undocumented
-- `VfxInput` (interface): interface VfxInput — Request a transient spell/ability VFX burst; `from`/`to` accept an instance id or a world point, `color` is a `0xRRGGBB` tint, and `durationMs` defaults per `kind`.
+- `VfxInput` (interface): interface VfxInput — Request a transient spell/ability VFX burst. The easy path is a named `preset` — `vfx({ preset: "arrow", from: caster, to: enemy })` renders a visible bolt with no color or archetype tuning; `"lightning"`, `"web"`, `"slash"`, `"shield"`, `"heal"`, `"explosion"` and the rest of {@link vfxPresets} likewise just work. `from`/`to` accept an instance id (the shell follows its live pose) or a fixed world point. Anything you also pass — `kind`, `color` (`0xRRGGBB`), `radius`, `durationMs` — overrides the preset; supply `kind` + `color` yourself for a fully custom burst with no preset. `durationMs` defaults per `kind`.
 - `WorldItemPickupResult` (type): type WorldItemPickupResult = | { status: "ok"; record: WorldItemRecord } | { status: "rejected"; reason: string } — ⚠ undocumented
 - `createGameContext` (function): function createGameContext<TAssetRef extends ModelAssetRef, TMultiplayer>(options: GameContextOptions<TAssetRef, TMultiplayer>): GameContext — ⚠ undocumented
 
@@ -307,7 +314,7 @@
 - `SceneObjectContext` (interface): interface SceneObjectContext extends ObjectStore — ⚠ undocumented
 - `SceneWorldItemContext` (interface): interface SceneWorldItemContext — ⚠ undocumented
 - `TelegraphInput` (interface): interface TelegraphInput — ⚠ undocumented
-- `VfxInput` (interface): interface VfxInput — Request a transient spell/ability VFX burst; `from`/`to` accept an instance id or a world point, `color` is a `0xRRGGBB` tint, and `durationMs` defaults per `kind`.
+- `VfxInput` (interface): interface VfxInput — Request a transient spell/ability VFX burst. The easy path is a named `preset` — `vfx({ preset: "arrow", from: caster, to: enemy })` renders a visible bolt with no color or archetype tuning; `"lightning"`, `"web"`, `"slash"`, `"shield"`, `"heal"`, `"explosion"` and the rest of {@link vfxPresets} likewise just work. `from`/`to` accept an instance id (the shell follows its live pose) or a fixed world point. Anything you also pass — `kind`, `color` (`0xRRGGBB`), `radius`, `durationMs` — overrides the preset; supply `kind` + `color` yourself for a fully custom burst with no preset. `durationMs` defaults per `kind`.
 - `WorldItemPickupResult` (type): type WorldItemPickupResult = | { status: "ok"; record: WorldItemRecord } | { status: "rejected"; reason: string } — ⚠ undocumented
 
 ## @jgengine/core/runtime/gameRuntime
@@ -322,6 +329,7 @@
 
 ## @jgengine/core/runtime/headlessRunner
 
+- `HeadlessCommandInterface` (interface): interface HeadlessCommandInterface — Canvas-free command/intent surface for {@link HeadlessRunner} — invoke a game's registered UI commands and read the resulting reactive state off `ctx`.
 - `HeadlessInput` (interface): interface HeadlessInput — One step's worth of player intent handed to {@link HeadlessRunner.step} — the held-action set and pointer state the shell would otherwise publish from the browser each frame.
 - `HeadlessRunner` (interface): interface HeadlessRunner — A renderer-free driver for a game loop: builds a {@link GameContext} from a {@link GameDefinition}, runs the init hooks, then advances the simulation one step at a time from injected input. No React, R3F, or three.js — the whole play path (time, input, `onTick`, behaviour nav, optional player movement) runs from `core` primitives alone, so a non-React host (a server tick, a test, a CLI replay) can play a real game and read its world snapshot. The shell's FrameDriver is one such driver bolted to `useFrame`; this is the same step distilled out of the render tree.
 - `HeadlessRunnerOptions` (interface): interface HeadlessRunnerOptions<TAssetRef extends ModelAssetRef, TMultiplayer> — ⚠ undocumented

package/skills/jgengine-ui/SKILL.md

@@ -14,9 +14,9 @@ Search [capabilities.md](capabilities.md), use [api.md](api.md) for signatures,
 ## Canonical workflow
 
 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/menu, live play, pause, results, empty/error, and relevant overlays.
+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 custom markup for this game. 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. 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.
@@ -28,8 +28,10 @@ Existing React games keep their entity store and use the focused
 ## Product rules
 
 - **Every game owns its UI end-to-end.** Custom composition, skin, placement, terminology, motion, and one main menu. The website/runner is a bare loader.
-- Engine packages do not supply a finished game face. Shared UI is headless or unskinned building blocks: layout (`HudCanvas`/`HudPanel`), data hooks, interaction models, tokens. Optional styled widgets exist for previews and scaffolding only — shipping them unskinned as the product is out of policy (see [AGENTS.md](../../../AGENTS.md)).
-- Never reach for genre HUD kits, theme presets, or "default RPG/FPS chrome" as the game's identity. Build the look this pitch needs.
+- **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)).
+- 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.