@jgengine/react 0.11.0 → 0.12.0

package/skills/jgengine-ui/capabilities.md

@@ -4,7 +4,7 @@
 
 Reach for these before hand-rolling. Each row is *the thing you need* → *the primitive that already does it*.
 
-## action-bar — drop-in cooldown/cost/hotkey action bar over the headless action model
+## action-bar — optional skinned action-bar composition over the headless model — games own chrome
 
 - `ActionBar` (function) · `import { ActionBar } from "@jgengine/react"`
 
@@ -61,6 +61,67 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `useEventMeter` (function) · `import { useEventMeter } from "@jgengine/react"`
 
+## heightfield-mesh-update — in-place partial update of a displaced ground plane mesh
+
+- `displaceHeightfieldGeometry` (function) · `import { displaceHeightfieldGeometry } from "@jgengine/shell/terrain"`
+
+## hud-canvas — the HUD root surface — design-resolution scaling plus live panel-placement editing (F2+C)
+
+- `HudCanvas` (function) · `import { HudCanvas } from "@jgengine/react"`
+
+## hud-clock — in-game time-of-day readout bound to the sim clock
+
+- `Clock` (function) · `import { Clock } from "@jgengine/react"`
+
+## hud-coins — currency counter widget bound to a currency id
+
+- `Coins` (function) · `import { Coins } from "@jgengine/react"`
+
+## hud-frame — optional framed panel skins (glass/plate/retro/themed) — games own product chrome
+
+- `HudFrame` (function) · `import { HudFrame } from "@jgengine/react"`
+
+## hud-hotbar — optional inventory hotbar building block — games own slot chrome
+
+- `Hotbar` (function) · `import { Hotbar } from "@jgengine/react"`
+
+## hud-icons — painted-icon treatment for hotbar/action slots — glyph + gradient + count badge
+
+- `IconSchool` (type) · `import { IconSchool } from "@jgengine/react"`
+
+## hud-layout — persistent, live-editable HUD panel layout state for `HudCanvas`
+
+- `useHudLayout` (function) · `import { useHudLayout } from "@jgengine/react"`
+
+## hud-layout-persist — inject a host callback so canvas HUD edits commit into the scene document
+
+- `HudLayoutPersistProvider` (function) · `import { HudLayoutPersistProvider } from "@jgengine/react"`
+
+## hud-layout-persist-hook — read the host panel-commit port from a HUD layout widget
+
+- `useHudLayoutPersist` (function) · `import { useHudLayoutPersist } from "@jgengine/react"`
+
+## hud-panel — anchored HUD slot — drop any widget in a named, player-movable panel
+
+- `HudPanel` (function) · `import { HudPanel } from "@jgengine/react"`
+
+## hud-slots — atomic themed equipment/weapon/armor/potion slot grids with painted icons
+
+- `SlotItem` (interface) · `import { SlotItem } from "@jgengine/react"`
+
+## hud-stat-bar — optional stat-bound bar building block (health, mana, stamina) — prefer game-owned chrome
+
+- `StatBar` (function) · `import { StatBar } from "@jgengine/react"`
+
+## hud-theme — game-authored token object for bars, frames, slots, and minimap ring
+
+- `HudThemePalette` (interface) · `import { HudThemePalette } from "@jgengine/react"`
+
+## hud-vitals — atomic purpose-named vitals bars (token-themed parts, not a finished HUD)
+
+- `BarTokens` (interface) · `import { BarTokens } from "@jgengine/react"`
+- `barTokens` (function) · `import { barTokens } from "@jgengine/react"`
+
 ## key-hint — keyboard/mouse control hint that hides itself on touch
 
 - `KeyHint` (function) · `import { KeyHint } from "@jgengine/react"`
@@ -69,6 +130,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `Keycap` (function) · `import { Keycap } from "@jgengine/react"`
 
+## live-markers — a self-ticking MarkerSet kept in sync from the live scene each HUD tick — pass a rebuild(markers, ctx) that clears+repopulates, no hand-rolled setInterval
+
+- `useLiveMarkers` (function) · `import { useLiveMarkers } from "@jgengine/react"`
+
 ## minimap — framed circular minimap with terrain bake, fog, markers, and facing arrow
 
 - `Minimap` (function) · `import { Minimap } from "@jgengine/react"`
@@ -81,6 +146,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `MinimapPanel` (function) · `import { MinimapPanel } from "@jgengine/react"`
 
