@jgengine/core 0.9.0 → 0.10.0

package/llms.txt

@@ -1,7 +1,7 @@
 # @jgengine/core
 > jgengine core — genre-agnostic TypeScript game engine SDK (npm @jgengine/core). Runtime, scene, combat, inventory, multiplayer primitives. Zero dependencies. https://jgengine.com
 
-Version: 0.9.0
+Version: 0.10.0
 License: AGPL-3.0-only
 Repository: https://github.com/Noisemaker111/jgengine
 Docs: https://jgengine.com
@@ -72,14 +72,22 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - SpawnDirectorConfig (interface): interface SpawnDirectorConfig
 - SpawnDirectorState (interface): interface SpawnDirectorState
 - SpawnEntry (interface): interface SpawnEntry
+- SpawnPointDistanceBias (type): type SpawnPointDistanceBias = "near" | "far" | "none" — Preference for picking a spawn point relative to `avoid` positions: closer, farther, or unweighted.
+- SpawnPointSelectionOptions (interface): interface SpawnPointSelectionOptions — Semantic options for selecting a spawn point without exposing weighting internals.
 - SpawnRequest (interface): interface SpawnRequest
 - WaveManifest (interface): interface WaveManifest
 - advanceSpawnDirector (function): function advanceSpawnDirector(config: SpawnDirectorConfig, state: SpawnDirectorState, dt: number, ctx: DirectorContext): DirectorStep
 - advanceWave (function): function advanceWave(config: SpawnDirectorConfig, state: SpawnDirectorState): SpawnDirectorState
 - createSpawnDirectorState (function): function createSpawnDirectorState(config: SpawnDirectorConfig): SpawnDirectorState
-- pickSpawnPoint (function): function pickSpawnPoint(points: readonly NavPoint[], players: readonly NavPoint[], options: { roll: number; bias?: number }): NavPoint | null
+- pickSpawnPoint (function): function pickSpawnPoint(options: SpawnPointSelectionOptions): NavPoint | null — Selects a candidate spawn point using a semantic distance preference and caller-supplied randomness.
 - raiseAlert (function): function raiseAlert(state: SpawnDirectorState, amount: number): SpawnDirectorState
 
+### @jgengine/core/ai/spawnPoint
+
+- SpawnPointDistanceBias (type): type SpawnPointDistanceBias = "near" | "far" | "none" — Preference for picking a spawn point relative to `avoid` positions: closer, farther, or unweighted.
+- SpawnPointSelectionOptions (interface): interface SpawnPointSelectionOptions — Semantic options for selecting a spawn point without exposing weighting internals.
+- selectSpawnPoint (function): function selectSpawnPoint(options: SpawnPointSelectionOptions): NavPoint | null — Selects a spawn point by game intent while keeping weighting mechanics internal.
+
 ### @jgengine/core/ai/threat
 
 - HighestThreatOptions (interface): interface HighestThreatOptions
@@ -126,6 +134,61 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - distance3 (function): function distance3(a: { x: number; y: number; z: number }, b: { x: number; y: number; z: number }): number
 - resolveEmitterGain (function): function resolveEmitterGain(distance: number, sound: Pick<SoundDef, "gain" | "positional" | "falloff">, busGain: number): number
 
+### @jgengine/core/audio/music
+
+- MusicInstrument (type): type MusicInstrument = | "strings" | "flute" | "harp" | "horn" | "choir" | "bell" | "timpani" | "bass" | "stacc" | "pad" | "lute" | "dulcimer" | "frameDrum" | "warDrum" | "reed" | "pipe" | "squareLead" | "woodBlock" | "tinyBell" | "piano" | "shaker" | "brassStab" | "cymSwell" | "oboe" — Named synthesised instrument. Each maps to a voice in the shell's instrument library (`@jgengine/shell/audio/musicVoices`); an unknown name falls back to a plain sine voice so a theme is never silent.
+- MusicTheme (interface): interface MusicTheme — A through-composed, looping music track. `events` need not be sorted; the director schedules them ahead against a fixed anchor so loops are seamless.
+- NoteEvent (interface): interface NoteEvent — One scheduled note in a theme, positioned on the loop's quarter-note grid.
+- ScheduledNote (interface): interface ScheduledNote — A resolved note occurrence: the source note plus its absolute onset in seconds.
+- mtof (function): function mtof(midi: number): number — Standard equal-temperament MIDI-to-frequency (A4 = 440 Hz at MIDI 69).
+- notesInWindow (function): function notesInWindow(theme: MusicTheme, anchorSec: number, fromSec: number, toSec: number): ScheduledNote[] — Pure lookahead scheduler: every note occurrence of `theme` whose onset falls in the half-open window `(fromSec, toSec]`, given the theme's loop-zero at `anchorSec`. Handles any number of loop wraps, so a director calls it once per tick with a non-overlapping window and never double-schedules a note.
+- themeLoopSeconds (function): function themeLoopSeconds(theme: MusicTheme): number — Loop length of a theme in seconds.
+
+### @jgengine/core/audio/synth
+
+- NoiseVoice (interface): interface NoiseVoice — A filtered white-noise burst — impacts, whooshes, breath, crackle. Realised from a shared 1s noise buffer at a randomised playback rate and start offset, decaying exponentially to silence at `duration * decay`.
+- SynthFilter (type): type SynthFilter = "lowpass" | "highpass" | "bandpass" — Biquad filter shape a noise voice is coloured through.
+- SynthPatch (interface): interface SynthPatch — A procedural sound cue: a set of voices triggered together, each with its own `delay`, summed into one one-shot. Pure serialisable data — the shell realises it on Web Audio, so the same catalog runs headless in tests with no `AudioContext`.
+- SynthVoice (type): type SynthVoice = ToneVoice | NoiseVoice — One layered voice of a synth cue.
+- SynthWave (type): type SynthWave = "sine" | "square" | "sawtooth" | "triangle" — Oscillator waveform available to a pitched synth voice.
+- ToneVoice (interface): interface ToneVoice — A pitched oscillator voice: a 12ms linear attack to `gain`, then an exponential decay to silence across `duration`, with an optional exponential pitch slide from `freq` to `slideTo`.
+- patchDuration (function): function patchDuration(patch: SynthPatch): number — Total wall-clock length of a patch in seconds — the latest voice end across all voices.
+
+### @jgengine/core/authoring
+
+- ActionCodesMap (type): type ActionCodesMap<TAction extends string = string, TCode extends string = string> = Record< TAction, ActionCodes<TCode> > — Maps each game action name to the input codes (hold/toggle keys, repeat rate) that trigger it.
+- Drop (interface): interface Drop — A resolved loot outcome — one item or currency grant with its rolled count.
+- GameDefinition (interface): interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> — Fully-resolved game description produced by {@link defineGame} — assets, scene, and opted-in subsystems.
+- GameDefinitionConfig (type): type GameDefinitionConfig<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> = Omit<GameDefinition<TAssetRef, TMultiplayer>, "scene" | "assets"> & { assets?: AssetCatalog<TAssetRef>; } — Input to {@link defineGame} — a `GameDefinition` with `scene` derived and `assets` optional.
+- GameLoop (interface): interface GameLoop<TContext = unknown> — Lifecycle hooks a game implements to drive init, per-tick simulation, and player join/leave.
+- GameServerConfig (type): type GameServerConfig = "persistent" | { mode: string; [key: string]: unknown } — Hosting mode for a game's multiplayer server: `"persistent"`, or a custom mode with its own options.
+- InventoryDeclaration (interface): interface InventoryDeclaration — Shape of one named inventory a game declares — slot count, accepted item types, HUD binding.
+- LootEntry (interface): interface LootEntry — One possible drop in a {@link LootTableDef} — an item or currency, its count range, and its odds.
+- LootTableDef (interface): interface LootTableDef — A named, validated loot table — its roll count, weighted-vs-independent mode, and candidate entries.
+- PhysicsConfig (interface): interface PhysicsConfig — World gravity and jump tuning, plus scene-object collision opt-ins, for the game's physics step.
+- SpawnPointDistanceBias (type): type SpawnPointDistanceBias = "near" | "far" | "none" — Preference for picking a spawn point relative to `avoid` positions: closer, farther, or unweighted.
+- SpawnPointSelectionOptions (interface): interface SpawnPointSelectionOptions — Semantic options for selecting a spawn point without exposing weighting internals.
+- WorldFeature (type): type WorldFeature = | ({ kind: "biomes" } & BiomesWorldConfig) | ({ kind: "voxel" } & VoxelWorldConfig) | ({ kind: "plots" } & PlotsWorldConfig) | ({ kind: "tilemap" } & TilemapWorldConfig) | EnvironmentWorldFeature | { kind: "flat" } — A declared world shape — biomes, voxel grid, plots, tilemap, environment, or flat — passed to `defineGame`.
+- biomes (function): function biomes(config: BiomesWorldConfig): WorldFeature — Declares a biome-painted world — the whole-world alternative to a single `environment()` terrain.
+- building (function): function building(config: BuildingEnvironmentConfig = {}): BuildingEnvironmentDescriptor — Declares a cluster of procedurally-massed buildings for `environment()` — count, footprint, stories, style.
+- contextVerb (function): function contextVerb(label: string, command: string, args?: Record<string, unknown>): ContextVerb — Builds a {@link ContextVerb} for a right-click menu entry.
+- defineGame (function): function defineGame<TAssetRef extends ModelAssetRef, TMultiplayer>(config: GameDefinitionConfig<TAssetRef, TMultiplayer>): GameDefinition<TAssetRef, TMultiplayer> — Task-first entry point for authoring a game: fills in `scene` and default `assets`, validates `name`.
+- environment (function): function environment(config: EnvironmentWorldConfig = {}): EnvironmentWorldFeature — Composes an `environment()` world feature from terrain, sky, weather, vegetation, water, structures, roads, and pads.
+- flat (function): function flat(): WorldFeature — Declares an empty flat world — the minimal `WorldFeature` for games with no terrain of their own.
+- grass (function): function grass(config: GrassEnvironmentConfig = {}): GrassEnvironmentDescriptor — Declares a grass vegetation patch for `environment()` — area, blade sizing, density, and colors.
+- lootTable (function): function lootTable(def: LootTableDef): LootTableDef — Validates a loot table definition and returns it unchanged, for use with {@link createLootRegistry}.
+- ocean (function): function ocean(config: OceanEnvironmentConfig = {}): OceanEnvironmentDescriptor — Declares an ocean water body for `environment()` — bounds, level, and wave tuning.
+- plots (function): function plots(config: PlotsWorldConfig = {}): WorldFeature — Declares a subdivided-plots world — farming, base-building, and other parcel-based layouts.
+- rain (function): function rain(config: RainEnvironmentConfig = {}): RainEnvironmentDescriptor — Declares a rainfall weather effect for `environment()` — area, density, speed, and wind.
+- road (function): function road(config: RoadEnvironmentConfig): RoadEnvironmentDescriptor — Declare a road ribbon for an `environment()` world; the shell drapes and renders it over the terrain.
+- seededRng (function): function seededRng(seed: string | number): () => number — Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence.
+- seededStreams (function): function seededStreams(seed: string | number): (stream: string) => () => number — Derives independent, deterministic {@link seededRng} streams from one base seed, keyed by stream name.
+- selectSpawnPoint (function): function selectSpawnPoint(options: SpawnPointSelectionOptions): NavPoint | null — Selects a spawn point by game intent while keeping weighting mechanics internal.
+- snow (function): function snow(config: SnowEnvironmentConfig = {}): SnowEnvironmentDescriptor — Declares a snowfall weather effect for `environment()` — area, density, drift, and wind.
+- terrain (function): function terrain(config: TerrainEnvironmentConfig = {}): TerrainEnvironmentDescriptor — Declares a heightfield terrain patch for `environment()` — bounds, noise, materials, and flatten masks.
+- tilemap (function): function tilemap(config: TilemapWorldConfig): WorldFeature — Declares a 2D tilemap world from a map string.
+- voxel (function): function voxel(config: VoxelWorldConfig): WorldFeature — Declares a voxel-grid world for block-based games.
+
 ### @jgengine/core/behaviour/behaviour
 
 - Behaviour (class): class Behaviour — Subclass and override the lifecycle hooks. A behaviour only joins the per-frame update dispatch if it actually overrides `onUpdate` (prototype-identity check at each activation), so hook-only behaviours cost nothing per frame.
@@ -356,6 +419,13 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - totalWindowMs (function): function totalWindowMs(config: DefensiveWindowConfig): number
 - windowActiveAt (function): function windowActiveAt(config: DefensiveWindowConfig, elapsedMs: number): boolean
 
+### @jgengine/core/combat/dotField
+
+- DotField (interface): interface DotField — A pool of timed damage-over-time instances keyed by string (`bleed`, `poison`, `burn`) — the recurring-damage counterpart to `breakMeters`' one-shot buildup procs (#536.4). `tick` advances every active DoT and returns the damage due this frame, one entry per interval crossed, so the game routes each through its own effect pipeline; a pure scheduler that never applies damage itself.
+- DotSpec (interface): interface DotSpec — A single damage-over-time instance: how hard, how often, and for how long.
+- DotTick (interface): interface DotTick — One damage event (or expiry marker) emitted by `DotField.tick` for the game to route through its effects.
+- createDotField (function): function createDotField(): DotField — Builds an empty {@link DotField}; `apply` DoTs onto it and drain damage each frame with `tick`.
+
 ### @jgengine/core/combat/downed
 
 - DownedConfig (interface): interface DownedConfig
@@ -410,6 +480,12 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - SettleResult (type): type SettleResult = | { status: "settled"; shotId: string; at: [number, number, number]; hits: EffectResult[]; origin?: [number, number, number]; } | { status: "rejected"; shotId: string; reason: string }
 - createProjectileSystem (function): function createProjectileSystem(deps: ProjectileSystemDeps): ProjectileSystem
 
