@jgengine/editor 0.11.0 → 0.13.0

package/dist/handlers/grids.js

@@ -0,0 +1,142 @@
+import { createGridLayer, eyedropGridCell, gridCellCount, importAsciiGrid, importCsvGrid, } from "@jgengine/core/editor/index";
+/** Compact grid-layer summary returned by the grid RPC verbs — never the full sparse cell map. */
+function gridLayerSummary(layer) {
+    return {
+        id: layer.id,
+        kind: layer.kind,
+        ...(layer.label === undefined ? {} : { label: layer.label }),
+        cols: layer.cols,
+        rows: layer.rows,
+        cellSize: layer.cellSize,
+        cellCount: gridCellCount(layer),
+        visible: layer.visible ?? true,
+        paletteIds: (layer.palette ?? []).map((entry) => entry.id),
+    };
+}
+/** Runs `fn` with the grid layer in `state`, or short-circuits with an honest not-found response. */
+function withGridLayer(state, id, fn) {
+    const layer = (state.document.grids ?? []).find((entry) => entry.id === id);
+    if (layer === undefined)
+        return { ok: false, error: `grid layer not found: ${id}` };
+    return fn(layer);
+}
+/** Grid/tile layer verbs — create, edit, paint, fill, and import. */
+export const gridHandlers = {
+    list_grids: (ctx) => {
+        const grids = ctx.session.getState().document.grids ?? [];
+        return { ok: true, result: { grids: grids.map(gridLayerSummary) } };
+    },
+    get_grid_cell: (ctx, request) => withGridLayer(ctx.session.getState(), request.id, (layer) => ({
+        ok: true,
+        result: { id: request.id, col: request.col, row: request.row, value: eyedropGridCell(layer, request.col, request.row) },
+    })),
+    add_grid_layer: (ctx, request) => {
+        const layer = createGridLayer({
+            id: request.id,
+            kind: request.kind,
+            cols: request.cols,
+            rows: request.rows,
+            ...(request.label === undefined ? {} : { label: request.label }),
+            ...(request.cellSize === undefined ? {} : { cellSize: request.cellSize }),
+            ...(request.origin === undefined ? {} : { origin: request.origin }),
+            ...(request.axes === undefined ? {} : { axes: request.axes }),
+            ...(request.empty === undefined ? {} : { empty: request.empty }),
+            ...(request.palette === undefined ? {} : { palette: request.palette }),
+        });
+        const { applied } = ctx.dispatchGuarded({ type: "addGridLayer", layer });
+        if (!applied)
+            return { ok: false, error: "add_grid_layer rejected: no effect" };
+        return { ok: true, result: gridLayerSummary(layer) };
+    },
+    remove_grid_layer: (ctx, request) => {
+        const { applied } = ctx.dispatchGuarded({ type: "removeGridLayer", id: request.id });
+        if (!applied)
+            return { ok: false, error: `grid layer not found: ${request.id}` };
+        return { ok: true, result: { removed: request.id } };
+    },
+    set_grid_layer: (ctx, request) => {
+        const patch = {};
+        if (request.label !== undefined)
+            patch.label = request.label;
+        if (request.kind !== undefined)
+            patch.kind = request.kind;
+        if (request.visible !== undefined)
+            patch.visible = request.visible;
+        if (request.empty !== undefined)
+            patch.empty = request.empty;
+        if (request.cellSize !== undefined)
+            patch.cellSize = request.cellSize;
+        if (request.origin !== undefined)
+            patch.origin = request.origin;
+        if (request.axes !== undefined)
+            patch.axes = request.axes;
+        if (request.palette !== undefined)
+            patch.palette = request.palette;
+        const { applied, state } = ctx.dispatchGuarded({ type: "setGridLayer", id: request.id, patch });
+        if (!applied)
+            return { ok: false, error: `set_grid_layer rejected: no effect (${request.id})` };
+        return withGridLayer(state, request.id, (layer) => ({ ok: true, result: gridLayerSummary(layer) }));
+    },
+    paint_grid_cells: (ctx, request) => {
+        const { applied, state } = ctx.dispatchGuarded({ type: "paintGridCells", id: request.id, cells: request.cells });
+        if (!applied)
+            return { ok: false, error: `paint_grid_cells rejected: no effect (${request.id})` };
+        return withGridLayer(state, request.id, (layer) => ({ ok: true, result: gridLayerSummary(layer) }));
+    },
+    fill_grid_rect: (ctx, request) => {
+        const { applied, state } = ctx.dispatchGuarded({
+            type: "fillGridRect",
+            id: request.id,
+            col0: request.col0,
+            row0: request.row0,
+            col1: request.col1,
+            row1: request.row1,
+            value: request.value,
+        });
+        if (!applied)
+            return { ok: false, error: `fill_grid_rect rejected: no effect (${request.id})` };
+        return withGridLayer(state, request.id, (layer) => ({ ok: true, result: gridLayerSummary(layer) }));
+    },
+    flood_fill_grid: (ctx, request) => {
+        const { applied, state } = ctx.dispatchGuarded({
+            type: "floodFillGrid",
+            id: request.id,
+            col: request.col,
+            row: request.row,
+            value: request.value,
+        });
+        if (!applied)
+            return { ok: false, error: `flood_fill_grid rejected: no effect (${request.id})` };
+        return withGridLayer(state, request.id, (layer) => ({ ok: true, result: gridLayerSummary(layer) }));
+    },
+    resize_grid_layer: (ctx, request) => {
+        const { applied, state } = ctx.dispatchGuarded({ type: "resizeGridLayer", id: request.id, cols: request.cols, rows: request.rows });
+        if (!applied)
+            return { ok: false, error: `resize_grid_layer rejected: no effect (${request.id})` };
+        return withGridLayer(state, request.id, (layer) => ({ ok: true, result: gridLayerSummary(layer) }));
+    },
+    import_grid: (ctx, request) => {
+        const layer = request.format === "csv"
+            ? importCsvGrid(request.text, {
+                id: request.id,
+                kind: request.kind,
+                ...(request.empty === undefined ? {} : { empty: request.empty }),
+                ...(request.cellSize === undefined ? {} : { cellSize: request.cellSize }),
+                ...(request.origin === undefined ? {} : { origin: request.origin }),
+                ...(request.palette === undefined ? {} : { palette: request.palette }),
+            })
+            : importAsciiGrid(request.text, {
+                id: request.id,
+                kind: request.kind,
+                ...(request.empty === undefined ? {} : { empty: request.empty }),
+                ...(request.cellSize === undefined ? {} : { cellSize: request.cellSize }),
+                ...(request.origin === undefined ? {} : { origin: request.origin }),
+                ...(request.glyphMap === undefined ? {} : { glyphMap: request.glyphMap }),
+                ...(request.palette === undefined ? {} : { palette: request.palette }),
+            });
+        const { applied } = ctx.dispatchGuarded({ type: "addGridLayer", layer });
+        if (!applied)
+            return { ok: false, error: "import_grid rejected: no effect" };
+        return { ok: true, result: gridLayerSummary(layer) };
+    },
+};

