@jgengine/shell 0.18.1 → 0.21.0

package/skills/jgengine-ui/capabilities.md

@@ -44,10 +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"`
@@ -72,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"`
@@ -117,6 +154,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `CreditsScreen` (function) · `import { CreditsScreen } from "@jgengine/react/creditsScreen"`
 
+## current-target — read the player's selected target (click or tab target) to drive a target frame
+
+- `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"`
@@ -141,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"`
@@ -157,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"`
@@ -205,6 +258,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `GameContextBridge` (function) · `import { GameContextBridge } from "@jgengine/react"`
 
+## heavy-models — models over the per-model triangle budget, for perf probes and smoke assertions
+
+- `heavyModels` (function) · `import { heavyModels } from "@jgengine/shell/render/modelLoad"`
+
 ## heightfield-mesh-update — in-place partial update of a displaced ground plane mesh
 
 - `displaceHeightfieldGeometry` (function) · `import { displaceHeightfieldGeometry } from "@jgengine/shell/terrain"`
@@ -282,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"`
@@ -314,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"`
@@ -346,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"`
@@ -423,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"`
 
@@ -447,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"`
@@ -467,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"`
@@ -487,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"`
@@ -515,6 +637,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `formatSpeed` (function) · `import { formatSpeed } from "@jgengine/core/ui"`
 
+## split-screen-hud — Per-seat HUD roots positioned over each split-screen viewport.
+
+- `ViewportHuds` (function) · `import { ViewportHuds } from "@jgengine/shell/camera/Viewports"`
+
 ## sprite-2d — animate a sprite atlas clip from headless or rendered game code
 
 - `createSpriteClipPlayer` (function) · `import { createSpriteClipPlayer } from "@jgengine/core/render/sprite2d"`
@@ -528,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"`

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

