@jgengine/shell 0.19.0 → 0.22.0

package/skills/jgengine-ui/capabilities.md

@@ -44,14 +44,43 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `ActionTooltip` (function) · `import { ActionTooltip } from "@jgengine/react"`
 
+## animation-motion-params — read resolved player movement into reusable animation graph parameters
+
+- `readModelAnimationParams` (function) · `import { readModelAnimationParams } from "@jgengine/shell/render/useModelAnimation"`
+
+## authored-flocks — render authored habitat agents through caller-selected animated species models with velocity orientation and bounded model lifetime
+
+- `AuthoredFlocks` (function) · `import { AuthoredFlocks } from "@jgengine/shell/world/AuthoredFlocks"`
+
 ## authored-solids — collision for studio-authored world content such as city volumes
 
 - `AuthoredSolids` (function) · `import { AuthoredSolids } from "@jgengine/shell/scene"`
 
+## authored-surface-material — mount an owned PBR surface material on a mesh
+
+- `AuthoredSurfaceMaterial` (function) · `import { AuthoredSurfaceMaterial } from "@jgengine/shell/render/authoredSurfaceMaterial"`
+- `useAuthoredSurfaceMaterial` (function) · `import { useAuthoredSurfaceMaterial } from "@jgengine/shell/render/authoredSurfaceMaterial"`
+
+## authored-weather-rendering — Render authored weather from shared gameplay samples, simulation time and shelter volumes.
+
+- `AuthoredWeatherLayer` (function) · `import { AuthoredWeatherLayer } from "@jgengine/shell/weather"`
+
 ## auto-scroll — pin a log/chat/console panel to its newest line as entries arrive — no hand-rolled scrollTop effects
 
 - `useAutoScroll` (function) · `import { useAutoScroll } from "@jgengine/react"`
 
+## bounded-spatial-audio — play positional or flat cues with listener orientation, voice budgets, and per-source cleanup
+
+- `createAudioEngine` (function) · `import { createAudioEngine } from "@jgengine/shell/audio/audioEngine"`
+
+## browser-suspension — observe blur, hidden-page and pointer-lock loss while the game owns pause and input policy
+
+- `useBrowserSuspension` (function) · `import { useBrowserSuspension } from "@jgengine/react"`
+
+## browser-suspension-observer — observe browser interruptions outside React with caller-owned pause policy and event sources
+
+- `observeBrowserSuspension` (function) · `import { observeBrowserSuspension } from "@jgengine/react"`
+
 ## camera-shake-meter — HUD readout for a core camera-shake controller — a trauma meter plus current impact-kind label, reskinnable and kind-labelled
 
 - `CameraShakeMeter` (function) · `import { CameraShakeMeter } from "@jgengine/react"`
@@ -76,6 +105,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `StatList` (function) · `import { StatList } from "@jgengine/react"`
 
+## chase-heading — keep camera-relative input heading independent of body facing while retaining vehicle and seat camera follow
+
+- `resolveChaseHeading` (function) · `import { resolveChaseHeading } from "@jgengine/shell/camera/chaseHeading"`
+
 ## clock-format — format a signed time gap like a race split (+/- m:ss.ff)
 
 - `formatDelta` (function) · `import { formatDelta } from "@jgengine/core/ui"`
@@ -125,6 +158,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `useTarget` (function) · `import { useTarget } from "@jgengine/react"`
 
+## custom-viewmodel-muzzle — align tracer origins with a custom viewmodel's live muzzle without changing authoritative shots
+
+- `registerFirstPersonMuzzle` (function) · `import { registerFirstPersonMuzzle } from "@jgengine/shell/camera"`
+
 ## cutscene-letterbox — reskinnable cinematic letterbox + skip overlay for a cutscene — animated bars, caption/dialogue slot, progress line, Skip button
 
 - `CutsceneLetterbox` (function) · `import { CutsceneLetterbox } from "@jgengine/react"`
@@ -149,6 +186,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `DEFAULT_WALK_CODES` (const) · `import { DEFAULT_WALK_CODES } from "@jgengine/shell/shellMovement"`
 
+## dialog-behavior — controlled dialog focus and keyboard behavior without owning markup or screen state
+
+- `useDialogBehavior` (function) · `import { useDialogBehavior } from "@jgengine/react"`
+
 ## dialogue-view — drop-in branching conversation UI — speaker + portrait slot, current line, clickable response choices that advance a DialogueRun
 
 - `DialogueView` (function) · `import { DialogueView } from "@jgengine/react"`
@@ -165,6 +206,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `useDomEvent` (function) · `import { useDomEvent } from "@jgengine/react"`
 
+## drag-layer — composable pointer-owned drag, drop targets and cancellation for custom cards and inventory UI
+
+- `useDragLayer` (function) · `import { useDragLayer } from "@jgengine/react"`
+
 ## entity-frames — overlay that renders caller-composed frames over on-screen entities
 
 - `EntityFrames` (function) · `import { EntityFrames } from "@jgengine/react"`