package/dist/handlers/hierarchy.d.ts

@@ -0,0 +1,3 @@
+import type { HandlerTable } from "./context.js";
+/** Parent/child hierarchy and prefab library verbs. */
+export declare const hierarchyHandlers: Pick<HandlerTable, "set_parent" | "hierarchy" | "list_prefabs" | "create_prefab" | "insert_prefab" | "detach_prefab_instance" | "delete_prefab">;

package/dist/handlers/hierarchy.js

@@ -0,0 +1,55 @@
+import { editorChildren, editorParentOf, editorRoots, findEditorPrefab, summarizeEditorSession, } from "@jgengine/core/editor/index";
+/** Parent/child hierarchy and prefab library verbs. */
+export const hierarchyHandlers = {
+    set_parent: (ctx, request) => {
+        const { applied, state } = ctx.dispatchGuarded({ type: "setParent", ids: request.ids, parentId: request.parentId });
+        if (!applied)
+            return { ok: false, error: "set_parent rejected: cyclic parent or empty selection" };
+        const doc = state.document;
+        return {
+            ok: true,
+            result: { roots: editorRoots(doc), parents: request.ids.map((id) => ({ id, parentId: editorParentOf(doc, id) ?? null })) },
+        };
+    },
+    hierarchy: (ctx) => {
+        const doc = ctx.session.getState().document;
+        const roots = editorRoots(doc);
+        return { ok: true, result: { roots, tree: roots.map((id) => ({ id, children: editorChildren(doc, id) })) } };
+    },
+    list_prefabs: (ctx) => ({ ok: true, result: { prefabs: ctx.session.getState().document.prefabs } }),
+    create_prefab: (ctx, request) => {
+        if (request.ids.length === 0)
+            return { ok: false, error: "create_prefab needs at least one id" };
+        ctx.session.dispatch({ type: "createPrefab", id: request.id, name: request.name, ids: request.ids });
+        const prefab = findEditorPrefab(ctx.session.getState().document, request.id);
+        return prefab === undefined ? { ok: false, error: `prefab not created: ${request.id}` } : { ok: true, result: prefab };
+    },
+    insert_prefab: (ctx, request) => {
+        const prefab = findEditorPrefab(ctx.session.getState().document, request.prefabId);
+        if (prefab === undefined)
+            return { ok: false, error: `prefab not found: ${request.prefabId}` };
+        const at = ctx.api.getFocusTarget() ?? { x: 0, y: 0, z: 0 };
+        ctx.session.dispatch({
+            type: "insertPrefab",
+            prefabId: request.prefabId,
+            at: { x: request.x ?? at.x, y: request.y ?? at.y, z: request.z ?? at.z },
+        });
+        return { ok: true, result: summarizeEditorSession(ctx.session.getState()) };
+    },
+    detach_prefab_instance: (ctx, request) => {
+        const doc = ctx.session.getState().document;
+        const carries = (item) => item.meta?.prefabInstanceId === request.instanceId;
+        const hasInstance = doc.markers.some(carries) || doc.volumes.some(carries) || doc.paths.some(carries) || doc.annotations.some(carries);
+        if (!hasInstance)
+            return { ok: false, error: `prefab instance not found: ${request.instanceId}` };
+        ctx.session.dispatch({ type: "detachPrefabInstance", instanceId: request.instanceId });
+        return { ok: true, result: summarizeEditorSession(ctx.session.getState()) };
+    },
+    delete_prefab: (ctx, request) => {
+        if (findEditorPrefab(ctx.session.getState().document, request.prefabId) === undefined) {
+            return { ok: false, error: `prefab not found: ${request.prefabId}` };
+        }
+        ctx.session.dispatch({ type: "deletePrefab", prefabId: request.prefabId });
+        return { ok: true, result: { prefabs: ctx.session.getState().document.prefabs } };
+    },
+};

