@jgengine/core 0.10.0 → 0.12.0

package/dist/editor/index.d.ts

@@ -1,30 +1,122 @@
 /** The full authored scene: every marker, volume, path, and note for a game. */
 export type { EditorDocument } from "./types.js";
+/** A sculpted heightfield overlay stored on a document ΓÇö the terraform snapshot of offset deltas. */
+export type { EditorTerrain } from "./types.js";
+/** A baked top-down minimap (PNG data URI + world bounds) persisted on the scene document. */
+export type { EditorMinimapBake } from "./types.js";
+/** Scene-document sky/fog/lighting bag edited by the lighting workspace. */
+export type { EditorEnvironment, EditorFogConfig, EditorSkyPreset } from "./types.js";
 /** Per-kind show/hide flags for the editor's layer panel. */
 export type { EditorKindVisibility } from "./types.js";
+/** The four placeable-object collections a prefab fragment or clipboard fragment carries. */
+export type { EditorFragmentContent } from "./types.js";
+/** A serializable, reusable stamp of authored objects ΓÇö "make prefab" / "insert prefab" / detach. */
+export type { EditorPrefab } from "./types.js";
+/** A named, persisted list of object ids ΓÇö selection bookmark and/or locked production group. */
+export type { EditorCollection } from "./types.js";
+/** One row in a gameplay data catalog — id + optional label + meta matching the catalog schema. */
+export type { EditorCatalogEntry } from "./types.js";
+/** Persisted values for one gameplay data catalog on the scene document. */
+export type { EditorCatalogData } from "./types.js";
+/**
+ * Game-exported catalog definition: ParamSchema + default entries for in-editor tuning.
+ * @example
+ * ```ts
+ * import type { EditorCatalogDefinition } from "@jgengine/core/editor/index";
+ * export const editorCatalogs: EditorCatalogDefinition[] = [{
+ *   id: "towers", label: "Towers",
+ *   schema: { fields: [{ key: "damage", type: "number", default: 8, min: 1, max: 100 }] },
+ *   entries: [{ id: "tower_archer", label: "Archer", meta: { damage: 8 } }],
+ * }];
+ * ```
+ */
+export type { EditorCatalogDefinition } from "./types.js";
+/** Accepted shape for a game's `editorCatalogs` export: definitions, or a factory. */
+export type { EditorCatalogsInput } from "./types.js";
+/** Well-known catalog id for authored entity definitions consumed by the default content path. */
+export { ENTITY_CATALOG_ID, entityDefinitionSchema, entityEntryFromCatalog, resolveCatalogDefinitions } from "./entityCatalog.js";
+/** Minimal document shape {@link entityEntryFromCatalog} reads — any `EditorDocument` satisfies it. */
+export type { EntityCatalogDocumentLike } from "./entityCatalog.js";
 /** Accepted shape for a game's `editorLayers` export: a document, partial data, or a factory. */
 export type { EditorLayersInput } from "./types.js";
-/** A placeable point object in the scene — spawn, mob, chest, POI, etc. */
+/** A placeable point object in the scene ΓÇö spawn, mob, chest, POI, etc. */
 export type { EditorMarker } from "./types.js";
 /** A free-text annotation pinned to a world position for designers. */
 export type { EditorNote } from "./types.js";
-/** A polyline of points — road, corridor, patrol route — placed in the scene. */
+/** A polyline of points ΓÇö road, corridor, patrol route ΓÇö placed in the scene. */
 export type { EditorPath } from "./types.js";
 /** A world-space point used across editor markers, volumes, and paths. */
 export type { EditorVec3 } from "./types.js";
-/** A spatial region — zone, aggro range, capture area — placed in the scene. */
+/** A spatial region ΓÇö zone, aggro range, capture area ΓÇö placed in the scene. */
 export type { EditorVolume } from "./types.js";
 /** Collision shape a volume is rendered and tested as. */
 export type { EditorVolumeShape } from "./types.js";
+/** HUD layout section on the scene document — panel id → anchor/offset/size/visibility. */
+export type { EditorUiDocument, EditorUiPanelLayout, HudPanelTypeDef, HudResizeAxes } from "./types.js";
 export { WELL_KNOWN_MARKER_KINDS, WELL_KNOWN_PATH_KINDS, WELL_KNOWN_VOLUME_KINDS, } from "./types.js";
