@jgengine/shell 0.13.0 → 0.15.0-next.0

package/skills/jgengine-ui/capabilities.md

@@ -4,6 +4,22 @@
 
 Reach for these before hand-rolling. Each row is *the thing you need* → *the primitive that already does it*.
 
+## accessibility-provider — apply accessibility preferences to a subtree — text-scale CSS var, reduced-motion/high-contrast/colorblind/captions data attrs, and the colorblind color-matrix filter
+
+- `AccessibilityProvider` (function) · `import { AccessibilityProvider } from "@jgengine/react"`
+
+## accessibility-store — serializable, observable accessibility preferences (reduced motion, high contrast, text scale, colorblind mode, captions) a game binds to its settings and presentation
+
+- `createAccessibilityStore` (function) · `import { createAccessibilityStore } from "@jgengine/core/ui"`
+
+## achievement-gallery — responsive achievement/trophy grid with unlocked/locked state, counter progress bars, secret masking, and a completion/score header
+
+- `AchievementGallery` (function) · `import { AchievementGallery } from "@jgengine/react"`
+
+## achievement-toast — unlock-moment banner (icon, heading, name, points) for an achievement toast queue
+
+- `AchievementToast` (function) · `import { AchievementToast } from "@jgengine/react"`
+
 ## action-bar — optional skinned action-bar composition over the headless model — games own chrome
 
 - `ActionBar` (function) · `import { ActionBar } from "@jgengine/react"`
@@ -28,10 +44,22 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `ActionTooltip` (function) · `import { ActionTooltip } from "@jgengine/react"`
 
+## 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"`
+
+## 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"`
+
 ## camera-transparent-decor — let author decor pass through the orbit spring-arm; a child opts back in with jgCameraCollide
 
 - `isCameraOccluderTransparent` (function) · `import { isCameraOccluderTransparent } from "@jgengine/shell/camera"`
 
+## capture-canvas — read the live R3F frame to a PNG data URL (needs preserveDrawingBuffer)
+
+- `captureCanvas` (function) · `import { captureCanvas } from "@jgengine/shell/render/sceneCapture"`
+
 ## character-paperdoll — equip-slot paperdoll — flanking columns around a portrait, activatable slots
 
 - `Paperdoll` (function) · `import { Paperdoll } from "@jgengine/react"`
@@ -49,22 +77,102 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `formatDelta` (function) · `import { formatDelta } from "@jgengine/core/ui"`
 - `formatDuration` (function) · `import { formatDuration } from "@jgengine/core/ui"`
 
+## coach-mark — single onboarding callout — title/body, N-of-M counter, Next + Skip controls, theme-reskinnable
+
+- `CoachMark` (function) · `import { CoachMark } from "@jgengine/react"`
+
+## coach-mark-host — full-screen onboarding coach-mark host — anchored/centered callout, dimmed spotlight backdrop, Next/Skip wired to the sequence
+
+- `CoachMarkHost` (function) · `import { CoachMarkHost } from "@jgengine/react"`
+
+## coach-marks — ordered, gated, persist-once onboarding coach-marks/tutorial callouts — anchored or centered steps with a seen set and Next/Skip
+
+- `createCoachMarkSequence` (function) · `import { createCoachMarkSequence } from "@jgengine/core/ui"`
+
+## codex-gallery — codex/bestiary gallery with category tabs, discovered/locked cards, secret masking, and a completion header
+
+- `Codex` (function) · `import { Codex } from "@jgengine/react"`
+
+## colorblind-filters — SVG feColorMatrix defs (protanopia/deuteranopia/tritanopia/grayscale) referenced by the accessibility colorblind filter
+
+- `ColorblindFilters` (function) · `import { ColorblindFilters } from "@jgengine/react"`
+
+## combo-meter-hud — drop-in HUD for a core combo meter — big live count, free-string tier label, derived multiplier, and a draining decay-window bar, per-tier colored from a caller map and HudTheme-token skinnable
+
+- `ComboMeterHud` (function) · `import { ComboMeterHud } from "@jgengine/react"`
+
+## confirm-dialog — generic themeable confirm/cancel dialog — title, body, two buttons, danger styling
+
+- `ConfirmDialog` (function) · `import { ConfirmDialog } from "@jgengine/react"`
+
+## controller-camera-shake — R3F consumer that applies a core camera-shake controller's pooled per-frame offset to the active camera (translation + pitch/yaw/roll) so the view visibly shakes
+
+- `ControllerCameraShake` (function) · `import { ControllerCameraShake } from "@jgengine/shell/camera"`
+
 ## controls-list — keybind-derived control legend that hides on touch
 
 - `ControlsList` (function) · `import { ControlsList } from "@jgengine/react"`
 