package/dist/handlers/index.d.ts

@@ -0,0 +1,8 @@
+import type { HandlerTable } from "./context.js";
+/**
+ * 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.
+ */
+export declare const EDITOR_RPC_HANDLERS: HandlerTable;
+export type { HandlerContext } from "./context.js";

package/dist/handlers/index.js

@@ -0,0 +1,25 @@
+import { catalogHandlers } from "./catalogs.js";
+import { collectionHandlers } from "./collections.js";
+import { documentHandlers } from "./document.js";
+import { gridHandlers } from "./grids.js";
+import { hierarchyHandlers } from "./hierarchy.js";
+import { minimapHandlers } from "./minimap.js";
+import { streetsHandlers } from "./streets.js";
+import { runtimeHandlers } from "./runtime.js";
+import { terrainHandlers } from "./terrain.js";
+/**
+ * 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.
+ */
+export const EDITOR_RPC_HANDLERS = {
+    ...documentHandlers,
+    ...catalogHandlers,
+    ...terrainHandlers,
+    ...minimapHandlers,
+    ...streetsHandlers,
+    ...hierarchyHandlers,
+    ...collectionHandlers,
+    ...gridHandlers,
+    ...runtimeHandlers,
+};

package/dist/handlers/minimap.d.ts

@@ -0,0 +1,9 @@
+import type { HandlerTable } from "./context.js";
+/**
+ * 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.
+ */
+export declare const minimapHandlers: Pick<HandlerTable, "bake_minimap">;