-export { cloneEditorDocument, createEmptyEditorDocument, editorDocumentBounds, exportEditorDocumentJson, findEditorMarker, findEditorNote, findEditorPath, findEditorVolume, importEditorDocumentJson, listEditorKinds, mergeEditorDocuments, normalizeEditorLayers, } from "./document.js";
+export { applyEditorDocumentOverlay, cloneEditorDocument, collectDescendants, createEmptyEditorDocument, createPrefabFragment, decodeEditorDocument, editorChildren, editorDocumentBounds, editorDocumentExtras, editorDocumentSize, editorMarkerPosition, editorMarkerXZ, editorParentOf, editorRoots, exportEditorDocumentJson, extractEditorFragment, findEditorCatalog, findEditorCatalogEntry, findEditorCollection, findEditorMarker, findEditorNote, findEditorPath, findEditorPrefab, findEditorVolume, importEditorDocumentJson, isEditorObjectCollectionLocked, isEditorObjectHidden, isEditorObjectLocked, isEditorObjectSelfLocked, listEditorKinds, mergeEditorDocuments, normalizeEditorLayers, requireEditorMarker, seedEditorCatalogs, wouldCreateCycle, } from "./document.js";
+/** One field-level failure surfaced while decoding an untrusted editor document. */
+export type { EditorDocumentDiagnostic } from "./document.js";
+export { WORLD_BASE_SHARD_ID, WORLD_MANIFEST_KIND, decodeWorldManifest, exportWorldManifestJson, loadWorldDocument, selectWorldShards, shardMatchesQuery, singleShardWorldManifest, splitEditorDocumentIntoShards, } from "./world.js";
+/** A sharded world manifest (`world.json`): grid + shard list + streaming config. */
+export type { DecodeWorldManifestResult, SplitWorldOptions, SplitWorldResult, WorldGrid, WorldManifest, WorldManifestShard, WorldQuery, WorldShardBounds, WorldShardResidency, WorldShardResolver, WorldStreamingConfig, } from "./world.js";
+/** Result of {@link decodeEditorDocument}: a typed document, or every diagnostic collected while decoding it. */
+export type { DecodeEditorDocumentResult } from "./document.js";
+export { environmentContentFromDocument, skyConfigFromEnvironment, skyFromDocument, terrainBoundsFromDocument, } from "./environment.js";
+/** Coordinate/placement content of an `environment()` world derived from the scene document. */
+export type { EnvironmentContent, EnvironmentContentOptions } from "./environment.js";
+export { bakeMinimapFromDocument, documentBakeZones } from "./minimap.js";
+/** Editor-side minimap bake from the scene document (footprint + biome-tint zones). */
+export type { DocumentBakeOptions } from "./minimap.js";
+export { createWorldStreamer, shardDistance } from "./streamer.js";
+/** A stateful proximity streamer that schedules shard load/unload as the camera moves. */
+export type { StreamUpdate, StreamerShard, WorldStreamer, WorldStreamerConfig } from "./streamer.js";
+/** A procedural directive on the scene document — scatter props or a mob population. */
+export type { EditorDirective, EditorDirectiveArea, EditorDirectiveKind, EditorPopulationDirective, EditorPopulationSpecies, EditorScatterDirective, } from "./types.js";
+export { applyDirectiveOverlay, materializeDirective, materializeDirectives, materializePopulationDirective, materializeScatterDirective, resolveDirectiveFootprint, } from "./directives.js";
+/** The deterministic bake of scene directives into per-instance placements + sparse overlays. */
+export type { DirectiveFootprint, DirectiveInstancePatch, EditorDirectiveOverlay, MaterializedInstance, } from "./directives.js";
 /** Creates an editor session with undo/redo history seeded from an initial document. */
 export { createEditorSession } from "./commands.js";
-/** Compact snapshot of a session state — counts, selection, and the selected object. */
+/** Compact snapshot of a session state ΓÇö counts, selection, and the selected object. */
 export { summarizeEditorSession } from "./commands.js";
-/** A single editor mutation — select, move, add, remove, undo/redo — dispatched to a session. */
+/** A single editor mutation ΓÇö select, move, add, remove, undo/redo ΓÇö dispatched to a session. */
 export type { EditorCommand } from "./commands.js";
+/** Per-dispatch options; `coalesce` merges consecutive same-key edits into one undo step. */
+export type { EditorDispatchOptions } from "./commands.js";
 /** Stateful, undoable handle for driving scene edits from UI or an MCP agent. */
 export type { EditorSession } from "./commands.js";
 /** The document plus current selection at a point in editor history. */
 export type { EditorSessionState } from "./commands.js";