+## credits-screen — drop-in credits view over a CreditsDocument — headed sections, optional links, HudTheme-skinned
+
+- `CreditsScreen` (function) · `import { CreditsScreen } from "@jgengine/react/creditsScreen"`
+
+## 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"`
+
+## damage-direction-overlay — drop-in hit-from damage-direction overlay — SVG arcs flaring around a center reticle toward each recent hit and fading over time, colored per `kind`/HudTheme, pointer-events none
+
+- `DamageDirectionOverlay` (function) · `import { DamageDirectionOverlay } from "@jgengine/react"`
+
+## day-night-sky — drop-in R3F presenter that drives the engine's existing sky dome and lights from a serializable day-night cycle for a moving, color-graded day-night look
+
+- `DayNightSky` (function) · `import { DayNightSky } from "@jgengine/shell/environment"`
+
+## debounced-commit — bind a slider/number/color control to an expensive commit path (scene-document patch, settings persist) — instant local mirror, one trailing commit per pause, flush on release/blur/unmount; no raw onChange→patch wiring
+
+- `useDebouncedCommit` (function) · `import { useDebouncedCommit } from "@jgengine/react"`
+
 ## default-look — one field that lights a scene like a shipped game (opt out with "flat")
 
 - `LookPreset` (type) · `import { LookPreset } from "@jgengine/core/ui"`
 
+## default-walk-codes — stock WASD + jump key codes for the shell walk controller
+
+- `DEFAULT_WALK_CODES` (const) · `import { DEFAULT_WALK_CODES } from "@jgengine/shell/shellMovement"`
+
+## 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"`
+
+## disposable-resource — memoize a three.js GPU resource (or tuple) with automatic dispose on change/unmount — no hand-rolled useMemo + dispose-effect pairs
+
+- `useDisposable` (function) · `import { useDisposable } from "@jgengine/shell/render/useDisposable"`
+
 ## distance-format — render meters as m or km for HUD stats, telemetry, and range readouts
 
 - `formatDistance` (function) · `import { formatDistance } from "@jgengine/core/ui"`
 
+## dom-event — attach a window/document/element event listener with automatic cleanup and a stable handler ref — no hand-rolled addEventListener effects
+
+- `useDomEvent` (function) · `import { useDomEvent } from "@jgengine/react"`
+
+## entity-frames — overlay that renders caller-composed frames over on-screen entities
+
+- `EntityFrames` (function) · `import { EntityFrames } from "@jgengine/react"`
+- `EntityScreenProjection` (interface) · `import { EntityScreenProjection } from "@jgengine/react"`
+- `WorldEntityFrames` (function) · `import { WorldEntityFrames } from "@jgengine/shell/world/WorldEntityFrames"`
+- `projectWorldToScreen` (function) · `import { projectWorldToScreen } from "@jgengine/shell/world/WorldEntityFrames"`
+- `useWorldProjection` (function) · `import { useWorldProjection } from "@jgengine/shell/world/WorldEntityFrames"`
+
 ## entity-portrait — selectable entity portrait tile with vitals and selected/focus states
 
 - `EntityPortrait` (function) · `import { EntityPortrait } from "@jgengine/react"`
 
+## entity-preview — live 3D entity portrait — nested Canvas + context bridge + studio stage, driven by the game's own renderEntity
+
+- `EntityPreview` (function) · `import { EntityPreview } from "@jgengine/shell/render/EntityPreview"`
+
 ## entity-render-cues — live velocity/bob/fire/reload/hit/death cues for a custom renderEntity or viewmodel component
 
 - `useEntityRenderCues` (function) · `import { useEntityRenderCues } from "@jgengine/shell/render/useEntityRenderCues"`