+## minimap-track-hud — horizontal linear track minimap (corridor/route progress) — colored zone spans and gate/player pips positioned by 0..1 fraction, sharing chrome with the radial Minimap
+
+- `MinimapTrack` (function) · `import { MinimapTrack } from "@jgengine/react"`
+
 ## nameplates — billboarded name + HP bar over nearby entities
 
 - `WorldNameplates` (function) · `import { WorldNameplates } from "@jgengine/shell/world/WorldHud"`
@@ -113,7 +182,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `useSelectionView` (function) · `import { useSelectionView } from "@jgengine/react"`
 
-## selection-panel — drop-in selection panel: primary summary beside a portrait strip / group chips
+## selection-panel — optional selection-panel composition: summary + portrait strip / group chips
 
 - `SelectionPanel` (function) · `import { SelectionPanel } from "@jgengine/react"`
 

package/skills/jgengine-ui/recipes/portable-minimap.md

@@ -0,0 +1,150 @@
+# Add the minimap to an existing React game
+
+Use this recipe when a React game already owns its entities in an array, ECS
+query, Zustand/Redux-style store, or another observable collection. JGengine
+only needs a display view of those records; do not copy them into a
+`MarkerSet`.
+
+## Install
+
+Keep the React and React DOM versions already used by the project, then add the
+two focused JGengine packages:
+
+```sh
+bun add @jgengine/core @jgengine/react
+```
+
+The minimap imports neither Three.js nor React Three Fiber and does not require
+`GameProvider`.
+
+## Static entity arrays
+
+Project an existing array directly. Keep the array stable with the same memo or
+selector the project already uses.
+
+```tsx
+import { useMemo } from "react";
+import { Minimap } from "@jgengine/react/map";
+
+interface Unit {
+  id: string;
+  x: number;
+  z: number;
+  team: "ally" | "enemy";
+}
+
+export function MapHud({
+  units,
+  cameraTarget,
+}: {
+  units: readonly Unit[];
+  cameraTarget: { x: number; z: number };
+}) {
+  const markers = useMemo(
+    () =>
+      units.map((unit) => ({
+        id: unit.id,
+        position: [unit.x, 0, unit.z] as const,
+        kind: unit.team,
+      })),
+    [units],
+  );
+
+  return (
+    <Minimap
+      markers={markers}
+      center={[cameraTarget.x, cameraTarget.z]}
+      worldRadius={120}
+      className="game-minimap"
+    />
+  );
+}
+```
+
+Only `id` and `position` are required. `kind`, `label`, `heading`, and `meta`
+are optional display data; lifecycle timestamps are not part of this view.
+
+## Observable external store
+
+Create the adapter once per store. The source caches its projected marker array
+until the external store emits, so React snapshot reads do not remap the world
+on every frame.
+
+```tsx
+import { useMemo } from "react";
+import { createMarkerSource } from "@jgengine/core/world/markers";
+import { Minimap } from "@jgengine/react/map";
+
+interface Unit {
+  id: string;
+  x: number;
+  z: number;
+  team: string;
+  name: string;
+}
+
+interface ExistingWorldStore {
+  subscribe(listener: () => void): () => void;
+  getState(): { units: readonly Unit[] };
+}
+
+export function ExistingGameMinimap({
+  world,
+  cameraTarget,
+}: {
+  world: ExistingWorldStore;
+  cameraTarget: { x: number; z: number };
+}) {
+  const markers = useMemo(
+    () =>
+      createMarkerSource({
+        subscribe: (listener) => world.subscribe(listener),
+        getSnapshot: () => world.getState().units,
+        project: (unit) => ({
+          id: unit.id,
+          position: [unit.x, 0, unit.z] as const,
+          kind: unit.team,
+          label: unit.name,
+        }),
+      }),
+    [world],
+  );
+
+  return (
+    <Minimap
+      markers={markers}
+      center={[cameraTarget.x, cameraTarget.z]}
+      worldRadius={120}
+    />
+  );
+}
+```
+
+For SSR, make the store's first client snapshot match the server snapshot. When
+they differ structurally, pass `getServerSnapshot` to `createMarkerSource` and
+read the same serialized initial units used to hydrate the external store.
+
+## Ownership
+
+The existing project still owns entities, updates, persistence, simulation,
+camera, renderer, input, scheduling, and the subscription. JGengine owns only
+the cached entity-to-marker projection, core world-to-map projection math, and
+the React SVG presentation. Save and restore the project's unit state as usual;
+markers are derived data and need no parallel save format.
+
+Use `kindStyles`, `className`, and `style` to skin the production `Minimap`.
+When the project owns every chrome element, compose `MinimapChrome` inside its
+own SVG instead of adopting the framed default.
+
+## Common traps
+
+- Keep `getSnapshot()` array identity stable until `subscribe()` emits. This is
+  the React external-store contract.
+- Create `createMarkerSource` outside render or in `useMemo`; recreating it each
+  render discards its projection cache.
+- Pass world coordinates, not Three.js screen coordinates. Marker positions are
+  `[x, y, z]`; the minimap projects X/Z.
+- Do not poll the source from a render loop. Notify subscribers when the
+  caller-owned collection changes.
+- Do not add `createdAt` or `expiresAt` unless the project intentionally adopts
+  `MarkerSet` lifecycle behavior.