package/dist/handlers/minimap.js

@@ -0,0 +1,32 @@
+import { bakeMinimapFromDocument } from "@jgengine/core/editor/index";
+import { editableTerrainFromSnapshot } from "@jgengine/core/world/terraform";
+/**
+ * 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.
+ */
+export const minimapHandlers = {
+    bake_minimap: (ctx, request) => {
+        const base = ctx.getTerrainSampler();
+        if (base === null)
+            return { ok: false, error: "bake_minimap needs the live editor viewport" };
+        const doc = ctx.session.getState().document;
+        // Compose base terrain + the document's sculpt delta; a doc with no sculpt bakes the base field.
+        const composed = doc.terrain === undefined ? base : editableTerrainFromSnapshot(doc.terrain, base);
+        const waterLevel = request.waterLevel ?? base.waterLevel;
+        const options = {
+            sampleNormal: (x, z) => composed.sampleNormal(x, z),
+            ...(request.padding === undefined ? {} : { padding: request.padding }),
+            ...(request.resolution === undefined ? {} : { resolution: request.resolution }),
+            ...(waterLevel === undefined ? {} : { waterLevel }),
+        };
+        const { background, mapBounds } = bakeMinimapFromDocument(doc, (x, z) => composed.sampleHeight(x, z), options);
+        ctx.dispatchGuarded({ type: "setMinimapBake", minimap: { background, bounds: mapBounds } });
+        const b64 = background.slice(background.indexOf(",") + 1);
+        const padCount = b64.endsWith("==") ? 2 : b64.endsWith("=") ? 1 : 0;
+        const bytes = Math.max(0, Math.floor((b64.length * 3) / 4) - padCount);
+        return { ok: true, result: { bounds: mapBounds, bytes } };
+    },
+};

package/dist/handlers/runtime.d.ts

@@ -0,0 +1,3 @@
+import type { HandlerTable } from "./context.js";
+/** Live-sync document patches, the ephemeral runtime reverse channel, and play-mode poke verbs. */
+export declare 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_runtime_override" | "clear_runtime_override" | "write_back_override">;

package/dist/handlers/runtime.js