@@ -77,6 +185,26 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `useEventMeter` (function) · `import { useEventMeter } from "@jgengine/react"`
 
+## fast-travel-menu — discovered-destinations picker grouped by region with distances, a discovery counter, and a travel callback
+
+- `FastTravelMenu` (function) · `import { FastTravelMenu } from "@jgengine/react"`
+
+## floating-text — overlay that renders on-screen floating combat text with per-kind color, alpha, and pop-in scale
+
+- `FloatingText` (function) · `import { FloatingText } from "@jgengine/react"`
+- `FloatingTextPlacement` (interface) · `import { FloatingTextPlacement } from "@jgengine/react"`
+- `WorldFloatingText` (function) · `import { WorldFloatingText } from "@jgengine/shell/vfx/WorldFloatingText"`
+- `createFloatingTextField` (function) · `import { createFloatingTextField } from "@jgengine/core/ui/floatingText"`
+- `layoutFloatingText` (function) · `import { layoutFloatingText } from "@jgengine/react"`
+
+## fullscreen-map — fullscreen pan/zoom world-map overlay over WorldMapSurface — wheel-zoom, drag-pan, click-to-place, and a freehand draw tool (onStrokeComplete)
+
+- `FullscreenMap` (function) · `import { FullscreenMap } from "@jgengine/react"`
+
+## game-context-bridge — re-provide the GameContext across a nested Canvas/reconciler boundary
+
+- `GameContextBridge` (function) · `import { GameContextBridge } from "@jgengine/react"`
+
 ## heightfield-mesh-update — in-place partial update of a displaced ground plane mesh
 
 - `displaceHeightfieldGeometry` (function) · `import { displaceHeightfieldGeometry } from "@jgengine/shell/terrain"`
@@ -129,27 +257,67 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `StatBar` (function) · `import { StatBar } from "@jgengine/react"`
 
-## hud-theme — game-authored token object for bars, frames, slots, and minimap ring
+## hud-theme — game-authored token object covering bars, frames, slots, chrome, text, status colors, fonts, and rarity
 
 - `HudThemePalette` (interface) · `import { HudThemePalette } from "@jgengine/react"`
 
+## hud-theme-author — fill a full HudTheme from per-group partial overrides
+
+- `hudTheme` (function) · `import { hudTheme } from "@jgengine/react"`
+
+## hud-theme-derive — build a full HudTheme from an accent + surface seed pair
+
+- `deriveHudTheme` (function) · `import { deriveHudTheme } from "@jgengine/react"`
+
+## 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-vitals — atomic purpose-named vitals bars (token-themed parts, not a finished HUD)
 
 - `BarTokens` (interface) · `import { BarTokens } from "@jgengine/react"`
 - `barTokens` (function) · `import { barTokens } from "@jgengine/react"`
 
+## i18n — translate a message catalog with fallback-locale lookup, `{param}` interpolation, and Intl pluralization; observable active-locale switching
+
+- `createI18n` (function) · `import { createI18n } from "@jgengine/core/ui"`
+
+## 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"`
+
 ## key-hint — keyboard/mouse control hint that hides itself on touch
 
 - `KeyHint` (function) · `import { KeyHint } from "@jgengine/react"`
 
+## keybinding-menu — drop-in controls-settings surface over a rebind session — click-to-capture rows with key glyphs, conflict badges, per-row and reset-all, HudTheme-skinnable
+
+- `KeybindingMenu` (function) · `import { KeybindingMenu } from "@jgengine/react"`
+
 ## keycap — styled keyboard/mouse key cap for control hints
 
 - `Keycap` (function) · `import { Keycap } from "@jgengine/react"`
 
+## kill-feed — vertical event/kill-feed ticker rendering a core event-ticker as a fading, newest-on-top stack of per-kind iconned, accent-colored rows over HudTheme tokens
+
+- `KillFeed` (function) · `import { KillFeed } from "@jgengine/react"`
+
 ## live-markers — a self-ticking MarkerSet kept in sync from the live scene each HUD tick — pass a rebuild(markers, ctx) that clears+repopulates, no hand-rolled setInterval
 
 - `useLiveMarkers` (function) · `import { useLiveMarkers } from "@jgengine/react"`
 
