@jgengine/core 0.9.0 → 0.11.0

package/dist/editor/gridAdapters.js

@@ -0,0 +1,134 @@
+import { createGridLayer, getGridCell, gridCellKey, gridEmptyValue, gridGlyphMap, } from "./grid.js";
+function normalizeLines(text) {
+    const lines = text.replace(/\r\n?/g, "\n").split("\n");
+    while (lines.length > 0 && lines[lines.length - 1] === "")
+        lines.pop();
+    return lines;
+}
+function glyphToValue(options) {
+    const map = {};
+    for (const entry of options.palette ?? []) {
+        if (entry.glyph !== undefined)
+            map[entry.glyph] = entry.id;
+    }
+    return { ...map, ...(options.glyphMap ?? {}) };
+}
+/**
+ * Parses an ASCII/glyph map — one row per text line, one char per cell — into a grid layer. Each
+ * glyph is resolved to a value id via the palette/`glyphMap`; unmapped glyphs and padding become
+ * the empty value, so a mostly-open room stays sparse. The canonical representation is the
+ * returned {@link EditorGridLayer}; ASCII is just this import path into it, never the source of
+ * truth. Bounds are the row count × longest row.
+ * @capability editor-grid-import Import an ASCII/glyph map into a grid layer.
+ */
+export function importAsciiGrid(text, options) {
+    const lines = normalizeLines(text);
+    const rows = lines.length;
+    let cols = 0;
+    for (const line of lines)
+        cols = Math.max(cols, line.length);
+    const map = glyphToValue(options);
+    const empty = options.empty ?? "";
+    const cells = {};
+    lines.forEach((line, row) => {
+        for (let col = 0; col < line.length; col += 1) {
+            const value = map[line[col]] ?? empty;
+            if (value !== empty)
+                cells[gridCellKey(col, row)] = value;
+        }
+    });
+    return createGridLayer({
+        id: options.id,
+        kind: options.kind,
+        ...(options.label === undefined ? {} : { label: options.label }),
+        cols,
+        rows,
+        ...(options.cellSize === undefined ? {} : { cellSize: options.cellSize }),
+        ...(options.origin === undefined ? {} : { origin: options.origin }),
+        ...(options.axes === undefined ? {} : { axes: options.axes }),
+        ...(empty === "" ? {} : { empty }),
+        cells,
+        ...(options.palette === undefined ? {} : { palette: options.palette }),
+        ...(options.meta === undefined ? {} : { meta: options.meta }),
+    });
+}
+/**
+ * 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.
+ * @capability editor-grid-import Export a grid layer as an ASCII/glyph map.
+ */
+export function exportAsciiGrid(layer, options = {}) {
+    const glyphMap = options.glyphMap ?? gridGlyphMap(layer);
+    const emptyGlyph = options.emptyGlyph ?? ".";
+    const empty = gridEmptyValue(layer);
+    const lines = [];
+    for (let row = 0; row < layer.rows; row += 1) {
+        let line = "";
+        for (let col = 0; col < layer.cols; col += 1) {
+            const value = getGridCell(layer, col, row);
+            line += value === empty ? emptyGlyph : (glyphMap[value] ?? (value.charAt(0) || emptyGlyph));
+        }
+        lines.push(line);
+    }
+    return lines.join("\n");
+}
+/**
+ * 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.
+ * @capability editor-grid-import Import a CSV grid (value id per cell) into a grid layer.
+ */
+export function importCsvGrid(text, options) {
+    const delimiter = options.delimiter ?? ",";
+    const empty = options.empty ?? "";
+    const lines = normalizeLines(text);
+    const rows = lines.length;
+    let cols = 0;
+    const parsed = lines.map((line) => {
+        const fields = line.split(delimiter).map((field) => field.trim());
+        cols = Math.max(cols, fields.length);
+        return fields;
+    });
+    const cells = {};
+    parsed.forEach((fields, row) => {
+        fields.forEach((value, col) => {
+            if (value !== "" && value !== empty)
+                cells[gridCellKey(col, row)] = value;
+        });
+    });
+    return createGridLayer({
+        id: options.id,
+        kind: options.kind,
+        ...(options.label === undefined ? {} : { label: options.label }),
+        cols,
+        rows,
+        ...(options.cellSize === undefined ? {} : { cellSize: options.cellSize }),
+        ...(options.origin === undefined ? {} : { origin: options.origin }),
+        ...(options.axes === undefined ? {} : { axes: options.axes }),
+        ...(empty === "" ? {} : { empty }),
+        cells,
+        ...(options.palette === undefined ? {} : { palette: options.palette }),
+        ...(options.meta === undefined ? {} : { meta: options.meta }),
+    });
+}
+/**
+ * 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}.
+ * @capability editor-grid-import Export a grid layer as CSV.
+ */
+export function exportCsvGrid(layer, options = {}) {
+    const delimiter = options.delimiter ?? ",";
+    const emptyField = options.emptyField ?? "";
+    const empty = gridEmptyValue(layer);
+    const lines = [];
+    for (let row = 0; row < layer.rows; row += 1) {
+        const fields = [];
+        for (let col = 0; col < layer.cols; col += 1) {
+            const value = getGridCell(layer, col, row);
+            fields.push(value === empty ? emptyField : value);
+        }
+        lines.push(fields.join(delimiter));
+    }
+    return lines.join("\n");
+}

package/dist/editor/index.d.ts

@@ -0,0 +1,97 @@
+/** 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";
+/** 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";
+/** 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. */
+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. */
+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. */
+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 { applyEditorDocumentOverlay, cloneEditorDocument, collectDescendants, createEmptyEditorDocument, createPrefabFragment, decodeEditorDocument, editorChildren, editorDocumentBounds, editorDocumentExtras, editorDocumentSize, editorParentOf, editorRoots, exportEditorDocumentJson, extractEditorFragment, findEditorCatalog, findEditorCatalogEntry, findEditorCollection, findEditorMarker, findEditorNote, findEditorPath, findEditorPrefab, findEditorVolume, importEditorDocumentJson, isEditorObjectLocked, listEditorKinds, mergeEditorDocuments, normalizeEditorLayers, seedEditorCatalogs, wouldCreateCycle, } from "./document.js";
+/** One field-level failure surfaced while decoding an untrusted editor document. */
+export type { EditorDocumentDiagnostic } from "./document.js";
+/** Result of {@link decodeEditorDocument}: a typed document, or every diagnostic collected while decoding it. */
+export type { DecodeEditorDocumentResult } from "./document.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. */
+export { summarizeEditorSession } from "./commands.js";
+/** 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

@@ -0,0 +1,10 @@
+export { WELL_KNOWN_MARKER_KINDS, WELL_KNOWN_PATH_KINDS, WELL_KNOWN_VOLUME_KINDS, } from "./types.js";
+export { applyEditorDocumentOverlay, cloneEditorDocument, collectDescendants, createEmptyEditorDocument, createPrefabFragment, decodeEditorDocument, editorChildren, editorDocumentBounds, editorDocumentExtras, editorDocumentSize, editorParentOf, editorRoots, exportEditorDocumentJson, extractEditorFragment, findEditorCatalog, findEditorCatalogEntry, findEditorCollection, findEditorMarker, findEditorNote, findEditorPath, findEditorPrefab, findEditorVolume, importEditorDocumentJson, isEditorObjectLocked, listEditorKinds, mergeEditorDocuments, normalizeEditorLayers, seedEditorCatalogs, wouldCreateCycle, } from "./document.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. */
+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);
+    };
+}