@jgengine/editor 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -12,7 +12,7 @@ Agents building on the published SDK can also read this programmatically:
 same data as typed values, so an updater can diff its installed version against
 the latest and surface the migration steps.
 
-## Unreleased
+## 0.11.0
 
 ### Migrate
 

package/dist/EditorApp.js

@@ -12,7 +12,10 @@ import { MaterialDropZone } from "./MaterialDropZone.js";
 import { PerfProbe } from "./PerfProbe.js";
 import { ScatterPreview } from "./ScatterPreview.js";
 import { SelectionGizmo, ViewportSelect } from "./SelectionGizmo.js";
+import { TerrainReadout } from "./TerrainReadout.js";
+import { TerrainReadoutHud } from "./TerrainReadoutHud.js";
 import { TerrainSculpt } from "./TerrainSculpt.js";
+import { createTerrainReadoutStore } from "./terrainReadoutStore.js";
 import { RuntimePlayInspectorChrome, RuntimePlayPublisher } from "./RuntimePlayBridge.js";
 import { createEditorHost } from "./session.js";
 import { createEditorUiStore } from "./uiStore.js";
@@ -82,7 +85,29 @@ function savePrefs(gameId, prefs) {
         return;
     }
 }
-function EditorWorldOverlay({ api, ui, world, }) {
+/** Default readout region half-extent when a world declares no terrain bounds. */
+const DEFAULT_READOUT_HALF = 64;
+/**
+ * Derives the XZ region the terrain-readability overlay samples: the sculpt snapshot's rect if the
+ * world carries one, else the terrain descriptor's centered bounds, else a default square. Guides are
+ * editor visualization, not authored content — the region is inferred, never stored in the scene.
+ */
+function readoutRegionFor(world) {
+    if (world !== undefined && world.kind === "environment") {
+        const sculpt = world.sculpt;
+        if (sculpt !== undefined) {
+            return { minX: sculpt.bounds.minX, minZ: sculpt.bounds.minZ, maxX: sculpt.bounds.maxX, maxZ: sculpt.bounds.maxZ };
+        }
+        const bounds = world.terrain?.bounds;
+        if (bounds !== undefined) {
+            return { minX: -bounds.w / 2, minZ: -bounds.d / 2, maxX: bounds.w / 2, maxZ: bounds.d / 2 };
+        }
+    }
+    return { minX: -DEFAULT_READOUT_HALF, minZ: -DEFAULT_READOUT_HALF, maxX: DEFAULT_READOUT_HALF, maxZ: DEFAULT_READOUT_HALF };
+}
+/** Idle window before the terrain overlay rebuilds off the edited field — bounds rebuild frequency during sculpting. */
+const READOUT_REBUILD_MS = 250;
+function EditorWorldOverlay({ api, ui, world, readout, }) {
     const session = api.getSession();
     const ctx = useGameContext();
     const visibilityStore = useMemo(() => ({ getState: api.getVisibility, subscribe: api.subscribeVisibility }), [api]);
@@ -90,10 +115,33 @@ function EditorWorldOverlay({ api, ui, world, }) {
     const selection = useStoreSelector(session, (s) => s.selection, shallowArrayEqual);
     const visibility = useStoreSelector(visibilityStore, (v) => v);
     const showGrid = useStoreSelector(ui, (s) => s.showGrid);
+    const showContours = useStoreSelector(ui, (s) => s.showContours);
+    const showSurfaceGrid = useStoreSelector(ui, (s) => s.showSurfaceGrid);
+    const showElevation = useStoreSelector(ui, (s) => s.showElevation);
     const pathPoint = useStoreSelector(ui, (s) => s.pathPoint);
     const pathDraft = useStoreSelector(ui, (s) => s.pathDraft);
     const groundHeightAt = useCallback((x, z) => ctx.world.groundHeightAt(x, z), [ctx.world]);
-    return (_jsxs(_Fragment, { children: [_jsx(PerfProbe, { api: api }), _jsx(EditorCameraDriver, { api: api }), _jsx(ViewportSelect, { api: api, ui: ui }), _jsx(MaterialDropZone, { api: api }), _jsx(TerrainSculpt, { api: api, ui: ui, world: world }), _jsx(ScatterPreview, { api: api }), showGrid ? _jsx("gridHelper", { args: [400, 80, "#3b4252", "#20242e"], position: [0, 0.05, 0] }) : null, _jsx(EditorLayerOverlays, { document: document, visibility: visibility, selection: selection, onSelect: (id) => session.dispatch({ type: "select", ids: [id] }), activePathPoint: pathPoint, groundHeightAt: groundHeightAt }), pathDraft.length > 0 ? _jsx(PathDraftPreview, { points: pathDraft }) : null, _jsx(SelectionGizmo, { session: session, ui: ui, groundSnap: groundHeightAt })] }));
+    const readoutRegion = useMemo(() => readoutRegionFor(world), [world]);
+    const readoutActive = showContours || showSurfaceGrid || showElevation;
+    // Debounced terrain version: rebuilds the overlay after sculpt edits settle, not every stroke frame.
+    const [terrainVersion, setTerrainVersion] = useState(0);
+    useEffect(() => {
+        if (!readoutActive)
+            return;
+        setTerrainVersion((value) => value + 1);
+        let timer = null;
+        const unsubscribe = session.subscribe(() => {
+            if (timer !== null)
+                clearTimeout(timer);
+            timer = setTimeout(() => setTerrainVersion((value) => value + 1), READOUT_REBUILD_MS);
+        });
+        return () => {
+            if (timer !== null)
+                clearTimeout(timer);
+            unsubscribe();
+        };
+    }, [session, readoutActive]);
+    return (_jsxs(_Fragment, { children: [_jsx(PerfProbe, { api: api }), _jsx(EditorCameraDriver, { api: api }), _jsx(ViewportSelect, { api: api, ui: ui }), _jsx(MaterialDropZone, { api: api }), _jsx(TerrainSculpt, { api: api, ui: ui, world: world }), _jsx(ScatterPreview, { api: api }), showGrid ? _jsx("gridHelper", { args: [400, 80, "#3b4252", "#20242e"], position: [0, 0.05, 0] }) : null, readoutActive ? (_jsx(TerrainReadout, { groundHeightAt: groundHeightAt, region: readoutRegion, showContours: showContours, showSurfaceGrid: showSurfaceGrid, version: terrainVersion, readout: readout })) : null, _jsx(EditorLayerOverlays, { document: document, visibility: visibility, selection: selection, onSelect: (id) => session.dispatch({ type: "select", ids: [id] }), activePathPoint: pathPoint, groundHeightAt: groundHeightAt }), pathDraft.length > 0 ? _jsx(PathDraftPreview, { points: pathDraft }) : null, _jsx(SelectionGizmo, { session: session, ui: ui, groundSnap: groundHeightAt })] }));
 }
 /** Default skin for the play/walk escape chip; swap via `EditorAppProps.modeChip`, or pass `null` to hide it (F2+E still exits). */
 function EditorModeChip({ mode, onExit }) {
@@ -146,6 +194,10 @@ export function EditorApp({ gameId, playable, layers, catalogs, save, modeChip }
     if (uiStoreRef.current === null)
         uiStoreRef.current = createEditorUiStore();
     const ui = uiStoreRef.current;
+    const readoutStoreRef = useRef(null);
+    if (readoutStoreRef.current === null)
+        readoutStoreRef.current = createTerrainReadoutStore();
+    const readout = readoutStoreRef.current;
     const [mode, setModeState] = useState("edit");
     const catalogAssets = useMemo(() => {
         try {
@@ -211,6 +263,9 @@ export function EditorApp({ gameId, playable, layers, catalogs, save, modeChip }
             ...(prefs.snapMode === undefined ? {} : { snapMode: prefs.snapMode }),
             ...(prefs.gridSize === undefined ? {} : { gridSize: prefs.gridSize }),
             ...(prefs.showGrid === undefined ? {} : { showGrid: prefs.showGrid }),
+            ...(prefs.showContours === undefined ? {} : { showContours: prefs.showContours }),
+            ...(prefs.showSurfaceGrid === undefined ? {} : { showSurfaceGrid: prefs.showSurfaceGrid }),
+            ...(prefs.showElevation === undefined ? {} : { showElevation: prefs.showElevation }),
         });
         const persist = () => {
             const state = ui.getState();
@@ -219,6 +274,9 @@ export function EditorApp({ gameId, playable, layers, catalogs, save, modeChip }
                 snapMode: state.snapMode,
                 gridSize: state.gridSize,
                 showGrid: state.showGrid,
+                showContours: state.showContours,
+                showSurfaceGrid: state.showSurfaceGrid,
+                showElevation: state.showElevation,
             });
         };
         const unsubscribeVisibility = host.api.subscribeVisibility(persist);
@@ -289,7 +347,7 @@ export function EditorApp({ gameId, playable, layers, catalogs, save, modeChip }
             };
         }
         const WorldOverlay = function EditorOverlay() {
-            return _jsx(EditorWorldOverlay, { api: host.api, ui: ui, world: playable.game.world });
+            return _jsx(EditorWorldOverlay, { api: host.api, ui: ui, world: playable.game.world, readout: readout });
         };
         const GameUI = function EditorUi() {
             return _jsx(EditorChrome, { gameId: gameId, session: host.api.getSession(), api: host.api, assets: catalogAssets, ui: ui, baselineJson: host.baselineJson, save: saveFn });
@@ -328,6 +386,7 @@ export function EditorApp({ gameId, playable, layers, catalogs, save, modeChip }
                 },
             },
         };
-    }, [playable, host, gameId, initialCamera, catalogAssets, ui, mode, saveFn, resolvedModeChip]);
-    return (_jsxs("div", { className: "relative h-full w-full bg-neutral-950", "data-jg-editor": "1", "data-jg-editor-game": gameId, children: [_jsx(GamePlayerShell, { playable: editorPlayable }), pendingDraft !== null && mode === "edit" ? (_jsxs("div", { className: "absolute left-1/2 top-14 z-[60] flex -translate-x-1/2 items-center gap-3 rounded-xl border border-amber-400/30 bg-amber-950/90 px-4 py-2 text-xs text-amber-100 shadow-2xl shadow-black/50 backdrop-blur-md", children: [_jsx("span", { children: "Unsaved edits from a previous session found." }), _jsx("button", { type: "button", className: "rounded-md bg-gradient-to-b from-amber-500 to-amber-600 px-2.5 py-1 font-semibold text-white shadow-md shadow-amber-950/50 transition-colors hover:from-amber-400 hover:to-amber-500", onClick: restoreDraft, children: "Restore" }), _jsx("button", { type: "button", className: "rounded-md bg-white/[0.07] px-2.5 py-1 ring-1 ring-inset ring-white/[0.06] transition-colors hover:bg-white/15", onClick: discardDraft, children: "Discard" })] })) : null] }));
+    }, [playable, host, gameId, initialCamera, catalogAssets, ui, readout, mode, saveFn, resolvedModeChip]);
+    const showElevation = useStoreSelector(ui, (s) => s.showElevation);
+    return (_jsxs("div", { className: "relative h-full w-full bg-neutral-950", "data-jg-editor": "1", "data-jg-editor-game": gameId, children: [_jsx(GamePlayerShell, { playable: editorPlayable }), mode === "edit" && showElevation ? _jsx(TerrainReadoutHud, { readout: readout }) : null, pendingDraft !== null && mode === "edit" ? (_jsxs("div", { className: "absolute left-1/2 top-14 z-[60] flex -translate-x-1/2 items-center gap-3 rounded-xl border border-amber-400/30 bg-amber-950/90 px-4 py-2 text-xs text-amber-100 shadow-2xl shadow-black/50 backdrop-blur-md", children: [_jsx("span", { children: "Unsaved edits from a previous session found." }), _jsx("button", { type: "button", className: "rounded-md bg-gradient-to-b from-amber-500 to-amber-600 px-2.5 py-1 font-semibold text-white shadow-md shadow-amber-950/50 transition-colors hover:from-amber-400 hover:to-amber-500", onClick: restoreDraft, children: "Restore" }), _jsx("button", { type: "button", className: "rounded-md bg-white/[0.07] px-2.5 py-1 ring-1 ring-inset ring-white/[0.06] transition-colors hover:bg-white/15", onClick: discardDraft, children: "Discard" })] })) : null] }));
 }