+export { applyDocumentPatch, applyRuntimeStateDelta, createDocumentLiveSync, getDocumentLiveSync, installDocumentLiveSync, runtimeEntityWriteBackCommand, subscribeDocumentLiveSyncInstall, } from "./liveSync.js";
+/** Versioned document mutation on the editorΓåöruntime live-sync stream. */
+export type { DocumentPatch, ApplyDocumentPatchResult } from "./liveSync.js";
+/** Two-way live-sync bus: document patches out, runtime state deltas back. */
+export type { DocumentLiveSync, DocumentLiveEvent } from "./liveSync.js";
+/** Ephemeral runtime entity/tunable state streamed on the reverse channel. */
+export type { RuntimeEntityState, RuntimeStateDelta, RuntimeStateSnapshot } from "./liveSync.js";
+export { consumeRuntimePlayStep, createRuntimePlayControl, getRuntimeInspectorValue, planRuntimeInspectorSet, runtimeEntityMetaWriteBackCommand, summarizeRuntimeInspector, } from "./runtimeInspector.js";
+/** Play-mode sim gate and reverse-channel inspector summary/get/set pure helpers. */
+export type { RuntimeInspectorGetResult, RuntimeInspectorSetPlan, RuntimeInspectorSummary, RuntimePlayControl, } from "./runtimeInspector.js";
+export { CURRENT_GRID_SCHEMA_VERSION, cloneGridLayer, createGridLayer, eraseGridCell, eyedropGridCell, fillGridRect, findGridPaletteEntry, floodFillGrid, forEachGridCell, getGridCell, getGridCellAtWorld, gridCellCount, gridCellEntries, gridCellKey, gridCellToWorld, gridCellsOfValue, gridEmptyValue, gridGlyphMap, inGridBounds, migrateGridLayer, paintGridCells, parseGridCellKey, resizeGridLayer, setGridCell, worldToGridCell, } from "./grid.js";
+/** How a grid layer's columns and rows map onto world axes (`"xz"` top-down, `"xy"` side view). */
+export type { EditorGridAxes } from "./grid.js";
+/** A sparse, editor-owned tile grid serialized on the scene document. */
+export type { EditorGridLayer } from "./grid.js";
+/** One selectable value in a grid layer's palette — value id, glyph, color, and typed payload. */
+export type { EditorGridPaletteEntry } from "./grid.js";
+/** One resolved cell of a grid layer — its column, row, and value id. */
+export type { EditorGridCell } from "./grid.js";
+/** A single paint/erase edit: set cell `col,row` to `value` (empty value erases). */
+export type { EditorGridCellEdit } from "./grid.js";
+/** Fields accepted when constructing a grid layer via `createGridLayer`. */
+export type { CreateGridLayerInit } from "./grid.js";
+export { exportAsciiGrid, exportCsvGrid, importAsciiGrid, importCsvGrid, } from "./gridAdapters.js";
+/** Options for importing an ASCII/glyph map into a grid layer. */
+export type { AsciiGridImportOptions } from "./gridAdapters.js";
+/** Options for rendering a grid layer back out as an ASCII/glyph map. */
+export type { AsciiGridExportOptions } from "./gridAdapters.js";
+/** Options for importing a CSV grid (one value id per cell) into a grid layer. */
+export type { CsvGridImportOptions } from "./gridAdapters.js";
+/** Options for exporting a grid layer as CSV. */
+export type { CsvGridExportOptions } from "./gridAdapters.js";

package/dist/editor/index.js

@@ -1,6 +1,17 @@
+/** Well-known catalog id for authored entity definitions consumed by the default content path. */
+export { ENTITY_CATALOG_ID, entityDefinitionSchema, entityEntryFromCatalog, resolveCatalogDefinitions } from "./entityCatalog.js";
 export { WELL_KNOWN_MARKER_KINDS, WELL_KNOWN_PATH_KINDS, WELL_KNOWN_VOLUME_KINDS, } from "./types.js";