@@ -294,6 +339,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createI18n` (function) · `import { createI18n } from "@jgengine/core/ui"`
 
+## imported-rig-node — resolve original imported bone and slot names with ambiguity diagnostics
+
+- `resolveRigNode` (function) · `import { resolveRigNode } from "@jgengine/shell/render/rigNode"`
+
 ## interaction-prompt-host — screen-anchored "press E to…" callout rendering a prompt registry's active interactable — keybind cap+label, gauge hold bar, or plain label, theme- and per-prompt-accent skinnable
 
 - `InteractionPrompt` (function) · `import { InteractionPrompt } from "@jgengine/react"`
@@ -326,6 +375,37 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `MapLegend` (function) · `import { MapLegend } from "@jgengine/react"`
 
+## material-appearance-signals — update one owned material from wetness and local card exposure without global lighting edits
+
+- `applyMaterialAppearanceSignals` (function) · `import { applyMaterialAppearanceSignals } from "@jgengine/shell/render/materialAppearanceSignals"`
+- `captureMaterialAppearanceBaseline` (function) · `import { captureMaterialAppearanceBaseline } from "@jgengine/shell/render/materialAppearanceSignals"`
+- `restoreMaterialAppearanceBaseline` (function) · `import { restoreMaterialAppearanceBaseline } from "@jgengine/shell/render/materialAppearanceSignals"`
+- `setHairCardLightExposure` (function) · `import { setHairCardLightExposure } from "@jgengine/shell/render/materialAsset"`
+
+## material-assets — render authored physical surfaces, woven detail and approximate hair-card appearance
+
+- `MaterialAssetSurface` (function) · `import { MaterialAssetSurface } from "@jgengine/shell/render/materialAsset"`
+- `applyMaterialAsset` (function) · `import { applyMaterialAsset } from "@jgengine/shell/render/materialAsset"`
+- `applyMaterialAssignments` (function) · `import { applyMaterialAssignments } from "@jgengine/shell/render/materialAsset"`
+- `materialAssetSurface` (function) · `import { materialAssetSurface } from "@jgengine/shell/render/materialAsset"`
+- `useMaterialAssetMaterial` (function) · `import { useMaterialAssetMaterial } from "@jgengine/shell/render/materialAsset"`
+
+## material-resource-metrics — inspect loaded texture byte bounds and physical, coverage and transmission participation
+
+- `materialResourceMetrics` (function) · `import { materialResourceMetrics } from "@jgengine/shell/render/materialAsset"`
+
+## material-slot-selection — preflight native model assignments without allocating or changing imported resources
+
+- `validateMaterialAssignmentTargets` (function) · `import { validateMaterialAssignmentTargets } from "@jgengine/shell/render/materialAsset"`
+
+## material-slots — discover exact imported mesh and material selectors with UV and tangent prerequisites
+
+- `inspectModelMaterialSlots` (function) · `import { inspectModelMaterialSlots } from "@jgengine/shell/render/materialAsset"`
+
+## material-texture-metadata — configure owned map views with semantic color space, packed channels, UV transforms and sampling
+
+- `configureMaterialTexture` (function) · `import { configureMaterialTexture } from "@jgengine/shell/render/materialAsset"`
+
 ## menu-router — screen stack for a game front-end — push/back/replace/reset with optional Escape-to-back
 
 - `useMenuRouter` (function) · `import { useMenuRouter } from "@jgengine/react/menuRouter"`
@@ -358,14 +438,28 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createModalStack` (function) · `import { createModalStack } from "@jgengine/core/ui"`
 
+## model-animation-diagnostics — inspect imported clip mappings, layer masks and root-track compatibility
+
+- `diagnoseModelAnimation` (function) · `import { diagnoseModelAnimation } from "@jgengine/shell/render/useModelAnimation"`
+
 ## model-fallbacks — models the loader replaced with a placeholder, for capture and smoke assertions
 
 - `modelLoadFallbacks` (function) · `import { modelLoadFallbacks } from "@jgengine/shell/render/modelLoad"`
 
+## model-instance — clone a loaded model for independent styling and animation
+
+- `cloneModelScene` (function) · `import { cloneModelScene } from "@jgengine/shell/render/modelRender"`
+- `disposeModelScene` (function) · `import { disposeModelScene } from "@jgengine/shell/render/modelRender"`
+- `useModelInstance` (function) · `import { useModelInstance } from "@jgengine/shell/render/useModelInstance"`
+
 ## model-load-idle — how long the shared GLB loader has been idle, for capture settle waits
 
 - `modelLoadIdleMs` (function) · `import { modelLoadIdleMs } from "@jgengine/shell/render/modelLoad"`
 
+## multiplayer-p2p — bootstrap a playable authoritative world for browser peer co-op
+
+- `resolvePeerShellMultiplayer` (function) · `import { resolvePeerShellMultiplayer } from "@jgengine/shell/multiplayer"`
+
 ## nameplates — billboarded name + HP bar over nearby entities
 
 - `WorldNameplates` (function) · `import { WorldNameplates } from "@jgengine/shell/world/WorldHud"`
@@ -435,7 +529,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `togglePanel` (function) · `import { togglePanel } from "@jgengine/core/ui"`
 
-## particle-field — render a core particle system as a soft-point GPU cloud with per-particle size, color, and alpha
+## particle-field — render a core particle pool as soft points, velocity streaks, connected ribbons, flakes, flames, smoke sprites, or ground ripples
 
 - `ParticleField` (function) · `import { ParticleField } from "@jgengine/shell/vfx/ParticleField"`
 
@@ -459,6 +553,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `Popover` (function) · `import { Popover } from "@jgengine/react"`
 
+## projected-overdraw — sample actual mesh/camera fragment overlap with native coverage and explicit depth/blending/transmission limits
+
+- `measureProjectedOverdraw` (function) · `import { measureProjectedOverdraw } from "@jgengine/shell/render/projectedOverdraw"`
+
+## projectile-models — render authoritative projectile flights with caller models or opt-in shaft/head geometry, velocity orientation, bounded instances, and settlement cleanup
+
+- `ProjectileModels` (function) · `import { ProjectileModels } from "@jgengine/shell/combat/ProjectileModels"`
+
 ## quest-tracker — compact quest/objective HUD tracker — titles + labelled objective progress from describeTrackedQuest views
 
 - `QuestTracker` (function) · `import { QuestTracker } from "@jgengine/react"`
@@ -479,6 +581,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `useRafLoop` (function) · `import { useRafLoop } from "@jgengine/react"`
 
