@jgengine/react 0.22.0 → 0.23.0

package/skills/jgengine-ui/capabilities.md

@@ -69,6 +69,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `useAutoScroll` (function) · `import { useAutoScroll } from "@jgengine/react"`
 
+## balance-ibl-lighting — trim flat ambient under IBL and add a key light to directionless lighting
+
+- `balanceLightingForIbl` (function) · `import { balanceLightingForIbl } from "@jgengine/core/render/lightingBalance"`
+
 ## 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"`
@@ -210,6 +214,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `useDragLayer` (function) · `import { useDragLayer } from "@jgengine/react"`
 
+## engine-styles — inject the engine stylesheet (jg-* keyframes, interaction states, reduced motion) once
+
+- `useEngineStyles` (function) · `import { useEngineStyles } from "@jgengine/react/engineStyles"`
+
 ## entity-frames — overlay that renders caller-composed frames over on-screen entities
 
 - `EntityFrames` (function) · `import { EntityFrames } from "@jgengine/react"`
@@ -266,6 +274,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `displaceHeightfieldGeometry` (function) · `import { displaceHeightfieldGeometry } from "@jgengine/shell/terrain"`
 
+## hud-button — themed button with hover lift, press scale, focus ring, disabled state, and an interaction cue seam
+
+- `HudButton` (const) · `import { HudButton } from "@jgengine/react/hudButton"`
+
 ## hud-canvas — the HUD root surface — design-resolution scaling plus live panel-placement editing (F2+C)
 
 - `HudCanvas` (function) · `import { HudCanvas } from "@jgengine/react"`
@@ -290,6 +302,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `IconSchool` (type) · `import { IconSchool } from "@jgengine/react"`
 
+## hud-interact — one listener for hover/press/activate/open/close from every engine HUD primitive
+
+- `HudInteractProvider` (function) · `import { HudInteractProvider } from "@jgengine/react/hudInteract"`
+
 ## hud-layout — persistent, live-editable HUD panel layout state for `HudCanvas`
 
 - `useHudLayout` (function) · `import { useHudLayout } from "@jgengine/react"`
@@ -326,10 +342,18 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `deriveHudTheme` (function) · `import { deriveHudTheme } from "@jgengine/react"`
 
+## hud-theme-root — apply the default (or a game) HudTheme and the engine stylesheet at the HUD root
+
+- `HudThemeRoot` (function) · `import { HudThemeRoot } from "@jgengine/react/hudThemeRoot"`
+
 ## hud-ticker — re-render a HUD element at a steady hz for time-derived readouts (cooldowns, cast/swing bars) — no hand-rolled setInterval effects
 
 - `useTicker` (function) · `import { useTicker } from "@jgengine/react"`
 
+## hud-tokens — inline-style accessors for the HudTheme type scale, spacing, motion, elevation, and focus ring
+
+- `HudTypeStep` (type) · `import { HudTypeStep } from "@jgengine/react/hudTokens"`
+
 ## hud-vitals — atomic purpose-named vitals bars (token-themed parts, not a finished HUD)
 
 - `BarTokens` (interface) · `import { BarTokens } from "@jgengine/react"`
@@ -414,6 +438,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `menuStackReducer` (function) · `import { menuStackReducer } from "@jgengine/react/menuRouter"`
 
+## merge-post-processing — layer a partial post chain over a look preset without losing its stages
+
+- `mergePostProcessing` (function) · `import { mergePostProcessing } from "@jgengine/core/render/lookPreset"`
+
 ## minimap — framed circular minimap with terrain bake, fog, markers, and facing arrow
 
 - `Minimap` (function) · `import { Minimap } from "@jgengine/react"`
@@ -456,6 +484,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `modelLoadIdleMs` (function) · `import { modelLoadIdleMs } from "@jgengine/shell/render/modelLoad"`
 