package/skills/jgengine-ui/reference.md

@@ -4,9 +4,11 @@ This reference defines the required visual and interaction quality for JGengine
 
 ## The rule
 
-A game must visually own its viewport. It must not resemble a dashboard, landing page, documentation page, or ordinary responsive web app.
+A game must visually own its viewport **and its entire interface**. Presentation is game content: each title designs a custom HUD, menus, feedback, and art direction. It must not resemble a dashboard, landing page, documentation page, ordinary responsive web app, **or another JGengine game's default widget stack**.
 
-HTML and React are valid implementation tools. Website visual grammar is not the default.
+The engine does not ship a finished game UI. `@jgengine/react` offers headless data/layout/accessibility seams and optional building blocks. Dropping in stock `StatBar` / `Hotbar` / `Coins` / glass `HudFrame` / theme presets without game-specific composition is incomplete work — not "using the engine correctly."
+
+HTML and React are valid implementation tools. Website visual grammar is not the default. Engine default chrome is not the default either.
 
 ## 1. Start with a concise UI art direction
 
@@ -95,13 +97,13 @@ The active game should behave like an application mode:
 Recommended layer contract:
 
 ```tsx
-<GamePlayer>
+<GameHost>
   <WorldLayer />
   <HudLayer />
   <ControlLayer />
   <ScreenLayer />
   <SystemLayer />
-</GamePlayer>
+</GameHost>
 ```
 
 - `WorldLayer`: game renderer
@@ -142,9 +144,11 @@ Design-resolution fit is on by default for every game: each `HudCanvas` auto-sca
 
 **Overflow is an error, not a style note.** `HudCanvas` measures every `HudPanel` against the viewport at runtime; offenders land in a `data-hud-overflow` attribute (and a console warning), and `bun run shoot <game> --device mobile` (or `both`) exits non-zero naming the escaping panels. A game is not mobile-done while shoot reports HUD OVERFLOW.
 
+**Authoring placement lives in the editor.** HUD panel placement is authored from the scene editor's **HUD** mode (F2+E → **HUD** toolbar button), not a separate devtools chord — the button mounts the game's real `HudCanvas` over the frozen world with drag/resize editing on. Dragging a panel writes an undoable `setUiPanel` patch into the scene document's `ui.panels` section (the same document the `canvas_move_panel` / `canvas_resize_panel` RPC verbs still target), so authored layout ships in `editor.scene.json`. The author's canvas **Done** button (or Esc / F2+C / F2+E) leaves HUD mode. Per-panel resize axes come from the panel `type`'s `registerHudPanelType` spec.
+
 ### Phase-gated HUD visibility (`showDuring`)
 
-`HudCanvas` and `HudPanel` take an opt-in `showDuring?: GamePhase[]` — the element renders only while `gamePhase` is one of the listed phases (`"menu" | "playing" | "paused" | "ended"`), so a non-cartridge game hides its HUD under menu/end overlays without hand-rolling a phase check. Omit it for the default always-visible behavior. Gate the whole HUD with `<HudCanvas showDuring={["playing"]}>`, or keep a single results panel up with a per-`HudPanel` value. The read degrades to `"playing"` when the component renders outside a `GameProvider` (component showcases, previews), so it never throws there.
+`HudCanvas` and `HudPanel` take an opt-in `showDuring?: GamePhase[]` — the element renders only while `gamePhase` is one of the listed phases (`"menu" | "playing" | "paused" | "ended"`), so a game hides its HUD under menu/end overlays without hand-rolling a phase check. Omit it for the default always-visible behavior. Gate the whole HUD with `<HudCanvas showDuring={["playing"]}>`, or keep a single results panel up with a per-`HudPanel` value. The read degrades to `"playing"` when the component renders outside a `GameProvider` (component showcases, previews), so it never throws there.
 
 ### Shared viewport allocation (`GameViewportProvider`, region collision)
 