+## map-legend — marker-kind key (glyph + color + label per kind) sharing the map's kindStyles
+
+- `MapLegend` (function) · `import { MapLegend } from "@jgengine/react"`
+
+## 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"`
+
+## menu-stack-reducer — pure push/back/replace/reset transitions for a menu screen stack
+
+- `menuStackReducer` (function) · `import { menuStackReducer } from "@jgengine/react/menuRouter"`
+
 ## minimap — framed circular minimap with terrain bake, fog, markers, and facing arrow
 
 - `Minimap` (function) · `import { Minimap } from "@jgengine/react"`
@@ -166,10 +334,39 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `MinimapTrack` (function) · `import { MinimapTrack } from "@jgengine/react"`
 
+## modal-host — full-screen modal/dialog host over a modal stack — dimmed backdrop, focus trap, Esc/backdrop-to-cancel, aria-modal dialog
+
+- `ModalHost` (function) · `import { ModalHost } from "@jgengine/react"`
+
+## modal-stack — serializable, observable stack of opaque modal/dialog records — push/pop/resolve blocking overlays (pause menu, confirm dialog) with optional auto-dismiss; never interprets kind or result
+
+- `createModalStack` (function) · `import { createModalStack } from "@jgengine/core/ui"`
+
 ## nameplates — billboarded name + HP bar over nearby entities
 
 - `WorldNameplates` (function) · `import { WorldNameplates } from "@jgengine/shell/world/WorldHud"`
 
+## notification-bell — icon button with a live unread-count badge over a notification store
+
+- `NotificationBell` (function) · `import { NotificationBell } from "@jgengine/react"`
+
+## notification-center-panel — scrollable notification log with kind markers, read tracking, relative time, and mark-all-read/clear
+
+- `NotificationCenter` (function) · `import { NotificationCenter } from "@jgengine/react"`
+
+## objective-banner — serializable, clock-driven stage/objective banner queue — flies a big transient centered title + optional subtitle in, holds, and fades out one at a time, with phase + progress for animation, free-string kinds the game styles, and snapshot/restore
+
+- `createObjectiveBanner` (function) · `import { createObjectiveBanner } from "@jgengine/core/ui"`
+
+## objective-banner-host — full-screen overlay that renders a core objective-banner controller as a fly-in / hold / fade-out centered title + subtitle stamp, theme- and per-kind-skinnable
+
+- `ObjectiveBannerHost` (function) · `import { ObjectiveBannerHost } from "@jgengine/react"`
+
+## offscreen-markers — serializable waypoint tracker + pure edge-clamp/bearing math for on-screen pins and off-screen directional arrows with distance
+
+- `createWaypointTracker` (function) · `import { createWaypointTracker } from "@jgengine/core/ui"`
+- `layoutScreenMarker` (function) · `import { layoutScreenMarker } from "@jgengine/core/ui"`
+
 ## ordinal-format — format a placement number as 1st/2nd/3rd for HUD ranks
 
 - `formatOrdinal` (function) · `import { formatOrdinal } from "@jgengine/core/ui"`
@@ -186,7 +383,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `focusPanel` (function) · `import { focusPanel } from "@jgengine/core/ui"`
 
-## panel-host — render a manager's open windows as draggable, closable, z-stacked dialogs
+## panel-host — render a manager's open windows as draggable, closable, z-stacked dialogs above the HUD
 
 - `PanelHost` (function) · `import { PanelHost } from "@jgengine/react"`
 
@@ -214,6 +411,22 @@ 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
+
+- `ParticleField` (function) · `import { ParticleField } from "@jgengine/shell/vfx/ParticleField"`
+
+## pause-menu — reskinnable pause-menu building block — Resume plus a game-filled Settings/Quit slot list, HudTheme-driven
+
+- `PauseMenu` (function) · `import { PauseMenu } from "@jgengine/react"`
+
+## photo-mode — observable photo-mode state (active + hide-HUD) a game binds its screenshot/camera flow to
+
+- `createPhotoModeStore` (function) · `import { createPhotoModeStore } from "@jgengine/core/ui"`
+
+## photo-mode-controls — photo-mode toolbar (hide-HUD toggle, capture, exit) bound to a photo-mode store
+
+- `PhotoModeControls` (function) · `import { PhotoModeControls } from "@jgengine/react"`
+
 ## placement-ghost — render valid/invalid placement preview mesh
 
 - `PlacementGhost` (function) · `import { PlacementGhost } from "@jgengine/shell/structures"`
