@jgengine/editor 0.11.0 → 0.13.0

package/dist/handlers/terrain.js

@@ -0,0 +1,204 @@
+import { createTerrainSnapshot, editableTerrainFromSnapshot, } from "@jgengine/core/world/terraform";
+import { resolveScatter, resolveScatterRegion, scatterRegionEstimate, scatterRegionFromPath, SCATTER_PATH_KIND, } from "@jgengine/core/world/scatterRegion";
+import { TERRAIN_MATERIALS } from "../uiStore.js";
+/** Sculpt heightfield, material painting, terrain layers, and foliage/scatter verbs. */
+export const terrainHandlers = {
+    create_terrain: (ctx, request) => {
+        const width = request.width ?? 200;
+        const depth = request.depth ?? 200;
+        const cx = request.centerX ?? 0;
+        const cz = request.centerZ ?? 0;
+        const terrain = createTerrainSnapshot({
+            bounds: { minX: cx - width / 2, minZ: cz - depth / 2, maxX: cx + width / 2, maxZ: cz + depth / 2 },
+            cellSize: request.cellSize ?? 2,
+        });
+        ctx.session.dispatch({ type: "setTerrain", terrain });
+        return { ok: true, result: { cols: terrain.cols, rows: terrain.rows, cellSize: terrain.cellSize } };
+    },
+    sculpt_terrain: (ctx, request) => {
+        const terrain = ctx.session.getState().document.terrain;
+        if (terrain === undefined)
+            return { ok: false, error: "no terrain — call create_terrain first" };
+        const live = editableTerrainFromSnapshot(terrain);
+        const edit = {
+            mode: request.mode,
+            center: [request.x, request.z],
+            radius: request.radius ?? 8,
+            strength: request.strength ?? 1,
+            ...(request.target === undefined ? {} : { target: request.target }),
+            ...(request.toX === undefined || request.toZ === undefined ? {} : { to: [request.toX, request.toZ] }),
+            ...(request.seed === undefined ? {} : { seed: request.seed }),
+            ...(request.shape === undefined ? {} : { shape: request.shape }),
+        };
+        const delta = live.editDelta(edit);
+        if (delta.indices.length === 0)
+            return { ok: false, error: "brush touched no vertices (check radius/position)" };
+        ctx.session.dispatch({ type: "sculptTerrain", delta });
+        return { ok: true, result: { changed: delta.indices.length, canUndo: ctx.session.canUndo() } };
+    },
+    terrain_summary: (ctx) => {
+        const terrain = ctx.session.getState().document.terrain;
+        if (terrain === undefined)
+            return { ok: true, result: { terrain: null } };
+        let min = Infinity;
+        let max = -Infinity;
+        let nonZero = 0;
+        for (const value of terrain.offsets) {
+            if (value < min)
+                min = value;
+            if (value > max)
+                max = value;
+            if (value !== 0)
+                nonZero += 1;
+        }
+        return {
+            ok: true,
+            result: {
+                cols: terrain.cols,
+                rows: terrain.rows,
+                cellSize: terrain.cellSize,
+                bounds: terrain.bounds,
+                minOffset: terrain.offsets.length === 0 ? 0 : min,
+                maxOffset: terrain.offsets.length === 0 ? 0 : max,
+                editedVertices: nonZero,
+                paintedCells: terrain.surfaces.filter((surface) => surface !== null).length,
+            },
+        };
+    },
+    paint_terrain: (ctx, request) => {
+        const terrain = ctx.session.getState().document.terrain;
+        if (terrain === undefined)
+            return { ok: false, error: "no terrain — call create_terrain first" };
+        const live = editableTerrainFromSnapshot(terrain);
+        const delta = live.paintDelta({
+            mode: "paint",
+            center: [request.x, request.z],
+            radius: request.radius ?? 8,
+            surface: request.surface,
+            ...(request.shape === undefined ? {} : { shape: request.shape }),
+        });
+        if (delta.indices.length === 0)
+            return { ok: false, error: "paint touched no cells (check radius/position)" };
+        ctx.session.dispatch({ type: "paintTerrain", delta });
+        return { ok: true, result: { changed: delta.indices.length, canUndo: ctx.session.canUndo() } };
+    },
+    fill_terrain: (ctx, request) => {
+        const terrain = ctx.session.getState().document.terrain;
+        if (terrain === undefined)
+            return { ok: false, error: "no terrain — call create_terrain first" };
+        const live = editableTerrainFromSnapshot(terrain);
+        const delta = live.fillSurfaceDelta(request.surface);
+        if (delta.indices.length === 0)
+            return { ok: true, result: { changed: 0 } };
+        ctx.session.dispatch({ type: "paintTerrain", delta });
+        return { ok: true, result: { changed: delta.indices.length } };
+    },
+    auto_paint: (ctx, request) => {
+        const terrain = ctx.session.getState().document.terrain;
+        if (terrain === undefined)
+            return { ok: false, error: "no terrain — call create_terrain first" };
+        const live = editableTerrainFromSnapshot(terrain);
+        const rule = {
+            surface: request.surface,
+            ...(request.minSlope === undefined ? {} : { minSlope: request.minSlope }),
+            ...(request.maxSlope === undefined ? {} : { maxSlope: request.maxSlope }),
+            ...(request.minHeight === undefined ? {} : { minHeight: request.minHeight }),
+            ...(request.maxHeight === undefined ? {} : { maxHeight: request.maxHeight }),
+        };
+        const delta = live.autoPaintDelta(rule);
+        if (delta.indices.length === 0)
+            return { ok: true, result: { changed: 0 } };
+        ctx.session.dispatch({ type: "paintTerrain", delta });
+        return { ok: true, result: { changed: delta.indices.length } };
+    },
+    terrain_materials: () => ({ ok: true, result: { materials: TERRAIN_MATERIALS } }),
+    terrain_layers: (ctx) => {
+        const terrain = ctx.session.getState().document.terrain;
+        return { ok: true, result: { layers: terrain?.layers ?? [] } };
+    },
+    set_terrain_layers: (ctx, request) => {
+        if (ctx.session.getState().document.terrain === undefined) {
+            return { ok: false, error: "no terrain — call create_terrain first" };
+        }
+        ctx.session.dispatch({ type: "setTerrainLayers", layers: request.layers });
+        return { ok: true, result: { layers: ctx.session.getState().document.terrain?.layers ?? [] } };
+    },
+    blend_terrain: (ctx, request) => {
+        const terrain = ctx.session.getState().document.terrain;
+        if (terrain === undefined)
+            return { ok: false, error: "no terrain — call create_terrain first" };
+        // Auto-add the surface as a layer if the stack does not carry it yet.
+        const layers = terrain.layers ?? [];
+        if (!layers.some((layer) => layer.surface === request.surface)) {
+            const next = [...layers, { id: request.surface, surface: request.surface }];
+            ctx.session.dispatch({ type: "setTerrainLayers", layers: next });
+        }
+        const snapshot = ctx.session.getState().document.terrain;
+        if (snapshot === undefined)
+            return { ok: false, error: "no terrain — call create_terrain first" };
+        const live = editableTerrainFromSnapshot(snapshot);
+        const delta = live.blendPaintDelta({
+            mode: "paint",
+            center: [request.x, request.z],
+            radius: request.radius ?? 8,
+            surface: request.surface,
+            strength: request.strength ?? 1,
+            ...(request.shape === undefined ? {} : { shape: request.shape }),
+        });
+        if (delta.indices.length === 0)
+            return { ok: false, error: "blend touched no cells (check radius/position)" };
+        ctx.session.dispatch({ type: "blendTerrain", delta });
+        return { ok: true, result: { changed: delta.indices.length, layers: ctx.session.getState().document.terrain?.layers ?? [] } };
+    },
+    convert_scatter: (ctx, request) => {
+        const doc = ctx.session.getState().document;
+        const path = doc.paths.find((entry) => entry.id === request.pathId);
+        if (path === undefined)
+            return { ok: false, error: `path not found: ${request.pathId}` };
+        const region = scatterRegionFromPath(path);
+        if (region === null)
+            return { ok: false, error: `not a scatter region: ${request.pathId}` };
+        const terrainSnapshot = doc.terrain;
+        const terrain = terrainSnapshot === undefined ? undefined : editableTerrainFromSnapshot(terrainSnapshot);
+        const instances = resolveScatterRegion(region, terrain);
+        const markers = instances.map((instance) => ({
+            id: instance.id.replace(/[^a-zA-Z0-9_]/g, "_"),
+            kind: "prop",
+            position: { x: instance.x, y: instance.y, z: instance.z },
+            rotationY: instance.rotationY,
+            meta: { item: instance.item, scale: instance.scale, fromScatter: request.pathId },
+        }));
+        ctx.session.dispatch({ type: "convertScatterToObjects", pathId: request.pathId, markers });
+        return { ok: true, result: { created: markers.length, removedPath: request.pathId } };
+    },
+    add_foliage: (ctx, request) => {
+        if (request.points.length < 3)
+            return { ok: false, error: "add_foliage needs at least 3 polygon points" };
+        const id = `foliage_${Date.now().toString(36)}`;
+        ctx.session.dispatch({
+            type: "addPath",
+            path: {
+                id,
+                kind: SCATTER_PATH_KIND,
+                points: request.points.map((point) => ({ x: point.x, y: 0, z: point.z })),
+                label: "foliage",
+                meta: {
+                    density: request.density ?? 0.15,
+                    ...(request.item === undefined ? {} : { item: request.item }),
+                    ...(request.seed === undefined ? {} : { seed: request.seed }),
+                    ...(request.minSpacing === undefined ? {} : { minSpacing: request.minSpacing }),
+                },
+            },
+        });
+        const path = ctx.session.getState().document.paths.find((p) => p.id === id);
+        if (path === undefined)
+            return { ok: false, error: `add_foliage failed to create region: ${id}` };
+        return { ok: true, result: { id, estimate: scatterRegionEstimate(path) } };
+    },
+    scatter_summary: (ctx) => {
+        const doc = ctx.session.getState().document;
+        const regions = doc.paths.filter((path) => path.kind === SCATTER_PATH_KIND).length;
+        const instances = resolveScatter(doc).length;
+        return { ok: true, result: { regions, instances } };
+    },
+};

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { EditorApp, type EditorAppProps, type EditorSaveFn } from "./EditorApp.js";
-export { StandaloneEditor, createBlankPlayable, blankWorld, downloadSaver, type StandaloneEditorProps, type StandaloneAsset, type BlankPlayableOptions, } from "./StandaloneEditor.js";
+export { buildEditorNetworkSnapshot, isNetworkMultiplayerConfigured, type EditorNetworkAdapterKind, type EditorNetworkPresenceActor, type EditorNetworkPresenceInput, type EditorNetworkSession, type EditorNetworkSnapshot, } from "./networkSnapshot.js";
+export { StandaloneEditor, createBlankPlayable, blankWorld, downloadSaver, importAssetToHost, loadDroppedAssets, mergeStandaloneAssets, type StandaloneEditorProps, type StandaloneAsset, type AssetImporter, type BlankPlayableOptions, } from "./StandaloneEditor.js";
 export { EditorLayerOverlays, PathDraftPreview } from "./DebugDraw.js";
 export { EditorChrome } from "./EditorChrome.js";
 export { SelectionGizmo, ViewportSelect } from "./SelectionGizmo.js";