@@ -220,7 +224,16 @@ Prefer small headless or lightly styled primitives over a giant universal design
 
 A primitive should expose game-oriented choices such as shape, material, urgency, placement, hierarchy, entry motion, icon treatment, compactness, and diegetic-versus-overlay presentation.
 
-**Minimap** is already shipped, not hand-rolled: `Minimap` / `WorldMap` / `Compass` from `@jgengine/react/map` render a framed SVG minimap over a `MarkerSet` (`createMarkerSet`, `@jgengine/core/world/markers`) and optional `FogField`, projecting via `@jgengine/core/world/minimap` (`projectToMinimap`, `headingToBearing`, edge-clamp). A game feeds flat props (`markers`, `center: [x,z]`, `worldRadius`, `size`, `facingYaw`, `rotate`) and repopulates the marker set each HUD tick from live entities — no custom canvas painter. `MinimapPanel` (same module) composes zone-label + clock header slots and a `Compass` strip around a `Minimap` — pass `zoneLabel`/`clock` nodes (e.g. from `useGameClock().calendar`) and `showCompass`/`compassProps`; omit either header slot and it collapses, `showCompass={false}` drops the strip. Rolling a **custom** minimap around your own course/route content (not the full `Minimap` panel)? `MinimapChrome` is the headless chrome layer other games were re-drawing by hand: nest it inside your own `<svg>` for the ring `frame`, and pass `markers: MinimapChromeMarker[]` (`{ id, position, heading?, color?, radius?, glyph? }`) for edge-clamped dots that draw as a rotated arrow whenever a marker carries a `heading` (the compass-arrow / player-blip layer) — never hand-roll `clampToMinimapEdge` + a `<polygon>` again. **Nameplates**: `WorldNameplates` (`@jgengine/shell/world/WorldHud`) billboards a name + optional 78×6px HP bar over every nearby non-local entity — turn it on declaratively via `defineGame({ nameplates: { roles, maxDistance } })` (mirrors `worldHealthBars`) rather than mounting it by hand; skin every part via `className`/`data-*` slots (`nameplateClassName`, `nameClassName`, `barClassName`, `fillClassName`) or swap the whole markup with `renderNameplate`. **Selection rings**: `WorldObjectHighlights` (`@jgengine/shell/world/WorldHud`) draws a ground ring over every `ctx.scene.object.selection`-ed placed object — the object-layer counterpart to `WorldEntityBars`/`WorldNameplates`; mount it once in the game's scene (`color`/`radius`/`y` props, `radius` otherwise derived from the object's catalog `halfExtents`) instead of hand-rolling a selection highlight through `WorldOverlay` against external state. **Playing cards** are already shipped, not hand-rolled: `CardFace` / `StackedPile` / `CardStack` (with `Suit`, `Rank`, `PlayingCard`) from `@jgengine/react/cards` render a French-deck face (rank + suit pips, patterned back when `faceDown`) and an overlapping fan. `StackedPile` composes the existing drag system (`useDragLayer`/`DraggableCard`/`DropZone`) — pass a `layer` for drag and `dropId` for a drop target; `CardStack` binds a fan to a headless `CardPileState` zone (`@jgengine/core/cards/cardPile`). Never draw cards on a canvas or reinvent pointer handling. **Swing timer**: `swingTimerState(player, target, prevPeriod, prevTimer)` (`@jgengine/core/ui/swingTimer`) is the pure, parameter-in/next-state-out core for a melee swing bar (recovers period on the reset edge; hidden unless auto-attacking a live non-object target) — thread the returned `nextPeriod`/`nextTimer` back via refs, render a thin `Meter`.
+**Portable minimap adoption.** Existing React games pass `MarkerView[]`, a
+`MarkerSource`, or their existing `MarkerSet` to `Minimap`/`Compass`/`WorldMap`.
+Use `createMarkerSource` (`@jgengine/core/world/markers`) to cache a projection
+from an external ECS/store snapshot; it needs no `GameProvider`, Three.js, or
+React Three Fiber. Follow [the portable minimap recipe](recipes/portable-minimap.md)
+instead of mirroring external entities into `createMarkerSet`.
+
+**Minimap** is already shipped, not hand-rolled: `Minimap` / `WorldMap` / `Compass` from `@jgengine/react/map` render a framed SVG minimap over a `MarkerSet` (`createMarkerSet`, `@jgengine/core/world/markers`) and optional `FogField`, projecting via `@jgengine/core/world/minimap` (`projectToMinimap`, `headingToBearing`, edge-clamp). A game feeds flat props (`markers`, `center: [x,z]`, `worldRadius`, `size`, `facingYaw`, `rotate`) and repopulates the marker set each HUD tick from live entities — no custom canvas painter. `MinimapPanel` (same module) composes zone-label + clock header slots and a `Compass` strip around a `Minimap` — pass `zoneLabel`/`clock` nodes (e.g. from `useGameClock().calendar`) and `showCompass`/`compassProps`; omit either header slot and it collapses, `showCompass={false}` drops the strip. **Baked terrain background**: to draw the authored terrain under the markers, pass `background={document.minimap?.background}` and `mapBounds={document.minimap?.bounds}` to `Minimap`/`WorldMap` (or `MinimapPanel`, which forwards both through) — the editor's `bake_minimap` action stores a top-down terrain PNG + world bounds on `EditorDocument.minimap` (see `jgengine-editor`), and runtime reads that stored PNG with no re-rasterization. Both are undefined until baked, so an unbaked game renders the plain map unchanged. Rolling a **custom** minimap around your own course/route content (not the full `Minimap` panel)? `MinimapChrome` is the headless chrome layer other games were re-drawing by hand: nest it inside your own `<svg>` for the ring `frame`, and pass `markers: MinimapChromeMarker[]` (`{ id, position, heading?, color?, radius?, glyph? }`) for edge-clamped dots that draw as a rotated arrow whenever a marker carries a `heading` (the compass-arrow / player-blip layer) — never hand-roll `clampToMinimapEdge` + a `<polygon>` again. **Nameplates**: `WorldNameplates` (`@jgengine/shell/world/WorldHud`) billboards a name + optional 78×6px HP bar over every nearby non-local entity — turn it on declaratively via `defineGame({ nameplates: { roles, maxDistance } })` (mirrors `worldHealthBars`) rather than mounting it by hand; skin every part via `className`/`data-*` slots (`nameplateClassName`, `nameClassName`, `barClassName`, `fillClassName`) or swap the whole markup with `renderNameplate`. **Selection rings**: `WorldObjectHighlights` (`@jgengine/shell/world/WorldHud`) draws a ground ring over every `ctx.scene.object.selection`-ed placed object — the object-layer counterpart to `WorldEntityBars`/`WorldNameplates`; mount it once in the game's scene (`color`/`radius`/`y` props, `radius` otherwise derived from the object's catalog `halfExtents`) instead of hand-rolling a selection highlight through `WorldOverlay` against external state. **Playing cards** are already shipped, not hand-rolled: `CardFace` / `StackedPile` / `CardStack` (with `Suit`, `Rank`, `PlayingCard`) from `@jgengine/react/cards` render a French-deck face (rank + suit pips, patterned back when `faceDown`) and an overlapping fan. `StackedPile` composes the existing drag system (`useDragLayer`/`DraggableCard`/`DropZone`) — pass a `layer` for drag and `dropId` for a drop target; `CardStack` binds a fan to a headless `CardPileState` zone (`@jgengine/core/cards/cardPile`). Never draw cards on a canvas or reinvent pointer handling. **Swing timer**: `swingTimerState(player, target, prevPeriod, prevTimer)` (`@jgengine/core/ui/swingTimer`) is the pure, parameter-in/next-state-out core for a melee swing bar (recovers period on the reset edge; hidden unless auto-attacking a live non-object target) — thread the returned `nextPeriod`/`nextTimer` back via refs, render a thin `Meter`.
+
+**HUD widgets split into three reusable layers** — data, renderer, chrome — so a second presentation drops in without a forked widget. **Chrome**: `HudFrame` (`@jgengine/react/hudFrame`, `hud-frame` capability) is the single framed-panel primitive — `<HudFrame variation="glass"|"plate"|"retro" shape="rounded"|"circle"|"square" title aside padding width style>` renders a `data-hud-frame` div with an optional small-caps `title`/`aside` header; `glass` is byte-identical to the built-in widgets' dark-glass panel, `plate` a heavier opaque plate, `retro` a hard black-outlined frame. Need only the CSS on your own element? spread `hudFrameStyle(variation, shape)`. Reach for it instead of hand-rolling a bordered panel `<div>` per widget. **Renderer**: `MinimapTrack` (`@jgengine/react/map`, `minimap-track-hud` capability) is a structurally-different second minimap — a horizontal linear progress rail (vs the radial `Minimap`) with colored zone `spans` and gate/exit/player `pips` placed by 0..1 fraction, driven by core `trackFraction([x,z], { from, to })` (`@jgengine/core/world/minimapTrack`, `minimap-track` capability — the 1D analogue of `projectToMinimap`). It reads no store; the caller supplies fractions. Use it for corridor/route progress; use the radial `Minimap` for open worlds — both share `HudFrame` chrome. **Data**: `useLiveMarkers(rebuild, { intervalMs?, deps? })` (`@jgengine/react/hooks`, `live-markers` capability) returns a self-ticking `MarkerSet` that each HUD tick clears and re-runs your `rebuild(markers, ctx)` against the live scene — replaces the hand-rolled `useState` ticker + `useEffect` + `createMarkerSet` + `markers.clear()` + rescan boilerplate; feed the returned set straight into `Minimap`/`MinimapPanel`.
 
 **Heat/streak gauges** are already shipped, not hand-rolled `clamp(value/max)`: build the gauge with `createEventMeter` (`@jgengine/core/stats/eventMeter`, `event-meter` capability — ult/adrenaline `"hold"` mode or streak/combo `"reset"` mode over tagged event gains) and bind it to a component with `useEventMeter(meter)` (`@jgengine/react`, `event-meter-hud` capability) — it self-ticks a heartbeat and returns `{ value, fraction, tier, ready }` for a `Meter`/`BossBar`-style fill, no manual `setInterval` polling of `meter.value()`.
 
@@ -477,7 +490,7 @@ Require revision when any of these are true:
 
 ## 15. Compact implementation API appendix
 
-Use the main `jgengine` skill for the authoritative engine API routing. The React package exposes `GameProvider`, hooks, and headless primitives from `@jgengine/react` and its documented subpaths. Common hooks include player/game state, entities, stats, inventory, quests, prompts, clocks, markers, fog, and engine stores. The shell provides `GamePlayerShell`, input integration, devtools, and `GameUiPreview`; `@jgengine/shell/GamePlayerShell` also re-exports the movement primitives it wires up internally (`applyMotionImpulses`, `nearbyObstacles`, `resolvePhysicsTuning`, `hasEnvironmentTerrain`) for a host that needs to replicate its physics loop, and `@jgengine/shell/terrain` re-exports the `jgengine-world` field builders (`arenaField`, `flatField`, `fractalNoise`, `resolveGroundStep`, `valueNoise`, `withNormal`) alongside its own `CarvedTerrain`/`GrassField` components so a shell consumer never needs a second import from core.
+Use the main `jgengine` skill for the authoritative engine API routing. The React package exposes `GameProvider`, hooks, and headless primitives from `@jgengine/react` and its documented subpaths. Common hooks include player/game state, entities, stats, inventory, quests, prompts, clocks, markers, fog, and engine stores. The shell provides `GameHost` (the game mount), input integration, devtools, and `GameUiPreview`; `@jgengine/shell/GamePlayerShell` (the internal player `GameHost` composes) also re-exports the movement primitives it wires up internally (`applyMotionImpulses`, `nearbyObstacles`, `resolvePhysicsTuning`, `hasEnvironmentTerrain`) for a host that needs to replicate its physics loop, and `@jgengine/shell/terrain` re-exports the `jgengine-world` field builders (`arenaField`, `flatField`, `fractalNoise`, `resolveGroundStep`, `valueNoise`, `withNormal`) alongside its own `CarvedTerrain`/`GrassField` components so a shell consumer never needs a second import from core.
 
 Use these APIs to bind state; do not let API wiring dictate visual composition. Keybind labels should derive from the game’s binding table, and UI actions should dispatch through game commands rather than existing only as click handlers.
 

package/skills/jgengine-ui/references/visual-scorecard.md

@@ -27,7 +27,7 @@ Score all ten from one `--mode play` shot plus deterministic world/document evid
 6. **Materials/textures** — terrain and props carry texture and color variation (`environment({ sculpt, materialRegions })`, catalog GLBs via `jgengine-assets`), not flat untextured solids.
 7. **Lighting/render** — a tuned daylight/sun+hemisphere rig and post stack (per `look: "cinematic"`, #773), not the bare untouched three.js default light.
 8. **VFX/motion** — particle/motion feedback tied to actual gameplay events (hits, pickups, weather), not absent, and not one looping default effect standing in everywhere.
-9. **UI/HUD** — a game-specific `HudCanvas`/`HudPanel` composition; fails automatically if it could pass for a generic admin dashboard.
+9. **UI/HUD** — a game-specific `HudCanvas`/`HudPanel` composition with unique art direction; fails automatically if it could pass for a generic admin dashboard **or** for another game shipping stock engine widgets/theme presets unskinned.
 10. **Performance evidence** — the look holds at the scale the game actually runs (`InstancedScatter` density, many entities), not only a hand-posed hero shot with three objects in frame.
 
 ## Measured-evidence row

package/skills/jgengine/reference-cartridge.md

@@ -1,72 +0,0 @@
-# jgengine-api — Cartridge
-
-Reference module for the [`jgengine`](./SKILL.md) skill. Load this when building a game as a **cartridge** — one declarative config instead of hand-wired loop/state/UI files. A cartridge game is ~75% smaller than the classic shape and nearly all of it is data; reach for `defineGame` + `defineSystem` ([reference-systems.md](./reference-systems.md)) when the simulation outgrows cartridge archetypes — same single authoring model, no rewrite cliff.
-
-## Why
-
-Across the classic games, 78–91% of each game's LOC was generic wiring restated per game: a run-state store with subscribe/notify, chase-and-contact enemy loops, auto-fire weapon routines, magnet pickups, draft plumbing, phase-gated HUD trees, and tests for all of it. The cartridge layer owns every one of those; the game ships only its **data** (catalogs, tuning, layout) and any genuinely bespoke rules through typed escape hatches.
-
-## Shape
-
-`game.config.ts` is the whole game — `cartridge({...})` from `@jgengine/shell/cartridge` compiles the config into a `PlayableGame` (validating it first — a bad reference throws at import with a list of problems). `loop.ts` and `world.ts` disappear; the spec carries the world feature and the loop is engine-owned. `main.tsx` is 5 lines via `mountGame` (`@/components/ui/mount`, registry). Sprites/SVG art stay in `src/game/assets.ts`; the game keeps one test file under `src/game/`.
-
-```ts
-import { cartridge, type CartridgeConfig } from "@jgengine/shell/cartridge";
-import { standardCartridgePanels } from "@/components/ui/cartridge-panels";
-
-export const config: CartridgeConfig = {
-  name, seed, panels: standardCartridgePanels, assets, entitySprites,
-  flow: { start: "gate", countdownSeconds: 3, restart: true },  // press-to-start → 3-2-1 → playing; "restart" command
-  player: { kind, health, walkSpeed },              // compiled into content + spawned per player
-  enemies: { id: { label, health, walkSpeed, xp, contact: { damage, intervalSeconds }, behavior: "chase" | "none" } },
-  combat: { contactRadius },
-  spawning: { director: SpawnDirectorConfig, placement: { kind: "ring", radius } },
-  weapons: { id: { kind: "projectile" | "orbit" | "pulse" | "custom", damage, cooldownMs, maxLevel, ... } },
-  progression: { xp: Curve, maxLevel, draft: { choices, upgrades } },
-  fields: { magnetRadius, damageMultiplier },       // named run-scalars upgrades mutate
-  xpGems: { collectRadius, pullSpeed, rarityThresholds, defaultRarity },
-  rules: { win: { kind: "survive", seconds }, lose: { kind: "playerDeath" } | { kind: "custom", check }, killLeaderboardStat },
-  world, physics, camera, worldItem, theme, hud, screens,   // screens: start/win/lose
-};
-export const game = cartridge(config);
-```
-
-The run is a phase machine every game gets for free: `start → countdown → playing → won | lost`. `flow.start: "gate"` renders `screens.start` (TitleScreen binding) until begin; `flow.countdownSeconds` renders the big-number countdown; `flow.restart: true` registers a `restart` command that resets the run in place, clears cartridge entities, and restores player stats — no hand-rolled session store, phase union, or reset function. `run.playingSeconds` is the run clock (drives the survive rule and the timer panel), so pauses and pre-game phases never skew timing.
-
-## Cartridge surface (`@jgengine/shell/cartridge/`)
-
-The survivor-shaped defaults (XP gems, contact-radius melee, orbit/pulse/projectile weapons) are a genre archetype, not a core primitive — the whole cartridge implementation lives in `@jgengine/shell` (opt-in, alongside its React binding), never in `@jgengine/core`. `core` only supplies the generic pieces it composes: `spawnDirector`, `abilityKit`, `leveling`/`progression`, `runDraft`, `autoTarget`. A puzzle or tactics game imports none of this.
-
-- `@jgengine/shell/cartridge/spec` — the `CartridgeSpec` types, `Leveled` values (`number | { base, perLevel, min?, max? } | { table }` resolved by `leveled(value, level)`), `WASD_KEYBINDS` (the default when `input` is omitted).
-- `@jgengine/shell/cartridge/runtime` — `createCartridge(spec)` → `{ content, loop, run(ctx), weaponKit(ctx), chooseUpgrade(ctx, offerId) }`. Owns the run store (outcome/kills/fields/weapon levels, subscribe/notify), spawn director advance + ring placement, chase + contact-damage enemies (terrain-grounded), the three weapon archetypes with auto-targeting, magnet xp-gem pickups feeding `leveling()`, pause-and-draft level-ups, kill → gem drop + leaderboard, and win/lose rules.
-- `@jgengine/shell/cartridge/validate` — `validateCartridge(spec)` → problem list: spawn waves must reference declared enemies, upgrades must reference declared weapons/fields, stacks can't exceed weapon `maxLevel`, tuning must be positive, rarity thresholds descending. The game's test asserts it returns `[]`.
-
-Weapon archetypes: `projectile` (auto-target nearest in `range`, travel-time bolt fx), `orbit` (leveled blade count/radius sweeping `hitRadius`), `pulse` (radial AoE with linear falloff and an expanding-ring fx). Upgrade effects: `weaponLevel` (+1 level per stack), `statBonus` (+max and +current on pick), `fieldAdd` / `fieldMultiply` (recomputed from stacks). Weapon damage is multiplied by the `damageMultiplier` field when declared.
-
-## Presentation (shell + registry)
-
-`hud.panels` is a schema — items `vital | xp | timer | score | abilityBar | component`, anchored via the movable HUD layout; `screens.win/lose` render the results/death screens; the upgrade-draft modal appears whenever a draft is pending. The shell renders the frame and injects concrete components through the `panels` seam — `standardCartridgePanels` (registry `cartridge-panels`) binds the jgengine UI kit; swap any binding for a custom component without touching the engine. Weapon fx render engine-side from the run store's bolt/pulse feeds (`fxColor`/`fxEmissive` per weapon). `theme` is the `--jg-*` CSS var block — hand-pick it or derive from a few seed colors with `deriveJgTheme` (registry `jg-theme`).
-
-## Escape hatches — bespoke logic without leaving the cartridge
-
-- `weapons.<id> = { kind: "custom", fire(ctx, run, args) }` — cooldown/level/damage handled for you; the fire shape is yours.
-- `spawning.placement = { kind: "custom", position(ctx, run) }`.
-- `rules.win = { kind: "custom", check(ctx, run) }`.
-- `progression.draft.upgrades[].effect = { kind: "custom", apply(ctx, run, stacks) }`.
-- `systems: [(ctx, run, dt) => ...]` — extra per-tick simulation after the built-ins, only while playing.
-- `hud` items `{ kind: "component", Component }` — arbitrary React panels alongside the schema ones.
-
-A game that is *mostly* bespoke simulation (custom physics, session machines) should keep `defineGame` and write its systems — the cartridge is for games whose shape the archetypes already cover.
-
-## Testing
-
-Cartridge behaviors are engine-tested once (`packages/shell/src/cartridge/runtime.test.ts`); the game test is one call plus any game-specific assertions:
-
-```ts
-import { bootCartridge, cartridgeSmokeTest, tickCartridge } from "@jgengine/shell/cartridge/testkit";
-cartridgeSmokeTest(config);   // validate + world summary + headless run/spawn/kill/gem smoke
-```
-
-`bootCartridge`/`tickCartridge` build a headless `GameContext` and drive the loop (auto-choosing drafts) for custom assertions — see `@jgengine/shell/cartridge/testkit`. The testkit imports `bun:test`; import it from test files only.
-
-Barrel surface tokens: createKeyValueStore createUnlocks durabilityFraction isComplete isOverdrawn memorySaveBackend partInSlot pruneToasts policyProjectsViewers projectByVisibleIds projectEntitiesForViewer projectPerUserForViewer visibleEntityIds applyDeltaToSnapshot applySurfaceDeltaToSnapshot boundaryNeighbors catenaryCurve distanceToPolygonEdge footprintObstacles hasValidAdjacency pointInPolygon polygonArea polygonBounds populateNavGridFromEnvironment readScatterPalette readScatterRules revertDeltaFromSnapshot revertSurfaceDeltaFromSnapshot slopeStepCost solveLock solveLockPath