@@ -222,10 +435,46 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `Popover` (function) · `import { Popover } from "@jgengine/react"`
 
+## quest-tracker — compact quest/objective HUD tracker — titles + labelled objective progress from describeTrackedQuest views
+
+- `QuestTracker` (function) · `import { QuestTracker } from "@jgengine/react"`
+
+## quick-menu — multi-form quick menu (radial / arc / list / grid) over one item model with hotkeys, badges, cooldowns, sections, and nested submenus
+
+- `QuickMenu` (function) · `import { QuickMenu } from "@jgengine/react"`
+
+## radial-menu — pointer/stick-driven radial or arc quick menu (weapon/emote wheel) — angular slice selection with hotkeys, badges, cooldowns, and a neutral hub
+
+- `RadialMenu` (function) · `import { RadialMenu } from "@jgengine/react"`
+
+## radial-select — map a pointer/stick vector to a radial-menu slice index, with a neutral dead zone and optional arc bounds
+
+- `radialIndexFromVector` (function) · `import { radialIndexFromVector } from "@jgengine/core/ui"`
+
+## raf-loop — run a cancellable requestAnimationFrame loop for DOM-side animation with delta seconds — no hand-rolled RAF effects
+
+- `useRafLoop` (function) · `import { useRafLoop } from "@jgengine/react"`
+
 ## resolve-game-look — expand a look preset into concrete lighting/backdrop/post knobs
 
 - `resolveGameLook` (function) · `import { resolveGameLook } from "@jgengine/core/ui"`
 
+## save-slot-menu — drop-in save-select / profile menu that renders a core save-slots index as New / Continue / Load / Delete cards with free-string meta chips and relative save times, theme-skinnable
+
+- `SaveSlotMenu` (function) · `import { SaveSlotMenu } from "@jgengine/react"`
+
+## scene-capture-binding — expose the in-Canvas scene-capture function to outside-Canvas HUD (photo mode)
+
+- `SceneCaptureBinding` (function) · `import { SceneCaptureBinding } from "@jgengine/shell/render/sceneCapture"`
+
+## scoreboard-table — reskinnable ranked-score / leaderboard table over the rankLeaderboard selector — medal-colored podium, local-row highlight, HudTheme-token driven
+
+- `Scoreboard` (function) · `import { Scoreboard } from "@jgengine/react"`
+
+## screen-effects-overlay — shell DOM overlay that renders a core screen-effects controller as full-screen flash / edge-vignette / low-health-pulse color-grade layers
+
+- `ScreenEffectsOverlay` (function) · `import { ScreenEffectsOverlay } from "@jgengine/shell/postfx/ScreenEffectsOverlay"`
+
 ## selection-collection — accessible portrait-strip / group-chip renderer over a selection model
 
 - `SelectionCollectionChrome` (function) · `import { SelectionCollectionChrome } from "@jgengine/react"`
@@ -242,6 +491,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `SelectionPanel` (function) · `import { SelectionPanel } from "@jgengine/react"`
 
+## shop-grid-host — drop-in vendor/shop grid over a caller-owned wallet — item cards with icon/price/stock, afford-aware Buy, optional Sell, and a balance readout, token-themed
+
+- `ShopGrid` (function) · `import { ShopGrid } from "@jgengine/react"`
+
 ## speed-format — render a m/s speed as km/h, mph, knots, or m/s for speedometers and telemetry HUDs
 
 - `formatSpeed` (function) · `import { formatSpeed } from "@jgengine/core/ui"`
@@ -250,26 +503,142 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `StartScreen` (function) · `import { StartScreen } from "@jgengine/react"`
 
+## 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"`
+
 ## studio-stage — cinematic lighting rig + backdrop + turntable for parametric studios
 
 - `StudioStage` (function) · `import { StudioStage } from "@jgengine/shell/scene/StudioStage"`
 