+## rain-ground-ripples — Render bounded rain impacts on exposed terrain using the shared precipitation clock.
+
+- `RainImpactField` (function) · `import { RainImpactField } from "@jgengine/shell/weather"`
+
 ## resolve-game-look — expand a look preset into concrete lighting/backdrop/post knobs
 
 - `resolveGameLook` (function) · `import { resolveGameLook } from "@jgengine/core/ui"`
@@ -499,6 +605,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `ScreenEffectsOverlay` (function) · `import { ScreenEffectsOverlay } from "@jgengine/shell/postfx/ScreenEffectsOverlay"`
 
+## scroll-rail — reachable horizontal controls with visible overflow navigation and keyboard focus reveal
+
+- `ScrollRail` (function) · `import { ScrollRail } from "@jgengine/react"`
+
 ## selection-collection — accessible portrait-strip / group-chip renderer over a selection model
 
 - `SelectionCollectionChrome` (function) · `import { SelectionCollectionChrome } from "@jgengine/react"`
@@ -544,6 +654,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `StartScreen` (function) · `import { StartScreen } from "@jgengine/react"`
 
+## static-shape-instances — render authored primitive transforms as static material-compatible instance batches
+
+- `StaticShapeInstances` (function) · `import { StaticShapeInstances } from "@jgengine/shell/render/staticShapeInstances"`
+
 ## status-effect-bar — timeline HUD row of active statuses — icon + radial countdown ring + stack badge, driven off the status model, HudTheme-skinned
 
 - `StatusEffectBar` (function) · `import { StatusEffectBar } from "@jgengine/react"`
@@ -556,6 +670,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `TalentTree` (function) · `import { TalentTree } from "@jgengine/react"`
 
+## terrain-paint-color — sample authored terrain surfaces and blended layers for shared ground rendering
+
+- `createTerrainPaintColorSampler` (function) · `import { createTerrainPaintColorSampler } from "@jgengine/shell/terrain"`
+
 ## territory-overlay — show footprint ownership, claim cost, and affordability
 
 - `TerritoryOverlay` (function) · `import { TerritoryOverlay } from "@jgengine/shell/TerritoryOverlay"`

package/skills/jgengine-ui/reference-primitives.md

@@ -2,6 +2,26 @@
 
 On-demand detail behind [reference.md](reference.md) §6. Search [capabilities.md](capabilities.md) by intent first; open this file when you need how a shipped block composes.
 
+## Browser interruptions
+
+`useBrowserSuspension(onSuspend, { blur, hidden, pointerLockLost })` from
+`@jgengine/react/browserLifecycle` observes all three triggers by default and
+calls the latest callback with `"blur"`, `"hidden"`, or `"pointer-lock-lost"`.
+Pointer lock acquisition and visible-page events do not notify. Mounting while
+unlocked or hidden does not notify either. The game owns its pause guards,
+modal handling, input reset and multiplayer policy; this hook never changes
+simulation state. `observeBrowserSuspension` offers the same behavior outside
+React and returns listener cleanup; its optional sources support iframe windows
+and isolated tests.
+
+**Voice transmission state.** `useVoice` (`@jgengine/react/voice`) reads its mode, mute, status and transmission from the push-to-talk controller. Initial `mode: "openMic"` enables transmission on the first render; granted audio tracks adopt the current mode and mute state before publication, including changes made while capture is pending. Transport readiness preserves explicitly enabled hold/toggle sessions. Use `setMode` and `setMuted` for policy changes; microphone permission and transport stay caller-owned.
+
+**Microphone lifetime.** `requestMic()` returns `false` for requests retired by unmount, a later request, or channel/transport replacement. Their returned tracks stop without publication or stale error updates. Successful replacement stops the previous capture; a current permission denial leaves an already accepted capture available. Accepted capture survives transport replacement and joins the replacement channel with its current stream id. Retained callbacks from a retired channel/transport cannot start capture; a grant without live audio is rejected. Current publication errors return `false` and populate `micError` while retaining accepted capture for retry; retired publication results cannot update the current owner.
+
+**Keyboard ownership.** The shell leaves prevented key events and focused text, dialog, grid, gridcell, and toolbar controls to the HUD, clearing held gameplay input at that boundary. Custom keyboard widgets call `preventDefault()` for the keys they handle. Opening a window does not pause simulation or change pointer lock; keep those policies in the game and use `suspendPlayControls(ctx)` when the window should suspend player controls.
+
+**Push-to-talk ownership.** `PushToTalkButton` (`@jgengine/react/voice`) owns one primary pointer or focused Enter/Space activation. Matching release, cancellation, capture loss, browser suspension and button unmount release its hold; mouse departure and keyboard focus loss also retire their activation. Secondary pointers, auxiliary buttons and key repeats cannot change it. Compose a caller-owned `VoiceState`; toggle/open-mic policy and holds started elsewhere remain caller-owned.
+
 ## 6. Game UI primitives
 
 Prefer small headless or lightly styled primitives over a giant universal design system. Useful concepts include:
@@ -25,6 +45,8 @@ 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.
 
+**Atomic bar fills.** An explicit `fill` prop wins over a bar skin and semantic palette colors. Without it, `HudSkin.bar.fill` wins over the normal or low-health palette token. `hudThemeVars` resets an inherited bar skin when the nested theme has none; `hudSkinVars` alone applies only the supplied skin fields and preserves inheritance for the rest.
+
 **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