@@ -0,0 +1,179 @@
+# JGengine UI — primitives and rendering reference
+
+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:
+
+- `HudAnchor`
+- `StatReadout`
+- `Meter`
+- `ObjectiveTracker`
+- `ActionPrompt`
+- `Reticle`
+- `MinimapFrame`
+- `DialoguePlate`
+- `Countdown`
+- `BossBar`
+- `ItemPickup`
+- `DamageIndicator`
+- `PauseScreen`
+- `ResultsScreen`
+- `VirtualControlZone`
+- `ScreenTransition`
+
+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
+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`.
+
+**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`.
+
+**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()`.
+
+**Action cards / command bars / ability bars** are a headless data → renderer → chrome split, not a hand-rolled cooldown grid. The model is caller-owned data: build `ActionDef[]` (`@jgengine/core/ui/actionModel` — `id`, optional `label`/`icon`/`hotkey`/`group`/`active`/`disabled`, plus `cooldown` via `actionCooldown`/`actionCooldownFromFraction` and `costs` via `actionCost`); `resolveAction`/`resolveActionCollection` compute `enabled` + ordered blocking `reasons` (cooldown, then unmet cost, then caller reasons). React side (`@jgengine/react`): `useActionBar(defs, { columns, wrap, hotkeys, onActivate })` is the DATA/HOOK layer (`action-bar-model` — focus, hover, `moveGridFocus` keyboard/controller grid nav, `actionByHotkey` routing); `ActionBarChrome` is the composable RENDERER (`action-bar-chrome` — `role="toolbar"`, roving tabindex, `layout: "grid" | "list"`, swap per-item chrome with `renderItem`); `ActionButton` is the default item chrome (`action-button` — radial cooldown wipe, cost line, `Keycap` hotkey, full rest/hover/focus/pressed/active/disabled states, `aria-disabled`/`aria-pressed`/`aria-keyshortcuts`); `ActionBar` is the batteries-included skinned default. A radial UI ignores the chrome and lays out `ActionButton`s from the model. Bind a combat `AbilityKit` with `actionFromAbilitySlot(slot, { label, icon, hotkey, resourceId })` over `useAbilitySlots`. Tooltips use the shared seam (no more DOM `title=` hand-rolling): `actionTooltip(resolved)` → `TooltipContent`, rendered by `ActionTooltip` inside a `Popover` (`popover` — pure `placePopover` viewport flip/clamp math from `@jgengine/core/ui/tooltipModel`, SSR-safe). **Selection panels / party frames / squad summaries** are the same split for entities: feed caller-owned `EntitySummaryDef[]` (`@jgengine/core/ui/selectionModel` — `id`, `name`, `kind`, `icon`, `vitals`, `tags`) to `summarizeSelection` (primary focus, `kind` buckets, `grouped` past a threshold, `selectionWindow` virtualization) or the `useSelectionView` hook (`selection-model` — focus stepping + keyboard nav). Renderers (`@jgengine/react`): `EntityPortrait` (`entity-portrait` selectable tile + health strip), `EntitySummary` (`entity-summary` primary detail with `VitalBar` rows), `SelectionGroupChip` (`selection-group-chip` icon+count), `SelectionCollectionChrome` (`selection-collection` portrait strip that flips to group chips when large, roving tabindex), and `SelectionPanel` (`selection-panel` batteries-included primary-summary-beside-strip default). Keep layout, dimensions, hotkeys, catalog-id mapping, renderer, and chrome caller-owned — the defaults are examples, not fixed RTS rules; never fork the model to reskin.
+
+**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.
+
+Do not create a primitive whose only value is wrapping a `div` with border radius.
+
+## Rendering — post-processing, lighting, shadows
+
+**Look presets.** Unset `look` is `"neutral"` (#1719): the game's own `lighting`/`backdrop`/`postProcessing` with an AgX tone-map and no styling. One field picks a whole art direction: `"photoreal"` (high-contrast PBR post), `"cinematic"` (day sky, view-following shadow-casting sun, tone-map/bloom/SSAO/vignette), `"toon"` (clean graphic grade), `"comic"` (ink outlines + cel bands + saturated grade — Borderlands-style), `"retro"` (pixelated, posterized, no smoothing), and `"flat"` (bare ambient+directional rig, no post). Non-neutral presets add a day sky unless the world declares one. The preset only fills knobs you didn't set — any explicit `lighting`/`backdrop`/`postProcessing` always wins. `resolveGameLook` (`@jgengine/core/render/lookPreset`) is the pure resolver; assert on it in a `bun test` (the post/sky layers are not visible to `summarizeEnvironment`). HUD-presentation and no-camera games are unaffected.
+
+The post chain itself is never hand-wired render passes. Set `defineGame({ postProcessing })` (`PostProcessingConfig` from `@jgengine/core/render/postProcessing`) and the shell mounts an `EffectComposer` and owns the render: RenderPass → AO → Bloom → tone-map output → Stylize → Grade. Each stage is a config object, `false` to skip, or omitted for its tuned default:
+
+- `toneMapping: "aces" | "agx" | "reinhard" | "cineon" | "linear" | "none"` (default `aces`) + `exposure`.
+- `bloom: { strength, radius, threshold }` — HDR glow around bright pixels (defaults 0.32 / 0.55 / 0.85).
+- `grade: { lift, gain, gamma, saturation, vignette, grain }` — display-space colour grade: cool-shadow/warm-highlight split, vignette, animated film grain.
+- `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.
+
+## First-person viewmodel, WorldOverlay props, render cues (#542)
+
+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, 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. 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
+
+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.
+
+The shipped building blocks — inventory grids, toggleable windows, character sheets, bars — are legitimate to compose and are the right starting point; reach for them instead of re-deriving inventory, windowing, or a paperdoll. But neither they nor the headless seams are finished design on their own: the game must still arrange, place, name, and art-direct them into its own look. Compose the building blocks, then skin and lay them out — don't ship them unarranged.
+
+## 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`.