@jgengine/editor 0.10.0 → 0.12.0

package/dist/SelectionGizmo.js

@@ -5,7 +5,8 @@ import * as THREE from "three";
 import { findEditorMarker, findEditorNote, findEditorPath, findEditorVolume, } from "@jgengine/core/editor/index";
 import { TransformGizmo, } from "@jgengine/shell/structures/TransformGizmo";
 import { isPointerClick } from "./viewportContextMenu.js";
-import { newPlacementId } from "./uiStore.js";
+import { resolvePivotPosition } from "./gizmoPivot.js";
+import { newPlacementId, } from "./uiStore.js";
 import { useStoreSelector } from "./useStoreSelector.js";
 const CLICK_SLOP_PX = 5;
 const SCREEN_PICK_RADIUS_PX = 22;
@@ -15,10 +16,26 @@ const NOTE_LIFT = 1;
 const SELECT_TAGS = ["jgEditorId", "jgEntityId", "jgObjectId"];
 const GROUND_PLANE = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0);
 function selectGizmoUi(state) {
-    return { gizmoMode: state.gizmoMode, snapMode: state.snapMode, gridSize: state.gridSize, pathPoint: state.pathPoint };
+    return {
+        gizmoMode: state.gizmoMode,
+        gizmoSpace: state.gizmoSpace,
+        gizmoPivot: state.gizmoPivot,
+        snapMode: state.snapMode,
+        gridSize: state.gridSize,
+        rotationSnapDeg: state.rotationSnapDeg,
+        scaleSnap: state.scaleSnap,
+        pathPoint: state.pathPoint,
+    };
 }
 function gizmoUiEqual(a, b) {
-    return a.gizmoMode === b.gizmoMode && a.snapMode === b.snapMode && a.gridSize === b.gridSize && a.pathPoint === b.pathPoint;
+    return (a.gizmoMode === b.gizmoMode &&
+        a.gizmoSpace === b.gizmoSpace &&
+        a.gizmoPivot === b.gizmoPivot &&
+        a.snapMode === b.snapMode &&
+        a.gridSize === b.gridSize &&
+        a.rotationSnapDeg === b.rotationSnapDeg &&
+        a.scaleSnap === b.scaleSnap &&
+        a.pathPoint === b.pathPoint);
 }
 /** Reads only the gizmo-relevant UI slice (mode, snap, path-point anchor) — skips re-render on
  * unrelated UI churn (sculpt/paint drags, tool switches, placement) that the old blanket
@@ -41,6 +58,24 @@ function pathCentroid(points) {
     const n = Math.max(1, points.length);
     return { x: x / n, y: y / n, z: z / n };
 }
+function objectPosition(session, id) {
+    const { document } = session.getState();
+    const marker = findEditorMarker(document, id);
+    if (marker !== undefined) {
+        return { position: marker.position, lift: MARKER_LIFT, rotationY: marker.rotationY ?? 0, kind: "marker" };
+    }
+    const volume = findEditorVolume(document, id);
+    if (volume !== undefined)
+        return { position: volume.center, lift: 0, rotationY: 0, kind: "volume" };
+    const path = findEditorPath(document, id);
+    if (path !== undefined && path.points.length > 0) {
+        return { position: pathCentroid(path.points), lift: 0.8, rotationY: 0, kind: "path" };
+    }
+    const note = findEditorNote(document, id);
+    if (note !== undefined)
+        return { position: note.position, lift: NOTE_LIFT, rotationY: 0, kind: "note" };
+    return null;
+}
 function isEditorOverlayNode(node) {
     let current = node;
     while (current !== null) {
@@ -146,21 +181,24 @@ export const ViewportSelect = memo(function ViewportSelect({ api, ui }) {
             const state = session().getState();
             const visibility = api.getVisibility();
             const candidates = [];
-            const consider = (id, kind, point, lift) => {
-                if (visibility[kind] === false)
+            const consider = (id, kind, point, lift, hidden) => {
+                if (visibility[kind] === false || hidden === true)
                     return;
                 const distance = screenDistance(point, lift, clickX, clickY, rect);
                 if (distance !== null && distance < SCREEN_PICK_RADIUS_PX)
                     candidates.push({ id, distance });
             };
-            for (const marker of state.document.markers)
-                consider(marker.id, marker.kind, marker.position, MARKER_LIFT);
-            for (const volume of state.document.volumes)
-                consider(volume.id, volume.kind, volume.center, 0);
-            for (const note of state.document.annotations)
-                consider(note.id, "note", note.position, NOTE_LIFT);
+            for (const marker of state.document.markers) {
+                consider(marker.id, marker.kind, marker.position, MARKER_LIFT, marker.hidden);
+            }
+            for (const volume of state.document.volumes) {
+                consider(volume.id, volume.kind, volume.center, 0, volume.hidden);
+            }
+            for (const note of state.document.annotations) {
+                consider(note.id, "note", note.position, NOTE_LIFT, note.hidden);
+            }
             for (const path of state.document.paths) {
-                if (visibility[path.kind] === false)
+                if (visibility[path.kind] === false || path.hidden === true)
                     continue;
                 let best = null;
                 for (const point of path.points) {
@@ -211,6 +249,44 @@ export const ViewportSelect = memo(function ViewportSelect({ api, ui }) {
             }
             return null;
         };
+        // Throttled hover pick for pre-selection affordance — reuses the same document pick path as click.
+        let hoverRaf = 0;
+        let lastHoverClientX = 0;
+        let lastHoverClientY = 0;
+        const flushHover = () => {
+            hoverRaf = 0;
+            if (ui.getState().tool === "terrain" || ui.getState().placement !== null) {
+                if (ui.getState().hoverId !== null)
+                    ui.patch({ hoverId: null });
+                return;
+            }
+            const rect = canvas.getBoundingClientRect();
+            const clickX = lastHoverClientX - rect.left;
+            const clickY = lastHoverClientY - rect.top;
+            if (clickX < 0 || clickY < 0 || clickX > rect.width || clickY > rect.height) {
+                if (ui.getState().hoverId !== null)
+                    ui.patch({ hoverId: null });
+                return;
+            }
+            const id = pickDocumentId(clickX, clickY, rect) ?? pickTaggedId(clickX, clickY, rect);
+            if (ui.getState().hoverId !== id)
+                ui.patch({ hoverId: id });
+        };
+        const onMove = (event) => {
+            lastHoverClientX = event.clientX;
+            lastHoverClientY = event.clientY;
+            if (hoverRaf !== 0)
+                return;
+            hoverRaf = requestAnimationFrame(flushHover);
+        };
+        const onLeave = () => {
+            if (hoverRaf !== 0) {
+                cancelAnimationFrame(hoverRaf);
+                hoverRaf = 0;
+            }
+            if (ui.getState().hoverId !== null)
+                ui.patch({ hoverId: null });
+        };
         const onDown = (event) => {
             if (ui.getState().tool === "terrain")
                 return;
@@ -317,16 +393,22 @@ export const ViewportSelect = memo(function ViewportSelect({ api, ui }) {
         };
         canvas.addEventListener("pointerdown", onDown);
         canvas.addEventListener("pointerup", onUp);
+        canvas.addEventListener("pointermove", onMove);
+        canvas.addEventListener("pointerleave", onLeave);
         canvas.addEventListener("contextmenu", onContextMenu);
         return () => {
+            if (hoverRaf !== 0)
+                cancelAnimationFrame(hoverRaf);
             canvas.removeEventListener("pointerdown", onDown);
             canvas.removeEventListener("pointerup", onUp);
+            canvas.removeEventListener("pointermove", onMove);
+            canvas.removeEventListener("pointerleave", onLeave);
             canvas.removeEventListener("contextmenu", onContextMenu);
         };
     }, [gl, camera, scene, api, ui]);
     return null;
 });
-function resolveTarget(session, selectedId, pathPoint) {
+function resolveTarget(session, selection, pathPoint, pivot) {
     const { document } = session.getState();
     if (pathPoint !== null) {
         const path = findEditorPath(document, pathPoint.pathId);
@@ -334,23 +416,25 @@ function resolveTarget(session, selectedId, pathPoint) {
         if (point !== undefined)
             return { position: point, lift: 0.8, rotationY: 0, kind: "pathPoint" };
     }
-    if (selectedId === undefined)
+    if (selection.length === 0)
         return null;
-    const marker = findEditorMarker(document, selectedId);
-    if (marker !== undefined) {
-        return { position: marker.position, lift: MARKER_LIFT, rotationY: marker.rotationY ?? 0, kind: "marker" };
-    }
-    const volume = findEditorVolume(document, selectedId);
-    if (volume !== undefined)
-        return { position: volume.center, lift: 0, rotationY: 0, kind: "volume" };
-    const path = findEditorPath(document, selectedId);
-    if (path !== undefined && path.points.length > 0) {
-        return { position: pathCentroid(path.points), lift: 0.8, rotationY: 0, kind: "path" };
+    const primaryId = selection[0];
+    const primary = objectPosition(session, primaryId);
+    if (primary === null)
+        return null;
+    if (selection.length === 1)
+        return primary;
+    const positions = [];
+    for (const id of selection) {
+        const resolved = objectPosition(session, id);
+        if (resolved !== null)
+            positions.push(resolved.position);
     }
-    const note = findEditorNote(document, selectedId);
-    if (note !== undefined)
-        return { position: note.position, lift: NOTE_LIFT, rotationY: 0, kind: "note" };
-    return null;
+    const pivotPos = resolvePivotPosition(positions, pivot, primary.position);
+    if (pivotPos === null)
+        return primary;
+    // Multi-select always translates as a group from the pivot; rotation/scale stay primary-kind limited.
+    return { position: pivotPos, lift: primary.lift, rotationY: primary.rotationY, kind: primary.kind };
 }
 function effectiveMode(mode, kind) {
     if (kind === "marker")
@@ -368,7 +452,7 @@ export const SelectionGizmo = memo(function SelectionGizmo({ session, ui, ground
     const uiState = useGizmoUiState(ui);
     const state = session.getState();
     const selectedId = state.selection[0];
-    const target = useMemo(() => resolveTarget(session, selectedId, uiState.pathPoint), [state, selectedId, uiState.pathPoint, session]);
+    const target = useMemo(() => resolveTarget(session, state.selection, uiState.pathPoint, uiState.gizmoPivot), [state, uiState.pathPoint, uiState.gizmoPivot, session]);
     const mode = target === null ? "translate" : effectiveMode(uiState.gizmoMode, target.kind);
     if (target === null)
         return null;
@@ -451,5 +535,5 @@ export const SelectionGizmo = memo(function SelectionGizmo({ session, ui, ground
         session.dispatch({ type: "setTransform", id: selectedId, position: dropped });
     };
     const snapMode = uiState.snapMode === "grid" ? "grid" : uiState.snapMode === "ground" ? "ground" : "free";
-    return (_jsx(TransformGizmo, { position: target.position, rotationY: target.rotationY, mode: mode, snapMode: snapMode, gridSize: uiState.gridSize, lift: target.lift, groundSnap: mode === "translate" && target.kind !== "path" ? groundSnap : undefined, onRelease: onRelease }));
+    return (_jsx(TransformGizmo, { position: target.position, rotationY: target.rotationY, mode: mode, snapMode: snapMode, gridSize: uiState.gridSize, space: uiState.gizmoSpace, rotationSnap: uiState.rotationSnapDeg === null ? null : (uiState.rotationSnapDeg * Math.PI) / 180, scaleSnap: uiState.scaleSnap, lift: target.lift, groundSnap: mode === "translate" && target.kind !== "path" ? groundSnap : undefined, onRelease: onRelease }));
 });

package/dist/StandaloneEditor.d.ts

@@ -1,21 +1,23 @@
 import type { EditorLayersInput } from "@jgengine/core/editor/index";
 import { type EnvironmentWorldFeature } from "@jgengine/core/world/features";
 import type { PlayableGame } from "@jgengine/shell/registry";
+import { type AssetImporter, type StandaloneAsset } from "./assetImport.js";
 import { type EditorSaveFn } from "./EditorApp.js";
-/** One user-supplied model the standalone editor can place: a stable id and a resolvable URL. */
-export interface StandaloneAsset {
-    id: string;
-    url: string;
-    label?: string;
-}
+export type { AssetImporter, StandaloneAsset } from "./assetImport.js";
+export { importAssetToHost, loadDroppedAssets, mergeStandaloneAssets } from "./assetImport.js";
 /** Options for the blank, gameless world the standalone editor authors over. */
 export interface BlankPlayableOptions {
     name?: string;
     assets?: readonly StandaloneAsset[];
     world?: EnvironmentWorldFeature;
 }