@@ -32,7 +54,9 @@ 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`. When the game does **not** run the JGengine entity store — it owns enemies in its own array/ECS/store — reach for the data-first **entity-frame** seam instead of `WorldNameplates`: `EntityFrames` (`@jgengine/react/entityFrames`, `entity-frames` capability) takes a caller-owned `{ id, worldPosition, ... }[]` plus a `project` (world→screen) and a `renderFrame` that composes the shipped `HealthBar` + a name (reskinned via `barTokens`/`HudTheme`); it owns only the reusable behavior — projection offset, off-screen/behind-camera culling, and nearest-on-top stacking (`layoutEntityFrames` is the pure, unit-tested core). An R3F game gets the projector for free from `WorldEntityFrames` / `useWorldProjection` (`@jgengine/shell/world/WorldEntityFrames`), which samples the live camera and composes the react primitive — overhead nameplates/health bars from your own array in a few lines, no store mirroring. Follow [the overhead entity-frames recipe](recipes/overhead-entity-frames.md). **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`.
+**Fullscreen map gestures.** `FullscreenMap` owns one primary pan or drawing pointer. Cancellation, touch capture loss, closing, tool changes and unmount discard unfinished gestures and route drafts. Mouse release outside the viewport also retires ownership; auxiliary buttons do not finish a primary drag. Custom overlay controls, including shadow DOM controls, keep their native input. Compose `onWorldClick` for navigation or `onStrokeComplete` with a caller-owned annotation layer; the game keeps route policy, composition and skin.
+
+**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`. Bars and nameplates respect blocking object, wall, and terrain geometry from the actual render camera by default; use `occlude: false` only for an intentional reveal mechanic. They filter hidden/depleted-health entities and renderer membership, use camera distance, and sample at most 64 nearby candidates with visibility rays per refresh (bars 80ms, plates 120ms); retained bar anchors reproject every frame without additional queries or rays. Both declarative configs and direct components expose `maxSamples` (capped at 256) and `tickMs`. Nameplates retain human names but suppress id-equal, lowercase machine names and names containing `_`, `:`, or `/`; supply `nameplates.resolveName(entity)` for authored catalog or player labels, returning `null` to omit a plate. When the game does **not** run the JGengine entity store — it owns enemies in its own array/ECS/store — reach for the data-first **entity-frame** seam instead of `WorldNameplates`: `EntityFrames` (`@jgengine/react/entityFrames`, `entity-frames` capability) takes a caller-owned `{ id, worldPosition, ... }[]` plus a `project` (world→screen) and a `renderFrame` that composes the shipped `HealthBar` + a name (reskinned via `barTokens`/`HudTheme`); it owns only the reusable behavior — projection offset, off-screen/behind-camera culling, and nearest-on-top stacking (`layoutEntityFrames` is the pure, unit-tested core). An R3F game gets the projector for free from `WorldEntityFrames` / `useWorldProjection` (`@jgengine/shell/world/WorldEntityFrames`), which samples the live camera and composes the react primitive — overhead nameplates/health bars from your own array in a few lines, no store mirroring. Follow [the overhead entity-frames recipe](recipes/overhead-entity-frames.md). **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"|"themed" 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, `themed` driven by the `--jg-frame-*` `HudTheme` tokens (the token-skinning path SKILL.md promotes). 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`.
 
@@ -42,8 +66,12 @@ instead of mirroring external entities into `createMarkerSet`.
 
 **Inventory grid** is already shipped, not hand-rolled: `<InventoryGrid inventoryId columns>` (`@jgengine/react`, backed by the `useInventoryGrid` hook) is a drop-in NxN grid bound to a live inventory — it renders the bound inventory's slots and wires drag-to-move / swap / stack / split through the built-in `inventory.move` / `inventory.split` commands, so a bag is one element plus a reskin, never a re-derived slot matrix over raw divs. It is distinct from the atomic `EquipmentSlots` / `WeaponSlots`, which are single-slot targets for paperdoll and equip layouts — reach for `InventoryGrid` for the bag/backpack surface and the atomic slots for the worn/equipped layout. Reskin via `className`/`data-*` slots and HudTheme tokens; the mechanics stay caller-agnostic.
 
+**Drag ownership.** `useDragLayer` (`@jgengine/react/dragLayer`) owns one primary pointer until release or cancellation. Compose `DraggableCard`, `DropZone`, and `DragGhost`; registered zones resolve from the pointer position even under touch capture. Releasing outside finishes with a null target; cancellation, Escape, blur, lost capture, and source or owner unmount release listeners without invoking drop policy. A removed zone cannot receive a stale drop. The layer releases ownership before calling `onDrop`; games retain their move, discard, rotation, and stack rules. Cards own the touch gesture, while inventory keyboard move and split controls remain available.
+
 **Toggleable game windows** are already shipped, not hand-rolled open/close state: `usePanels(defs)` + `<PanelHost>` + `<Window>` (`@jgengine/react`) over the headless `@jgengine/core/ui/panelModel` are THE way to build openable windows — bag (`B`), character (`C`), spellbook, quest log — with keybind toggles, drag-to-move, close buttons, ESC-to-close, and z-stack ordering all handled. Declare each window in `defs` (id, keybind, title), mount one `<PanelHost>`, and render each panel's body inside a `<Window>`; the game owns the body content and skin, the model owns focus/stacking/keybind wiring. Never re-derive window toggling from local `useState` booleans and hand-rolled keydown listeners.
 
+Window title-bar movement belongs to one primary pointer. Release, cancellation, capture loss, blur, and window unmount retire that gesture's listeners; another pointer cannot move it. Controlled positions and panel z-order remain caller-owned.
+
 **Character sheet / paperdoll** is already shipped, not hand-rolled: `<CharacterSheet>` / `<Paperdoll>` / `<StatList>` (`@jgengine/react`) compose the paperdoll equip layout (worn `EquipmentSlots` arranged around a portrait) and the derived-stat readout into one window body. `Paperdoll` is the equip-slot arrangement, `StatList` the derived-stat rows, `CharacterSheet` the batteries-included default that pairs them — the game composes and reskins them (slot layout, stat labels/terminology, skin) rather than re-deriving a paperdoll from raw divs and manual stat math.
 
 **Toast/announcer stacks**: two supported sources, pick the one that matches where the message comes from. An engine event already bound onto `ctx.game.feed` (kill feed, loot log, quest update) renders with `@jgengine/react`'s `ToastStack({ action })` directly. A game-raised one-off message with its own lifetime (boss-intro banner, objective callout) belongs in a `createToastQueue` (`@jgengine/core/game/toasts`, `toast-feed` capability — see `jgengine-gameplay`) rendered from `queue.list()`; don't reimplement the append-cap-plus-TTL-prune loop as a local `Toast`/`pushToast` pair.