@@ -0,0 +1,191 @@
+import { decodeEditorDocument, getRuntimeInspectorValue, planRuntimeInspectorSet, runtimeEntityMetaWriteBackCommand, runtimeEntityWriteBackCommand, summarizeEditorSession, summarizeRuntimeInspector, } from "@jgengine/core/editor/index";
+/** Live-sync document patches, the ephemeral runtime reverse channel, and play-mode poke verbs. */
+export const runtimeHandlers = {
+    push_document_patch: (ctx, request) => {
+        const force = request.force === true;
+        const rawPatch = request.patch;
+        if (rawPatch === null || typeof rawPatch !== "object") {
+            return { ok: false, error: "push_document_patch requires a patch object" };
+        }
+        const patch = rawPatch;
+        if (patch.type !== "snapshot" && patch.type !== "commands") {
+            return { ok: false, error: `unknown document patch type: ${String(patch.type)} (snapshot | commands)` };
+        }
+        if (typeof patch.baseRevision !== "number") {
+            return { ok: false, error: "push_document_patch requires a numeric baseRevision" };
+        }
+        if (!force && patch.baseRevision !== ctx.liveSync.getRevision()) {
+            return { ok: false, error: `baseRevision mismatch: patch=${patch.baseRevision} current=${ctx.liveSync.getRevision()}` };
+        }
+        if (patch.type === "snapshot") {
+            // A snapshot replaces the whole document, so it must clear the same decode/migrate boundary a
+            // disk or `import_document` document does — otherwise a fuzzed snapshot would reach
+            // `replaceDocument` uncoerced.
+            const decoded = decodeEditorDocument(patch.document);
+            if (!decoded.ok) {
+                return { ok: false, error: `invalid snapshot document: ${decoded.errors.map((e) => `${e.path} ${e.message}`).join("; ")}` };
+            }
+            ctx.session.dispatch({ type: "replaceDocument", document: decoded.document });
+            return { ok: true, result: { revision: ctx.liveSync.getRevision(), ...summarizeEditorSession(ctx.session.getState()) } };
+        }
+        if (!Array.isArray(patch.commands))
+            return { ok: false, error: "commands patch requires a commands array" };
+        if (patch.commands.length === 0)
+            return { ok: false, error: "commands patch is empty" };
+        for (const command of patch.commands) {
+            const { applied } = ctx.dispatchGuarded(command);
+            if (!applied && command.type !== "select" && command.type !== "clearSelection") {
+                return { ok: false, error: `${command.type} rejected while applying patch` };
+            }
+        }
+        return { ok: true, result: { revision: ctx.liveSync.getRevision(), ...summarizeEditorSession(ctx.session.getState()) } };
+    },
+    pull_document_patches: (ctx, request) => ({
+        ok: true,
+        result: { revision: ctx.liveSync.getRevision(), patches: ctx.liveSync.pullPatches(request.sinceRevision ?? 0) },
+    }),
+    document_revision: (ctx, request) => ({
+        ok: true,
+        result: {
+            revision: ctx.liveSync.getRevision(),
+            ...(request.includeDocument === true ? { document: ctx.liveSync.getDocument() } : {}),
+        },
+    }),
+    push_runtime_delta: (ctx, request) => {
+        const delta = ctx.liveSync.pushRuntimeDelta({
+            at: request.at ?? Date.now(),
+            ...(request.entities === undefined ? {} : { entities: request.entities }),
+            ...(request.removeIds === undefined ? {} : { removeIds: request.removeIds }),
+            ...(request.tunables === undefined ? {} : { tunables: request.tunables }),
+        });
+        return { ok: true, result: delta };
+    },
+    pull_runtime_deltas: (ctx, request) => ({
+        ok: true,
+        result: {
+            seq: ctx.liveSync.getRuntimeState().seq,
+            deltas: ctx.liveSync.pullRuntimeDeltas(request.sinceSeq ?? 0),
+            ...(request.includeSnapshot === true ? { snapshot: ctx.liveSync.getRuntimeState() } : {}),
+        },
+    }),
+    runtime_snapshot: (ctx) => ({ ok: true, result: ctx.liveSync.getRuntimeState() }),
+    runtime_summary: (ctx) => ({
+        ok: true,
+        result: summarizeRuntimeInspector(ctx.liveSync.getRuntimeState(), ctx.liveSync.getRuntimeOverrides(), ctx.api.getPlayControl()),
+    }),
+    runtime_get: (ctx, request) => {
+        if (request.id.length === 0)
+            return { ok: false, error: "runtime_get requires id" };
+        const got = getRuntimeInspectorValue(ctx.liveSync.getRuntimeState(), ctx.liveSync.getRuntimeOverrides(), request.id, request.path);
+        if (got.kind === "missing")
+            return { ok: false, error: `runtime entity/tunable not found: ${request.id}` };
+        return { ok: true, result: got };
+    },
+    runtime_set: (ctx, request) => {
+        if (request.id.length === 0)
+            return { ok: false, error: "runtime_set requires id" };
+        const plan = planRuntimeInspectorSet(ctx.session.getState().document, {
+            id: request.id,
+            ...(request.path === undefined ? {} : { path: request.path }),
+            ...(request.value === undefined ? {} : { value: request.value }),
+            ...(request.position === undefined ? {} : { position: request.position }),
+            ...(request.rotationY === undefined ? {} : { rotationY: request.rotationY }),
+            ...(request.values === undefined ? {} : { values: request.values }),
+            ...(request.writeBack === undefined ? {} : { writeBack: request.writeBack }),
+        });
+        if (plan.error !== undefined)
+            return { ok: false, error: plan.error };
+        if (plan.tunable !== undefined) {
+            ctx.liveSync.pushRuntimeDelta({ at: Date.now(), tunables: { [plan.tunable.key]: plan.tunable.value } });
+            return {
+                ok: true,
+                result: {
+                    kind: "tunable",
+                    key: plan.tunable.key,
+                    value: plan.tunable.value,
+                    writeBack: false,
+                    ...summarizeRuntimeInspector(ctx.liveSync.getRuntimeState(), ctx.liveSync.getRuntimeOverrides(), ctx.api.getPlayControl()),
+                },
+            };
+        }
+        if (plan.entity === undefined)
+            return { ok: false, error: "runtime_set produced no entity" };
+        // Apply the document write-back first so a rejected command leaves the document — and the reverse
+        // channel — untouched. Any commands that did land are undone before bailing, keeping the edit atomic.
+        let wroteBack = false;
+        let appliedCount = 0;
+        let lastState = ctx.session.getState();
+        for (const command of plan.writeBackCommands) {
+            const { applied, state } = ctx.dispatchGuarded(command);
+            if (!applied) {
+                for (let i = 0; i < appliedCount; i += 1)
+                    ctx.session.dispatch({ type: "undo" });
+                return { ok: false, error: `runtime_set write-back rejected: ${command.type}` };
+            }
+            appliedCount += 1;
+            lastState = state;
+            wroteBack = true;
+        }
+        // Only publish the ephemeral override + delta once the document write-back (if any) has committed.
+        ctx.liveSync.setRuntimeOverride(plan.entity);
+        ctx.liveSync.pushRuntimeDelta({ at: Date.now(), entities: [plan.entity] });
+        if (wroteBack)
+            ctx.liveSync.clearRuntimeOverride(plan.entity.id);
+        return {
+            ok: true,
+            result: {
+                kind: "entity",
+                entity: plan.entity,
+                writeBack: wroteBack,
+                revision: ctx.liveSync.getRevision(),
+                ...summarizeEditorSession(lastState),
+            },
+        };
+    },
+    runtime_pause: (ctx) => {
+        const play = ctx.api.setPlayControl({ paused: true, pendingSteps: 0 });
+        ctx.liveSync.pushRuntimeDelta({ at: Date.now(), tunables: { paused: true } });
+        return { ok: true, result: { play } };
+    },
+    runtime_resume: (ctx) => {
+        const play = ctx.api.setPlayControl({ paused: false, pendingSteps: 0 });
+        ctx.liveSync.pushRuntimeDelta({ at: Date.now(), tunables: { paused: false } });
+        return { ok: true, result: { play } };
+    },
+    runtime_step: (ctx, request) => {
+        const frames = request.frames === undefined ? 1 : Math.max(1, Math.floor(request.frames));
+        // Thread the applied control back so the published delta agrees with the incremented step count.
+        const play = ctx.api.setPlayControl({ paused: true, pendingSteps: ctx.api.getPlayControl().pendingSteps + frames });
+        ctx.liveSync.pushRuntimeDelta({ at: Date.now(), tunables: { paused: true, pendingSteps: play.pendingSteps } });
+        return { ok: true, result: { play } };
+    },
+    set_runtime_override: (ctx, request) => {
+        ctx.liveSync.setRuntimeOverride(request.entity);
+        return { ok: true, result: { overrides: ctx.liveSync.getRuntimeOverrides() } };
+    },
+    clear_runtime_override: (ctx, request) => {
+        ctx.liveSync.clearRuntimeOverride(request.id);
+        return { ok: true, result: { overrides: ctx.liveSync.getRuntimeOverrides() } };
+    },
+    write_back_override: (ctx, request) => {
+        const entity = ctx.liveSync.getRuntimeOverrides()[request.id];
+        if (entity === undefined)
+            return { ok: false, error: `no runtime override for "${request.id}"` };
+        const transform = runtimeEntityWriteBackCommand(ctx.session.getState().document, entity);
+        const meta = runtimeEntityMetaWriteBackCommand(ctx.session.getState().document, entity);
+        if (transform === null && meta === null) {
+            return { ok: false, error: `override "${request.id}" has nothing to write back into the document` };
+        }
+        let lastState = ctx.session.getState();
+        for (const command of [transform, meta]) {
+            if (command === null)
+                continue;
+            const { applied, state } = ctx.dispatchGuarded(command);
+            if (!applied)
+                return { ok: false, error: `write_back_override rejected for "${request.id}"` };
+            lastState = state;
+        }
+        ctx.liveSync.clearRuntimeOverride(request.id);
+        return { ok: true, result: { revision: ctx.liveSync.getRevision(), ...summarizeEditorSession(lastState) } };
+    },
+};