-export { cloneEditorDocument, createEmptyEditorDocument, editorDocumentBounds, exportEditorDocumentJson, findEditorMarker, findEditorNote, findEditorPath, findEditorVolume, importEditorDocumentJson, listEditorKinds, mergeEditorDocuments, normalizeEditorLayers, } from "./document.js";
+export { applyEditorDocumentOverlay, cloneEditorDocument, collectDescendants, createEmptyEditorDocument, createPrefabFragment, decodeEditorDocument, editorChildren, editorDocumentBounds, editorDocumentExtras, editorDocumentSize, editorMarkerPosition, editorMarkerXZ, editorParentOf, editorRoots, exportEditorDocumentJson, extractEditorFragment, findEditorCatalog, findEditorCatalogEntry, findEditorCollection, findEditorMarker, findEditorNote, findEditorPath, findEditorPrefab, findEditorVolume, importEditorDocumentJson, isEditorObjectCollectionLocked, isEditorObjectHidden, isEditorObjectLocked, isEditorObjectSelfLocked, listEditorKinds, mergeEditorDocuments, normalizeEditorLayers, requireEditorMarker, seedEditorCatalogs, wouldCreateCycle, } from "./document.js";
+export { WORLD_BASE_SHARD_ID, WORLD_MANIFEST_KIND, decodeWorldManifest, exportWorldManifestJson, loadWorldDocument, selectWorldShards, shardMatchesQuery, singleShardWorldManifest, splitEditorDocumentIntoShards, } from "./world.js";
+export { environmentContentFromDocument, skyConfigFromEnvironment, skyFromDocument, terrainBoundsFromDocument, } from "./environment.js";
+export { bakeMinimapFromDocument, documentBakeZones } from "./minimap.js";
+export { createWorldStreamer, shardDistance } from "./streamer.js";
+export { applyDirectiveOverlay, materializeDirective, materializeDirectives, materializePopulationDirective, materializeScatterDirective, resolveDirectiveFootprint, } from "./directives.js";
 /** Creates an editor session with undo/redo history seeded from an initial document. */
 export { createEditorSession } from "./commands.js";
-/** Compact snapshot of a session state — counts, selection, and the selected object. */
+/** Compact snapshot of a session state ΓÇö counts, selection, and the selected object. */
 export { summarizeEditorSession } from "./commands.js";
+export { applyDocumentPatch, applyRuntimeStateDelta, createDocumentLiveSync, getDocumentLiveSync, installDocumentLiveSync, runtimeEntityWriteBackCommand, subscribeDocumentLiveSyncInstall, } from "./liveSync.js";
+export { consumeRuntimePlayStep, createRuntimePlayControl, getRuntimeInspectorValue, planRuntimeInspectorSet, runtimeEntityMetaWriteBackCommand, summarizeRuntimeInspector, } from "./runtimeInspector.js";
+export { CURRENT_GRID_SCHEMA_VERSION, cloneGridLayer, createGridLayer, eraseGridCell, eyedropGridCell, fillGridRect, findGridPaletteEntry, floodFillGrid, forEachGridCell, getGridCell, getGridCellAtWorld, gridCellCount, gridCellEntries, gridCellKey, gridCellToWorld, gridCellsOfValue, gridEmptyValue, gridGlyphMap, inGridBounds, migrateGridLayer, paintGridCells, parseGridCellKey, resizeGridLayer, setGridCell, worldToGridCell, } from "./grid.js";
+export { exportAsciiGrid, exportCsvGrid, importAsciiGrid, importCsvGrid, } from "./gridAdapters.js";

package/dist/editor/liveSync.d.ts