+### @jgengine/core/combat/regenShield
+
+- RegenShield (interface): interface RegenShield — A shield pool that stops regenerating for `regenDelayMs` after every hit, then refills at `regenPerSecond` — the delayed-regen primitive that replaces snapshot-comparing stat values per tick to detect "damage taken" (#536.3). `damage` resets the grace timer; `tick` counts it down and regenerates once it elapses.
+- RegenShieldConfig (interface): interface RegenShieldConfig — Tuning for `createRegenShield`: pool size, refill rate, and the post-damage grace period.
+- createRegenShield (function): function createRegenShield(config: RegenShieldConfig): RegenShield — Builds a {@link RegenShield} that suppresses regen for `regenDelayMs` after each hit.
+
 ### @jgengine/core/combat/resistance
 
 - ResistVerdict (type): type ResistVerdict = "immune" | "resist" | "normal" | "vulnerable"
@@ -428,12 +504,14 @@ Imports use deep paths: `@jgengine/core/<path>`.
 
 ### @jgengine/core/combat/shotOrigin
 
+- DEFAULT_EYE_HEIGHT (const): const DEFAULT_EYE_HEIGHT: number — Shot-origin and first-person camera eye height above an entity's position: 90% of the default 1.8m hitbox top.
 - ResolvedShot (interface): interface ResolvedShot
 - ShotOriginDeps (interface): interface ShotOriginDeps
-- ShotOriginPolicy (type): type ShotOriginPolicy = | { kind: "legacy" } | { kind: "entity" } | { kind: "entityOffset"; offset: EntityPosition } | { kind: "muzzle"; offset?: EntityPosition } | { kind: "camera"; origin: EntityPosition; direction?: EntityPosition } | { kind: "world"; origin: EntityPosition; direction?: EntityPos… — How a shot's world-space origin (and optional direction) is resolved before prediction/settlement. - `legacy` — `aim.origin` when present, else the shooter's entity position (pre-#431 default). - `entity` — always the shooter's entity position. - `entityOffset` / `muzzle` — entity-local offset rotated by the shooter's yaw (muzzle on a weapon model). - `camera` — explicit camera/reticle world origin (and optional direction override). - `world` — absolute world origin.
+- ShotOriginPolicy (type): type ShotOriginPolicy = | { kind: "eye"; height?: number } | { kind: "legacy" } | { kind: "entity" } | { kind: "entityOffset"; offset: EntityPosition } | { kind: "muzzle"; offset?: EntityPosition } | { kind: "camera"; origin: EntityPosition; direction?: EntityPosition } | { kind: "world"; origin: En… — How a shot's world-space origin (and optional direction) is resolved before prediction/settlement. - `eye` — `aim.origin` when present, else the shooter's entity position raised to eye height; the shot traces the shooter's sightline, so what the crosshair covers is what gets hit (the default). - `legacy` — `aim.origin` when present, else the shooter's raw entity position (feet). - `entity` — always the shooter's entity position. - `entityOffset` / `muzzle` — entity-local offset rotated by the shooter's yaw (muzzle on a weapon model). - `camera` — explicit camera/reticle world origin (and optional direction override). - `world` — absolute world origin.
 - aimDirection (function): function aimDirection(aim: Aim): EntityPosition | null
 - aimSpreadDeg (function): function aimSpreadDeg(aim: Aim): number
-- resolveShot (function): function resolveShot(deps: ShotOriginDeps, from: string, aim: Aim, policy: ShotOriginPolicy = { kind: "legacy" }): ResolvedShot | null
+- eyeHeightFromColliders (function): function eyeHeightFromColliders(set: EntityColliderSet | null | undefined): number — Eye height derived from a collider set: 90% of the tallest hitbox top, or the humanoid default when unknown.
+- resolveShot (function): function resolveShot(deps: ShotOriginDeps, from: string, aim: Aim, policy: ShotOriginPolicy = { kind: "eye" }): ResolvedShot | null
 
 ### @jgengine/core/combat/telegraph
 
@@ -726,6 +804,76 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - createEmptyWallet (function): function createEmptyWallet(): WalletState
 - grant (function): function grant(state: WalletState, currency: string, amount: number): WalletState
 
+### @jgengine/core/editor/commands
+
+- EditorCommand (type): type EditorCommand = | { type: "select"; ids: readonly string[] } | { type: "clearSelection" } | { type: "setTransform"; id: string; position?: EditorVec3; rotationY?: number } | { type: "addMarker"; marker: EditorMarker } | { type: "remove"; id: string } | { type: "setVolume"; id: string; patch: Pa… — A single editor mutation — select, move, add, remove, undo/redo — dispatched to a session.
+- EditorSession (interface): interface EditorSession — Stateful, undoable handle for driving scene edits from UI or an MCP agent.
+- EditorSessionState (interface): interface EditorSessionState — The document plus current selection at a point in editor history.
+- createEditorSession (function): function createEditorSession(initial: EditorDocument, historyLimit = 100): EditorSession — Creates an editor session with undo/redo history seeded from an initial document.
+- summarizeEditorSession (function): function summarizeEditorSession(state: EditorSessionState): { markers: number; volumes: number; paths: number; annotations: number; selection: string[]; selectedMarker?: EditorMarker; selectedVolume?: EditorVolume; } — Compact snapshot of a session state — counts, selection, and the selected object.
+
+### @jgengine/core/editor/document
+
+- cloneEditorDocument (function): function cloneEditorDocument(doc: EditorDocument): EditorDocument — Deep-copies an editor document so edits never mutate the source.
+- createEmptyEditorDocument (function): function createEmptyEditorDocument(): EditorDocument — Builds a fresh, empty editor document to start authoring a scene from scratch.
+- editorDocumentBounds (function): function editorDocumentBounds(doc: EditorDocument): { min: { x: number; y: number; z: number }; max: { x: number; y: number; z: number }; } | null — Computes the world-space min/max bounds spanning every object in a document, or null if empty.
+- exportEditorDocumentJson (function): function exportEditorDocumentJson(doc: EditorDocument, pretty = true): string — Serializes an editor document to JSON text for saving or export.
+- findEditorMarker (function): function findEditorMarker(doc: EditorDocument, id: string): EditorMarker | undefined — Looks up a marker by id in an editor document.
+- findEditorNote (function): function findEditorNote(doc: EditorDocument, id: string): EditorNote | undefined — Looks up an annotation note by id in an editor document.
+- findEditorPath (function): function findEditorPath(doc: EditorDocument, id: string): EditorPath | undefined — Looks up a path by id in an editor document.
+- findEditorVolume (function): function findEditorVolume(doc: EditorDocument, id: string): EditorVolume | undefined — Looks up a volume by id in an editor document.
+- importEditorDocumentJson (function): function importEditorDocumentJson(raw: string): EditorDocument — Parses JSON text back into a normalized editor document.
+- listEditorKinds (function): function listEditorKinds(doc: EditorDocument): { markers: string[]; volumes: string[]; paths: string[]; } — Lists the distinct marker, volume, and path kinds authored in a document.
+- mergeEditorDocuments (function): function mergeEditorDocuments(...docs: readonly EditorDocument[]): EditorDocument — Combines multiple editor documents' markers, volumes, paths, and notes into one.
+- normalizeEditorLayers (function): function normalizeEditorLayers(input: EditorLayersInput | undefined | null): EditorDocument — Resolves a game's `editorLayers` export — document, partial data, or factory — into a full document.
+
+### @jgengine/core/editor/index
+
+- EditorCommand (type): type EditorCommand = | { type: "select"; ids: readonly string[] } | { type: "clearSelection" } | { type: "setTransform"; id: string; position?: EditorVec3; rotationY?: number } | { type: "addMarker"; marker: EditorMarker } | { type: "remove"; id: string } | { type: "setVolume"; id: string; patch: Pa… — A single editor mutation — select, move, add, remove, undo/redo — dispatched to a session.
+- EditorDocument (interface): interface EditorDocument — The full authored scene: every marker, volume, path, and note for a game.
+- EditorKindVisibility (interface): interface EditorKindVisibility — Per-kind show/hide flags for the editor's layer panel.
+- EditorLayersInput (type): type EditorLayersInput = | EditorDocument | Partial<Omit<EditorDocument, "version">> | (() => EditorDocument | Partial<Omit<EditorDocument, "version">>) — Accepted shape for a game's `editorLayers` export: a document, partial data, or a factory.
+- EditorMarker (interface): interface EditorMarker — A placeable point object in the scene — spawn, mob, chest, POI, etc.
+- EditorNote (interface): interface EditorNote — A free-text annotation pinned to a world position for designers.
+- EditorPath (interface): interface EditorPath — A polyline of points — road, corridor, patrol route — placed in the scene.
+- EditorSession (interface): interface EditorSession — Stateful, undoable handle for driving scene edits from UI or an MCP agent.
+- EditorSessionState (interface): interface EditorSessionState — The document plus current selection at a point in editor history.
+- EditorVec3 (type): type EditorVec3 = { x: number; y: number; z: number } — A world-space point used across editor markers, volumes, and paths.
+- EditorVolume (interface): interface EditorVolume — A spatial region — zone, aggro range, capture area — placed in the scene.
+- EditorVolumeShape (type): type EditorVolumeShape = "sphere" | "cylinder" | "box" — Collision shape a volume is rendered and tested as.
+- WELL_KNOWN_MARKER_KINDS (const): const WELL_KNOWN_MARKER_KINDS: readonly ["player_spawn", "mob", "boss", "vendor", "chest", "travel", "npc", "poi", "prop", "goal", "branch"] — Standard marker kinds recognized with default colors and behavior.
+- WELL_KNOWN_PATH_KINDS (const): const WELL_KNOWN_PATH_KINDS: readonly ["road", "corridor", "branch", "route"] — Standard path kinds recognized with default colors and behavior.
+- WELL_KNOWN_VOLUME_KINDS (const): const WELL_KNOWN_VOLUME_KINDS: readonly ["zone", "flatten", "cluster", "aggro", "leash", "discover", "capture", "prompt", "poi", "respawn_skip"] — Standard volume kinds recognized with default colors and behavior.
+- cloneEditorDocument (function): function cloneEditorDocument(doc: EditorDocument): EditorDocument — Deep-copies an editor document so edits never mutate the source.
+- createEditorSession (function): function createEditorSession(initial: EditorDocument, historyLimit = 100): EditorSession — Creates an editor session with undo/redo history seeded from an initial document.
+- createEmptyEditorDocument (function): function createEmptyEditorDocument(): EditorDocument — Builds a fresh, empty editor document to start authoring a scene from scratch.
+- editorDocumentBounds (function): function editorDocumentBounds(doc: EditorDocument): { min: { x: number; y: number; z: number }; max: { x: number; y: number; z: number }; } | null — Computes the world-space min/max bounds spanning every object in a document, or null if empty.
+- exportEditorDocumentJson (function): function exportEditorDocumentJson(doc: EditorDocument, pretty = true): string — Serializes an editor document to JSON text for saving or export.
+- findEditorMarker (function): function findEditorMarker(doc: EditorDocument, id: string): EditorMarker | undefined — Looks up a marker by id in an editor document.
+- findEditorNote (function): function findEditorNote(doc: EditorDocument, id: string): EditorNote | undefined — Looks up an annotation note by id in an editor document.
+- findEditorPath (function): function findEditorPath(doc: EditorDocument, id: string): EditorPath | undefined — Looks up a path by id in an editor document.
+- findEditorVolume (function): function findEditorVolume(doc: EditorDocument, id: string): EditorVolume | undefined — Looks up a volume by id in an editor document.
+- importEditorDocumentJson (function): function importEditorDocumentJson(raw: string): EditorDocument — Parses JSON text back into a normalized editor document.
+- listEditorKinds (function): function listEditorKinds(doc: EditorDocument): { markers: string[]; volumes: string[]; paths: string[]; } — Lists the distinct marker, volume, and path kinds authored in a document.
+- mergeEditorDocuments (function): function mergeEditorDocuments(...docs: readonly EditorDocument[]): EditorDocument — Combines multiple editor documents' markers, volumes, paths, and notes into one.
+- normalizeEditorLayers (function): function normalizeEditorLayers(input: EditorLayersInput | undefined | null): EditorDocument — Resolves a game's `editorLayers` export — document, partial data, or factory — into a full document.
+- summarizeEditorSession (function): function summarizeEditorSession(state: EditorSessionState): { markers: number; volumes: number; paths: number; annotations: number; selection: string[]; selectedMarker?: EditorMarker; selectedVolume?: EditorVolume; } — Compact snapshot of a session state — counts, selection, and the selected object.
+
+### @jgengine/core/editor/types
+
+- EditorDocument (interface): interface EditorDocument — The full authored scene: every marker, volume, path, and note for a game.
+- EditorKindVisibility (interface): interface EditorKindVisibility — Per-kind show/hide flags for the editor's layer panel.
+- EditorLayersInput (type): type EditorLayersInput = | EditorDocument | Partial<Omit<EditorDocument, "version">> | (() => EditorDocument | Partial<Omit<EditorDocument, "version">>) — Accepted shape for a game's `editorLayers` export: a document, partial data, or a factory.
+- EditorMarker (interface): interface EditorMarker — A placeable point object in the scene — spawn, mob, chest, POI, etc.
+- EditorNote (interface): interface EditorNote — A free-text annotation pinned to a world position for designers.
+- EditorPath (interface): interface EditorPath — A polyline of points — road, corridor, patrol route — placed in the scene.
+- EditorVec3 (type): type EditorVec3 = { x: number; y: number; z: number } — A world-space point used across editor markers, volumes, and paths.
+- EditorVolume (interface): interface EditorVolume — A spatial region — zone, aggro range, capture area — placed in the scene.
+- EditorVolumeShape (type): type EditorVolumeShape = "sphere" | "cylinder" | "box" — Collision shape a volume is rendered and tested as.
+- WELL_KNOWN_MARKER_KINDS (const): const WELL_KNOWN_MARKER_KINDS: readonly ["player_spawn", "mob", "boss", "vendor", "chest", "travel", "npc", "poi", "prop", "goal", "branch"] — Standard marker kinds recognized with default colors and behavior.
+- WELL_KNOWN_PATH_KINDS (const): const WELL_KNOWN_PATH_KINDS: readonly ["road", "corridor", "branch", "route"] — Standard path kinds recognized with default colors and behavior.
+- WELL_KNOWN_VOLUME_KINDS (const): const WELL_KNOWN_VOLUME_KINDS: readonly ["zone", "flatten", "cluster", "aggro", "leash", "discover", "capture", "prompt", "poi", "respawn_skip"] — Standard volume kinds recognized with default colors and behavior.
+
 ### @jgengine/core/faction/factions
 
 - FactionDef (interface): interface FactionDef
@@ -776,6 +924,12 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - createChatFilter (function): function createChatFilter(config: ChatFilterConfig): ChatFilter
 - normalizeChatText (function): function normalizeChatText(text: string): string
 
+### @jgengine/core/game/connectedPlayers
+
+- ConnectedPlayer (interface): interface ConnectedPlayer — A player currently joined to a hosted world — the unit a shared-world loop iterates instead of `ctx.player`.
+- ConnectedPlayers (interface): interface ConnectedPlayers — The set of players connected to one hosted world. A single-player game uses `ctx.player`; a shared-world loop reads `ctx.game.players` so `onTick` can advance every connected hero, not just the one local player. The host (`HostedGameRunner`) drives `join`/`leave`/`setInput`; game code reads `list`/`ids`/`has`/`count`/`input`.
+- createConnectedPlayers (function): function createConnectedPlayers(): ConnectedPlayers — Build an empty {@link ConnectedPlayers} registry — the host joins/leaves players; the game loop reads them.
+
 ### @jgengine/core/game/controlGate
 
 - PLAY_CONTROLS_STORE_KEY (const): const PLAY_CONTROLS_STORE_KEY: "jg.playControls"
@@ -793,17 +947,21 @@ Imports use deep paths: `@jgengine/core/<path>`.
 
 ### @jgengine/core/game/defineGame
 
-- GameDefinition (interface): interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown>
-- GameDefinitionConfig (type): type GameDefinitionConfig<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> = Omit<GameDefinition<TAssetRef, TMultiplayer>, "scene" | "assets"> & { assets?: AssetCatalog<TAssetRef>; }
-- GameLoop (interface): interface GameLoop<TContext = unknown>
-- GameServerConfig (type): type GameServerConfig = "persistent" | { mode: string; [key: string]: unknown }
-- InventoryDeclaration (interface): interface InventoryDeclaration
-- PhysicsConfig (interface): interface PhysicsConfig
-- defineGame (function): function defineGame<TAssetRef extends ModelAssetRef, TMultiplayer>(config: GameDefinitionConfig<TAssetRef, TMultiplayer>): GameDefinition<TAssetRef, TMultiplayer>
+- GameDefinition (interface): interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> — Fully-resolved game description produced by {@link defineGame} — assets, scene, and opted-in subsystems.
+- GameDefinitionConfig (type): type GameDefinitionConfig<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> = Omit<GameDefinition<TAssetRef, TMultiplayer>, "scene" | "assets"> & { assets?: AssetCatalog<TAssetRef>; } — Input to {@link defineGame} — a `GameDefinition` with `scene` derived and `assets` optional.
+- GameFeatures (interface): interface GameFeatures — Opt-in `ctx.game.*` subsystems. Absent = off: the game doesn't carry (or expose) it, and `ctx.game.<name>` is `undefined`. Present (`true`) builds it. The universal base — `commands`, `events`, `store`, `feed` — is always on and not listed here. This is what keeps core genre-agnostic: a puzzle game isn't handed an MMO's leaderboard/roster/turn plumbing it never asked for.
+- GameLoop (interface): interface GameLoop<TContext = unknown> — Lifecycle hooks a game implements to drive init, per-tick simulation, and player join/leave.
+- GameServerConfig (type): type GameServerConfig = "persistent" | { mode: string; [key: string]: unknown } — Hosting mode for a game's multiplayer server: `"persistent"`, or a custom mode with its own options.
+- InventoryDeclaration (interface): interface InventoryDeclaration — Shape of one named inventory a game declares — slot count, accepted item types, HUD binding.
+- LoopPlayer (interface): interface LoopPlayer — Identity of a player joining or leaving a hosted world — passed to the multiplayer loop hooks.
+- PhysicsConfig (interface): interface PhysicsConfig — World gravity and jump tuning, plus scene-object collision opt-ins, for the game's physics step.
+- defineGame (function): function defineGame<TAssetRef extends ModelAssetRef, TMultiplayer>(config: GameDefinitionConfig<TAssetRef, TMultiplayer>): GameDefinition<TAssetRef, TMultiplayer> — Task-first entry point for authoring a game: fills in `scene` and default `assets`, validates `name`.
 
 ### @jgengine/core/game/events
 
+- AudioMusicEvent (interface): interface AudioMusicEvent — Crossfade the procedural soundtrack to `theme` (null fades out), optionally transposing the incoming theme by `transpose` semitones.
 - AudioPlayEvent (interface): interface AudioPlayEvent
+- AudioResumeEvent (type): type AudioResumeEvent = Record<string, never> — Request that the shell's audio engine resume its (browser-gesture-suspended) context; carries no payload.
 - ChatMessageEvent (interface): interface ChatMessageEvent
 - CombatHitReactionEvent (interface): interface CombatHitReactionEvent
 - CombatTelegraphCancelledEvent (interface): interface CombatTelegraphCancelledEvent
@@ -811,6 +969,7 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - CosmeticsChangedEvent (interface): interface CosmeticsChangedEvent
 - DeathReason (type): type DeathReason = | { kind: "player_kill"; killerUserId: string; via?: { item?: string } } | { kind: "environment"; source: string } | { kind: "self"; source: string }
 - EmotePlayedEvent (interface): interface EmotePlayedEvent
+- EntityAnimationEvent (interface): interface EntityAnimationEvent — Request that an entity's rig play a one-shot animation clip bound to `event` in its `animation.oneShots` (e.g. an "attack" swing); the shell resolves the clip and plays it once over the locomotion state.
 - EntityDiedEvent (interface): interface EntityDiedEvent
 - EntityFloatTextEvent (interface): interface EntityFloatTextEvent
 - FormChangedEvent (interface): interface FormChangedEvent
@@ -851,6 +1010,14 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - isPlaying (function): function isPlaying(ctx: GameContext): boolean
 - setGamePhase (function): function setGamePhase(ctx: GameContext, phase: GamePhase): void — Set the current phase. Publishes it to `ctx.game.store` (React reads it via `useGamePhase`) and gates the shell's on-screen touch controls in one call — `playing` shows them, every other phase hides them. This is the whole "main menu shouldn't show touch controls" wiring: call it once per phase transition and the dock follows.
 
+### @jgengine/core/game/keyValueStore
+
+- KeyValueStorage (interface): interface KeyValueStorage — Structural, DOM-free storage backend: the browser `localStorage` satisfies it, as does a test stub or `null`. The one storage seam core primitives target so persistence code never needs the DOM `Storage` lib.
+- KeyValueStore (interface): interface KeyValueStore<T> — A single persisted, mutable cell: read the current value, overwrite it, or read-modify-write with {@link KeyValueStore.update}. Unlike a record book it has no monotonic guard — the value goes wherever you set it.
+- KeyValueStoreConfig (interface): interface KeyValueStoreConfig<T> — Config for {@link createKeyValueStore}: the storage `key`, the `initial` value used before anything is saved, an optional `storage` backend (defaults to `localStorage`, pass `null` for memory-only), and optional custom `serialize`/`deserialize` (default JSON).
+- createKeyValueStore (function): function createKeyValueStore<T>(config: KeyValueStoreConfig<T>): KeyValueStore<T> — A lightweight mutable local save cell for single-player state (a credit bank, a settings blob, level progress) — the read-modify-write counterpart to the monotonic `recordBook`. Persists through a {@link KeyValueStorage} (browser `localStorage` by default); corrupt or unavailable storage degrades to in-memory and never throws into a game tick.
+- defaultKeyValueStorage (function): function defaultKeyValueStorage(): KeyValueStorage | null — The ambient `localStorage` as a {@link KeyValueStorage} when one exists (browser), otherwise `null` (server/tests) — never references the DOM `Storage` type, so it is safe in core.
+
 ### @jgengine/core/game/leaderboard
 
 - IncrementResult (type): type IncrementResult = { status: "ok"; value: number } | { status: "rejected"; reason: "not-tracked" }
@@ -864,10 +1031,12 @@ Imports use deep paths: `@jgengine/core/<path>`.
 
 - CurrentLevel (interface): interface CurrentLevel<TLevelConfig>
 - LevelDescriptor (interface): interface LevelDescriptor<TLevelConfig>
+- LevelRecord (interface): interface LevelRecord — Persisted per-level outcome: whether it has ever been cleared and the best star rating achieved.
 - LevelSequence (interface): interface LevelSequence<TLevelConfig>
 - LevelSequenceConfig (interface): interface LevelSequenceConfig<TLevelConfig>
 - LevelSequenceProgress (interface): interface LevelSequenceProgress
 - LevelSequenceStatus (type): type LevelSequenceStatus = "idle" | "playing" | "cleared" | "failed" | "complete"
+- LevelStars (type): type LevelStars = 0 | 1 | 2 | 3 — A level's star rating, 0 (cleared, no stars) to 3.
 - createLevelSequence (function): function createLevelSequence<TLevelConfig>(config: LevelSequenceConfig<TLevelConfig>): LevelSequence<TLevelConfig> — A pure, deterministic level campaign: an ordered list of levels, each with its own opaque config, played through a `start` → (`clear` → `advance`)* → `complete` happy path, with `fail`/`retry` handling per-level attempts. Mirrors the reducer style of `game/race.ts` and `ai/spawnDirector.ts` — no I/O, no timers, just state transitions driven by the caller.
 
 ### @jgengine/core/game/loadout
@@ -890,13 +1059,18 @@ Imports use deep paths: `@jgengine/core/<path>`.
 
 ### @jgengine/core/game/lootTable
 
-- Drop (interface): interface Drop
-- LootEntry (interface): interface LootEntry
+- Drop (interface): interface Drop — A resolved loot outcome — one item or currency grant with its rolled count.
+- LootEntry (interface): interface LootEntry — One possible drop in a {@link LootTableDef} — an item or currency, its count range, and its odds.
 - LootRegistry (interface): interface LootRegistry
-- LootTableDef (interface): interface LootTableDef
+- LootTableDef (interface): interface LootTableDef — A named, validated loot table — its roll count, weighted-vs-independent mode, and candidate entries.
 - createLootRegistry (function): function createLootRegistry(): LootRegistry
 - grantDrops (function): function grantDrops(drops: Drop[], appliers: { putItem: (itemId: string, count: number) => unknown; grantCurrency: (currencyId: string, amount: number) => unknown; }): void
-- lootTable (function): function lootTable(def: LootTableDef): LootTableDef
+- lootTable (function): function lootTable(def: LootTableDef): LootTableDef — Validates a loot table definition and returns it unchanged, for use with {@link createLootRegistry}.
+
+### @jgengine/core/game/modelAnimation
+
+- AUTO_ONE_SHOT_EVENTS (const): const AUTO_ONE_SHOT_EVENTS: readonly ["hit", "death"] — The two one-shot events the shell fires automatically for an entity, from `combat.hitReaction` and `entity.died`.
+- resolveOneShotClip (function): function resolveOneShotClip(oneShots: Record<string, string | readonly string[]> | undefined, event: string, roll: number): string | null — Resolves the clip name a one-shot `event` should play from a model's `animation.oneShots` map, or `null` if the event isn't bound. A `string[]` binding picks a variant by `roll` (a value in `[0, 1)`), so combat can vary attack swings. Pure and deterministic given `roll` — the shell supplies the randomness.
 
 ### @jgengine/core/game/ping
 
@@ -938,6 +1112,8 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - LightingConfig (interface): interface LightingConfig — Declarative lighting replacing the shell's hardcoded ambient/directional default (#207.5); mounts regardless of world kind, only when supplied.
 - LockOnCameraConfig (interface): interface LockOnCameraConfig — Lock-on / strafe rig (#26) — yaw bound to player→target, move axis becomes strafe.
 - ModelAnimationConfig (interface): interface ModelAnimationConfig — Rig playback for a `ModelConfig`'s GLTF animation clips — looping idles, one-shots, and held poses.
+- ModelAnimationStates (interface): interface ModelAnimationStates — Movement-state clip set for `ModelAnimationConfig.states`: the shell reads the entity's live speed each frame and crossfades between these clips, so a walking mob animates without any game-side driver.
+- ModelAttachment (interface): interface ModelAttachment — Parents a prop/weapon model to a named bone or node on the host model's rig — a sword on `handslot.r`, a spellbook offhand — following the bone's animated transform each frame.
 - ModelConfig (interface): interface ModelConfig
 - ModelMaterialOverride (interface): interface ModelMaterialOverride — Per-entity PBR material override (#151.3) applied to every `MeshStandardMaterial` in the model's cloned scene graph.
 - MovementCommitFrame (interface): interface MovementCommitFrame — One frame's movement resolution handed to `PlayerMovementConfig.beforeCommit`.
@@ -1011,7 +1187,7 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - RecordBook (interface): interface RecordBook<K extends string>
 - RecordBookConfig (interface): interface RecordBookConfig<K extends string>
 - RecordDirection (type): type RecordDirection = "lower" | "higher"
-- RecordStorage (interface): interface RecordStorage
+- RecordStorage (type): type RecordStorage = KeyValueStorage — The structural storage backend a record book persists through — an alias of the shared {@link KeyValueStorage} seam (browser `localStorage`, a test stub, or `null`).
 - RecordSubmission (interface): interface RecordSubmission<K extends string>
 - createRecordBook (function): function createRecordBook<K extends string>(config: RecordBookConfig<K>): RecordBook<K> — A personal-best record book: named numeric fields each racing toward "lower" (times) or "higher" (scores, streaks), persisted through a structural key-value storage (pass `localStorage` in a browser, a stub in tests, or `null` for in-memory only). Corrupt or unavailable storage degrades to an empty book — a record write never throws into a game tick.
 
@@ -1125,6 +1301,8 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - CameraVisibilityContext (interface): interface CameraVisibilityContext — A camera's position and reach, as seen by the visibility system.
 - CommandDef (type): type CommandDef<TInput = unknown> = { validate: ( snapshot: GameRuntimeSnapshot, input: TInput, actorUserId: string, ) => CommandValidationError | null; apply: ( snapshot: GameRuntimeSnapshot, input: TInput, actorUserId: string, ) => GameRuntimeSnapshot; }
 - CommandValidationError (type): type CommandValidationError = { reason: string }
+- ConnectedPlayer (interface): interface ConnectedPlayer — A player currently joined to a hosted world — the unit a shared-world loop iterates instead of `ctx.player`.
+- ConnectedPlayers (interface): interface ConnectedPlayers — The set of players connected to one hosted world. A single-player game uses `ctx.player`; a shared-world loop reads `ctx.game.players` so `onTick` can advance every connected hero, not just the one local player. The host (`HostedGameRunner`) drives `join`/`leave`/`setInput`; game code reads `list`/`ids`/`has`/`count`/`input`.
 - DEFAULT_VISIBILITY_SETTINGS (const): const DEFAULT_VISIBILITY_SETTINGS: Readonly<VisibilityDefaults> — Default `VisibilityDefaults` a `VisibilitySystem` falls back to when unspecified.
 - FeedUnsubscribe (type): type FeedUnsubscribe = () => void
 - GameBackend (type): type GameBackend<TPresenceRow = unknown, TPresenceLocation = unknown, TGameId extends string = string> = { transport: GameRuntimeTransport; feeds?: GameRuntimeFeeds; presence?: PresenceTransport<TPresenceRow, TPresenceLocation, TGameId>; }
@@ -1136,10 +1314,20 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - GameRuntimeServerView (type): type GameRuntimeServerView = { serverId: string; gameId: string; revision: number; memberUserIds: string[]; serverState: unknown; updatedAt: number; }
 - GameRuntimeSnapshot (type): type GameRuntimeSnapshot = { version: number; gameId: string; serverId: string; server: RuntimeServerRow; players: Record<string, RuntimePlayerRow>; chunks: Record<string, RuntimeChunkRow>; revision: number; dirty: { server: boolean; players: string[]; chunks: string[]; }; }
 - GameRuntimeTransport (type): type GameRuntimeTransport = { joinServer: (args: { gameId: string; serverId?: string }) => Promise<JoinServerResult>; leaveServer: (args: { serverId: string }) => Promise<void>; runCommand: (args: RunCommandArgs) => Promise<TransportRunCommandResult>; }
+- HostedGameRunner (interface): interface HostedGameRunner — The GameContext-loop equivalent of the pure-reducer `createGameHost`: one authoritative `createGameContext` per world, driven server-side. `onInit` runs once at construction; `onNewPlayer`/`onPlayerLeave` fire per join/leave; `tick` advances `onTick` then commits a revision. Clients pull a full {@link WorldSnapshot} baseline once, then per-tick {@link WorldDiff}s from their last revision. Games ship only normal GameContext code — the runner adds no per-game surface.
+- HostedGameRunnerOptions (interface): interface HostedGameRunnerOptions<TAssetRef extends ModelAssetRef, TMultiplayer> — Config for {@link createHostedGameRunner}: the game definition, its content lookup, and an optional host identity.
+- HostedWorldRecord (interface): interface HostedWorldRecord — One hosted world's persisted authoritative state — the unit a {@link HostedWorldStore} loads and saves.
+- HostedWorldSession (interface): interface HostedWorldSession — The stateful host substrate a long-lived backend binds (ws server, browser P2P host): a live {@link HostedGameRunner} loaded from a {@link HostedWorldStore}, auto-persisted on tick, serving each client a baseline then diffs. The stateless Convex path doesn't use this — it reconstructs a runner from the same store per invocation and diffs with `diffSnapshots`. Either way the store seam and the game code are identical.
+- HostedWorldSessionOptions (interface): interface HostedWorldSessionOptions<TAssetRef extends ModelAssetRef, TMultiplayer> — Config for {@link createHostedWorldSession}: the game, its persistence store, and the auto-save cadence.
+- HostedWorldStore (interface): interface HostedWorldStore — Narrow persistence seam for a hosted world — the {@link HostedWorldRecord} counterpart of `HostPersistence`. Backends implement it (memory/file/sql/convex); the session never names one. A stateful host loads once and saves on a cadence; a stateless host reconstructs from `load()` each invocation.
+- HostedWorldSync (type): type HostedWorldSync = | { kind: "baseline"; revision: number; snapshot: WorldSnapshot } | { kind: "diff"; diff: WorldDiff } — A client replication pull: a full baseline (first sync / fell behind) or a diff since the client's cursor.
 - HydrateInput (type): type HydrateInput = { gameId: string; serverId: string; serverRow: RuntimeServerRow; playersByUserId: Record<string, RuntimePlayerRow>; chunksByKey: Record<string, RuntimeChunkRow>; revision?: number; }
+- INPUT_COMMAND (const): const INPUT_COMMAND: "engine.input" — Reserved command name the authoritative host intercepts on the existing `runCommand` transport to route a client's {@link InputFrame} to `session.input`, so per-tick input needs no separate wire.
+- InputFrame (interface): interface InputFrame — One client's input for a tick — the semantic held-action set plus pointer state, the serializable, over-the-wire counterpart of {@link InputSnapshot} the host stores per connected player.
 - JoinServerResult (type): type JoinServerResult = { serverId: string; isNew: boolean; }
 - LiveGameBackend (type): type LiveGameBackend<TPresenceRow = unknown, TPresenceLocation = unknown, TGameId extends string = string> = GameBackend<TPresenceRow, TPresenceLocation, TGameId> & { presenceSync: PresenceSync; pushFeedEntry: (args: { serverId: string; action: string; entry: unknown }) => Promise<void>; chatSyncFor…
-- MultiplayerAdapterConfig (type): type MultiplayerAdapterConfig = | { kind: "convex"; topology?: MultiplayerTopology } | { kind: "ws"; topology?: MultiplayerTopology; url?: string } | { kind: "socketio"; topology?: MultiplayerTopology; url?: string } | { kind: "p2p"; topology?: MultiplayerTopology; room?: string } | { kind: "lan"; t…
+- MultiplayerAdapterConfig (type): type MultiplayerAdapterConfig = | { kind: "convex"; topology?: MultiplayerTopology; authority?: MultiplayerAuthority } | { kind: "ws"; topology?: MultiplayerTopology; url?: string; authority?: MultiplayerAuthority } | { kind: "socketio"; topology?: MultiplayerTopology; url?: string; authority?: Mult…
+- MultiplayerAuthority (type): type MultiplayerAuthority = "server" | "client" — Where the world simulation is authoritative. `"client"` (default) keeps the historical model — each client runs its own `onTick` and syncs only presence/feeds/chat. `"server"` opts into host-authoritative replication: the host runs the loop, and the shell mirrors the server's world into the local `ctx` instead of simulating locally.
 - MultiplayerSession (type): type MultiplayerSession = { gameId: string; userId: string; backend: LiveGameBackend; feedActions: string[]; }
 - MultiplayerTopology (type): type MultiplayerTopology = "shared" | "lobbies" | "private"
 - PresencePoseRow (type): type PresencePoseRow = { userId: string; position: { x: number; y: number; z: number }; rotationY: number; rotationPitch: number; lastSeenAt: number; }
@@ -1161,6 +1349,7 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - SaveScope (type): type SaveScope = "player" | "chunks" | "player+chunks"
 - ServerLoopHooks (type): type ServerLoopHooks = { onInit?: (ctx: RuntimeInitContext) => void; onNewPlayer?: (ctx: RuntimeLoopContext) => void; onTick?: (ctx: RuntimeWorldContext, dtSeconds: number) => void; }
 - ServersPoolConfig (type): type ServersPoolConfig = { maxServers: number; slotsPerServer: number; minPlayersToStart?: number; adapter: MultiplayerAdapterConfig; }
+- SnapshotModule (interface): interface SnapshotModule<T = unknown> — The replication seam for host-authoritative shared worlds: the opt-in feature manifest *is* the replication schema. Each live subsystem a game opts into registers a {@link SnapshotModule} keyed by name; the host serializes exactly the registered set into a {@link WorldSnapshot} and a client hydrates the same keys back. Adding a replicated subsystem is a registration, never a new branch.
 - TransportRunCommandResult (type): type TransportRunCommandResult = | { ok: true } | { ok: false; reason: string }
 - VisibilityBounds (interface): interface VisibilityBounds — Sphere bounds used for visibility/streaming distance checks.
 - VisibilityDecision (interface): interface VisibilityDecision — Result of evaluating one object against the active cameras this tick.
@@ -1170,29 +1359,52 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - VisibilityOverrides (interface): interface VisibilityOverrides — Per-object escape hatches that bypass or tune the default visibility policy.
 - VisibilityPoint (interface): interface VisibilityPoint — World-space point; `z` is optional for 2D adapters.
 - VisibilitySystem (class): class VisibilitySystem — Engine-level visibility and asset-residency policy.
+- WorldClientFrame (type): type WorldClientFrame = | { t: "join"; isNew: boolean } | { t: "leave" } | { t: "command"; name: string; input: unknown } | { t: "input"; frame: InputFrame } — Client→host frame: a player's session verbs. What a transport marshals upstream.
+- WorldClientLink (interface): interface WorldClientLink — The client end of a {@link WorldHost} connection: applies server frames to a local `ctx`, sends session verbs upstream.
+- WorldDiff (interface): interface WorldDiff — A revision-stamped delta over a {@link WorldSnapshot}. The host sends one per tick to each client, carrying only what changed since that client's last acknowledged revision — entity/stat/store deltas plus whole snapshots of any other opted-in module (feed, leaderboard, chat, …) that changed. Fold it onto a prior baseline with {@link applyWorldDiff}.
+- WorldHost (interface): interface WorldHost — The transport-agnostic host: fans one {@link HostedWorldSession} out to many connections, each tracking its own revision cursor so a joiner gets a baseline and everyone else gets diffs. A ws server, a Convex function, or an in-process loopback all drive the same shape — decode a frame → `connection.receive`; after `session.tick` → `broadcast`. No wire format is assumed; frames are plain data a transport serializes however it likes.
+- WorldHostConnection (interface): interface WorldHostConnection — One client's link on the host side: routes its upstream frames into the shared session, pushes it sync frames.
+- WorldMirror (interface): interface WorldMirror — The client end of host-authoritative replication: folds a host's baseline + {@link WorldDiff} stream onto a local {@link GameContext}. It keeps the last full {@link WorldSnapshot}, advances it with each diff, and pushes the result through `ctx.hydrate` — so the client mirrors exactly the subsystems its own game opted into and silently ignores host modules it lacks. This is the inverse of a {@link HostedWorldSession}; the transport in between (loopback, ws, Convex) is irrelevant.
+- WorldReplicator (type): type WorldReplicator = ReturnType<typeof createWorldReplicator> — The stateful diff tracker returned by {@link createWorldReplicator}: `commit()`, `diff(sinceRevision)`, `revision()`.
+- WorldServerFrame (type): type WorldServerFrame = | { t: "baseline"; revision: number; snapshot: WorldSnapshot } | { t: "diff"; diff: WorldDiff } — Host→client frame: the full baseline a joiner needs, then per-tick diffs. What a transport marshals downstream.
+- WorldSnapshot (type): type WorldSnapshot = Record<string, unknown> — Full world baseline keyed by {@link SnapshotModule.key} — one entry per opted-in subsystem.
 - adapterOf (function): function adapterOf(multiplayer: unknown): MultiplayerAdapterConfig | null
+- applyWorldDiff (function): function applyWorldDiff(baseline: WorldSnapshot, diff: WorldDiff): WorldSnapshot — Fold a {@link WorldDiff} onto a prior {@link WorldSnapshot} baseline, returning the next full snapshot — the client-side inverse of {@link createWorldReplicator}. Pure data in, pure data out: upserts changed entities, stats and store keys, drops the removed ones, and replaces changed module snapshots wholesale.
+- applyWorldSnapshot (function): function applyWorldSnapshot(modules: readonly SnapshotModule[], snapshot: WorldSnapshot): void — Hydrate every registered module whose key is present in `snapshot`; keys absent from it are left untouched.
 - clearDirtyFlags (function): function clearDirtyFlags(snapshot: GameRuntimeSnapshot): GameRuntimeSnapshot
-- convex (function): function convex(config?: { topology?: MultiplayerTopology }): MultiplayerAdapterConfig
+- composeWorldSnapshot (function): function composeWorldSnapshot(modules: readonly SnapshotModule[]): WorldSnapshot — Serialize every registered module into one keyed baseline — the host→client full-world send.
+- convex (function): function convex(config?: { topology?: MultiplayerTopology; authority?: MultiplayerAuthority }): MultiplayerAdapterConfig
+- createConnectedPlayers (function): function createConnectedPlayers(): ConnectedPlayers — Build an empty {@link ConnectedPlayers} registry — the host joins/leaves players; the game loop reads them.
 - createEmptyPlayerRow (function): function createEmptyPlayerRow(userId: string): RuntimePlayerRow
 - createEmptyServerRow (function): function createEmptyServerRow(): RuntimeServerRow
 - createGameRuntime (function): function createGameRuntime(definition: GameRuntimeDefinition): GameRuntime
+- createHostedGameRunner (function): function createHostedGameRunner<TAssetRef extends ModelAssetRef, TMultiplayer>(options: HostedGameRunnerOptions<TAssetRef, TMultiplayer>): HostedGameRunner — Build a {@link HostedGameRunner} — one authoritative GameContext world driven server-side from the game's own loop.
+- createHostedWorldSession (function): function createHostedWorldSession<TAssetRef extends ModelAssetRef, TMultiplayer>(options: HostedWorldSessionOptions<TAssetRef, TMultiplayer>): HostedWorldSession — Build a {@link HostedWorldSession} — a live runner loaded from a {@link HostedWorldStore} and auto-persisted on tick.
 - createRuntimeSnapshot (function): function createRuntimeSnapshot(args: { gameId: string; serverId: string; server?: RuntimeServerRow; players?: Record<string, RuntimePlayerRow>; chunks?: Record<string, RuntimeChunkRow>; revision?: number; }): GameRuntimeSnapshot
-- fly (function): function fly(config: { app: string; topology?: MultiplayerTopology; path?: string }): MultiplayerAdapterConfig
+- createWorldClientLink (function): function createWorldClientLink(ctx: Pick<GameContext, "hydrate">, send: (frame: WorldClientFrame) => void): WorldClientLink — Build a {@link WorldClientLink} — the client end that mirrors host frames into `ctx` and sends session verbs upstream.
+- createWorldHost (function): function createWorldHost(session: HostedWorldSession): WorldHost — Build a {@link WorldHost} fanning one {@link HostedWorldSession} out to many cursor-tracked connections.
+- createWorldMirror (function): function createWorldMirror(ctx: Pick<GameContext, "hydrate">): WorldMirror — Build a {@link WorldMirror} that replicates a host's baseline + diff stream onto `ctx` via `ctx.hydrate`.
+- createWorldReplicator (function): function createWorldReplicator(takeSnapshot: () => WorldSnapshot): { commit: () => number; diff: (sinceRevision: number) => WorldDiff; revision: () => number; } — Turns successive full {@link WorldSnapshot}s into per-client {@link WorldDiff}s. Each `commit()` re-reads the world, stamps every item that changed with the new revision, and remembers removals; `diff(sinceRevision)` then replays exactly the items stamped after that revision. Everything the tracker holds is JSON — the same shape that rides the wire — so a diff is inherently serializable. Change-detection is a full re-serialize per commit; dirty-hint acceleration is a later optimization behind the same seam.
+- diffSnapshots (function): function diffSnapshots(prev: WorldSnapshot, next: WorldSnapshot, revision: number): WorldDiff — Diff two full {@link WorldSnapshot}s directly, stamping the result at `revision` — the stateless counterpart of {@link createWorldReplicator} for hosts that persist snapshots rather than keep a live tracker (Convex reconstructs per invocation). `applyWorldDiff(prev, diffSnapshots(prev, next, r))` reproduces `next`.
+- fly (function): function fly(config: { app: string; topology?: MultiplayerTopology; path?: string; authority?: MultiplayerAuthority }): MultiplayerAdapterConfig
 - isSaveEnabled (function): function isSaveEnabled(config: SaveConfig): config is Exclude<SaveConfig, "none">
-- lan (function): function lan(config?: { topology?: MultiplayerTopology; port?: number; path?: string; }): MultiplayerAdapterConfig
+- isServerAuthoritative (function): function isServerAuthoritative(multiplayer: unknown): boolean — True when the adapter opts into host-authoritative world replication (`authority: "server"`).
+- lan (function): function lan(config?: { topology?: MultiplayerTopology; port?: number; path?: string; authority?: MultiplayerAuthority; }): MultiplayerAdapterConfig
 - markPlayerDirty (function): function markPlayerDirty(snapshot: GameRuntimeSnapshot, userId: string): GameRuntimeSnapshot
 - markServerDirty (function): function markServerDirty(snapshot: GameRuntimeSnapshot): GameRuntimeSnapshot
+- memoryWorldStore (function): function memoryWorldStore(seed?: HostedWorldRecord): HostedWorldStore — In-process {@link HostedWorldStore} for tests, local play, and the browser-tab P2P host.
 - multiplayerAdapterKind (function): function multiplayerAdapterKind(multiplayer: unknown): string | null
 - offline (function): function offline(): MultiplayerAdapterConfig
-- p2p (function): function p2p(config?: { topology?: MultiplayerTopology; room?: string }): MultiplayerAdapterConfig
+- p2p (function): function p2p(config?: { topology?: MultiplayerTopology; room?: string; authority?: MultiplayerAuthority }): MultiplayerAdapterConfig
 - parseSaveAutoMs (function): function parseSaveAutoMs(auto: string): number
+- pullWorld (function): function pullWorld(session: HostedWorldSession, mirror: WorldMirror): void — Pull one replication step from a co-located {@link HostedWorldSession} into a {@link WorldMirror} — the no-network local path (host and client in one process). A fresh mirror pulls a baseline; thereafter it pulls a diff since its own revision. The same `sync(sinceRevision)` call is what a networked transport marshals.
 - runCommand (function): function runCommand<TInput>(snapshot: GameRuntimeSnapshot, commands: Record<string, CommandDef<TInput>>, commandName: string, input: TInput, actorUserId: string): RunCommandResult
 - saveScopeIncludesChunks (function): function saveScopeIncludesChunks(scope: SaveScope): boolean
 - saveScopeIncludesPlayer (function): function saveScopeIncludesPlayer(scope: SaveScope): boolean
 - servers (function): function servers(config: ServersPoolConfig): ServersPoolConfig
-- socketIo (function): function socketIo(config?: { topology?: MultiplayerTopology; url?: string }): MultiplayerAdapterConfig
+- socketIo (function): function socketIo(config?: { topology?: MultiplayerTopology; url?: string; authority?: MultiplayerAuthority }): MultiplayerAdapterConfig
 - splitProfilePlayer (function): function splitProfilePlayer(player: RuntimePlayerRow): { persistent: RuntimePlayerRow; session: Record<string, unknown>; }
-- ws (function): function ws(config?: { topology?: MultiplayerTopology; url?: string }): MultiplayerAdapterConfig
+- ws (function): function ws(config?: { topology?: MultiplayerTopology; url?: string; authority?: MultiplayerAuthority }): MultiplayerAdapterConfig
 
 ### @jgengine/core/input/actionBindings
 
@@ -1201,13 +1413,13 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - ActionBindingMap (type): type ActionBindingMap<TAction extends string, TCode extends string = string> = Record< TAction, ActionBinding<TCode> >
 - ActionBindingModes (interface): interface ActionBindingModes<TCode extends string = string>
 - ActionCodes (type): type ActionCodes<TCode extends string = string> = | readonly TCode[] | { hold?: readonly TCode[]; toggle?: readonly TCode[]; repeatMs?: number }
-- ActionCodesMap (type): type ActionCodesMap<TAction extends string = string, TCode extends string = string> = Record< TAction, ActionCodes<TCode> >
+- ActionCodesMap (type): type ActionCodesMap<TAction extends string = string, TCode extends string = string> = Record< TAction, ActionCodes<TCode> > — Maps each game action name to the input codes (hold/toggle keys, repeat rate) that trigger it.
 - ActionStateBindingMap (type): type ActionStateBindingMap<TAction extends string, TCode extends string = string> = Record< TAction, ActionBindingConfig<TCode> >
 - ActionStateTracker (interface): interface ActionStateTracker<TAction extends string>
 - ShouldDispatchActionInput (interface): interface ShouldDispatchActionInput
 - actionLabel (function): function actionLabel(map: ActionCodesMap, action: string): string | null — Short display label for an action's first bound code, or null when unbound.
 - actionRepeatMs (function): function actionRepeatMs(codes: ActionCodes | undefined): number | undefined
-- bindingLabel (function): function bindingLabel(code: string): string
+- bindingLabel (function): function bindingLabel(code: string): string — Short display label for a raw key/button code (e.g. `"KeyW"` → `"W"`).
 - bindingMatches (function): function bindingMatches<TCode extends string>(code: TCode, binding: ActionBinding<TCode>): boolean
 - createActionStateTracker (function): function createActionStateTracker<TAction extends string, TCode extends string = string>(map: ActionStateBindingMap<TAction, TCode>): ActionStateTracker<TAction>
 - hotbarSlotActionIndex (function): function hotbarSlotActionIndex(action: string): number | null — 0-based slot index for a hotbar-slot action name (`slot1`, `hotbarSlot1`), or null.
@@ -1236,6 +1448,7 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - clampAxis (function): function clampAxis(value: number, range: AxisRange): number
 - createAxisChannel (function): function createAxisChannel<TAxes extends string>(config: GenericAxisConfig<TAxes>): GenericAxisChannel<TAxes>
 - rampToward (function): function rampToward(current: number, target: number, rate: number, dt: number): number
+- sampleAxisBindings (function): function sampleAxisBindings<TAxes extends string>(bindings: Record<TAxes, AxisBinding>, isDown: (code: string) => boolean, pointer?: PointerAxisState | null, ranges?: Partial<Record<TAxes, AxisRange>>): Record<TAxes, number> — Instantaneous (unsmoothed) analog sample of an axis binding map — the per-frame target an `AxisChannel` ramps toward, exposed as a pure read for `ctx.input.axis` and headless sampling. Each axis is its binding's positive-minus-negative held state (or its pointer source while a pointer is active), clamped to the axis range; axes without a listed range default to bipolar `[-1, 1]`.
 
 ### @jgengine/core/input/bindingOverrides
 
@@ -1316,7 +1529,7 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - ContextTargetKind (type): type ContextTargetKind = "entity" | "object"
 - ContextVerb (interface): interface ContextVerb — One right-click verb: a label plus the command it dispatches (walk-then-act supported by args).
 - buildContextMenu (function): function buildContextMenu(input: BuildContextMenuInput): ContextMenu | null — Assemble a menu from a target's catalog verbs; null when the target lists none.
-- contextVerb (function): function contextVerb(label: string, command: string, args?: Record<string, unknown>): ContextVerb
+- contextVerb (function): function contextVerb(label: string, command: string, args?: Record<string, unknown>): ContextVerb — Builds a {@link ContextVerb} for a right-click menu entry.
 - contextVerbInput (function): function contextVerbInput(menu: ContextMenu, verb: ContextVerb): Record<string, unknown> — Command input a chosen verb dispatches: the verb's own args, plus the target id and the world point, so a single handler can walk the actor to the target then perform it.
 
 ### @jgengine/core/interaction/proximityPrompt
@@ -1332,7 +1545,7 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - ProximityPromptDisplay (type): type ProximityPromptDisplay = KeybindPromptDisplay | GaugePromptDisplay | LabelPromptDisplay
 - command (function): function command(name: string, input?: unknown): PromptCommand
 - gauge (function): function gauge(gaugeId: string): GaugePromptDisplay
-- keybind (function): function keybind(actionId: string): KeybindPromptDisplay
+- keybind (function): function keybind(actionId: string, label?: string): KeybindPromptDisplay
 - label (function): function label(text: string): LabelPromptDisplay
 - positionedPromptsEqual (function): function positionedPromptsEqual(a: PositionedPrompt, b: PositionedPrompt): boolean
 - promptCommandsEqual (function): function promptCommandsEqual(a: PromptCommand | null, b: PromptCommand | null): boolean
@@ -1446,7 +1659,7 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - RolledItem (interface): interface RolledItem
 - RollerConfig (interface): interface RollerConfig
 - createAffixRoller (function): function createAffixRoller(config: RollerConfig): AffixRoller
-- seededRng (function): function seededRng(seed: string | number): () => number
+- seededRng (function): function seededRng(seed: string | number): () => number — Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence.
 
 ### @jgengine/core/item/durability
 
@@ -1507,7 +1720,7 @@ Imports use deep paths: `@jgengine/core/<path>`.
 
 - CHANGELOG (const): const CHANGELOG: Record<string, ChangelogEntry>
 - ChangelogEntry (interface): interface ChangelogEntry
-- VERSION (const): const VERSION: "0.9.0"
+- VERSION (const): const VERSION: "0.10.0"
 
 ### @jgengine/core/movement/avatarGait
 
@@ -1585,10 +1798,20 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - constrainStepToAxis (function): function constrainStepToAxis(stepX: number, stepZ: number, axis: "x" | "z"): MovementFrameStep — Zeroes the off-axis component so travel is locked to a single world axis (`PlayerMovementConfig.mode: "axis"`).
 - createEmptyMovementKeys (function): function createEmptyMovementKeys(): MovementKeysState
 - createPlayerMotionState (function): function createPlayerMotionState(): PlayerMotionState
+- nearbyObstacles (function): function nearbyObstacles(objects: readonly { position: readonly [number, number, number] }[], center: readonly [number, number, number], radius: number = OBSTACLE_GATHER_RADIUS): CollisionObstacle[] — Placed objects within `radius` (XZ) of `center`, as {@link CollisionObstacle}s to pre-filter for {@link resolveObstacleStep}.
 - resolveMovementIntent (function): function resolveMovementIntent(keys: MovementKeysState, canMove: boolean): MovementIntent — Translate the set of held keys into an intent. When `canMove` is false (a menu is open, the world is paused) the avatar is fully idle so it never drifts behind an overlay.
 - resolveObstacleStep (function): function resolveObstacleStep(current: readonly [number, number, number], stepX: number, stepZ: number, obstacles: readonly CollisionObstacle[], playerRadius: number = DEFAULT_OBSTACLE_PLAYER_RADIUS): MovementFrameStep — Resolve a horizontal step against nearby placed objects with classic axis-separated sliding (try X, then Z against the post-X position) so walking into a wall stops the blocked axis but keeps sliding along the other. Obstacles are treated as circle-vs-AABB in the X/Z plane, inflated by `playerRadius`; an obstacle whose vertical span misses the player's feet-to-head span is skipped entirely. Callers should pre-filter to nearby objects — this also early-exits per obstacle on horizontal distance.
 - snapPositionToGrid (function): function snapPositionToGrid(x: number, z: number, cellSize: number): [number, number] — Snap a world position to its containing cell's center, matching the bounds-free form of `navGrid`'s and `tacticalGrid`'s `floor` + half-cell convention (`PlayerMovementConfig.mode: "grid"`).
 
+### @jgengine/core/movement/playerMovement
+
+- PlayerMovementTuning (interface): interface PlayerMovementTuning — The resolved, per-world movement configuration {@link stepPlayerMovement} integrates against — the same inputs the shell FrameDriver used to read piecemeal, gathered into one struct so single-player and host movement run identical math.
+- forgetPlayerMovement (function): function forgetPlayerMovement(ctx: GameContext, userId: string): void — Drop a player's retained movement state (heading + kinematic body) — call on leave so a rejoin starts fresh instead of resuming stale velocity.
+- playerMovementHeading (function): function playerMovementHeading(ctx: GameContext, userId: string): number — One player's current heading (radians), integrated by {@link stepPlayerMovement} — the shell reads it back into its camera/aim yaw.
+- resolvePhysicsTuning (function): function resolvePhysicsTuning(physics: PhysicsConfig | undefined): MovementTuningOverrides | undefined — Maps a game's declared `physics` onto the movement controllers' tuning. `PhysicsConfig.gravity` is a signed world acceleration (negative points down), but the controllers integrate `velocityY -= gravityAcceleration * dt` and expect a positive downward magnitude — so gravity is negated here to keep down-pointing gravity pulling down.
+- resolvePlayerMovementTuning (function): function resolvePlayerMovementTuning(opts: { collision?: VoxelCollisionConfig; movement?: PlayerMovementConfig; physics?: PhysicsConfig; world?: WorldFeature; }): PlayerMovementTuning — Gather a game's collision/movement/physics/world config into a {@link PlayerMovementTuning} — call once per world; both the shell and a host pass the result to {@link stepPlayerMovement}.
+- stepPlayerMovement (function): function stepPlayerMovement(ctx: GameContext, userId: string, input: InputFrame, dt: number, tuning: PlayerMovementTuning, heading?: number): void — Integrate one player's movement for a tick from their held-input frame and commit the pose — the single genre-agnostic controller both the shell (its local player) and a host (each connected player in `onTick`) call, so single-player and server-authoritative movement are identical. Reads the player's controlled entity, terrain, scene solids, and pending motion impulses; writes the entity pose via `setPose`. Retains heading + kinematic body per `userId` on the `ctx`. Pass `heading` to override the internally-integrated yaw (the shell owns yaw for its camera); omit it and the controller turns from the frame's `turnLeft`/`turnRight` actions.
+
 ### @jgengine/core/movement/poseState
 
 - AimMode (type): type AimMode = "hip" | "ads"
@@ -1964,8 +2187,8 @@ Imports use deep paths: `@jgengine/core/<path>`.
 
 ### @jgengine/core/random/rng
 
-- seededRng (function): function seededRng(seed: string | number): () => number
-- seededStreams (function): function seededStreams(seed: string | number): (stream: string) => () => number
+- seededRng (function): function seededRng(seed: string | number): () => number — Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence.
+- seededStreams (function): function seededStreams(seed: string | number): (stream: string) => () => number — Derives independent, deterministic {@link seededRng} streams from one base seed, keyed by stream name.
 
 ### @jgengine/core/random/seedLink
 
@@ -1975,21 +2198,31 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - seedFromUrl (function): function seedFromUrl(url: string, param = DEFAULT_SEED_PARAM): string | null
 - withSeedParam (function): function withSeedParam(url: string, seed: string | number, param = DEFAULT_SEED_PARAM): string
 
+### @jgengine/core/render/postProcessing
+
+- AoConfig (interface): interface AoConfig — Ground-truth ambient occlusion stage — darkens contact creases and cavities for depth.
+- BloomConfig (interface): interface BloomConfig — UnrealBloom stage — soft HDR glow around bright pixels (sun, glints, emissive).
+- GradeConfig (interface): interface GradeConfig — Final colour-grade stage: lift/gain/gamma, saturation, vignette, film grain — applied in display space after tone mapping.
+- PostProcessingConfig (interface): interface PostProcessingConfig — Declarative post-processing chain (RenderPass → AO → Bloom → tone-map output → Grade). Present on a game means the shell mounts an `EffectComposer` and owns the render; absent means the renderer draws directly (unchanged). Each stage is a config object, `false` to skip, or omitted for its default. Pure data — no three.js types leak into core.
+- ToneMappingMode (type): type ToneMappingMode = "aces" | "agx" | "reinhard" | "cineon" | "linear" | "none" — Renderer tone-mapping curve applied by the post chain's output stage.
+
 ### @jgengine/core/runtime/adapter
 
-- MultiplayerAdapterConfig (type): type MultiplayerAdapterConfig = | { kind: "convex"; topology?: MultiplayerTopology } | { kind: "ws"; topology?: MultiplayerTopology; url?: string } | { kind: "socketio"; topology?: MultiplayerTopology; url?: string } | { kind: "p2p"; topology?: MultiplayerTopology; room?: string } | { kind: "lan"; t…
+- MultiplayerAdapterConfig (type): type MultiplayerAdapterConfig = | { kind: "convex"; topology?: MultiplayerTopology; authority?: MultiplayerAuthority } | { kind: "ws"; topology?: MultiplayerTopology; url?: string; authority?: MultiplayerAuthority } | { kind: "socketio"; topology?: MultiplayerTopology; url?: string; authority?: Mult…
+- MultiplayerAuthority (type): type MultiplayerAuthority = "server" | "client" — Where the world simulation is authoritative. `"client"` (default) keeps the historical model — each client runs its own `onTick` and syncs only presence/feeds/chat. `"server"` opts into host-authoritative replication: the host runs the loop, and the shell mirrors the server's world into the local `ctx` instead of simulating locally.
 - MultiplayerTopology (type): type MultiplayerTopology = "shared" | "lobbies" | "private"
 - ServersPoolConfig (type): type ServersPoolConfig = { maxServers: number; slotsPerServer: number; minPlayersToStart?: number; adapter: MultiplayerAdapterConfig; }
 - adapterOf (function): function adapterOf(multiplayer: unknown): MultiplayerAdapterConfig | null
-- convex (function): function convex(config?: { topology?: MultiplayerTopology }): MultiplayerAdapterConfig
-- fly (function): function fly(config: { app: string; topology?: MultiplayerTopology; path?: string }): MultiplayerAdapterConfig
-- lan (function): function lan(config?: { topology?: MultiplayerTopology; port?: number; path?: string; }): MultiplayerAdapterConfig
+- convex (function): function convex(config?: { topology?: MultiplayerTopology; authority?: MultiplayerAuthority }): MultiplayerAdapterConfig
+- fly (function): function fly(config: { app: string; topology?: MultiplayerTopology; path?: string; authority?: MultiplayerAuthority }): MultiplayerAdapterConfig
+- isServerAuthoritative (function): function isServerAuthoritative(multiplayer: unknown): boolean — True when the adapter opts into host-authoritative world replication (`authority: "server"`).
+- lan (function): function lan(config?: { topology?: MultiplayerTopology; port?: number; path?: string; authority?: MultiplayerAuthority; }): MultiplayerAdapterConfig
 - multiplayerAdapterKind (function): function multiplayerAdapterKind(multiplayer: unknown): string | null
 - offline (function): function offline(): MultiplayerAdapterConfig
-- p2p (function): function p2p(config?: { topology?: MultiplayerTopology; room?: string }): MultiplayerAdapterConfig
+- p2p (function): function p2p(config?: { topology?: MultiplayerTopology; room?: string; authority?: MultiplayerAuthority }): MultiplayerAdapterConfig
 - servers (function): function servers(config: ServersPoolConfig): ServersPoolConfig
-- socketIo (function): function socketIo(config?: { topology?: MultiplayerTopology; url?: string }): MultiplayerAdapterConfig
-- ws (function): function ws(config?: { topology?: MultiplayerTopology; url?: string }): MultiplayerAdapterConfig
+- socketIo (function): function socketIo(config?: { topology?: MultiplayerTopology; url?: string; authority?: MultiplayerAuthority }): MultiplayerAdapterConfig
+- ws (function): function ws(config?: { topology?: MultiplayerTopology; url?: string; authority?: MultiplayerAuthority }): MultiplayerAdapterConfig
 
 ### @jgengine/core/runtime/cameraDirector
 
@@ -2008,6 +2241,7 @@ Imports use deep paths: `@jgengine/core/<path>`.
 
 - CatalogEntityRole (type): type CatalogEntityRole = "player" | "enemy" | "hostile" | "npc" | "vehicle"
 - FloatTextInput (interface): interface FloatTextInput
+- GameAudio (interface): interface GameAudio — Reachable audio seam on `ctx.game`: `play`, `music`, and `resume` route through the `audio.play`/`audio.music`/`audio.resume` events the shell's audio engine listens on, so game code triggers sound without importing the shell.
 - GameContext (interface): interface GameContext
 - GameContextCards (interface): interface GameContextCards
 - GameContextCommands (interface): interface GameContextCommands
@@ -2075,8 +2309,27 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - topLeaderboardRows (function): function topLeaderboardRows(rows: Iterable<LeaderboardRow>, args: { gameId: string; stat: string; scope: LeaderboardScope; serverId?: string; limit?: number; }): LeaderboardEntry[]
 - trimFeedEntries (function): function trimFeedEntries<T>(entries: T[], limit = FEED_RING_LIMIT): T[]
 
+### @jgengine/core/runtime/hostedGameRunner
+
+- HostedGameRunner (interface): interface HostedGameRunner — The GameContext-loop equivalent of the pure-reducer `createGameHost`: one authoritative `createGameContext` per world, driven server-side. `onInit` runs once at construction; `onNewPlayer`/`onPlayerLeave` fire per join/leave; `tick` advances `onTick` then commits a revision. Clients pull a full {@link WorldSnapshot} baseline once, then per-tick {@link WorldDiff}s from their last revision. Games ship only normal GameContext code — the runner adds no per-game surface.
+- HostedGameRunnerOptions (interface): interface HostedGameRunnerOptions<TAssetRef extends ModelAssetRef, TMultiplayer> — Config for {@link createHostedGameRunner}: the game definition, its content lookup, and an optional host identity.
+- INPUT_COMMAND (const): const INPUT_COMMAND: "engine.input" — Reserved command name the authoritative host intercepts on the existing `runCommand` transport to route a client's {@link InputFrame} to `session.input`, so per-tick input needs no separate wire.
+- InputFrame (interface): interface InputFrame — One client's input for a tick — the semantic held-action set plus pointer state, the serializable, over-the-wire counterpart of {@link InputSnapshot} the host stores per connected player.
+- createHostedGameRunner (function): function createHostedGameRunner<TAssetRef extends ModelAssetRef, TMultiplayer>(options: HostedGameRunnerOptions<TAssetRef, TMultiplayer>): HostedGameRunner — Build a {@link HostedGameRunner} — one authoritative GameContext world driven server-side from the game's own loop.
+
+### @jgengine/core/runtime/hostedWorldSession
+
+- HostedWorldRecord (interface): interface HostedWorldRecord — One hosted world's persisted authoritative state — the unit a {@link HostedWorldStore} loads and saves.
+- HostedWorldSession (interface): interface HostedWorldSession — The stateful host substrate a long-lived backend binds (ws server, browser P2P host): a live {@link HostedGameRunner} loaded from a {@link HostedWorldStore}, auto-persisted on tick, serving each client a baseline then diffs. The stateless Convex path doesn't use this — it reconstructs a runner from the same store per invocation and diffs with `diffSnapshots`. Either way the store seam and the game code are identical.
+- HostedWorldSessionOptions (interface): interface HostedWorldSessionOptions<TAssetRef extends ModelAssetRef, TMultiplayer> — Config for {@link createHostedWorldSession}: the game, its persistence store, and the auto-save cadence.
+- HostedWorldStore (interface): interface HostedWorldStore — Narrow persistence seam for a hosted world — the {@link HostedWorldRecord} counterpart of `HostPersistence`. Backends implement it (memory/file/sql/convex); the session never names one. A stateful host loads once and saves on a cadence; a stateless host reconstructs from `load()` each invocation.
+- HostedWorldSync (type): type HostedWorldSync = | { kind: "baseline"; revision: number; snapshot: WorldSnapshot } | { kind: "diff"; diff: WorldDiff } — A client replication pull: a full baseline (first sync / fell behind) or a diff since the client's cursor.
+- createHostedWorldSession (function): function createHostedWorldSession<TAssetRef extends ModelAssetRef, TMultiplayer>(options: HostedWorldSessionOptions<TAssetRef, TMultiplayer>): HostedWorldSession — Build a {@link HostedWorldSession} — a live runner loaded from a {@link HostedWorldStore} and auto-persisted on tick.
+- memoryWorldStore (function): function memoryWorldStore(seed?: HostedWorldRecord): HostedWorldStore — In-process {@link HostedWorldStore} for tests, local play, and the browser-tab P2P host.
+
 ### @jgengine/core/runtime/inputSnapshot
 
+- InputFrame (interface): interface InputFrame — One client's input for a tick — the semantic held-action set plus pointer state, the serializable, over-the-wire counterpart of {@link InputSnapshot} the host stores per connected player.
 - InputSnapshot (interface): interface InputSnapshot
 - createInputSnapshot (function): function createInputSnapshot(): InputSnapshot
 
@@ -2085,6 +2338,7 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - MotionIntentBatch (interface): interface MotionIntentBatch
 - MotionIntents (interface): interface MotionIntents — Seam for game code to reach the motion the shell's FrameDriver otherwise owns privately (#162.4). Game code calls `impulse`, `pushHorizontal`, `setVerticalVelocity`, and/or `setY` from `onTick` or commands; the shell calls `takePending()` once per frame, before integrating gravity, to drain what accumulated. `setY` wins over physics for that frame; impulses add to the velocity the driver is about to integrate; a later `setVerticalVelocity` replaces that velocity outright. Horizontal pushes compose with the walk controller (#282.4): they add to its horizontal velocity and decay naturally as it re-blends toward input — knockback, dashes, explosion shoves without raw `setPose` offsets.
 - applyHorizontalImpulses (function): function applyHorizontalImpulses(velocityX: number, velocityZ: number, batch: MotionIntentBatch | null): readonly [number, number] — Fold a batch's horizontal pushes into a controller's velocity pair — shared by the walk and voxel drivers.
+- applyMotionImpulses (function): function applyMotionImpulses(currentVelocity: number, batch: MotionIntentBatch | null): number — Fold a batch's vertical impulses into a controller's velocity, then apply an outright `setVerticalVelocity` override — the vertical counterpart of {@link applyHorizontalImpulses}.
 - createMotionIntents (function): function createMotionIntents(): MotionIntents
 
 ### @jgengine/core/runtime/persistenceScope
@@ -2159,11 +2413,42 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - VisibilityPoint (interface): interface VisibilityPoint — World-space point; `z` is optional for 2D adapters.
 - VisibilitySystem (class): class VisibilitySystem — Engine-level visibility and asset-residency policy.
 
+### @jgengine/core/runtime/worldChannel
+
+- WorldClientFrame (type): type WorldClientFrame = | { t: "join"; isNew: boolean } | { t: "leave" } | { t: "command"; name: string; input: unknown } | { t: "input"; frame: InputFrame } — Client→host frame: a player's session verbs. What a transport marshals upstream.
+- WorldClientLink (interface): interface WorldClientLink — The client end of a {@link WorldHost} connection: applies server frames to a local `ctx`, sends session verbs upstream.
+- WorldHost (interface): interface WorldHost — The transport-agnostic host: fans one {@link HostedWorldSession} out to many connections, each tracking its own revision cursor so a joiner gets a baseline and everyone else gets diffs. A ws server, a Convex function, or an in-process loopback all drive the same shape — decode a frame → `connection.receive`; after `session.tick` → `broadcast`. No wire format is assumed; frames are plain data a transport serializes however it likes.
+- WorldHostConnection (interface): interface WorldHostConnection — One client's link on the host side: routes its upstream frames into the shared session, pushes it sync frames.
+- WorldServerFrame (type): type WorldServerFrame = | { t: "baseline"; revision: number; snapshot: WorldSnapshot } | { t: "diff"; diff: WorldDiff } — Host→client frame: the full baseline a joiner needs, then per-tick diffs. What a transport marshals downstream.
+- createWorldClientLink (function): function createWorldClientLink(ctx: Pick<GameContext, "hydrate">, send: (frame: WorldClientFrame) => void): WorldClientLink — Build a {@link WorldClientLink} — the client end that mirrors host frames into `ctx` and sends session verbs upstream.
+- createWorldHost (function): function createWorldHost(session: HostedWorldSession): WorldHost — Build a {@link WorldHost} fanning one {@link HostedWorldSession} out to many cursor-tracked connections.
+
+### @jgengine/core/runtime/worldMirror
+
+- WorldMirror (interface): interface WorldMirror — The client end of host-authoritative replication: folds a host's baseline + {@link WorldDiff} stream onto a local {@link GameContext}. It keeps the last full {@link WorldSnapshot}, advances it with each diff, and pushes the result through `ctx.hydrate` — so the client mirrors exactly the subsystems its own game opted into and silently ignores host modules it lacks. This is the inverse of a {@link HostedWorldSession}; the transport in between (loopback, ws, Convex) is irrelevant.
+- createWorldMirror (function): function createWorldMirror(ctx: Pick<GameContext, "hydrate">): WorldMirror — Build a {@link WorldMirror} that replicates a host's baseline + diff stream onto `ctx` via `ctx.hydrate`.
+- pullWorld (function): function pullWorld(session: HostedWorldSession, mirror: WorldMirror): void — Pull one replication step from a co-located {@link HostedWorldSession} into a {@link WorldMirror} — the no-network local path (host and client in one process). A fresh mirror pulls a baseline; thereafter it pulls a diff since its own revision. The same `sync(sinceRevision)` call is what a networked transport marshals.
+
+### @jgengine/core/runtime/worldReplication
+
+- WorldDiff (interface): interface WorldDiff — A revision-stamped delta over a {@link WorldSnapshot}. The host sends one per tick to each client, carrying only what changed since that client's last acknowledged revision — entity/stat/store deltas plus whole snapshots of any other opted-in module (feed, leaderboard, chat, …) that changed. Fold it onto a prior baseline with {@link applyWorldDiff}.
+- WorldReplicator (type): type WorldReplicator = ReturnType<typeof createWorldReplicator> — The stateful diff tracker returned by {@link createWorldReplicator}: `commit()`, `diff(sinceRevision)`, `revision()`.
+- applyWorldDiff (function): function applyWorldDiff(baseline: WorldSnapshot, diff: WorldDiff): WorldSnapshot — Fold a {@link WorldDiff} onto a prior {@link WorldSnapshot} baseline, returning the next full snapshot — the client-side inverse of {@link createWorldReplicator}. Pure data in, pure data out: upserts changed entities, stats and store keys, drops the removed ones, and replaces changed module snapshots wholesale.
+- createWorldReplicator (function): function createWorldReplicator(takeSnapshot: () => WorldSnapshot): { commit: () => number; diff: (sinceRevision: number) => WorldDiff; revision: () => number; } — Turns successive full {@link WorldSnapshot}s into per-client {@link WorldDiff}s. Each `commit()` re-reads the world, stamps every item that changed with the new revision, and remembers removals; `diff(sinceRevision)` then replays exactly the items stamped after that revision. Everything the tracker holds is JSON — the same shape that rides the wire — so a diff is inherently serializable. Change-detection is a full re-serialize per commit; dirty-hint acceleration is a later optimization behind the same seam.
+- diffSnapshots (function): function diffSnapshots(prev: WorldSnapshot, next: WorldSnapshot, revision: number): WorldDiff — Diff two full {@link WorldSnapshot}s directly, stamping the result at `revision` — the stateless counterpart of {@link createWorldReplicator} for hosts that persist snapshots rather than keep a live tracker (Convex reconstructs per invocation). `applyWorldDiff(prev, diffSnapshots(prev, next, r))` reproduces `next`.
+
+### @jgengine/core/runtime/worldSnapshot
+
+- SnapshotModule (interface): interface SnapshotModule<T = unknown> — The replication seam for host-authoritative shared worlds: the opt-in feature manifest *is* the replication schema. Each live subsystem a game opts into registers a {@link SnapshotModule} keyed by name; the host serializes exactly the registered set into a {@link WorldSnapshot} and a client hydrates the same keys back. Adding a replicated subsystem is a registration, never a new branch.
+- WorldSnapshot (type): type WorldSnapshot = Record<string, unknown> — Full world baseline keyed by {@link SnapshotModule.key} — one entry per opted-in subsystem.
+- applyWorldSnapshot (function): function applyWorldSnapshot(modules: readonly SnapshotModule[], snapshot: WorldSnapshot): void — Hydrate every registered module whose key is present in `snapshot`; keys absent from it are left untouched.
+- composeWorldSnapshot (function): function composeWorldSnapshot(modules: readonly SnapshotModule[]): WorldSnapshot — Serialize every registered module into one keyed baseline — the host→client full-world send.
+
 ### @jgengine/core/scene/assetCatalog
 
 - AssetCatalog (interface): interface AssetCatalog<TMeta extends ModelAssetRef = ModelAssetRef>
 - ModelAssetRef (interface): interface ModelAssetRef
-- ModelDims (interface): interface ModelDims
+- ModelDims (interface): interface ModelDims — Measured horizontal footprint, footprint center, and lowest Y of a model in model space.
 - createAssetCatalog (function): function createAssetCatalog<TMeta extends ModelAssetRef = ModelAssetRef>(): AssetCatalog<TMeta>
 
 ### @jgengine/core/scene/assetPreload
@@ -2203,6 +2488,8 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - ColliderDef (interface): interface ColliderDef
 - ColliderPurpose (type): type ColliderPurpose = "physical" | "damage"
 - ColliderShape (type): type ColliderShape = | { kind: "sphere"; radius: number; offset?: EntityPosition } | { kind: "aabb"; halfExtents: EntityPosition; offset?: EntityPosition }
+- DEFAULT_ENTITY_BODY_HALF_EXTENTS (const): const DEFAULT_ENTITY_BODY_HALF_EXTENTS: EntityPosition — Matches the shell's fallback actor capsule (~0.7m wide, feet at y=0 to head at ~1.8m).
+- DEFAULT_ENTITY_BODY_OFFSET (const): const DEFAULT_ENTITY_BODY_OFFSET: EntityPosition — Entity-local center of the default body hitbox (half its height above the feet).
 - DEFAULT_ENTITY_HIT_RADIUS (const): const DEFAULT_ENTITY_HIT_RADIUS: 0.5
 - DEFAULT_OBJECT_HALF_EXTENTS (const): const DEFAULT_OBJECT_HALF_EXTENTS: EntityPosition
 - EntityColliderSet (interface): interface EntityColliderSet
@@ -2212,6 +2499,7 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - defaultEntityColliders (function): function defaultEntityColliders(): EntityColliderSet
 - defaultObjectColliders (function): function defaultObjectColliders(halfExtents: EntityPosition = DEFAULT_OBJECT_HALF_EXTENTS): EntityColliderSet
 - resolveColliders (function): function resolveColliders(set: EntityColliderSet | null | undefined): ResolvedCollider[]
+- scaledObjectColliders (function): function scaledObjectColliders(scale: readonly [number, number, number]): EntityColliderSet — Blocking physical body derived from an object's rendered scale: a grounded box spanning the visual (base at y=0, matching the shell's fallback mesh).
 - worldOffset (function): function worldOffset(local: EntityPosition | undefined, position: EntityPosition, rotationY: number): EntityPosition
 
 ### @jgengine/core/scene/entityStats
@@ -2225,11 +2513,14 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - applyPoolDelta (function): function applyPoolDelta(map: StatValueMap, statId: string, amount: number): PoolDeltaResult
 - createEntityStatsApi (function): function createEntityStatsApi(resolve: (instanceId: string) => StatValueMap | undefined): EntityStatsApi
 - getStatValue (function): function getStatValue(map: StatValueMap, statId: string): StatValue | null
+- hydrateEntityStats (function): function hydrateEntityStats(store: Map<string, StatValueMap>, data: Record<string, StatValueMap>): void — Replace a live stat store with deep copies of a snapshot, clearing entities absent from it.
 - seedStatValues (function): function seedStatValues(catalogStats: StatCatalog): StatValueMap
 - setStatValue (function): function setStatValue(map: StatValueMap, statId: string, patch: StatValuePatch): StatValueMap
+- snapshotEntityStats (function): function snapshotEntityStats(store: ReadonlyMap<string, StatValueMap>): Record<string, StatValueMap> — Deep-copy the per-entity stat maps into a serializable record — the transport counterpart of {@link hydrateEntityStats}.
 
 ### @jgengine/core/scene/entityStore
 
+- EntityBlackboard (interface): interface EntityBlackboard — Per-entity scratch and cooldown timers, auto-cleared on despawn (#533.8) — the home for AI state (next-shot-at, alert level) that would otherwise be smuggled through the serializable `meta` or a hand-pruned module-level map. Keys share one namespace per entity: `arm`/`ready`/`remaining` store a deadline under a key, `get`/`set` store arbitrary scratch.
 - EntityMovement (interface): interface EntityMovement
 - EntityPose (interface): interface EntityPose
 - EntityPosition (type): type EntityPosition = readonly [number, number, number]
@@ -2630,8 +2921,8 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - FallingGridSnapshot (interface): interface FallingGridSnapshot<TCell>
 - GravityIntervalConfig (interface): interface GravityIntervalConfig
 - LockState (interface): interface LockState — Elapsed grounded time for the lock-delay state machine. `null` means airborne / not timing.
-- createFallingGrid (function): function createFallingGrid<TCell>(config: FallingGridConfig): FallingGrid<TCell> — A game-agnostic cell grid for gravity-driven falling-block mechanics: bounded occupancy, footprint placement/collision, line-clear collapse, column-gravity settle (for match-3/sand style cascades), and a pure lock-delay helper. Extracted from `Games/block-stacker`'s tetris logic so any falling-block game can adopt it instead of reimplementing the grid.
-- gravityIntervalMs (function): function gravityIntervalMs(level: number, config: GravityIntervalConfig = {}): number — Gravity tick interval for a given level: linear speed-up with a floor, generalizing `Games/block-stacker`'s `gravityInterval` (`max(0.05, 0.8 - level * 0.07)` seconds) to milliseconds with configurable base/step/floor.
+- createFallingGrid (function): function createFallingGrid<TCell>(config: FallingGridConfig): FallingGrid<TCell> — A game-agnostic cell grid for gravity-driven falling-block mechanics: bounded occupancy, footprint placement/collision, line-clear collapse, column-gravity settle (for match-3/sand style cascades), and a pure lock-delay helper. Extracted from falling-block tetris logic so any falling-block game can adopt it instead of reimplementing the grid.
+- gravityIntervalMs (function): function gravityIntervalMs(level: number, config: GravityIntervalConfig = {}): number — Gravity tick interval for a given level: linear speed-up with a floor, generalizing a falling-block `gravityInterval` (`max(0.05, 0.8 - level * 0.07)` seconds) to milliseconds with configurable base/step/floor.
 
 ### @jgengine/core/tactics/predictiveQuery
 
@@ -2781,6 +3072,33 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - TurnState (interface): interface TurnState
 - createTurnLoop (function): function createTurnLoop<TAction = unknown>(config: TurnLoopConfig): TurnLoop<TAction>
 
+### @jgengine/core/ui/gameLayout
+
+- DetectCollisionsOptions (interface): interface DetectCollisionsOptions — Options for `detectLayoutCollisions`.
+- GameLayoutMode (type): type GameLayoutMode = "desktop-wide" | "desktop-compact" | "mobile-landscape" | "mobile-portrait" — The explicit composition mode a game renders for — not a scaled desktop layout.
+- GameViewportLayout (interface): interface GameViewportLayout — The shared live geometry the engine allocates once and every UI subsystem reads.
+- HudPriority (type): type HudPriority = "critical" | "secondary" | "tertiary" — Gameplay-importance tier of a HUD element.
+- Insets (interface): interface Insets — Edge insets in CSS pixels (safe areas, reservations).
+- LayoutCollision (interface): interface LayoutCollision — One detected forbidden/warned overlap between two regions.
+- LayoutCollisionPolicy (type): type LayoutCollisionPolicy = "forbid" | "allow" | "warn" — How a region participates in collision reporting.
+- LayoutModeInput (interface): interface LayoutModeInput — Inputs to `resolveLayoutMode`.
+- LayoutRect (interface): interface LayoutRect — Axis-aligned rectangle in CSS pixels (origin top-left). Structurally compatible with a `DOMRect`'s edge fields.
+- LayoutRegion (interface): interface LayoutRegion — A physical rectangle a UI subsystem occupies, published to the shared registry.
+- LayoutRegionKind (type): type LayoutRegionKind = "hud" | "control" | "system" | "screen" — What kind of UI a registered region belongs to.
+- MobileHudBehavior (type): type MobileHudBehavior = | "persistent" | "compact" | "icon" | "transient" | "hidden" | "sheet" | "modal" — How a HUD element adapts on phones.
+- ZERO_INSETS (const): const ZERO_INSETS: Insets — All-zero insets.
+- computeGameplayRect (function): function computeGameplayRect(viewport: LayoutRect, safeArea: Insets, reserved: readonly LayoutRect[]): LayoutRect — The usable gameplay rectangle after reserving physical zones for touch controls and system UI. Starts from the safe-area-inset viewport and carves each reserved zone from whichever edge it hugs.
+- detectLayoutCollisions (function): function detectLayoutCollisions(regions: readonly LayoutRegion[], options?: DetectCollisionsOptions): LayoutCollision[] — Every forbidden or warned rectangle intersection across the registered regions. A pair is skipped when either side's policy is `allow`, when either opts into the other via `allowOverlapWith`, when they share a `collisionGroup`, or when the overlap is below `minArea`.
+- formatLayoutCollisions (function): function formatLayoutCollisions(collisions: readonly LayoutCollision[]): string — Human-readable diagnostic block for a set of collisions (empty string when there are none).
+- intersects (function): function intersects(a: LayoutRect, b: LayoutRect): boolean — Do the two rectangles share any interior area? Touching edges do not count.
+- isMobileMode (function): function isMobileMode(mode: GameLayoutMode): boolean — Whether a mode is one of the phone modes.
+- orientationOf (function): function orientationOf(width: number, height: number): LayoutOrientation — Portrait when taller than wide, else landscape.
+- overlapArea (function): function overlapArea(a: LayoutRect, b: LayoutRect): number — Overlapping area in px²; 0 when the rectangles don't intersect.
+- rectArea (function): function rectArea(rect: LayoutRect): number — Area of a rect in px².
+- rectHeight (function): function rectHeight(rect: LayoutRect): number — Height of a rect (clamped to ≥0).
+- rectWidth (function): function rectWidth(rect: LayoutRect): number — Width of a rect (clamped to ≥0).
+- resolveLayoutMode (function): function resolveLayoutMode(input: LayoutModeInput): GameLayoutMode — Resolve the explicit composition mode. A mobile layout is not a scaled desktop layout: a coarse-pointer device on a game that supports mobile is always a `mobile-*` mode, split by live orientation; everything else is a desktop mode split by width.
+
 ### @jgengine/core/ui/hudLayout
 
 - HUD_ANCHOR_FRACTIONS (const): const HUD_ANCHOR_FRACTIONS: Record<HudAnchor, { fx: number; fy: number }>
@@ -2815,6 +3133,27 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - rectOverflow (function): function rectOverflow(rect: HudRect, viewport: HudSize, tolerance = 1.5): Omit<HudOverflow, "id"> | null — Non-null when any edge of `rect` falls outside `viewport` by more than `tolerance` px; each field is the overflow distance past that edge (0 when inside).
 - resolveHudFit (function): function resolveHudFit(config: HudViewportConfig | undefined, mobile: boolean): Required<HudFitConfig>
 
+### @jgengine/core/ui/orientation
+
+- GameOrientation (type): type GameOrientation = "landscape" | "portrait" | GameOrientationConfig — The `orientation` field of a game definition. Legacy shorthand `"landscape"` / `"portrait"` stays advisory (a dismissible rotate hint, never a gate). The object form `{ mobile: "landscape-required" }` is the strict contract that blocks gameplay behind the rotate screen until the device is turned.
+- GameOrientationConfig (interface): interface GameOrientationConfig — Object form of the `orientation` field: the strict per-platform contract.
+- LayoutOrientation (type): type LayoutOrientation = "portrait" | "landscape" — A concrete device orientation.
+- MobileOrientationRule (type): type MobileOrientationRule = | "any" | "portrait" | "landscape" | "portrait-required" | "landscape-required" | "unsupported" — The game-level orientation contract. A game declares how it supports phone orientations; the shell resolves that against the live orientation to decide whether to show a dismissible rotate hint (advisory) or a full-screen gate that blocks gameplay until the device is turned (required).
+- OrientationRequirement (interface): interface OrientationRequirement — The resolved orientation contract for a platform: whether it's supported, gated, or merely preferred.
+- orientationGateActive (function): function orientationGateActive(requirement: OrientationRequirement, liveOrientation: LayoutOrientation): boolean — The rotate gate blocks gameplay: a hard requirement (or `unsupported`) the live orientation doesn't satisfy.
+- orientationHintActive (function): function orientationHintActive(requirement: OrientationRequirement, liveOrientation: LayoutOrientation): boolean — An advisory rotate hint applies: a preference (not a hard gate) the live orientation doesn't satisfy.
+- resolveMobileOrientationRule (function): function resolveMobileOrientationRule(orientation: GameOrientation | undefined): MobileOrientationRule — Normalize the `orientation` field (legacy string or object) to a single mobile rule.
+- resolveOrientationRequirement (function): function resolveOrientationRequirement(orientation: GameOrientation | undefined, platform: "mobile" | "desktop"): OrientationRequirement — Resolve the game's orientation declaration into a concrete requirement for a platform. Desktop is always unconstrained.
+
+### @jgengine/core/ui/swingTimer
+
+- SWING_EDGE_EPSILON (const): const SWING_EDGE_EPSILON: 0.0001 — Threshold above which a timer jump is treated as a fresh swing (period reset).
+- SwingLabelKind (type): type SwingLabelKind = "ready" | "seconds" — Whether the bar shows a "ready" label or the seconds-remaining countdown.
+- SwingPlayerInput (interface): interface SwingPlayerInput — The local player's auto-attack state for one frame. `swingTimer` counts DOWN in seconds to 0 (= a swing lands).
+- SwingTargetInput (interface): interface SwingTargetInput — The current target, or the fields the bar needs from it.
+- SwingTimerState (interface): interface SwingTimerState — One frame of swing-bar state plus the cursor (`nextPeriod`/`nextTimer`) the caller carries back into the next call.
+- swingTimerState (function): function swingTimerState(player: SwingPlayerInput, target: SwingTargetInput | null, prevPeriod: number, prevTimer: number): SwingTimerState — Pure swing-timer bar state — no hidden state, no clock, no DOM. The caller threads `prevPeriod`/`prevTimer` back each frame. The period is recovered on the reset edge (when `swingTimer` jumps up = a new swing began) as `max(swingTimer, weapon.speed)`, so the fill is correct even without knowing the weapon's exact cadence. Hidden unless auto-attacking a live, non-object target.
+
 ### @jgengine/core/visibility/assetStreaming
 
 - AssetLoadResult (interface): interface AssetLoadResult
@@ -3020,6 +3359,7 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - EnvironmentCounts (interface): interface EnvironmentCounts
 - EnvironmentSummary (interface): interface EnvironmentSummary
 - IslandSummary (interface): interface IslandSummary extends TerrainSummary
+- RoadSummary (interface): interface RoadSummary — One road descriptor's resolved footprint: vertex count, width, and total centerline length.
 - StructureSummary (interface): interface StructureSummary
 - TerrainHeightStats (interface): interface TerrainHeightStats
 - TerrainSummary (interface): interface TerrainSummary
@@ -3031,6 +3371,7 @@ Imports use deep paths: `@jgengine/core/<path>`.
 
 ### @jgengine/core/world/features
 
+- BiomeBand (interface): interface BiomeBand — A z-ordered ground palette zone — the linear-boundary counterpart to the radial `materialRegions`. Adjacent bands cross-fade into each other across a `fade`-wide window centered on the midpoint z between their centers, so a multi-biome world (vale → marsh → peaks along z) blends its ground color instead of hard-switching. Order the list by ascending `z`.
 - BiomesWorldConfig (interface): interface BiomesWorldConfig extends WorldGridConfig
 - BuildingEnvironmentConfig (interface): interface BuildingEnvironmentConfig
 - BuildingEnvironmentDescriptor (type): type BuildingEnvironmentDescriptor = { kind: "building" } & Required< Pick<BuildingEnvironmentConfig, "count" | "footprint" | "stories" | "storyHeight" | "spacing" | "style"> > & Pick<BuildingEnvironmentConfig, "seed" | "position" | "palette">
@@ -3049,44 +3390,52 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - PlotsWorldConfig (interface): interface PlotsWorldConfig extends WorldGridConfig
 - RainEnvironmentConfig (interface): interface RainEnvironmentConfig
 - RainEnvironmentDescriptor (type): type RainEnvironmentDescriptor = { kind: "rain" } & Required< Pick<RainEnvironmentConfig, "area" | "density" | "speed" | "dropLength" | "wind" | "color"> >
+- RoadEnvironmentConfig (interface): interface RoadEnvironmentConfig — Config for {@link road}: a flat asphalt ribbon draped over the terrain along a centerline.
+- RoadEnvironmentDescriptor (type): type RoadEnvironmentDescriptor = { kind: "road" } & Required< Pick<RoadEnvironmentConfig, "path" | "width" | "color" | "markings" | "markingColor" | "elevation"> > & { /** Resolved sidewalk band, or `false` when the road has none. */ sidewalk: { width: number; color: string } | false; } — Resolved road descriptor produced by {@link road} and rendered by the shell environment scene.
 - SkyEnvironmentConfig (interface): interface SkyEnvironmentConfig
 - SkyEnvironmentDescriptor (type): type SkyEnvironmentDescriptor = { kind: "sky" } & Required< Pick<SkyEnvironmentConfig, "preset" | "timeOfDay"> > & Omit<SkyEnvironmentConfig, "preset" | "timeOfDay">
 - SnowEnvironmentConfig (interface): interface SnowEnvironmentConfig
 - SnowEnvironmentDescriptor (type): type SnowEnvironmentDescriptor = { kind: "snow" } & Required< Pick<SnowEnvironmentConfig, "area" | "density" | "speed" | "flakeSize" | "drift" | "wind" | "color"> >
 - StructureEnvironmentDescriptor (type): type StructureEnvironmentDescriptor = BuildingEnvironmentDescriptor
+- TerrainCircleRegion (interface): interface TerrainCircleRegion extends TerrainRegionStyle — A circular palette zone painted over the base terrain palette — snow caps, ash wastes, spawn circles.
 - TerrainColors (interface): interface TerrainColors
+- TerrainDetailConfig (interface): interface TerrainDetailConfig — Procedural detail-surface layer for terrain: a noise-driven shader that keeps the biome-tinted base ground (from `colors`/`biomeBands`) and blends distinct rock, sand, and snow over it by slope, height, and waterline — turning a flat vertex-colour surface into varied, textured-reading ground with no image assets.
 - TerrainEnvironmentConfig (interface): interface TerrainEnvironmentConfig
 - TerrainEnvironmentDescriptor (type): type TerrainEnvironmentDescriptor = { kind: "terrain" } & Required< Pick<TerrainEnvironmentConfig, "bounds" | "height"> > & Omit<TerrainEnvironmentConfig, "bounds" | "height">
 - TerrainFlattenMask (interface): interface TerrainFlattenMask
 - TerrainIslandConfig (interface): interface TerrainIslandConfig extends TerrainEnvironmentConfig — A bounded terrain patch floating at its own altitude — sky islands, arena platforms, split landmasses with void between.
 - TerrainIslandDescriptor (type): type TerrainIslandDescriptor = Omit<TerrainEnvironmentDescriptor, "kind"> & { kind: "island"; origin: EnvironmentVec2; }
 - TerrainMaterial (type): type TerrainMaterial = "grass" | "sand" | "snow" | "rock" | "ash" | "highland" | "slate"
-- TerrainMaterialRegion (interface): interface TerrainMaterialRegion — A circular palette zone painted over the base terrain palette — snow caps, ash wastes, sand shores on one heightfield.
+- TerrainMaterialRegion (type): type TerrainMaterialRegion = TerrainCircleRegion | TerrainPolylineRegion | TerrainRectRegion — A palette zone painted over the base terrain palette. Circle (the default when no `shape` is given), `polyline` ribbons for roads/rivers, and rotatable `rect` districts all paint fully inside their core and blend back across `falloff`; later regions in the list win overlaps.
+- TerrainPolylineRegion (interface): interface TerrainPolylineRegion extends TerrainRegionStyle — A ribbon palette zone following a centerline — roads and rivers, instead of chaining overlapping circles.
+- TerrainRectRegion (interface): interface TerrainRectRegion extends TerrainRegionStyle — A rectangular palette zone, optionally rotated about the world y axis — plazas, fields, districts.
+- TerrainRegionStyle (interface): interface TerrainRegionStyle — Palette and blend fields shared by every `TerrainMaterialRegion` shape.
 - TilemapWorldConfig (interface): interface TilemapWorldConfig extends WorldGridConfig
 - VegetationEnvironmentDescriptor (type): type VegetationEnvironmentDescriptor = GrassEnvironmentDescriptor
 - VoxelWorldConfig (interface): interface VoxelWorldConfig extends WorldGridConfig
 - WaterEnvironmentDescriptor (type): type WaterEnvironmentDescriptor = OceanEnvironmentDescriptor
 - WeatherEnvironmentDescriptor (type): type WeatherEnvironmentDescriptor = RainEnvironmentDescriptor | SnowEnvironmentDescriptor
 - WorldBounds (interface): interface WorldBounds
-- WorldFeature (type): type WorldFeature = | ({ kind: "biomes" } & BiomesWorldConfig) | ({ kind: "voxel" } & VoxelWorldConfig) | ({ kind: "plots" } & PlotsWorldConfig) | ({ kind: "tilemap" } & TilemapWorldConfig) | EnvironmentWorldFeature | { kind: "flat" }
+- WorldFeature (type): type WorldFeature = | ({ kind: "biomes" } & BiomesWorldConfig) | ({ kind: "voxel" } & VoxelWorldConfig) | ({ kind: "plots" } & PlotsWorldConfig) | ({ kind: "tilemap" } & TilemapWorldConfig) | EnvironmentWorldFeature | { kind: "flat" } — A declared world shape — biomes, voxel grid, plots, tilemap, environment, or flat — passed to `defineGame`.
 - WorldGridCell (interface): interface WorldGridCell
 - WorldGridConfig (interface): interface WorldGridConfig — Shared by `biomes()`/`voxel()`/`plots()`/`tilemap()` so the shell can render their declared content as instanced boxes without a hand-written renderer.
-- biomes (function): function biomes(config: BiomesWorldConfig): WorldFeature
-- building (function): function building(config: BuildingEnvironmentConfig = {}): BuildingEnvironmentDescriptor
-- environment (function): function environment(config: EnvironmentWorldConfig = {}): EnvironmentWorldFeature
-- flat (function): function flat(): WorldFeature
-- grass (function): function grass(config: GrassEnvironmentConfig = {}): GrassEnvironmentDescriptor
+- biomes (function): function biomes(config: BiomesWorldConfig): WorldFeature — Declares a biome-painted world — the whole-world alternative to a single `environment()` terrain.
+- building (function): function building(config: BuildingEnvironmentConfig = {}): BuildingEnvironmentDescriptor — Declares a cluster of procedurally-massed buildings for `environment()` — count, footprint, stories, style.
+- environment (function): function environment(config: EnvironmentWorldConfig = {}): EnvironmentWorldFeature — Composes an `environment()` world feature from terrain, sky, weather, vegetation, water, structures, roads, and pads.
+- flat (function): function flat(): WorldFeature — Declares an empty flat world — the minimal `WorldFeature` for games with no terrain of their own.
+- grass (function): function grass(config: GrassEnvironmentConfig = {}): GrassEnvironmentDescriptor — Declares a grass vegetation patch for `environment()` — area, blade sizing, density, and colors.
 - island (function): function island(config: TerrainIslandConfig): TerrainIslandDescriptor
-- ocean (function): function ocean(config: OceanEnvironmentConfig = {}): OceanEnvironmentDescriptor
+- ocean (function): function ocean(config: OceanEnvironmentConfig = {}): OceanEnvironmentDescriptor — Declares an ocean water body for `environment()` — bounds, level, and wave tuning.
 - pad (function): function pad(config: PadEnvironmentConfig): PadEnvironmentDescriptor
 - padFlattenMasks (function): function padFlattenMasks(pads: readonly PadEnvironmentDescriptor[]): readonly TerrainFlattenMask[] — Derives implicit `TerrainFlattenMask`s carving each pad's footprint into the terrain beneath it. Elevated pads (absolute `elevation`) float free and carve nothing.
-- plots (function): function plots(config: PlotsWorldConfig = {}): WorldFeature
-- rain (function): function rain(config: RainEnvironmentConfig = {}): RainEnvironmentDescriptor
+- plots (function): function plots(config: PlotsWorldConfig = {}): WorldFeature — Declares a subdivided-plots world — farming, base-building, and other parcel-based layouts.
+- rain (function): function rain(config: RainEnvironmentConfig = {}): RainEnvironmentDescriptor — Declares a rainfall weather effect for `environment()` — area, density, speed, and wind.
+- road (function): function road(config: RoadEnvironmentConfig): RoadEnvironmentDescriptor — Declare a road ribbon for an `environment()` world; the shell drapes and renders it over the terrain.
 - sky (function): function sky(config: SkyEnvironmentConfig = {}): SkyEnvironmentDescriptor
-- snow (function): function snow(config: SnowEnvironmentConfig = {}): SnowEnvironmentDescriptor
-- terrain (function): function terrain(config: TerrainEnvironmentConfig = {}): TerrainEnvironmentDescriptor
-- tilemap (function): function tilemap(config: TilemapWorldConfig): WorldFeature
-- voxel (function): function voxel(config: VoxelWorldConfig): WorldFeature
+- snow (function): function snow(config: SnowEnvironmentConfig = {}): SnowEnvironmentDescriptor — Declares a snowfall weather effect for `environment()` — area, density, drift, and wind.
+- terrain (function): function terrain(config: TerrainEnvironmentConfig = {}): TerrainEnvironmentDescriptor — Declares a heightfield terrain patch for `environment()` — bounds, noise, materials, and flatten masks.
+- tilemap (function): function tilemap(config: TilemapWorldConfig): WorldFeature — Declares a 2D tilemap world from a map string.
+- voxel (function): function voxel(config: VoxelWorldConfig): WorldFeature — Declares a voxel-grid world for block-based games.
 
 ### @jgengine/core/world/fog
 
@@ -3241,6 +3590,18 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - createRegionField (function): function createRegionField<T = unknown>(config: RegionFieldConfig<T>): RegionField<T>
 - isRegionField (function): function isRegionField(field: TerrainField): field is RegionField
 
+### @jgengine/core/world/roads
+
+- RoadPoint (type): type RoadPoint = readonly [number, number] — A road centerline vertex in world XZ.
+- RoadRibbon (interface): interface RoadRibbon — Renderer-ready triangle ribbon: flat position triples plus triangle indices.
+- RoadRibbonOptions (interface): interface RoadRibbonOptions — Options for {@link buildRoadRibbon}.
+- RoadSample (interface): interface RoadSample — Result of {@link nearestOnPath}: closest point on the centerline plus distance and tangent.
+- buildRoadRibbon (function): function buildRoadRibbon(path: readonly RoadPoint[], width: number, sampleHeight: (x: number, z: number) => number, options: RoadRibbonOptions = {}): RoadRibbon — Triangulate a road centerline into a ground-draped ribbon mesh: the polyline is subdivided, each vertex is offset half a `width` along the local perpendicular, and every vertex sits at `sampleHeight(x, z) + elevation`. Pure geometry — the shell (or any renderer) turns the result into a mesh, and tests can assert on it directly.
+- dashSegments (function): function dashSegments(path: readonly RoadPoint[], dashLength = 3, gapLength = 3): readonly (readonly RoadPoint[])[] — Split a centerline into dash sub-polylines for lane markings: `dashLength` of painted line, `gapLength` of asphalt, repeated along the path's arc length. Feed each returned sub-path back through {@link buildRoadRibbon} with a thin width to mesh the dashes.
+- isOnRoad (function): function isOnRoad(path: readonly RoadPoint[], width: number, x: number, z: number): boolean — True when the query point lies within half the road `width` of the centerline.
+- nearestOnPath (function): function nearestOnPath(path: readonly RoadPoint[], x: number, z: number): RoadSample | null — Closest-point query against a road centerline — the seam traffic AI, spawn placement, and "am I on the road" checks share. Returns null for a degenerate path.
+- pathLength (function): function pathLength(path: readonly RoadPoint[]): number — Total arc length of a centerline in world units.
+
 ### @jgengine/core/world/scatter
 
 - ScatterArea (interface): interface ScatterArea
@@ -3256,6 +3617,21 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - pickWeighted (function): function pickWeighted<T>(entries: readonly { value: T; weight: number }[], roll: number): T | null — Weighted pick from opaque entries; `roll` in [0, 1). Returns null when empty.
 - scatterItems (function): function scatterItems<T>(field: RegionField<T>, area: Aabb, layersFor: (sample: RegionSample<T>) => readonly ScatterLayer[], options: { cell?: number; max?: number; saltKey?: number } = {}): ScatterInstance[] — Deterministically place opaque items across `area`, grounded on a region field. For each grid cell it asks `layersFor` which items may appear in that region and rolls one against their densities. The engine never interprets `item` — a game maps it to a mesh or entity. Content scatter (region-driven density) as opposed to `scatter` in `./scatter`, which is renderer-free geometric point distribution.
 
+### @jgengine/core/world/streets
+
+- FurnitureSpot (interface): interface FurnitureSpot — A placement anchor on the curb line: position, outward-facing heading, and which side it sits on.
+- FurnitureSpotOptions (interface): interface FurnitureSpotOptions — Options for {@link furnitureSpots}.
+- ParkingSpot (interface): interface ParkingSpot — A curbside parking anchor: position at the road edge and a heading parallel to the street.
+- ParkingSpotOptions (interface): interface ParkingSpotOptions — Options for {@link parkingSpots}.
+- StreetLane (interface): interface StreetLane — A directed lane derived from a road: an offset centerline plus its direction of travel.
+- furnitureSpots (function): function furnitureSpots(road: RoadEnvironmentDescriptor, options: FurnitureSpotOptions = {}): readonly FurnitureSpot[] — Evenly spaced street-furniture anchors along a road's curb lines — streetlights, palms, signs, hydrants, benches. Each spot sits just outside the asphalt (plus `outset`), faces away from the street, and alternates sides by default so lights stagger like a real avenue. This is the answer to "where do I put it": furniture is an asset of the street, never a hand-typed coordinate.
+- laneCenters (function): function laneCenters(road: RoadEnvironmentDescriptor): readonly [StreetLane, StreetLane] — Two right-hand-traffic lane centerlines for a road — each offset a quarter of the drivable width from the center and ordered in its direction of travel. Feed a lane's `path` straight into `nav/pathFollow` for traffic AI, or use its endpoints as directed car spawn points.
+- offsetPath (function): function offsetPath(path: readonly RoadPoint[], offset: number): readonly RoadPoint[] — Offset a centerline sideways by a signed distance along its local perpendicular — the building block for lanes, curb lines, and sidewalk paths. Positive offsets fall on the left of the direction of travel, negative on the right.
+- parkingSpots (function): function parkingSpots(road: RoadEnvironmentDescriptor, options: ParkingSpotOptions = {}): readonly ParkingSpot[] — Curbside parking anchors along a road: hugging the edge of the asphalt, headed parallel to the street in that side's direction of travel. Spawn parked vehicles here instead of eyeballing coordinates in the middle of the carriageway.
+- sidewalkPaths (function): function sidewalkPaths(road: RoadEnvironmentDescriptor): readonly (readonly RoadPoint[])[] — The two sidewalk walking paths of a road — offset polylines running down the middle of each sidewalk band. Pedestrians spawn and route along these instead of the asphalt.
+- sidewalkPoint (function): function sidewalkPoint(road: RoadEnvironmentDescriptor, side: "left" | "right", fraction: number): RoadPoint | null — A deterministic point on one of a road's sidewalks at a normalized position — `side` picks the band, `fraction` (0..1) picks how far along. The canonical pedestrian spawn helper.
+- sidewalkWidthOf (function): function sidewalkWidthOf(road: RoadEnvironmentDescriptor): number — Resolved sidewalk band widths for a road; zero when the road declares no sidewalk.
+
 ### @jgengine/core/world/support
 
 - DebrisOptions (interface): interface DebrisOptions
@@ -3287,29 +3663,33 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - DEFAULT_MAX_WALK_SLOPE (const): const DEFAULT_MAX_WALK_SLOPE: 0.6
 - DEFAULT_TERRAIN_MATERIAL (const): const DEFAULT_TERRAIN_MATERIAL: TerrainMaterial
 - FLAT_FIELD (const): const FLAT_FIELD: TerrainField
-- FractalNoiseConfig (interface): interface FractalNoiseConfig
+- FractalNoiseConfig (interface): interface FractalNoiseConfig — Octave settings for {@link fractalNoise}: frequency, layering, and optional ridged shaping.
 - GroundSnapEntityStore (interface): interface GroundSnapEntityStore
 - GroundSnapTarget (interface): interface GroundSnapTarget
 - HeightMapFieldConfig (interface): interface HeightMapFieldConfig
 - ISLAND_VOID_HEIGHT (const): const ISLAND_VOID_HEIGHT: -256 — Ground height between islands when no base terrain exists — deep enough to read as a fall into the void, finite so physics stays sane.
-- NoiseFieldConfig (interface): interface NoiseFieldConfig
+- NoiseFieldConfig (interface): interface NoiseFieldConfig — Configuration for {@link noiseField}: seed, amplitude, and fractal noise shaping.
+- ResolvedTerrainDetail (type): type ResolvedTerrainDetail = Required<Omit<TerrainDetailConfig, "waterLevel">> & { waterLevel: number } — A {@link TerrainDetailConfig} with every field resolved to a concrete value — the shape the shell's detail material consumes.
 - RollingFieldConfig (interface): interface RollingFieldConfig
 - TERRAIN_MATERIAL_PALETTES (const): const TERRAIN_MATERIAL_PALETTES: Record<TerrainMaterial, TerrainPalette>
-- TerrainField (interface): interface TerrainField
-- TerrainNormal (type): type TerrainNormal = readonly [number, number, number]
+- TerrainField (interface): interface TerrainField — A sampleable ground surface: height and normal at any x/z, with optional bounds and water level.
+- TerrainNormal (type): type TerrainNormal = readonly [number, number, number] — A surface normal vector at a terrain sample point.
 - TerrainPalette (interface): interface TerrainPalette
 - TerrainSlopeSample (interface): interface TerrainSlopeSample
-- arenaField (function): function arenaField(config: ArenaFieldConfig = {}): TerrainField
+- arenaField (function): function arenaField(config: ArenaFieldConfig = {}): TerrainField — Builds a `TerrainField` with a flat spawn plateau, rolling hills, and a basin, for combat arenas.
 - composeIslandFields (function): function composeIslandFields(base: TerrainField | null, islands: readonly TerrainIslandDescriptor[], voidHeight = ISLAND_VOID_HEIGHT): TerrainField — Composes a base terrain and any number of bounded islands into one world field: inside an island's rect the island's own field (sampled in island-local coordinates) wins, elsewhere the base terrain answers, and with no base the gap is `ISLAND_VOID_HEIGHT` void. Later islands win overlaps.
-- createTerrainPaletteSampler (function): function createTerrainPaletteSampler(descriptor: Pick<TerrainEnvironmentConfig, "material" | "colors" | "materialRegions">): (x: number, z: number) => TerrainPalette — Per-position palette sampler over the descriptor's base `material`/`colors` plus its `materialRegions` — the multi-biome coloring seam. Regions paint fully inside `radius` and blend back to the surrounding palette across `falloff`; later regions win overlaps.
-- flatField (function): function flatField(): TerrainField
-- fractalNoise (function): function fractalNoise(x: number, z: number, config: FractalNoiseConfig): number
+- createBiomeBandSampler (function): function createBiomeBandSampler(bands: readonly BiomeBand[], fallback: TerrainPalette): (z: number) => TerrainPalette — Per-z palette sampler over a descriptor's `biomeBands` — ordered zones that cross-fade their ground palette across a `fade`-wide window centered on the midpoint z between adjacent centers. Below the first / above the last band clamps to that band's palette. Returns `fallback` when no bands are declared. Pure math, unit-testable independent of rendering.
+- createTerrainPaletteSampler (function): function createTerrainPaletteSampler(descriptor: Pick<TerrainEnvironmentConfig, "material" | "colors" | "materialRegions" | "biomeBands">): (x: number, z: number) => TerrainPalette — Per-position palette sampler over the descriptor's base `material`/`colors` plus its z-ordered `biomeBands` (painted first) and radial `materialRegions` (painted over) — the multi-biome coloring seam. Regions paint fully inside `radius` and blend back across `falloff`; later regions win overlaps.
+- flatField (function): function flatField(): TerrainField — A flat, zero-height `TerrainField` for arenas with no elevation.
+- fractalNoise (function): function fractalNoise(x: number, z: number, config: FractalNoiseConfig): number — Layers `valueNoise` octaves per `config` into a single normalized noise sample.
 - groundFieldFor (function): function groundFieldFor(world?: WorldFeature): TerrainField
+- hasEnvironmentTerrain (function): function hasEnvironmentTerrain(world: WorldFeature | undefined): boolean — Whether a world declares real terrain (base heightfield or islands) rather than a flat plane — gates terrain-floor sampling in the movement controllers.
 - heightMapField (function): function heightMapField(config: HeightMapFieldConfig): TerrainField
-- noiseField (function): function noiseField(config: NoiseFieldConfig = {}): TerrainField
+- noiseField (function): function noiseField(config: NoiseFieldConfig = {}): TerrainField — Builds a `TerrainField` whose height is fractal noise shaped by `config`.
 - resolveEnvironmentField (function): function resolveEnvironmentField(feature: EnvironmentWorldFeature): TerrainField — The full ground field for an environment world: base `terrain` composed with any `islands`.
-- resolveGroundStep (function): function resolveGroundStep(field: TerrainField, x: number, z: number, stepX: number, stepZ: number, maxSlope = DEFAULT_MAX_WALK_SLOPE): { stepX: number; stepZ: number }
-- resolveTerrainField (function): function resolveTerrainField(descriptor?: TerrainEnvironmentDescriptor): TerrainField
+- resolveGroundStep (function): function resolveGroundStep(field: TerrainField, x: number, z: number, stepX: number, stepZ: number, maxSlope = DEFAULT_MAX_WALK_SLOPE): { stepX: number; stepZ: number } — Zeroes out a movement step's x or z component where it would climb steeper than `maxSlope`.
+- resolveTerrainDetail (function): function resolveTerrainDetail(config: TerrainDetailConfig, terrainWaterLevel = 0): ResolvedTerrainDetail — Fill a `TerrainDetailConfig` with defaults; `waterLevel` falls back to the terrain's own water level.
+- resolveTerrainField (function): function resolveTerrainField(descriptor?: TerrainEnvironmentDescriptor): TerrainField — Resolves a `TerrainEnvironmentDescriptor` into a concrete `TerrainField`, applying flatten masks.
 - resolveTerrainPalette (function): function resolveTerrainPalette(descriptor: Pick<TerrainEnvironmentConfig, "material" | "colors"> = {}): TerrainPalette
 - rollingField (function): function rollingField(config: RollingFieldConfig = {}): TerrainField
 - sampleSlope (function): function sampleSlope(field: TerrainField, x: number, z: number): TerrainSlopeSample — Local slope from the field's normal — the input for gravity-roll, ski acceleration, and slide checks (#284.6).
@@ -3317,8 +3697,8 @@ Imports use deep paths: `@jgengine/core/<path>`.
 - slopeForce (function): function slopeForce(field: TerrainField, x: number, z: number, scale = 9.8): readonly [number, number] — Downhill force/acceleration from the local slope: direction × sin(slope angle) × `scale`. Add it to any integrator's XZ velocity each tick (`scale` ≈ gravity for a free-rolling body).
 - snapEntityToGround (function): function snapEntityToGround(entities: GroundSnapEntityStore, id: string, field: TerrainField, offset = 0): boolean — Ground-snaps an already-spawned entity in place; returns false when `id` is unknown.
 - snapToGround (function): function snapToGround(field: TerrainField, position: readonly [number, number, number], offset = 0): [number, number, number] — Returns `position` with `y` replaced by the field's ground height (plus `offset`) at its `x`/`z`.
-- valueNoise (function): function valueNoise(x: number, z: number, seed: number): number
-- withNormal (function): function withNormal(sampleHeight: (x: number, z: number) => number): TerrainField["sampleNormal"]
+- valueNoise (function): function valueNoise(x: number, z: number, seed: number): number — Smoothly interpolated 2D value noise in `[-1, 1]` for the given seed.
+- withNormal (function): function withNormal(sampleHeight: (x: number, z: number) => number): TerrainField["sampleNormal"] — Derives a `TerrainField.sampleNormal` from a height sampler via finite-difference gradients.
 
 ### @jgengine/core/world/voxelField
 
@@ -3497,7 +3877,9 @@ Exact import paths and export names — **do not invent paths**; every row below
 | Loadout | `game/loadout` | `LoadoutDef`, `LoadoutItemEntry`, `Loadouts` |
 | Cosmetic loadout | `game/cosmetics` | `createCosmetics`, `Cosmetics`, `CosmeticLoadoutDef` |
 | Quest | `game/quest` | `QuestDef`, `QuestRewards`, `QuestObjective`, `QuestJournal` |
-| World features | `world/features` | `WorldFeature`, `biomes`, `voxel`, `plots`, `tilemap`, `flat`, `environment`, `terrain`, `rain`, `snow`, `grass`, `ocean`, `building` |
+| World features | `world/features` | `WorldFeature`, `biomes`, `voxel`, `plots`, `tilemap`, `flat`, `environment`, `terrain`, `rain`, `snow`, `grass`, `ocean`, `building`, `road` |
+| Street layout | `world/streets` | `laneCenters`, `sidewalkPaths`, `furnitureSpots`, `parkingSpots`, `sidewalkPoint`, `offsetPath`, `sidewalkWidthOf`, `StreetLane`, `FurnitureSpot`, `ParkingSpot` — where things belong on a `road()`: lanes for traffic, sidewalks for peds, curb anchors for furniture |
+| Road ribbons | `world/roads` | `buildRoadRibbon`, `dashSegments`, `nearestOnPath`, `isOnRoad`, `pathLength`, `RoadRibbon`, `RoadSample`, `RoadPoint` — geometry + queries behind the `road()` environment feature |
 | Voxel field | `world/voxelField` | `createVoxelField`, `VoxelField`, `VoxelCell`, `VoxelHit`, `VoxelBounds`, `VoxelFieldSummary`, `VoxelFace`, `VOXEL_FACES`, `VOXEL_FACE_NORMALS` — a chunked block lattice, distinct from the `voxel()` `WorldFeature` descriptor |
 | Terrain field | `world/terrain` | `TerrainField`, `noiseField`, `resolveTerrainField`, `rollingField`, `fractalNoise`, `valueNoise`, `withNormal`, `arenaField`, `flatField`, `resolveGroundStep`, `snapToGround`, `snapEntityToGround`, `resolveTerrainPalette`, `TERRAIN_MATERIAL_PALETTES` |
 | Seeded RNG | `random/rng` | `seededRng`, `seededStreams` |
@@ -3789,7 +4171,7 @@ A voxel block is an object. A rack is an object with a slot inventory. A GPU is
 
 ## Game repo layout
 
-Every game is one shape, enforced by `check-game-shape` (part of `check-types`): the top of `src/` holds only the skeleton, and every game-specific module, UI component, and test lives under `src/game/`. Dense files — one `catalog.ts` per domain, never one file per entry.
+Every game is one shape, enforced by `check-game-shape` (part of `check-types`): the top of `src/` holds only the skeleton, and every game-specific module, UI component, and test lives under `src/game/`. In this repo the gate also requires a root `package.json` script `"games:<id>": "bun run --cwd Games/<id> dev"` for every `Games/*` directory — add it with the scaffold, or the very first `check-types` fails before the compiler even runs. Dense files — one `catalog.ts` per domain, never one file per entry.
 
 ```
 src/
@@ -3820,6 +4202,8 @@ src/
 
 **Smart defaults** — omit any of these and the call still resolves: `multiplayer` → `offline()`; `assets` → an empty asset catalog; `loop` hooks (`onInit`/`onNewPlayer`/`onTick`) → no-ops; `content` → `{}`; `GameUI` → an empty component; `camera` → third-person orbit; `feed` → 20-entry ring buffers per action; a `world` of kind `environment()` auto-renders as the backdrop with no `environment` component supplied — a non-`environment()` world (`flat()`, `voxel()`, …) still needs the game to hand it one.
 
+**Opt-in `ctx.game.*` subsystems (`features`)** — core is genre-agnostic: the always-on base is `commands` / `events` / `store` / `feed` (plus `audio`), and genre subsystems are opt-in via `defineGame({ features: { roster, cards, turn, race, leaderboard, social, chat } })`. Omit one and `ctx.game.<name>` is `undefined` — a puzzle game isn't handed a card pile, race state, or party/chat it never asked for. Declare only what the game uses (`chat` implies `social`). (The content cluster — economy/quest/loot/trade — joins this manifest in a later slim-core phase.)
+
 ```ts
 // game.config.ts — imports only, nothing inline
 import { defineGame } from "@jgengine/shell/defineGame";
@@ -3881,7 +4265,7 @@ export const physics: PhysicsConfig = { gravity: -32 };
 
 - `PhysicsConfig.gravity`/`jumpVelocity` tune the shell's built-in walk controller's fall/jump feel (defaults ~`-24`/`7.1`) — the only two levers on gravity and jump height; everything else about movement (speed, poses) stays catalog `movement` fields.
 - Input bindings are string arrays (hold semantics) or `{ hold, toggle, repeatMs? }` for the same verb. `repeatMs` turns a held action into an auto-repeat fire (build-mode place-on-drag, rapid-fire without a separate `wasPressed`/interval combo in game code) — the shell refires the command every `repeatMs` while the binding stays down, on top of its normal press-edge fire.
-- **Keybind → command convention.** The shell fires a command for any bound action that isn't reserved: pressing an action runs a command of the **same name** if one is defined, else a `ui.<action>` fallback (so `openBackpack` → `ui.openBackpack`). Just declare the binding and a matching command — no per-game `keydown` listener. Reserved actions the shell consumes natively and never routes to a command: `moveForward/moveBack/moveLeft/moveRight`, `turnLeft/turnRight`, `sprint`, `jump`, `tabTarget`, `clearTarget`, `useAbility`, `interact`, and any `hotbarSlotN`/`slotN`. `tabTarget`/`clearTarget` run `target.cycle`/`target.clear` (native `cycleTarget`/`setTarget` fallback).
+- **Keybind → command convention.** The shell fires a command for any bound action that isn't reserved: pressing an action runs a command of the **same name** if one is defined, else a `ui.<action>` fallback (so `openBackpack` → `ui.openBackpack`). Just declare the binding and a matching command — no per-game `keydown` listener. Reserved actions the shell consumes natively and never routes to a command: `moveForward/moveBack/moveLeft/moveRight`, `turnLeft/turnRight`, `sprint`, `jump`, `tabTarget`, `clearTarget`, `useAbility`, `interact`, and any `hotbarSlotN`/`slotN`. `tabTarget`/`clearTarget` run `target.cycle`/`target.clear` (native `cycleTarget`/`setTarget` fallback). Because `hotbarSlotN` never reaches a command, a game that drives selection from game code binds its own `selectSlot1..N` actions, defines matching commands that write a store key, and reads it back through `hotbarSelection: () => ...` on `defineGame` (see `loot-shooter`).
 - **`interact`** is special: pressing it resolves the active proximity prompt from the `prompts` field of `defineGame({...})` and runs that prompt's `invoke` command. A prompt with `invoke: null` is display-only and does nothing on the key.
 - UI keybind badges derive from `keybinds` via `actionLabel(keybinds, "openBackpack")` — `bindingLabel` maps codes to short labels (`Digit1`→`1`, `KeyB`→`B`, `mouse0`→`LMB`, `Escape`→`Esc`). Never hardcode label strings; they drift the moment a binding changes.
 - `server.mode` is a string your loop/commands interpret — the engine ships no gamemode presets.
@@ -3966,7 +4350,7 @@ Catalog-first, no per-game audio glue. The `audio` field of `defineGame({...})`
 The shell ships a **rig library**; a game picks and tunes one through `camera` config, never by writing camera positions from `onTick`. Select with `camera.rig` (or the `perspective: "third" | "first"` shorthand) — or by config block alone (#207.8): supplying `camera.<rig>` selects that rig with no redundant `rig` field, checked in the table's order; an explicit `rig` wins when several blocks are present:
 | `rig` | For | Key config (`camera.<rig>`) |
 |-------|-----|------------------------------|
-| `orbit` (default) | Third-person chase | `initialDistance`, `targetHeight`, `min/maxPolarAngle`, drag/zoom |
+| `orbit` (default) | Third-person chase | Top-level fields on `camera` itself — `initialDistance`, `minDistance`/`maxDistance`, `targetHeight`, `min/maxPolarAngle`, drag/zoom. There is **no `camera.orbit` block**; orbit is the one rig tuned at the top level |
 | `first` | FPS mouse-look | `firstPerson: { eyeHeight, sensitivity, maxPitch, reticle, viewmodel }` |
 | `topDown` | ARPG iso / top-down (Diablo IV, Hades II) | `topDown: { height, pitch, yaw, followSmoothing, zoom }` — decoupled follow; `pitch` is camera elevation (PI/2 = straight down, near 0 = grazing and boom-distance blows up past `frustum.far`) |
 | `rts` | Free-pan / edge-scroll (The Sims, Manor Lords) | `rts: { panSpeed, edgeScroll, rotateSpeed, bounds, start, pan }` — `pan: false` turns it into a static backdrop camera: no WASD/arrow pan, no edge-scroll, no Q/E rotate, no wheel zoom, still re-centers on `followEntityId` if one resolves |
@@ -4025,7 +4409,7 @@ ctx.time            advance, now, calendar, snapshot; pause, play, toggle,
 ctx.subscribe / ctx.version    change signal — UI layers bind via useSyncExternalStore
 ```
 
-`content.itemById(id)` supplies `{ use?, weapon?, trade? }`; `content.entityById(id)` supplies `{ stats?, receive?, onDeath?, movement?, role? }`; `content.objectById(id)` supplies `GameContextObjectEntry` `{ proximityPrompt?, breakable?, slotInventory? }`. Build all three from your catalogs in `content.ts`. A placed object resolves its catalog entry via `ctx.scene.object.catalog(instanceId)`; `ctx.scene.object.at(x, y, z, tolerance?)` finds placed objects near a point (grid interaction, click resolution beyond the pointer service). `ctx.scene.entity.update(id, patch)` writes a shallow patch onto a spawned entity's mutable fields (e.g. `movement.walkSpeed`) without a full respawn — `scene/movementSpeed`'s `applyStatDrivenSpeed(deps, id, { baseSpeed, multiplierStat?, flatBonusStat? })` is the catalog-driven helper that recomputes and writes `movement.walkSpeed` from a stat-modifier pair each time a buff changes.
+`content.itemById(id)` supplies `{ use?, weapon?, trade? }` — exact shapes: `use` is the handler **name string** (not an object), `weapon` is a flat `Record<string, number | Record<string, number>>` built from your catalog stats (`damage`, `projectile.{...}`, `explosion.{...}`), and every lookup returns **`null`** (not `undefined`) for an unknown id; `content.entityById(id)` supplies `{ stats?, receive?, onDeath?, movement?, role? }`; `content.objectById(id)` supplies `GameContextObjectEntry` `{ proximityPrompt?, breakable?, slotInventory? }`. Build all three from your catalogs in `content.ts`. Call-shape gotchas that cost typecheck loops: `ctx.item.use.use(input)` takes **one** argument on the ctx surface (the two-arg `use(state, input)` is the raw factory shape); `ctx.scene.entity.moveToward(id, target, { speed, dt, stopDistance? })` — the third argument is an options object, never a bare `dt`; `nav/pathFollow`'s `createPathFollow(config)` returns the initial `PathFollowState` directly and `advancePathFollow(config, state, dt)` returns the **next state** (with `position: [x,y,z]`, `heading`, `done`) — there is no wrapper object, and `Waypoint` is a `[x, y, z]` tuple. A placed object resolves its catalog entry via `ctx.scene.object.catalog(instanceId)`; `ctx.scene.object.at(x, y, z, tolerance?)` finds placed objects near a point (grid interaction, click resolution beyond the pointer service). `ctx.scene.entity.update(id, patch)` writes a shallow patch onto a spawned entity's mutable fields (e.g. `movement.walkSpeed`) without a full respawn — `scene/movementSpeed`'s `applyStatDrivenSpeed(deps, id, { baseSpeed, multiplierStat?, flatBonusStat? })` is the catalog-driven helper that recomputes and writes `movement.walkSpeed` from a stat-modifier pair each time a buff changes.
 
 ### Two tiers: `ctx` runtime vs pure factories
 
@@ -4183,7 +4567,7 @@ description: Gameplay systems: items, quests, economy, crafting, turns, objectiv
 | `snap` | `"grid"` \| `"free"` \| `"wall"` |
 | `solid` | Blocks movement |
 | `breakable` | `false` or `{ baseBreakTime, harvest, drops, dropsWhenUnmet }` |
-| `proximityPrompt` | Float UI + optional command invoke |
+| `proximityPrompt` | Float UI + optional command invoke; `keybind(action, label?)` shows what the interaction does beside the key (`[E] Open Chest`) |
 | `slotInventory` | Attached container `{ slots, accepts }` created at place time (`object:<instanceId>`) |
 
 Break resolution: `duration = baseBreakTime / (tool?.breakSpeed ?? 1)`; drops per `when` (`always` / `harvestMet` / `silkTouch` / `playerKill`); then `inventory.put` + `object.remove`.
@@ -4285,6 +4669,10 @@ Banned in the engine: `weapon.fire`, `consumable.use`, `game.combat.*`, per-weap
 
 A capture item's `item.use` handler composes the primitives instead of forking them: read the wild target's hp via `ctx.scene.entity.stats.get(target, "health")`, roll `rollCapture({ hpFraction, catchPower })`, and on success call `ctx.scene.entity.despawn(target)` + `ctx.game.roster.capture(ownerId, catalogId)` — the wild scene entity is removed and re-parented into the owner's persisted roster; the react `CaptureOdds({ chance })` component shows the live odds meter the UI quality bar requires.
 
+### Local saves — mutable single-player state
+
+`@jgengine/core/game/keyValueStore` — `createKeyValueStore({ key, initial, storage? })` is a single persisted mutable cell (`get` / `set` / `update` / `clear`) for single-player state a `recordBook` can't hold: a credit bank, a settings blob, level progress. `recordBook` is monotonic — it keeps only improved values; reach for the KV store when the value moves both ways. It targets the DOM-free `KeyValueStorage` seam (defaults to `localStorage`, pass a stub in tests or `null` for memory-only); corrupt or unavailable storage degrades to in-memory and never throws into a tick. Author any core-side persistence against `KeyValueStorage`, never the DOM `Storage` type — core has no DOM lib, so copying shell's `fovPreference.ts` shape into core fails the build.
+
 ## Combat — effects, projectiles, death, feel, abilities
 ## Card, board & shaped-inventory primitives
 Pure, renderer-free structures for card, board, and deckbuilder games — they sit **beside** the slot inventory, not in place of it. All are immutable-reducer + thin-controller pairs, mirroring the two-tier ctx/factory model: use the `create*` controller in game code, reach for the exported pure functions (`draw`, `moveCards`, `tickTimeline`, `laneAggregate`, `runPipeline`, `placeShaped`) for unit tests and headless servers.
@@ -4518,6 +4906,8 @@ description: Combat API: effects, projectiles, damage, abilities, loot, weapons.
 
 Combat primitives — effects & projectiles, death handling, melee/defense/telegraph feel, and abilities/resources/auto-target/resistance/run drafts. Full surface: **[reference.md](https://github.com/Noisemaker111/jgengine/blob/main/.claude/skills/jgengine-combat/reference.md)**.
 
+**One-shot rig animations.** A model's `animation.oneShots` (in `entityModels`) maps event names → clip name(s), played once over the locomotion `states` then released. `hit` and `death` auto-fire from the entity's own `combat.hitReaction` / `entity.died` (no wiring); trigger any other (e.g. `attack`) with `ctx.game.playEntityAnimation(instanceId, event)` when the swing lands. A `string[]` binding picks a random variant per trigger; `death` clamps on its final frame. Pairs with `animation.states` — the shell fades the loco state out for the clip and back in when it finishes (death holds the pose). Clip-selection logic is the pure `resolveOneShotClip` in `@jgengine/core/game/modelAnimation`.
+
 ## Loot
 
 ```ts
@@ -4557,7 +4947,7 @@ fireProjectile({ from, via, aim, effect })      // → shotId (pending)
 settleProjectile(shotId)                        // authoritative → { at, hits } | rejection
 ```
 
-`Aim = { origin, direction } | { yaw, pitch, spread? }`. Hitscan settles into per-hit effects; ballistic shots (`weapon.projectile` with `fuseTime`/`settleOn`) settle to a landing point — the handler then calls `effect({ at: settle.at, radius })`. Settling twice rejects. Prediction is never authority.
+`Aim = { origin, direction } | { yaw, pitch, spread? }`. Shot origin resolves via `ShotOriginPolicy` (default `eye`: `aim.origin` when given, else shooter position raised to eye height — 90% of the shooter's own hitbox top when colliders are known, ~1.6m otherwise — so shots trace the sightline and the crosshair is truth; `muzzle`/`camera`/`world` for custom rigs, `legacy` = raw entity position). Default entity hitbox is a body-covering AABB (feet to ~1.8m). Objects with a `visual.scale` get a matching grounded physical body automatically; explicit catalog `colliders`/`halfExtents` override. Hitscan settles into per-hit effects; ballistic shots (`weapon.projectile` with `fuseTime`/`settleOn`) settle to a landing point — the handler then calls `effect({ at: settle.at, radius })`. Settling twice rejects. Prediction is never authority.
 
 Raycasts are **object-aware**: the default raycast checks placed scene objects as well as entities, discriminated by `RaycastHit.kind` (`"entity" | "object"` — an `ObjectRaycastHit` also carries `catalogId`). A crate or wall between shooter and target blocks or absorbs the shot instead of every projectile passing through scenery; supply `ProjectileSystemDeps.objects` (`{ list(), halfExtents?(catalogId) }`, matching `ObjectStore.list()` structurally) to opt in, with a `[0.5, 0.5, 0.5]` half-extent default per object.
 
@@ -4581,6 +4971,8 @@ Layered on top of effects/projectiles/death — none of it replaces them, i
 - **Defensive window** (`combat/defensiveWindow`) — a parry/block/dodge with `{ startupMs, activeMs, recoveryMs, iframes }`. `resolveDefense({ config, elapsedMs, attack })` is the pure overlap of the defender's window against the moment the attacker's `active` frames land → `parry | block | iframe | hit`. `createDefensiveWindow(config)` tracks the open time (`open(now)` / `evaluate(now, attack)` / `isInvulnerable(now)`).
 - **Combo strings** (`combat/comboString`) — `ComboStep`s with `cancelInto` + `cancelPhases` + optional `stance`, over the anim SM. `advanceCombo(...)` (pure) accepts the next attack only inside the current step's cancel window and matching stance; `createComboRunner(combo, anim)` drives the SM.
 - **Meters share one accumulator** (`stats/accumulatorMeter`) — `createAccumulatorMeter({ max, mode: "hold" | "reset", decayPerSecond, decayDelayMs, tiers })`: fill via `add(n)` → `MeterAddResult { fired, overflow, tier, tierChanged }`, `tick(dt)` decays after an idle grace. `combat/breakMeters` builds two on it: `createStaggerMeter` (mode `hold` — fills from hits, `broke()` stays true until `recover()` after a riposte/deathblow) and `createBuildupMeter` (mode `reset` — `add(n)` returns a `BuildupProc { status, durationMs }` at threshold for bleed/frost/rot, then decays). The same base backs G6's ult/streak meters.
+- **Delayed-regen shield** (`combat/regenShield`) — `createRegenShield(config)` is a shield pool that pauses regen for `regenDelayMs` after every hit, then refills at `regenPerSecond`; `damage`/`tick` replace snapshot-comparing a stat to detect "took damage."
+- **DoT field** (`combat/dotField`) — `createDotField()` schedules recurring damage-over-time instances (bleed/poison/burn) keyed by id; `tick` drains due damage per interval. Pairs with `combat/breakMeters`' `BuildupProc` — a fired buildup applies a DoT instead of one-shot damage.
 - **Dash / dodge** (`movement/dash`) — `createDashState({ distance, durationMs, iframes, staminaCost, staminaMax, staminaRegenPerSecond, cooldownMs })`: `tryDash(dir, now)` → burst or `{ reason: "no-stamina" | "cooldown" | "dashing" }`, `isInvulnerable(now)` for the i-frame window, `offset(now)` for the burst displacement, `tick(dt, now)` regens stamina.
 - **Hit reaction** (`combat/hitReaction`) — `resolveHitReaction(config, { attackerPos, targetPos, power })` (pure) → `{ hitstopMs, impulse, shake }`. Wired on `ctx`: `ctx.scene.entity.hitReaction({ from, to, config, power? })` knocks the target back and emits `combat.hitReaction` (the shell reads `shake` for a trauma channel — feeds a G2 camera-shake rig when present, else the shell's own kick).
 - **Telegraph** (`combat/telegraph`) — a `TelegraphShape` (`circle | ring | cone | line`) + `windupMs`. `ctx.scene.entity.telegraph({ from, shape, at, dir?, windupMs, kind?, effect? })` emits `combat.telegraph` for the shell to draw a ground decal that fills over the windup, and — if `effect` is bound — applies that effect to everyone inside the shape (`pointInTelegraph`) at activation. Returns a cancel handle. **Turn-scoped variant**, for tactics/turn-based enemy intents instead of a real-time windup: set `TelegraphConfig.turns` (a count of turns instead of `windupMs`), then read `telegraphTurnProgress(config, startedTurn, currentTurn)` (0..1 fill fraction), `telegraphFiredAtTurn(config, startedTurn, currentTurn)` (has it resolved), and `telegraphTurnsRemaining(config, startedTurn, currentTurn)` — the same "enemy will hit this tile" decal, advanced by `turnLoop.round()`/`active()` instead of a clock.
@@ -4721,6 +5113,18 @@ Shell wiring: `@jgengine/shell/vision/RevealVision` (`RevealHighlights` — dept
 
 Renderer-free world surface — query primitives, environment fields + weather + realm composition, survival meters/moodles, interactive building & terraform, the optional headless physics world, vehicles/mounts/racing, and spawn placement. Full surface: **[reference.md](https://github.com/Noisemaker111/jgengine/blob/main/.claude/skills/jgengine-world/reference.md)**.
 
+## Level design — places, not noise
+
+Procedural terrain is a canvas, never the level. A world with only `terrain()` + spawn clusters reads as an empty sandbox no matter how big its bounds. Every open-world game composes **places** on top of the canvas, and the checklist below is the floor, not the ceiling:
+
+- **Every site is a set-piece.** A camp is a wall ring with a deliberate gate opening facing the approach, cover inside, a tower or banner as its silhouette — never a bare radius of spawns. Compose from placed objects (`ctx.scene.object.place` with stable instance ids) driven by pure data functions (ring/scatter/route generators) so bun tests can assert the composition without rendering.
+- **Roads make the space legible.** Physically connect sites: trace waypoint routes between them and feed the points into the terrain descriptor's `flatten` masks so the route is genuinely walkable, then dress it — markers, wrecks, signposts — every ~60 units so the player can read the path at a glance. A test should walk the route and assert the step height stays small.
+- **One landmark per region.** A water tower, crashed vehicle, gate, or monument visible from the approach gives orientation without a map. Distinct silhouette + distinct color.
+- **Anchor → approach → arena → reward.** Each combat site needs a visible anchor drawing the player in, a readable approach (the road), an arena with cover the AI and player both use, and a visible reward (chest, vendor, quest turn-in) at the back so clearing it feels earned.
+- **People, not just spawns.** Hubs hold named NPCs (talkable entities with prompts), vendors, and light props (lamps, crates, stalls). A hub with only vending-machine objects is a menu, not a town.
+- **Density budget.** Inside a site's flatten radius aim for roughly one placed object per 6–10 units of radius; along roads one prop per ~60 units; open wilderness stays sparse so sites contrast. Frustum/distance culling is automatic — err toward more dressing, not less.
+- **Guided openness, never invisible walls.** Total freedom reads as emptiness: herd the player physically. Raise terrain amplitude so off-road relief is genuinely unclimbable, gate slope in `movement.beforeCommit` (block a step whose ground rises past a climb limit, with per-axis slide so it feels like a wall of rock, not a script), and carve the intended route as the one low path. Then buy the openness back deliberately: side pockets (a den, a cache, a wreck field) hang off the main road on short spur routes, each with its own reward, so exploration branches from the path instead of dissolving it. Test the herding the same way you test the road: assert off-road samples rise above the climb limit while every route and spur stays under it.
+
 ## Turn-based & tactics (renderer-free)
 
 # jgengine domain API — World features
@@ -4738,11 +5142,13 @@ Descriptors from `@jgengine/core/world/features` — config data the runner
 | `plots(config)` | Shared city + instanced interiors |
 | `tilemap({ map })` | 2D/2.5D levels |
 | `flat()` | Plain arena |
-| `environment({ terrain, sky, weather, vegetation, water, structures, pads })` | Composable outdoor scene — terrain + sky/time-of-day + rain/snow + grass + ocean + buildings + ground pads. Each field takes the matching descriptor: `terrain()`, `sky()`, `rain()`/`snow()`, `grass()`, `ocean()`, `building()`, `pad()`. `building()` and `ocean()` take `position: [x, z]` to site a cluster/water body away from the origin (several settlements, an offset lake); building clusters ground-snap to the terrain field per building; each `pad()` (a flat platform/paved patch — `{ center, size: [w,d] | { radius }, height?, color?, rotationY? }`) implicitly flattens the terrain beneath it via a `TerrainFlattenMask`, so a building pad or spawn circle never fights the noise field underneath |
+| `environment({ terrain, sky, weather, vegetation, water, structures, pads })` | Composable outdoor scene — terrain + sky/time-of-day + rain/snow + grass + ocean + buildings + ground pads. Each field takes the matching descriptor: `terrain()`, `sky()`, `rain()`/`snow()`, `grass()`, `ocean()`, `building()`, `pad()`. `building()`, `ocean()`, `rain()`/`snow()`, and `grass()` take `position: [x, z]` to site a cluster/water body/weather band/vegetation patch away from the origin (several settlements, an offset lake, per-biome rain, a distant meadow) — the weather/grass `position` is sugar for `area.position`, so a biome-banded world places each band by zone; building clusters ground-snap to the terrain field per building; each `pad()` (a flat platform/paved patch — `{ center, size: [w,d] | { radius }, height?, color?, rotationY? }`) implicitly flattens the terrain beneath it via a `TerrainFlattenMask`, so a building pad or spawn circle never fights the noise field underneath |
 
 `biomes`/`voxel`/`plots`/`tilemap` share a `WorldGridConfig` (`cells?: WorldGridCell[]`, `cellSize?`, `baseHeight?`, `defaultColor?`) — a `WorldGridCell` is `{ x, z, height?, color? }`, one extruded box per cell. `resolveGridInstances(config)` (`@jgengine/core/world/gridInstances`) is the pure cell→instance math (position, scale, color per cell); the shell renders the result as a single `THREE.InstancedMesh` **automatically whenever `PlayableGame.environment` is unset and `game.world` is one of these four grid kinds** — no manual render wiring for a cell-based world, same auto-render convention as `environment()` worlds.
 
-`terrain()`'s `material` (a named palette — `"grass" | "sand" | "snow" | "rock" | "ash"`, resolved via `resolveTerrainPalette`/`TERRAIN_MATERIAL_PALETTES` in `world/terrain`) sets the default low/high/waterline colors; `colors: { low?, high?, waterline? }` overrides any of them field-by-field, and `segments` tunes the render mesh's subdivision. `flatten: TerrainFlattenMask[]` (`{ center, radius, height?, falloff? }`) carves explicit flat circles into the noise field independent of pads — building foundations, spawn circles, roads — blending back to the noise height over `falloff` (default `radius * 0.5`). `sky({ preset?, timeOfDay?, horizonColor?, zenithColor?, sunIntensity?, ambientIntensity?, fog? })` — `preset: "day" | "dusk" | "night"` (default `"day"`) is the static look; `timeOfDay: true` instead drives sun position, sky colors, and fog from the world clock's `calendar().dayFraction` every frame (`@jgengine/shell`'s `TimeOfDayDaylight` mounts this automatically for an `environment()` world with `sky` set — no per-game render wiring). **Gotcha:** `sunIntensity` / `ambientIntensity` are honored only on the **day** keyframe (`daylightCycle` builds dusk/night/dawn from fixed constants). Raising intensities under `preset: "dusk"` or `"night"` does nothing — use `preset: "day"` plus warm `horizonColor`/`zenithColor` when the first screenshot must be bright and readable (see `jgengine`'s first-shot art recipe).
+`terrain()`'s `material` (a named palette — `"grass" | "sand" | "snow" | "rock" | "ash"`, resolved via `resolveTerrainPalette`/`TERRAIN_MATERIAL_PALETTES` in `world/terrain`) sets the default low/high/waterline colors; `colors: { low?, high?, waterline? }` overrides any of them field-by-field, and `segments` tunes the render mesh's subdivision. `biomeBands: BiomeBand[]` (`{ z, fade?, material?, colors? }`) cross-fades the **ground palette along the world's z axis** — ordered zones (vale → marsh → peaks) that blend across a `fade`-wide window (default 64) centered on each boundary; it's the linear counterpart to the radial `materialRegions` (which paint on top; each region is a `TerrainCircleRegion` (default), `TerrainPolylineRegion` (roads/rivers), or `TerrainRectRegion` (rotatable districts), sharing a `TerrainRegionStyle`). Pure/testable via `createTerrainPaletteSampler`/`createBiomeBandSampler` in `world/terrain`; the shell renders it through the same per-vertex `paletteAt` seam as regions, no extra wiring. (Per-zone **fog/sky** cross-fade isn't wired yet — three.js fog is scene-global — so bands drive ground color today.) `flatten: TerrainFlattenMask[]` (`{ center, radius, height?, falloff? }`) carves explicit flat circles into the noise field independent of pads — building foundations, spawn circles, roads — blending back to the noise height over `falloff` (default `radius * 0.5`). `detail: TerrainDetailConfig` (`{ rockColor?, sandColor?, snowColor?, rockSlopeStart?, snowHeight?, waterLevel?, detailScale?, macroScale?, roughness?, strength? }`) swaps the flat vertex-colour ground for a procedural noise shader (`@jgengine/shell`'s `createTerrainDetailMaterial`, defaults via `resolveTerrainDetail`): it keeps the biome-tinted base and blends noise-broken **rock by slope**, **sand by waterline**, and **snow by height** over it — textured-reading terrain with no image assets, full PBR (lit/shadowed/fogged), composing with the post-processing chain. Omit for the flat look. `sky({ preset?, timeOfDay?, horizonColor?, zenithColor?, sunIntensity?, ambientIntensity?, fog? })` — `preset: "day" | "dusk" | "night"` (default `"day"`) is the static look; `timeOfDay: true` instead drives sun position, sky colors, and fog from the world clock's `calendar().dayFraction` every frame (`@jgengine/shell`'s `TimeOfDayDaylight` mounts this automatically for an `environment()` world with `sky` set — no per-game render wiring). The sky dome renders a bright HDR sun disc + warm glow (aligned to the sun light, so it blooms through a `postProcessing` chain), a mid-sky procedural cloud band, and a horizon haze — no HDRI assets; richer than a flat gradient with zero config. **Gotcha:** `sunIntensity` / `ambientIntensity` are honored only on the **day** keyframe (`daylightCycle` builds dusk/night/dawn from fixed constants). Raising intensities under `preset: "dusk"` or `"night"` does nothing — use `preset: "day"` plus warm `horizonColor`/`zenithColor` when the first screenshot must be bright and readable (see `jgengine`'s first-shot art recipe).
+
+**Flatten-mask composition semantics** (`withFlattenMasks` — easy to fight if guessed): masks apply **sequentially and the last matching mask wins outright**; there is no mask-to-mask blending. Inside `radius` the height becomes that mask's `target` exactly; in the `radius..radius+falloff` annulus it lerps from `target` back to the **raw noise height**, never to another mask's output. `target` defaults to the raw noise height at the mask's own center (`height` overrides). Consequences to know before composing roads or multi-site layouts: (1) a chain of default-height circles stair-steps, because each snaps to its own center's noise — give road masks explicit `height` values ramped between the endpoint site targets; (2) a later mask's falloff annulus punches raw-noise bumps through an earlier flat area — order masks so the surface that must win comes last, keep road `falloff` small (≤ radius), and skip road circles inside an already-flat site radius; (3) raw noise rarely herds — to guarantee canyon walls, emit masks with `height` *above* the surroundings flanking the corridor. A working road-ramp recipe (overlapping circles every ~12 units, height ramped between site targets, ramp clamped flat inside each site radius, wall masks alongside) lives in `Games/borderlands2/src/game/world/level.ts`.
 
 `parentSpace` positions are local to that space — convert at seams only.
 
@@ -4815,7 +5221,7 @@ Turn data-only placement into the build tooling of Valheim/Enshrouded/The Sims/F
 **Structural destruction (`physics/structure`).** `StructureGraph` models a building as nodes (pieces) + load-bearing edges with some nodes `anchor`ed (foundations). `damage(id, n)`/`damageEdge(a,b,n)`/`severEdge(a,b)` wear pieces and connections; when one breaks, the graph recomputes reachability to an anchor and returns a single `CollapseEvent { fell }` — every piece the loss disconnected. `toDebris(world, event)` sinks the fallen pieces into a `PhysicsWorld` as rigid bodies (The Finals, Rainbow Six). It is coarse by design: **replicate the collapse event (the `fell` id list), not each fragment's physics** — game clients re-derive the debris locally. Piece integrity and edge strength default from a `StructureMaterial` table (DATA).
 ### Vehicles, mounts, crash damage & racing
 Five primitives layer a driving/racing game over the physics sim and `world/water`. All are **data-first** (spec the chassis/wheels/grip curve, damage thresholds, and checkpoint layout as catalog data) and pure `@jgengine/core`; renderers live in the game/shell. Each `update(dt, …)` runs **before** the shared `world.step(dt)`.
-- **Analog input — `input/axisInput`.** `AxisInput { throttle, brake, steer, handbrake }` is a continuous channel, **distinct from the digital action bindings**. `new AxisChannel({ bindings, smoothing })` ramps held keys into pedal-like analog values (`sample(dt, isDown)`), or `setAnalog(axis, value)` drives it straight from a gamepad axis. `DRIVE_AXIS_BINDINGS` is a ready WASD/arrow map.
+- **Analog input — `input/axisInput`.** `AxisInput { throttle, brake, steer, handbrake }` is a continuous channel, **distinct from the digital action bindings**. `new AxisChannel({ bindings, smoothing })` ramps held keys into pedal-like analog values (`sample(dt, isDown)`), or `setAnalog(axis, value)` drives it straight from a gamepad axis. `DRIVE_AXIS_BINDINGS` is a ready WASD/arrow map. `sampleAxisBindings` is the instantaneous, unsmoothed read the channel ramps toward each frame — exposed headlessly as `ctx.input.axis(bindings, ranges?)`, bound to **action names** rather than raw key codes (#533.7).
 - **`physics/vehicleBody`.** `createVehicleBody(world, config)` is an arcade car: a chassis box body with per-wheel suspension held by G3's `springJoint` against the sampled `groundHeight`, drive/brake along the heading, and a `GripCurve` (`sampleGripCurve`) that bleeds lateral velocity for cornering — and, under `handbrake`, drift. `update(dt, axisInput)` then `world.step`. Because the chassis is a real body it still collides, which feeds crash damage. Rocket League, Trackmania, Wreckfest.
 - **`physics/buoyancy`.** `createBuoyantBody(world, { body, water, … })` floats a body on a CPU `WaterSurface` (Archimedes per hull point + water drag) so it settles at the waterline and rides the Gerstner waves; pass an `AxisInput` to `update(dt, time, input?)` and it drives as a boat (thrust + yaw + keel). Sea of Thieves, BOTW rafts.
 - **`scene/mount`.** `createMountController()` transfers control to a driven entity: `register({ id, kit, seats })`, `mount(riderId, mountId, seatId?)`, `dismount`. Read `cameraTarget(riderId)` to point the follow camera and `driveTarget(riderId)` to route that rider's `AxisInput` at the mount — the control seat drives, passenger seats ride (multi-seat shared vehicles), and an un-mounted rider drives themselves. `driver(mountId)`/`occupants(mountId)`/`kitOf`. Palworld mounts, V Rising horse, a crewed ship.
@@ -4980,4 +5386,4 @@ import { bootCartridge, cartridgeSmokeTest, tickCartridge } from "@jgengine/core
 cartridgeSmokeTest(config);   // validate + world summary + headless run/spawn/kill/gem smoke
 ```
 
-`bootCartridge`/`tickCartridge` build a headless `GameContext` and drive the loop (auto-choosing drafts) for custom assertions — see `Games/swarm-survivor/src/game/cartridge.test.ts`. The testkit imports `bun:test`; import it from test files only.
+`bootCartridge`/`tickCartridge` build a headless `GameContext` and drive the loop (auto-choosing drafts) for custom assertions — see `@jgengine/core/cartridge/testkit`. The testkit imports `bun:test`; import it from test files only.