@jgengine/react 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -11,9 +11,174 @@ Agents building on the published SDK can also read this programmatically:
 same data as typed values, so an updater can diff its installed version against
 the latest and surface the migration steps.
 
-## Unreleased
+## 0.7.0
+
+The engine-gaps release — 22 system-level additions across turn/tactics, cards & boards,
+crafting, survival, navigation & AI, camera rigs, physics & vehicles, traversal &
+destruction, world items & building, map/HUD/ping, combat feel & abilities, audio,
+interaction, sensors, embodiment, multiplayer depth, and objective/session machines.
+**Every 0.6.0 API is unchanged** — the whole release is additive, so upgrading is a version bump.
+
+### Migrate
+
+- Bump every `@jgengine/*` dependency to `^0.7.0` (the eight packages version in lockstep).
+- No code change is required — 0.7.0 only adds surface; no 0.6.0 API moved or was removed. Existing games keep the orbit/first-person camera, single-player-entity control, and every existing primitive exactly as before.
+- Opt into any new system by importing it directly: a camera rig via `camera.rig` + its config block; a `sensor/*` probe with `@jgengine/shell/vision` renderers; an `ai/*` director over the `nav/` navmesh; `turn/*` + `tactics/*` for turn-based/grid games; `cards/*` + `board/*` for deckbuilders; `crafting/*` for recipes/production/farming; `survival/*` + `world/{envField,weather,realm}` for survival; `combat/{abilityKit,animationState,defensiveWindow,…}` for action feel; `physics/{vehicleBody,traversal,structure,ragdoll,…}` for vehicles/destruction; `session/*` for contested/round/downed/ring/extraction machines; and `multiplayer/*` for lag-comp/hidden-commit/matchmaking.
+- `entityStore.update()` now also accepts `name`, so possession/form can retarget an instance's catalog id without despawn/respawn — no action needed unless you relied on `name` being immutable.
+
+### Added
+
+- **Turn-based & tactics stack** — six pure, renderer-free `@jgengine/core` primitives for turn-based, grid-tactics, and card games (XCOM, BG3, Into the Breach, Slay the Spire, Marvel Snap, Tactical Breach Wizards, Divinity surfaces).
+  - `@jgengine/core/turn/turnLoop` (`createTurnLoop`) — initiative machine with configurable `phases` and per-turn action-economy `pools` (`{ id, max, start? }`) that reset when a participant enters their turn; `advanceTurn`/`advancePhase`/`advanceRound`, `spend`/`canSpend`/`gain`/`refill`, and `setOrder`/`addParticipant`/`removeParticipant`. Covers both Slay-the-Spire single-energy resets and BG3's Action/Bonus/Movement/Reaction set.
+  - `@jgengine/core/turn/commit` (`createCommitController`, also `turnLoop.commit`) — three commit modes: `immediate`, `simultaneous` (sealed hidden submissions → `reveal()` on `allReady()`), and `rewind` (visible `pending()` → `rewind()`/`commit()`).
+  - `@jgengine/core/tactics/tacticalGrid` (`createTacticalGrid`) — tile occupancy, `reachable(from, budget)` flood-fill, `path`, and `push(id, dir, { distance, chain })` discrete knockback-to-tile with chained collisions (Into the Breach).
+  - `@jgengine/core/tactics/predictiveQuery` (`predictAreaEffect`/`predictArcEffect`/`predictTiles`) — a would-this-effect-hit query for pre-commit overlays and enemy-intent telegraphs, reusing the exact AoE/LoS targeting behind `ctx.scene.entity.effect` (new shared `resolveAreaTargets` in `combat/effects`) so predictions match what the effect actually drains.
+  - `@jgengine/core/tactics/snapshot` (`createSnapshotStore`, `deepClone`) — cheap, repeatable turn-undo over registered `capture()/restore()` slices (the grid, surfaces, and turn loop all qualify), with a `push()/pop()` undo stack.
+  - `@jgengine/core/tactics/surface` (`createSurfaceLayer`) — a stateful tile surface layer with its own `tick(dt)` and a data-driven combination matrix (`reactions: [{ when: [a, b], result }]`) — grease+fire, water+lightning — distinct from terrain/water.
+- `@jgengine/core/combat/effects` now exports `resolveAreaTargets` (+ `AreaTarget`, `AreaTargetInput`), the shared in-radius→LoS→falloff→accept targeting that both `applyEffect` and the predictive query run, guaranteeing parity by construction. No behavior change to `effect`.
+
+Pure, renderer-free primitives for card, board, and deckbuilder games — they sit **beside** the slot inventory, never replace it.
+
+- **`@jgengine/core/cards/cardPile`** — a `cardPile` of named ordered zones (deck/hand/discard/exhaust) with seeded `shuffle`, `draw(n)` (hand limits + reshuffle-on-empty), `discard`/`exhaust`/`move`. Reuses the engine's seeded RNG (`pileRng`), so shuffles are deterministic under a seed. Slay the Spire, Balatro.
+- **`@jgengine/core/cards/modifierPipeline`** — an ordered `{ source, apply(value) → value }` pipeline (`runPipeline` / `createModifierPipeline`) with an inspectable per-step `trace` (before/after/changed) for Balatro-style scoring readouts. Generic over the scored value.
+- **`@jgengine/core/board/laneBoard`** — N lanes, per-side power aggregate + optional per-lane `LaneRule` modifier, with `laneOutcome`/`boardTotals`/`lanesWon`. Marvel Snap, Inscryption.
+- **`@jgengine/core/board/timelineBoard`** — N slots each on an independent cooldown, `tick(dtMs)` resolving fires in expiry order (then slot index), multiple fires per slot per tick. The Bazaar auto-battlers.
+- **`@jgengine/core/inventory/shapedGrid`** — a polyomino inventory variant: `Footprint` placement, `rotateFootprint`, `canPlace` overlap/bounds check, plus `gridAdjacencyQuery` (orthogonal/diagonal neighbors) feeding synergy effects, and `cellFromPoint` for pointer→cell snap. Backpack Hero, Tetris inventory.
+- **`@jgengine/react/dragLayer`** — a 2-D UI-space drag/rotate/drop/snap gesture layer over the above: `useDragLayer`, headless `DraggableCard` (right-click rotate), `DropZone` (cell snap + active state), `DragGhost`.
+
+- `@jgengine/core/crafting/recipe` — a recipe graph primitive: `RecipeDef { inputs, outputs, seconds?, station?, stationRange?, requires? }` turns inputs + an optional required-workstation-in-range + time into outputs. `craft` / `canCraft` consume and produce on an `InventoryState` atomically (rejecting `missing-inputs` / `no-station` / `locked` / `no-output-space`); `stationSatisfied` does the range check against placed `{ catalogId, position }` stations; `createRecipeGraph` indexes recipes by `producing` / `using` / `category`. For Valheim/Enshrouded-style workbench tiers, Tarkov hideout stations, Palworld base craft. (#71)
+- `@jgengine/core/economy/techTree` — a prerequisite-gated tech tree that **generalizes flat `unlocks`** rather than duplicating it: `TechNodeDef extends UnlockDef` adds `requires` (prereq ids), a `recipe` payload, and `grants`. `createTechTree(defs)` wraps `createUnlocks` and gates `unlock(userId, id)` on prerequisites, exposing `available` (frontier) and `recipes` (payloads unlocked). Flat unlocks are just nodes with no `requires`. For Once Human Memetics / Abiotic Factor branching trees. (#72)
+- `@jgengine/core/crafting/production` — `productionBuilding({ inputs, outputs, rate, power? })` plus `tickProduction`, which consumes buffered inputs and emits outputs continuously through game-time `dt` (so pause/fast-forward apply for free). `feedProduction` / `drainOutput` are the buffer I/O, `advanceTransport` slides items along a conveyor path, `resolvePowerGrid` powers demands greedily against a supply. For Palworld/Satisfactory/Factorio automation. (#74)
+- `@jgengine/core/crafting/crop` — a `cropTile` soil-and-growth state machine (`tillTile` / `plantCrop` / `waterTile` / `advanceCropDay` / `harvestCrop`, with regrow and daily-water rules) that advances stages on the simClock day tick, plus `applyToolToTiles(tiles, center, pattern, apply)` with `squarePattern` / `diamondPattern` / `rectPattern` for watering-can/hoe AoE under the cursor. `createCropField` wraps a tile grid; `createDayTicker` reads day rollovers off `ctx.time.calendar()`. For Stardew/Coral Island/Palia farming. (#75)
+- **Survival & environment layer.** Renderer-free `@jgengine/core` primitives for survival games (Project Zomboid moodles, The Long Dark / Green Hell survival, DayZ / Tarkov per-limb health, weather-driven games, Nightingale realm cards), plus the `@jgengine/shell` fire visuals.
+  - `@jgengine/core/survival/decayMeter` — named `decayMeter`s (`createDecayMeterSet`) that drain/recover on game-time `dt`, refill from consumables/actions, raise threshold moodles, and take environment-driven rate modifiers (cold speeds warmth loss, toxic biomes drop oxygen).
+  - `@jgengine/core/survival/moodle` — a stacking status-effect display distinct from numeric bars: `stackMoodles(...)` folds meter/ailment/buff moodles worst-first, and `createMoodleStack()` holds timed buffs (Valheim-style concurrent food buffs) that expire on `tick(dt)`.
+  - `@jgengine/core/survival/regionHealth` — a multi-region health component (`createMultiRegionHealth`): per-part pools with vulnerability + vital death, a stacking ailment queue (bleed/fracture) that drains over time, and per-injury treatment items (`treat("bandage")`). Shares the moodle display via `ailmentMoodles()`.
+  - `@jgengine/core/world/envField` — sampleable environment fields (`createEnvironmentField`): temperature, wetness, light-exposure, and ambient-light at any world position and time, with sky occluders, heat sources, and a day/night sun cycle. Meters and spawn gating read it renderer-free.
+  - `@jgengine/core/world/weather` — weather → gameplay modifiers (`resolveWeather` → grip/visibility/structure-damage/chill/ignition/spread) over a game-owned table, plus a **coarse cellular** fire-spread grid (`createFireGrid`, not a fluid solver): wind-biased propagation, fuel burn-through, firebreaks, and rain/wetness suppression.
+  - `@jgengine/core/world/realm` — runtime realm composition (`composeRealm`): assemble a played instance from a deck of modifier cards (major biome + minor weather/day-length/spawn cards) that override environment params and spawn tables, recomposing a sampleable environment field on top of the weather hooks.
+  - `@jgengine/shell/weather` `FireSpreadLayer` — renders a `FireGrid`'s burning flames + scorched cells; a `survival-demo` game wires the whole stack (moodle stack, per-part body panel, condition meters, weather readout, spreading fire).
+- `@jgengine/core/audio/audioFalloff` — the audio contract + pure distance→gain math. `SoundDef`/`AudioBusDef` catalog types, `computeFalloffGain(distance, config)` (`"linear" | "inverse" | "none"` curves), and `resolveEmitterGain`/`distance3` helpers. No Web Audio in core — this is the tested math the shell plays from.
+- `@jgengine/core/time/beatClock` — a BPM tick signal, separate from `simClock`. `createBeatClock({ bpm, beatsPerBar? }, onBeat?)` advances on **game-time** `dt` and fires `onBeat` per crossed beat; `createBeatInputBuffer` auto-corrects an off-beat press to fire on the next beat tick (`nextBeatTime` is the underlying pure quantization). For rhythm-quantized combat (Hi-Fi Rush–style).
+- `@jgengine/shell` positional audio — `PlayableGame.audio = { sounds, buses? }` + `entitySounds`/`objectSounds` (kind/catalog-id → sound id, same convention as `entityModels`) declare looping positional emitters; the shell (`shell/audio/audioEngine`, `shell/audio/AudioComponents`) owns the `AudioContext`, attaches the listener to the camera every frame, and drives emitter gain from the core falloff curve. Music/SFX buses are plain per-bus gain nodes. No per-game Web Audio glue.
+- `@jgengine/ws/voiceChannel` — a thin, coarse voice-channel router riding the same transport/presence model (channel/falloff model only, no WebRTC media). `createVoiceChannelRouter(channels?)`: `join`/`leave` any number of channels at once, `updatePosition` for proximity falloff (reusing the core audio falloff curve), `setMuted`, and `resolveRoutes(listenerUserId)` — one `{ fromUserId, channelId, gain }` per shared channel, so a positional proximity channel and a flat-gain walkie/crew channel resolve simultaneously and independently.
+- `@jgengine/core/interaction/skillCheck` — a moving-target-zone, timed minigame (`evaluateSkillCheck`, `skillCheckMarkerPosition`, `skillCheckZoneAt`) for casting/reeling, active-reload, and production minigames from an `item.use` handler.
+- `@jgengine/core/interaction/qte` — a timed-prompt QTE sequencer (`evaluateQteSequence`, `pendingQteStep`, `qteProgress`).
+- `@jgengine/core/scene/captureCheck` — `captureChance`/`rollCapture`, an hp%+catchPower→probability formula for capture/tame mechanics.
+- `@jgengine/core/scene/roster` — `createRoster()`, a persisted per-owner roster (capture/release/list/setEquipped) wired onto the runtime as `ctx.game.roster`, distinct from the ephemeral `game.social.party`.
+- `@jgengine/core/stats/rollCheck` — `rollCheck`, a d20-style roll vs. DC with advantage/disadvantage and critical detection.
+- Dialogue choices can now gate a branch behind a roll: `DialogueChoice.check` (+ `onSuccess`/`onFailure`) on the `@jgengine/react/components` `DialogueDef`/`DialogueChoice` types, resolved via `resolveDialogueInvoke`.
+- `@jgengine/react` gained `SkillCheckBar`, `QteTrack`, and `CaptureOdds` headless minigame UI components, plus a `useRoster(userId?)` hook and extra `DialogueBox` slot classNames (`lineClassName`, `speakerClassName`, `choicesClassName`, `choiceClassName`, `checkClassName`).
+- **Navigation & pointer-driven input.** A renderer-free foundation for click-to-move, RTS unit command, and pointer verbs.
+  - `@jgengine/core/nav/navGrid` — a walkable grid + A* pathfinding (`createNavGrid`, `findPath`, `smoothPath`); blocked start/goal snap to the nearest walkable cell, paths are string-pulled, and one graph feeds both click-to-move and AI routing.
+  - `@jgengine/core/nav/pathFollow` — an authored-polyline mover for tower-defense creeps needing no navmesh (`createPathFollow` + pure `advancePathFollow`); `pathFromNav` lifts an A* route so the same follower drives click-to-move.
+  - `@jgengine/core/input/pointer` — the renderer-free `PointerHit` contract (`{ point, normal, entity, object }`) plus `aimToPoint` / `moveTargetFromHit` / `groundOf` so gameplay consumes cursor hits (aim, move-to, routing) without three.js.
+  - `@jgengine/core/scene/selection` — pure box-select math (`createSelectionSet`, `screenRect`, `selectWithinRect`, `isMarquee`).
+  - `@jgengine/core/interaction/contextMenu` — `contextVerb` / `buildContextMenu` / `contextVerbInput`; catalog entities/objects carry `verbs` for right-click menus.
+  - `PlayableGame.pointer` config (`moveCommand`, `select`, `orderCommand`, `contextMenu`, `aim`) — the `@jgengine/shell` `GamePlayerShell` casts the cursor (`pointer.worldHit()`), renders a drag-marquee + right-click verb menu, routes primary-ability aim to the cursor, and remaps orbit to middle-drag so the left button drives verbs.
+- **AI over the navmesh.** A renderer-free `ai/` domain for directors, aggro, jobs, and crowds — all ticking on game-time `dt` (the `ctx.time` simClock delta, so pause/fast-forward come free) and routing over the `nav/` navmesh.
+  - `@jgengine/core/ai/spawnDirector` — a budget/escalation spawn director for wave shooters and difficulty directors (`createSpawnDirectorState` + pure `advanceSpawnDirector`). Per-`WaveManifest` budgets spent on weighted `SpawnEntry`s (`cost`/`weight`/`minWave`) under a `maxAlive` cap; `duration` auto-advances waves (or `advanceWave` on clear); budget trickles, ramps with sim-time (`escalationPerSecond`), scales per player, and surges on `raiseAlert`. Seeded/deterministic; `pickSpawnPoint` biases placement toward players.
+  - `@jgengine/core/ai/threat` — an aggro/threat table (`createThreatTable`): accumulate/`decay` per source, `highest({ current, stickiness })` for sticky MMO target selection feeding `scene/targeting`, `ranked` for a threat meter.
+  - `@jgengine/core/scene/behaviors` gained `patrol({ waypoints, speed, loop? })` — a waypoint route as a `BehaviorDescriptor` on top of `wander`, driven by `pathFollow` over `findPath`.
+  - `@jgengine/core/ai/jobBoard` — a task/job queue NPCs pull from (`createJobBoard`): `post`/`claim`/`assign`/`release` plus a per-tick `advance(worker, dt, { distanceToStation })` state machine (`travelling → working → done`, `repeat` for production loops) that reports on completion. For colony/companion assignment (Palworld, Schedule I, Sons of the Forest).
+  - `@jgengine/core/ai/crowd` — a flow field with congestion + POI routing for management sims (`computeFlowField` Dijkstra steering without per-agent A*, `createCrowdField` per-cell occupancy whose `penalty()` reroutes flow around crowds, `selectPoi` weighting appeal/proximity/capacity with a `findPath`-length distance override).
+- **Dropped-item world entities & loot filter.** Loot no longer has to teleport straight to inventory — it can lie on the ground as a rarity-coded, beam-and-labelled `worldItem` you walk up to and grab (Borderlands/Diablo loot beams, ARPG ground loot, Apex/Lethal-Company pick-ups).
+  - `@jgengine/core/game/worldItem` — the `worldItem` scene-entity model (position + item ref + rarity): `ctx.scene.worldItem.spawn / get / list / nearestInRadius / pickup` (a third scene bucket alongside object/entity, never merged into inventory). Pure helpers `createWorldItemStore`, `resolveDeathDrops` (splits rolled drops into scattered ground items vs direct grants), `scatterOffset` / `scatterPosition` (the on-death scatter impulse), `selectNearestWorldItem` (pickup-radius nearest selection), and `resolveWorldItemPresentation` (rarity baseline + filter overlay → render binding). Emits `worldItem.dropped` / `worldItem.picked_up`.
+  - `onDeath.dropMode: "world"` (+ optional `onDeath.scatter`) routes an entity's death drops through scattered ground items instead of granting straight to the killer; currency still grants directly. Item catalog entries carry `rarity` / `baseType` read by the render binding + filter.
+  - `@jgengine/core/game/lootFilter` — a PoE/Last-Epoch-style rule evaluator (`lootFilter`, `evaluateLootFilter`) keyed on rarity + base type + affix-tier that hides/recolors/beams/labels ground items. Rules are **data the game supplies**; first match wins, field-by-field over the rarity baseline. The render binding is engine-owned.
+  - `PlayableGame.worldItem` config (`rarityStyle`, `filter`, `pickupRadius`, `beamHeight`) + `pointer.grabWorldItems` — `@jgengine/shell`'s `WorldItems` draws the rarity beam/color/label per drop and `GamePlayerShell` grants + despawns on a click within pickup radius (using `pointer.worldHit()`). `@jgengine/react`'s `useWorldItems()` / `useNearestWorldItem(radius)` drive a HUD pickup prompt.
+
+- **Interactive placement, building & terraform.** Data-only placement becomes the build tooling of Valheim/Enshrouded/The Sims/Fortnite/Dinkum/Palia, all pure `@jgengine/core/world` driven by `pointer.worldHit()`, with shell renderers for the ghost/tint/brush.
+  - `@jgengine/core/world/placementController` — `createPlacementController(footprint)` owns the placement ghost: `hover(hit)` → `PlacementPreview` (valid/invalid tint wrapping `validatePlacement`), `rotate`, grid/free/surface `snapMode`, `commit` → `PlacementCommit`.
+  - `@jgengine/core/world/connectors` — typed connector sockets with `snapToNearest` snap-to-nearest-compatible (`socketsCompatible`, `worldSockets`).
+  - `@jgengine/core/world/support` — `solveSupport` walks the connector graph to ground (`supported`/`unsupported`/hop-`distance` for white→red decay); `toDebrisBodies` sinks collapsed pieces into the `PhysicsWorld`.
+  - `@jgengine/core/world/walls` — `createWallDrawTool` (drag walls → auto-enclose → `footprintFromWalls` → `autoRoof` hip/gable/flat) plus `createSurfacePaint` for per-tile floor/wall surfaces.
+  - `@jgengine/core/world/placedStructureStore` — `createPlacedStructureStore` save/load/select/move/delete with a `snapshot`↔`load` round-trip that survives reload.
+  - `@jgengine/core/world/terraform` — `createEditableTerrain({ bounds, base, cellSize })` makes a `TerrainField` you can **write back to** via `apply(edit)` (raise/lower/flatten/paint), and `createTerraformBrush` is the cursor tool. This height-offset grid is the shared terrain-edit write-back pattern.
+  - `@jgengine/core/world/buildPermissions` — `createPlotPermissions` (per-plot/guild `BuildRole` edit authority) + `createContributionPool` (co-op pooled-resource contribution model).
+  - `@jgengine/shell` renderers: `structures/PlacementGhost` (tinted ghost), `terrain/EditableGround` (renders an `EditableTerrain` with surface paint), `terrain/TerraformBrushCursor` (brush ring); the `builder-sandbox` demo game wires them to `pointer.worldHit()`.
+- **Map, fog of war & contextual ping.** Minimap/world-map/fog/compass + a squad ping verb, built on renderer-free core state, a shell terrain bake, and react HUD components. (Stacked on the pointer foundation above.)
+  - `@jgengine/core/world/markers` — a reactive `createMarkerSet()` of `MapMarker`s (objective/entity/loot/ping) with `add`/`remove`/`query`/`prune`/`subscribe`; `DEFAULT_MARKER_KINDS` supplies content-agnostic colors + glyphs.
+  - `@jgengine/core/world/fog` — reveal-on-event fog: `createFogField({ bounds, cellSize })` with `reveal` (dig/act) and `revealAlong` (walked trail); revealed cells stay revealed and render from a stable `cells()` snapshot.
+  - `@jgengine/core/world/minimap` — pure projection + bearings (`projectToMinimap`, `clampToMinimapEdge`, `compassBearing`, `headingToBearing`, `bearingToCardinal`, `relativeBearing`).
+  - `@jgengine/core/game/ping` — `classifyPing(hit, …)` (hostile → enemy, tagged object → its category, ground → location) + `createPingSystem` that classifies, drops a categorized marker, and broadcasts a `PingPayload` over the existing party feed under `PING_FEED_ACTION`. `PlayableGame.pointer.pingCommand` binds the `ping` action → `worldHit()` → your command.
+  - `@jgengine/react` — `useMarkers` / `useFog` hooks and `Minimap` / `Compass` / `WorldMap` headless components (bind a core `MarkerSet`/`FogField`, override the `kindStyles` palette).
+  - `@jgengine/shell/map` — `bakeTerrainMap` (top-down terrain image for the map background) and `MapMarkerBeacons` world-space beacons; the `extraction-map` demo game wires the whole loop.
+- **Physics joints & constraints** — `PhysicsWorld` gains `hingeJoint`/`fixedJoint`/`distanceJoint`/`springJoint(JointOptions)` between two bodies or a body and a fixed world point, plus `removeJoint`, `setJointAnchor` (move a follow point), `setJointRest`, and `readJointSegments`. The sim is translational: `hinge`/`fixed` pin the shared anchor, `distance` holds a separation, `spring` drives toward `restLength` with stiffness/damping. Foundation under vehicle suspension, ragdolls, grapples, and carry. Tune the buffers with `jointCapacity` / `jointCorrection` in `PhysicsWorldConfig`.
+- **Physics collision → gameplay-event hook** — `PhysicsWorld.onCollision(listener, minApproachSpeed?)` delivers each impacting contact as a reused `CollisionEvent { a, b, nx, ny, nz, approachSpeed, impulse }` during `step`. The seam crash-damage and destruction read; contacts otherwise stay inside the sim.
+- **`@jgengine/core/physics/ragdoll`** — `createRagdoll(world, { bones, links, balance? })` builds a jointed multi-body character on the joint API: floppy by default, or active-ragdoll when a balance motor drives the root toward a target height (`Ragdoll.balance(dt, moveX?, moveZ?)`), with `centerOfMass`, `applyImpulse`, `remove`.
+- **`@jgengine/core/physics/carryable`** — `Carryable` grabs a physics body to a moving follow point via a spring constraint (the raycast pick is the caller's), supports shared multi-owner carry (follow point = owner average), drop/throw, and `carrySpeedMultiplier(mass, capacity, owners)` encumbrance.
+- **`@jgengine/core/physics/forceVolume`** — `ForceVolume` (impulse/velocity/accelerate trigger region, `once` for boost pads vs continuous fans) and `PlatformCarry` (carry bodies standing on a moving platform by its per-`step` delta).
+- **`@jgengine/core/physics/spatialGrid`** — `SpatialGrid`, a broad-phase uniform grid over the x/z plane, separate from the rigid-body sim, for cheap same-tick proximity across hundreds–thousands of simple movers: `rebuild(count, xs, zs)` then `queryCircle` (swarm enemies hitting a player/AoE) or `forEachPair` (mutual separation).
+- **`@jgengine/shell/world/InstancedJoints`** — debug LineSegments overlay drawing a `PhysicsWorld`'s active joints from `readJointSegments`.
+- **`@jgengine/core/physics/traversal`** — `Grapple` (a fired-anchor rope on the joint API: `fire`/`reel`/`payOut`/`moveAnchor`/`release` for grapple, zipline, and swing traversal) and `Glide` (reduced-gravity, forward-thrust wingsuit/glider via `apply(dt, steerX, steerZ)` before `step`). Grapple/zipline/glide (Sekiro, Deep Rock, Enshrouded) over the shared physics sim.
+- **`@jgengine/core/world/carve`** — runtime destructible terrain. `VoxelVolume` is an editable dense voxel grid with `carve`/`deposit` sphere ops honouring per-material `strength` against a tool (Deep Rock dig, Astroneer deposit); `CarvableField` / `carvableTerrain(base)` writes craters and mounds back into any `TerrainField`'s height so ground-snap, collision, and the terrain mesh all see the deformation (Helldivers 2 craters).
+- **`@jgengine/core/physics/structure`** — `StructureGraph`, a structural-integrity graph over a building: nodes (pieces), load-bearing edges, anchored foundations. `damage`/`damageEdge`/`severEdge` recompute reachability to an anchor and return one `CollapseEvent` of every newly-disconnected piece; `toDebris(world, event)` sinks the fallen pieces into a `PhysicsWorld` as rigid bodies. Coarse by design — the collapse **event** replicates, not each fragment (The Finals, Rainbow Six).
+- **`@jgengine/shell/terrain/CarvedTerrain`** — meshes any `TerrainField` (a `CarvableField` with its craters/mounds) into a vertex-coloured deformed ground; `createFieldGroundGeometry` is the underlying geometry builder.
+- **Analog axis input** (`@jgengine/core/input/axisInput`) — `AxisInput { throttle, brake, steer, handbrake }` continuous channel, distinct from the digital action bindings. `AxisChannel` ramps held keys into pedal-like analog values (`sample`) or takes a raw gamepad axis (`setAnalog`); `DRIVE_AXIS_BINDINGS` is a ready WASD/arrow map.
+- **Vehicle controller** (`@jgengine/core/physics/vehicleBody`) — `createVehicleBody(world, config)`: chassis body + per-wheel suspension raycast + spring-damper (on `springJoint`) + a `GripCurve` (`sampleGripCurve`) that bleeds lateral velocity for cornering and, under handbrake, drift. Driven by an `AxisInput`; still a colliding body, so contact feeds crash damage. (Rocket League, Trackmania, Wreckfest.)
+- **Buoyant boat** (`@jgengine/core/physics/buoyancy`) — `createBuoyantBody(world, { body, water, … })` floats a body on a CPU `waterSurface` (Archimedes per hull point + water drag) and, given an `AxisInput`, drives it as a boat (thrust + yaw + keel).
+- **Mount / rideable controller** (`@jgengine/core/scene/mount`) — `createMountController()` transfers camera + input to a driven entity with its own movement kit: `register({ id, kit, seats })`, `mount`/`dismount`, `cameraTarget`/`driveTarget`, `driver`/`occupants`. Control seat drives, passenger seats ride (multi-seat shared vehicles). (Palworld, V Rising, Sea of Thieves.)
+- **Crash-damage stages** (`@jgengine/core/physics/damageZones`) — `createDamageModel({ zones, disableAt })` maps accumulated `onCollision` impulse to coarse discrete stages (`absorb`/`routeCollision`), with an optional `detachStage` (part → debris) and a `disabled` threshold. Coarse stages, not soft-body. (Wreckfest.)
+- **Race state machine** (`@jgengine/core/game/race`) — `raceTrack({ checkpoints, laps })` + `createRaceState({ track, win })` emit `checkpoint.hit` / `lap.completed` / `position.changed` / `race.finished` on game time, keep split times, resolve a pluggable win condition (`firstPastPost`, `topK`, `everyoneFinishes`, `lastStanding`), and `resetToCheckpoint`. (Trackmania, Mario Kart, Fall Guys.)
+- **Lag-compensated hit registration** (`@jgengine/core/multiplayer/lagCompensation`) — `createPositionHistory({ historyMs })` retains an N-sample position ring per entity; `rewindTimestamp(now, rtt, interpDelay)` and `resolveHitscan(history, targets, ray, atMs)` (ray-sphere) register a shot where the target *was* at the shooter's perceived time. Coarse server-side rewind, not full rollback. The `@jgengine/node` ws host records accepted presence poses and exposes `server.rewind({ serverId, atMs })` (`positionHistoryMs` option). (Valorant, Apex.)
+- **Simultaneous hidden-commit + reveal** (`@jgengine/core/multiplayer/simultaneousCommit`) — `createCommitRound({ participants })`: each player `seal`s a sealed action, nothing is readable until `allSealed()`, then `reveal()` returns commits in deterministic participant order (independent of network arrival) for `resolveCommits`. (Marvel Snap.)
+- **Combat-snapshot replay** (`@jgengine/core/multiplayer/combatSnapshot`) — `serializeBoard({ ownerId, units, stats, seed })` deep-freezes a build into a portable `BoardSnapshot`; `replayCombat(a, b, rules)` resolves it deterministically (seeded PRNG) against a live opponent's snapshot — an async-PvP primitive distinct from the live-sync adapters. (The Bazaar.)
+- **Shared-vehicle stations** (`@jgengine/core/scene/stationClaim`) — `createStationClaim(controller?)` layers facet stations (`steer`/`sails`/`cannon`) on `scene/mount`: `register({ id, kit, stations })`, `claim`/`release`, `controllerOf(vehicleId, facet)`, `facetOf`, `openFacets`, `crew`. One control station drives the hull; the rest ride but command their facet. (Sea of Thieves.)
+- **Shared / group wallet** (`@jgengine/core/economy/sharedWallet`) — `createWalletBook()` holds per-`WalletScope` balances (`userScope`/`groupScope`) beside the per-user `economy/wallet`: `grantTo`/`chargeFrom`/`balanceIn`, with a `contributionOf`/`contributorsOf` ledger tracking who funded a shared pool. (Schedule I company funds, Lethal Company quota.)
+- **Session matchmaking** (`@jgengine/core/multiplayer/matchmaking`) — data-driven browse/filter (`browseSessions`, `matchesFilter`, `quickMatch`) hiding private/closed lobbies, plus join-by-code (`findByJoinCode`, `normalizeJoinCode`, `generateJoinCode`). The node host carries generic `SessionAttributes` (`label`/`mode`/`visibility`/`joinCode`/`tags`) on `GameServerRecord`/`ServerListing` and gains `browseServers` + `joinByCode`; the ws backend exposes `browse` / `joinByCode` / `createSession`. (Fortnite island browse, Web Fishing code lobbies.)
+- **Camera rig library** (`@jgengine/shell`, config types in `@jgengine/core/game/playableGame`) — the single orbit camera is now one of eight rigs, selected and tuned through `PlayableGame.camera` (never by writing camera positions from `onTick`). Set `camera.rig`:
+  - `topDown` — fixed height/pitch/yaw with decoupled follow for ARPG-iso and top-down (Diablo IV/PoE 2/Last Epoch, Hades II); `camera.topDown: { height, pitch, yaw, followSmoothing, zoom }`.
+  - `rts` — free-pan / edge-scroll / rotate / zoom independent of any avatar (The Sims 4, Manor Lords, Two Point Museum); `camera.rts: { panSpeed, edgeScroll, rotateSpeed, bounds, start }`.
+  - `shoulder` — over-the-shoulder with ADS transition and shoulder-swap, reticle decoupled from camera center (Remnant II, Helldivers 2, The First Descendant); `camera.shoulder: { shoulderOffset, distance, ads, side }`.
+  - `lockOn` — yaw bound to the player→target vector with the move axis reinterpreted as strafe (Elden Ring, Sekiro); `camera.lockOn: { targetEntityId?, distance, framingBias, yawSmoothing }`.
+  - `chase` — speed-reactive vehicle chase (speed→FOV curve, spring-arm damping, procedural shake) plus fixed `cockpit`/`hood`/`rear` views (Forza Horizon 5, Rocket League, Trackmania); `camera.chase: { distance, springDamping, fov, shakePerSpeed, view }`.
+- **Every rig accepts `followEntityId: null`** — avatar-less games (city-builders, card games, auto-battlers) can now mount a camera; the orbit rig no longer bails when there is no follow target.
+- **Camera-shake / trauma channel** — every rig reads a shared trauma channel; feed it from any system with `import { cameraShake } from "@jgengine/shell/camera"` (`cameraShake(amplitude, decayPerSecond?)`, amplitude 0..1) or from React via `useCameraShake()`. Tune with `camera.shake: { maxOffset, maxRoll, decayPerSecond, exponent, frequency }`. (Combat hitstop and other systems feed the same channel.)
+- **Cinematic camera + mode-swap cross-fade** — `camera.cinematic: { keyframes: [{ position, lookAt, fov?, duration?, ease? }], loop? }` plays a scripted keyframe path over the active rig, and `camera.transitionSeconds` cross-fades the camera when the rig changes so mode swaps no longer hard-cut.
+- Pure rig math (shake decay/trauma, spring-arm damping, speed→FOV, lerp/cross-fade, offset/strafe vectors, keyframe sampling) is exported from `@jgengine/shell/camera` as testable functions.
+- **Sensors, vision & observer tools** (`@jgengine/core/sensor/*`, renderers in `@jgengine/shell/vision` and `@jgengine/shell/replay`) — a coherent "query hidden/tagged/framed world state and surface it" family:
+  - **Reveal vision** (`sensor/revealQuery`) — `createRevealQuery` is an occlusion-ignoring tagged-entity radius query (`inRadius` already never checks occlusion; this scopes it to catalog-declared tags for a vision readout) paired with a toggleable screen-space reveal effect (`shell/vision/RevealVision`: `RevealHighlights` for through-wall 3D highlights, `RevealScreenTint` for the full-screen tint) — Dark Sight / detective-vision / wallhack-style highlight (Hunt: Showdown).
+  - **Hidden-state probe** (`sensor/hiddenStateProbe`) — `probeHiddenState`/`probeHiddenStateAll` read a hidden zone/entity state variable in range and surface a distance-weighted reading; `shell/vision/HiddenStateProbeHud`'s `SensorReadoutMeter` renders it as a handheld sensor needle (EMF reader/spirit box/thermometer/geiger, Phasmophobia).
+  - **View-frustum sensor** (`sensor/frustumSensor`) — `projectToView`/`framingScore`/`createFrustumSensor` answer "what's in this held camera's view, how well framed, and for how long" (dwell time resets the instant a subject leaves frame); `shell/vision/FrustumSensorHud`'s `FrustumSensorReadout` drives it off the live render camera for a photo-mode HUD (Content Warning).
+  - **Session-recording buffer** (`sensor/recordingBuffer`) — `createRecordingBuffer` appends timestamped snapshots on game-time and seeks/scrubs them for replay, photo mode, or kill-cam; `shell/replay/useSessionRecorder` records an entity's pose every frame.
+  - **`observer` camera rig** (config in `@jgengine/core/game/playableGame`: `ObserverCameraConfig`) — a detached spectator/photo cam bound to any entity or fixed point that reads no player input at all (van CCTV spectate, Forza-style photo mode free cam, Trackmania ghost/kill-cam).
+
+- **Possession** (`@jgengine/core/scene/possession`, `createPossession`) — a player can own N scene entities and switch which one is under active control, distinct from the social party. `ctx.player.possession.own/disown/owns/listOwned(userId, entityId)` tracks ownership; `possess(userId, entityId)` swaps active control (rejecting entities the user doesn't own), flips the previous/next entity's `EntityRole` between `"player"`/`"npc"` (reusing entity control, not forking it), and emits `possession.swapped`. `active(userId)` defaults to `userId` itself until a swap happens. `@jgengine/shell`'s `GamePlayerShell` rebinds WASD movement, targeting, hotbar `from`, and the camera rig's `followEntityId` to the active possessed entity on every swap — no per-game camera glue required.
+- **Form / shapeshift** (`@jgengine/core/scene/form`, `createForms`) — a `form` bundles movement params + an ability-id list + a mesh (reusing the entity's catalog name, so mesh, movement defaults, and receive/role all follow the swap through the existing name-keyed resolution — no parallel mesh system). `ctx.scene.entity.form.register(defs)` in `onInit`; `shapeshift(instanceId, formId, durationSeconds?)` applies the bundle and optionally reverts automatically after `durationSeconds` of **game time** (`ctx.time.after`, so it obeys pause/fast-forward); `revert(instanceId)` reverts early. Emits `form.changed`.
+- **Cosmetic loadouts + emote broadcast** (`@jgengine/core/game/cosmetics` `createCosmetics`; `@jgengine/core/game/social` `Social.emotes`) — `ctx.player.cosmetics.register(defs)` + `apply(userId, loadoutId)` / `equip(userId, slot, cosmeticId)` manage a per-player cosmetic slot map (skin/back/aura/…), emitting `cosmetics.changed`. `ctx.game.social.emotes.play(fromUserId, emoteId, radius?)` broadcasts to nearby **player**-role entities (reusing `scene.entity.inRadius`, not a parallel proximity system) and emits `emote.played` — bind it through the existing `ctx.game.feed` primitive (`feed.bind("emote.played")`) for a HUD feed, no new hook needed.
+- `entityStore`'s `update()` patch now also accepts `name`, so possession/form (and any future system) can retarget an instance's catalog id without despawn/respawn.
+
+An additive layer over effects/projectiles/death that adds melee/action feel. Every model is a renderer-free `@jgengine/core` factory a game composes per entity; `@jgengine/shell` renders the world/HUD side. No existing API moved.
+
+- **Animation state machine** — `@jgengine/core/combat/animationState`: `createAnimationState({ clips })` over `AnimationClip`s whose `FrameRange`s tag `windup | active | recovery | cancel` windows. The root contract combat/defense subscribe to (`inPhase`, `isActive`, `canCancel`, `activeWindowMs`).
+- **Shared accumulator meter** — `@jgengine/core/stats/accumulatorMeter`: `createAccumulatorMeter({ max, mode, decayPerSecond, decayDelayMs, tiers })`, the fill/decay/threshold-fire/tier primitive. `@jgengine/core/combat/breakMeters` builds `createStaggerMeter` (poise/posture break → riposte) and `createBuildupMeter` (bleed/frost/rot proc) on it.
+- **Defensive window + attack tags** — `@jgengine/core/combat/defensiveWindow` (`resolveDefense` / `createDefensiveWindow`, parry/block/dodge evaluated against the attacker's active frames) reading `@jgengine/core/combat/attackTags` (`attackMeta`, unblockable/thrust/sweep/grab; `counters` for Mikiri-style reads).
+- **Combo strings** — `@jgengine/core/combat/comboString`: `advanceCombo` / `createComboRunner` — ordered attacks with stance-conditioned cancel points over the animation SM.
+- **Dash / dodge** — `@jgengine/core/movement/dash`: `createDashState` — directional burst + i-frame window + stamina/cooldown.
+- **Hit reaction, telegraphs, typed damage numbers** — `@jgengine/core/combat/hitReaction` + `ctx.scene.entity.hitReaction(...)` (knockback impulse + hitstop + `combat.hitReaction` shake channel); `@jgengine/core/combat/telegraph` + `ctx.scene.entity.telegraph(...)` (windup→activation ground decal bound to an effect, drawn by the shell); `ctx.scene.entity.floatText({ crit, element, hitType, scale })` styled by `@jgengine/shell/world/floatTextStyle`.
+
+Genre systems over the existing effects/projectiles/targeting/loot primitives. Every model is a renderer-free `@jgengine/core` factory the game ticks on game-time `dt`; `@jgengine/react` adds four-state slot binding hooks. No existing API moved. The ult/streak meters build on the `stats/accumulatorMeter` from the combat-feel layer above.
+
+- **Ability kit** — `@jgengine/core/combat/abilityKit`: `createAbilityKit([{ id, cooldownMs, chargesMax?, resourceCost?, castType? }])` models an ability slot **separate from an inventory item**, exposing the four HUD states `ready | cooldown | no-resource | just-cast` plus charges + cooldown fraction. Resource-agnostic — reports `no-resource` against a supplied `resourceAvailable`, the game spends. (MOBA/ARPG action bars, hero-shooter kits.)
+- **Event-fed meters** — `@jgengine/core/stats/eventMeter`: `createEventMeter({ max, mode, gains, resets?, tiers? })` on the shared accumulator. Mode `"hold"` = ult/adrenaline charge (`feed` combat tags, `ready()`, `consume()`); mode `"reset"` = kill-streak/combo with tiered thresholds that resets on a break tag. (Overwatch/Marvel Rivals ult, Returnal/DMC streak.)
+- **Auto-target policy** — `@jgengine/core/scene/autoTarget`: `selectAutoTarget` / `createAutoTargeter` — zero-input per-tick target selection `nearest | farthest | random | strongest | weakest | first | last` (path-progress aware). (Vampire Survivors auto-fire, Bloons tower priority.)
+- **Resistance matrix** — `@jgengine/core/combat/resistance`: `resolveResistance` / `resistanceScale` — damage-category × target-property → `immune | resist | normal | vulnerable` multiplier over the `receive` gate. (Bloons pop-types, elemental RPG weaknesses.)
+- **Run draft** — `@jgengine/core/game/runDraft`: `createRunDraft` / `createRunModifierStack` — pause, present N weighted picks (`pickWeighted`), choose, stack the modifiers for the run (aggregated onto `stats/statModifiers`). (Vampire Survivors level-ups, Hades boons.)
+- **React** — `@jgengine/react` `useAbilitySlots` / `useAbilitySlot` (four-state snapshots) and `useEventMeter` (ult/streak bar view).
+
+- `@jgengine/core/item/durability` — per-instance item durability + repair. A catalog `DurabilitySpec` (`max`, `wearPerUse`/`wearPerHit`, `disableAtZero`, `repair`); `createDurability`/`wear`/`isDisabled`/`durabilityFraction` for the wear loop, `repairQuote(spec, state, { station?, to? })` for a quote-then-apply repair (material cost scaled by points restored, optional `qualityLossPerRepair` shrinking `max`), and `createDurabilityTracker()` to hold state per instance id. For weapon/tool/armor degradation repaired at stations.
+- `@jgengine/core/item/affix` — rarity-weighted procgen roller. `createAffixRoller({ pools, rarities })` turns `base × rarity` into `{ rolled affixes, computed stats, name }`: draws `affixCount` distinct affixes without replacement (weighted via the engine `pickWeighted`), computes stats (base × rarity scale, then `add` then `mul` affixes), and composes a name from rarity + prefix/suffix parts. `seededRng(seed)` gives deterministic drops. For looter-shooter / ARPG generated weapons.
+- `@jgengine/core/item/modularItem` — parts-in-typed-slots assembly. `ModularItemDef` with category-constrained `MountSlotDef`s; `install`/`uninstall` validate slot + category + occupancy, `computeEffectiveStats` rolls part `stats` (additive) then `multipliers` over the frame's `baseStats`, `missingRequiredSlots`/`isComplete` gate a buildable whole; `createModularItem(def)` is the stateful wrapper. For piece-by-piece guns and mech loadouts.
+- `@jgengine/core/inventory/storageTier` — tiered extraction-economy inventory. A `tier: "carried" | "banked"` on inventory containers (`InventoryDeclaration.tier`); `partitionOnDeath` splits a death snapshot into kept (banked) vs lost (carried) with merged stacks, `createDeliveryQueue()` is the delayed-delivery (insurance) hook (`schedule`/`due`/`claimDue` on the game clock), `insureLost` filters the lost set to insured items with a delayed `deliverAt`, and `resolveConsolation` yields a baseline loadout id (apply via `applyLoadout`) for the post-death consolation grant. The inventory foundation the extraction session/round machines build on.
+- `InventoryDeclaration` (`@jgengine/core/game/defineGame`) gained an optional `tier?: StorageTier` flag so containers declare carried-vs-banked storage directly.
+- `@jgengine/core/session/contestedChannel` — the interrupt-on-damage progress objective (plant/defuse, cash-out, urn deposit, hold-to-extract). `createContestedChannel({ duration, interruptOnDamage?, resetOnInterrupt?, favorability?, ratePerOccupant?, contested?, decayRate? })`: `start(team)`, `tick(dt, occupants)` (per-team occupancy → `start`/`tick`/`contested`/`paused`/`complete` events), `damage()` interrupts. `favorability`/`ratePerOccupant` scale the fill rate; `contested: "pause" | "decay"` handles a contesting team.
+- `@jgengine/core/session/roundState` — the buy→live→end match machine. `createRoundState({ phases, teams, maxRounds?, winReward?, lossBonus? })`: `tick(dt)` runs phase timers and auto-advances rounds, `concludeRound(winner)` settles win + escalating loss-bonus economy (`lossBonusFor`), `onPhaseEnd(hook)` gates commerce/spawns, `match.end` fires at `maxRounds`.
+- `@jgengine/core/combat/downed` — the alive→downed→dead revive chain. `createDownedState({ bleedoutSeconds, reviveSeconds?, reviveHealthFraction?, banner? })`: `down`/`tick` (bleedout → `died` + optional banner), `revive(id, dt)` accumulates ally hold time, `finish` executes, `respawnFromBanner` beacons back. Sits in front of engine death resolution.
+- `@jgengine/core/session/ring` — the shrinking battle-royale safe zone. `RingConfig` = `{ center, phases }`; `ringSampleAt(config, t)`/`createRing` give the live `{ center, radius, damagePerSecond }` (interpolated on the game clock), `isOutside`/`distanceOutside`/`damageOutside(t, dt, positions)` for out-of-bounds DoT.
+- `@jgengine/core/session/extraction` — the raid-scoped extract-to-bank session, composed from the contested channel + `inventory/storageTier`. `createRaidSession({ extracts, insurance?, consolation? })`: `beginExtract`/`tickExtract`/`damage` drive hold-to-leave, `resolveExtraction` banks everything carried, `resolveDeath` partitions/insures/consoles via storage tiers, `claimDeliveries(now)` drains insured returns.
+- `@jgengine/core/runtime/persistenceScope` — run-vs-meta persistence split with reset boundaries. `partitionScopes`/`resetRun`/`mergeScopes` over flat records, `clearRunFields`/`applyRunReset` over player rows/profiles, `planScenarioReset(...)` normalizes a season/scenario wipe applied through the new optional `HostPersistence.resetScenario` — implemented by `@jgengine/sql` (deletes a server's chunks + session and run-resets each profile in one transaction, keeping account meta).
 
-_Nothing yet._
 
 ## 0.6.0
 

package/dist/components.d.ts

@@ -1,8 +1,11 @@
 import { type ReactNode } from "react";
 import type { InventorySlot } from "@jgengine/core/inventory/inventoryModel";
 import type { ProximityPrompt as ProximityPromptDef } from "@jgengine/core/interaction/proximityPrompt";
+import { type SkillCheckConfig, type SkillCheckResult } from "@jgengine/core/interaction/skillCheck";
+import { type QteStep } from "@jgengine/core/interaction/qte";
 import type { FeedEntry } from "@jgengine/core/game/feed";
 import type { StatLevelUpEvent } from "@jgengine/core/game/events";
+import { type CheckAdvantage, type CheckResult } from "@jgengine/core/stats/rollCheck";
 export declare function SlotGrid({ inventoryId, className, renderSlot, }: {
     inventoryId: string;
     className?: string;
@@ -33,12 +36,27 @@ export declare function KeybindRow({ action, keys, className, }: {
     keys: readonly string[];
     className?: string;
 }): import("react").JSX.Element;
+export interface DialogueCheck {
+    label?: string;
+    modifier: number;
+    dc: number;
+    advantage?: CheckAdvantage;
+}
 export interface DialogueChoice {
     label: string;
     invoke: {
         command: string;
         args?: unknown;
     } | null;
+    check?: DialogueCheck;
+    onSuccess?: {
+        command: string;
+        args?: unknown;
+    } | null;
+    onFailure?: {
+        command: string;
+        args?: unknown;
+    } | null;
 }
 export type DialogueLine = {
     speaker: string;
@@ -50,10 +68,42 @@ export interface DialogueDef {
     id: string;
     lines: readonly DialogueLine[];
 }
-export declare function DialogueBox({ dialogue, onChoice, className, }: {
+export declare function resolveDialogueInvoke(choice: DialogueChoice, result: CheckResult | null): {
+    command: string;
+    args?: unknown;
+} | null;
+export declare function DialogueBox({ dialogue, onChoice, rng, className, lineClassName, speakerClassName, choicesClassName, choiceClassName, checkClassName, }: {
     dialogue: DialogueDef;
-    onChoice?: (choice: DialogueChoice) => void;
+    onChoice?: (choice: DialogueChoice, result: CheckResult | null) => void;
+    rng?: () => number;
     className?: string;
+    lineClassName?: string;
+    speakerClassName?: string;
+    choicesClassName?: string;
+    choiceClassName?: string;
+    checkClassName?: string;
+}): import("react").JSX.Element;
+export declare function SkillCheckBar({ config, startedAt, className, trackClassName, zoneClassName, markerClassName, renderStatus, }: {
+    config: SkillCheckConfig;
+    startedAt: number;
+    className?: string;
+    trackClassName?: string;
+    zoneClassName?: string;
+    markerClassName?: string;
+    renderStatus?: (result: SkillCheckResult) => ReactNode;
+}): import("react").JSX.Element;
+export declare function QteTrack({ steps, startedAt, className, stepClassName, activeClassName, doneClassName, }: {
+    steps: readonly QteStep[];
+    startedAt: number;
+    className?: string;
+    stepClassName?: string;
+    activeClassName?: string;
+    doneClassName?: string;
+}): import("react").JSX.Element;
+export declare function CaptureOdds({ chance, className, fillClassName, }: {
+    chance: number;
+    className?: string;
+    fillClassName?: string;
 }): import("react").JSX.Element;
 export declare function ToastStack({ action, limit, className, renderToast, }: {
     action: string;

package/dist/components.js

@@ -1,5 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from "react";
+import { evaluateSkillCheck, } from "@jgengine/core/interaction/skillCheck";
+import { pendingQteStep } from "@jgengine/core/interaction/qte";
+import { rollCheck } from "@jgengine/core/stats/rollCheck";
 import { useGameContext } from "./provider.js";
 import { useCurrency, useEntityStat, useFeed, useInventory, useLocalPlayerDead } from "./hooks.js";
 export function SlotGrid({ inventoryId, className, renderSlot, }) {
@@ -40,8 +43,61 @@ export function Screen({ id, open = true, className, children, }) {
 export function KeybindRow({ action, keys, className, }) {
     return (_jsxs("div", { className: className, "data-action": action, children: [_jsx("span", { children: action }), keys.map((key) => (_jsx("kbd", { children: key }, key)))] }));
 }
-export function DialogueBox({ dialogue, onChoice, className, }) {
-    return (_jsx("div", { className: className, "data-dialogue": dialogue.id, children: dialogue.lines.map((line, index) => "choices" in line ? (_jsx("div", { "data-choices": true, children: line.choices.map((choice) => (_jsx("button", { type: "button", onClick: () => onChoice?.(choice), children: choice.label }, choice.label))) }, index)) : (_jsxs("p", { children: [_jsx("span", { "data-speaker": true, children: line.speaker }), _jsx("span", { children: line.text })] }, index))) }));
+export function resolveDialogueInvoke(choice, result) {
+    if (result === null)
+        return choice.invoke;
+    return result.success ? (choice.onSuccess ?? choice.invoke) : (choice.onFailure ?? choice.invoke);
+}
+export function DialogueBox({ dialogue, onChoice, rng, className, lineClassName, speakerClassName, choicesClassName, choiceClassName, checkClassName, }) {
+    return (_jsx("div", { className: className, "data-dialogue": dialogue.id, children: dialogue.lines.map((line, index) => "choices" in line ? (_jsx("div", { className: choicesClassName, "data-choices": true, children: line.choices.map((choice) => (_jsxs("button", { type: "button", className: choiceClassName, "data-dc": choice.check?.dc, onClick: () => onChoice?.(choice, choice.check === undefined ? null : rollCheck(choice.check, rng)), children: [_jsx("span", { children: choice.label }), choice.check !== undefined && (_jsxs("span", { className: checkClassName, "data-check": true, children: [choice.check.label ?? "Check", " DC ", choice.check.dc, choice.check.advantage !== undefined && choice.check.advantage !== "normal"
+                                ? ` (${choice.check.advantage})`
+                                : ""] }))] }, choice.label))) }, index)) : (_jsxs("p", { className: lineClassName, children: [_jsx("span", { className: speakerClassName, "data-speaker": true, children: line.speaker }), _jsx("span", { children: line.text })] }, index))) }));
+}
+export function SkillCheckBar({ config, startedAt, className, trackClassName, zoneClassName, markerClassName, renderStatus, }) {
+    const ctx = useGameContext();
+    const [, tick] = useState(0);
+    useEffect(() => {
+        let frame;
+        const step = () => {
+            tick((n) => n + 1);
+            frame = requestAnimationFrame(step);
+        };
+        frame = requestAnimationFrame(step);
+        return () => cancelAnimationFrame(frame);
+    }, []);
+    const elapsed = Math.max(0, ctx.time.now() - startedAt);
+    const result = evaluateSkillCheck(config, elapsed);
+    const zoneLeft = (result.zone.start / config.trackWidth) * 100;
+    const zoneWidth = ((result.zone.end - result.zone.start) / config.trackWidth) * 100;
+    const markerLeft = (result.markerPosition / config.trackWidth) * 100;
+    return (_jsxs("div", { className: className, "data-skill-check": true, "data-in-zone": result.success, "data-timed-out": result.timedOut, children: [_jsxs("div", { className: trackClassName, "data-track": true, style: { position: "relative" }, children: [_jsx("div", { className: zoneClassName, "data-zone": true, style: { position: "absolute", left: `${zoneLeft}%`, width: `${zoneWidth}%`, height: "100%" } }), _jsx("div", { className: markerClassName, "data-marker": true, style: { position: "absolute", left: `${markerLeft}%`, height: "100%" } })] }), renderStatus?.(result)] }));
+}
+export function QteTrack({ steps, startedAt, className, stepClassName, activeClassName, doneClassName, }) {
+    const ctx = useGameContext();
+    const [, tick] = useState(0);
+    useEffect(() => {
+        let frame;
+        const step = () => {
+            tick((n) => n + 1);
+            frame = requestAnimationFrame(step);
+        };
+        frame = requestAnimationFrame(step);
+        return () => cancelAnimationFrame(frame);
+    }, []);
+    const elapsed = Math.max(0, ctx.time.now() - startedAt);
+    const active = pendingQteStep(steps, elapsed);
+    return (_jsx("div", { className: className, "data-qte": true, children: steps.map((step) => {
+            const isActive = active?.id === step.id;
+            const isDone = elapsed > step.windowEnd;
+            const classes = [stepClassName, isActive ? activeClassName : isDone ? doneClassName : undefined]
+                .filter(Boolean)
+                .join(" ");
+            return (_jsx("div", { className: classes.length > 0 ? classes : undefined, "data-qte-step": step.id, "data-active": isActive, "data-done": isDone, children: step.action }, step.id));
+        }) }));
+}
+export function CaptureOdds({ chance, className, fillClassName, }) {
+    const percent = Math.round(Math.min(1, Math.max(0, chance)) * 100);
+    return (_jsxs("div", { className: className, role: "progressbar", "aria-valuemin": 0, "aria-valuemax": 100, "aria-valuenow": percent, "data-capture-odds": percent, children: [_jsx("div", { className: fillClassName, style: { width: `${percent}%`, height: "100%" } }), _jsxs("span", { "data-capture-odds-label": true, style: { position: "relative", zIndex: 1 }, children: [percent, "%"] })] }));
 }
 function defaultToast(entry) {
     const data = entry.data;

package/dist/dragLayer.d.ts

@@ -0,0 +1,67 @@
+import { type CSSProperties, type PointerEvent as ReactPointerEvent, type ReactNode } from "react";
+import { type Cell, type Rotation } from "@jgengine/core/inventory/shapedGrid";
+export interface DragPayload<T> {
+    id: string;
+    value: T;
+    rotation: Rotation;
+}
+export interface DragState<T> {
+    payload: DragPayload<T> | null;
+    point: {
+        x: number;
+        y: number;
+    };
+    origin: {
+        x: number;
+        y: number;
+    };
+    overTarget: string | null;
+    overCell: Cell | null;
+}
+export interface DropInfo<T> {
+    payload: DragPayload<T>;
+    target: string | null;
+    cell: Cell | null;
+    point: {
+        x: number;
+        y: number;
+    };
+}
+export interface DragLayer<T> {
+    state: DragState<T>;
+    dragging: boolean;
+    beginDrag(payload: {
+        id: string;
+        value: T;
+        rotation?: Rotation;
+    }, event: ReactPointerEvent): void;
+    rotate(quarterTurns?: number): void;
+    setTarget(target: string | null, cell?: Cell | null): void;
+    endDrag(): DropInfo<T> | null;
+    cancel(): void;
+}
+export declare function useDragLayer<T>(options?: {
+    onDrop?: (info: DropInfo<T>) => void;
+}): DragLayer<T>;
+export declare function DragGhost<T>({ layer, className, style, children, }: {
+    layer: DragLayer<T>;
+    className?: string;
+    style?: CSSProperties;
+    children?: (payload: DragPayload<T>) => ReactNode;
+}): import("react").JSX.Element | null;
+export declare function DraggableCard<T>({ id, value, layer, className, children, onRotate, }: {
+    id: string;
+    value: T;
+    layer: DragLayer<T>;
+    className?: string;
+    children?: ReactNode;
+    onRotate?: boolean;
+}): import("react").JSX.Element;
+export declare function DropZone<T>({ id, layer, className, activeClassName, cellSize, children, }: {
+    id: string;
+    layer: DragLayer<T>;
+    className?: string;
+    activeClassName?: string;
+    cellSize?: number;
+    children?: ReactNode;
+}): import("react").JSX.Element;

package/dist/dragLayer.js

@@ -0,0 +1,143 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useMemo, useRef, useState, } from "react";
+import { cellFromPoint, } from "@jgengine/core/inventory/shapedGrid";
+const EMPTY_POINT = { x: 0, y: 0 };
+export function useDragLayer(options) {
+    const [state, setState] = useState({
+        payload: null,
+        point: EMPTY_POINT,
+        origin: EMPTY_POINT,
+        overTarget: null,
+        overCell: null,
+    });
+    const moveRef = useRef(null);
+    const detach = useCallback(() => {
+        if (moveRef.current !== null) {
+            window.removeEventListener("pointermove", moveRef.current);
+            moveRef.current = null;
+        }
+    }, []);
+    const beginDrag = useCallback((payload, event) => {
+        const point = { x: event.clientX, y: event.clientY };
+        setState({
+            payload: { id: payload.id, value: payload.value, rotation: payload.rotation ?? 0 },
+            point,
+            origin: point,
+            overTarget: null,
+            overCell: null,
+        });
+        const onMove = (moveEvent) => {
+            setState((prev) => prev.payload === null
+                ? prev
+                : { ...prev, point: { x: moveEvent.clientX, y: moveEvent.clientY } });
+        };
+        detach();
+        moveRef.current = onMove;
+        window.addEventListener("pointermove", onMove);
+    }, [detach]);
+    const rotate = useCallback((quarterTurns = 1) => {
+        setState((prev) => prev.payload === null
+            ? prev
+            : {
+                ...prev,
+                payload: {
+                    ...prev.payload,
+                    rotation: (((prev.payload.rotation + quarterTurns) % 4) + 4) % 4,
+                },
+            });
+    }, []);
+    const setTarget = useCallback((target, cell = null) => {
+        setState((prev) => ({ ...prev, overTarget: target, overCell: cell }));
+    }, []);
+    const reset = useCallback(() => {
+        detach();
+        setState({
+            payload: null,
+            point: EMPTY_POINT,
+            origin: EMPTY_POINT,
+            overTarget: null,
+            overCell: null,
+        });
+    }, [detach]);
+    const endDrag = useCallback(() => {
+        let info = null;
+        setState((prev) => {
+            if (prev.payload !== null) {
+                info = {
+                    payload: prev.payload,
+                    target: prev.overTarget,
+                    cell: prev.overCell,
+                    point: prev.point,
+                };
+            }
+            return prev;
+        });
+        if (info !== null)
+            options?.onDrop?.(info);
+        reset();
+        return info;
+    }, [options, reset]);
+    return {
+        state,
+        dragging: state.payload !== null,
+        beginDrag,
+        rotate,
+        setTarget,
+        endDrag,
+        cancel: reset,
+    };
+}
+export function DragGhost({ layer, className, style, children, }) {
+    if (layer.state.payload === null)
+        return null;
+    const { x, y } = layer.state.point;
+    return (_jsx("div", { className: className, "data-drag-ghost": "", style: {
+            position: "fixed",
+            left: x,
+            top: y,
+            transform: `translate(-50%, -50%) rotate(${layer.state.payload.rotation * 90}deg)`,
+            pointerEvents: "none",
+            zIndex: 1000,
+            ...style,
+        }, children: children?.(layer.state.payload) }));
+}
+export function DraggableCard({ id, value, layer, className, children, onRotate, }) {
+    const isDragging = layer.state.payload?.id === id;
+    return (_jsx("div", { className: className, "data-card": id, "data-dragging": isDragging ? "" : undefined, onPointerDown: (event) => {
+            event.preventDefault();
+            layer.beginDrag({ id, value }, event);
+        }, onPointerUp: () => {
+            if (layer.dragging)
+                layer.endDrag();
+        }, onContextMenu: (event) => {
+            if (onRotate === false)
+                return;
+            event.preventDefault();
+            if (layer.dragging)
+                layer.rotate(1);
+        }, children: children }));
+}
+export function DropZone({ id, layer, className, activeClassName, cellSize, children, }) {
+    const ref = useRef(null);
+    const active = layer.state.overTarget === id && layer.dragging;
+    const resolveCell = useCallback((event) => {
+        if (cellSize === undefined || ref.current === null)
+            return null;
+        const rect = ref.current.getBoundingClientRect();
+        return cellFromPoint({ x: event.clientX - rect.left, y: event.clientY - rect.top }, cellSize);
+    }, [cellSize]);
+    const composed = useMemo(() => [className, active ? activeClassName : undefined].filter(Boolean).join(" ") || undefined, [className, active, activeClassName]);
+    return (_jsx("div", { ref: ref, className: composed, "data-dropzone": id, "data-active": active ? "" : undefined, onPointerEnter: (event) => {
+            if (layer.dragging)
+                layer.setTarget(id, resolveCell(event));
+        }, onPointerMove: (event) => {
+            if (layer.dragging && layer.state.overTarget === id)
+                layer.setTarget(id, resolveCell(event));
+        }, onPointerLeave: () => {
+            if (layer.dragging && layer.state.overTarget === id)
+                layer.setTarget(null, null);
+        }, onPointerUp: () => {
+            if (layer.dragging)
+                layer.endDrag();
+        }, children: children }));
+}

package/dist/hooks.d.ts

@@ -1,4 +1,6 @@
 import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { AbilityKit, AbilitySlotSnapshot } from "@jgengine/core/combat/abilityKit";
+import type { EventMeter } from "@jgengine/core/stats/eventMeter";
 import type { GameEvents } from "@jgengine/core/game/events";
 import type { FeedEntry } from "@jgengine/core/game/feed";
 import type { QuestInstance } from "@jgengine/core/game/quest";
@@ -8,6 +10,8 @@ import type { InventorySlot } from "@jgengine/core/inventory/inventoryModel";
 import type { StatValue } from "@jgengine/core/scene/entityStats";
 import type { SceneEntity } from "@jgengine/core/scene/entityStore";
 import type { SceneObject } from "@jgengine/core/scene/objectStore";
+import type { RosterEntry } from "@jgengine/core/scene/roster";
+import type { WorldItemRecord } from "@jgengine/core/game/worldItem";
 import type { ClockSnapshot, SimClock } from "@jgengine/core/time/simClock";
 import { type PositionedPrompt } from "@jgengine/core/interaction/proximityPrompt";
 export declare function useGameStore<T>(selector: (ctx: GameContext) => T): T;
@@ -21,6 +25,9 @@ export declare function usePlayer(): {
 };
 export declare function useSceneEntities(): readonly SceneEntity[];
 export declare function useSceneObjects(): readonly SceneObject[];
+export declare function useWorldItems(): readonly WorldItemRecord[];
+/** Nearest ground item within `radius` of the local player — drives a pickup prompt/highlight. */
+export declare function useNearestWorldItem(radius: number): WorldItemRecord | null;
 export declare function useEntityStat(instanceId: string, statId: string): StatValue | null;
 export declare function useTarget(fromInstanceId: string): string | null;
 export declare function useInventory(inventoryId: string): readonly InventorySlot[];
@@ -33,6 +40,7 @@ export declare function useQuestJournal(): QuestInstance[];
 export declare function useFriends(): FriendEntry[];
 export declare function useParty(): PartyMemberEntry[];
 export declare function usePresence(userId: string): PresenceInfo;
+export declare function useRoster(userId?: string): readonly RosterEntry[];
 export declare function useLeaderboard(stat: string, options: {
     scope: LeaderboardScope;
     limit?: number;
@@ -46,3 +54,15 @@ export declare function useGameClock(): ClockSnapshot & {
     controls: SimClock;
 };
 export declare function useActivePrompt<T extends PositionedPrompt>(prompts?: readonly T[]): T | null;
+export interface AbilitySlotBindingOptions {
+    intervalMs?: number;
+}
+export declare function useAbilitySlots(kit: AbilityKit, resourceAvailable?: number, options?: AbilitySlotBindingOptions): AbilitySlotSnapshot[];
+export declare function useAbilitySlot(kit: AbilityKit, slotId: string, resourceAvailable?: number, options?: AbilitySlotBindingOptions): AbilitySlotSnapshot | null;
+export interface EventMeterView {
+    value: number;
+    fraction: number;
+    tier: string | null;
+    ready: boolean;
+}
+export declare function useEventMeter(meter: EventMeter, options?: AbilitySlotBindingOptions): EventMeterView;

package/dist/hooks.js

@@ -1,4 +1,4 @@
-import { useMemo, useSyncExternalStore } from "react";
+import { useEffect, useMemo, useState, useSyncExternalStore } from "react";
 import { resolveActivePrompt, } from "@jgengine/core/interaction/proximityPrompt";
 import { useGameContext } from "./provider.js";
 export function useGameStore(selector) {
@@ -20,6 +20,19 @@ export function useSceneEntities() {
 export function useSceneObjects() {
     return useGameStore((ctx) => ctx.scene.object.list());
 }
+export function useWorldItems() {
+    return useGameStore((ctx) => ctx.scene.worldItem.list());
+}
+/** Nearest ground item within `radius` of the local player — drives a pickup prompt/highlight. */
+export function useNearestWorldItem(radius) {
+    return useGameStore((ctx) => {
+        const player = localPlayerEntity(ctx);
+        if (player === null)
+            return null;
+        const instanceId = ctx.scene.worldItem.nearestInRadius(player.position, radius);
+        return instanceId === null ? null : ctx.scene.worldItem.get(instanceId);
+    });
+}
 export function useEntityStat(instanceId, statId) {
     return useGameStore((ctx) => ctx.scene.entity.stats.get(instanceId, statId));
 }
@@ -47,6 +60,9 @@ export function useParty() {
 export function usePresence(userId) {
     return useGameStore((ctx) => ctx.game.social.presence.get(userId));
 }
+export function useRoster(userId) {
+    return useGameStore((ctx) => ctx.game.roster.list(userId ?? ctx.player.userId));
+}
 export function useLeaderboard(stat, options) {
     return useGameStore((ctx) => ctx.game.leaderboard.getTop(stat, options));
 }
@@ -79,3 +95,26 @@ export function useActivePrompt(prompts) {
         return resolveActivePrompt({ x: player.position[0], z: player.position[2] }, prompts);
     });
 }
+function useEngineHeartbeat(intervalMs) {
+    const ctx = useGameContext();
+    useSyncExternalStore(ctx.subscribe, ctx.version, ctx.version);
+    const [, setTick] = useState(0);
+    useEffect(() => {
+        if (intervalMs <= 0 || typeof window === "undefined")
+            return undefined;
+        const id = window.setInterval(() => setTick((current) => current + 1), intervalMs);
+        return () => window.clearInterval(id);
+    }, [intervalMs]);
+}
+export function useAbilitySlots(kit, resourceAvailable, options) {
+    useEngineHeartbeat(options?.intervalMs ?? 80);
+    return kit.snapshot(resourceAvailable);
+}
+export function useAbilitySlot(kit, slotId, resourceAvailable, options) {
+    useEngineHeartbeat(options?.intervalMs ?? 80);
+    return kit.state(slotId, resourceAvailable);
+}
+export function useEventMeter(meter, options) {
+    useEngineHeartbeat(options?.intervalMs ?? 80);
+    return { value: meter.value(), fraction: meter.fraction(), tier: meter.tier(), ready: meter.ready() };
+}

package/dist/index.d.ts

@@ -2,3 +2,5 @@ export * from "./provider.js";
 export * from "./hooks.js";
 export * from "./components.js";
 export * from "./engineStore.js";
+export * from "./dragLayer.js";
+export * from "./map.js";

package/dist/index.js

@@ -2,3 +2,5 @@ export * from "./provider.js";
 export * from "./hooks.js";
 export * from "./components.js";
 export * from "./engineStore.js";
+export * from "./dragLayer.js";
+export * from "./map.js";

package/dist/map.d.ts

@@ -0,0 +1,68 @@
+import { type ReactNode } from "react";
+import type { FogField } from "@jgengine/core/world/fog";
+import { type MapMarker, type MarkerKindStyle, type MarkerSet } from "@jgengine/core/world/markers";
+import { type WorldXZ } from "@jgengine/core/world/minimap";
+export declare function useMarkers(markers: MarkerSet): readonly MapMarker[];
+export declare function useFog(fog: FogField): ReturnType<FogField["cells"]>;
+export interface MinimapProps {
+    markers: MarkerSet;
+    center: WorldXZ;
+    worldRadius: number;
+    fog?: FogField;
+    size?: number;
+    heading?: number;
+    rotate?: boolean;
+    kindStyles?: Record<string, MarkerKindStyle>;
+    background?: string;
+    /** World bounds the `background` image spans, so it pans correctly under a player-centered map. */
+    mapBounds?: MapBounds;
+    className?: string;
+    title?: string;
+    children?: ReactNode;
+}
+export interface MapBounds {
+    minX: number;
+    minZ: number;
+    maxX: number;
+    maxZ: number;
+}
+/**
+ * Framed circular minimap: optional baked terrain background, reveal-on-event
+ * fog overlay, categorized marker icons, and a facing arrow. Reads a core
+ * `MarkerSet` / `FogField`; supply your own `kindStyles` palette to reskin.
+ */
+export declare function Minimap({ markers, center, worldRadius, fog, size, heading, rotate, kindStyles, background, mapBounds, className, title, children, }: MinimapProps): ReactNode;
+export interface CompassProps {
+    heading: number;
+    center?: WorldXZ;
+    markers?: MarkerSet;
+    width?: number;
+    fov?: number;
+    kindStyles?: Record<string, MarkerKindStyle>;
+    className?: string;
+}
+/**
+ * Horizontal compass strip centered on the player's facing bearing, with the
+ * eight cardinals and optional marker pips (bearing to each `MarkerSet` entry).
+ */
+export declare function Compass({ heading, center, markers, width, fov, kindStyles, className, }: CompassProps): ReactNode;
+export interface WorldMapProps {
+    markers: MarkerSet;
+    bounds: MapBounds;
+    player?: WorldXZ;
+    heading?: number;
+    fog?: FogField;
+    background?: string;
+    width?: number;
+    height?: number;
+    kindStyles?: Record<string, MarkerKindStyle>;
+    className?: string;
+    title?: string;
+    onClose?: () => void;
+}
+/**
+ * Full-bounds top-down world map (the "press M" overlay): baked terrain
+ * background, reveal-on-event fog, all markers with labels, and the player.
+ * Rectangular linear projection over the supplied world `bounds`.
+ */
+export declare function WorldMap({ markers, bounds, player, heading, fog, background, width, height, kindStyles, className, title, onClose, }: WorldMapProps): ReactNode;

package/dist/map.js

@@ -0,0 +1,210 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useSyncExternalStore } from "react";
+import { DEFAULT_MARKER_KINDS, markerKindStyle, } from "@jgengine/core/world/markers";
+import { bearingToCardinal, clampToMinimapEdge, compassBearing, projectToMinimap, relativeBearing, } from "@jgengine/core/world/minimap";
+export function useMarkers(markers) {
+    return useSyncExternalStore(markers.subscribe, markers.snapshot, markers.snapshot);
+}
+export function useFog(fog) {
+    return useSyncExternalStore(fog.subscribe, fog.cells, fog.cells);
+}
+/**
+ * Framed circular minimap: optional baked terrain background, reveal-on-event
+ * fog overlay, categorized marker icons, and a facing arrow. Reads a core
+ * `MarkerSet` / `FogField`; supply your own `kindStyles` palette to reskin.
+ */
+export function Minimap({ markers, center, worldRadius, fog, size = 176, heading = 0, rotate = false, kindStyles = DEFAULT_MARKER_KINDS, background, mapBounds, className, title = "Map", children, }) {
+    const markerList = useMarkers(markers);
+    const fogCells = useSyncExternalStore(fog?.subscribe ?? NO_SUBSCRIBE, fog?.cells ?? NULL_CELLS, fog?.cells ?? NULL_CELLS);
+    const view = {
+        center,
+        worldRadius,
+        size,
+        ...(rotate ? { rotate: -heading } : {}),
+    };
+    const half = size / 2;
+    const clipId = `mm-clip-${size}`;
+    const sorted = [...markerList].sort((a, b) => markerKindStyle(a.kind, kindStyles).priority - markerKindStyle(b.kind, kindStyles).priority);
+    const fogRects = [];
+    if (fogCells !== null) {
+        const cellPx = (fogCells.cellSize / worldRadius) * half;
+        for (let row = 0; row < fogCells.rows; row += 1) {
+            for (let col = 0; col < fogCells.cols; col += 1) {
+                if (fogCells.revealed[row * fogCells.cols + col])
+                    continue;
+                const worldX = fogCells.minX + (col + 0.5) * fogCells.cellSize;
+                const worldZ = fogCells.minZ + (row + 0.5) * fogCells.cellSize;
+                const projected = projectToMinimap([worldX, worldZ], view);
+                if (projected.distance > worldRadius + fogCells.cellSize)
+                    continue;
+                fogRects.push(_jsx("rect", { x: projected.x - cellPx / 2 - 0.5, y: projected.y - cellPx / 2 - 0.5, width: cellPx + 1, height: cellPx + 1, fill: "#0b0f14", opacity: 0.82 }, `fog-${col}-${row}`));
+            }
+        }
+    }
+    return (_jsxs("div", { className: className, "data-minimap": true, style: {
+            width: size,
+            borderRadius: 14,
+            padding: 8,
+            background: "linear-gradient(160deg, rgba(24,28,36,0.94), rgba(12,15,20,0.94))",
+            border: "1px solid rgba(148,163,184,0.28)",
+            boxShadow: "0 10px 30px rgba(0,0,0,0.45)",
+            color: "#e2e8f0",
+            fontFamily: "ui-sans-serif, system-ui, sans-serif",
+        }, children: [_jsxs("div", { style: {
+                    display: "flex",
+                    justifyContent: "space-between",
+                    alignItems: "center",
+                    marginBottom: 6,
+                    fontSize: 10,
+                    letterSpacing: 1.4,
+                    textTransform: "uppercase",
+                    color: "rgba(203,213,225,0.75)",
+                }, children: [_jsx("span", { children: title }), _jsx("span", { style: { color: "rgba(148,163,184,0.6)" }, children: bearingToCardinal(heading) })] }), _jsxs("svg", { width: size, height: size, viewBox: `0 0 ${size} ${size}`, "data-minimap-canvas": true, children: [_jsx("defs", { children: _jsx("clipPath", { id: clipId, children: _jsx("circle", { cx: half, cy: half, r: half - 1 }) }) }), _jsxs("g", { clipPath: `url(#${clipId})`, children: [_jsx("circle", { cx: half, cy: half, r: half - 1, fill: "#1c2733" }), background !== undefined
+                                ? (() => {
+                                    if (mapBounds === undefined) {
+                                        return (_jsx("image", { href: background, x: 0, y: 0, width: size, height: size, preserveAspectRatio: "xMidYMid slice", opacity: 0.9 }));
+                                    }
+                                    const pxPerWorld = half / worldRadius;
+                                    return (_jsx("image", { href: background, x: half + (mapBounds.minX - center[0]) * pxPerWorld, y: half + (mapBounds.minZ - center[1]) * pxPerWorld, width: (mapBounds.maxX - mapBounds.minX) * pxPerWorld, height: (mapBounds.maxZ - mapBounds.minZ) * pxPerWorld, preserveAspectRatio: "none", opacity: 0.92 }));
+                                })()
+                                : null, fogRects, _jsx("circle", { cx: half, cy: half, r: half - 1, fill: "none", stroke: "rgba(148,163,184,0.12)" }), sorted.map((marker) => {
+                                const style = markerKindStyle(marker.kind, kindStyles);
+                                const projected = projectToMinimap(marker.position, view);
+                                const at = projected.inside ? projected : clampToMinimapEdge(projected, size);
+                                return (_jsxs("g", { "data-marker-kind": marker.kind, children: [_jsx("circle", { cx: at.x, cy: at.y, r: 7, fill: "rgba(2,6,12,0.55)" }), _jsx("text", { x: at.x, y: at.y + 3.5, textAnchor: "middle", fontSize: 10, fill: style.color, style: { fontWeight: 700 }, children: style.glyph })] }, marker.id));
+                            }), _jsx("g", { transform: `translate(${half} ${half}) rotate(${(rotate ? 0 : heading) * (180 / Math.PI)})`, children: _jsx("path", { d: "M0,-9 L6,7 L0,3 L-6,7 Z", fill: "#4ade80", stroke: "#052e16", strokeWidth: 0.75 }) })] }), _jsx("circle", { cx: half, cy: half, r: half - 1, fill: "none", stroke: "rgba(148,163,184,0.4)", strokeWidth: 1.5 }), _jsx("text", { x: half, y: 13, textAnchor: "middle", fontSize: 11, fill: "rgba(226,232,240,0.9)", style: { fontWeight: 700 }, children: "N" })] }), children] }));
+}
+const NO_SUBSCRIBE = () => () => undefined;
+const NULL_CELLS = () => null;
+const EMPTY_MARKERS_VALUE = [];
+const EMPTY_MARKERS = () => EMPTY_MARKERS_VALUE;
+const COMPASS_TICKS = [
+    { cardinal: "N", bearing: 0 },
+    { cardinal: "NE", bearing: Math.PI / 4 },
+    { cardinal: "E", bearing: Math.PI / 2 },
+    { cardinal: "SE", bearing: (3 * Math.PI) / 4 },
+    { cardinal: "S", bearing: Math.PI },
+    { cardinal: "SW", bearing: (5 * Math.PI) / 4 },
+    { cardinal: "W", bearing: (3 * Math.PI) / 2 },
+    { cardinal: "NW", bearing: (7 * Math.PI) / 4 },
+];
+/**
+ * Horizontal compass strip centered on the player's facing bearing, with the
+ * eight cardinals and optional marker pips (bearing to each `MarkerSet` entry).
+ */
+export function Compass({ heading, center, markers, width = 340, fov = (Math.PI * 2) / 3, kindStyles = DEFAULT_MARKER_KINDS, className, }) {
+    const markerList = useSyncExternalStore(markers?.subscribe ?? NO_SUBSCRIBE, markers?.snapshot ?? EMPTY_MARKERS, markers?.snapshot ?? EMPTY_MARKERS);
+    const half = fov / 2;
+    const toX = (bearing) => {
+        const delta = relativeBearing(bearing, heading);
+        if (Math.abs(delta) > half)
+            return null;
+        return width / 2 + (delta / half) * (width / 2);
+    };
+    return (_jsxs("div", { className: className, "data-compass": true, style: {
+            width,
+            height: 34,
+            position: "relative",
+            overflow: "hidden",
+            borderRadius: 8,
+            border: "1px solid rgba(148,163,184,0.28)",
+            background: "linear-gradient(180deg, rgba(18,22,30,0.92), rgba(10,13,18,0.92))",
+            color: "#e2e8f0",
+            fontFamily: "ui-sans-serif, system-ui, sans-serif",
+        }, children: [_jsx("div", { style: {
+                    position: "absolute",
+                    left: "50%",
+                    top: 0,
+                    bottom: 0,
+                    width: 1,
+                    background: "rgba(74,222,128,0.85)",
+                } }), COMPASS_TICKS.map((tick) => {
+                const x = toX(tick.bearing);
+                if (x === null)
+                    return null;
+                const major = tick.cardinal.length === 1;
+                return (_jsx("span", { style: {
+                        position: "absolute",
+                        left: x,
+                        top: major ? 7 : 11,
+                        transform: "translateX(-50%)",
+                        fontSize: major ? 13 : 9,
+                        fontWeight: major ? 700 : 500,
+                        color: major ? "#f8fafc" : "rgba(148,163,184,0.75)",
+                    }, children: tick.cardinal }, tick.cardinal));
+            }), center !== undefined
+                ? markerList.map((marker) => {
+                    const bearing = compassBearing(center, [marker.position[0], marker.position[2]]);
+                    const x = toX(bearing);
+                    if (x === null)
+                        return null;
+                    const style = markerKindStyle(marker.kind, kindStyles);
+                    return (_jsx("span", { "data-compass-marker": marker.kind, style: {
+                            position: "absolute",
+                            left: x,
+                            bottom: 2,
+                            transform: "translateX(-50%)",
+                            fontSize: 11,
+                            color: style.color,
+                            fontWeight: 700,
+                        }, children: style.glyph }, marker.id));
+                })
+                : null] }));
+}
+/**
+ * Full-bounds top-down world map (the "press M" overlay): baked terrain
+ * background, reveal-on-event fog, all markers with labels, and the player.
+ * Rectangular linear projection over the supplied world `bounds`.
+ */
+export function WorldMap({ markers, bounds, player, heading = 0, fog, background, width = 520, height, kindStyles = DEFAULT_MARKER_KINDS, className, title = "World Map", onClose, }) {
+    const markerList = useMarkers(markers);
+    const fogCells = useSyncExternalStore(fog?.subscribe ?? NO_SUBSCRIBE, fog?.cells ?? NULL_CELLS, fog?.cells ?? NULL_CELLS);
+    const worldW = bounds.maxX - bounds.minX;
+    const worldD = bounds.maxZ - bounds.minZ;
+    const mapH = height ?? Math.round((width * worldD) / worldW);
+    const project = (x, z) => ({
+        x: ((x - bounds.minX) / worldW) * width,
+        y: ((z - bounds.minZ) / worldD) * mapH,
+    });
+    return (_jsxs("div", { className: className, "data-world-map": true, style: {
+            borderRadius: 16,
+            padding: 14,
+            background: "linear-gradient(160deg, rgba(20,24,32,0.97), rgba(10,13,18,0.97))",
+            border: "1px solid rgba(148,163,184,0.35)",
+            boxShadow: "0 24px 60px rgba(0,0,0,0.6)",
+            color: "#e2e8f0",
+            fontFamily: "ui-sans-serif, system-ui, sans-serif",
+        }, children: [_jsxs("div", { style: { display: "flex", justifyContent: "space-between", alignItems: "center", marginBottom: 10 }, children: [_jsx("span", { style: { fontSize: 13, fontWeight: 700, letterSpacing: 1.5, textTransform: "uppercase" }, children: title }), onClose !== undefined ? (_jsx("button", { type: "button", onClick: onClose, style: {
+                            border: "1px solid rgba(148,163,184,0.4)",
+                            borderRadius: 6,
+                            background: "transparent",
+                            color: "rgba(226,232,240,0.85)",
+                            fontSize: 11,
+                            padding: "3px 9px",
+                            cursor: "pointer",
+                        }, children: "Close" })) : null] }), _jsxs("svg", { width: width, height: mapH, viewBox: `0 0 ${width} ${mapH}`, "data-world-map-canvas": true, style: { borderRadius: 10 }, children: [_jsx("rect", { x: 0, y: 0, width: width, height: mapH, fill: "#16202b" }), background !== undefined ? (_jsx("image", { href: background, x: 0, y: 0, width: width, height: mapH, preserveAspectRatio: "none", opacity: 0.95 })) : null, fogCells !== null
+                        ? (() => {
+                            const cellW = (fogCells.cellSize / worldW) * width;
+                            const cellH = (fogCells.cellSize / worldD) * mapH;
+                            const rects = [];
+                            for (let row = 0; row < fogCells.rows; row += 1) {
+                                for (let col = 0; col < fogCells.cols; col += 1) {
+                                    if (fogCells.revealed[row * fogCells.cols + col])
+                                        continue;
+                                    const at = project(fogCells.minX + col * fogCells.cellSize, fogCells.minZ + row * fogCells.cellSize);
+                                    rects.push(_jsx("rect", { x: at.x, y: at.y, width: cellW + 0.5, height: cellH + 0.5, fill: "#0b0f14", opacity: 0.86 }, `wfog-${col}-${row}`));
+                                }
+                            }
+                            return rects;
+                        })()
+                        : null, markerList.map((marker) => {
+                        const at = project(marker.position[0], marker.position[2]);
+                        const style = markerKindStyle(marker.kind, kindStyles);
+                        return (_jsxs("g", { "data-world-marker": marker.kind, children: [_jsx("circle", { cx: at.x, cy: at.y, r: 9, fill: "rgba(2,6,12,0.6)", stroke: style.color, strokeWidth: 1.2 }), _jsx("text", { x: at.x, y: at.y + 4, textAnchor: "middle", fontSize: 12, fill: style.color, style: { fontWeight: 700 }, children: style.glyph }), marker.label !== undefined ? (_jsx("text", { x: at.x + 12, y: at.y + 4, fontSize: 11, fill: "rgba(226,232,240,0.85)", children: marker.label })) : null] }, marker.id));
+                    }), player !== undefined
+                        ? (() => {
+                            const at = project(player[0], player[1]);
+                            return (_jsx("g", { transform: `translate(${at.x} ${at.y}) rotate(${heading * (180 / Math.PI)})`, children: _jsx("path", { d: "M0,-11 L7,9 L0,4 L-7,9 Z", fill: "#4ade80", stroke: "#052e16", strokeWidth: 1 }) }));
+                        })()
+                        : null] })] }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/react",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "React UI layer for JGengine: GameProvider, hooks, and headless primitives over @jgengine/core.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -29,7 +29,7 @@
     "check-types": "tsgo --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@jgengine/core": "^0.6.0"
+    "@jgengine/core": "^0.7.0"
   },
   "peerDependencies": {
     "react": "^19.0.0"