@@ -0,0 +1,127 @@
+import { type EditorCommand } from "./commands.js";
+import type { EditorDocument, EditorVec3 } from "./types.js";
+/**
+ * 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).
+ */
+export type DocumentPatch = {
+    type: "snapshot";
+    revision?: number;
+    baseRevision: number;
+    document: EditorDocument;
+} | {
+    type: "commands";
+    revision?: number;
+    baseRevision: number;
+    commands: readonly EditorCommand[];
+};
+/** Result of applying a {@link DocumentPatch} to a document + revision pair. */
+export type ApplyDocumentPatchResult = {
+    ok: true;
+    document: EditorDocument;
+    revision: number;
+    patch: DocumentPatch;
+} | {
+    ok: false;
+    error: string;
+};
+/** One live entity row the runtime may stream to the editor (play-mode inspector feed). */
+export interface RuntimeEntityState {
+    id: string;
+    position?: EditorVec3;
+    rotationY?: number;
+    values?: Record<string, unknown>;
+}
+/** Full ephemeral runtime view held on the reverse channel — never mutates the document. */
+export interface RuntimeStateSnapshot {
+    seq: number;
+    entities: Record<string, RuntimeEntityState>;
+    tunables: Record<string, unknown>;
+}
+/**
+ * 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.
+ */
+export interface RuntimeStateDelta {
+    seq: number;
+    at: number;
+    entities?: readonly RuntimeEntityState[];
+    removeIds?: readonly string[];
+    tunables?: Record<string, unknown>;
+}
+/** Event emitted when the authoritative document changes on a {@link DocumentLiveSync}. */
+export interface DocumentLiveEvent {
+    document: EditorDocument;
+    revision: number;
+    patch: DocumentPatch;
+}
+/**
+ * Applies a versioned document patch. Rejects base-revision mismatches unless `force` (document
+ * is authoritative — the editor forces when publishing its own session state).
+ * @capability editor-live-sync apply a versioned document patch onto a live scene document
+ */
+export declare function applyDocumentPatch(document: EditorDocument, revision: number, patch: DocumentPatch, options?: {
+    force?: boolean;
+}): ApplyDocumentPatchResult;
+/**
+ * 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.
+ * @capability editor-live-sync merge a runtime state delta into the reverse-channel snapshot
+ */
+export declare function applyRuntimeStateDelta(snapshot: RuntimeStateSnapshot, delta: Omit<RuntimeStateDelta, "seq"> & {
+    seq?: number;
+}): {
+    snapshot: RuntimeStateSnapshot;
+    delta: RuntimeStateDelta;
+};
+/**
+ * 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.
+ * @capability editor-live-sync promote a runtime entity override into a document write-back command
+ */
+export declare function runtimeEntityWriteBackCommand(document: EditorDocument, entity: RuntimeEntityState): EditorCommand | null;
+/** Two-way live-sync bus: document patches out, runtime state deltas back. */
+export interface DocumentLiveSync {
+    getDocument(): EditorDocument;
+    getRevision(): number;
+    applyPatch(patch: DocumentPatch, options?: {
+        force?: boolean;
+    }): ApplyDocumentPatchResult;
+    /** Document-authoritative full replace (editor session mirror). */
+    replaceDocument(document: EditorDocument): DocumentLiveEvent;
+    pullPatches(sinceRevision: number): DocumentPatch[];
+    subscribeDocument(listener: (event: DocumentLiveEvent) => void): () => void;
+    getRuntimeState(): RuntimeStateSnapshot;
+    pushRuntimeDelta(delta: Omit<RuntimeStateDelta, "seq">): RuntimeStateDelta;
+    pullRuntimeDeltas(sinceSeq: number): RuntimeStateDelta[];
+    subscribeRuntime(listener: (delta: RuntimeStateDelta, snapshot: RuntimeStateSnapshot) => void): () => void;
+    setRuntimeOverride(entity: RuntimeEntityState): void;
+    clearRuntimeOverride(id: string): void;
+    getRuntimeOverrides(): Readonly<Record<string, RuntimeEntityState>>;
+    /**
+     * Promote an ephemeral override into a document command patch when the id exists in the
+     * document. Clears the override only after a successful apply.
+     */
+    writeBackOverride(id: string): ApplyDocumentPatchResult | {
+        ok: false;
+        error: string;
+    };
+}
+/**
+ * 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}.
+ * @capability editor-live-sync two-way document/runtime live-sync bus for editor↔game
+ */
+export declare function createDocumentLiveSync(initial: EditorDocument): DocumentLiveSync;
+/** Publishes a live-sync bus globally so AuthoredScene / games can subscribe without prop drilling. */
+export declare function installDocumentLiveSync(sync: DocumentLiveSync): () => void;
+/** Returns the globally installed live-sync bus, or null when none is mounted. */
+export declare function getDocumentLiveSync(): DocumentLiveSync | null;
+/**
+ * Subscribe to install/uninstall of the global live-sync bus (AuthoredScene re-attaches when the
+ * editor host mounts over a running game).
+ */
+export declare function subscribeDocumentLiveSyncInstall(listener: () => void): () => void;

package/dist/editor/liveSync.js

