@jgengine/editor 0.11.0 → 0.13.0

package/skills/jgengine-editor/api.md

@@ -11,17 +11,28 @@
 - `CreateGridLayerInit` (interface): interface CreateGridLayerInit — Fields accepted when constructing a grid layer; sensible defaults fill the rest.
 - `CsvGridExportOptions` (interface): interface CsvGridExportOptions — Options for exporting a grid layer as CSV.
 - `CsvGridImportOptions` (interface): interface CsvGridImportOptions — Options for importing a CSV grid (one value id per cell).
+- `DecodeWorldManifestResult` (type): type DecodeWorldManifestResult = | { ok: true; manifest: WorldManifest } | { ok: false; errors: EditorDocumentDiagnostic[] } — Result of {@link decodeWorldManifest}: a typed manifest, or every diagnostic collected decoding it.
+- `DirectiveFootprint` (interface): interface DirectiveFootprint — A resolved directive footprint: the XZ bounds to scatter within, plus an optional clip polygon.
+- `DirectiveInstancePatch` (interface): interface DirectiveInstancePatch — A per-instance hand-tweak over a materialized directive, keyed by the minted instance id.
+- `DocumentBakeOptions` (interface): interface DocumentBakeOptions extends MinimapBakeOptions — Options for {@link bakeMinimapFromDocument}.
 - `DocumentLiveEvent` (interface): interface DocumentLiveEvent — Event emitted when the authoritative document changes on a {@link DocumentLiveSync}.
 - `DocumentLiveSync` (interface): interface DocumentLiveSync — Two-way live-sync bus: document patches out, runtime state deltas back.
 - `DocumentPatch` (type): type DocumentPatch = | { type: "snapshot"; revision?: number; baseRevision: number; document: EditorDocument; } | { type: "commands"; revision?: number; baseRevision: number; commands: readonly EditorCommand[]; } — One versioned document mutation on the live-sync stream. `snapshot` replaces the whole document; `commands` replays structural editor commands onto the current document. `baseRevision` must match the receiver's current revision unless `force` is set (document authority from the editor).