package/dist/EditorChrome.js

@@ -13,6 +13,7 @@ import { OutlinerPanel } from "./OutlinerPanel.js";
 import { PrefabsPanel } from "./PrefabsPanel.js";
 import { buildEditorContextMenu, } from "./viewportContextMenu.js";
 import { buildOutlinerGroups } from "./outlinerModel.js";
+import { classifyEditorPerf } from "./perfPill.js";
 import { newPlacementId } from "./uiStore.js";
 import { useF2Chord } from "./useF2Chord.js";
 import { BTN, MICRO } from "./chromeStyles.js";
@@ -50,6 +51,17 @@ function formatTriangles(count) {
         return `${(count / 1_000).toFixed(0)}k`;
     return String(count);
 }
+const PERF_TONE_CLASS = {
+    idle: "text-neutral-500",
+    healthy: "text-emerald-400",
+    busy: "text-rose-400",
+};
+/** Toolbar perf pill: neutral "idle" when the loop is throttled/at rest, red only for active low fps. */
+function PerfPill({ perf }) {
+    const tone = classifyEditorPerf(perf);
+    const rate = tone === "idle" ? "idle" : `${perf.fps.toFixed(0)} fps`;
+    return (_jsxs("span", { className: `ml-3 ${PERF_TONE_CLASS[tone]}`, children: [rate, " \u00B7 ", perf.drawCalls, " draws \u00B7 ", formatTriangles(perf.triangles), " tris"] }));
+}
 let clipboardFragment = null;
 const SHORTCUTS = [
     { keys: "W / E / R", action: "Move · rotate · scale gizmo" },
@@ -534,7 +546,7 @@ export function EditorChrome({ gameId, session, api, assets, ui, baselineJson, s
                                                 : { tool: "marker", kind: definition.kind }), children: [definition.label, definition.target === "path" ? (definition.pathShape === "line" ? " (draw line)" : " (lasso)") : ""] }, definition.kind))), _jsx("div", { className: `px-2 pb-1 pt-2 ${MICRO}`, children: "Other" }), _jsx("button", { type: "button", className: "block w-full rounded-md px-2 py-1 text-left text-neutral-300 transition-colors hover:bg-cyan-500/15 hover:text-cyan-100", onClick: () => startPlacement({ tool: "path", kind: "route" }), children: "Draw path (route)" }), _jsx("button", { type: "button", className: "block w-full rounded-md px-2 py-1 text-left text-neutral-300 transition-colors hover:bg-cyan-500/15 hover:text-cyan-100", onClick: () => startPlacement({ tool: "path", kind: "road" }), children: "Draw road" }), _jsx("button", { type: "button", className: "block w-full rounded-md px-2 py-1 text-left text-neutral-300 transition-colors hover:bg-cyan-500/15 hover:text-cyan-100", onClick: () => startPlacement({ tool: "note" }), children: "Note" })] })) : null] }), _jsxs("button", { type: "button", className: BTN, onClick: () => {
                             const at = SNAP_MODES.findIndex((entry) => entry.mode === uiState.snapMode);
                             ui.patch({ snapMode: SNAP_MODES[(at + 1) % SNAP_MODES.length].mode });
-                        }, children: [SNAP_MODES.find((entry) => entry.mode === uiState.snapMode)?.label, uiState.snapMode === "grid" ? ` ${uiState.gridSize}` : ""] }), uiState.snapMode === "grid" ? (_jsx("button", { type: "button", className: BTN, onClick: () => ui.patch({ gridSize: uiState.gridSize >= 8 ? 0.5 : uiState.gridSize * 2 }), children: "\u00B1" })) : null, _jsx("button", { type: "button", className: `rounded-md px-2 py-1 ring-1 ring-inset ring-white/[0.06] transition-colors hover:bg-white/15 ${uiState.showGrid ? "bg-white/10 text-neutral-200" : "bg-white/[0.03] text-neutral-500"}`, onClick: () => ui.patch({ showGrid: !uiState.showGrid }), children: "Grid G" }), _jsx("div", { className: "h-5 w-px bg-white/[0.07]" }), _jsx("button", { type: "button", className: BTN, onClick: () => api.handle({ method: "camera_frame" }), children: "Frame all" }), _jsx("button", { type: "button", className: `${BTN} disabled:opacity-40`, onClick: () => session.dispatch({ type: "undo" }), disabled: !session.canUndo(), children: "Undo" }), _jsx("button", { type: "button", className: `${BTN} disabled:opacity-40`, onClick: () => session.dispatch({ type: "redo" }), disabled: !session.canRedo(), children: "Redo" }), _jsx("button", { type: "button", className: BTN, onClick: () => showPanel("assets"), children: "Assets" }), _jsxs("div", { className: "ml-auto flex items-center gap-2", children: [_jsx("button", { type: "button", className: BTN, onClick: () => setRightOpen((value) => !value), children: "Inspector" }), _jsx("button", { type: "button", className: `rounded-md px-2 py-1 ring-1 ring-inset transition-colors ${agentOpen
+                        }, children: [SNAP_MODES.find((entry) => entry.mode === uiState.snapMode)?.label, uiState.snapMode === "grid" ? ` ${uiState.gridSize}` : ""] }), uiState.snapMode === "grid" ? (_jsx("button", { type: "button", className: BTN, onClick: () => ui.patch({ gridSize: uiState.gridSize >= 8 ? 0.5 : uiState.gridSize * 2 }), children: "\u00B1" })) : null, _jsx("button", { type: "button", className: `rounded-md px-2 py-1 ring-1 ring-inset ring-white/[0.06] transition-colors hover:bg-white/15 ${uiState.showGrid ? "bg-white/10 text-neutral-200" : "bg-white/[0.03] text-neutral-500"}`, onClick: () => ui.patch({ showGrid: !uiState.showGrid }), children: "Grid G" }), _jsx("button", { type: "button", title: "Surface-following iso-elevation contours", className: `rounded-md px-2 py-1 ring-1 ring-inset ring-white/[0.06] transition-colors hover:bg-white/15 ${uiState.showContours ? "bg-white/10 text-neutral-200" : "bg-white/[0.03] text-neutral-500"}`, onClick: () => ui.patch({ showContours: !uiState.showContours }), children: "Contours" }), _jsx("button", { type: "button", title: "Terrain-draped reference grid", className: `rounded-md px-2 py-1 ring-1 ring-inset ring-white/[0.06] transition-colors hover:bg-white/15 ${uiState.showSurfaceGrid ? "bg-white/10 text-neutral-200" : "bg-white/[0.03] text-neutral-500"}`, onClick: () => ui.patch({ showSurfaceGrid: !uiState.showSurfaceGrid }), children: "Drape" }), _jsx("button", { type: "button", title: "Measurable elevation readout", className: `rounded-md px-2 py-1 ring-1 ring-inset ring-white/[0.06] transition-colors hover:bg-white/15 ${uiState.showElevation ? "bg-white/10 text-neutral-200" : "bg-white/[0.03] text-neutral-500"}`, onClick: () => ui.patch({ showElevation: !uiState.showElevation }), children: "Elev" }), _jsx("div", { className: "h-5 w-px bg-white/[0.07]" }), _jsx("button", { type: "button", className: BTN, onClick: () => api.handle({ method: "camera_frame" }), children: "Frame all" }), _jsx("button", { type: "button", className: `${BTN} disabled:opacity-40`, onClick: () => session.dispatch({ type: "undo" }), disabled: !session.canUndo(), children: "Undo" }), _jsx("button", { type: "button", className: `${BTN} disabled:opacity-40`, onClick: () => session.dispatch({ type: "redo" }), disabled: !session.canRedo(), children: "Redo" }), _jsx("button", { type: "button", className: BTN, onClick: () => showPanel("assets"), children: "Assets" }), _jsxs("div", { className: "ml-auto flex items-center gap-2", children: [_jsx("button", { type: "button", className: BTN, onClick: () => setRightOpen((value) => !value), children: "Inspector" }), _jsx("button", { type: "button", className: `rounded-md px-2 py-1 ring-1 ring-inset transition-colors ${agentOpen
                                     ? "bg-violet-500/25 text-violet-100 ring-violet-400/40"
                                     : "bg-white/[0.04] text-neutral-300 ring-white/[0.06] hover:bg-white/10 hover:text-neutral-100"}`, onClick: () => setAgentOpen((value) => !value), title: "Embedded agent panel \u2014 same RPC/undo as the GUI", children: "Agent" }), _jsx("button", { type: "button", className: BTN, onClick: () => api.setMode("walk"), children: "Walk" }), _jsx("button", { type: "button", className: "rounded-md bg-gradient-to-b from-emerald-500 to-emerald-600 px-3 py-1 font-semibold text-white shadow-md shadow-emerald-950/50 transition-colors hover:from-emerald-400 hover:to-emerald-500", onClick: () => api.setMode("play"), children: "\u25B6 Play" }), _jsx("button", { type: "button", className: BTN, onClick: () => importInputRef.current?.click(), children: "Import" }), _jsx("input", { ref: importInputRef, type: "file", accept: "application/json,.json", className: "hidden", onChange: (event) => {
                                     const file = event.target.files?.[0];
@@ -555,5 +567,5 @@ export function EditorChrome({ gameId, session, api, assets, ui, baselineJson, s
                                     hitId: uiState.contextMenu.hitId,
                                     selection: state.selection,
                                     canPaste: clipboardFragment !== null,
-                                }), onPick: runContextAction, onClose: closeContextMenu })) : null, _jsxs("div", { className: "absolute bottom-2 left-1/2 -translate-x-1/2 whitespace-nowrap rounded-full border border-white/[0.08] bg-black/70 px-4 py-1.5 text-[11px] text-neutral-400 shadow-lg shadow-black/40 backdrop-blur-md", children: [_jsx("span", { children: "RMB orbit \u00B7 MMB pan \u00B7 click select \u00B7 RMB menu \u00B7 W/E/R \u00B7 Ctrl+C/V \u00B7 F frame \u00B7 ? help" }), _jsxs("span", { className: "ml-3 text-neutral-500", children: [sceneStats.objects, " objs", sceneStats.foliage > 0 ? ` · ≈${formatTriangles(sceneStats.foliage)} foliage` : ""] }), perf !== null ? _jsxs("span", { className: `ml-3 ${perf.fps < 30 ? "text-rose-400" : "text-emerald-400"}`, children: [perf.fps.toFixed(0), " fps \u00B7 ", perf.drawCalls, " draws \u00B7 ", formatTriangles(perf.triangles), " tris"] }) : null] })] }), rightOpen ? _jsx(InspectorPanel, { session: session, ui: ui, onClose: () => setRightOpen(false) }) : null, agentOpen ? _jsx(AgentPanel, { api: api, onClose: () => setAgentOpen(false) }) : null] }), bottomOpen ? (_jsxs("section", { className: "pointer-events-auto flex h-64 min-h-40 max-h-[55vh] resize-y flex-col overflow-hidden border-t border-white/[0.08] bg-[#0d0f13]/95 backdrop-blur-md", children: [_jsxs("div", { className: "flex items-center border-b border-white/[0.08] px-3 py-2", children: [_jsx("div", { className: MICRO, children: "Asset browser" }), _jsxs("span", { className: "ml-2 text-neutral-600", children: [assets.length, " assets \u00B7 Ctrl+B"] }), _jsx("button", { type: "button", className: "ml-auto rounded-md px-2 py-1 text-neutral-500 transition-colors hover:bg-white/10 hover:text-neutral-200", onClick: () => setBottomOpen(false), "aria-label": "Close asset browser", children: "\u00D7" })] }), _jsx("div", { className: "min-h-0 flex-1 overflow-hidden p-2", children: _jsx(AssetBrowser, { assets: assets, session: session, onPlace: placeAsset }) })] })) : null] }));
+                                }), onPick: runContextAction, onClose: closeContextMenu })) : null, _jsxs("div", { className: "absolute bottom-2 left-1/2 -translate-x-1/2 whitespace-nowrap rounded-full border border-white/[0.08] bg-black/70 px-4 py-1.5 text-[11px] text-neutral-400 shadow-lg shadow-black/40 backdrop-blur-md", children: [_jsx("span", { children: "RMB orbit \u00B7 MMB pan \u00B7 click select \u00B7 RMB menu \u00B7 W/E/R \u00B7 Ctrl+C/V \u00B7 F frame \u00B7 ? help" }), _jsxs("span", { className: "ml-3 text-neutral-500", children: [sceneStats.objects, " objs", sceneStats.foliage > 0 ? ` · ≈${formatTriangles(sceneStats.foliage)} foliage` : ""] }), perf !== null ? _jsx(PerfPill, { perf: perf }) : null] })] }), rightOpen ? _jsx(InspectorPanel, { session: session, ui: ui, onClose: () => setRightOpen(false) }) : null, agentOpen ? _jsx(AgentPanel, { api: api, onClose: () => setAgentOpen(false) }) : null] }), bottomOpen ? (_jsxs("section", { className: "pointer-events-auto flex h-64 min-h-40 max-h-[55vh] resize-y flex-col overflow-hidden border-t border-white/[0.08] bg-[#0d0f13]/95 backdrop-blur-md", children: [_jsxs("div", { className: "flex items-center border-b border-white/[0.08] px-3 py-2", children: [_jsx("div", { className: MICRO, children: "Asset browser" }), _jsxs("span", { className: "ml-2 text-neutral-600", children: [assets.length, " assets \u00B7 Ctrl+B"] }), _jsx("button", { type: "button", className: "ml-auto rounded-md px-2 py-1 text-neutral-500 transition-colors hover:bg-white/10 hover:text-neutral-200", onClick: () => setBottomOpen(false), "aria-label": "Close asset browser", children: "\u00D7" })] }), _jsx("div", { className: "min-h-0 flex-1 overflow-hidden p-2", children: _jsx(AssetBrowser, { assets: assets, session: session, onPlace: placeAsset }) })] })) : null] }));
 }

package/dist/PerfProbe.js

@@ -2,33 +2,67 @@ import { useFrame, useThree } from "@react-three/fiber";
 import { memo, useRef } from "react";
 import { editorPerfMarks } from "./perfMarks.js";
 const SAMPLE_WINDOW_MS = 500;
+/** Sum-of-abs delta on camera position/orientation above which a frame counts as camera activity. */
+const CAMERA_MOVE_EPSILON = 1e-4;
 /** In-canvas frame counter: publishes fps/draw-call samples to the editor host every 500ms. */
 export const PerfProbe = memo(function PerfProbe({ api }) {
     const gl = useThree((state) => state.gl);
+    const camera = useThree((state) => state.camera);
     const framesRef = useRef(0);
     const windowStartRef = useRef(0);
+    const activeRef = useRef(false);
+    const lastCamRef = useRef({ px: 0, py: 0, pz: 0, qx: 0, qy: 0, qz: 0, qw: 1 });
+    const lastDrawRef = useRef(-1);
+    const lastTriRef = useRef(-1);
     useFrame(() => {
         const now = performance.now();
         if (windowStartRef.current === 0)
             windowStartRef.current = now;
         framesRef.current += 1;
+        // Detect camera activity frame-to-frame so a single moved frame inside the window still counts.
+        const cam = lastCamRef.current;
+        const dPos = Math.abs(camera.position.x - cam.px) +
+            Math.abs(camera.position.y - cam.py) +
+            Math.abs(camera.position.z - cam.pz);
+        const dRot = Math.abs(camera.quaternion.x - cam.qx) +
+            Math.abs(camera.quaternion.y - cam.qy) +
+            Math.abs(camera.quaternion.z - cam.qz) +
+            Math.abs(camera.quaternion.w - cam.qw);
+        if (dPos > CAMERA_MOVE_EPSILON || dRot > CAMERA_MOVE_EPSILON)
+            activeRef.current = true;
+        cam.px = camera.position.x;
+        cam.py = camera.position.y;
+        cam.pz = camera.position.z;
+        cam.qx = camera.quaternion.x;
+        cam.qy = camera.quaternion.y;
+        cam.qz = camera.quaternion.z;
+        cam.qw = camera.quaternion.w;
         const elapsed = now - windowStartRef.current;
         if (elapsed < SAMPLE_WINDOW_MS)
             return;
         const fps = (framesRef.current * 1000) / elapsed;
         const authoring = editorPerfMarks.flush();
+        const drawCalls = gl.info.render.calls;
+        const triangles = gl.info.render.triangles;
+        // Edit activity: viewport raycasts / preview-mesh rebuilds, or the rendered scene changed.
+        const sceneChanged = lastDrawRef.current >= 0 && (drawCalls !== lastDrawRef.current || triangles !== lastTriRef.current);
+        const active = activeRef.current || authoring.authoringMs > 0 || sceneChanged;
+        lastDrawRef.current = drawCalls;
+        lastTriRef.current = triangles;
         api.setPerf({
             fps: Math.round(fps * 10) / 10,
             frameMs: Math.round((elapsed / framesRef.current) * 100) / 100,
-            drawCalls: gl.info.render.calls,
-            triangles: gl.info.render.triangles,
+            drawCalls,
+            triangles,
             sampledAt: now,
+            active,
             raycastMs: authoring.raycastMs,
             rebuildMs: authoring.rebuildMs,
             authoringMs: authoring.authoringMs,
         });
         framesRef.current = 0;
         windowStartRef.current = now;
+        activeRef.current = false;
     });
     return null;
 });

package/dist/TerrainReadout.d.ts

@@ -0,0 +1,17 @@
+import { type GuideRegion } from "@jgengine/core/world/terrainGuides";
+import type { TerrainReadoutStore } from "./terrainReadoutStore.js";
+/**
+ * Surface-following terrain-readability overlay: draws iso-elevation contour lines and an optional
+ * terrain-draped reference grid from the live ground field, and tracks the cursor's elevation. All
+ * geometry comes from headless `@jgengine/core/world/terrainGuides` math; this component only turns it
+ * into three.js lines and publishes the measured feedback to the readout store.
+ */
+export declare function TerrainReadout({ groundHeightAt, region, showContours, showSurfaceGrid, version, readout, }: {
+    groundHeightAt: (x: number, z: number) => number;
+    region: GuideRegion;
+    showContours: boolean;
+    showSurfaceGrid: boolean;
+    /** Bumped by the host when the terrain changes, so the overlay rebuilds off the fresh field. */
+    version: number;
+    readout: TerrainReadoutStore;
+}): import("react").JSX.Element;

package/dist/TerrainReadout.js

@@ -0,0 +1,163 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef } from "react";
+import { useFrame, useThree } from "@react-three/fiber";
+import * as THREE from "three";
+import { extractContours, sampleElevation, summarizeElevation, surfaceGridLines, surfaceRing, chooseContourInterval, } from "@jgengine/core/world/terrainGuides";
+/** How often (seconds) the cursor readout re-samples — a bounded per-frame cost, not every frame. */
+const CURSOR_SAMPLE_INTERVAL = 1 / 20;
+/** Cap on marching-squares samples per axis — the overlay's explicit performance budget. */
+const READOUT_MAX_SAMPLES = 200;
+/** Small lift keeping guide lines off the surface so they never z-fight the terrain mesh. */
+const DEPTH_BIAS = 0.08;
+const MAJOR_CONTOUR_COLOR = "#f2c14e";
+const MINOR_CONTOUR_COLOR = "#8aa0b8";
+const MAJOR_GRID_COLOR = "#5b6b7d";
+const MINOR_GRID_COLOR = "#39434f";
+const CURSOR_RING_COLOR = "#ffd479";
+/** Expands a flat `[x,y,z,...]` polyline into consecutive `LineSegments` vertex pairs. */
+function polylineToSegments(points, into) {
+    const vertexCount = Math.floor(points.length / 3);
+    for (let i = 0; i < vertexCount - 1; i += 1) {
+        const a = i * 3;
+        const b = (i + 1) * 3;
+        into.push(points[a], points[a + 1], points[a + 2]);
+        into.push(points[b], points[b + 1], points[b + 2]);
+    }
+}
+function lineSegments(positions, color, opacity) {
+    if (positions.length === 0)
+        return null;
+    const geometry = new THREE.BufferGeometry();
+    geometry.setAttribute("position", new THREE.BufferAttribute(new Float32Array(positions), 3));
+    const material = new THREE.LineBasicMaterial({ color, transparent: true, opacity, depthTest: true });
+    return new THREE.LineSegments(geometry, material);
+}
+/**
+ * Surface-following terrain-readability overlay: draws iso-elevation contour lines and an optional
+ * terrain-draped reference grid from the live ground field, and tracks the cursor's elevation. All
+ * geometry comes from headless `@jgengine/core/world/terrainGuides` math; this component only turns it
+ * into three.js lines and publishes the measured feedback to the readout store.
+ */
+export function TerrainReadout({ groundHeightAt, region, showContours, showSurfaceGrid, version, readout, }) {
+    const regionKey = `${region.minX},${region.minZ},${region.maxX},${region.maxZ}`;
+    const guides = useMemo(() => {
+        const summary = summarizeElevation(groundHeightAt, region, 96, READOUT_MAX_SAMPLES);
+        const interval = chooseContourInterval(summary.range);
+        const objects = [];
+        if (showContours && interval > 0) {
+            const contours = extractContours(groundHeightAt, {
+                region,
+                interval,
+                resolution: 128,
+                maxSamples: READOUT_MAX_SAMPLES,
+            });
+            const major = [];
+            const minor = [];
+            for (const line of contours) {
+                const target = line.major ? major : minor;
+                for (let i = 0; i < line.segments.length; i += 2) {
+                    target.push(line.segments[i], line.level + DEPTH_BIAS, line.segments[i + 1]);
+                }
+            }
+            const majorObj = lineSegments(major, MAJOR_CONTOUR_COLOR, 0.9);
+            const minorObj = lineSegments(minor, MINOR_CONTOUR_COLOR, 0.5);
+            if (majorObj !== null)
+                objects.push(majorObj);
+            if (minorObj !== null)
+                objects.push(minorObj);
+        }
+        if (showSurfaceGrid) {
+            const spacing = interval > 0 ? Math.max(region.maxX - region.minX, region.maxZ - region.minZ) / 16 : 8;
+            const lines = surfaceGridLines(groundHeightAt, {
+                region,
+                spacing,
+                drape: { spacing: Math.max(1, spacing / 8), offset: DEPTH_BIAS },
+            });
+            const major = [];
+            const minor = [];
+            for (const line of lines)
+                polylineToSegments(line.points, line.major ? major : minor);
+            const majorObj = lineSegments(major, MAJOR_GRID_COLOR, 0.7);
+            const minorObj = lineSegments(minor, MINOR_GRID_COLOR, 0.4);
+            if (majorObj !== null)
+                objects.push(majorObj);
+            if (minorObj !== null)
+                objects.push(minorObj);
+        }
+        return { summary, interval, objects };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [groundHeightAt, regionKey, showContours, showSurfaceGrid, version]);
+    useEffect(() => {
+        readout.setSummary(guides.summary, guides.interval);
+    }, [guides, readout]);
+    useEffect(() => () => {
+        for (const object of guides.objects) {
+            if (object instanceof THREE.LineSegments) {
+                object.geometry.dispose();
+                object.material.dispose();
+            }
+        }
+    }, [guides]);
+    // Cursor ring — a surface-following placement guide draped under the pointer.
+    const ring = useMemo(() => {
+        const geometry = new THREE.BufferGeometry();
+        geometry.setAttribute("position", new THREE.BufferAttribute(new Float32Array(48 * 2 * 3), 3));
+        const material = new THREE.LineBasicMaterial({ color: CURSOR_RING_COLOR, transparent: true, opacity: 0.85 });
+        const segments = new THREE.LineSegments(geometry, material);
+        segments.visible = false;
+        return segments;
+    }, []);
+    useEffect(() => () => {
+        ring.geometry.dispose();
+        ring.material.dispose();
+    }, [ring]);
+    const { camera, pointer, raycaster } = useThree();
+    const planeRef = useRef(new THREE.Plane(new THREE.Vector3(0, 1, 0), 0));
+    const hitRef = useRef(new THREE.Vector3());
+    const accum = useRef(0);
+    useEffect(() => {
+        planeRef.current.constant = -(guides.summary.mean ?? 0);
+    }, [guides.summary]);
+    useFrame((_, delta) => {
+        accum.current += delta;
+        if (accum.current < CURSOR_SAMPLE_INTERVAL)
+            return;
+        accum.current = 0;
+        raycaster.setFromCamera(pointer, camera);
+        const hit = raycaster.ray.intersectPlane(planeRef.current, hitRef.current);
+        if (hit === null ||
+            hit.x < region.minX ||
+            hit.x > region.maxX ||
+            hit.z < region.minZ ||
+            hit.z > region.maxZ) {
+            readout.setCursor(null);
+            if (ring.visible)
+                ring.visible = false;
+            return;
+        }
+        const elevation = sampleElevation(groundHeightAt, hit.x, hit.z);
+        readout.setCursor(elevation);
+        const radius = Math.max(1.5, (region.maxX - region.minX) / 48);
+        const ringPoints = surfaceRing(groundHeightAt, [hit.x, hit.z], radius, 48, { offset: DEPTH_BIAS });
+        const attribute = ring.geometry.getAttribute("position");
+        const array = attribute.array;
+        let w = 0;
+        const vertexCount = Math.floor(ringPoints.length / 3);
+        for (let i = 0; i < vertexCount - 1 && w + 6 <= array.length; i += 1) {
+            const a = i * 3;
+            const b = (i + 1) * 3;
+            array[w++] = ringPoints[a];
+            array[w++] = ringPoints[a + 1];
+            array[w++] = ringPoints[a + 2];
+            array[w++] = ringPoints[b];
+            array[w++] = ringPoints[b + 1];
+            array[w++] = ringPoints[b + 2];
+        }
+        while (w < array.length)
+            array[w++] = 0;
+        attribute.needsUpdate = true;
+        ring.geometry.setDrawRange(0, Math.max(0, (vertexCount - 1) * 2));
+        ring.visible = true;
+    });
+    return (_jsxs("group", { children: [guides.objects.map((object, index) => (_jsx("primitive", { object: object }, index))), _jsx("primitive", { object: ring })] }));
+}

package/dist/TerrainReadoutHud.d.ts

@@ -0,0 +1,9 @@
+import type { TerrainReadoutStore } from "./terrainReadoutStore.js";
+/**
+ * The measurable terrain-readability legend: cursor elevation and delta from the `y = 0` reference,
+ * plus the region's min/max/mean relief and the active contour interval. Reads live measurements from
+ * the readout store the {@link TerrainReadout} overlay publishes; renders nothing until shown.
+ */
+export declare function TerrainReadoutHud({ readout }: {
+    readout: TerrainReadoutStore;
+}): import("react").JSX.Element;

package/dist/TerrainReadoutHud.js

@@ -0,0 +1,20 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useStoreSelector } from "./useStoreSelector.js";
+function fmt(value) {
+    return (Math.round(value * 100) / 100).toFixed(2);
+}
+function signed(value) {
+    const text = fmt(value);
+    return value > 0 ? `+${text}` : text;
+}
+/**
+ * The measurable terrain-readability legend: cursor elevation and delta from the `y = 0` reference,
+ * plus the region's min/max/mean relief and the active contour interval. Reads live measurements from
+ * the readout store the {@link TerrainReadout} overlay publishes; renders nothing until shown.
+ */
+export function TerrainReadoutHud({ readout }) {
+    const cursor = useStoreSelector(readout, (s) => s.cursor);
+    const summary = useStoreSelector(readout, (s) => s.summary);
+    const interval = useStoreSelector(readout, (s) => s.interval);
+    return (_jsxs("div", { className: "pointer-events-none absolute bottom-3 left-3 z-40 min-w-[180px] rounded-lg border border-white/[0.08] bg-black/70 px-3 py-2 font-mono text-[11px] leading-relaxed text-neutral-200 shadow-lg shadow-black/40 backdrop-blur-md", children: [_jsx("div", { className: "mb-1 text-[10px] font-semibold uppercase tracking-widest text-neutral-500", children: "Elevation" }), _jsxs("div", { className: "flex justify-between gap-4", children: [_jsx("span", { className: "text-neutral-400", children: "cursor" }), _jsx("span", { children: cursor === null ? "—" : `${fmt(cursor.height)} (${signed(cursor.delta)})` })] }), summary !== null ? (_jsxs(_Fragment, { children: [_jsxs("div", { className: "flex justify-between gap-4", children: [_jsx("span", { className: "text-neutral-400", children: "min / max" }), _jsxs("span", { children: [fmt(summary.min), " / ", fmt(summary.max)] })] }), _jsxs("div", { className: "flex justify-between gap-4", children: [_jsx("span", { className: "text-neutral-400", children: "mean / relief" }), _jsxs("span", { children: [fmt(summary.mean), " / ", fmt(summary.range)] })] }), _jsxs("div", { className: "flex justify-between gap-4", children: [_jsx("span", { className: "text-neutral-400", children: "contour" }), _jsx("span", { children: interval > 0 ? `${fmt(interval)} m` : "flat" })] })] })) : (_jsx("div", { className: "text-neutral-500", children: "no terrain sampled" }))] }));
+}

package/dist/mcp/rpcRequest.js

@@ -1,8 +1,18 @@
 /** Every `method` an {@link EditorBridgeRequest} may carry — kept in lockstep with the union in `session.ts`. */
 const EDITOR_BRIDGE_METHODS = new Set([
     "add_foliage",
+    "add_grid_layer",
     "add_to_collection",
     "assign_material",
+    "fill_grid_rect",
+    "flood_fill_grid",
+    "get_grid_cell",
+    "import_grid",
+    "list_grids",
+    "paint_grid_cells",
+    "remove_grid_layer",
+    "resize_grid_layer",
+    "set_grid_layer",
     "auto_paint",
     "batch_set_properties",
     "blend_terrain",