@jgengine/shell 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-world/SKILL.md

@@ -11,8 +11,16 @@ This skill owns runtime spatial behavior: authored-scene consumption, environmen
 
 Search [capabilities.md](capabilities.md) by intent before designing a primitive. Use [api.md](api.md) for exact exports and [reference.md](reference.md) for environment, camera, navigation, physics, audio, and authored-scene recipes.
 
+For a *connected* walkthrough that wires several primitives into a running loop, read the goal-oriented recipes under [recipes/](recipes/) — organized by composition seam (what connects to what), never by genre. Start there before reading a game's source to learn how pieces fit; a hybrid game is just a different composition of the same primitives.
+
+- [recipes/commanding-entities.md](recipes/commanding-entities.md) — select → order → tick → resolve: direct command over a group of entities (the command loop behind squad control, base-defense, herding, autobattle, or a mutating game's real-time phase).
+
 ## Canonical workflows
 
+### Declare the place
+
+A world is the place you play in: substrate + laws, via `world()` from `@jgengine/core/world/place` — `{ id, ground: { mode: flat|round|voxel|board, size, surface?, generator? }, physics? }`. Thin is complete: flat with `Infinity` axes for 3D, `board` for 2D, or omit `world` for pure UI/rules games. Never put seed, sky, or vegetation in a world definition — seeds derive from world id + save/run (`seedForPlace`); sky look and foliage scatter are editor-authored scene content, with the engine default sky when the document has none. `ground.surface` carries matter/feel laws (metal vs slime vs felt) that the same rule systems read — swap the surface, not the rules. See [reference.md](reference.md) for the full shape; `environment()` is the legacy consumption path for editor/preset-written scene data, never the starter.
+
 ### Authored world
 
 1. Load the scene document through the shared authored-scene feature.
@@ -28,8 +36,13 @@ Choose input intent, controller/motor, collision/navigation, and camera as separ
 
 Compose perception, selection, planning/behavior, movement, and lifecycle independently. Inject randomness and scheduling. Use spatial indexes, interest tiers, or bounded candidate sets for scale.
 
+### Fallback-seam diagnostics
+
+Render seams fall back to placeholders when content is unauthored: default green ground (no environment), primitive capsule/box actors (no `entityModels`/`objectModels` mapping), stylized proxy foliage (no scatter `resolveItem`). These placeholders are sometimes intended, so runtime never changes — but a dev-only, opt-in probe (`@jgengine/core/devtools/fallbackSeams`) tells "unauthored/misconfigured" apart from "intended". The shell arms it via `armFallbackSeams(devtoolsEnabled)`; each seam reports at its choice site (`reportFallbackSeam`), and counts surface through the devtools `fallbacks` probe. Disarmed (production) it is a pure, allocation-free no-op.
+
 ## Traps
 
+- Do not put seed, sky presets, or vegetation/scatter fields in a world definition — `world()` rejects them; dressing belongs to the editor's scene document.
 - Do not put UI layout, touch chrome, combat resolution, or asset acquisition here.
 - Do not duplicate editor coordinates in runtime state.
 - Public APIs accept semantic policies and caller data, not renderer mechanics or internal tuning rolls.