-/** The default flat-ground world the standalone editor opens on when the host supplies none. */
-export declare function blankWorld(seed?: string): EnvironmentWorldFeature;
+/**
+ * The default flat-ground authoring canvas the standalone editor opens on when the host supplies
+ * none. Deliberately thin — bare sculptable ground under a clear default sky. Dressing (sky look,
+ * foliage scatter, props) is what the author adds here, written into the scene document; it is
+ * never pre-baked into the canvas. The `seed` parameter is legacy and unused.
+ */
+export declare function blankWorld(_seed?: string): EnvironmentWorldFeature;
 /** Builds a minimal gameless `PlayableGame` — a flat world plus an asset catalog — for the editor to mount over. */
 export declare function createBlankPlayable(options?: BlankPlayableOptions): PlayableGame;
 /** A save fn that hands the scene JSON back to the browser as a downloaded file — the exit path when no dev server is listening. */
@@ -32,6 +34,11 @@ export interface StandaloneEditorProps {
     world?: EnvironmentWorldFeature;
     /** Where Save writes. Default: the installed dev-server endpoint, else a browser download. */
     save?: EditorSaveFn;
+    /**
+     * How a dropped model is made durable. Default: upload to the `@jgengine/node` editor host plugin so it
+     * persists to disk and survives reload; when no host answers the import degrades to an ephemeral blob URL.
+     */
+    importAsset?: AssetImporter;
     /** Hide the built-in open-scene / add-assets strip (host supplies its own loading UI). */
     hidePickers?: boolean;
 }