+## talent-tree — drop-in skill/talent/upgrade-tree widget — pass `nodes`+`tree` for point-spend or a precomputed `view` for any unlock rule; branch/tier layout, SVG prerequisite edges, learned/available/locked/maxed styling, icon + rank, onLearn
+
+- `TalentTree` (function) · `import { TalentTree } from "@jgengine/react"`
+
+## timer-readout — live digital mm:ss/m:ss.d timer readout bound to a TimerSet
+
+- `TimerReadout` (function) · `import { TimerReadout } from "@jgengine/react"`
+
+## timer-readout-format — format milliseconds as digital timer text (mm:ss / m:ss.d / ss.d)
+
+- `formatTimerMs` (function) · `import { formatTimerMs } from "@jgengine/react"`
+
+## timer-ring — radial SVG charge/cooldown ring bound to a TimerSet's progress
+
+- `TimerRing` (function) · `import { TimerRing } from "@jgengine/react"`
+
+## trans — inline translated-message component bound to the active locale
+
+- `Trans` (function) · `import { Trans } from "@jgengine/react"`
+
 ## transform-gizmo — in-game select/move/rotate/scale gizmo
 
 - `TransformGizmo` (const) · `import { TransformGizmo } from "@jgengine/shell/structures"`
 
+## 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"`
+
+## use-coach-marks — React hook binding a coach-mark sequence to a component — re-renders on advance/skip/gate changes
+
+- `useCoachMarks` (function) · `import { useCoachMarks } from "@jgengine/react"`
+
+## use-combo-meter — React hook binding a combo meter — re-renders per frame so the decay-window bar drains live and returns the current combo view
+
+- `useComboMeter` (function) · `import { useComboMeter } from "@jgengine/react"`
+
+## use-damage-direction — React hook that animates a damage-direction tracker's fade with requestAnimationFrame and re-renders its live indicators
+
+- `useDamageDirection` (function) · `import { useDamageDirection } from "@jgengine/react"`
+
+## use-dialogue-run — React hook binding a branching dialogue run to a component — re-renders as the player advances the conversation
+
+- `useDialogueRun` (function) · `import { useDialogueRun } from "@jgengine/react"`
+
+## use-event-ticker — React hook binding an event-ticker — re-renders per frame so entries fade and drop live, returning the current newest-first views
+
+- `useEventTicker` (function) · `import { useEventTicker } from "@jgengine/react"`
+
+## use-fast-travel — re-render a component when a fast-travel network's discovery state changes
+
+- `useFastTravel` (function) · `import { useFastTravel } from "@jgengine/react"`
+
+## use-interaction-prompt — React hook binding a prompt registry to a moving player — resolves the nearest interactable prompt and returns the active one
+
+- `useInteractionPrompt` (function) · `import { useInteractionPrompt } from "@jgengine/react"`
+
+## use-modal-stack — React hook binding a modal stack to a component — re-renders on push/pop/resolve
+
+- `useModalStack` (function) · `import { useModalStack } from "@jgengine/react"`
+
+## use-objective-banner — React hook binding an objective-banner controller — advances its clock per frame and returns the current banner view
+
+- `useObjectiveBanner` (function) · `import { useObjectiveBanner } from "@jgengine/react"`
+
 ## use-panels — headless toggleable-window manager with keybind + ESC handling over the core panel model
 
 - `usePanels` (function) · `import { usePanels } from "@jgengine/react"`
 