+## model-load-starts — count of model streaming bursts, for capture quiescence checks
+
+- `modelLoadStarts` (function) · `import { modelLoadStarts } 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"`
@@ -464,6 +496,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `WorldNameplates` (function) · `import { WorldNameplates } from "@jgengine/shell/world/WorldHud"`
 
+## notice-feed — render ctx.game.notices as an animated toned stack (enter/exit motion, ×N stacking)
+
+- `NoticeStack` (function) · `import { NoticeStack } from "@jgengine/react/notices"`
+
 ## notification-bell — icon button with a live unread-count badge over a notification store
 
 - `NotificationBell` (function) · `import { NotificationBell } from "@jgengine/react"`
@@ -553,6 +589,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `Popover` (function) · `import { Popover } from "@jgengine/react"`
 
+## presence — keep a closing element mounted through its exit transition
+
+- `usePresence` (function) · `import { usePresence } from "@jgengine/react/presence"`
+
 ## 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"`
@@ -698,6 +738,18 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `TransformGizmo` (const) · `import { TransformGizmo } from "@jgengine/shell/structures"`
 
+## tween-number — rolling number readout with an up/down delta flash
+
+- `TweenNumber` (function) · `import { TweenNumber } from "@jgengine/react/tweenNumber"`
+
+## tweened-value — animate a displayed number toward its target, honouring reduced motion
+
+- `useTweenedValue` (function) · `import { useTweenedValue } from "@jgengine/react/tweenNumber"`
+
+## ui-sound-cues — play click/hover/open/close/confirm/deny/notify UI sounds from any component
+
+- `useUiCue` (function) · `import { useUiCue } from "@jgengine/react/uiCues"`
+
 ## use-camera-shake — React hook binding a camera-shake controller — subscribes for live trauma/kind and can self-drive its decay on a frame loop
 
 - `useCameraShake` (function) · `import { useCameraShake } from "@jgengine/react"`

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

@@ -70,7 +70,7 @@ instead of mirroring external entities into `createMarkerSet`.
 
 **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.
+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. Windows without a `variation` render on `HudPanel` (theme frame plus modal elevation) and rise in on open; `PanelHost` keeps a closed window mounted for its short exit transition, and closing retires any drag in progress. `ModalHost` fades its backdrop and lifts the dialog in, and plays the same exit when the stack empties; `ConfirmDialog` and `PauseMenu` are built from `HudPanel` and `HudButton`.
 
 **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.
 
@@ -80,21 +80,21 @@ Do not create a primitive whose only value is wrapping a `div` with border radiu
 
 ## 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.
+**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` wins, and a styled preset's post stages deep-merge under a partial `postProcessing` (`mergePostProcessing`): fields you set, including `false`, win; stages you omit come from the preset. Under `"neutral"` your chain is used as authored. `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.
+- `ao: { radius, intensity, distanceFalloff, blend }` — ground-truth ambient occlusion. Omitted runs `DEFAULT_AO` on tiers whose `postStages.ao` is on (medium and up; low skips it); `ao: false` turns it off everywhere. It adds a normal/depth prepass (one extra draw per opaque mesh) and is fill-heavy: 8 samples on medium, 12 on high, 16 on ultra.
 - `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.
+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` and `shadowRadius` (PCF penumbra in texels, default 1.25; the shell uses `PCFShadowMap` — in three r182 `PCFSoftShadowMap` silently compiles as unfiltered basic shadows). Every look but `"flat"` adds image-based light from a procedural sky probe (sky/horizon/ground from `hemisphere`, an HDR sun lobe from the first directional light, horizon leaning toward the ambient colour, intensity 0.45); `environmentSource` swaps in an HDRI or cube map. Under that IBL, `ambient` intensity is scaled by `iblAmbientScale` (default 0.5; set 1 to keep it), and lighting with no `directional` entry gets a soft shadowless key tinted by the ambient colour unless `fallbackKey: false` (`balanceLightingForIbl` in `@jgengine/core/render/lightingBalance`). 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)