@@ -41,4 +48,4 @@ export interface StandaloneEditorProps {
  * desktop app, or any React host). Ships a slim strip to open a world file and pull in an asset
  * folder; both are also settable up front through props.
  */
-export declare function StandaloneEditor({ sceneId, scene, assets, world, save, hidePickers, }: StandaloneEditorProps): import("react").JSX.Element;
+export declare function StandaloneEditor({ sceneId, scene, assets, world, save, importAsset, hidePickers, }: StandaloneEditorProps): import("react").JSX.Element;

package/dist/StandaloneEditor.js

@@ -2,15 +2,23 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useMemo, useRef, useState } from "react";
 import { getSaveEndpoint } from "@jgengine/core/devtools/saveEndpoint";
 import { createAssetCatalog } from "@jgengine/core/scene/assetCatalog";
-import { environment, grass, sky, terrain, } from "@jgengine/core/world/features";
+import { environment, sky, terrain, } from "@jgengine/core/world/features";
 import { defineGame } from "@jgengine/shell/defineGame";
+import { importAssetToHost, loadDroppedAssets, mergeStandaloneAssets, } from "./assetImport.js";
 import { EditorApp } from "./EditorApp.js";
-/** The default flat-ground world the standalone editor opens on when the host supplies none. */
-export function blankWorld(seed = "standalone") {
+export { importAssetToHost, loadDroppedAssets, mergeStandaloneAssets } from "./assetImport.js";
+/**
+ * The default flat-ground authoring canvas the standalone editor opens on when the host supplies
+ * none. Deliberately thin — bare sculptable ground under a clear default sky. Dressing (sky look,
+ * foliage scatter, props) is what the author adds here, written into the scene document; it is
+ * never pre-baked into the canvas. The `seed` parameter is legacy and unused.
+ */
+export function blankWorld(_seed = "standalone") {
     return environment({
         terrain: terrain({ bounds: { w: 128, d: 128 }, height: 0, material: "grass" }),
-        sky: sky({ preset: "day" }),
-        vegetation: grass({ area: { w: 100, d: 100 }, density: 1.5, colors: ["#3f7d2d", "#6bbf4a"], seed }),
+        // Fog pushed past the world edge: the engine's default (near 70 / far 260) soaks most of a
+        // 128 m authoring canvas in haze — the editor should open on a clear world.
+        sky: sky({ preset: "day", fog: { near: 220, far: 700 } }),
     });
 }
 /** Builds a minimal gameless `PlayableGame` — a flat world plus an asset catalog — for the editor to mount over. */
@@ -44,17 +52,13 @@ export function downloadSaver(filename = "editor.scene.json") {
         }
     };
 }