package/dist/handlers/streets.d.ts

@@ -0,0 +1,3 @@
+import type { HandlerTable } from "./context.js";
+/** Document, selection, camera, mode, asset placement, and status verbs. */
+export declare const streetsHandlers: Pick<HandlerTable, "generate_streets">;

package/dist/handlers/streets.js

@@ -0,0 +1,159 @@
+import { generateStreets } from "@jgengine/core/world/streetGenerator";
+/** Fully-defaulted slider preset for an open street net (resolves to `net` in `streetNetworkMode`). */
+const NET_DEFAULTS = {
+    gridness: 0.9,
+    loopiness: 0.2,
+    connectivity: 0.35,
+    branching: 0.3,
+    deadEnds: 0.5,
+    segmentLength: 48,
+    aspect: 1,
+    winding: 0.2,
+    minCurveRadius: 30,
+    minTurnAngle: 0,
+    maxTurnAngle: 120,
+    width: 7,
+    boulevards: 0.3,
+};
+/** Fully-defaulted slider preset for a closed race circuit (resolves to `circuit` in `streetNetworkMode`). */
+const CIRCUIT_DEFAULTS = {
+    gridness: 0.1,
+    loopiness: 1,
+    connectivity: 0,
+    branching: 0,
+    deadEnds: 0,
+    segmentLength: 60,
+    aspect: 1,
+    winding: 0.5,
+    minCurveRadius: 24,
+    minTurnAngle: 0,
+    maxTurnAngle: 70,
+    width: 12,
+    boulevards: 0,
+};
+/** The numeric slider keys a caller may overlay onto the mode preset via `params`. */
+const RULE_KEYS = [
+    "gridness",
+    "loopiness",
+    "connectivity",
+    "branching",
+    "deadEnds",
+    "segmentLength",
+    "aspect",
+    "winding",
+    "minCurveRadius",
+    "minTurnAngle",
+    "maxTurnAngle",
+    "width",
+    "boulevards",
+];
+/** The tag every baked path carries in `meta.generator`, so a re-run can find and replace its own output. */
+const GENERATOR_TAG = "streetGenerator";
+/** Stable id prefix for a seed's baked paths — the idempotency key for replace-on-re-run. */
+function genPrefix(seed) {
+    return `gen-${seed}-`;
+}
+/** True when a path was baked by this generator for `seed` (matches id prefix OR the meta tag). */
+function isGeneratedForSeed(path, seed) {
+    if (path.id.startsWith(genPrefix(seed)))
+        return true;
+    const meta = path.meta;
+    return meta !== undefined && meta.generator === GENERATOR_TAG && meta.seed === seed;
+}
+/** Half-extents (hx, hz) and world origin a volume fills, so the generator grows inside its footprint. */
+function volumeFootprint(volume) {
+    if (volume.shape === "box" && volume.halfExtents !== undefined) {
+        return { hx: Math.max(1, volume.halfExtents.x), hz: Math.max(1, volume.halfExtents.z), origin: volume.center };
+    }
+    // sphere / cylinder (or a box missing halfExtents): a radius is symmetric in x/z.
+    const r = Math.max(1, volume.radius ?? 0);
+    return { hx: r, hz: r, origin: volume.center };
+}
+/** Document, selection, camera, mode, asset placement, and status verbs. */
+export const streetsHandlers = {
+    generate_streets: (ctx, request) => {
+        const doc = ctx.session.getState().document;
+        const seed = request.seed ?? "path";
+        const requestedMode = request.mode === "circuit" ? "circuit" : "net";
+        // Resolve the footprint + world origin from a named volume or from explicit bounds.
+        let hx;
+        let hz;
+        let origin;
+        if (request.volumeId !== undefined) {
+            const volume = doc.volumes.find((v) => v.id === request.volumeId);
+            if (volume === undefined)
+                return { ok: false, error: `volume not found: ${request.volumeId}` };
+            ({ hx, hz, origin } = volumeFootprint(volume));
+        }
+        else {
+            const center = request.center ?? { x: 0, y: 0, z: 0 };
+            if (request.halfX === undefined || request.halfZ === undefined) {
+                return { ok: false, error: "generate_streets requires volumeId, or center + halfX + halfZ" };
+            }
+            hx = Math.max(1, request.halfX);
+            hz = Math.max(1, request.halfZ);
+            origin = center;
+        }
+        // Build rules: mode preset, overlaid with any numeric slider overrides from `params`.
+        const preset = requestedMode === "circuit" ? CIRCUIT_DEFAULTS : NET_DEFAULTS;
+        const rules = { seed, ...preset };
+        const params = request.params;
+        if (params !== undefined) {
+            for (const key of RULE_KEYS) {
+                const value = params[key];
+                if (typeof value === "number" && Number.isFinite(value)) {
+                    rules[key] = value;
+                }
+            }
+        }
+        const network = generateStreets(rules, hx, hz);
+        // The generator resolves the ACTUAL topology from the rules; use it for the default path kind so a
+        // circuit bakes `route`s and a net bakes `road`s even when the caller's sliders cross the boundary.
+        const kind = request.kind ?? (network.mode === "circuit" ? "route" : "road");
+        const baseY = origin.y;
+        const toWorld = (street) => street.points.map(([lx, lz]) => ({ x: origin.x + lx, y: baseY, z: origin.z + lz }));
+        // Through-streets → one path each (a circuit's ring is a single closed loop street: first ≈ last).
+        const newPaths = [];
+        network.streets.forEach((street, index) => {
+            const points = toWorld(street);
+            if (points.length < 2)
+                return;
+            newPaths.push({
+                id: `${genPrefix(seed)}${index}`,
+                kind,
+                points,
+                width: street.width,
+                label: `${kind} ${index}`,
+                meta: {
+                    generator: GENERATOR_TAG,
+                    seed,
+                    mode: network.mode,
+                    level: street.level,
+                    loop: street.loop,
+                },
+            });
+        });
+        // Idempotent replace: drop this seed's prior baked paths, keep everything else, append the fresh set —
+        // all as ONE undoable structural edit via replaceDocument.
+        const kept = doc.paths.filter((p) => !isGeneratedForSeed(p, seed));
+        const nextDoc = { ...doc, paths: [...kept, ...newPaths] };
+        const { applied } = ctx.dispatchGuarded({ type: "replaceDocument", document: nextDoc });
+        if (!applied)
+            return { ok: false, error: "generate_streets: document replace had no effect" };
+        // replaceDocument clears selection; re-select the freshly baked paths for the caller.
+        ctx.session.dispatch({ type: "select", ids: newPaths.map((p) => p.id) });
+        return {
+            ok: true,
+            result: {
+                seed,
+                requestedMode,
+                mode: network.mode,
+                kind,
+                pathCount: newPaths.length,
+                removed: doc.paths.length - kept.length,
+                ids: newPaths.map((p) => p.id),
+                footprint: { hx, hz, origin },
+            },
+        };
+    },
+};

package/dist/handlers/terrain.d.ts

@@ -0,0 +1,3 @@
+import type { HandlerTable } from "./context.js";
+/** Sculpt heightfield, material painting, terrain layers, and foliage/scatter verbs. */
+export declare 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">;