@@ -0,0 +1,249 @@
+import { createEditorSession } from "./commands.js";
+import { cloneEditorDocument } from "./document.js";
+const MAX_PATCH_LOG = 64;
+const MAX_RUNTIME_LOG = 128;
+/**
+ * Applies a versioned document patch. Rejects base-revision mismatches unless `force` (document
+ * is authoritative — the editor forces when publishing its own session state).
+ * @capability editor-live-sync apply a versioned document patch onto a live scene document
+ */
+export function applyDocumentPatch(document, revision, patch, options) {
+    if (!options?.force && patch.baseRevision !== revision) {
+        return {
+            ok: false,
+            error: `baseRevision mismatch: patch=${patch.baseRevision} current=${revision}`,
+        };
+    }
+    if (patch.type === "snapshot") {
+        const nextDoc = cloneEditorDocument(patch.document);
+        const nextRevision = revision + 1;
+        return {
+            ok: true,
+            document: nextDoc,
+            revision: nextRevision,
+            patch: { ...patch, revision: nextRevision, document: nextDoc },
+        };
+    }
+    if (patch.commands.length === 0) {
+        return { ok: false, error: "commands patch is empty" };
+    }
+    const session = createEditorSession(cloneEditorDocument(document));
+    for (const command of patch.commands) {
+        session.dispatch(command);
+    }
+    const nextDoc = session.getState().document;
+    const nextRevision = revision + 1;
+    return {
+        ok: true,
+        document: nextDoc,
+        revision: nextRevision,
+        patch: { ...patch, revision: nextRevision },
+    };
+}
+/**
+ * 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.
+ * @capability editor-live-sync merge a runtime state delta into the reverse-channel snapshot
+ */
+export function applyRuntimeStateDelta(snapshot, delta) {
+    const entities = { ...snapshot.entities };
+    if (delta.removeIds !== undefined) {
+        for (const id of delta.removeIds)
+            delete entities[id];
+    }
+    if (delta.entities !== undefined) {
+        for (const row of delta.entities) {
+            const prev = entities[row.id];
+            entities[row.id] = {
+                id: row.id,
+                position: row.position ?? prev?.position,
+                rotationY: row.rotationY ?? prev?.rotationY,
+                values: row.values === undefined && prev?.values === undefined
+                    ? undefined
+                    : { ...prev?.values, ...row.values },
+            };
+        }
+    }
+    const tunables = delta.tunables === undefined ? snapshot.tunables : { ...snapshot.tunables, ...delta.tunables };
+    const seq = snapshot.seq + 1;
+    const applied = {
+        seq,
+        at: delta.at,
+        ...(delta.entities === undefined ? {} : { entities: delta.entities }),
+        ...(delta.removeIds === undefined ? {} : { removeIds: delta.removeIds }),
+        ...(delta.tunables === undefined ? {} : { tunables: delta.tunables }),
+    };
+    return { snapshot: { seq, entities, tunables }, delta: applied };
+}
+/**
+ * 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.
+ * @capability editor-live-sync promote a runtime entity override into a document write-back command
+ */
+export function runtimeEntityWriteBackCommand(document, entity) {
+    const marker = document.markers.find((entry) => entry.id === entity.id);
+    if (marker !== undefined) {
+        if (entity.position === undefined && entity.rotationY === undefined)
+            return null;
+        return {
+            type: "setTransform",
+            id: entity.id,
+            ...(entity.position === undefined ? {} : { position: { ...entity.position } }),
+            ...(entity.rotationY === undefined ? {} : { rotationY: entity.rotationY }),
+        };
+    }
+    const volume = document.volumes.find((entry) => entry.id === entity.id);
+    if (volume !== undefined) {
+        if (entity.position === undefined)
+            return null;
+        return { type: "setTransform", id: entity.id, position: { ...entity.position } };
+    }
+    const note = document.annotations.find((entry) => entry.id === entity.id);
+    if (note !== undefined) {
+        if (entity.position === undefined)
+            return null;
+        return { type: "setTransform", id: entity.id, position: { ...entity.position } };
+    }
+    return null;
+}
+/**
+ * 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}.
+ * @capability editor-live-sync two-way document/runtime live-sync bus for editor↔game
+ */
+export function createDocumentLiveSync(initial) {
+    let document = cloneEditorDocument(initial);
+    let revision = 0;
+    let runtime = { seq: 0, entities: {}, tunables: {} };
+    const overrides = {};
+    const patchLog = [];
+    const runtimeLog = [];
+    const documentListeners = new Set();
+    const runtimeListeners = new Set();
+    const emitDocument = (event) => {
+        for (const listener of documentListeners)
+            listener(event);
+    };
+    const commit = (result) => {
+        document = result.document;
+        revision = result.revision;
+        patchLog.push(result.patch);
+        if (patchLog.length > MAX_PATCH_LOG)
+            patchLog.splice(0, patchLog.length - MAX_PATCH_LOG);
+        const event = {
+            document,
+            revision,
+            patch: result.patch,
+        };
+        emitDocument(event);
+        return event;
+    };
+    return {
+        getDocument: () => document,
+        getRevision: () => revision,
+        applyPatch(patch, options) {
+            const result = applyDocumentPatch(document, revision, patch, options);
+            if (!result.ok)
+                return result;
+            commit(result);
+            return result;
+        },
+        replaceDocument(next) {
+            const result = applyDocumentPatch(document, revision, { type: "snapshot", baseRevision: revision, document: next }, { force: true });
+            if (!result.ok) {
+                throw new Error(result.error);
+            }
+            return commit(result);
+        },
+        pullPatches(sinceRevision) {
+            return patchLog.filter((patch) => (patch.revision ?? 0) > sinceRevision);
+        },
+        subscribeDocument(listener) {
+            documentListeners.add(listener);
+            return () => {
+                documentListeners.delete(listener);
+            };
+        },
+        getRuntimeState: () => runtime,
+        pushRuntimeDelta(delta) {
+            const applied = applyRuntimeStateDelta(runtime, delta);
+            runtime = applied.snapshot;
+            runtimeLog.push(applied.delta);
+            if (runtimeLog.length > MAX_RUNTIME_LOG)
+                runtimeLog.splice(0, runtimeLog.length - MAX_RUNTIME_LOG);
+            for (const listener of runtimeListeners)
+                listener(applied.delta, runtime);
+            return applied.delta;
+        },
+        pullRuntimeDeltas(sinceSeq) {
+            return runtimeLog.filter((delta) => delta.seq > sinceSeq);
+        },
+        subscribeRuntime(listener) {
+            runtimeListeners.add(listener);
+            return () => {
+                runtimeListeners.delete(listener);
+            };
+        },
+        setRuntimeOverride(entity) {
+            const prev = overrides[entity.id];
+            overrides[entity.id] = {
+                id: entity.id,
+                position: entity.position ?? prev?.position,
+                rotationY: entity.rotationY ?? prev?.rotationY,
+                values: entity.values === undefined && prev?.values === undefined
+                    ? undefined
+                    : { ...prev?.values, ...entity.values },
+            };
+        },
+        clearRuntimeOverride(id) {
+            delete overrides[id];
+        },
+        getRuntimeOverrides: () => ({ ...overrides }),
+        writeBackOverride(id) {
+            const entity = overrides[id];
+            if (entity === undefined)
+                return { ok: false, error: `no runtime override for "${id}"` };
+            const command = runtimeEntityWriteBackCommand(document, entity);
+            if (command === null) {
+                return { ok: false, error: `override "${id}" has nothing to write back into the document` };
+            }
+            const result = applyDocumentPatch(document, revision, { type: "commands", baseRevision: revision, commands: [command] }, { force: true });
+            if (!result.ok)
+                return result;
+            commit(result);
+            delete overrides[id];
+            return result;
+        },
+    };
+}
+const GLOBAL_KEY = "__jgengineDocumentLiveSync";
+const INSTALL_LISTENERS = new Set();
+/** Publishes a live-sync bus globally so AuthoredScene / games can subscribe without prop drilling. */
+export function installDocumentLiveSync(sync) {
+    const root = globalThis;
+    root[GLOBAL_KEY] = sync;
+    for (const listener of INSTALL_LISTENERS)
+        listener();
+    return () => {
+        if (root[GLOBAL_KEY] === sync)
+            delete root[GLOBAL_KEY];
+        for (const listener of INSTALL_LISTENERS)
+            listener();
+    };
+}
+/** Returns the globally installed live-sync bus, or null when none is mounted. */
+export function getDocumentLiveSync() {
+    const root = globalThis;
+    return root[GLOBAL_KEY] ?? null;
+}
+/**
+ * Subscribe to install/uninstall of the global live-sync bus (AuthoredScene re-attaches when the
+ * editor host mounts over a running game).
+ */
+export function subscribeDocumentLiveSyncInstall(listener) {
+    INSTALL_LISTENERS.add(listener);
+    return () => {
+        INSTALL_LISTENERS.delete(listener);
+    };
+}