@@ -62,6 +90,8 @@ The post chain itself is never hand-wired render passes. Set `defineGame({ postP
 - `ao: { radius, intensity, distanceFalloff, blend }` — ground-truth ambient occlusion; heavier than the rest, omit or `false` on low-end targets.
 - `stylize: { outline, bands, pixelSize }` — art style without touching materials. `outline: { color, thickness, opacity, depthThreshold, normalThreshold, fadeDistance }` traces ink lines from depth and normal edges (one extra normal/depth scene render, shadow maps reused); `bands` quantizes brightness into cel bands keeping hue; `pixelSize` snaps the frame to retro blocks. Mix freely: outline alone is a clean comic ink, `bands: 3` plus outline is cartoon, `pixelSize` plus `bands` is retro. Mark custom overlay effects with `POSTFX_OVERLAY_USERDATA` so they are not outlined; transparent, alpha-cut, points, lines and sprites are skipped automatically.
 
+AO and depth-of-field prepasses reuse the beauty pass's shadow maps; they do not redraw shadow casters. Prepass failure restores shadow update policy and marked overlay visibility. The composer resizes passes through `setSize`, and graph cleanup calls each pass's `dispose` once; avoid reading a pass's internal targets or materials.
+
 **Orbit camera occlusion:** the third-person orbit rig takes `camera: { collision: { enabled, padding?, minTargetDistance? } }` — a spring-arm that raycasts target→camera each frame and pulls the boom in past walls/terrain so the camera never clips inside geometry. Off by default (unchanged chase feel); enable it for any world with interiors or dense structures.
 
 Lighting is `defineGame({ lighting })` (`LightingConfig`): ambient / hemisphere / directional, replacing the shell's default lights when set. A `DirectionalLightingConfig` with `castShadow` takes `shadowMapSize`, `shadowCameraSize`, `shadowBias`, `shadowNormalBias` for crisp contact shadows. Sky-lit worlds (a `sky()` world feature) get a high-res sun whose shadow camera follows the view each frame, so grounded shadows stay sharp under the player anywhere in a large world.
@@ -70,10 +100,50 @@ Lighting is `defineGame({ lighting })` (`LightingConfig`): ambient / hemisphere
 
 Three composable-chrome seams for FPS/TPS polish — a placement hook plus a good default, never a forced look:
 
-- **Custom viewmodel.** `defineGame({ viewmodel })` supplies a component rendered inside the shell's camera-locked, muzzle-tracked anchor in place of the built-in three-mesh gun — read when the active rig is first-person. It receives `ViewmodelProps` (`@jgengine/shell/camera`): `{ cuesRef }`, a live `MutableRefObject<EntityRenderCues>` for the followed entity — read `cuesRef.current` inside your own `useFrame` to drive bob/recoil/reload poses; never store it as render state (it updates every frame). `camera.firstPerson.viewmodel: false` renders no viewmodel at all regardless of `defineGame`'s `viewmodel` field — the explicit opt-out always wins. `readFirstPersonMuzzle(target: THREE.Vector3)` (also `@jgengine/shell/camera`) writes the live muzzle world position into `target` and returns `false` when no viewmodel is mounted — the seam for muzzle-flash lights, tracer origins, or shell casings.
+- **Custom viewmodel.** `defineGame({ viewmodel })` supplies a component rendered inside the shell's camera-locked, muzzle-tracked anchor in place of the built-in three-mesh gun — read when the active rig is first-person. It receives `ViewmodelProps` (`@jgengine/shell/camera`): `{ cuesRef }`, a live `MutableRefObject<EntityRenderCues>` for the followed entity — read `cuesRef.current` inside your own `useFrame` to drive bob/recoil/reload poses; never store it as render state (it updates every frame). `camera.firstPerson.viewmodel: false` renders no viewmodel at all regardless of `defineGame`'s `viewmodel` field — the explicit opt-out always wins. `readFirstPersonMuzzle(target: THREE.Vector3, camera?: THREE.Camera)` (also `@jgengine/shell/camera`) writes the live presentation muzzle world position into `target`; pass the active Three.js camera to isolate canvases. It returns `false` without changing `target` when no muzzle is available — the seam for muzzle-flash lights, tracer origins, or shell casings.
 - **Weapon pose.** `camera.weapon: (entityId) => { handling, presentation } | null` hands the rigs the held weapon's `createWeaponHandling` frame and a `WeaponPresentationTuning` (`@jgengine/core/combat/weaponPresentation`). First person poses the viewmodel anchor from it (hip and ADS offsets, viewmodel FOV, `adsZoom`, sway from look speed, bob from `cuesRef`, recoil kick) and adds the recoil to the look; `shoulder` takes its ADS blend from `adsProgress` and adds the same recoil. A custom `viewmodel` rides the posed anchor. `bun run drive weapon-handling` (and `weapon-handling-shoulder`) is the dev demo.
-- **`WorldOverlay` receives `{ ctx }`.** `defineGame({ WorldOverlay })` components take `WorldOverlayProps` (`@jgengine/core/game/playableGame`) — `ctx: GameContext` handed directly, no extra hook or module-global workaround needed to reach engine state from canvas-layer VFX.
+- **`WorldOverlay` receives `{ ctx }`.** `defineGame({ WorldOverlay })` components take `WorldOverlayProps` (`@jgengine/core/game/playableGame`) — `ctx: GameContext` handed directly, no extra hook or module-global workaround needed to reach engine state from canvas-layer VFX. Shared bars/nameplates mounted there inherit the renderer's visibility context; both omit the local account and its currently possessed body. Occlusion still uses the render camera and the authored overlay anchor, with `occlude: false` as an explicit through-wall reveal. Custom geometry retains the overlay's camera-transparent policy.
 - **Render cues for any custom rig.** `useEntityRenderCues(instanceId, tuning?)` (`@jgengine/shell/render/useEntityRenderCues`) returns the same `cuesRef` the viewmodel gets, for a custom `renderEntity` component: velocity-driven `bobPhase`, `firing`/`recoil` from `ctx.game.playEntityAnimation(instanceId, "fire")`, `reloading` from `"reload"`/`"reloadEnd"`, `hit` from `combat.hitReaction`, `dead` from `entity.died` — no diffing the parent group's position, no game-side module map for attack timing. `RenderCueTuning` (`@jgengine/core/combat/renderCues`) overrides the bob rate / recoil decay / pulse durations; see `jgengine-combat`'s `combat/renderCues` for the underlying pure math.
+A custom `WorldOverlay` rig can keep `camera.firstPerson.viewmodel: false` and
+register its own live muzzle for the shell's tracer presentation:
+
+```tsx
+import { useEffect, useRef } from "react";
+import { useThree } from "@react-three/fiber";
+import type { Object3D } from "three";
+import { registerFirstPersonMuzzle } from "@jgengine/shell/camera";
+
+function CustomRig() {
+  const camera = useThree((state) => state.camera);
+  const muzzle = useRef<Object3D>(null);
+  useEffect(() => registerFirstPersonMuzzle(camera, (target) => {
+    const tip = muzzle.current;
+    if (tip === null) return false;
+    tip.getWorldPosition(target);
+    return true;
+  }), [camera]);
+  return <group>{/* game-owned animated weapon geometry */}<object3D ref={muzzle} /></group>;
+}
+```
+
+Place the marker at the game's actual barrel tip and move it with the custom
+rig's recoil, aim, bob, reload, and equipment poses. Returning the registration's
+cleanup from the effect releases only that owner, including StrictMode remounts.
+The newest available custom reader wins over that camera's tracked stock muzzle;
+return `false` when unequipped or unavailable. A failed/invalid read preserves
+the caller's fallback origin. Registrations are limited to 64 per camera per
+priority; legacy one-argument reads consider the newest 64 globally per priority.
+Callbacks run on demand over a snapshot of at most 64 readers per priority.
+Disposed readers are skipped before their callback starts; newly registered
+readers join the next read. Callbacks must write finite world coordinates and should not throw.
+
+This is presentation only: projectile prediction, collision, authority, and
+`projectile.settled.origin` remain simulation-owned. Scrap Signal's
+`FerralonViewmodel` is the concrete adopter: its `flash` marker already shares
+`muzzleOffsetZ(gun.family)` with the actual barrel geometry. Its game-side
+registration waits for the coordinator's verified published SDK release; no
+source aliases or native verification of unpublished APIs are implied.
+
 `@jgengine/shell/terrain`'s `ProceduralGround`/`CarvedTerrain`/`GrassField` are the game-facing terrain surface; the height-field math underneath (`arenaField`, `flatField`, `fractalNoise`, `resolveGroundStep`, `valueNoise`, `withNormal`, re-exported from `@jgengine/core/world/terrain`) and `GamePlayerShell`'s physics helpers (`applyMotionImpulses`, `nearbyObstacles`, `resolvePhysicsTuning`, `hasEnvironmentTerrain`, sourced from `core/runtime/motionIntents` / `core/movement`) are internal building blocks the shell composes for you — reach for `defineGame({ movement, world })` and the ground primitives above instead of calling these directly.
 
 ## 15. Compact implementation API appendix
@@ -87,3 +157,23 @@ The shipped building blocks — inventory grids, toggleable windows, character s
 ## 2D sprite presentation
 
 Core owns renderer-independent atlas data and animation state. Convert Aseprite or TexturePacker JSON with `fromAseprite` / `fromTexturePacker` from `@jgengine/core/assets/spriteAtlas`, then drive a clip with `createSpriteClipPlayer` from `@jgengine/core/render/sprite2d`. Persist `snapshot()` and restore it on load; use `retune({ speed })` for runtime playback changes. Use `sortingOrder(layers, layer, offset)` when a game maps named presentation layers to renderer order.
+
+The shell's `EntitySprite` changes atlas UVs without uploading the image again. Configuration changes request a frame; frozen shell posters keep their demand rendering behavior.
+
+## Model instances
+
+Custom R3F model components use `useModelInstance` (`@jgengine/shell/render/useModelInstance`) inside Canvas and Suspense. Pass the model's URL, placement, shadows and animation; render its returned `scene` with `position` and uniform `scale`. The imported `content` stays inside that placement frame, so imported pivots/transforms and root animation survive normalization. The hook shares the diagnostic loader and bind-pose placement used by `EntityModel`, and releases cloned materials and bone textures on replacement/unmount. It works without a game provider. Placement retuning uses the initially configured bind frame even after root animation has moved the content. Geometry/textures retained by the loader remain shared; resources introduced or replaced by `configure` stay caller-owned.
+
+Use the optional `configure(content)` callback for initial caller-owned styling or deformation; memoize it, since a changed callback rebuilds the clone. Live mood colors or custom motion can update `content` in caller effects without replacing it. Texture loading, material-map application and extra geometry remain caller-owned; `EntityModel` supplies those for ordinary model configurations. Each clone owns its pose, bone textures and cloned materials, with one skeleton/material per shared source skeleton/material. Geometry and image textures stay in the loader cache. Apply material overrides with `clone: false` to an instance that already owns its materials. Attachments own their separate cleanup.
+
+For non-hook consumers, `cloneModelScene` and `disposeModelScene` (`@jgengine/shell/render/modelRender`) provide the same resource ownership. `cloneMaterials: false` borrows source materials; do not mutate them.
+
+`useModelInstance` already mounts `useModelAnimation`; do not mount a second driver on that instance. Other custom scene owners use `useModelAnimation` (`@jgengine/shell/render/useModelAnimation`) instead of creating a mixer in game code. It releases mixer bindings on replacement/unmount and skips updates for paused or completed single clips. Configuration and animation events request a frame without continuously waking a frozen poster.
+
+`EntityModel` starts resolved part, attachment and material-map requests alongside the root model through the existing loader cache. Loaded maps apply before their next draw, without eagerly uploading an unconfigured color texture. Keep per-part error boundaries; a failed texture or attachment still reports its own fallback.
+
+Cascaded lighting patches streamed meshes on attachment and material replacement instead of scanning the scene each frame. Replacing or unmounting a cascaded light releases its lights, targets, shadow maps and shader bindings while retaining authored material hooks. Authored cascade counts and map sizes keep priority over graphics-profile defaults.
+
+**Scrolling controls.** `ScrollRail` (`@jgengine/react/scrollRail`) wraps caller-owned items with native horizontal scrolling, overflow-only 44px navigation buttons, and automatic focus reveal. Supply `label` for navigation names, prevent items from shrinking, and keep selection and keyboard semantics in the caller. Shared settings rows use it; short sidebar settings remain vertically scrollable. Touch movement sits below the HUD so the floating joystick capture zone cannot intercept an interactive panel; touch action clusters keep their higher layer.
+
+**Controlled dialogs.** `useDialogBehavior({ open, onClose?, initialFocus?, focusKey? })` (`@jgengine/react/dialogBehavior`) returns a ref for the game's own dialog element. It owns initial focus, Tab cycling, Escape close requests, and return focus; it does not create modal state or markup. Set `role="dialog"`, `aria-modal`, an accessible name, and `tabIndex={-1}` on the root. Use `initialFocus: "root"` to focus the dialog itself. Omit `onClose` to disable Escape, or leave `open` true when the game rejects a close. `focusKey` refocuses changed content while keeping the original return target. Replacing an open root preserves its dialog order and original return target; a portalled child whose opener was removed returns to the replacement parent root. Nested dialogs may render through portals; only the most recently opened dialog handles keys. `ModalHost` uses the same behavior for its stack, so game-owned screens need no mirrored `ModalStack`.

package/skills/jgengine-ui/reference.md

@@ -261,6 +261,8 @@ Only show entries the game supports, and disable (don't delete) verbs that are t
 
 **Settings menu (themed, four layouts, no forced chrome).** The engine builds the whole menu for free — Sound (master + per-bus volume), Graphics (Low/Medium/High/Ultra tier, render scale, frame-rate limit (V-Sync or 30/60/120/144 cap), texture filtering, shadows, per-stage post toggles, UI scale, FPS counter), Gameplay (FOV slider, default 40–120), Controls (per-action key rebinding, inline click-to-rebind, persisted) — from the game's `audio.buses` and `input` map. What it does **not** do is bolt a fixed gear onto every game: **there is no auto trigger.** You place the entry yourself so it lives *inline with your game's own UI*, never a stray corner overlay. Drop `<SettingsTrigger className=…>` (from `@jgengine/react`) anywhere in your HUD or menu — headless button, `className` for skin/placement, optional `children` to replace the default gear glyph, renders nothing when there's nothing to show. Or call `useSettings().open()` from your own control. Tune the menu via `defineGame({ settings })` (`GameSettingsConfig` from `@jgengine/core/settings/settingsModel`):
 
+HUD-only games (`presentation: "hud"` or a camera with rig `"none"`) use the same shell-owned settings store, audio volumes, key rebinding, actions, and menu. Pass `settings` directly to the public `defineGame` from `@jgengine/shell/gameKit`; both HUD and 3D presentations receive that configuration. Declare custom rows in `settings.extra` and read them with `useSetting`; saved player values override configured defaults, and no additional settings provider or runtime is needed. HUD-only menus omit the camera FOV slider. Select option buttons expose their selected state through `aria-pressed` in a labelled group. The shell leaves Tab navigation and Space activation to focused HUD controls and dialogs.
+
 - `variant: "panel" | "sheet" | "sidebar" | "fullscreen"` — the layout + skin (default `panel`; `sheet` is the mobile bottom-sheet). All four are fixed-size (no shrink-to-content jitter) and read the game's `--jg-*` theme tokens, falling back to a neutral dark skin.
 - `actions: SettingsActionDef[]` — game-state actions (Restart, Quit to menu, …). They become the **first "Game" tab, shown before anything else** — the home for buttons that used to float over the HUD. Each: `{ id, label, kind?: "default"|"danger", description?, run(ctx) }`; the menu closes right after `run`.
 - `hideBindings: string[]` — input actions to drop from the rebindable Controls list. A game-state key like `restart` belongs in `actions`, not the rebind grid — hide it here so it stops showing up as a "rebindable" control.

package/skills/jgengine-world/SKILL.md

@@ -19,7 +19,7 @@ For a *connected* walkthrough that wires several primitives into a running loop,
 - [recipes/vehicle-feel.md](recipes/vehicle-feel.md) — feel target → handling metrics → physical knobs for a ground vehicle, plus the camera, sound and rumble hooks that hang off its telemetry.
 - [recipes/flight-feel.md](recipes/flight-feel.md) — an aircraft as physical numbers: surfaces, inertia and engine, with the symptom → knob table for how it flies.
 - [recipes/controls.md](recipes/controls.md) — actions → layered contexts that rebind live → keyboard, touch and gamepad on the same actions → per-axis feel.
-- [recipes/character-animation.md](recipes/character-animation.md) — clips → graph → rig → ground: data-driven state machines, triggers and clip events, root motion, foot IK that keeps feet on slopes, and instanced crowds.
+- [recipes/character-animation.md](recipes/character-animation.md) — clips → graph → rig → ground: modular instance visibility, data-driven state machines, triggers and clip events, root motion, foot IK that keeps feet on slopes, and instanced crowds.
 
 ## Canonical workflows
 
@@ -31,15 +31,19 @@ A world is the place you play in: substrate + laws, via `world()` from `@jgengin
 
 1. Load the scene document through the shared authored-scene feature.
 2. Render objects, paths, terrain, foliage, and markers generically.