+## use-rebind-session — React hook that re-renders a component whenever a rebind session changes
+
+- `useRebindSession` (function) · `import { useRebindSession } from "@jgengine/react"`
+
+## use-save-slots — React hook binding a save-slots metadata index — re-renders on change and returns the ordered slot list
+
+- `useSaveSlots` (function) · `import { useSaveSlots } from "@jgengine/react"`
+
+## use-sequence-director — React hook that drives a cutscene director's per-frame tick loop and exposes playhead/progress + play/pause/skip controls
+
+- `useSequenceDirector` (function) · `import { useSequenceDirector } from "@jgengine/react"`
+
+## use-shop-stock — React hook binding a shop-stock model — re-renders on any stock change and returns the entry list
+
+- `useShopStock` (function) · `import { useShopStock } from "@jgengine/react"`
+
+## use-timer — React hook binding one timer to a component with a per-frame re-read
+
+- `useTimerRead` (function) · `import { useTimerRead } from "@jgengine/react"`
+
+## use-translate — live `t(key, params)` translator bound to the active locale, re-rendering on locale change
+
+- `useT` (function) · `import { useT } from "@jgengine/react"`
+
+## use-wave-runner — React hook that subscribes to a wave runner and returns its pooled current-wave view
+
+- `useWaveRunner` (function) · `import { useWaveRunner } from "@jgengine/react"`
+
+## use-waypoints — React binding that returns a waypoint tracker's live list (or a passthrough array)
+
+- `useWaypoints` (function) · `import { useWaypoints } from "@jgengine/react"`
+
 ## vital-bar — compact current/max vital meter for an entity summary
 
 - `VitalBar` (function) · `import { VitalBar } from "@jgengine/react"`
 
+## wave-hud — drop-in wave/spawn HUD over a wave runner — big WAVE N label, wave-progress bar, spawned/total + budget + alert readouts, theme-skinnable
+
+- `WaveHud` (function) · `import { WaveHud } from "@jgengine/react"`
+
+## waypoint-arrow — on-screen HUD guide arrow to a tracked waypoint, rotated by facing-relative bearing with a distance readout
+
+- `WaypointArrow` (function) · `import { WaypointArrow } from "@jgengine/react"`
+
+## waypoint-markers — overlay rendering world waypoints as on-screen pins and off-screen edge-clamped directional arrows with distance, colored per game-owned kind
+
+- `WaypointMarkers` (function) · `import { WaypointMarkers } from "@jgengine/react"`
+
 ## window — standalone draggable, closable window primitive over HudFrame — no manager required
 
 - `Window` (function) · `import { Window } from "@jgengine/react"`
 
+## world-intersections — inspect turns and junction meshes in a deterministic preview fixture
+
+- `StreetGeometryPreview` (function) · `import { StreetGeometryPreview } from "@jgengine/react"`
+
 ## world-object-highlights — ground-ring highlight over every selected placed object
 
 - `WorldObjectHighlights` (function) · `import { WorldObjectHighlights } from "@jgengine/shell/world/WorldHud"`
+
+## world-pings — in-scene ping markers — a bobbing downward arrowhead, ground ring, and billboarded callout per marker, colored by kind and fading over the marker's lifetime
+
+- `WorldPings` (function) · `import { WorldPings } from "@jgengine/shell/world/WorldPings"`

package/skills/jgengine-ui/recipes/overhead-entity-frames.md