package/dist/editor/minimap.d.ts

@@ -0,0 +1,31 @@
+import { type MinimapBakeBounds, type MinimapBakeOptions, type MinimapBakeZone } from "../world/minimapBake.js";
+import type { EditorDocument } from "./types.js";
+/**
+ * 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.)
+ * @capability minimap-bake derive biome-tint zones for a bake from the scene document
+ */
+export declare function documentBakeZones(doc: EditorDocument): MinimapBakeZone[];
+/** Options for {@link bakeMinimapFromDocument}. */
+export interface DocumentBakeOptions extends MinimapBakeOptions {
+    /** Explicit bounds; default = the document's object bounds padded by `padding`. */
+    bounds?: MinimapBakeBounds;
+    /** Padding (m) around the derived bounds when `bounds` is omitted. Default 16. */
+    padding?: number;
+    /** Ground normal sampler for slope shading (optional). */
+    sampleNormal?: (x: number, z: number) => readonly [number, number, number];
+    /** Water level — ground at or below renders as water. */
+    waterLevel?: number;
+}
+/**
+ * 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.
+ * @capability minimap-bake bake a minimap PNG + bounds from the authored scene document
+ */
+export declare function bakeMinimapFromDocument(doc: EditorDocument, sampleHeight: (x: number, z: number) => number, options?: DocumentBakeOptions): {
+    background: string;
+    mapBounds: MinimapBakeBounds;
+};