-3. Query the same ids/layers for spawns, routes, plots, and interaction.
+3. Query the same ids/layers for spawns, routes, plots, and interaction. The shell batches compatible static catalog props above eight placements per 24 m cell, preserving chosen models, material groups, shadows, measured colliders and object ids for picking. Interactive/custom props, per-object visual/style overrides, and animated, rigged, composed, transparent or mirrored models keep individual renderers. Runtime compatibility changes return a placement to its individual renderer. Visibility compacts each batch to the current visible placements.
 4. Collision for generated and studio content comes from its data through `ctx.world.solids`; never hand-place invisible blockers for it (see reference.md, World solids).
 5. Keep derived caches rebuildable; the document remains authoritative.
 
+For existing `environment()` consumers, `defineGame` overlays only defined editor sky fields on the legacy sky, retaining settings the editor cannot represent; an explicit `backdrop.sky` remains authoritative.
+
+For environment-driven surface appearance, sample only selected targets through `material/appearanceSignals`; wetness already includes shelter. Capture the assigned material's dry baseline, apply explicit wet endpoints, and restore it on unbinding. Keep wind in geometry/simulation consumers and local card backlighting separate from scene exposure. See [reference.md](reference.md#environment-fields-weather-hooks--realm-composition).
+
 ### Movement and interaction
 
 Choose input intent, controller/motor, collision/navigation, and camera as separate seams. Commands express game intent; world systems resolve motion. Interaction targets come from bounded spatial/sensor queries, not full-world scans.
 