@@ -0,0 +1,136 @@
+# Overhead enemy nameplates and health bars
+
+Use this recipe when a game needs floating world-anchored frames over entities —
+enemy nameplates with a health bar, interaction prompts, objective pips. The
+game keeps owning its entities; JGengine owns only the reusable behavior:
+projecting a world position to the screen, offsetting above the head, culling
+frames that are off-screen or behind the camera, and stacking nearer frames over
+farther ones. You compose the frame markup itself from the shipped bars, so the
+look is the game's, not a prefab.
+
+The seam is data-first and caller-owned: pass an array of
+`{ id, worldPosition, ... }` and a projector. Nothing is mirrored into a store.
+
+## Install
+
+```sh
+bun add @jgengine/core @jgengine/react
+# @jgengine/shell only for the R3F projection convenience below
+bun add @jgengine/shell
+```
+
+`@jgengine/react/entityFrames` imports neither Three.js nor React Three Fiber and
+needs no `GameProvider`. The `@jgengine/shell` piece is a thin R3F convenience.
+
+## R3F game: one component from your own entity array
+
+`WorldEntityFrames` mounts inside the R3F scene, samples the live camera each
+frame, and renders the frames through a fullscreen overlay. Pass the entities you
+already have and a `renderFrame` that composes the shipped `HealthBar` plus a
+name. Projection, culling, and stacking come for free.
+
+```tsx
+import { WorldEntityFrames } from "@jgengine/shell/world/WorldEntityFrames";
+import { HealthBar, barTokens } from "@jgengine/react/bars";
+
+interface Enemy {
+  id: string;
+  name: string;
+  position: [number, number, number];
+  hp: number;
+  maxHp: number;
+}
+
+export function EnemyNameplates({ enemies }: { enemies: readonly Enemy[] }) {
+  const entries = enemies.map((e) => ({
+    id: e.id,
+    // Anchor over the head: lift the world Y by the entity's height.
+    worldPosition: [e.position[0], e.position[1] + 2.2, e.position[2]] as const,
+    enemy: e,
+  }));
+
+  return (
+    <WorldEntityFrames
+      entries={entries}
+      maxCount={24} // keep the nearest 24 when a crowd is on screen
+      renderFrame={({ enemy }) => (
+        <div style={{ ...barTokens({ health: "#e5484d" }), textAlign: "center" }}>
+          <span
+            style={{
+              fontSize: 12,
+              fontWeight: 700,
+              color: "#f1f5f9",
+              textShadow: "0 1px 3px rgba(0,0,0,0.9)",
+              whiteSpace: "nowrap",
+            }}
+          >
+            {enemy.name}
+          </span>
+          <HealthBar value={enemy.hp} max={enemy.maxHp} width={78} showValue={false} shape="pill" />
+        </div>
+      )}
+    />
+  );
+}
+```
+
+Reskin the whole set with one `HudTheme`/`barTokens` object on an ancestor —
+health color, frame material, radius, and glow flow to every plate's `HealthBar`.
+The `enemy` payload rides along on each entry, so `renderFrame` reads live values
+without a second lookup.
+
+## Non-R3F game: bring your own projector
+
+Outside R3F (a 2D or custom-renderer game), use the headless
+`EntityFrames` directly and pass a `project` that maps a world position to a
+screen point — return `null`, or `{ behind: true }`, to cull an entry. `depth`
+(larger = farther) drives stacking.
+
+```tsx
+import { EntityFrames, type ProjectEntity } from "@jgengine/react/entityFrames";
+import { HealthBar } from "@jgengine/react/bars";
+
+const project: ProjectEntity = (world) => {
+  const screen = myCamera.worldToScreen(world); // your renderer's projection
+  if (screen === null) return null; // outside the frustum → culled
+  return { x: screen.x, y: screen.y, depth: screen.distance, behind: screen.behind };
+};
+
+export function Nameplates({ enemies }: { enemies: readonly Enemy[] }) {
+  return (
+    <EntityFrames
+      entries={enemies.map((e) => ({ id: e.id, worldPosition: e.position, enemy: e }))}
+      project={project}
+      offsetY={-24}
+      viewport={{ width: window.innerWidth, height: window.innerHeight }}
+      renderFrame={({ enemy }) => (
+        <HealthBar value={enemy.hp} max={enemy.maxHp} width={78} showValue={false} />
+      )}
+    />
+  );
+}
+```
+
+Mount either component inside `HudCanvas` (or any positioned ancestor) so the
+overlay is bounded to the viewport.
+
+## Ownership
+
+The game still owns its entities, their positions, health, updates, camera, and
+the render cadence. JGengine owns the projection→offset→cull→stack behavior
+(`layoutEntityFrames`, unit-tested) and, for R3F, the camera→screen projector
+(`useWorldProjection` / `projectWorldToScreen`). The frame markup is yours.
+
+## Common traps
+
+- Pass a fresh `entries` array each frame (or memo it on your live data). The
+  component re-projects on the R3F frame loop; the pure `EntityFrames` re-projects
+  whenever it re-renders.
+- Lift `worldPosition` by the entity's height for an overhead anchor — the seam
+  does not guess a height.
+- Set `maxCount` for crowds so a battlefield of entities does not render hundreds
+  of plates; the nearest are kept.
+- Do not mirror entities into a `GameProvider`/entity store to use this. If the
+  game *does* run the JGengine entity store, `WorldNameplates`
+  (`@jgengine/shell/world/WorldHud`) is the store-driven counterpart.
+- Keep `renderFrame` cheap — it runs per visible entity per refresh.