package/dist/editor/minimap.js

@@ -0,0 +1,73 @@
+import { bakeMinimapImage, minimapBakeToPngDataUri, } from "../world/minimapBake.js";
+import { editorDocumentBounds } from "./document.js";
+/**
+ * The editor-side minimap bake (#1036): bake a top-down terrain image straight from the authored
+ * scene document. The document owns the zones (biome-tinted volumes) and the footprint; the caller
+ * supplies the composed `sampleHeight` (base terrain + the document's sculpt), since the sculpt on
+ * the document is a delta over the game's base terrain. Returns the `{ background, mapBounds }` the
+ * `Minimap`/`WorldMap` props take, so the editor stores that on the document and runtime consumes it
+ * with no new render path. Deterministic for a fixed scene — safe for verify/CI.
+ */
+/** A volume that carries a `color` tints the bake over its XZ footprint. */
+function volumeFootprint(volume) {
+    const half = volume.halfExtents !== undefined
+        ? { x: volume.halfExtents.x, z: volume.halfExtents.z }
+        : volume.radius !== undefined
+            ? { x: volume.radius, z: volume.radius }
+            : null;
+    if (half === null)
+        return null;
+    const { x, z } = volume.center;
+    return [
+        [x - half.x, z - half.z],
+        [x + half.x, z - half.z],
+        [x + half.x, z + half.z],
+        [x - half.x, z + half.z],
+    ];
+}
+/**
+ * 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.)
+ * @capability minimap-bake derive biome-tint zones for a bake from the scene document
+ */
+export function documentBakeZones(doc) {
+    const zones = [];
+    for (const volume of doc.volumes) {
+        if (volume.color === undefined)
+            continue;
+        const polygon = volumeFootprint(volume);
+        if (polygon === null)
+            continue;
+        zones.push({ polygon, color: volume.color, alpha: 0.4 });
+    }
+    return zones;
+}
+/** Falls back to a small square when the document has no spatial objects. */
+function boundsFromDocument(doc, padding) {
+    const b = editorDocumentBounds(doc);
+    if (b === null)
+        return { minX: -32, minZ: -32, maxX: 32, maxZ: 32 };
+    return { minX: b.min.x - padding, minZ: b.min.z - padding, maxX: b.max.x + padding, maxZ: b.max.z + padding };
+}
+/**
+ * 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.
+ * @capability minimap-bake bake a minimap PNG + bounds from the authored scene document
+ */
+export function bakeMinimapFromDocument(doc, sampleHeight, options = {}) {
+    const bounds = options.bounds ?? boundsFromDocument(doc, options.padding ?? 16);
+    const bake = bakeMinimapImage({
+        bounds,
+        sampleHeight,
+        ...(options.sampleNormal === undefined ? {} : { sampleNormal: options.sampleNormal }),
+        ...(options.waterLevel === undefined ? {} : { waterLevel: options.waterLevel }),
+        zones: documentBakeZones(doc),
+    }, {
+        ...(options.resolution === undefined ? {} : { resolution: options.resolution }),
+        ...(options.palette === undefined ? {} : { palette: options.palette }),
+    });
+    return { background: minimapBakeToPngDataUri(bake), mapBounds: bake.bounds };
+}