-Walk feel is data, not code. `movement.feel` sets `groundAcceleration`, `airAcceleration` and `groundFriction` (response rates, 1/s) plus `runMultiplier`, `crouchMultiplier`, jump forgiveness (`jumpBufferMs`, `coyoteMs`) and jump shape (`jumpCutFactor`, `apexGravityScale`, `fallGravityScale`, `landingRecoveryMs`), and `physics` sets `gravity` and `jumpVelocity`. A floaty platformer and a weighty shooter differ only in these numbers; pin them with `measureMovement` (`movement/movementProbe`) in a test.
+Walk feel is data, not code. `movement.feel` sets `groundAcceleration`, `airAcceleration` and `groundFriction` (response rates, 1/s) plus `runMultiplier`, `crouchMultiplier`, jump forgiveness (`jumpBufferMs`, `coyoteMs`) and jump shape (`jumpCutFactor`, `apexGravityScale`, `fallGravityScale`, `landingRecoveryMs`), and `physics` sets `gravity` and `jumpVelocity`. The heightfield and capsule paths share these feel controls; voxel jumping retains its press-frame policy. Crouch follows supported catalog poses, and capsule standing requires headroom. Pin numeric movement behavior with `measureMovement` (`movement/movementProbe`) in a test.
 
 ### Stateful placed objects
 
