@jgengine/react 0.11.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/selectionHud.d.ts

@@ -35,6 +35,9 @@ export declare function useSelectionView(members: readonly EntitySummaryDef[], o
  * A compact current/max vital meter for an entity summary; tone maps to a colour ramp. Reuse it as
  * the vital row inside {@link EntitySummary} or any custom entity panel.
  *
+ * @deprecated The `tone`/`vital`-API umbrella is retired (#1033). Use the atomic, purpose-named,
+ * token-themed bars from `@jgengine/react/bars` (`HealthBar`, `ShieldBar`, `ManaBar`, …) and compose
+ * your own panel — each does one readout and restyles globally via the shared `--jg-*` tokens.
  * @capability vital-bar compact current/max vital meter for an entity summary
  */
 export declare function VitalBar({ vital, width, showLabel, className, style, }: {
@@ -67,6 +70,9 @@ export declare function EntityPortrait({ entity, selected, size, vitalId, tabInd
  * "who is selected" summary a single-selection or the head of a multi-selection shows. Swap the vital
  * rows via `renderVital`.
  *
+ * @deprecated Bundling a whole vitals array in one component is the combo anti-pattern #1033 retires.
+ * Compose your own summary — name/tags plus the atomic `@jgengine/react/bars` (`HealthBar`, …) you
+ * need — so no engine component packages multiple readouts by default. Kept during migration.
  * @capability entity-summary primary selected-entity detail panel (name, tags, vitals)
  */
 export declare function EntitySummary({ entity, renderVital, className, style, }: {
@@ -111,12 +117,12 @@ export declare function SelectionCollectionChrome({ model, itemSize, gap, window
     style?: CSSProperties;
 }): import("react").JSX.Element;
 /**
- * The batteries-included default: a skinned glass panel composing {@link EntitySummary} for the
- * primary member beside {@link SelectionCollectionChrome} for the rest. Pass `members` (or a prebuilt
- * `model`) and it renders a working RTS-style selection panel; every sub-renderer stays swappable, and
- * a game that wants a different frame composes the hook and chrome directly.
+ * Convenience composition: skinned glass panel with {@link EntitySummary} for the primary member
+ * beside {@link SelectionCollectionChrome} for the rest — demos/scaffold only, not a finished game
+ * face. Pass `members` (or a prebuilt `model`); swap sub-renderers or compose the headless pieces
+ * under game-owned chrome for product UI.
  *
- * @capability selection-panel drop-in selection panel: primary summary beside a portrait strip / group chips
+ * @capability selection-panel optional selection-panel composition: summary + portrait strip / group chips
  */
 export declare function SelectionPanel({ members, model: providedModel, groupThreshold, labelOf, windowSize, renderPrimary, renderMember, renderVital, onFocusChange, className, style, }: {
     members?: readonly EntitySummaryDef[];

package/dist/selectionHud.js

@@ -65,6 +65,9 @@ const VITAL_TONES = {
  * A compact current/max vital meter for an entity summary; tone maps to a colour ramp. Reuse it as
  * the vital row inside {@link EntitySummary} or any custom entity panel.
  *
+ * @deprecated The `tone`/`vital`-API umbrella is retired (#1033). Use the atomic, purpose-named,
+ * token-themed bars from `@jgengine/react/bars` (`HealthBar`, `ShieldBar`, `ManaBar`, …) and compose
+ * your own panel — each does one readout and restyles globally via the shared `--jg-*` tokens.
  * @capability vital-bar compact current/max vital meter for an entity summary
  */
 export function VitalBar({ vital, width = 120, showLabel = true, className, style, }) {
@@ -115,6 +118,9 @@ export function EntityPortrait({ entity, selected = false, size = 44, vitalId =
  * "who is selected" summary a single-selection or the head of a multi-selection shows. Swap the vital
  * rows via `renderVital`.
  *
+ * @deprecated Bundling a whole vitals array in one component is the combo anti-pattern #1033 retires.
+ * Compose your own summary — name/tags plus the atomic `@jgengine/react/bars` (`HealthBar`, …) you
+ * need — so no engine component packages multiple readouts by default. Kept during migration.
  * @capability entity-summary primary selected-entity detail panel (name, tags, vitals)
  */
 export function EntitySummary({ entity, renderVital, className, style, }) {
@@ -165,12 +171,12 @@ const PANEL = {
     font: "500 12px/1.2 ui-sans-serif, system-ui, sans-serif",
 };
 /**
- * The batteries-included default: a skinned glass panel composing {@link EntitySummary} for the
- * primary member beside {@link SelectionCollectionChrome} for the rest. Pass `members` (or a prebuilt
- * `model`) and it renders a working RTS-style selection panel; every sub-renderer stays swappable, and
- * a game that wants a different frame composes the hook and chrome directly.
+ * Convenience composition: skinned glass panel with {@link EntitySummary} for the primary member
+ * beside {@link SelectionCollectionChrome} for the rest — demos/scaffold only, not a finished game
+ * face. Pass `members` (or a prebuilt `model`); swap sub-renderers or compose the headless pieces
+ * under game-owned chrome for product UI.
  *
- * @capability selection-panel drop-in selection panel: primary summary beside a portrait strip / group chips
+ * @capability selection-panel optional selection-panel composition: summary + portrait strip / group chips
  */
 export function SelectionPanel({ members, model: providedModel, groupThreshold, labelOf, windowSize, renderPrimary, renderMember, renderVital, onFocusChange, className, style, }) {
     const ownModel = useSelectionView(members ?? [], { groupThreshold, labelOf, onFocusChange });

package/dist/slots.d.ts

@@ -0,0 +1,47 @@
+import { type CSSProperties, type ReactNode } from "react";
+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` — 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
+ */
+/** One slot's content — a `GameIcon` glyph (or custom node), school tint, count, keycap, active flag. */
+export interface SlotItem {
+    icon?: GameIconName;
+    glyph?: ReactNode;
+    school?: IconSchool;
+    count?: number;
+    keycap?: string;
+    active?: boolean;
+    /** Accessible label / tooltip. */
+    label?: string;
+}
+/** Props shared by every atomic slot grid. */
+export interface SlotGridProps {
+    /** Slots in order; `null` (or a slot with no icon/glyph) renders an empty placeholder. */
+    items: readonly (SlotItem | null)[];
+    /** Tile size in px. Default 44. */
+    size?: number;
+    /** Grid columns; default = one row (all slots). */
+    columns?: number;
+    /** Gap between tiles in px. Default 6. */
+    gap?: number;
+    className?: string;
+    style?: CSSProperties;
+}
+/** Worn-gear slots (head/chest/hands/…): one atomic grid, painted icons, themed from tokens. */
+export declare function EquipmentSlots(props: SlotGridProps): import("react").JSX.Element;
+/** Weapon loadout slots. */
+export declare function WeaponSlots(props: SlotGridProps): import("react").JSX.Element;
+/** Armor piece slots. */
+export declare function ArmorSlots(props: SlotGridProps): import("react").JSX.Element;
+/** Consumable (health/shield potion) slots. */
+export declare function PotionSlots(props: SlotGridProps): import("react").JSX.Element;

package/dist/slots.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import {} from "react";
+import { IconTreatment } from "./iconTreatment.js";
+function EmptySlot({ size }) {
+    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: "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",
+        } }));
+}
+function SlotGrid({ category, items, size = 44, columns, gap = 6, className, style }) {
+    const cols = columns ?? items.length;
+    return (_jsx("div", { "data-slots": category, className: className, style: { display: "grid", gridTemplateColumns: `repeat(${Math.max(1, cols)}, ${size}px)`, gap, ...style }, children: items.map((item, index) => {
+            const filled = item !== null && (item.icon !== undefined || item.glyph !== undefined);
+            return filled ? (_jsx(IconTreatment, { ...(item.icon === undefined ? {} : { icon: item.icon }), ...(item.glyph === undefined ? {} : { glyph: item.glyph }), school: item.school ?? "neutral", size: size, ...(item.count === undefined ? {} : { count: item.count }), ...(item.keycap === undefined ? {} : { keycap: item.keycap }), active: item.active ?? false }, index)) : (_jsx(EmptySlot, { size: size }, index));
+        }) }));
+}
+/** Worn-gear slots (head/chest/hands/…): one atomic grid, painted icons, themed from tokens. */
+export function EquipmentSlots(props) {
+    return _jsx(SlotGrid, { category: "equipment", ...props });
+}
+/** Weapon loadout slots. */
+export function WeaponSlots(props) {
+    return _jsx(SlotGrid, { category: "weapon", ...props });
+}
+/** Armor piece slots. */
+export function ArmorSlots(props) {
+    return _jsx(SlotGrid, { category: "armor", ...props });
+}
+/** Consumable (health/shield potion) slots. */
+export function PotionSlots(props) {
+    return _jsx(SlotGrid, { category: "potion", ...props });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/react",
-  "version": "0.11.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.11.0"
+    "@jgengine/core": "^0.13.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/skills/jgengine/SKILL.md

@@ -9,16 +9,16 @@ Read the repository [README](../../../README.md) for package truth, commands, la
 
 ## 1. Establish the target
 
-Capture only decisions that change architecture:
+Treat the pitch as a unique composition of needs, not a genre to fill in — never reach for a genre kit, preset, archetype, or class template ("default sports car", "default RPG", "default FPS") in the SDK or skills (see [AGENTS.md](../../../AGENTS.md)). Use `game-design` to turn the pitch into a testable player promise, verbs, loops, progression, failure, and completion scenario. Use `level-design` when play depends on authored spaces, routes, encounters, exploration, or spatial pacing. Capture only decisions that change architecture:
 
 - player point of view and controls
 - world shape and authored content
 - core loop, interaction, combat, and progression
 - solo, local, hosted, or persistent multiplayer
-- HUD/menu states and art direction
+- HUD/menu states and **custom** UI art direction (every game owns its presentation — no stock drop-in face)
 - one observable completion scenario
 
-For a new in-repo game, scaffold with `bun run new:game <id> --name "Title"`. Outside this monorepo, start with `npx jgengine create`; never copy `Games/*`.
+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/*`.
 
 ## 2. Select domains
 
@@ -26,6 +26,8 @@ Load only rows the target needs. Do not preload every domain.
 
 | Need | Skill | Owner |
 | --- | --- | --- |
+| player promise, pillars, verbs, loops, economy, progression, balance | `game-design` | experience and rule intent |
+| metrics, topology, encounters, navigation, spatial pacing | `level-design` | playable space intent |
 | scene placement, terrain painting, paths, asset authoring | `jgengine-editor` | editor document and authoring tools |
 | runtime world, movement, input, interaction, AI, navigation, audio | `jgengine-world` | spatial simulation and world runtime |
 | game state, systems, inventory, crafting, quests, economy, turns | `jgengine-gameplay` | non-combat rules and state |
@@ -34,15 +36,17 @@ Load only rows the target needs. Do not preload every domain.
 | models, sprites, materials, audio files, source licensing | `jgengine-assets` | asset discovery and catalogs |
 | authority, transport, replication, sessions, host persistence | `jgengine-multiplayer` | network topology and persistence adapters |
 
-Scenes normally require both `jgengine-editor` for authoring and `jgengine-world` for runtime consumption. Combat and multiplayer are opt-in, not default intake.
+World content routes editor-first: any request that adds, moves, restyles, or removes something visible in the world — however phrased ("design this world", "place the enemies", "make it look better") — starts in `jgengine-editor`; the other domains consume the authored document. Scenes normally require both `jgengine-editor` for authoring and `jgengine-world` for runtime consumption. Combat and multiplayer are opt-in, not default intake.
 
 ## 3. Discover before designing
 
 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.
+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.
 
 If no capability fits, identify the upstream package seam before writing game-local code. In this repository, implement a reusable primitive with its first adopter; if editor-owned content cannot be expressed, file the editor gap first.