@jgengine/editor 0.10.0 → 0.11.0

package/dist/mcp/tools.js

@@ -761,4 +761,153 @@ export const EDITOR_MCP_TOOLS = [
             additionalProperties: false,
         },
     },
+    {
+        name: "list_grids",
+        description: "List the scene document's grid/tile layers (id, kind, bounds, cell count, palette ids).",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    },
+    {
+        name: "get_grid_cell",
+        description: "Eyedrop: read the value id at col,row of a grid layer (empty value for unset/out-of-bounds cells).",
+        inputSchema: {
+            type: "object",
+            properties: { id: { type: "string" }, col: { type: "number" }, row: { type: "number" } },
+            required: ["id", "col", "row"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "add_grid_layer",
+        description: "Create an empty grid/tile layer on the scene document with the given bounds, cell size, and palette.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                kind: { type: "string" },
+                cols: { type: "number" },
+                rows: { type: "number" },
+                label: { type: "string" },
+                cellSize: { type: "number" },
+                origin: { type: "object", properties: { x: { type: "number" }, y: { type: "number" }, z: { type: "number" } }, required: ["x", "y", "z"], additionalProperties: false },
+                axes: { type: "string", enum: ["xz", "xy"] },
+                empty: { type: "string" },
+                palette: { type: "array", items: { type: "object" } },
+            },
+            required: ["id", "kind", "cols", "rows"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "remove_grid_layer",
+        description: "Delete a grid/tile layer from the scene document by id.",
+        inputSchema: {
+            type: "object",
+            properties: { id: { type: "string" } },
+            required: ["id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "set_grid_layer",
+        description: "Patch a grid layer's metadata — label, kind, visibility, empty value, cell size, origin, axes, or palette.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                label: { type: "string" },
+                kind: { type: "string" },
+                visible: { type: "boolean" },
+                empty: { type: "string" },
+                cellSize: { type: "number" },
+                origin: { type: "object", properties: { x: { type: "number" }, y: { type: "number" }, z: { type: "number" } }, required: ["x", "y", "z"], additionalProperties: false },
+                axes: { type: "string", enum: ["xz", "xy"] },
+                palette: { type: "array", items: { type: "object" } },
+            },
+            required: ["id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "paint_grid_cells",
+        description: "Paint or erase grid cells (value equal to the layer's empty value erases). One undo step for the whole batch.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                cells: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: { col: { type: "number" }, row: { type: "number" }, value: { type: "string" } },
+                        required: ["col", "row", "value"],
+                        additionalProperties: false,
+                    },
+                },
+            },
+            required: ["id", "cells"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "fill_grid_rect",
+        description: "Rectangle tool: fill the inclusive col0,row0..col1,row1 rectangle of a grid layer with one value.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                col0: { type: "number" },
+                row0: { type: "number" },
+                col1: { type: "number" },
+                row1: { type: "number" },
+                value: { type: "string" },
+            },
+            required: ["id", "col0", "row0", "col1", "row1", "value"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "flood_fill_grid",
+        description: "Bucket tool: flood-fill the contiguous region sharing the seed cell's value with a new value.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                col: { type: "number" },
+                row: { type: "number" },
+                value: { type: "string" },
+            },
+            required: ["id", "col", "row", "value"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "resize_grid_layer",
+        description: "Resize a grid layer's bounds to cols x rows, trimming any cells outside the new extent.",
+        inputSchema: {
+            type: "object",
+            properties: { id: { type: "string" }, cols: { type: "number" }, rows: { type: "number" } },
+            required: ["id", "cols", "rows"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "import_grid",
+        description: "Import an ASCII/glyph map or CSV into a new grid layer (the ASCII/CSV is an import adapter, not the stored form).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                kind: { type: "string" },
+                format: { type: "string", enum: ["ascii", "csv"] },
+                text: { type: "string" },
+                empty: { type: "string" },
+                cellSize: { type: "number" },
+                origin: { type: "object", properties: { x: { type: "number" }, y: { type: "number" }, z: { type: "number" } }, required: ["x", "y", "z"], additionalProperties: false },
+                glyphMap: { type: "object" },
+                palette: { type: "array", items: { type: "object" } },
+            },
+            required: ["id", "kind", "format", "text"],
+            additionalProperties: false,
+        },
+    },
 ];

package/dist/perfPill.d.ts

@@ -0,0 +1,21 @@
+/** Toolbar perf-pill health, separating an idle render-on-demand loop from a genuinely slow frame. */
+export type EditorPerfTone = "idle" | "healthy" | "busy";
+/**
+ * FPS at or below which an *actively rendering* editor frame is treated as struggling.
+ * Only applied when the loop is active — an idle / browser-throttled loop never trips it.
+ */
+export declare const EDITOR_PERF_LOW_FPS = 30;
+/**
+ * Classify a perf sample for the toolbar pill. The editor renders `frameloop="always"`, so a
+ * healthy visible loop sits at ~60fps; a low wall-clock fps only appears when the browser throttles
+ * rAF (backgrounded tab / headless screenshot) while nothing is happening. `PerfProbe` measures
+ * that idleness (no camera move, no raycast/rebuild, no scene change) and reports it as `active:false`,
+ * which classifies here as `"idle"` instead of the red danger cue. The danger cue (`"busy"`) is
+ * reserved for sustained low fps while the loop is genuinely active (orbit / drag / sculpt) — the
+ * regression actually worth surfacing.
+ * @internal — drives the editor toolbar perf pill; not game-facing.
+ */
+export declare function classifyEditorPerf(sample: {
+    fps: number;
+    active: boolean;
+}): EditorPerfTone;

package/dist/perfPill.js

@@ -0,0 +1,20 @@
+/**
+ * FPS at or below which an *actively rendering* editor frame is treated as struggling.
+ * Only applied when the loop is active — an idle / browser-throttled loop never trips it.
+ */
+export const EDITOR_PERF_LOW_FPS = 30;
+/**
+ * Classify a perf sample for the toolbar pill. The editor renders `frameloop="always"`, so a
+ * healthy visible loop sits at ~60fps; a low wall-clock fps only appears when the browser throttles
+ * rAF (backgrounded tab / headless screenshot) while nothing is happening. `PerfProbe` measures
+ * that idleness (no camera move, no raycast/rebuild, no scene change) and reports it as `active:false`,
+ * which classifies here as `"idle"` instead of the red danger cue. The danger cue (`"busy"`) is
+ * reserved for sustained low fps while the loop is genuinely active (orbit / drag / sculpt) — the
+ * regression actually worth surfacing.
+ * @internal — drives the editor toolbar perf pill; not game-facing.
+ */
+export function classifyEditorPerf(sample) {
+    if (!sample.active)
+        return "idle";
+    return sample.fps < EDITOR_PERF_LOW_FPS ? "busy" : "healthy";
+}

package/dist/session.d.ts

@@ -1,4 +1,4 @@
-import { type DocumentLiveSync, type DocumentPatch, type EditorCatalogDefinition, type EditorCommand, type EditorDocument, type EditorKindVisibility, type EditorLayersInput, type EditorSession, type EditorSessionState, type RuntimeEntityState, type RuntimePlayControl } from "@jgengine/core/editor/index";
+import { type DocumentLiveSync, type DocumentPatch, type EditorCatalogDefinition, type EditorCommand, type EditorDocument, type EditorGridPaletteEntry, type EditorKindVisibility, type EditorLayersInput, type EditorSession, type EditorSessionState, type RuntimeEntityState, type RuntimePlayControl } from "@jgengine/core/editor/index";
 import { type TerraformMode, type TerrainMaterialLayer } from "@jgengine/core/world/terraform";
 /** How the editor hosts the game: frozen placement view, roamable world, or the real game. */
 export type EditorRunMode = "edit" | "walk" | "play";
@@ -246,6 +246,89 @@ export type EditorBridgeRequest = {
     method: "assign_material";
     ids: string[];
     materialId: string;
+} | {
+    method: "list_grids";
+} | {
+    method: "get_grid_cell";
+    id: string;
+    col: number;
+    row: number;
+} | {
+    method: "add_grid_layer";
+    id: string;
+    kind: string;
+    cols: number;
+    rows: number;
+    label?: string;
+    cellSize?: number;
+    origin?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    axes?: "xz" | "xy";
+    empty?: string;
+    palette?: EditorGridPaletteEntry[];
+} | {
+    method: "remove_grid_layer";
+    id: string;
+} | {
+    method: "set_grid_layer";
+    id: string;
+    label?: string;
+    kind?: string;
+    visible?: boolean;
+    empty?: string;
+    cellSize?: number;
+    origin?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    axes?: "xz" | "xy";
+    palette?: EditorGridPaletteEntry[];
+} | {
+    method: "paint_grid_cells";
+    id: string;
+    cells: {
+        col: number;
+        row: number;
+        value: string;
+    }[];
+} | {
+    method: "fill_grid_rect";
+    id: string;
+    col0: number;
+    row0: number;
+    col1: number;
+    row1: number;
+    value: string;
+} | {
+    method: "flood_fill_grid";
+    id: string;
+    col: number;
+    row: number;
+    value: string;
+} | {
+    method: "resize_grid_layer";
+    id: string;
+    cols: number;
+    rows: number;
+} | {
+    method: "import_grid";
+    id: string;
+    kind: string;
+    format: "ascii" | "csv";
+    text: string;
+    empty?: string;
+    cellSize?: number;
+    origin?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    glyphMap?: Record<string, string>;
+    palette?: EditorGridPaletteEntry[];
 } | {
     method: "push_document_patch";
     patch: DocumentPatch;
@@ -324,6 +407,12 @@ export interface EditorPerfSample {
     drawCalls: number;
     triangles: number;
     sampledAt: number;
+    /**
+     * Whether the sampled window saw camera or edit activity. `false` means the render-on-demand /
+     * browser-throttled loop is idle, so a low `fps` is expected pacing rather than lag — the pill
+     * shows a neutral "idle" instead of the red danger cue.
+     */
+    active: boolean;
     /** Avg viewport raycast (pick) time this window — editor-authoring cost, not sim cost. */
     raycastMs?: number;
     /** Avg preview-mesh rebuild (displace) time this window — editor-authoring cost, not sim cost. */

package/dist/session.js

@@ -1,4 +1,4 @@
-import { createDocumentLiveSync, createEditorSession, createRuntimePlayControl, editorChildren, editorDocumentBounds, editorParentOf, editorRoots, findEditorCatalog, findEditorCatalogEntry, findEditorCollection, findEditorPrefab, getRuntimeInspectorValue, installDocumentLiveSync, listEditorKinds, normalizeEditorLayers, planRuntimeInspectorSet, runtimeEntityMetaWriteBackCommand, runtimeEntityWriteBackCommand, seedEditorCatalogs, summarizeEditorSession, summarizeRuntimeInspector, } from "@jgengine/core/editor/index";
+import { createDocumentLiveSync, createEditorSession, createRuntimePlayControl, editorChildren, editorDocumentBounds, editorParentOf, editorRoots, findEditorCatalog, findEditorCatalogEntry, findEditorCollection, findEditorPrefab, getRuntimeInspectorValue, installDocumentLiveSync, listEditorKinds, normalizeEditorLayers, planRuntimeInspectorSet, runtimeEntityMetaWriteBackCommand, runtimeEntityWriteBackCommand, seedEditorCatalogs, summarizeEditorSession, summarizeRuntimeInspector, createGridLayer, eyedropGridCell, gridCellCount, importAsciiGrid, importCsvGrid, } from "@jgengine/core/editor/index";
 import { createTerrainSnapshot, editableTerrainFromSnapshot, } from "@jgengine/core/world/terraform";
 import { resolvePlaceAsset, toEditorMarker } from "@jgengine/core/world/placeAsset";
 import { resolveScatter, resolveScatterRegion, scatterRegionEstimate, scatterRegionFromPath, SCATTER_PATH_KIND, } from "@jgengine/core/world/scatterRegion";
@@ -22,6 +22,20 @@ function findMetaTarget(doc, id) {
         return { target: "note", kind: "note", meta: note.meta };
     return null;
 }
+/** 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),
+    };
+}
 /** Validates a merged meta bag against a registered kind's schema; returns an error string or null. */
 function validateMetaForKind(kind, meta) {
     const definition = getSceneKind(kind);
@@ -1012,6 +1026,130 @@ export function createEditorHost(options) {
                     case "assign_material":
                         session.dispatch({ type: "assignMaterial", ids: request.ids, materialId: request.materialId });
                         return { ok: true, result: summarizeEditorSession(session.getState()) };
+                    case "list_grids": {
+                        const grids = session.getState().document.grids ?? [];
+                        return { ok: true, result: { grids: grids.map(gridLayerSummary) } };
+                    }
+                    case "get_grid_cell": {
+                        const layer = (session.getState().document.grids ?? []).find((entry) => entry.id === request.id);
+                        if (layer === undefined)
+                            return { ok: false, error: `grid layer not found: ${request.id}` };
+                        return { ok: true, result: { id: request.id, col: request.col, row: request.row, value: eyedropGridCell(layer, request.col, request.row) } };
+                    }
+                    case "add_grid_layer": {
+                        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 } = dispatchGuarded({ type: "addGridLayer", layer });
+                        if (!applied)
+                            return { ok: false, error: "add_grid_layer rejected: no effect" };
+                        return { ok: true, result: gridLayerSummary(layer) };
+                    }
+                    case "remove_grid_layer": {
+                        const { applied } = 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 } };
+                    }
+                    case "set_grid_layer": {
+                        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 } = dispatchGuarded({ type: "setGridLayer", id: request.id, patch });
+                        if (!applied)
+                            return { ok: false, error: `set_grid_layer rejected: no effect (${request.id})` };
+                        const layer = (state.document.grids ?? []).find((entry) => entry.id === request.id);
+                        return { ok: true, result: gridLayerSummary(layer) };
+                    }
+                    case "paint_grid_cells": {
+                        const { applied, state } = dispatchGuarded({ type: "paintGridCells", id: request.id, cells: request.cells });
+                        if (!applied)
+                            return { ok: false, error: `paint_grid_cells rejected: no effect (${request.id})` };
+                        const layer = (state.document.grids ?? []).find((entry) => entry.id === request.id);
+                        return { ok: true, result: gridLayerSummary(layer) };
+                    }
+                    case "fill_grid_rect": {
+                        const { applied, state } = 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})` };
+                        const layer = (state.document.grids ?? []).find((entry) => entry.id === request.id);
+                        return { ok: true, result: gridLayerSummary(layer) };
+                    }
+                    case "flood_fill_grid": {
+                        const { applied, state } = 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})` };
+                        const layer = (state.document.grids ?? []).find((entry) => entry.id === request.id);
+                        return { ok: true, result: gridLayerSummary(layer) };
+                    }
+                    case "resize_grid_layer": {
+                        const { applied, state } = 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})` };
+                        const layer = (state.document.grids ?? []).find((entry) => entry.id === request.id);
+                        return { ok: true, result: gridLayerSummary(layer) };
+                    }
+                    case "import_grid": {
+                        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 } = dispatchGuarded({ type: "addGridLayer", layer });
+                        if (!applied)
+                            return { ok: false, error: "import_grid rejected: no effect" };
+                        return { ok: true, result: gridLayerSummary(layer) };
+                    }
                 }
             }
             catch (error) {

package/dist/terrainReadoutStore.d.ts

@@ -0,0 +1,19 @@
+import type { ElevationReadout, ElevationSummary } from "@jgengine/core/world/terrainGuides";
+/** Live, transient terrain-readability feedback shared by the viewport overlay and the HUD legend. */
+export interface TerrainReadoutState {
+    /** Elevation under the pointer, or `null` when the pointer is off the terrain. */
+    cursor: ElevationReadout | null;
+    /** Elevation stats for the readout region (whole terrain), or `null` before the first build. */
+    summary: ElevationSummary | null;
+    /** The contour interval the overlay chose for the current relief; `0` when flat. */
+    interval: number;
+}
+/** Subscribable store for transient terrain-readout feedback (not persisted — it is live measurement). */
+export interface TerrainReadoutStore {
+    getState(): TerrainReadoutState;
+    setCursor(cursor: ElevationReadout | null): void;
+    setSummary(summary: ElevationSummary | null, interval: number): void;
+    subscribe(listener: () => void): () => void;
+}
+/** Creates the readout store the terrain overlay writes and the HUD reads. */
+export declare function createTerrainReadoutStore(): TerrainReadoutStore;

package/dist/terrainReadoutStore.js

@@ -0,0 +1,36 @@
+/** Creates the readout store the terrain overlay writes and the HUD reads. */
+export function createTerrainReadoutStore() {
+    let state = { cursor: null, summary: null, interval: 0 };
+    const listeners = new Set();
+    const emit = () => {
+        for (const listener of listeners)
+            listener();
+    };
+    return {
+        getState: () => state,
+        setCursor(cursor) {
+            const prev = state.cursor;
+            if (prev === cursor)
+                return;
+            if (prev !== null &&
+                cursor !== null &&
+                prev.height === cursor.height &&
+                prev.x === cursor.x &&
+                prev.z === cursor.z) {
+                return;
+            }
+            state = { ...state, cursor };
+            emit();
+        },
+        setSummary(summary, interval) {
+            state = { ...state, summary, interval };
+            emit();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}

package/dist/uiStore.d.ts

@@ -76,6 +76,12 @@ export interface EditorUiState {
     snapMode: SnapMode;
     gridSize: number;
     showGrid: boolean;
+    /** Surface-following iso-elevation contour overlay (terrain readability). */
+    showContours: boolean;
+    /** Terrain-draped reference grid overlay that climbs relief instead of being occluded by it. */
+    showSurfaceGrid: boolean;
+    /** Measurable elevation HUD: cursor height/delta, region min/max/mean, contour interval. */
+    showElevation: boolean;
     placement: PlacementTool | null;
     pathDraft: readonly EditorVec3[];
     pathPoint: {

package/dist/uiStore.js

@@ -40,6 +40,9 @@ export function createEditorUiStore() {
         snapMode: "ground",
         gridSize: 1,
         showGrid: true,
+        showContours: false,
+        showSurfaceGrid: false,
+        showElevation: false,
         placement: null,
         pathDraft: [],
         pathPoint: null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/editor",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Scene/world/asset editor for JGengine — loaded lazily by the runner; never import from game entrypoints.",
   "license": "Apache-2.0",
   "type": "module",
@@ -31,9 +31,9 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.10.0",
-    "@jgengine/react": "^0.10.0",
-    "@jgengine/shell": "^0.10.0"
+    "@jgengine/core": "^0.11.0",
+    "@jgengine/react": "^0.11.0",
+    "@jgengine/shell": "^0.11.0"
   },
   "peerDependencies": {
     "@react-three/drei": "^10.0.0",