@@ -49,8 +53,12 @@ Per-instance state belongs on the placement, not in a game-owned map keyed by `i
 
 Compose perception, selection, planning/behavior, movement, and lifecycle independently. Inject randomness and scheduling. Use spatial indexes, interest tiers, or bounded candidate sets for scale.
 
+For chase-to-reach and cooldown effects, attach `pursue({ aggroRadius, reach, leashRange, speed, attack })` as behavior data. The host schedules acquisition and solid-aware movement; `behaviorControl` exposes pause/reset and optional threat. Pursuit progress survives GameContext save/replication without a game-local home/cooldown map. For allies or neutral players, configure `defineGame({ pursuit: { eligible(ctx, selfId, candidateId) { /* bounded caller policy */ } } })`; the predicate receives the current world and constrains nearest, held, explicit and forced targets. Bind the receiving world's policy data before advancing after a cold restore. Omission keeps the all-player default; see the reference for faction composition. Use a decision graph and navigation actions when a route or richer perception policy is required.
+
 NPC decisions are a `decisionGraph` behavior: the graph and its blackboard are data, actions are registered by name, and perception or game systems write facts into `behaviorControl(ctx).blackboard(id)` rather than actions querying the world. Set `thinkInterval` so crowds think a few times a second, not every frame, and release movement or claims in `onAbort`.
 
+For a bounded local detour over movement collision geometry, use `planSolidRoute` (`nav/solidRoute`) with an indexed `solidObstaclesNear` or `sourceObstaclesNear` query. Handle `no-path` and `budget` separately; retain caller movement, goals, terrain and retry policy. See [reference.md](reference.md#local-collision-routes) for limits.
+
 Route on a polygon nav mesh through one `createNavMeshQuery(mesh)` per mesh; price terrain and gate doors with `areaCosts` via `retune`, and keep `maxNodes` bounded so a long request returns a `partial` route instead of stalling a frame.
 
 ### Fallback-seam diagnostics
@@ -64,6 +72,7 @@ Render seams fall back to placeholders when content is unauthored: default green
 - Do not duplicate editor coordinates in runtime state.
 - Public APIs accept semantic policies and caller data, not renderer mechanics or internal tuning rolls.
 - Generated environments still need deterministic data assertions; authored environments need scene-document assertions.
+- Bound SFX through `PlayableGame.audio.maxVoices` and game-owned `SoundDef.priority`/`maxVoices`; choose reject or deterministic stealing with `voiceOverflow`. See the spatial audio reference for custom hosts and cleanup.
 - Audio files and licensing belong to `jgengine-assets`; spatial playback policy belongs here.