-const MODEL_FILE = /\.(glb|gltf)$/i;
-function assetId(name) {
-    return name.replace(MODEL_FILE, "").replace(/[^a-z0-9]+/gi, "-").replace(/^-+|-+$/g, "").toLowerCase() || "asset";
-}
 /**
  * The scene editor, mounted over a blank gameless world instead of a game — the same `EditorApp`
  * every jgengine game ships, usable standalone on the user's own project (CLI `jgengine editor`,
  * desktop app, or any React host). Ships a slim strip to open a world file and pull in an asset
  * folder; both are also settable up front through props.
  */
-export function StandaloneEditor({ sceneId = "standalone", scene, assets, world, save, hidePickers = false, }) {
+export function StandaloneEditor({ sceneId = "standalone", scene, assets, world, save, importAsset = importAssetToHost, hidePickers = false, }) {
     const [loadedScene, setLoadedScene] = useState(scene);
     const [loadedAssets, setLoadedAssets] = useState(assets ?? []);
     const [rev, setRev] = useState(0);
@@ -67,18 +71,13 @@ export function StandaloneEditor({ sceneId = "standalone", scene, assets, world,
         setLoadedScene(JSON.parse(text));
         setRev((value) => value + 1);
     }, []);
-    const addAssets = useCallback((files) => {
-        const next = [];
-        for (const file of Array.from(files)) {
-            if (!MODEL_FILE.test(file.name))
-                continue;
-            next.push({ id: assetId(file.name), url: URL.createObjectURL(file), label: file.name });
-        }
+    const addAssets = useCallback(async (files) => {
+        const next = await loadDroppedAssets(Array.from(files), importAsset);
         if (next.length === 0)
             return;
-        setLoadedAssets((current) => [...current, ...next]);
+        setLoadedAssets((current) => mergeStandaloneAssets(current, next));
         setRev((value) => value + 1);
-    }, []);
+    }, [importAsset]);
     return (_jsxs("div", { className: "relative h-full w-full", children: [_jsx(EditorApp, { gameId: sceneId, playable: playable, layers: loadedScene, save: saveFn }, rev), hidePickers ? null : (_jsxs("div", { className: "pointer-events-none absolute bottom-3 left-1/2 z-[70] flex -translate-x-1/2 items-center gap-2 rounded-full border border-white/10 bg-black/70 px-2 py-1.5 text-[11px] text-neutral-200 shadow-lg shadow-black/40 backdrop-blur-md", children: [_jsx("button", { type: "button", className: "pointer-events-auto rounded-full px-3 py-1 transition-colors hover:bg-white/10", onClick: () => sceneInput.current?.click(), children: "\uD83D\uDCC2 Open scene" }), _jsx("span", { className: "h-4 w-px bg-white/15" }), _jsx("button", { type: "button", className: "pointer-events-auto rounded-full px-3 py-1 transition-colors hover:bg-white/10", onClick: () => assetInput.current?.click(), children: "\uD83E\uDDCA Add assets" }), loadedAssets.length > 0 ? (_jsx("span", { className: "rounded-full bg-white/10 px-2 py-0.5 text-[10px] text-neutral-300", children: loadedAssets.length })) : null, _jsx("input", { ref: sceneInput, type: "file", accept: ".json,application/json", className: "hidden", onChange: (event) => {
                             const file = event.target.files?.[0];
                             if (file !== undefined)
@@ -86,7 +85,7 @@ export function StandaloneEditor({ sceneId = "standalone", scene, assets, world,
                             event.target.value = "";
                         } }), _jsx("input", { ref: assetInput, type: "file", accept: ".glb,.gltf,model/gltf-binary", multiple: true, className: "hidden", onChange: (event) => {
                             if (event.target.files !== null)
-                                addAssets(event.target.files);
+                                void addAssets(event.target.files);
                             event.target.value = "";
                         } })] }))] }));
 }

package/dist/TerrainPanel.d.ts

@@ -1,7 +1,8 @@
-import type { EditorSession } from "./session.js";
+import type { EditorHostApi, EditorSession } from "./session.js";
 import { type EditorUiStore } from "./uiStore.js";
 /** The terrain-tool panel: create/clear the heightfield and drive the sculpt/paint controls. */
-export declare function TerrainPanel({ session, ui }: {
+export declare function TerrainPanel({ session, ui, api }: {
     session: EditorSession;
     ui: EditorUiStore;
+    api: EditorHostApi;
 }): import("react").JSX.Element;

package/dist/TerrainPanel.js

@@ -3,8 +3,11 @@ import { useEffect, useState } from "react";
 import { editorDocumentBounds } from "@jgengine/core/editor/index";
 import { createTerrainSnapshot, editableTerrainFromSnapshot, } from "@jgengine/core/world/terraform";
 import { TERRAIN_MATERIALS } from "./uiStore.js";
-import { INPUT } from "./chromeStyles.js";
 import { SliderRow } from "./chromeFields.js";
+import { BORDER, CONTROL, CONTROL_ACTIVE, FOCUS_RING, INPUT_CLS, MICRO_LABEL } from "./shell/theme.js";
+const BTN = `${CONTROL} px-2 py-1 text-[11px] disabled:opacity-40`;
+const BTN_SM = `${CONTROL} px-2 py-0.5 text-[11px]`;
+const BTN_ACTIVE = `${CONTROL_ACTIVE} rounded-[5px] px-1.5 py-1 text-[11px] ${FOCUS_RING}`;
 const TERRAIN_BRUSHES = [
     { kind: "raise", label: "Raise", hint: "Push terrain up" },
     { kind: "lower", label: "Lower", hint: "Dig terrain down" },
@@ -30,7 +33,7 @@ function defaultTerrainBounds(document) {
 }
 function SculptControls({ ui }) {
     const sculpt = ui.getState().sculpt;
-    return (_jsxs(_Fragment, { children: [_jsx("div", { className: "grid grid-cols-3 gap-1", children: TERRAIN_BRUSHES.map((brush) => (_jsx("button", { type: "button", title: brush.hint, className: `rounded-md px-1.5 py-1 text-[11px] transition-colors ${sculpt.brush === brush.kind ? "bg-amber-500/90 text-white shadow-sm shadow-amber-950/50" : "bg-white/[0.04] text-neutral-300 ring-1 ring-inset ring-white/[0.06] hover:bg-white/10"}`, onClick: () => ui.patchSculpt({ brush: brush.kind }), children: brush.label }, brush.kind))) }), sculpt.brush === "ramp" ? _jsx("div", { className: "text-[10px] text-neutral-500", children: "Drag from the low end to the high end to grade a slope." }) : null, _jsx(SliderRow, { label: "radius", value: sculpt.radius, min: 1, max: 60, step: 0.5, onChange: (value) => ui.patchSculpt({ radius: value }), format: (v) => `${v.toFixed(1)}m` }), _jsx(SliderRow, { label: "strength", value: sculpt.strength, min: 0.05, max: 5, step: 0.05, onChange: (value) => ui.patchSculpt({ strength: value }) }), _jsx(SliderRow, { label: "spacing", value: sculpt.spacing, min: 0.25, max: 12, step: 0.25, onChange: (value) => ui.patchSculpt({ spacing: value }), format: (v) => `${v.toFixed(2)}m` }), _jsxs("div", { className: "flex items-center gap-1", children: [_jsx("span", { className: "text-[9px] font-semibold uppercase tracking-wider text-neutral-500", children: "falloff" }), _jsx("div", { className: "ml-auto flex gap-0.5 rounded-md bg-black/40 p-0.5 ring-1 ring-inset ring-white/[0.06]", children: ["smooth", "linear", "none"].map((mode) => (_jsx("button", { type: "button", className: `rounded px-1.5 py-0.5 text-[10px] capitalize transition-colors ${sculpt.falloff === mode ? "bg-amber-500/80 text-white" : "text-neutral-400 hover:text-neutral-200"}`, onClick: () => ui.patchSculpt({ falloff: mode }), children: mode }, mode))) })] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx("span", { className: "text-[9px] font-semibold uppercase tracking-wider text-neutral-500", children: "shape" }), _jsx("button", { type: "button", className: "ml-auto rounded-md bg-white/[0.04] px-2 py-0.5 text-[11px] capitalize ring-1 ring-inset ring-white/[0.06] transition-colors hover:bg-white/10", onClick: () => ui.patchSculpt({ shape: sculpt.shape === "circle" ? "square" : "circle" }), children: sculpt.shape }), _jsxs("label", { className: "flex items-center gap-1 text-[10px] text-neutral-400", children: [_jsx("input", { type: "checkbox", className: "accent-amber-400", checked: sculpt.invert, onChange: (event) => ui.patchSculpt({ invert: event.target.checked }) }), "invert"] })] }), sculpt.brush === "flatten" ? (_jsxs("label", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: "text-[9px] font-semibold uppercase tracking-wider text-neutral-500", children: "flatten to" }), _jsx("input", { type: "number", step: 0.5, placeholder: "sample", className: `w-24 ${INPUT}`, value: sculpt.flattenHeight ?? "", onChange: (event) => ui.patchSculpt({ flattenHeight: event.target.value === "" ? null : Number(event.target.value) }) })] })) : null, sculpt.brush === "noise" ? (_jsxs("label", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: "text-[9px] font-semibold uppercase tracking-wider text-neutral-500", children: "seed" }), _jsx("input", { type: "number", step: 1, className: `w-24 ${INPUT}`, value: sculpt.noiseSeed, onChange: (event) => ui.patchSculpt({ noiseSeed: Math.round(Number(event.target.value)) || 0 }) })] })) : null] }));
+    return (_jsxs(_Fragment, { children: [_jsx("div", { className: "grid grid-cols-3 gap-1", children: TERRAIN_BRUSHES.map((brush) => (_jsx("button", { type: "button", title: brush.hint, className: sculpt.brush === brush.kind ? BTN_ACTIVE : `${BTN} px-1.5`, onClick: () => ui.patchSculpt({ brush: brush.kind }), children: brush.label }, brush.kind))) }), sculpt.brush === "ramp" ? _jsx("div", { className: "text-[10px] text-neutral-500", children: "Drag from the low end to the high end to grade a slope." }) : null, _jsx(SliderRow, { label: "radius", value: sculpt.radius, min: 1, max: 60, step: 0.5, onChange: (value) => ui.patchSculpt({ radius: value }), format: (v) => `${v.toFixed(1)}m` }), _jsx(SliderRow, { label: "strength", value: sculpt.strength, min: 0.05, max: 5, step: 0.05, onChange: (value) => ui.patchSculpt({ strength: value }) }), _jsx(SliderRow, { label: "spacing", value: sculpt.spacing, min: 0.25, max: 12, step: 0.25, onChange: (value) => ui.patchSculpt({ spacing: value }), format: (v) => `${v.toFixed(2)}m` }), _jsxs("div", { className: "flex items-center gap-1", children: [_jsx("span", { className: MICRO_LABEL, children: "falloff" }), _jsx("div", { className: `ml-auto flex gap-0.5 rounded-[5px] border ${BORDER} bg-black/40 p-0.5`, children: ["smooth", "linear", "none"].map((mode) => (_jsx("button", { type: "button", className: `rounded-[4px] px-1.5 py-0.5 text-[10px] capitalize transition-colors ${FOCUS_RING} ${sculpt.falloff === mode ? CONTROL_ACTIVE : "text-neutral-400 hover:text-neutral-200"}`, onClick: () => ui.patchSculpt({ falloff: mode }), children: mode }, mode))) })] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx("span", { className: MICRO_LABEL, children: "shape" }), _jsx("button", { type: "button", className: `ml-auto capitalize ${BTN_SM}`, onClick: () => ui.patchSculpt({ shape: sculpt.shape === "circle" ? "square" : "circle" }), children: sculpt.shape }), _jsxs("label", { className: "flex items-center gap-1 text-[10px] text-neutral-400", children: [_jsx("input", { type: "checkbox", className: "accent-amber-400", checked: sculpt.invert, onChange: (event) => ui.patchSculpt({ invert: event.target.checked }) }), "invert"] })] }), sculpt.brush === "flatten" ? (_jsxs("label", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: MICRO_LABEL, children: "flatten to" }), _jsx("input", { type: "number", step: 0.5, placeholder: "sample", className: `h-7 w-24 px-1.5 ${INPUT_CLS}`, value: sculpt.flattenHeight ?? "", onChange: (event) => ui.patchSculpt({ flattenHeight: event.target.value === "" ? null : Number(event.target.value) }) })] })) : null, sculpt.brush === "noise" ? (_jsxs("label", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: MICRO_LABEL, children: "seed" }), _jsx("input", { type: "number", step: 1, className: `h-7 w-24 px-1.5 ${INPUT_CLS}`, value: sculpt.noiseSeed, onChange: (event) => ui.patchSculpt({ noiseSeed: Math.round(Number(event.target.value)) || 0 }) })] })) : null] }));
 }
 function PaintControls({ session, ui }) {
     const paint = ui.getState().paint;
@@ -42,11 +45,12 @@ function PaintControls({ session, ui }) {
         if (delta.indices.length > 0)
             session.dispatch({ type: "paintTerrain", delta });
     };
-    return (_jsxs(_Fragment, { children: [_jsx("div", { className: "grid grid-cols-2 gap-1", children: TERRAIN_MATERIALS.map((material) => (_jsxs("button", { type: "button", className: `flex items-center gap-1.5 rounded-md px-1.5 py-1 text-[11px] transition-colors ${paint.material === material.id ? "bg-amber-500/90 text-white shadow-sm shadow-amber-950/50" : "bg-white/[0.04] text-neutral-300 ring-1 ring-inset ring-white/[0.06] hover:bg-white/10"}`, onClick: () => ui.patchPaint({ material: material.id }), children: [_jsx("span", { className: "h-3 w-3 shrink-0 rounded-sm ring-1 ring-inset ring-black/40", style: { backgroundColor: material.color } }), material.label] }, material.id))) }), _jsx("div", { className: "text-[10px] text-neutral-500", children: "Click/drag to paint \u00B7 Alt-click to sample." }), _jsx(SliderRow, { label: "radius", value: paint.radius, min: 1, max: 60, step: 0.5, onChange: (value) => ui.patchPaint({ radius: value }), format: (v) => `${v.toFixed(1)}m` }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx("span", { className: "text-[9px] font-semibold uppercase tracking-wider text-neutral-500", children: "shape" }), _jsx("button", { type: "button", className: "ml-auto rounded-md bg-white/[0.04] px-2 py-0.5 text-[11px] capitalize ring-1 ring-inset ring-white/[0.06] transition-colors hover:bg-white/10", onClick: () => ui.patchPaint({ shape: paint.shape === "circle" ? "square" : "circle" }), children: paint.shape })] }), _jsxs("div", { className: "grid grid-cols-2 gap-1", children: [_jsx("button", { type: "button", className: "rounded-md bg-white/[0.04] px-2 py-1 text-[11px] text-neutral-300 ring-1 ring-inset ring-white/[0.06] transition-colors hover:bg-white/10", onClick: () => paintDelta((terrain) => terrain.fillSurfaceDelta(paint.material)), children: "Fill all" }), _jsx("button", { type: "button", className: "rounded-md bg-white/[0.04] px-2 py-1 text-[11px] text-neutral-300 ring-1 ring-inset ring-white/[0.06] transition-colors hover:bg-white/10", onClick: () => paintDelta((terrain) => terrain.fillSurfaceDelta(null)), children: "Clear paint" })] }), _jsxs("div", { className: "space-y-1 rounded-lg border border-white/[0.06] p-2", children: [_jsx("div", { className: "text-[9px] font-semibold uppercase tracking-wider text-neutral-500", children: "Auto rules" }), _jsxs("div", { className: "grid grid-cols-2 gap-1", children: [_jsx("button", { type: "button", className: "rounded-md bg-white/[0.04] px-2 py-1 text-[10px] text-neutral-300 ring-1 ring-inset ring-white/[0.06] transition-colors hover:bg-white/10", title: "Paint the selected material onto slopes steeper than ~30\u00B0", onClick: () => paintDelta((terrain) => terrain.autoPaintDelta({ surface: paint.material, minSlope: 0.6 })), children: "On steep slopes" }), _jsx("button", { type: "button", className: "rounded-md bg-white/[0.04] px-2 py-1 text-[10px] text-neutral-300 ring-1 ring-inset ring-white/[0.06] transition-colors hover:bg-white/10", title: "Paint the selected material above height 15", onClick: () => paintDelta((terrain) => terrain.autoPaintDelta({ surface: paint.material, minHeight: 15 })), children: "On high ground" })] })] })] }));
+    return (_jsxs(_Fragment, { children: [_jsx("div", { className: "grid grid-cols-2 gap-1", children: TERRAIN_MATERIALS.map((material) => (_jsxs("button", { type: "button", className: `flex items-center gap-1.5 ${paint.material === material.id ? BTN_ACTIVE : `${BTN} px-1.5`}`, onClick: () => ui.patchPaint({ material: material.id }), children: [_jsx("span", { className: "h-3 w-3 shrink-0 rounded-sm ring-1 ring-inset ring-black/40", style: { backgroundColor: material.color } }), material.label] }, material.id))) }), _jsx("div", { className: "text-[10px] text-neutral-500", children: "Click/drag to paint \u00B7 Alt-click to sample." }), _jsx(SliderRow, { label: "radius", value: paint.radius, min: 1, max: 60, step: 0.5, onChange: (value) => ui.patchPaint({ radius: value }), format: (v) => `${v.toFixed(1)}m` }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx("span", { className: MICRO_LABEL, children: "shape" }), _jsx("button", { type: "button", className: `ml-auto capitalize ${BTN_SM}`, onClick: () => ui.patchPaint({ shape: paint.shape === "circle" ? "square" : "circle" }), children: paint.shape })] }), _jsxs("div", { className: "grid grid-cols-2 gap-1", children: [_jsx("button", { type: "button", className: BTN, onClick: () => paintDelta((terrain) => terrain.fillSurfaceDelta(paint.material)), children: "Fill all" }), _jsx("button", { type: "button", className: BTN, onClick: () => paintDelta((terrain) => terrain.fillSurfaceDelta(null)), children: "Clear paint" })] }), _jsxs("div", { className: `space-y-1 rounded-[6px] border ${BORDER} p-2`, children: [_jsx("div", { className: MICRO_LABEL, children: "Auto rules" }), _jsxs("div", { className: "grid grid-cols-2 gap-1", children: [_jsx("button", { type: "button", className: `${BTN} text-[10px]`, title: "Paint the selected material onto slopes steeper than ~30\u00B0", onClick: () => paintDelta((terrain) => terrain.autoPaintDelta({ surface: paint.material, minSlope: 0.6 })), children: "On steep slopes" }), _jsx("button", { type: "button", className: `${BTN} text-[10px]`, title: "Paint the selected material above height 15", onClick: () => paintDelta((terrain) => terrain.autoPaintDelta({ surface: paint.material, minHeight: 15 })), children: "On high ground" })] })] })] }));
 }
 /** The terrain-tool panel: create/clear the heightfield and drive the sculpt/paint controls. */