@@ -7,7 +8,7 @@ export { createEditorUiStore, newPlacementId, DEFAULT_SCULPT_SETTINGS, DEFAULT_P
 export { TerrainSculpt } from "./TerrainSculpt.js";
 export { ScatterPreview } from "./ScatterPreview.js";
 export { EditorCameraDriver } from "./EditorCameraDriver.js";
-export { AssetBrowser, assetsFromCatalog, type EditorAssetEntry } from "./AssetBrowser.js";
+export { AssetBrowser, assetsFromCatalog, editorAssetFromImport, mergeEditorAssets, type EditorAssetEntry, } from "./AssetBrowser.js";
 export { createEditorHost, getEditorHost, installEditorHost, type EditorAssetInfo, type EditorBridgeRequest, type EditorBridgeResponse, type EditorHostApi, type EditorPerfSample, type EditorRunMode, } from "./session.js";
 export { PerfProbe } from "./PerfProbe.js";
 export { useStoreSelector, shallowArrayEqual, virtualWindow, type SubscribableStore, type VirtualWindow, } from "./useStoreSelector.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 export { EditorApp } from "./EditorApp.js";
-export { StandaloneEditor, createBlankPlayable, blankWorld, downloadSaver, } from "./StandaloneEditor.js";
+export { buildEditorNetworkSnapshot, isNetworkMultiplayerConfigured, } from "./networkSnapshot.js";
+export { StandaloneEditor, createBlankPlayable, blankWorld, downloadSaver, importAssetToHost, loadDroppedAssets, mergeStandaloneAssets, } from "./StandaloneEditor.js";
 export { EditorLayerOverlays, PathDraftPreview } from "./DebugDraw.js";
 export { EditorChrome } from "./EditorChrome.js";
 export { SelectionGizmo, ViewportSelect } from "./SelectionGizmo.js";
@@ -7,7 +8,7 @@ export { createEditorUiStore, newPlacementId, DEFAULT_SCULPT_SETTINGS, DEFAULT_P
 export { TerrainSculpt } from "./TerrainSculpt.js";
 export { ScatterPreview } from "./ScatterPreview.js";
 export { EditorCameraDriver } from "./EditorCameraDriver.js";
-export { AssetBrowser, assetsFromCatalog } from "./AssetBrowser.js";
+export { AssetBrowser, assetsFromCatalog, editorAssetFromImport, mergeEditorAssets, } from "./AssetBrowser.js";
 export { createEditorHost, getEditorHost, installEditorHost, } from "./session.js";
 export { PerfProbe } from "./PerfProbe.js";
 export { useStoreSelector, shallowArrayEqual, virtualWindow, } from "./useStoreSelector.js";

package/dist/listDocumentTriggers.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure collect of authored behavior triggers from a scene document for the scripting workspace.
+ * Object-centric: one row per marker/volume that carries at least one valid on/action binding.
+ * Runtime dispatch still uses {@link collectAuthoredTriggers}; this is the editor list model.
+ */
+import { type TriggerEvent, type TriggerSourceKind } from "@jgengine/core/scene/authoredTriggers";
+import type { SceneDocumentLike, SceneMarkerLike, SceneVolumeLike } from "@jgengine/core/world/sceneShapes";
+/** One on/action binding shown on a document trigger row. */
+export interface DocumentTriggerBinding {
+    on: TriggerEvent;
+    action: string;
+}
+/**
+ * A marker or volume that owns one or more authored triggers, with a display label for the
+ * scripting workspace list.
+ */
+export interface DocumentTriggerEntry {
+    sourceId: string;
+    sourceKind: TriggerSourceKind;
+    objectKind: string;
+    /** Marker/volume label when present; otherwise the object id. */
+    label: string;
+    bindings: readonly DocumentTriggerBinding[];
+}
+/** Document slice the list helper needs — `EditorDocument` satisfies this structurally. */
+export interface DocumentTriggersSource {
+    markers: readonly (SceneMarkerLike & {
+        label?: string;
+    })[];
+    volumes: readonly (SceneVolumeLike & {
+        label?: string;
+    })[];
+}
+/**
+ * List every marker and volume on `document` that has at least one valid authored trigger.
+ * Pure — no session, registry, or runtime state. Markers are listed before volumes; order within
+ * each collection matches the document. Prefer this over {@link collectAuthoredTriggers} when the
+ * UI wants one row per object rather than one row per binding.
+ *
+ * @internal
+ */
+export declare function listDocumentTriggers(document: DocumentTriggersSource | SceneDocumentLike): DocumentTriggerEntry[];

package/dist/listDocumentTriggers.js

@@ -0,0 +1,49 @@
+/**
+ * Pure collect of authored behavior triggers from a scene document for the scripting workspace.
+ * Object-centric: one row per marker/volume that carries at least one valid on/action binding.
+ * Runtime dispatch still uses {@link collectAuthoredTriggers}; this is the editor list model.
+ */
+import { readTriggerSpecs, } from "@jgengine/core/scene/authoredTriggers";
+function labelOf(object) {
+    const label = object.label;
+    return typeof label === "string" && label.length > 0 ? label : object.id;
+}
+function bindingsFromMeta(meta) {
+    return readTriggerSpecs(meta).map((spec) => ({ on: spec.on, action: spec.action }));
+}
+/**
+ * List every marker and volume on `document` that has at least one valid authored trigger.
+ * Pure — no session, registry, or runtime state. Markers are listed before volumes; order within
+ * each collection matches the document. Prefer this over {@link collectAuthoredTriggers} when the
+ * UI wants one row per object rather than one row per binding.
+ *
+ * @internal
+ */
+export function listDocumentTriggers(document) {
+    const out = [];
+    for (const marker of document.markers) {
+        const bindings = bindingsFromMeta(marker.meta);
+        if (bindings.length === 0)
+            continue;
+        out.push({
+            sourceId: marker.id,
+            sourceKind: "marker",
+            objectKind: marker.kind,
+            label: labelOf(marker),
+            bindings,
+        });
+    }
+    for (const volume of document.volumes) {
+        const bindings = bindingsFromMeta(volume.meta);
+        if (bindings.length === 0)
+            continue;
+        out.push({
+            sourceId: volume.id,
+            sourceKind: "volume",
+            objectKind: volume.kind,
+            label: labelOf(volume),
+            bindings,
+        });
+    }
+    return out;
+}

package/dist/materialAssignments.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Document-wide material assignment inventory for the Materials workspace.
+ * Reads real `meta.materialId` stamps from placeables — no thumbnails or faked previews.
+ */
+/** Placeable families that carry `meta.materialId` under assign_material. */
+export type MaterialObjectKind = "marker" | "volume" | "path";
+/** One object row in the materials workspace browser. */
+export interface MaterialAssignmentRow {
+    id: string;
+    label: string;
+    kind: string;
+    objectKind: MaterialObjectKind;
+    /** Present material id, or null when none is assigned. */
+    materialId: string | null;
+}
+/** Minimal document slice the materials inventory needs. */
+export interface MaterialDocumentSlice {
+    markers: readonly {
+        id: string;
+        kind: string;
+        label?: string;
+        meta?: Record<string, unknown>;
+    }[];
+    volumes: readonly {
+        id: string;
+        kind: string;
+        label?: string;
+        meta?: Record<string, unknown>;
+    }[];
+    paths: readonly {
+        id: string;
+        kind: string;
+        label?: string;
+        meta?: Record<string, unknown>;
+    }[];
+}
+/** Filter for {@link filterMaterialAssignments}. */
+export type MaterialAssignmentFilter = "all" | "assigned" | "unassigned" | {
+    materialId: string;
+};
+/**
+ * Lists every marker/volume/path with its current material assignment (or null).
+ * Order is document order: markers, then volumes, then paths.
+ *
+ * @internal
+ */
+export declare function listMaterialAssignments(document: MaterialDocumentSlice): MaterialAssignmentRow[];
+/**
+ * Filters material rows by text query (id/label/kind/materialId) and optional assignment filter.
+ * Case-insensitive; empty query is a no-op on text.
+ *
+ * @internal
+ */
+export declare function filterMaterialAssignments(rows: readonly MaterialAssignmentRow[], query: string, filter?: MaterialAssignmentFilter): MaterialAssignmentRow[];
+/**
+ * Aggregates how many placeables use each material id (assigned only). Sorted by count desc, then id.
+ *
+ * @internal
+ */
+export declare function summarizeMaterialUsage(rows: readonly MaterialAssignmentRow[]): readonly {
+    materialId: string;
+    count: number;
+}[];

package/dist/materialAssignments.js

@@ -0,0 +1,84 @@
+/**
+ * Document-wide material assignment inventory for the Materials workspace.
+ * Reads real `meta.materialId` stamps from placeables — no thumbnails or faked previews.
+ */
+function readMaterialId(meta) {
+    const value = meta?.["materialId"];
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+/**
+ * Lists every marker/volume/path with its current material assignment (or null).
+ * Order is document order: markers, then volumes, then paths.
+ *
+ * @internal
+ */
+export function listMaterialAssignments(document) {
+    const rows = [];
+    for (const marker of document.markers) {
+        rows.push({
+            id: marker.id,
+            label: marker.label ?? marker.id,
+            kind: marker.kind,
+            objectKind: "marker",
+            materialId: readMaterialId(marker.meta),
+        });
+    }
+    for (const volume of document.volumes) {
+        rows.push({
+            id: volume.id,
+            label: volume.label ?? volume.id,
+            kind: volume.kind,
+            objectKind: "volume",
+            materialId: readMaterialId(volume.meta),
+        });
+    }
+    for (const path of document.paths) {
+        rows.push({
+            id: path.id,
+            label: path.label ?? path.id,
+            kind: path.kind,
+            objectKind: "path",
+            materialId: readMaterialId(path.meta),
+        });
+    }
+    return rows;
+}
+/**
+ * Filters material rows by text query (id/label/kind/materialId) and optional assignment filter.
+ * Case-insensitive; empty query is a no-op on text.
+ *
+ * @internal
+ */
+export function filterMaterialAssignments(rows, query, filter = "all") {
+    const needle = query.trim().toLowerCase();
+    return rows.filter((row) => {
+        if (filter === "assigned" && row.materialId === null)
+            return false;
+        if (filter === "unassigned" && row.materialId !== null)
+            return false;
+        if (typeof filter === "object" && row.materialId !== filter.materialId)
+            return false;
+        if (needle.length === 0)
+            return true;
+        return (row.id.toLowerCase().includes(needle) ||
+            row.label.toLowerCase().includes(needle) ||
+            row.kind.toLowerCase().includes(needle) ||
+            (row.materialId !== null && row.materialId.toLowerCase().includes(needle)));
+    });
+}
+/**
+ * Aggregates how many placeables use each material id (assigned only). Sorted by count desc, then id.
+ *
+ * @internal
+ */
+export function summarizeMaterialUsage(rows) {
+    const counts = new Map();
+    for (const row of rows) {
+        if (row.materialId === null)
+            continue;
+        counts.set(row.materialId, (counts.get(row.materialId) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .map(([materialId, count]) => ({ materialId, count }))
+        .sort((a, b) => b.count - a.count || a.materialId.localeCompare(b.materialId));
+}

package/dist/mcp/fieldSpec.d.ts

@@ -0,0 +1,32 @@
+import type { EditorBridgeRequest } from "../session.js";
+/** The value type a request field is expected to carry. */
+export type RpcFieldKind = "string" | "number" | "boolean" | "string[]" | "object" | "object[]" | "vec3" | "value";
+/** One field's expected shape in a request; `oneOf`/`nullable`/`required`/`of` refine the check. */
+export interface RpcFieldSpec {
+    name: string;
+    kind: RpcFieldKind;
+    nullable?: boolean;
+    oneOf?: readonly string[];
+    /** True when the field is mandatory — surfaced in the generated MCP `required` array. */
+    required?: boolean;
+    /** For `object`/`object[]`: the element/object's own field specs, so nested schemas stay expressive. */
+    of?: readonly RpcFieldSpec[];
+}
+/**
+ * Per-method field type table — the single source of truth for the RPC boundary. A field listed here
+ * is type-checked when present (see `decodeEditorBridgeRequest`); existence is left to
+ * `EditorHostApi.handle` (whose per-method guards return honest `ok:false` diagnostics for
+ * missing/unknown targets). Type-checking presented fields is what keeps a fuzzed value — a string
+ * where a number belongs, a scalar where an object belongs — from reaching a live session uncoerced.
+ * Unknown extra fields are ignored so a superset payload stays forward-compatible.
+ *
+ * The same table generates the MCP tool `inputSchema`s (see `mcp/tools.ts`), so `required`/`oneOf`/
+ * `of` here also shape what agents are told a tool accepts. The `Record<EditorBridgeRequest["method"],
+ * …>` type is the lockstep guarantee: adding a method to the union in `session.ts` fails to compile
+ * here until it gets a schema, and a stale entry is a compile error too.
+ */
+export declare const RPC_FIELD_SCHEMAS: Record<EditorBridgeRequest["method"], readonly RpcFieldSpec[]>;
+/** The set of known RPC method names — exported for meta/manifest tooling and tests. @internal */
+export declare const EDITOR_BRIDGE_METHOD_NAMES: readonly string[];
+/** Generates the MCP tool `inputSchema` for a method from its {@link RPC_FIELD_SCHEMAS} entry. */
+export declare function buildInputSchema(method: EditorBridgeRequest["method"]): Record<string, unknown>;