+- `ENTITY_CATALOG_ID` (const): const ENTITY_CATALOG_ID: "entities" — Well-known catalog id for authored entity definitions. A `mob`/`boss` marker's `catalogId` references an entry (row) in this catalog, and {@link entityEntryFromCatalog} turns that row into the runtime {@link GameContextEntityEntry} a spawn consumes — so an entity's stats and speed are authored in the editor Data tab, not hardcoded in game TS.
 - `EditorCatalogData` (interface): interface EditorCatalogData — Persisted values for one gameplay data catalog (weapons, waves, economy, …). Schemas are not stored here — they come from the game's `editorCatalogs` export and drive SchemaInspector.
 - `EditorCatalogDefinition` (interface): interface EditorCatalogDefinition — Game-exported catalog definition: a `ParamSchema` plus default entries. Schemas stay in code; entry values merge into `document.catalogs` and are what the editor/RPC edits and saves.
 - `EditorCatalogEntry` (interface): interface EditorCatalogEntry — One row in a gameplay data catalog — id + optional label + a meta bag matching the catalog's `ParamSchema`. Values persist on the scene document; the schema lives in the game export.
 - `EditorCatalogsInput` (type): type EditorCatalogsInput = | readonly EditorCatalogDefinition[] | (() => readonly EditorCatalogDefinition[]) — Accepted shape for a game's `editorCatalogs` export: definitions, or a factory.
 - `EditorCollection` (interface): interface EditorCollection — A named, persisted list of object ids — a selection bookmark (restore, add-to) that can also double as a production group: `locked` blocks `translate`/`setTransform`/`remove`/`removeMany` on its members, `color`/`visible` are UI-only hints for the collections panel.
 - `EditorCommand` (type): type EditorCommand = | { type: "select"; ids: readonly string[] } | { type: "clearSelection" } | { type: "setTransform"; id: string; position?: EditorVec3; rotationY?: number } | { type: "translate"; ids: readonly string[]; delta: EditorVec3 } | { type: "setParent"; ids: readonly string[]; parentId:… — A single editor mutation — select, move, add, remove, undo/redo — dispatched to a session.
+- `EditorDirective` (type): type EditorDirective = EditorScatterDirective | EditorPopulationDirective — A procedural directive on the scene document: scatter props or a mob population.
+- `EditorDirectiveArea` (interface): interface EditorDirectiveArea — XZ world-space bounds, `[minX, minZ]`..`[maxX, maxZ]`, for a directive that names no region.
+- `EditorDirectiveKind` (type): type EditorDirectiveKind = EditorDirective["kind"] — The distinct directive kinds a materializer expands.
+- `EditorDirectiveOverlay` (interface): interface EditorDirectiveOverlay — A sparse overlay over one directive's materialized instances — the "nudge *that one* rock" answer. Hand-edits are keyed by the stable instance id the materializer mints, so they survive re-bakes.
 - `EditorDispatchOptions` (interface): interface EditorDispatchOptions — Per-dispatch options; `coalesce` merges consecutive same-key edits into one undo step.
 - `EditorDocument` (interface): interface EditorDocument — The full authored scene: every marker, volume, path, note, and sculpted terrain for a game.
+- `EditorEnvironment` (interface): interface EditorEnvironment — Scene-document environment/lighting authoring (#1110): sky preset, optional time-of-day drive, horizon/zenith tints, sun/ambient intensity, and fog. Serializable and genre-agnostic — games feed it into `environment({ sky: sky(skyFromDocument(doc)) })` (or leave world.ts sky as a fallback when the field is absent). Absent until the lighting workspace (or a seed layer) writes it, so existing documents load unchanged.
+- `EditorFogConfig` (interface): interface EditorFogConfig — Linear distance fog authored on the scene document — serializable subset of sky/backdrop fog. Absent fields keep engine defaults when the document is applied at runtime.
 - `EditorFragmentContent` (interface): interface EditorFragmentContent — The four placeable-object collections a prefab fragment or clipboard fragment carries.
 - `EditorGridAxes` (type): type EditorGridAxes = "xz" | "xy" — How a grid layer's columns and rows map onto world axes. - `"xz"` (default): columns advance +X, rows advance +Z — a top-down floor plan / board. - `"xy"`: columns advance +X, rows advance +Y — a vertical slice / side-view board.
 - `EditorGridCell` (interface): interface EditorGridCell — One resolved cell of a grid layer — its column, row, and value id.
@@ -31,19 +42,28 @@
 - `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.
+- `EditorMinimapBake` (interface): interface EditorMinimapBake — A baked top-down minimap stored on the scene document (#1036): the PNG the editor rasterized from the authored terrain (a `data:image/png;base64,…` URI) plus the world bounds it spans. Runtime feeds these straight into the `Minimap`/`WorldMap` `background`/`mapBounds` props — no re-raster.
 - `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.
+- `EditorPopulationDirective` (interface): interface EditorPopulationDirective extends EditorDirectiveBase — Populates a region with weighted, capped mob spawns — config for `ai/populationDirector`.
+- `EditorPopulationSpecies` (interface): interface EditorPopulationSpecies — One weighted species in a population directive, with a hard instance cap.
 - `EditorPrefab` (interface): interface EditorPrefab — A serializable, reusable stamp of authored objects — markers/volumes/paths/notes centered on their own centroid so the same prefab inserts consistently anywhere, in this scene or another game's. `insertPrefab` tags every inserted object's `meta.prefabId`/`meta.prefabInstanceId`; `detachPrefabInstance` strips those tags to break the link without touching the content.
+- `EditorScatterDirective` (interface): interface EditorScatterDirective extends EditorDirectiveBase — Scatters catalog props (rocks/trees/foliage) across a region — feeds the existing scatter system.
 - `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.
+- `EditorSkyPreset` (type): type EditorSkyPreset = "day" | "dusk" | "night" — Named sky look stored on the scene document; matches runtime `SkyEnvironmentConfig.preset`.
 - `EditorTerrain` (type): type EditorTerrain = TerraformSnapshot — A sculpted heightfield authored in the editor: the {@link TerraformSnapshot} of offset deltas over the game's base ground. Serializes with the scene; a game rebuilds the field with `editableTerrainFromSnapshot`.
 - `EditorUiDocument` (interface): interface EditorUiDocument — Scene-document HUD section: panel id → layout. Single source of truth for placement.
 - `EditorUiPanelLayout` (interface): interface EditorUiPanelLayout — Authored layout for one HUD panel inside `editor.scene.json` → `ui.panels`.
 - `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.
+- `EntityCatalogDocumentLike` (interface): interface EntityCatalogDocumentLike — Minimal document shape {@link entityEntryFromCatalog} reads — any `EditorDocument` satisfies it.
+- `EnvironmentContent` (interface): interface EnvironmentContent — The coordinate/placement content of a world, derived from its scene document.
+- `EnvironmentContentOptions` (interface): interface EnvironmentContentOptions extends ClearanceOptions — World-authoring convergence (#1018, epic #1006 Phase 4): derive the **coordinate/placement** content of an `environment()` world from the scene document, so a game with an authored document needs no coordinate arrays in `world.ts` — the remaining `world.ts` surface is engine tuning (noise, materials, sky preset, physics). Terrain footprint follows the authored objects, ground clearings come from authored spawns/POIs (`clearanceZonesFrom`), and the sculpt snapshot is the document's own terrain overlay. Pure and serializable; consumers pass the result straight to `environment({ terrain: terrain({ bounds }), clearings, sculpt })`.
 - `HudPanelTypeDef` (interface): interface HudPanelTypeDef — Declared panel type: growable axes, size limits, optional ParamSchema for the editor.
 - `HudResizeAxes` (type): type HudResizeAxes = "none" | "x" | "y" | "both" — Which axes a panel type may grow when resized in canvas mode. Resize is semantic — content reflows (longer track, more rows) — never a CSS scale of the whole panel.
+- `MaterializedInstance` (interface): interface MaterializedInstance — The deterministic materializer for scene {@link EditorDirective}s — the bake side of the bake/patch seam in #985. A directive is one authored line ("scatter rocks across the north ridge"); this expands it into many placements with **stable per-instance ids** (`<directiveId># <index>`) so a sparse overlay can hand-tweak or delete individual instances by id without every re-materialize orphaning those edits. Fully deterministic: same directive + seed + region ⇒ the same field, every time (safe for verify/CI). Built on the existing `scatter` primitive.
 - `RuntimeEntityState` (interface): interface RuntimeEntityState — One live entity row the runtime may stream to the editor (play-mode inspector feed).
 - `RuntimeInspectorGetResult` (interface): interface RuntimeInspectorGetResult — One resolved runtime field returned by `runtime_get`.
 - `RuntimeInspectorSetPlan` (interface): interface RuntimeInspectorSetPlan — Desired mutation from `runtime_set` before the host applies it.
@@ -51,19 +71,44 @@
 - `RuntimePlayControl` (interface): interface RuntimePlayControl — Play-mode sim gate held by the editor host — pause freezes ticks; step runs N frames then re-pauses.
 - `RuntimeStateDelta` (interface): interface RuntimeStateDelta — Incremental runtime state for the reverse channel. Entity rows upsert by id; `removeIds` drop rows; `tunables` shallow-merge. Ephemeral unless written back as a document patch.
 - `RuntimeStateSnapshot` (interface): interface RuntimeStateSnapshot — Full ephemeral runtime view held on the reverse channel — never mutates the document.
+- `SplitWorldOptions` (interface): interface SplitWorldOptions — Options controlling how a monolithic document is partitioned into shards.
+- `SplitWorldResult` (interface): interface SplitWorldResult — The result of splitting a document: a manifest plus the shard documents keyed by their file path.
+- `StreamUpdate` (interface): interface StreamUpdate — The residency change produced by one {@link WorldStreamer.update}.
+- `StreamerShard` (interface): interface StreamerShard — The proximity streamer for a sharded world (#985 stage 3): a stateful scheduler that decides, as the camera moves, which shards enter and leave residency. It is pure scheduling — actually reading/merging the shard documents stays the caller's job (compose with `@jgengine/core/editor/world`'s `loadWorldDocument` on each returned delta) — so the streamer has no I/O and stays deterministic and testable. Hysteresis (`loadRadius` < `keepRadius`) stops a shard on a boundary from thrashing load/unload every frame.
 - `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.
+- `WORLD_BASE_SHARD_ID` (const): const WORLD_BASE_SHARD_ID: "base" — The always-resident base shard id used by {@link splitEditorDocumentIntoShards}.
+- `WORLD_MANIFEST_KIND` (const): const WORLD_MANIFEST_KIND: "world" — A sharded **world**: a scene that is no longer one monolithic `editor.scene.json` but a manifest plus spatially-partitioned shard documents. A single-file game is the degenerate one-shard case, so nothing pays for scale it does not have. The shard/overlay documents are the exact {@link EditorDocument} format loaders already consume — this module is composition over `mergeEditorDocuments` / `extractEditorFragment` / `editorDocumentBounds`, not a new format.
+- `WorldGrid` (interface): interface WorldGrid — The world grid the shards partition space on.
+- `WorldManifest` (interface): interface WorldManifest — A world manifest — the `world.json` at the root of a world folder.
+- `WorldManifestShard` (interface): interface WorldManifestShard — One entry in a world manifest: a shard document, its footprint, residency, and optional overlay.
+- `WorldQuery` (interface): interface WorldQuery — A spatial query used to select which shards a neighborhood needs.
+- `WorldShardBounds` (interface): interface WorldShardBounds — A shard's XZ world-space footprint, `[minX, minZ]`..`[maxX, maxZ]`, used to route/stream loads.
+- `WorldShardResidency` (type): type WorldShardResidency = "always" | "streamed" — Whether a shard is always loaded (terrain, always-resident hero content) or streamed by proximity.
+- `WorldShardResolver` (type): type WorldShardResolver = (file: string) => EditorDocument | null — Resolves a shard/overlay file path to a decoded document, or null when it cannot be read.
+- `WorldStreamer` (interface): interface WorldStreamer — A stateful proximity streamer over a fixed shard set.
+- `WorldStreamerConfig` (interface): interface WorldStreamerConfig — Configuration for {@link createWorldStreamer}.
+- `WorldStreamingConfig` (interface): interface WorldStreamingConfig — Proximity streaming radii, in meters.
+- `applyDirectiveOverlay` (function): function applyDirectiveOverlay(instances: readonly MaterializedInstance[], overlay: EditorDirectiveOverlay): MaterializedInstance[] — Applies a directive overlay to its materialized instances: patched fields override, `deleted` drops the instance. Instances with no patch pass through untouched.
 - `applyDocumentPatch` (function): function applyDocumentPatch(document: EditorDocument, revision: number, patch: DocumentPatch, options?: { force?: boolean }): ApplyDocumentPatchResult — Applies a versioned document patch. Rejects base-revision mismatches unless `force` (document is authoritative — the editor forces when publishing its own session state).
 - `applyRuntimeStateDelta` (function): function applyRuntimeStateDelta(snapshot: RuntimeStateSnapshot, delta: Omit<RuntimeStateDelta, "seq"> & { seq?: number }): { snapshot: RuntimeStateSnapshot; delta: RuntimeStateDelta } — Merges a runtime delta into a snapshot without touching the scene document — runtime overrides stay ephemeral until an explicit write-back produces a document patch.
+- `bakeMinimapFromDocument` (function): function bakeMinimapFromDocument(doc: EditorDocument, sampleHeight: (x: number, z: number) => number, options: DocumentBakeOptions = {}): { background: string; mapBounds: MinimapBakeBounds } — Bakes a minimap image from a scene document plus a terrain height sampler: sizes the footprint to the authored objects (or an explicit `bounds`), tints biome-colored volumes, and rasterizes the terrain top-down. Returns `{ background, mapBounds }` for the `Minimap` props. The editor runs this as its bake action and stores the result on the document.
 - `cloneGridLayer` (function): function cloneGridLayer(layer: EditorGridLayer): EditorGridLayer — Deep-clones a grid layer so authoring edits and history snapshots never alias source cells.
 - `consumeRuntimePlayStep` (function): function consumeRuntimePlayStep(play: RuntimePlayControl): { runFrame: boolean; next: RuntimePlayControl; } — Advances the play-control step counter: when paused with pending steps, consumes one and reports whether the sim should run this frame. When not paused, always runs.
 - `createDocumentLiveSync` (function): function createDocumentLiveSync(initial: EditorDocument): DocumentLiveSync — Creates an in-memory two-way live-sync bus seeded from an initial document. Document is authoritative; runtime overrides are ephemeral until {@link DocumentLiveSync.writeBackOverride}.
 - `createGridLayer` (function): function createGridLayer(init: CreateGridLayerInit): EditorGridLayer — Creates a grid layer from a partial init, defaulting cell size to `1`, origin to the world origin, and axes to `"xz"`. Runs the result through {@link migrateGridLayer} so it is normalized and bounds-clean.
 - `createRuntimePlayControl` (function): function createRuntimePlayControl(paused = false): RuntimePlayControl — Default play-control state when entering play mode (running).
+- `createWorldStreamer` (function): function createWorldStreamer(config: WorldStreamerConfig): WorldStreamer — Creates a proximity streamer over a world's shards. Always-resident shards are resident from the first update onward; each bounded shard loads when the camera comes within `loadRadius` of its footprint and unloads only once the camera passes `keepRadius` (≥ `loadRadius`, clamped up), giving a hysteresis band that prevents boundary thrash. Purely spatial and deterministic; the caller wires each delta to `loadWorldDocument`.
+- `decodeWorldManifest` (function): function decodeWorldManifest(raw: unknown): DecodeWorldManifestResult — The authoritative decoder for a `world.json` manifest arriving from disk or an agent: validates `kind`, the shard list, and each shard's fields with a path-specific diagnostic on failure, so a malformed manifest fails loudly at the boundary instead of streaming a broken world.
+- `documentBakeZones` (function): function documentBakeZones(doc: EditorDocument): MinimapBakeZone[] — The biome-tint zones a document contributes to a bake: every volume carrying a `color` becomes a polygon tint over its footprint. (The optional stretch from #1036 — a bare bake still reads as terrain without any.)
+- `entityDefinitionSchema` (const): const entityDefinitionSchema: ParamSchema — The default {@link ParamSchema} for an authored entity definition — role, health, movement speed, and visual scale. Drives the editor Data-tab inspector for the `entities` catalog and is the shape {@link entityEntryFromCatalog} reads. A game exports it as an `editorCatalogs` schema; the scaffold ships a starter one so the tab is never empty.
+- `entityEntryFromCatalog` (function): function entityEntryFromCatalog(document: EntityCatalogDocumentLike, entityId: string, definitions?: readonly EditorCatalogDefinition[]): GameContextEntityEntry | null — Turns an authored entity row into the runtime {@link GameContextEntityEntry} a spawn consumes: looks up `entityId` in the document's {@link ENTITY_CATALOG_ID} catalog (falling back to the game-exported `definitions` defaults), parses it against {@link entityDefinitionSchema}, and maps the fields onto stats/movement/role. Returns `null` when no row defines the entity, so the default `content.ts` path can chain other resolvers. The single seam that makes "place a mob, tune its stats/speed in the editor, save — it spawns with those stats" work with zero game code.
+- `environmentContentFromDocument` (function): function environmentContentFromDocument(doc: EditorDocument, options: EnvironmentContentOptions = {}): EnvironmentContent — Derives the coordinate/placement content of an `environment()` world from its scene document: terrain footprint (via {@link terrainBoundsFromDocument}), ground clearings under authored spawns/POIs (via `clearanceZonesFrom`), and the document's sculpt snapshot. This is the seam that lets a game author its world footprint and flatten regions in the editor instead of hardcoding them — the `world.ts` that consumes it carries only engine tuning.
 - `eraseGridCell` (function): function eraseGridCell(layer: EditorGridLayer, col: number, row: number): EditorGridLayer — Erases `col,row` back to the layer's empty value — {@link setGridCell} with the empty value.
 - `exportAsciiGrid` (function): function exportAsciiGrid(layer: EditorGridLayer, options: AsciiGridExportOptions = {}): string — Renders a grid layer back to an ASCII/glyph map (rows top to bottom). Value ids map to chars via the layer palette (or an override map); empty cells become `emptyGlyph`. Round-trips with {@link importAsciiGrid} when the glyph legend matches.
 - `exportCsvGrid` (function): function exportCsvGrid(layer: EditorGridLayer, options: CsvGridExportOptions = {}): string — Renders a grid layer as CSV — one row per line, each cell's value id as a field, empty cells as `emptyField`. Round-trips with {@link importCsvGrid}.
+- `exportWorldManifestJson` (function): function exportWorldManifestJson(manifest: WorldManifest, pretty = true): string — Serializes a world manifest to pretty JSON for writing `world.json`.
 - `eyedropGridCell` (function): function eyedropGridCell(layer: EditorGridLayer, col: number, row: number): string — Samples the value id at `col,row` — the eyedropper. Identical to {@link getGridCell}, named for the authoring op that picks up a cell's value to paint with.
 - `fillGridRect` (function): function fillGridRect(layer: EditorGridLayer, col0: number, row0: number, col1: number, row1: number, value: string): EditorGridLayer — Fills the inclusive rectangle spanning the two corners with `value` (the rectangle tool). Corners may be given in any order; the clamped in-bounds portion is painted.
 - `findEditorCatalog` (function): function findEditorCatalog(doc: EditorDocument, id: string): EditorCatalogData | undefined — Looks up a gameplay data catalog by id on the scene document.
@@ -85,17 +130,31 @@
 - `importCsvGrid` (function): function importCsvGrid(text: string, options: CsvGridImportOptions): EditorGridLayer — Parses a CSV grid — one row per line, one value id per comma-separated field — into a grid layer. Blank fields become the empty value. Unlike ASCII this carries multi-character value ids directly, so it suits grids whose cell values are names rather than single glyphs.
 - `inGridBounds` (function): function inGridBounds(layer: EditorGridLayer, col: number, row: number): boolean — True when `col,row` falls inside the layer's declared bounds.
 - `installDocumentLiveSync` (function): function installDocumentLiveSync(sync: DocumentLiveSync): () => void — Publishes a live-sync bus globally so AuthoredScene / games can subscribe without prop drilling.
+- `loadWorldDocument` (function): function loadWorldDocument(manifest: WorldManifest, resolve: WorldShardResolver, query?: WorldQuery): EditorDocument — Loads the live neighborhood document for a query: reads each selected shard through `resolve`, applies its overlay (if any) on top, then merges them into one {@link EditorDocument} downstream consumers (`placeAuthoredObjects`, `collectAuthoredTriggers`, scatter, …) read unchanged. The monolith becomes an internal detail of the loader; a one-shard world yields exactly that shard.
+- `materializeDirective` (function): function materializeDirective(doc: EditorDocument, directive: EditorDirective): MaterializedInstance[] — Materializes one directive against a document, resolving its footprint first. Returns an empty list when the region does not resolve.
+- `materializeDirectives` (function): function materializeDirectives(doc: EditorDocument, overlays?: readonly EditorDirectiveOverlay[]): MaterializedInstance[] — Materializes every directive on a document into one flat instance list, applying each directive's overlay (matched by `over` === directive id) as it goes. The bulk-content counterpart to `resolveAuthoredObjects` / `resolveScatter`: games and headless tests read the same list.
+- `materializePopulationDirective` (function): function materializePopulationDirective(directive: EditorPopulationDirective, footprint: DirectiveFootprint): MaterializedInstance[] — Materializes a population directive into deterministic mob spawn placements: at most `cap` of each weighted species, distributed across the footprint. Each placement carries a stable id and its species id in `asset`, ready to feed `ctx.scene.entity.spawn` / `ai/populationDirector`.
+- `materializeScatterDirective` (function): function materializeScatterDirective(directive: EditorScatterDirective, footprint: DirectiveFootprint): MaterializedInstance[] — Materializes a scatter directive into deterministic catalog-prop placements across its footprint, clipped to the region polygon when one is present. Per-instance scale and yaw derive from the directive id + seed + point index, so ids are stable across re-materializes.
 - `migrateGridLayer` (function): function migrateGridLayer(layer: EditorGridLayer): EditorGridLayer — Normalizes a grid layer forward to the current cell-schema version: clamps `cols`/`rows` to non-negative integers, drops out-of-bounds and empty-valued cells, and stamps `schemaVersion`. The single migration seam every loader and authoring op funnels new/old layers through, so a layer from an older document or an import adapter always lands in a valid, minimal shape.
 - `paintGridCells` (function): function paintGridCells(layer: EditorGridLayer, edits: readonly EditorGridCellEdit[]): EditorGridLayer — Applies a batch of cell edits in one pass, returning the same layer when nothing changed. The op the editor uses for a drag stroke, a paste, or any multi-cell paint/erase.
 - `parseGridCellKey` (function): function parseGridCellKey(key: string): { col: number; row: number } | null — Parses a `"col,row"` sparse-map key back into integer coordinates, or `null` when malformed.
 - `planRuntimeInspectorSet` (function): function planRuntimeInspectorSet(document: EditorDocument, input: { id: string; path?: string; value?: unknown; position?: { x: number; y: number; z: number }; rotationY?: number; values?: Record<string, unknown>; writeBack?: boolean; }): RuntimeInspectorSetPlan — Plans a play-mode poke: builds the ephemeral entity/tunable override and, when `writeBack` is true, the undoable document commands that promote it into the scene document.
 - `resizeGridLayer` (function): function resizeGridLayer(layer: EditorGridLayer, cols: number, rows: number): EditorGridLayer — Resizes the layer's bounds to `cols`×`rows`, dropping any cells that fall outside the new extent (values are anchored at the origin corner). Negative or fractional sizes are floored to `≥ 0`.
+- `resolveCatalogDefinitions` (function): function resolveCatalogDefinitions(document: EntityCatalogDocumentLike, gameDefinitions: readonly EditorCatalogDefinition[]): EditorCatalogDefinition[] — Merges game-exported catalog definitions with editor-authored ones carried on the scene document. A document catalog that carries its own `schema` and has no matching game definition is synthesized into a full {@link EditorCatalogDefinition} (label falls back to the id) so the Data panel, the `list_catalogs` RPC, and the count all see it. A game definition always wins on id collision — its schema lives in code and is authoritative. Document catalogs without a schema (plain value bags for a game-declared catalog) are ignored here; they are addressed through their game definition.
+- `resolveDirectiveFootprint` (function): function resolveDirectiveFootprint(doc: EditorDocument, directive: EditorDirective): DirectiveFootprint | null — Resolves the footprint a directive fills: an explicit `area`, else the footprint of the named `region` — a scatter/closed path (as a clip polygon) or a volume (its XZ AABB). Null when neither is present or the region id does not resolve.
 - `runtimeEntityMetaWriteBackCommand` (function): function runtimeEntityMetaWriteBackCommand(document: EditorDocument, entity: RuntimeEntityState): EditorCommand | null — Promotes ephemeral runtime `values` into an undoable meta patch on a document-linked object. Returns null when the id is not in the document or there are no values.
 - `runtimeEntityWriteBackCommand` (function): function runtimeEntityWriteBackCommand(document: EditorDocument, entity: RuntimeEntityState): EditorCommand | null — Builds an undoable document command from an ephemeral runtime entity row (write-back). Returns null when there is nothing to promote. Does not mutate document or clear the override — the caller dispatches the command and then clears the override.
 - `seedEditorCatalogs` (function): function seedEditorCatalogs(doc: EditorDocument, definitions: readonly EditorCatalogDefinition[]): EditorDocument — Seeds default catalog rows from game-exported definitions into a document: missing catalogs and missing entries are filled from the definition; existing document values win (overlay already applied).
+- `selectWorldShards` (function): function selectWorldShards(manifest: WorldManifest, query?: WorldQuery): WorldManifestShard[] — The shards a query needs — always-resident shards plus every bounded shard whose footprint the query disc overlaps, in manifest order. With no query every shard is selected (load the planet), so a one-shard game and an unqueried load behave exactly as a monolithic document does today.
 - `setGridCell` (function): function setGridCell(layer: EditorGridLayer, col: number, row: number, value: string): EditorGridLayer — Returns a copy of the layer with `col,row` set to `value`, dropping the cell when `value` is the empty value (that is the erase op). Out-of-bounds writes and no-op writes return the layer unchanged, so callers can diff by identity.
+- `shardDistance` (function): function shardDistance(shard: StreamerShard, center: { x: number; z: number }): number — Distance from a point to a shard's XZ footprint (0 when inside), or 0 for an always-resident shard.
+- `shardMatchesQuery` (function): function shardMatchesQuery(shard: WorldManifestShard, query: WorldQuery): boolean — True when a shard should be resident for a query: always-resident shards always, bounded shards only when the query disc (`center` ± `radius`) overlaps their footprint.
+- `singleShardWorldManifest` (function): function singleShardWorldManifest(file: string, shardId = WORLD_BASE_SHARD_ID): WorldManifest — The backward-compatible degenerate manifest: one always-resident shard pointing at a single scene document file. `loadWorldDocument(singleShardWorldManifest(file), resolve)` returns exactly that document — the migration path for a game that has one `editor.scene.json` and wants the world API without sharding yet.
+- `skyFromDocument` (function): function skyFromDocument(doc: EditorDocument): SkyEnvironmentConfig | undefined — Maps the scene document's serializable environment bag onto the runtime sky config consumed by `sky()` / `environment({ sky })`. Returns `undefined` when the document has no environment field so callers can fall back to a world.ts default without inventing values.
+- `splitEditorDocumentIntoShards` (function): function splitEditorDocumentIntoShards(doc: EditorDocument, options: SplitWorldOptions = {}): SplitWorldResult — Splits a monolithic document into a sharded world: placeable objects (markers, volumes, paths, notes) are bucketed into `cellSize`-meter grid cells by a representative point and extracted into per-cell shard documents; the non-placeable extras (terrain, catalogs, prefabs, collections, grids, HUD layout) go into one always-resident `base` shard. Round-trips through {@link loadWorldDocument} to the same object set — the reverse of monolith authoring, so a large scene can be sharded once and streamed thereafter. Cell shards carry their exact object footprint as bounds; empty cells are omitted; order is deterministic (row-major by grid coordinate).
 - `subscribeDocumentLiveSyncInstall` (function): function subscribeDocumentLiveSyncInstall(listener: () => void): () => void — Subscribe to install/uninstall of the global live-sync bus (AuthoredScene re-attaches when the editor host mounts over a running game).
 - `summarizeRuntimeInspector` (function): function summarizeRuntimeInspector(snapshot: RuntimeStateSnapshot, overrides: Readonly<Record<string, RuntimeEntityState>>, play: RuntimePlayControl): RuntimeInspectorSummary — Builds the compact reverse-channel summary used by the play-mode inspector panel and the `runtime_summary` bridge RPC.
+- `terrainBoundsFromDocument` (function): function terrainBoundsFromDocument(doc: EditorDocument, options: EnvironmentContentOptions = {}): WorldBounds — The origin-centered terrain footprint that covers every authored object in a document, padded and floored to `minBounds`. An empty document yields exactly `minBounds`. Because `environment()` terrain is centered on the origin, the footprint is sized symmetrically to the farthest object on each axis, so no authored object falls off the ground.
 - `worldToGridCell` (function): function worldToGridCell(layer: EditorGridLayer, x: number, y: number, z: number): { col: number; row: number } — Inverse of {@link gridCellToWorld}: the nearest cell to a world point (may be out of bounds). The shared world→cell map runtime uses to answer "which cell is the player standing on".
 
 ## @jgengine/core/editor/commands
@@ -105,12 +164,42 @@
 - `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.
 
+## @jgengine/core/editor/directives
+
+- `DirectiveFootprint` (interface): interface DirectiveFootprint — A resolved directive footprint: the XZ bounds to scatter within, plus an optional clip polygon.
+- `DirectiveInstancePatch` (interface): interface DirectiveInstancePatch — A per-instance hand-tweak over a materialized directive, keyed by the minted instance id.
+- `EditorDirectiveOverlay` (interface): interface EditorDirectiveOverlay — A sparse overlay over one directive's materialized instances — the "nudge *that one* rock" answer. Hand-edits are keyed by the stable instance id the materializer mints, so they survive re-bakes.
+- `MaterializedInstance` (interface): interface MaterializedInstance — The deterministic materializer for scene {@link EditorDirective}s — the bake side of the bake/patch seam in #985. A directive is one authored line ("scatter rocks across the north ridge"); this expands it into many placements with **stable per-instance ids** (`<directiveId># <index>`) so a sparse overlay can hand-tweak or delete individual instances by id without every re-materialize orphaning those edits. Fully deterministic: same directive + seed + region ⇒ the same field, every time (safe for verify/CI). Built on the existing `scatter` primitive.
+- `applyDirectiveOverlay` (function): function applyDirectiveOverlay(instances: readonly MaterializedInstance[], overlay: EditorDirectiveOverlay): MaterializedInstance[] — Applies a directive overlay to its materialized instances: patched fields override, `deleted` drops the instance. Instances with no patch pass through untouched.
+- `materializeDirective` (function): function materializeDirective(doc: EditorDocument, directive: EditorDirective): MaterializedInstance[] — Materializes one directive against a document, resolving its footprint first. Returns an empty list when the region does not resolve.
+- `materializeDirectives` (function): function materializeDirectives(doc: EditorDocument, overlays?: readonly EditorDirectiveOverlay[]): MaterializedInstance[] — Materializes every directive on a document into one flat instance list, applying each directive's overlay (matched by `over` === directive id) as it goes. The bulk-content counterpart to `resolveAuthoredObjects` / `resolveScatter`: games and headless tests read the same list.
+- `materializePopulationDirective` (function): function materializePopulationDirective(directive: EditorPopulationDirective, footprint: DirectiveFootprint): MaterializedInstance[] — Materializes a population directive into deterministic mob spawn placements: at most `cap` of each weighted species, distributed across the footprint. Each placement carries a stable id and its species id in `asset`, ready to feed `ctx.scene.entity.spawn` / `ai/populationDirector`.
+- `materializeScatterDirective` (function): function materializeScatterDirective(directive: EditorScatterDirective, footprint: DirectiveFootprint): MaterializedInstance[] — Materializes a scatter directive into deterministic catalog-prop placements across its footprint, clipped to the region polygon when one is present. Per-instance scale and yaw derive from the directive id + seed + point index, so ids are stable across re-materializes.
+- `resolveDirectiveFootprint` (function): function resolveDirectiveFootprint(doc: EditorDocument, directive: EditorDirective): DirectiveFootprint | null — Resolves the footprint a directive fills: an explicit `area`, else the footprint of the named `region` — a scatter/closed path (as a clip polygon) or a volume (its XZ AABB). Null when neither is present or the region id does not resolve.
+
 ## @jgengine/core/editor/document
 
 - `findEditorCatalog` (function): function findEditorCatalog(doc: EditorDocument, id: string): EditorCatalogData | undefined — Looks up a gameplay data catalog by id on the scene document.
 - `findEditorCatalogEntry` (function): function findEditorCatalogEntry(doc: EditorDocument, catalogId: string, entryId: string): EditorCatalogEntry | undefined — Looks up one entry inside a gameplay data catalog.
 - `seedEditorCatalogs` (function): function seedEditorCatalogs(doc: EditorDocument, definitions: readonly EditorCatalogDefinition[]): EditorDocument — Seeds default catalog rows from game-exported definitions into a document: missing catalogs and missing entries are filled from the definition; existing document values win (overlay already applied).
 
+## @jgengine/core/editor/entityCatalog
+
+- `ENTITY_CATALOG_ID` (const): const ENTITY_CATALOG_ID: "entities" — Well-known catalog id for authored entity definitions. A `mob`/`boss` marker's `catalogId` references an entry (row) in this catalog, and {@link entityEntryFromCatalog} turns that row into the runtime {@link GameContextEntityEntry} a spawn consumes — so an entity's stats and speed are authored in the editor Data tab, not hardcoded in game TS.
+- `EntityCatalogDocumentLike` (interface): interface EntityCatalogDocumentLike — Minimal document shape {@link entityEntryFromCatalog} reads — any `EditorDocument` satisfies it.
+- `entityDefinitionSchema` (const): const entityDefinitionSchema: ParamSchema — The default {@link ParamSchema} for an authored entity definition — role, health, movement speed, and visual scale. Drives the editor Data-tab inspector for the `entities` catalog and is the shape {@link entityEntryFromCatalog} reads. A game exports it as an `editorCatalogs` schema; the scaffold ships a starter one so the tab is never empty.
+- `entityEntryFromCatalog` (function): function entityEntryFromCatalog(document: EntityCatalogDocumentLike, entityId: string, definitions?: readonly EditorCatalogDefinition[]): GameContextEntityEntry | null — Turns an authored entity row into the runtime {@link GameContextEntityEntry} a spawn consumes: looks up `entityId` in the document's {@link ENTITY_CATALOG_ID} catalog (falling back to the game-exported `definitions` defaults), parses it against {@link entityDefinitionSchema}, and maps the fields onto stats/movement/role. Returns `null` when no row defines the entity, so the default `content.ts` path can chain other resolvers. The single seam that makes "place a mob, tune its stats/speed in the editor, save — it spawns with those stats" work with zero game code.
+- `resolveCatalogDefinitions` (function): function resolveCatalogDefinitions(document: EntityCatalogDocumentLike, gameDefinitions: readonly EditorCatalogDefinition[]): EditorCatalogDefinition[] — Merges game-exported catalog definitions with editor-authored ones carried on the scene document. A document catalog that carries its own `schema` and has no matching game definition is synthesized into a full {@link EditorCatalogDefinition} (label falls back to the id) so the Data panel, the `list_catalogs` RPC, and the count all see it. A game definition always wins on id collision — its schema lives in code and is authoritative. Document catalogs without a schema (plain value bags for a game-declared catalog) are ignored here; they are addressed through their game definition.
+
+## @jgengine/core/editor/environment
+
+- `EnvironmentContent` (interface): interface EnvironmentContent — The coordinate/placement content of a world, derived from its scene document.
+- `EnvironmentContentOptions` (interface): interface EnvironmentContentOptions extends ClearanceOptions — World-authoring convergence (#1018, epic #1006 Phase 4): derive the **coordinate/placement** content of an `environment()` world from the scene document, so a game with an authored document needs no coordinate arrays in `world.ts` — the remaining `world.ts` surface is engine tuning (noise, materials, sky preset, physics). Terrain footprint follows the authored objects, ground clearings come from authored spawns/POIs (`clearanceZonesFrom`), and the sculpt snapshot is the document's own terrain overlay. Pure and serializable; consumers pass the result straight to `environment({ terrain: terrain({ bounds }), clearings, sculpt })`.
+- `environmentContentFromDocument` (function): function environmentContentFromDocument(doc: EditorDocument, options: EnvironmentContentOptions = {}): EnvironmentContent — Derives the coordinate/placement content of an `environment()` world from its scene document: terrain footprint (via {@link terrainBoundsFromDocument}), ground clearings under authored spawns/POIs (via `clearanceZonesFrom`), and the document's sculpt snapshot. This is the seam that lets a game author its world footprint and flatten regions in the editor instead of hardcoding them — the `world.ts` that consumes it carries only engine tuning.
+- `lakebedFromWaterVolumes` (function): function lakebedFromWaterVolumes(doc: EditorDocument): TerraformSnapshot | undefined — Derives a terrain-depression sculpt snapshot from the document's authored `water` volumes: each water box carves a lake bed that ramps from the shoreline down to below the box's bottom face, so an editor-authored pond/lake sits *in* the ground instead of floating as a sheet on top of it (and ground-sampled vegetation sinks below the surface rather than growing through it). Returns `undefined` when the document has no water volumes.
+- `skyFromDocument` (function): function skyFromDocument(doc: EditorDocument): SkyEnvironmentConfig | undefined — Maps the scene document's serializable environment bag onto the runtime sky config consumed by `sky()` / `environment({ sky })`. Returns `undefined` when the document has no environment field so callers can fall back to a world.ts default without inventing values.
+- `terrainBoundsFromDocument` (function): function terrainBoundsFromDocument(doc: EditorDocument, options: EnvironmentContentOptions = {}): WorldBounds — The origin-centered terrain footprint that covers every authored object in a document, padded and floored to `minBounds`. An empty document yields exactly `minBounds`. Because `environment()` terrain is centered on the origin, the footprint is sized symmetrically to the farthest object on each axis, so no authored object falls off the ground.
+
 ## @jgengine/core/editor/grid
 
 - `CURRENT_GRID_SCHEMA_VERSION` (const): const CURRENT_GRID_SCHEMA_VERSION: 1 — The grid-layer cell-schema version this build writes and migrates toward.
@@ -172,6 +261,12 @@
 - `runtimeEntityWriteBackCommand` (function): function runtimeEntityWriteBackCommand(document: EditorDocument, entity: RuntimeEntityState): EditorCommand | null — Builds an undoable document command from an ephemeral runtime entity row (write-back). Returns null when there is nothing to promote. Does not mutate document or clear the override — the caller dispatches the command and then clears the override.
 - `subscribeDocumentLiveSyncInstall` (function): function subscribeDocumentLiveSyncInstall(listener: () => void): () => void — Subscribe to install/uninstall of the global live-sync bus (AuthoredScene re-attaches when the editor host mounts over a running game).
 
+## @jgengine/core/editor/minimap
+
+- `DocumentBakeOptions` (interface): interface DocumentBakeOptions extends MinimapBakeOptions — Options for {@link bakeMinimapFromDocument}.
+- `bakeMinimapFromDocument` (function): function bakeMinimapFromDocument(doc: EditorDocument, sampleHeight: (x: number, z: number) => number, options: DocumentBakeOptions = {}): { background: string; mapBounds: MinimapBakeBounds } — Bakes a minimap image from a scene document plus a terrain height sampler: sizes the footprint to the authored objects (or an explicit `bounds`), tints biome-colored volumes, and rasterizes the terrain top-down. Returns `{ background, mapBounds }` for the `Minimap` props. The editor runs this as its bake action and stores the result on the document.
+- `documentBakeZones` (function): function documentBakeZones(doc: EditorDocument): MinimapBakeZone[] — The biome-tint zones a document contributes to a bake: every volume carrying a `color` becomes a polygon tint over its footprint. (The optional stretch from #1036 — a bare bake still reads as terrain without any.)
+
 ## @jgengine/core/editor/runtimeInspector
 
 - `RuntimeInspectorGetResult` (interface): interface RuntimeInspectorGetResult — One resolved runtime field returned by `runtime_get`.
@@ -185,6 +280,15 @@
 - `runtimeEntityMetaWriteBackCommand` (function): function runtimeEntityMetaWriteBackCommand(document: EditorDocument, entity: RuntimeEntityState): EditorCommand | null — Promotes ephemeral runtime `values` into an undoable meta patch on a document-linked object. Returns null when the id is not in the document or there are no values.
 - `summarizeRuntimeInspector` (function): function summarizeRuntimeInspector(snapshot: RuntimeStateSnapshot, overrides: Readonly<Record<string, RuntimeEntityState>>, play: RuntimePlayControl): RuntimeInspectorSummary — Builds the compact reverse-channel summary used by the play-mode inspector panel and the `runtime_summary` bridge RPC.
 
+## @jgengine/core/editor/streamer
+
+- `StreamUpdate` (interface): interface StreamUpdate — The residency change produced by one {@link WorldStreamer.update}.
+- `StreamerShard` (interface): interface StreamerShard — The proximity streamer for a sharded world (#985 stage 3): a stateful scheduler that decides, as the camera moves, which shards enter and leave residency. It is pure scheduling — actually reading/merging the shard documents stays the caller's job (compose with `@jgengine/core/editor/world`'s `loadWorldDocument` on each returned delta) — so the streamer has no I/O and stays deterministic and testable. Hysteresis (`loadRadius` < `keepRadius`) stops a shard on a boundary from thrashing load/unload every frame.
+- `WorldStreamer` (interface): interface WorldStreamer — A stateful proximity streamer over a fixed shard set.
+- `WorldStreamerConfig` (interface): interface WorldStreamerConfig — Configuration for {@link createWorldStreamer}.
+- `createWorldStreamer` (function): function createWorldStreamer(config: WorldStreamerConfig): WorldStreamer — Creates a proximity streamer over a world's shards. Always-resident shards are resident from the first update onward; each bounded shard loads when the camera comes within `loadRadius` of its footprint and unloads only once the camera passes `keepRadius` (≥ `loadRadius`, clamped up), giving a hysteresis band that prevents boundary thrash. Purely spatial and deterministic; the caller wires each delta to `loadWorldDocument`.
+- `shardDistance` (function): function shardDistance(shard: StreamerShard, center: { x: number; z: number }): number — Distance from a point to a shard's XZ footprint (0 when inside), or 0 for an always-resident shard.
+
 ## @jgengine/core/editor/types
 
 - `EditorCatalogData` (interface): interface EditorCatalogData — Persisted values for one gameplay data catalog (weapons, waves, economy, …). Schemas are not stored here — they come from the game's `editorCatalogs` export and drive SchemaInspector.
@@ -192,14 +296,24 @@
 - `EditorCatalogEntry` (interface): interface EditorCatalogEntry — One row in a gameplay data catalog — id + optional label + a meta bag matching the catalog's `ParamSchema`. Values persist on the scene document; the schema lives in the game export.
 - `EditorCatalogsInput` (type): type EditorCatalogsInput = | readonly EditorCatalogDefinition[] | (() => readonly EditorCatalogDefinition[]) — Accepted shape for a game's `editorCatalogs` export: definitions, or a factory.
 - `EditorCollection` (interface): interface EditorCollection — A named, persisted list of object ids — a selection bookmark (restore, add-to) that can also double as a production group: `locked` blocks `translate`/`setTransform`/`remove`/`removeMany` on its members, `color`/`visible` are UI-only hints for the collections panel.
+- `EditorDirective` (type): type EditorDirective = EditorScatterDirective | EditorPopulationDirective — A procedural directive on the scene document: scatter props or a mob population.
+- `EditorDirectiveArea` (interface): interface EditorDirectiveArea — XZ world-space bounds, `[minX, minZ]`..`[maxX, maxZ]`, for a directive that names no region.
+- `EditorDirectiveKind` (type): type EditorDirectiveKind = EditorDirective["kind"] — The distinct directive kinds a materializer expands.
 - `EditorDocument` (interface): interface EditorDocument — The full authored scene: every marker, volume, path, note, and sculpted terrain for a game.
+- `EditorEnvironment` (interface): interface EditorEnvironment — Scene-document environment/lighting authoring (#1110): sky preset, optional time-of-day drive, horizon/zenith tints, sun/ambient intensity, and fog. Serializable and genre-agnostic — games feed it into `environment({ sky: sky(skyFromDocument(doc)) })` (or leave world.ts sky as a fallback when the field is absent). Absent until the lighting workspace (or a seed layer) writes it, so existing documents load unchanged.
+- `EditorFogConfig` (interface): interface EditorFogConfig — Linear distance fog authored on the scene document — serializable subset of sky/backdrop fog. Absent fields keep engine defaults when the document is applied at runtime.
 - `EditorFragmentContent` (interface): interface EditorFragmentContent — The four placeable-object collections a prefab fragment or clipboard fragment carries.
 - `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.
+- `EditorMinimapBake` (interface): interface EditorMinimapBake — A baked top-down minimap stored on the scene document (#1036): the PNG the editor rasterized from the authored terrain (a `data:image/png;base64,…` URI) plus the world bounds it spans. Runtime feeds these straight into the `Minimap`/`WorldMap` `background`/`mapBounds` props — no re-raster.
 - `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.
+- `EditorPopulationDirective` (interface): interface EditorPopulationDirective extends EditorDirectiveBase — Populates a region with weighted, capped mob spawns — config for `ai/populationDirector`.
+- `EditorPopulationSpecies` (interface): interface EditorPopulationSpecies — One weighted species in a population directive, with a hard instance cap.
 - `EditorPrefab` (interface): interface EditorPrefab — A serializable, reusable stamp of authored objects — markers/volumes/paths/notes centered on their own centroid so the same prefab inserts consistently anywhere, in this scene or another game's. `insertPrefab` tags every inserted object's `meta.prefabId`/`meta.prefabInstanceId`; `detachPrefabInstance` strips those tags to break the link without touching the content.
+- `EditorScatterDirective` (interface): interface EditorScatterDirective extends EditorDirectiveBase — Scatters catalog props (rocks/trees/foliage) across a region — feeds the existing scatter system.
+- `EditorSkyPreset` (type): type EditorSkyPreset = "day" | "dusk" | "night" — Named sky look stored on the scene document; matches runtime `SkyEnvironmentConfig.preset`.
 - `EditorTerrain` (type): type EditorTerrain = TerraformSnapshot — A sculpted heightfield authored in the editor: the {@link TerraformSnapshot} of offset deltas over the game's base ground. Serializes with the scene; a game rebuilds the field with `editableTerrainFromSnapshot`.
 - `EditorUiDocument` (interface): interface EditorUiDocument — Scene-document HUD section: panel id → layout. Single source of truth for placement.
 - `EditorUiPanelLayout` (interface): interface EditorUiPanelLayout — Authored layout for one HUD panel inside `editor.scene.json` → `ui.panels`.
@@ -212,6 +326,29 @@
 - `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/editor/world
+
+- `DecodeWorldManifestResult` (type): type DecodeWorldManifestResult = | { ok: true; manifest: WorldManifest } | { ok: false; errors: EditorDocumentDiagnostic[] } — Result of {@link decodeWorldManifest}: a typed manifest, or every diagnostic collected decoding it.
+- `SplitWorldOptions` (interface): interface SplitWorldOptions — Options controlling how a monolithic document is partitioned into shards.
+- `SplitWorldResult` (interface): interface SplitWorldResult — The result of splitting a document: a manifest plus the shard documents keyed by their file path.
+- `WORLD_BASE_SHARD_ID` (const): const WORLD_BASE_SHARD_ID: "base" — The always-resident base shard id used by {@link splitEditorDocumentIntoShards}.
+- `WORLD_MANIFEST_KIND` (const): const WORLD_MANIFEST_KIND: "world" — A sharded **world**: a scene that is no longer one monolithic `editor.scene.json` but a manifest plus spatially-partitioned shard documents. A single-file game is the degenerate one-shard case, so nothing pays for scale it does not have. The shard/overlay documents are the exact {@link EditorDocument} format loaders already consume — this module is composition over `mergeEditorDocuments` / `extractEditorFragment` / `editorDocumentBounds`, not a new format.
+- `WorldGrid` (interface): interface WorldGrid — The world grid the shards partition space on.
+- `WorldManifest` (interface): interface WorldManifest — A world manifest — the `world.json` at the root of a world folder.
+- `WorldManifestShard` (interface): interface WorldManifestShard — One entry in a world manifest: a shard document, its footprint, residency, and optional overlay.
+- `WorldQuery` (interface): interface WorldQuery — A spatial query used to select which shards a neighborhood needs.
+- `WorldShardBounds` (interface): interface WorldShardBounds — A shard's XZ world-space footprint, `[minX, minZ]`..`[maxX, maxZ]`, used to route/stream loads.
+- `WorldShardResidency` (type): type WorldShardResidency = "always" | "streamed" — Whether a shard is always loaded (terrain, always-resident hero content) or streamed by proximity.
+- `WorldShardResolver` (type): type WorldShardResolver = (file: string) => EditorDocument | null — Resolves a shard/overlay file path to a decoded document, or null when it cannot be read.
+- `WorldStreamingConfig` (interface): interface WorldStreamingConfig — Proximity streaming radii, in meters.
+- `decodeWorldManifest` (function): function decodeWorldManifest(raw: unknown): DecodeWorldManifestResult — The authoritative decoder for a `world.json` manifest arriving from disk or an agent: validates `kind`, the shard list, and each shard's fields with a path-specific diagnostic on failure, so a malformed manifest fails loudly at the boundary instead of streaming a broken world.
+- `exportWorldManifestJson` (function): function exportWorldManifestJson(manifest: WorldManifest, pretty = true): string — Serializes a world manifest to pretty JSON for writing `world.json`.
+- `loadWorldDocument` (function): function loadWorldDocument(manifest: WorldManifest, resolve: WorldShardResolver, query?: WorldQuery): EditorDocument — Loads the live neighborhood document for a query: reads each selected shard through `resolve`, applies its overlay (if any) on top, then merges them into one {@link EditorDocument} downstream consumers (`placeAuthoredObjects`, `collectAuthoredTriggers`, scatter, …) read unchanged. The monolith becomes an internal detail of the loader; a one-shard world yields exactly that shard.
+- `selectWorldShards` (function): function selectWorldShards(manifest: WorldManifest, query?: WorldQuery): WorldManifestShard[] — The shards a query needs — always-resident shards plus every bounded shard whose footprint the query disc overlaps, in manifest order. With no query every shard is selected (load the planet), so a one-shard game and an unqueried load behave exactly as a monolithic document does today.
+- `shardMatchesQuery` (function): function shardMatchesQuery(shard: WorldManifestShard, query: WorldQuery): boolean — True when a shard should be resident for a query: always-resident shards always, bounded shards only when the query disc (`center` ± `radius`) overlaps their footprint.
+- `singleShardWorldManifest` (function): function singleShardWorldManifest(file: string, shardId = WORLD_BASE_SHARD_ID): WorldManifest — The backward-compatible degenerate manifest: one always-resident shard pointing at a single scene document file. `loadWorldDocument(singleShardWorldManifest(file), resolve)` returns exactly that document — the migration path for a game that has one `editor.scene.json` and wants the world API without sharding yet.
+- `splitEditorDocumentIntoShards` (function): function splitEditorDocumentIntoShards(doc: EditorDocument, options: SplitWorldOptions = {}): SplitWorldResult — Splits a monolithic document into a sharded world: placeable objects (markers, volumes, paths, notes) are bucketed into `cellSize`-meter grid cells by a representative point and extracted into per-cell shard documents; the non-placeable extras (terrain, catalogs, prefabs, collections, grids, HUD layout) go into one always-resident `base` shard. Round-trips through {@link loadWorldDocument} to the same object set — the reverse of monolith authoring, so a large scene can be sharded once and streamed thereafter. Cell shards carry their exact object footprint as bounds; empty cells are omitted; order is deterministic (row-major by grid coordinate).
+
 ## @jgengine/core/scene/sceneOwnership
 
 - `AuthoredProvenance` (interface): interface AuthoredProvenance — A first-class entry in the scene document — the editor fully owns and persists it.
@@ -248,6 +385,7 @@
 - `AgentTranscriptEntry` (type): type AgentTranscriptEntry = | { kind: "user"; id: string; content: string; at: number } | { kind: "assistant"; id: string; content: string; at: number } | { kind: "tool"; id: string; result: AgentToolResult; at: number } | { kind: "error"; id: string; content: string; at: number } | { kind: "patch";… — One rendered line in the agent panel transcript (user, assistant, tool, error, or patch).
 - `AgentTurnResult` (interface): interface AgentTurnResult — Result of {@link runAgentTurn}: chat history, UI transcript, undoable patches, and packed context.
 - `AssetBrowser` (function): function AssetBrowser({ assets, session, onPlace, }: { assets: readonly EditorAssetEntry[]; session: EditorSession; onPlace: (entry: EditorAssetEntry) => void; }): React.JSX.Element — Searchable panel for placing catalog assets or an empty marker into the scene.
+- `AssetImporter` (type): type AssetImporter = (file: File) => Promise<StandaloneAsset | null> — Persists a dropped model file through the editor host so it survives reload as a durable catalog asset, returning the host-assigned id/url (which the manifest scan re-lists on reload). Resolves `null` when no host is listening — a plain browser mount with no dev server — so the caller can fall back to a blob URL.
 - `BlankPlayableOptions` (interface): interface BlankPlayableOptions — Options for the blank, gameless world the standalone editor authors over.
 - `DEFAULT_PAINT_SETTINGS` (const): const DEFAULT_PAINT_SETTINGS: PaintSettings — The terrain tool's default paint controls.
 - `DEFAULT_SCULPT_SETTINGS` (const): const DEFAULT_SCULPT_SETTINGS: SculptSettings — The terrain tool's default brush controls.
@@ -255,7 +393,7 @@
 - `EDITOR_AGENT_KEY_FALLBACK_ENV` (const): const EDITOR_AGENT_KEY_FALLBACK_ENV: "ANTHROPIC_API_KEY" — Fallback API-key env when `JGENGINE_EDITOR_AGENT_KEY` is unset (`ANTHROPIC_API_KEY`).
 - `EDITOR_AGENT_URL_ENV` (const): const EDITOR_AGENT_URL_ENV: "JGENGINE_EDITOR_AGENT_URL" — Env var name for the remote agent HTTP URL (`JGENGINE_EDITOR_AGENT_URL`).
 - `EDITOR_MCP_TOOLS` (const): const EDITOR_MCP_TOOLS: readonly EditorMcpTool[] — Full set of MCP tools an agent can call to drive the live scene editor.
-- `EditorApp` (function): function EditorApp({ gameId, playable, layers, catalogs, save, modeChip }: EditorAppProps): React.JSX.Element — Top-level scene editor: author spawns/zones/paths/notes visually over edit, walk, or play modes.
+- `EditorApp` (function): function EditorApp({ gameId, playable, layers, catalogs, save, modeChip, networkPresence, onExitEditor }: EditorAppProps): React.JSX.Element — Top-level scene editor: author spawns/zones/paths/notes visually over edit, walk, or play modes.
 - `EditorAppProps` (interface): interface EditorAppProps — Props for mounting the scene editor over a playable game.
 - `EditorAssetEntry` (interface): interface EditorAssetEntry — A searchable, placeable asset shown in the editor's asset browser panel.
 - `EditorAssetInfo` (interface): interface EditorAssetInfo — A placeable asset entry offered in the editor's asset browser.
@@ -264,12 +402,17 @@
 - `EditorBridgeServer` (interface): interface EditorBridgeServer — A running editor bridge server: its bound port, URL, and a stop handle.
 - `EditorBridgeServerOptions` (interface): interface EditorBridgeServerOptions — Options for starting the editor's HTTP bridge server: host api, port, hostname.
 - `EditorCameraDriver` (const): const EditorCameraDriver: React.MemoExoticComponent<({ api }: { api: EditorHostApi; }) => null> — Smoothly pans the orbit camera to the editor host's focus target when it changes.
-- `EditorChrome` (function): function EditorChrome({ gameId, session, api, assets, ui, baselineJson, save, }: { gameId: string; session: EditorSession; api: EditorHostApi; assets: readonly EditorAssetEntry[]; ui: EditorUiStore; baselineJson?: string; save?: (json: string) => Promise<{ ok: boolean; path?: string; error?: string … — The full editor UI shell — toolbar, left panels (outliner/prefabs/sets/layers), viewport overlays, the selector-subscribed {@link InspectorPanel}, the embedded {@link AgentPanel}, and the asset browser — wired to the session, UI store, and host RPC. Mounted by `EditorApp`; not a game-author entry point.
+- `EditorChrome` (function): function EditorChrome({ gameId, session, api, assets, ui, baselineDocument, save, networkSnapshot, importAsset = importAssetToHost, onRegisterAsset, onExitEditor, }: { gameId: string; session: EditorSession; api: EditorHostApi; assets: readonly EditorAssetEntry[]; ui: EditorUiStore; /** The document… — The full editor UI shell — global app bar, contextual scene toolbar, workspace rail, resizable hierarchy/inspector docks, tabbed bottom dock (content browser, console, profiler, AI assistant), viewport overlays, and status bar — wired to the session, UI store, layout store, and host RPC. Mounted by `EditorApp`; not a game-author entry point.
 - `EditorHostApi` (interface): interface EditorHostApi — The live editor's global control surface — session, visibility, camera focus, assets, mode, RPC.
-- `EditorLayerOverlays` (function): function EditorLayerOverlays({ document, visibility, selection, onSelect, activePathPoint, groundHeightAt, }: { document: EditorDocument; visibility: EditorKindVisibility; selection: readonly string[]; onSelect: (id: string) => void; activePathPoint?: { pathId: string; index: number } | null; ground… — Renders every visible marker, volume, path, and note from a document as in-scene 3D gizmos.
+- `EditorLayerOverlays` (function): function EditorLayerOverlays({ document, visibility, selection, hoverId = null, onSelect, activePathPoint, groundHeightAt, }: { document: EditorDocument; visibility: EditorKindVisibility; selection: readonly string[]; /** Pre-selection hover id from viewport pointer pick; ignored when already select… — Renders every visible marker, volume, path, and note from a document as in-scene 3D gizmos.
 - `EditorMcpTool` (interface): interface EditorMcpTool — One MCP tool descriptor — same verbs as the in-browser host RPC.
+- `EditorNetworkAdapterKind` (type): type EditorNetworkAdapterKind = MultiplayerAdapterConfig["kind"] | "unknown" — Transport kind declared by the game, or `"unknown"` when the config is unreadable.
+- `EditorNetworkPresenceActor` (interface): interface EditorNetworkPresenceActor — One online actor from a host-supplied presence feed. Fields mirror {@link PresencePoseRow} so hosts can forward backend rows without inventing shape.
+- `EditorNetworkPresenceInput` (interface): interface EditorNetworkPresenceInput — Optional live presence/session injection from the editor host.
+- `EditorNetworkSession` (interface): interface EditorNetworkSession — Optional live session identity when a multiplayer backend is attached. Omit entirely when the host has no session — the panel reports offline honestly.
+- `EditorNetworkSnapshot` (interface): interface EditorNetworkSnapshot — Host-facing network inspection payload for the editor Network workspace.
 - `EditorPerfSample` (interface): interface EditorPerfSample — Rolling frame-rate sample published by the in-canvas PerfProbe.
-- `EditorRunMode` (type): type EditorRunMode = "edit" | "walk" | "play" — How the editor hosts the game: frozen placement view, roamable world, or the real game.
+- `EditorRunMode` (type): type EditorRunMode = "edit" | "walk" | "play" | "hud" — How the editor hosts the game: frozen placement view, roamable world, the real game, or HUD-layout authoring.
 - `EditorSaveFn` (type): type EditorSaveFn = (json: string) => Promise<{ ok: boolean; path?: string; error?: string }> — Persists an exported document JSON; resolves with where it landed or why it failed.
 - `EditorTool` (type): type EditorTool = "select" | "terrain" — Which top-level editor tool is active: object placement/selection, or terrain sculpting.
 - `EditorUiState` (interface): interface EditorUiState — Transient editor UI state shared between chrome, viewport, and gizmos.
@@ -282,8 +425,8 @@
 - `SculptSettings` (interface): interface SculptSettings — Live terrain-brush controls driven by the terrain tool panel.
 - `SelectionGizmo` (const): const SelectionGizmo: React.MemoExoticComponent<({ session, ui, groundSnap, }: { session: EditorSession; ui: EditorUiStore; groundSnap?: ((x: number, z: number) => number) | undefined; }) => React.JSX.Element | null> — Drag-to-transform gizmo bound to the current selection, dispatching editor commands on release. Mounts the shared shell `TransformGizmo` and maps release poses onto editor commands (multi-select translate, volume scale, path vertex move).
 - `SnapMode` (type): type SnapMode = "ground" | "grid" | "off" — How gizmo drags land: stick to terrain height, quantize to a grid, or free.
-- `StandaloneAsset` (interface): interface StandaloneAsset — One user-supplied model the standalone editor can place: a stable id and a resolvable URL.
-- `StandaloneEditor` (function): function StandaloneEditor({ sceneId = "standalone", scene, assets, world, save, hidePickers = false, }: StandaloneEditorProps): React.JSX.Element — The scene editor, mounted over a blank gameless world instead of a game — the same `EditorApp` every jgengine game ships, usable standalone on the user's own project (CLI `jgengine editor`, desktop app, or any React host). Ships a slim strip to open a world file and pull in an asset folder; both are also settable up front through props.
+- `StandaloneAsset` (interface): interface StandaloneAsset — Shared model-import helpers used by the standalone editor strip and the in-game Content Browser. Host-agnostic and free of React/shell so unit tests can exercise the importer without a DOM or three.
+- `StandaloneEditor` (function): function StandaloneEditor({ sceneId = "standalone", scene, assets, world, save, importAsset = importAssetToHost, hidePickers = false, }: StandaloneEditorProps): React.JSX.Element — The scene editor, mounted over a blank gameless world instead of a game — the same `EditorApp` every jgengine game ships, usable standalone on the user's own project (CLI `jgengine editor`, desktop app, or any React host). Ships a slim strip to open a world file and pull in an asset folder; both are also settable up front through props.
 - `StandaloneEditorProps` (interface): interface StandaloneEditorProps — Props for the gameless scene editor — everything optional so it boots on a blank world with nothing wired.
 - `SubscribableStore` (interface): interface SubscribableStore<S> — The minimal external-store shape both the editor session and UI store satisfy.
 - `TERRAIN_MATERIALS` (const): const TERRAIN_MATERIALS: readonly TerrainMaterial[] — The default terrain paint palette (surface id → color) shared by the panel and the mesh.
@@ -293,8 +436,8 @@
 - `TerrainMode` (type): type TerrainMode = "sculpt" | "paint" — The terrain tool's active sub-mode: reshape the heightfield, or paint material layers onto it.
 - `ViewportSelect` (const): const ViewportSelect: React.MemoExoticComponent<({ api, ui }: { api: EditorHostApi; ui: EditorUiStore; }) => null> — Canvas click-to-select and click-to-place. Document objects pick by screen proximity (registration always matches what you see) with click-cycling through stacked candidates and shift/ctrl additive selection; everything else picks by occlusion-ordered raycast against the tagged scene graph. When a placement tool is armed, clicks author new markers, volumes, notes, or path points at the ground hit instead of selecting.
 - `VirtualWindow` (interface): interface VirtualWindow — The visible slice of a fixed-row-height list: which rows to mount and the spacer geometry.
-- `assetsFromCatalog` (function): function assetsFromCatalog(ids: readonly string[], resolve?: (id: string) => { url?: string } | null): EditorAssetEntry[] — Turns a game's asset catalog ids into editor asset entries for the browser panel.
-- `blankWorld` (function): function blankWorld(seed = "standalone"): EnvironmentWorldFeature — The default flat-ground world the standalone editor opens on when the host supplies none.
+- `assetsFromCatalog` (function): function assetsFromCatalog(ids: readonly string[], resolve?: (id: string) => { url?: string; clips?: readonly string[] } | null): EditorAssetEntry[] — Turns a game's asset catalog ids into editor asset entries for the browser panel.
+- `blankWorld` (function): function blankWorld(_seed = "standalone"): EnvironmentWorldFeature — The default flat-ground authoring canvas the standalone editor opens on when the host supplies none. Deliberately thin — bare sculptable ground under a clear default sky. Dressing (sky look, foliage scatter, props) is what the author adds here, written into the scene document; it is never pre-baked into the canvas. The `seed` parameter is legacy and unused.
 - `createBlankPlayable` (function): function createBlankPlayable(options: BlankPlayableOptions = {}): PlayableGame — Builds a minimal gameless `PlayableGame` — a flat world plus an asset catalog — for the editor to mount over.
 - `createDefaultAgentEndpoint` (function): function createDefaultAgentEndpoint(config: AgentEndpointConfig = resolveAgentEndpointConfig()): AgentEndpoint — Picks HTTP endpoint when `JGENGINE_EDITOR_AGENT_URL` (or config.url) is set, otherwise the offline local agent.
 - `createEditorUiStore` (function): function createEditorUiStore(): EditorUiStore — Creates the shared UI store the editor chrome and viewport both drive.
@@ -314,19 +457,20 @@
 
 ## @jgengine/editor/AssetBrowser
 
+- `ASSET_DRAG_MIME` (const): const ASSET_DRAG_MIME: "application/x-jgengine-editor-asset" — Custom drag mime for placeable catalog assets. Payload is JSON `{ id, label, kind }` so the viewport can call `place_asset` without a registry round-trip.
 - `AssetBrowser` (function): function AssetBrowser({ assets, session, onPlace, }: { assets: readonly EditorAssetEntry[]; session: EditorSession; onPlace: (entry: EditorAssetEntry) => void; }): React.JSX.Element — Searchable panel for placing catalog assets or an empty marker into the scene.
 - `EditorAssetEntry` (interface): interface EditorAssetEntry — A searchable, placeable asset shown in the editor's asset browser panel.
-- `MATERIAL_DRAG_MIME` (const): const MATERIAL_DRAG_MIME: "application/x-jgengine-material" — Custom drag mime carrying a material id — read by `OutlinerPanel` rows and the viewport drop zone.
-- `assetsFromCatalog` (function): function assetsFromCatalog(ids: readonly string[], resolve?: (id: string) => { url?: string } | null): EditorAssetEntry[] — Turns a game's asset catalog ids into editor asset entries for the browser panel.
+- `MATERIAL_DRAG_MIME` (const): const MATERIAL_DRAG_MIME: "application/x-jgengine-material" — Custom drag mime carrying a material id — read by hierarchy rows and the viewport drop zone.
+- `assetsFromCatalog` (function): function assetsFromCatalog(ids: readonly string[], resolve?: (id: string) => { url?: string; clips?: readonly string[] } | null): EditorAssetEntry[] — Turns a game's asset catalog ids into editor asset entries for the browser panel.
 
 ## @jgengine/editor/DebugDraw
 
-- `EditorLayerOverlays` (function): function EditorLayerOverlays({ document, visibility, selection, onSelect, activePathPoint, groundHeightAt, }: { document: EditorDocument; visibility: EditorKindVisibility; selection: readonly string[]; onSelect: (id: string) => void; activePathPoint?: { pathId: string; index: number } | null; ground… — Renders every visible marker, volume, path, and note from a document as in-scene 3D gizmos.
+- `EditorLayerOverlays` (function): function EditorLayerOverlays({ document, visibility, selection, hoverId = null, onSelect, activePathPoint, groundHeightAt, }: { document: EditorDocument; visibility: EditorKindVisibility; selection: readonly string[]; /** Pre-selection hover id from viewport pointer pick; ignored when already select… — Renders every visible marker, volume, path, and note from a document as in-scene 3D gizmos.
 - `PathDraftPreview` (function): function PathDraftPreview({ points }: { points: readonly EditorVec3[] }): React.JSX.Element — Live preview of an in-progress path drawing: placed points and the connecting line.
 
 ## @jgengine/editor/EditorApp
 
-- `EditorApp` (function): function EditorApp({ gameId, playable, layers, catalogs, save, modeChip }: EditorAppProps): React.JSX.Element — Top-level scene editor: author spawns/zones/paths/notes visually over edit, walk, or play modes.
+- `EditorApp` (function): function EditorApp({ gameId, playable, layers, catalogs, save, modeChip, networkPresence, onExitEditor }: EditorAppProps): React.JSX.Element — Top-level scene editor: author spawns/zones/paths/notes visually over edit, walk, or play modes.
 - `EditorAppProps` (interface): interface EditorAppProps — Props for mounting the scene editor over a playable game.
 - `EditorSaveFn` (type): type EditorSaveFn = (json: string) => Promise<{ ok: boolean; path?: string; error?: string }> — Persists an exported document JSON; resolves with where it landed or why it failed.
 
@@ -336,7 +480,7 @@
 
 ## @jgengine/editor/EditorChrome
 
-- `EditorChrome` (function): function EditorChrome({ gameId, session, api, assets, ui, baselineJson, save, }: { gameId: string; session: EditorSession; api: EditorHostApi; assets: readonly EditorAssetEntry[]; ui: EditorUiStore; baselineJson?: string; save?: (json: string) => Promise<{ ok: boolean; path?: string; error?: string … — The full editor UI shell — toolbar, left panels (outliner/prefabs/sets/layers), viewport overlays, the selector-subscribed {@link InspectorPanel}, the embedded {@link AgentPanel}, and the asset browser — wired to the session, UI store, and host RPC. Mounted by `EditorApp`; not a game-author entry point.
+- `EditorChrome` (function): function EditorChrome({ gameId, session, api, assets, ui, baselineDocument, save, networkSnapshot, importAsset = importAssetToHost, onRegisterAsset, onExitEditor, }: { gameId: string; session: EditorSession; api: EditorHostApi; assets: readonly EditorAssetEntry[]; ui: EditorUiStore; /** The document… — The full editor UI shell — global app bar, contextual scene toolbar, workspace rail, resizable hierarchy/inspector docks, tabbed bottom dock (content browser, console, profiler, AI assistant), viewport overlays, and status bar — wired to the session, UI store, layout store, and host RPC. Mounted by `EditorApp`; not a game-author entry point.
 
 ## @jgengine/editor/PerfProbe
 
@@ -354,17 +498,18 @@
 
 ## @jgengine/editor/StandaloneEditor
 
+- `AssetImporter` (type): type AssetImporter = (file: File) => Promise<StandaloneAsset | null> — Persists a dropped model file through the editor host so it survives reload as a durable catalog asset, returning the host-assigned id/url (which the manifest scan re-lists on reload). Resolves `null` when no host is listening — a plain browser mount with no dev server — so the caller can fall back to a blob URL.
 - `BlankPlayableOptions` (interface): interface BlankPlayableOptions — Options for the blank, gameless world the standalone editor authors over.
-- `StandaloneAsset` (interface): interface StandaloneAsset — One user-supplied model the standalone editor can place: a stable id and a resolvable URL.
-- `StandaloneEditor` (function): function StandaloneEditor({ sceneId = "standalone", scene, assets, world, save, hidePickers = false, }: StandaloneEditorProps): React.JSX.Element — The scene editor, mounted over a blank gameless world instead of a game — the same `EditorApp` every jgengine game ships, usable standalone on the user's own project (CLI `jgengine editor`, desktop app, or any React host). Ships a slim strip to open a world file and pull in an asset folder; both are also settable up front through props.
+- `StandaloneAsset` (interface): interface StandaloneAsset — Shared model-import helpers used by the standalone editor strip and the in-game Content Browser. Host-agnostic and free of React/shell so unit tests can exercise the importer without a DOM or three.
+- `StandaloneEditor` (function): function StandaloneEditor({ sceneId = "standalone", scene, assets, world, save, importAsset = importAssetToHost, hidePickers = false, }: StandaloneEditorProps): React.JSX.Element — The scene editor, mounted over a blank gameless world instead of a game — the same `EditorApp` every jgengine game ships, usable standalone on the user's own project (CLI `jgengine editor`, desktop app, or any React host). Ships a slim strip to open a world file and pull in an asset folder; both are also settable up front through props.
 - `StandaloneEditorProps` (interface): interface StandaloneEditorProps — Props for the gameless scene editor — everything optional so it boots on a blank world with nothing wired.
-- `blankWorld` (function): function blankWorld(seed = "standalone"): EnvironmentWorldFeature — The default flat-ground world the standalone editor opens on when the host supplies none.
+- `blankWorld` (function): function blankWorld(_seed = "standalone"): EnvironmentWorldFeature — The default flat-ground authoring canvas the standalone editor opens on when the host supplies none. Deliberately thin — bare sculptable ground under a clear default sky. Dressing (sky look, foliage scatter, props) is what the author adds here, written into the scene document; it is never pre-baked into the canvas. The `seed` parameter is legacy and unused.
 - `createBlankPlayable` (function): function createBlankPlayable(options: BlankPlayableOptions = {}): PlayableGame — Builds a minimal gameless `PlayableGame` — a flat world plus an asset catalog — for the editor to mount over.
 - `downloadSaver` (function): function downloadSaver(filename = "editor.scene.json"): EditorSaveFn — A save fn that hands the scene JSON back to the browser as a downloaded file — the exit path when no dev server is listening.
 
 ## @jgengine/editor/TerrainPanel
 
-- `TerrainPanel` (function): function TerrainPanel({ session, ui }: { session: EditorSession; ui: EditorUiStore }): React.JSX.Element — The terrain-tool panel: create/clear the heightfield and drive the sculpt/paint controls.
+- `TerrainPanel` (function): function TerrainPanel({ session, ui, api }: { session: EditorSession; ui: EditorUiStore; api: EditorHostApi }): React.JSX.Element — The terrain-tool panel: create/clear the heightfield and drive the sculpt/paint controls.
 
 ## @jgengine/editor/TerrainReadout
 
@@ -412,6 +557,11 @@
 - `runAgentTurn` (function): function runAgentTurn(options: { api: EditorHostApi; endpoint: AgentEndpoint; history: readonly AgentChatMessage[]; userMessage: string; maxRounds?: number; now?: () => number; }): Promise<AgentTurnResult> — Runs one user message against an agent endpoint: injects live editor context via `packAgentContext`, executes tool calls through `routeToolCall` (shared undo), and returns transcript + patch entries the human can reverse with `undoAgentPatch`.
 - `undoAgentPatch` (function): function undoAgentPatch(api: EditorHostApi, patches: readonly AgentPatchEntry[], patchId: string): { ok: true; patches: AgentPatchEntry[] } | { ok: false; error: string } — Undoes one agent patch when it is still the top of the session undo stack. Newer live agent patches must be undone first; returns the updated list immutably.
 
+## @jgengine/editor/assetImport
+
+- `AssetImporter` (type): type AssetImporter = (file: File) => Promise<StandaloneAsset | null> — Persists a dropped model file through the editor host so it survives reload as a durable catalog asset, returning the host-assigned id/url (which the manifest scan re-lists on reload). Resolves `null` when no host is listening — a plain browser mount with no dev server — so the caller can fall back to a blob URL.
+- `StandaloneAsset` (interface): interface StandaloneAsset — Shared model-import helpers used by the standalone editor strip and the in-game Content Browser. Host-agnostic and free of React/shell so unit tests can exercise the importer without a DOM or three.
+
 ## @jgengine/editor/chromeFields
 
 - `NumberField` (function): function NumberField({ label, value, onCommit, step = 1, }: { label: string; value: number; onCommit: (value: number) => void; step?: number; }): React.JSX.Element — ⚠ undocumented
@@ -423,6 +573,67 @@
 - `INPUT` (const): const INPUT: "rounded-md border border-white/10 bg-black/40 px-2 py-1 outline-none transition-colors placeholder:text-neutral-600 focus:border-cyan-400/60 focus:bg-black/60" — ⚠ undocumented
 - `MICRO` (const): const MICRO: "text-[9px] font-semibold uppercase tracking-[0.14em] text-neutral-500" — ⚠ undocumented
 
+## @jgengine/editor/handlers
+
+- `EDITOR_RPC_HANDLERS` (const): const EDITOR_RPC_HANDLERS: HandlerTable — The complete method → handler dispatch table. Spreading the per-domain tables into a value typed `HandlerTable` is the compile-time completeness check: if any union method lacks a handler (or a domain misspells one), this assignment fails to type-check.
+- `HandlerContext` (interface): interface HandlerContext — Everything a per-domain RPC handler needs from the host. Mutable host state (focus, mode, play control, assets, visibility, perf) is reached through `api`'s getters/setters so handlers stay closure-free and independently testable; `dispatchGuarded` and the catalog lookups are threaded in because they are built once when the host is constructed.
+
+## @jgengine/editor/handlers/catalogs
+
+- `catalogHandlers` (const): const catalogHandlers: Pick< HandlerTable, | "list_catalogs" | "get_catalog_entry" | "set_catalog_entry" | "add_catalog_entry" | "remove_catalog_entry" | "add_catalog" | "remove_catalog" | "set_catalog_schema" > — Gameplay data catalog verbs (list / get / merge-patch / add / remove rows).
+
+## @jgengine/editor/handlers/collections
+
+- `collectionHandlers` (const): const collectionHandlers: Pick< HandlerTable, | "list_collections" | "create_collection" | "rename_collection" | "delete_collection" | "set_collection_members" | "add_to_collection" | "remove_from_collection" | "set_collection_flags" | "select_collection" > — Named collection / selection-set verbs.
+
+## @jgengine/editor/handlers/context
+
+- `DispatchOutcome` (interface): interface DispatchOutcome — Outcome of a guarded dispatch: whether it mutated the session, plus the resulting state.
+- `HandlerContext` (interface): interface HandlerContext — Everything a per-domain RPC handler needs from the host. Mutable host state (focus, mode, play control, assets, visibility, perf) is reached through `api`'s getters/setters so handlers stay closure-free and independently testable; `dispatchGuarded` and the catalog lookups are threaded in because they are built once when the host is constructed.
+- `HandlerFor` (type): type HandlerFor<M extends EditorBridgeRequest["method"]> = ( ctx: HandlerContext, request: Extract<EditorBridgeRequest, { method: M }>, ) => EditorBridgeResponse — One method's handler, with `request` narrowed to that method's union member.
+- `HandlerTable` (type): type HandlerTable = { [M in EditorBridgeRequest["method"]]: HandlerFor<M> } — The full method → handler map. Spreading the per-domain tables into a value of this type is the lockstep guarantee that every union method has exactly one handler: a missing verb fails to compile.
+
+## @jgengine/editor/handlers/document
+
+- `documentHandlers` (const): const documentHandlers: Pick< HandlerTable, | "editor_status" | "set_mode" | "perf_report" | "list_layers" | "list_selection" | "get_marker" | "get_volume" | "set_transform" | "set_volume" | "set_path" | "set_marker" | "set_note" | "set_meta" | "apply_preset" | "select" | "clear_selection" | "camera… — Document, selection, camera, mode, asset placement, and status verbs.
+
+## @jgengine/editor/handlers/grids
+
+- `gridHandlers` (const): const gridHandlers: Pick< HandlerTable, | "list_grids" | "get_grid_cell" | "add_grid_layer" | "remove_grid_layer" | "set_grid_layer" | "paint_grid_cells" | "fill_grid_rect" | "flood_fill_grid" | "resize_grid_layer" | "import_grid" > — Grid/tile layer verbs — create, edit, paint, fill, and import.
+
+## @jgengine/editor/handlers/hierarchy
+
+- `hierarchyHandlers` (const): const hierarchyHandlers: Pick< HandlerTable, | "set_parent" | "hierarchy" | "list_prefabs" | "create_prefab" | "insert_prefab" | "detach_prefab_instance" | "delete_prefab" > — Parent/child hierarchy and prefab library verbs.
+
+## @jgengine/editor/handlers/minimap
+
+- `minimapHandlers` (const): const minimapHandlers: Pick<HandlerTable, "bake_minimap"> — Bake the authored terrain into a stored minimap PNG (#1036). Composes the live viewport's base ground field with the document's sculpt snapshot, rasterizes it top-down via the pure core bake, and stores `{ background, bounds }` on `document.minimap` as an undoable edit — runtime then feeds those straight into the `Minimap`/`WorldMap` props with no re-raster. Needs the mounted viewport's composed sampler, so it is a live-editor-only action, not a headless CLI verb.
+
+## @jgengine/editor/handlers/runtime
+
+- `runtimeHandlers` (const): const runtimeHandlers: Pick< HandlerTable, | "push_document_patch" | "pull_document_patches" | "document_revision" | "push_runtime_delta" | "pull_runtime_deltas" | "runtime_snapshot" | "runtime_summary" | "runtime_get" | "runtime_set" | "runtime_pause" | "runtime_resume" | "runtime_step" | "set_runt… — Live-sync document patches, the ephemeral runtime reverse channel, and play-mode poke verbs.
+
+## @jgengine/editor/handlers/streets
+
+- `streetsHandlers` (const): const streetsHandlers: Pick<HandlerTable, "generate_streets"> — Document, selection, camera, mode, asset placement, and status verbs.
+
+## @jgengine/editor/handlers/terrain
+
+- `terrainHandlers` (const): const terrainHandlers: Pick< HandlerTable, | "create_terrain" | "sculpt_terrain" | "terrain_summary" | "paint_terrain" | "fill_terrain" | "auto_paint" | "terrain_materials" | "terrain_layers" | "set_terrain_layers" | "blend_terrain" | "convert_scatter" | "add_foliage" | "scatter_summary" > — Sculpt heightfield, material painting, terrain layers, and foliage/scatter verbs.
+
+## @jgengine/editor/listDocumentTriggers
+
+- `DocumentTriggerBinding` (interface): interface DocumentTriggerBinding — One on/action binding shown on a document trigger row.
+- `DocumentTriggerEntry` (interface): interface DocumentTriggerEntry — A marker or volume that owns one or more authored triggers, with a display label for the scripting workspace list.
+- `DocumentTriggersSource` (interface): interface DocumentTriggersSource — Document slice the list helper needs — `EditorDocument` satisfies this structurally.
+
+## @jgengine/editor/materialAssignments
+
+- `MaterialAssignmentFilter` (type): type MaterialAssignmentFilter = | "all" | "assigned" | "unassigned" | { materialId: string } — Filter for {@link filterMaterialAssignments}.
+- `MaterialAssignmentRow` (interface): interface MaterialAssignmentRow — One object row in the materials workspace browser.
+- `MaterialDocumentSlice` (interface): interface MaterialDocumentSlice — Minimal document slice the materials inventory needs.
+- `MaterialObjectKind` (type): type MaterialObjectKind = "marker" | "volume" | "path" — Document-wide material assignment inventory for the Materials workspace. Reads real `meta.materialId` stamps from placeables — no thumbnails or faked previews.
+
 ## @jgengine/editor/mcp/bridgeServer
 
 - `EditorBridgeServer` (interface): interface EditorBridgeServer — A running editor bridge server: its bound port, URL, and a stop handle.
@@ -434,7 +645,15 @@
 
 ## @jgengine/editor/mcp/cli
 
-- `EditorCliOptions` (type): type EditorCliOptions = { gameId: string; port: number; rpcSource: RpcPayloadSource | null; serve: boolean; stdio: boolean; } — Parsed CLI flags for the headless editor control plane.
+- `EditorCliOptions` (type): type EditorCliOptions = { gameId: string; port: number; rpcSources: RpcPayloadSource[]; save: boolean; serve: boolean; stdio: boolean; } — Parsed CLI flags for the headless editor control plane.
+- `SaveSceneResult` (type): type SaveSceneResult = { ok: true; saved: string } | { ok: false; error: string } — Result of a `--save` write-back: the path written, or why nothing was written.
+
+## @jgengine/editor/mcp/fieldSpec
+
+- `RPC_FIELD_SCHEMAS` (const): const RPC_FIELD_SCHEMAS: Record<EditorBridgeRequest["method"], readonly RpcFieldSpec[]> — Per-method field type table — the single source of truth for the RPC boundary. A field listed here is type-checked when present (see `decodeEditorBridgeRequest`); existence is left to `EditorHostApi.handle` (whose per-method guards return honest `ok:false` diagnostics for missing/unknown targets). Type-checking presented fields is what keeps a fuzzed value — a string where a number belongs, a scalar where an object belongs — from reaching a live session uncoerced. Unknown extra fields are ignored so a superset payload stays forward-compatible.
+- `RpcFieldKind` (type): type RpcFieldKind = "string" | "number" | "boolean" | "string[]" | "object" | "object[]" | "vec3" | "value" — The value type a request field is expected to carry.
+- `RpcFieldSpec` (interface): interface RpcFieldSpec — One field's expected shape in a request; `oneOf`/`nullable`/`required`/`of` refine the check.
+- `buildInputSchema` (function): function buildInputSchema(method: EditorBridgeRequest["method"]): Record<string, unknown> — Generates the MCP tool `inputSchema` for a method from its {@link RPC_FIELD_SCHEMAS} entry.
 
 ## @jgengine/editor/mcp/loadGameCatalogs
 
@@ -455,7 +674,7 @@
 
 - `DecodeRpcRequestResult` (type): type DecodeRpcRequestResult = | { ok: true; request: EditorBridgeRequest } | { ok: false; errors: RpcRequestDiagnostic[] } — Result of {@link decodeEditorBridgeRequest}: a request whose `method` is a real one, or the diagnostic that rejected it.
 - `RpcRequestDiagnostic` (interface): interface RpcRequestDiagnostic — One field-level failure surfaced while decoding an untrusted RPC request.
-- `decodeEditorBridgeRequest` (function): function decodeEditorBridgeRequest(raw: unknown): DecodeRpcRequestResult — Validates an untrusted JSON-decoded RPC payload (from `--rpc` or the HTTP bridge) before it reaches `EditorHostApi.handle`: confirms it is a plain object carrying a known `method` name. Per-method field shape is still enforced by `handle`'s own dispatch, but a garbled or unknown-method payload is rejected here with a path-specific diagnostic instead of flowing through on a blind cast.
+- `decodeEditorBridgeRequest` (function): function decodeEditorBridgeRequest(raw: unknown): DecodeRpcRequestResult — Validates an untrusted JSON-decoded RPC payload (from `--rpc`, the HTTP bridge, or an agent tool call) before it reaches `EditorHostApi.handle`: confirms it is a plain object carrying a known `method`, then type-checks every field the method understands against {@link RPC_FIELD_SCHEMAS}. A garbled method, or a field whose value is the wrong type (a string where a number belongs, a scalar where an object belongs), is rejected here with a path-specific diagnostic instead of flowing into a live session on a blind cast. Missing fields and unknown extra fields are left for `handle` to interpret so the boundary stays forward-compatible.
 
 ## @jgengine/editor/mcp/stdioServer
 
@@ -466,6 +685,14 @@
 - `EDITOR_MCP_TOOLS` (const): const EDITOR_MCP_TOOLS: readonly EditorMcpTool[] — Full set of MCP tools an agent can call to drive the live scene editor.
 - `EditorMcpTool` (interface): interface EditorMcpTool — One MCP tool descriptor — same verbs as the in-browser host RPC.
 
+## @jgengine/editor/networkSnapshot
+
+- `EditorNetworkAdapterKind` (type): type EditorNetworkAdapterKind = MultiplayerAdapterConfig["kind"] | "unknown" — Transport kind declared by the game, or `"unknown"` when the config is unreadable.
+- `EditorNetworkPresenceActor` (interface): interface EditorNetworkPresenceActor — One online actor from a host-supplied presence feed. Fields mirror {@link PresencePoseRow} so hosts can forward backend rows without inventing shape.
+- `EditorNetworkPresenceInput` (interface): interface EditorNetworkPresenceInput — Optional live presence/session injection from the editor host.
+- `EditorNetworkSession` (interface): interface EditorNetworkSession — Optional live session identity when a multiplayer backend is attached. Omit entirely when the host has no session — the panel reports offline honestly.
+- `EditorNetworkSnapshot` (interface): interface EditorNetworkSnapshot — Host-facing network inspection payload for the editor Network workspace.
+
 ## @jgengine/editor/outlinerModel
 
 - `OutlinerFlatRow` (type): type OutlinerFlatRow = | { type: "group"; key: string; kind: string; total: number; collapsed: boolean } | { type: "kindItem"; key: string; kind: string; label: string; ids: string[] } | { type: "treeItem"; key: string; id: string; label: string; kind: string; depth: number; hasChildren: boolean } — One rendered outliner line — a kind header, a deduped kind row, or a hierarchy tree node.
@@ -494,11 +721,162 @@
 - `EditorHostApi` (interface): interface EditorHostApi — The live editor's global control surface — session, visibility, camera focus, assets, mode, RPC.
 - `EditorKindVisibility` (interface): interface EditorKindVisibility — Per-kind show/hide flags for the editor's layer panel.
 - `EditorPerfSample` (interface): interface EditorPerfSample — Rolling frame-rate sample published by the in-canvas PerfProbe.
-- `EditorRunMode` (type): type EditorRunMode = "edit" | "walk" | "play" — How the editor hosts the game: frozen placement view, roamable world, or the real game.
+- `EditorRunMode` (type): type EditorRunMode = "edit" | "walk" | "play" | "hud" — How the editor hosts the game: frozen placement view, roamable world, the real game, or HUD-layout authoring.
 - `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.
 - `installEditorHost` (function): function installEditorHost(api: EditorHostApi): () => void — Publishes an editor host globally so devtools and MCP agents can reach it; returns a cleanup fn.
 
+## @jgengine/editor/shell/BottomDock
+
+- `BottomDock` (function): function BottomDock({ tab, onSelectTab, onClose, assets, session, api, consoleStore, perfHistory, browserView, onSetBrowserView, onPlaceAsset, onImportModels, importBusy, }: { tab: BottomDockTab; onSelectTab: (tab: BottomDockTab) => void; onClose: () => void; assets: readonly EditorAssetEntry[]; ses… — Tabbed bottom dock: Content Browser, Console, Profiler, Animation (path flythrough scrub), and the AI Assistant. Only the active tab's panel mounts, so hidden tools cost nothing per frame.
+
+## @jgengine/editor/shell/CommandPalette
+
+- `CommandPalette` (function): function CommandPalette({ commands, onClose, initialQuery = "", }: { commands: readonly PaletteCommand[]; onClose: () => void; /** Pre-filled filter (e.g. "add " to open straight into placement commands). */ initialQuery?: string; }): React.JSX.Element — Modal command palette (Ctrl/Cmd+K): fuzzy-filters every executable editor command (plus scene object jump rows), surfaces recent commands when the query is empty, and runs the highlighted entry on Enter. Esc or backdrop click cancels without side effects.
+
+## @jgengine/editor/shell/ConsolePanel
+
+- `ConsolePanel` (function): function ConsolePanel({ store }: { store: EditorConsoleStore }): React.JSX.Element — Console dock tab over the real editor event log — notifications, save/import results, RPC and agent errors. Severity filters, counts, search, timestamps, and clear; no fabricated entries.
+
+## @jgengine/editor/shell/ContentBrowser
+
+- `ContentBrowser` (function): function ContentBrowser({ assets, session, onPlace, view, onSetView, onImportModels, importBusy = false, }: { assets: readonly EditorAssetEntry[]; session: EditorSession; onPlace: (entry: EditorAssetEntry) => void; view: BrowserViewMode; onSetView: (view: BrowserViewMode) => void; /** When set, enab… — Content Browser dock tab: folder rail + searchable asset grid/list over the game's real asset catalog, plus the terrain material palette (drag chips onto objects or the viewport). Assets are draggable into the viewport for placement (and still double-click / Place). Model cards with a URL get a real offscreen-GLB thumbnail (cached); catalog/marker rows and failed loads keep typed glyphs — never a fabricated screenshot. Import reuses the standalone editor's host importer.
+
+## @jgengine/editor/shell/HierarchyPanel
+
+- `HierarchyPanel` (const): const HierarchyPanel: React.MemoExoticComponent<({ session, api, onAdd, onRowContextMenu, }: { session: EditorSession; api: EditorHostApi; onAdd: () => void; onRowContextMenu?: ((event: { clientX: number; clientY: number; }, id: string) => void) | undefined; }) => React.JSX.Element> — Redesigned world outliner: searchable, virtualized, kind-iconed rows generated from the live document. Group headers carry real per-kind visibility toggles (the editor's layer system); rows expose per-object eye/lock toggles (`setObjectFlags` → document `hidden`/`locked`) and show a lock affordance when a locked collection also owns the id. Tree view supports drag-and-drop reparenting through the existing `set_parent` RPC. Keyboard navigation uses a single tab stop on the list (roving active row via `aria-activedescendant`; arrows / Home / End / Enter / F2), double-click rename, and row context menus (frame / duplicate / delete / prefab / parent to… / unparent) are supported. Selector-subscribed and memoized, so UI-only churn never rerenders it.
+- `OBJECT_DRAG_MIME` (const): const OBJECT_DRAG_MIME: "application/x-jgengine-editor-object" — HTML5 drag payload for hierarchy reparenting via `set_parent`.
+
+## @jgengine/editor/shell/ProfilerPanel
+
+- `ProfilerPanel` (function): function ProfilerPanel({ history }: { history: PerfHistoryStore }): React.JSX.Element — Profiler dock tab over the real {@link PerfProbe} sample history: frame-time graph, current and average values, authoring-cost series when the probe reports one, sim/outside budget when `devtools.frame` has recorded frames, and JS heap memory when the browser exposes `performance.memory`. Series the host cannot measure are omitted entirely rather than fabricated.
+
+## @jgengine/editor/shell/SceneToolbar
+
+- `ADD_VOLUME_ENTRIES` (const): const ADD_VOLUME_ENTRIES: readonly { label: string; tool: PlacementTool }[] — Volume placement entries offered by the Add menu.
+- `SceneToolbar` (function): function SceneToolbar({ tool, gizmoMode, gizmoSpace, gizmoPivot, snapMode, gridSize, rotationSnapDeg, scaleSnap, cameraProjection, showGrid, showContours, showSurfaceGrid, showElevation, placementActive, onSetTool, onSetGizmoMode, onSetGizmoSpace, onSetGizmoPivot, onSetSnapMode, onSetGridSize, onSet… — Contextual scene toolbar under the app bar: tools, gizmo modes, gizmo space, pivot, snapping, viewport overlays, framing, projection, and the Add menu.
+
+## @jgengine/editor/shell/StatusBar
+
+- `StatusBar` (function): function StatusBar({ api, history, objects, foliage, selectionCount, autosave, }: { api: EditorHostApi; history: PerfHistoryStore; objects: number; foliage: number; selectionCount: number; autosave: boolean; }): React.JSX.Element — Bottom status strip: readiness, scene stats, live perf pill, autosave state, and camera hints. Owns its own perf poll (and the profiler history feed) so the 500ms tick never rerenders the shell.
+- `formatTriangles` (function): function formatTriangles(count: number): string — Compact triangle-count formatting (1.2M / 340k).
+- `usePerfSample` (function): function usePerfSample(api: EditorHostApi, history?: PerfHistoryStore): EditorPerfSample | null — Shared editor-host perf poll: samples on an interval and feeds the profiler history.
+
+## @jgengine/editor/shell/TopAppBar
+
+- `TopAppBar` (function): function TopAppBar({ gameId, onExitToGame, dirty, saveState, lastSavedAt = null, saveAvailable, saveError, canUndo, canRedo, onUndo, onRedo, onSave, onPlay, onWalk, onHud, onImport, onExport, onCopyJson, onOpenPalette, onToggleHelp, onResetLayout, }: { gameId: string; /** When set (editor summoned o… — Global application bar: identity + save state on the left, command palette in the center, history / run controls / document actions on the right. Pause and Step stay disabled in edit mode; Play mode mounts {@link PlayModeBar}, which wires the same controls to the runtime pause/step RPCs so mode switches keep shell chrome.
+- `TopBarSaveState` (type): type TopBarSaveState = "idle" | "saving" | "saved" | "error" — Document save lifecycle mirrored from `useDocumentSave`.
+
+## @jgengine/editor/shell/ViewportOverlays
+
+- `OrientationWidget` (const): const OrientationWidget: React.MemoExoticComponent<() => React.JSX.Element> — Bottom-left orientation axis widget. Reads the camera basis published by the in-canvas probe on its own rAF loop and mutates SVG attributes directly, so orbiting never rerenders React.
+- `PerformanceOverlay` (const): const PerformanceOverlay: React.MemoExoticComponent<({ api }: { api: EditorHostApi; }) => React.JSX.Element | null> — Top-left viewport performance readout backed by the real in-canvas {@link PerfProbe} samples. Rows without data (no sample yet) simply don't render — nothing is fabricated.
+- `ViewportUtilityPanel` (function): function ViewportUtilityPanel({ document, api, selectionCount, }: { document: EditorDocument; api: EditorHostApi; selectionCount: number; }): React.JSX.Element — Top-right collapsible viewport utility panel: real minimap from `document.minimap` when baked (via `bake_minimap` RPC — never a fake image), plus per-kind object counts and framing actions.
+
+## @jgengine/editor/shell/WorkspaceRail
+
+- `WORKSPACES` (const): const WORKSPACES: readonly RailEntry[] — Rail order and support map. Unsupported modes are visible but disabled — never fake panels.
+- `WorkspaceRail` (function): function WorkspaceRail({ active, onSelect, }: { active: EditorWorkspace; onSelect: (workspace: EditorWorkspace) => void; }): React.JSX.Element — Narrow left workspace rail. Supported modes activate their home panels; planned modes are disabled with an explanatory tooltip so nothing pretends to work.
+
+## @jgengine/editor/shell/cameraTelemetry
+
+- `CameraTelemetry` (interface): interface CameraTelemetry — Per-frame camera orientation channel between the in-canvas probe and the DOM orientation widget. Deliberately a mutable record, not React state: the probe writes every frame and the widget reads on its own rAF loop, applying styles directly — zero shell rerenders.
+- `createCameraTelemetry` (function): function createCameraTelemetry(): CameraTelemetry — Creates a telemetry record seeded at rest (identity basis).
+- `getCameraTelemetry` (function): function getCameraTelemetry(): CameraTelemetry — Shared telemetry singleton — probe and widget may mount in different React trees.
+
+## @jgengine/editor/shell/commandRegistry
+
+- `PaletteCommand` (interface): interface PaletteCommand — One executable command-palette entry.
+- `PaletteContext` (interface): interface PaletteContext — Everything the palette can drive — thin callbacks over existing editor systems.
+- `PaletteObjectTarget` (interface): interface PaletteObjectTarget — A scene object the palette can jump to by name/id.
+- `buildPaletteCommands` (function): function buildPaletteCommands(ctx: PaletteContext): PaletteCommand[] — Builds the full palette command list from live editor capabilities — no dead entries.
+- `filterPaletteCommands` (function): function filterPaletteCommands(commands: readonly PaletteCommand[], query: string, recentIds: readonly string[] = []): PaletteCommand[] — Case-insensitive filter over title, group, and keywords. With an empty query, recent commands (that still exist) float to the top under a virtual order — the caller groups them visually.
+
+## @jgengine/editor/shell/consoleStore
+
+- `CONSOLE_CAPACITY` (const): const CONSOLE_CAPACITY: 500 — Entries kept before the oldest are dropped.
+- `ConsoleEntry` (interface): interface ConsoleEntry — One recorded editor event.
+- `ConsoleSeverity` (type): type ConsoleSeverity = "info" | "warning" | "error" — Bounded editor event log backing the Console dock tab. Only real editor events are recorded — notifications, save/import/export results, RPC and agent errors — never fabricated runtime logs.
+- `EditorConsoleStore` (interface): interface EditorConsoleStore — Subscribable, bounded editor event log.
+- `createEditorConsoleStore` (function): function createEditorConsoleStore(now: () => number = () => Date.now()): EditorConsoleStore — Creates the editor console store. `now` is injectable for tests.
+
+## @jgengine/editor/shell/fields
+
+- `AxisNumberField` (function): function AxisNumberField({ axis, label, value, onCommit, step = 0.1, precision = 3, disabled = false, mixed = false, }: { /** Axis coloring; omit for a neutral field. */ axis?: "x" | "y" | "z"; label: string; value: number; onCommit: (value: number) => void; step?: number; precision?: number; disabl… — Polished numeric field with an axis-colored label chip. The whole field is a drag-scrub surface (not just the chip): horizontal pointer-drag adjusts by `step` per few pixels while Alt/Option or double-click focuses the input for precise typing. The input commits finite values on change and re-normalizes its text on blur. Invalid text never commits.
+- `FieldRow` (function): function FieldRow({ label, children, title }: { label: string; children: React.ReactNode; title?: string }): React.JSX.Element — Labeled row wrapper aligning a caption with one or more fields.
+- `SectionAction` (function): function SectionAction({ label, onClick, active = false, disabled = false, children, }: { label: string; onClick: () => void; active?: boolean; disabled?: boolean; children: React.ReactNode; }): React.JSX.Element — Small ghost action used inside section headers (reset, link).
+- `TextField` (function): function TextField({ label, value, placeholder, onCommit, }: { label: string; value: string; placeholder?: string; onCommit: (value: string) => void; }): React.JSX.Element — Compact text input row used by the inspector header and component cards.
+
+## @jgengine/editor/shell/glbThumbnailCache
+
+- `ThumbnailState` (interface): interface ThumbnailState — Cache entry for one asset's thumbnail: status plus the data URL when ready.
+- `ThumbnailStatus` (type): type ThumbnailStatus = "idle" | "loading" | "ready" | "error" — Lifecycle of one GLB thumbnail render: idle → loading → ready, or error.
+
+## @jgengine/editor/shell/icons
+
+- `Icon` (function): function Icon({ name, size = 14, ...rest }: { name: IconName; size?: number } & SVGProps<SVGSVGElement>): React.JSX.Element — One 16px stroke icon from the shell's internal set; sized via the `size` prop.
+- `IconName` (type): type IconName = | "cursor" | "move" | "rotate" | "scale" | "terrain" | "brush" | "grid" | "magnet" | "frame" | "camera" | "eye" | "eyeOff" | "lock" | "unlock" | "search" | "filter" | "plus" | "folder" | "folderOpen" | "cube" | "pin" | "sphere" | "spline" | "note" | "play" | "pause" | "step" | "stop"… — Internal editor icon set: compact 16px stroke glyphs drawn in-repo so the shell has one consistent icon language without adding a dependency. Every glyph is original geometry.
+- `kindIcon` (function): function kindIcon(kind: string): IconName — Icon assigned to a scene-object kind for hierarchy rows and inspector headers.
+
+## @jgengine/editor/shell/layoutStore
+
+- `BottomDockTab` (type): type BottomDockTab = "content" | "console" | "profiler" | "animation" | "assistant" — Bottom dock tool tabs.
+- `BrowserViewMode` (type): type BrowserViewMode = "grid" | "list" — Content-browser presentation density.
+- `DEFAULT_LAYOUT` (const): const DEFAULT_LAYOUT: ShellLayoutState — Default shell layout, matching the reference composition.
+- `EditorWorkspace` (type): type EditorWorkspace = | "scene" | "terrain" | "assets" | "materials" | "scripting" | "animation" | "audio" | "lighting" | "ai" | "multiplayer" — Persistent editor-shell layout state: which workspace is active, which panels are open, their sizes, and dock tab selections. Kept apart from `uiStore` (transient interaction state) so layout preferences survive reloads without entangling gizmo/placement churn. Persistence is throttled so drag-resizing never writes localStorage per pointer move.
+- `InspectorTab` (type): type InspectorTab = "inspector" | "components" | "materials" — Inspector header tabs.
+- `LAYOUT_LIMITS` (const): const LAYOUT_LIMITS: { readonly leftWidth: { readonly min: 220; readonly max: 420; }; readonly rightWidth: { readonly min: 260; readonly max: 460; }; readonly bottomHeight: { readonly min: 160; readonly max: 480; }; } — Bounds applied to persisted/live panel sizes so restored layouts can never crush the viewport.
+- `LAYOUT_PERSIST_DELAY_MS` (const): const LAYOUT_PERSIST_DELAY_MS: 400 — How long resize/patch churn batches before one localStorage write.
+- `LeftDockPage` (type): type LeftDockPage = "hierarchy" | "collections" | "prefabs" | "catalogs" — Left dock content pages (hierarchy plus the existing data panels).
+- `ShellLayoutState` (interface): interface ShellLayoutState — The persisted + live shell layout state.
+- `ShellLayoutStore` (interface): interface ShellLayoutStore — Subscribable store over {@link ShellLayoutState} with clamped resize helpers.
+- `createShellLayoutStore` (function): function createShellLayoutStore(gameId: string): ShellLayoutStore — Creates the shell layout store, seeded from localStorage when available.
+- `normalizeLayout` (function): function normalizeLayout(raw: unknown): ShellLayoutState — Normalizes any partially-persisted layout into a valid state (sizes clamped, unions guarded).
+
+## @jgengine/editor/shell/pathFlythrough
+
+- `ScrubbablePath` (interface): interface ScrubbablePath — A scrubbable scene path — real document polylines with enough points to sample.
+
+## @jgengine/editor/shell/perfHistory
+
+- `FrameBudgetFields` (interface): interface FrameBudgetFields — Optional sim / outside / phase fields derived from real frame-tracker stats (never invented).
+- `FrameBudgetStatsInput` (interface): interface FrameBudgetStatsInput — Minimal frame-stats shape consumed when folding core `devtools.frame.stats()` into a sample.
+- `PERF_HISTORY_CAPACITY` (const): const PERF_HISTORY_CAPACITY: 240 — Samples retained (~2 minutes at the 500ms poll).
+- `PerfHistoryStore` (interface): interface PerfHistoryStore — Rolling history of real {@link EditorPerfSample}s for the Profiler dock tab's frame-time graph. Fed by the same 500ms host poll the toolbar pill uses; never fabricates values. Kept outside React state so recording continues while the profiler tab is closed without rerendering anything.
+- `createPerfHistoryStore` (function): function createPerfHistoryStore(): PerfHistoryStore — Creates the rolling perf-sample history store.
+- `seriesAverage` (function): function seriesAverage(values: readonly number[]): number — Mean of a numeric series, 0 for empty input.
+- `sparklinePoints` (function): function sparklinePoints(values: readonly number[], width: number, height: number, maxValue: number): string — Builds an SVG polyline `points` string for a series scaled into a width×height box.
+
+## @jgengine/editor/shell/theme
+
+- `APP_BG` (const): const APP_BG: "bg-[#0b0d10]" — Editor shell design tokens as Tailwind class constants. One place owns the layered dark theme (app < panel < control elevation), text scale, and interaction states so every shell component reads identically. Class strings are complete literals so the host app's Tailwind scan keeps them.
+- `AXIS_COLORS` (const): const AXIS_COLORS: Record<"x" | "y" | "z", { text: string; bar: string }> — Per-axis accent colors for transform fields (X red, Y green, Z blue — gizmo-matched).
+- `BORDER` (const): const BORDER: "border-white/[0.07]" — Low-contrast neutral border used between shell regions.
+- `CONTROL` (const): const CONTROL: "rounded-[5px] border border-white/[0.07] bg-[#191d24] text-neutral-300 transition-colors hover:bg-[#1f242d] hover:text-neutral-100 outline-none focus-visible:ring-2 focus-visible:ring-cyan-400/60 focus-visible:ring-offset-0" — Base interactive control: compact, subtle border, hover elevation.
+- `CONTROL_ACTIVE` (const): const CONTROL_ACTIVE: "border-cyan-400/40 bg-cyan-500/15 text-cyan-200 hover:bg-cyan-500/20" — Active/selected control state — restrained cyan.
+- `CONTROL_BG` (const): const CONTROL_BG: "bg-[#191d24]" — Elevated control surface — inputs, chips, dropdowns.
+- `FLOAT_BG` (const): const FLOAT_BG: "bg-[#14171d]" — Floating layer surface — menus, palettes, popovers.
+- `FOCUS_RING` (const): const FOCUS_RING: "outline-none focus-visible:ring-2 focus-visible:ring-cyan-400/60 focus-visible:ring-offset-0" — Shared focus ring for keyboard navigation on interactive controls.
+- `INPUT_CLS` (const): const INPUT_CLS: "rounded-[5px] border border-white/[0.08] bg-black/40 text-[12px] text-neutral-200 outline-none transition-colors placeholder:text-neutral-600 focus:border-cyan-400/50 focus:bg-black/60 outline-none focus-visible:ring-2 focus-visible:ring-cyan-400/60 focus-visible:ring-offset-0" — Text input styling shared across shell panels.
+- `MICRO_LABEL` (const): const MICRO_LABEL: "text-[10px] font-semibold uppercase tracking-[0.12em] text-neutral-500" — Micro uppercase section label.
+- `NUMERIC` (const): const NUMERIC: "tabular-nums" — Tabular numerals for transforms, metrics, and timing readouts.
+- `PANEL_BG` (const): const PANEL_BG: "bg-[#111318]" — Panel surface — one elevation step above the app background.
+- `TEXT` (const): const TEXT: "text-[12px] text-neutral-300" — Standard control text row.
+- `TEXT_MUTED` (const): const TEXT_MUTED: "text-[11px] text-neutral-500" — Muted metadata text.
+
+## @jgengine/editor/shell/ui
+
+- `CollapsibleSection` (function): function CollapsibleSection({ title, icon, open, onToggle, children, trailing, tone, }: { title: string; icon?: IconName; open: boolean; onToggle: () => void; children: ReactNode; trailing?: ReactNode; /** Optional accent color for the title icon. */ tone?: string; }): React.JSX.Element — Collapsible component card for the inspector and side panels.
+- `EmptyState` (function): function EmptyState({ icon, title, description, badge, children, }: { icon: IconName; title: string; description: string; badge?: string; children?: ReactNode; }): React.JSX.Element — Polished empty state used by unsupported workspaces and empty docks.
+- `IconButton` (function): function IconButton({ icon, label, onClick, active = false, disabled = false, size = 14, className = "", tone = "neutral", }: { icon: IconName; label: string; onClick?: () => void; active?: boolean; disabled?: boolean; size?: number; className?: string; tone?: "neutral" | "ghost"; }): React.JSX.Elem… — Icon-only control with a mandatory accessible name (tooltip + aria-label).
+- `Kbd` (function): function Kbd({ children }: { children: ReactNode }): React.JSX.Element — Keyboard-shortcut chip rendered inside buttons and menus.
+- `PanelHeading` (function): function PanelHeading({ children, trailing }: { children: ReactNode; trailing?: ReactNode }): React.JSX.Element — Micro uppercase heading used inside panels.
+- `PanelResizer` (function): function PanelResizer({ orientation, label, onResize, sign = 1, }: { orientation: "vertical" | "horizontal"; label: string; onResize: (delta: number) => void; sign?: 1 | -1; }): React.JSX.Element — Drag handle between shell regions. Pointer-drag resizes continuously; arrow keys resize in 16px steps for keyboard access. `sign` maps a positive pointer delta to a size increase.
+- `PanelTabs` (function): function PanelTabs<T extends string>({ tabs, active, onSelect, trailing, ariaLabel, }: { tabs: readonly { id: T; label: string; icon?: IconName; badge?: string | number }[]; active: T; onSelect: (id: T) => void; trailing?: ReactNode; ariaLabel: string; }): React.JSX.Element — Horizontal tab strip for dock panels (bottom dock, inspector tabs).
+- `Segmented` (function): function Segmented<T extends string>({ options, value, onChange, ariaLabel, disabled = false, }: { options: readonly SegmentedOption<T>[]; value: T; onChange: (value: T) => void; ariaLabel: string; disabled?: boolean; }): React.JSX.Element — Compact segmented control on the elevated-control surface with a cyan active segment.
+- `SegmentedOption` (interface): interface SegmentedOption<T extends string> — One choice within a {@link Segmented} control.
+- `ToolbarDivider` (function): function ToolbarDivider(): React.JSX.Element — Thin vertical divider between toolbar clusters.
+
 ## @jgengine/editor/terrainReadoutStore
 
 - `TerrainReadoutState` (interface): interface TerrainReadoutState — Live, transient terrain-readability feedback shared by the viewport overlay and the HUD legend.
@@ -507,14 +885,19 @@
 
 ## @jgengine/editor/uiStore
 
+- `CameraProjectionMode` (type): type CameraProjectionMode = "perspective" | "orthographic" — Editor viewport camera projection — perspective (default) or orthographic top-down-friendly view.
 - `DEFAULT_PAINT_SETTINGS` (const): const DEFAULT_PAINT_SETTINGS: PaintSettings — The terrain tool's default paint controls.
 - `DEFAULT_SCULPT_SETTINGS` (const): const DEFAULT_SCULPT_SETTINGS: SculptSettings — The terrain tool's default brush controls.
 - `EditorTool` (type): type EditorTool = "select" | "terrain" — Which top-level editor tool is active: object placement/selection, or terrain sculpting.
 - `EditorUiState` (interface): interface EditorUiState — Transient editor UI state shared between chrome, viewport, and gizmos.
 - `EditorUiStore` (interface): interface EditorUiStore — Subscribable store for the editor's transient UI state (gizmo, snapping, placement).
 - `GizmoMode` (type): type GizmoMode = "translate" | "rotate" | "scale" — Which transform gizmo is active for the current selection.
+- `GizmoPivot` (type): type GizmoPivot = "origin" | "center" | "median" — Where multi-select gizmo handles sit: - `origin` — primary selection (first selected id) - `center` — arithmetic mean of selected object positions - `median` — per-axis median of selected object positions
+- `GizmoSpace` (type): type GizmoSpace = "world" | "local" — Gizmo handle orientation: world axes, or the selection's local (yaw-rotated) axes.
 - `PaintSettings` (interface): interface PaintSettings — Live terrain material-paint controls driven by the terrain tool panel.
 - `PlacementTool` (type): type PlacementTool = | { tool: "marker"; kind: string } | { tool: "volume"; kind: string; shape: EditorVolumeShape } | { tool: "note" } | { tool: "path"; kind: string } — The active creation tool — what a viewport click places next.
+- `ROTATION_SNAP_CHOICES_DEG` (const): const ROTATION_SNAP_CHOICES_DEG: readonly number[] — Rotation snap increments (degrees) offered by the toolbar snap menu.
+- `SCALE_SNAP_CHOICES` (const): const SCALE_SNAP_CHOICES: readonly number[] — Scale snap increments offered by the toolbar snap menu.
 - `SculptSettings` (interface): interface SculptSettings — Live terrain-brush controls driven by the terrain tool panel.
 - `SnapMode` (type): type SnapMode = "ground" | "grid" | "off" — How gizmo drags land: stick to terrain height, quantize to a grid, or free.
 - `TERRAIN_MATERIALS` (const): const TERRAIN_MATERIALS: readonly TerrainMaterial[] — The default terrain paint palette (surface id → color) shared by the panel and the mesh.