-export function TerrainPanel({ session, ui }) {
+export function TerrainPanel({ session, ui, api }) {
     const [, setTick] = useState(0);
+    const [bakeStatus, setBakeStatus] = useState(null);
     useEffect(() => ui.subscribe(() => setTick((value) => value + 1)), [ui]);
     useEffect(() => session.subscribe(() => setTick((value) => value + 1)), [session]);
     const uiState = ui.getState();
@@ -55,5 +59,12 @@ export function TerrainPanel({ session, ui }) {
     const createTerrain = () => {
         session.dispatch({ type: "setTerrain", terrain: createTerrainSnapshot({ bounds: defaultTerrainBounds(document), cellSize: 2 }) });
     };
-    return (_jsxs("div", { className: "pointer-events-auto absolute right-3 top-3 z-40 max-h-[calc(100%-1.5rem)] w-64 space-y-2.5 overflow-auto rounded-xl border border-amber-400/20 bg-[#0d0f13]/95 p-3 shadow-2xl shadow-black/60 backdrop-blur-md", children: [_jsxs("div", { className: "flex items-center", children: [_jsx("div", { className: "text-[9px] font-semibold uppercase tracking-[0.14em] text-amber-300", children: "Terrain" }), _jsx("button", { type: "button", className: "ml-auto rounded-md px-2 py-0.5 text-neutral-500 transition-colors hover:bg-white/10 hover:text-neutral-200", onClick: () => ui.setTool("select"), title: "Back to select tool", children: "\u00D7" })] }), !hasTerrain ? (_jsxs("div", { className: "space-y-2", children: [_jsx("p", { className: "text-[11px] leading-relaxed text-neutral-400", children: "No terrain yet. Create an editable heightfield over the scene, then sculpt its shape and paint material layers on it." }), _jsx("button", { type: "button", className: "w-full rounded-md bg-gradient-to-b from-amber-500 to-amber-600 px-2.5 py-1.5 font-semibold text-white shadow-md shadow-amber-950/50 transition-colors hover:from-amber-400 hover:to-amber-500", onClick: createTerrain, children: "Create terrain" })] })) : (_jsxs(_Fragment, { children: [_jsx("div", { className: "flex gap-0.5 rounded-lg bg-black/40 p-0.5 ring-1 ring-inset ring-white/[0.06]", children: ["sculpt", "paint"].map((mode) => (_jsx("button", { type: "button", className: `flex-1 rounded-md px-2 py-1 text-[11px] capitalize transition-colors ${uiState.terrainMode === mode ? "bg-amber-500/90 text-white shadow-sm shadow-amber-950/50" : "text-neutral-400 hover:bg-white/[0.06] hover:text-neutral-200"}`, onClick: () => ui.setTerrainMode(mode), children: mode }, mode))) }), uiState.terrainMode === "paint" ? _jsx(PaintControls, { session: session, ui: ui }) : _jsx(SculptControls, { ui: ui }), _jsxs("div", { className: "flex items-center justify-between gap-2 border-t border-white/[0.06] pt-2", children: [_jsx("button", { type: "button", className: "rounded-md bg-white/[0.04] px-2 py-1 text-[11px] text-neutral-300 ring-1 ring-inset ring-white/[0.06] transition-colors hover:bg-white/10 disabled:opacity-40", onClick: () => session.dispatch({ type: "undo" }), disabled: !session.canUndo(), children: "Undo" }), _jsx("button", { type: "button", className: "rounded-md bg-rose-500/15 px-2 py-1 text-[11px] text-rose-200 ring-1 ring-inset ring-rose-400/25 transition-colors hover:bg-rose-500/25", onClick: () => session.dispatch({ type: "clearTerrain" }), children: "Clear terrain" })] })] }))] }));
+    const bakeMinimap = () => {
+        const response = api.handle({ method: "bake_minimap" });
+        if (response.ok)
+            setBakeStatus({ tone: "ok", text: "Minimap baked onto the scene." });
+        else
+            setBakeStatus({ tone: "error", text: response.error ?? "Bake failed." });
+    };
+    return (_jsxs("div", { className: `pointer-events-auto absolute right-3 top-3 z-40 max-h-[calc(100%-1.5rem)] w-64 space-y-2.5 overflow-auto rounded-xl border ${BORDER} bg-[#111318]/96 p-3 shadow-2xl shadow-black/60 backdrop-blur-md`, children: [_jsxs("div", { className: "flex items-center", children: [_jsx("div", { className: MICRO_LABEL, children: "Terrain" }), _jsx("button", { type: "button", className: `ml-auto rounded-[5px] px-2 py-0.5 text-neutral-500 transition-colors hover:bg-white/10 hover:text-neutral-200 ${FOCUS_RING}`, onClick: () => ui.setTool("select"), title: "Back to select tool", children: "\u00D7" })] }), _jsxs("div", { className: `space-y-1 border-b ${BORDER} pb-2`, children: [_jsx("button", { type: "button", className: `w-full ${BTN}`, onClick: bakeMinimap, title: "Rasterize the authored terrain into a stored minimap PNG the game reads at runtime", children: "Bake minimap" }), bakeStatus !== null ? (_jsx("div", { className: `text-[10px] leading-snug ${bakeStatus.tone === "error" ? "text-rose-300" : "text-emerald-300"}`, children: bakeStatus.text })) : null] }), !hasTerrain ? (_jsxs("div", { className: "space-y-2", children: [_jsx("p", { className: "text-[11px] leading-relaxed text-neutral-400", children: "No terrain yet. Create an editable heightfield over the scene, then sculpt its shape and paint material layers on it." }), _jsx("button", { type: "button", className: `w-full ${CONTROL_ACTIVE} rounded-[5px] px-2.5 py-1.5 text-[12px] font-semibold ${FOCUS_RING}`, onClick: createTerrain, children: "Create terrain" })] })) : (_jsxs(_Fragment, { children: [_jsx("div", { className: `flex gap-0.5 rounded-[6px] border ${BORDER} bg-black/40 p-0.5`, children: ["sculpt", "paint"].map((mode) => (_jsx("button", { type: "button", className: `flex-1 rounded-[5px] px-2 py-1 text-[11px] capitalize transition-colors ${FOCUS_RING} ${uiState.terrainMode === mode ? CONTROL_ACTIVE : "text-neutral-400 hover:bg-white/[0.06] hover:text-neutral-200"}`, onClick: () => ui.setTerrainMode(mode), children: mode }, mode))) }), uiState.terrainMode === "paint" ? _jsx(PaintControls, { session: session, ui: ui }) : _jsx(SculptControls, { ui: ui }), _jsxs("div", { className: `flex items-center justify-between gap-2 border-t ${BORDER} pt-2`, children: [_jsx("button", { type: "button", className: BTN, onClick: () => session.dispatch({ type: "undo" }), disabled: !session.canUndo(), children: "Undo" }), _jsx("button", { type: "button", className: `rounded-[5px] border border-rose-400/25 bg-rose-500/15 px-2 py-1 text-[11px] text-rose-200 transition-colors hover:bg-rose-500/25 ${FOCUS_RING}`, onClick: () => session.dispatch({ type: "clearTerrain" }), children: "Clear terrain" })] })] }))] }));
 }

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 })] }));
+}