@jgengine/editor 0.10.0

package/dist/TerrainPanel.js

@@ -0,0 +1,59 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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";
+const TERRAIN_BRUSHES = [
+    { kind: "raise", label: "Raise", hint: "Push terrain up" },
+    { kind: "lower", label: "Lower", hint: "Dig terrain down" },
+    { kind: "smooth", label: "Smooth", hint: "Average toward neighbors" },
+    { kind: "flatten", label: "Flatten", hint: "Level to a target height" },
+    { kind: "noise", label: "Noise", hint: "Roughen with fractal detail" },
+    { kind: "ramp", label: "Ramp", hint: "Drag a straight grade A→B" },
+];
+/** Sensible sculpt area when none is authored yet: the document footprint padded, or a 200m square. */
+function defaultTerrainBounds(document) {
+    const bounds = editorDocumentBounds(document);
+    if (bounds === null)
+        return { minX: -100, minZ: -100, maxX: 100, maxZ: 100 };
+    const pad = 40;
+    const minX = bounds.min.x - pad;
+    const minZ = bounds.min.z - pad;
+    const maxX = bounds.max.x + pad;
+    const maxZ = bounds.max.z + pad;
+    const span = Math.max(80, Math.min(400, Math.max(maxX - minX, maxZ - minZ)));
+    const cx = (minX + maxX) / 2;
+    const cz = (minZ + maxZ) / 2;
+    return { minX: cx - span / 2, minZ: cz - span / 2, maxX: cx + span / 2, maxZ: cz + span / 2 };
+}
+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] }));
+}
+function PaintControls({ session, ui }) {
+    const paint = ui.getState().paint;
+    const document = session.getState().document;
+    const paintDelta = (build) => {
+        if (document.terrain === undefined)
+            return;
+        const delta = build(editableTerrainFromSnapshot(document.terrain));
+        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" })] })] })] }));
+}
+/** The terrain-tool panel: create/clear the heightfield and drive the sculpt/paint controls. */
+export function TerrainPanel({ session, ui }) {
+    const [, setTick] = useState(0);
+    useEffect(() => ui.subscribe(() => setTick((value) => value + 1)), [ui]);
+    useEffect(() => session.subscribe(() => setTick((value) => value + 1)), [session]);
+    const uiState = ui.getState();
+    const document = session.getState().document;
+    const hasTerrain = document.terrain !== undefined;
+    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" })] })] }))] }));
+}

package/dist/TerrainSculpt.d.ts

@@ -0,0 +1,14 @@
+import type { WorldFeature } from "@jgengine/core/world/features";
+import type { EditorHostApi } from "./session.js";
+import { type EditorUiStore } from "./uiStore.js";
+/**
+ * Terrain-sculpt viewport layer: renders the editable heightfield and, while the terrain tool is
+ * active, converts pointer drags into brush strokes. A whole drag batches into one
+ * `sculptTerrain` command committed on release, so undo replays the stroke as a single step.
+ * @internal — mounted by `EditorApp`; not a game-author entry point.
+ */
+export declare const TerrainSculpt: import("react").MemoExoticComponent<({ api, ui, world, }: {
+    api: EditorHostApi;
+    ui: EditorUiStore;
+    world?: WorldFeature;
+}) => import("react").JSX.Element | null>;

package/dist/TerrainSculpt.js

@@ -0,0 +1,415 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useThree } from "@react-three/fiber";
+import { memo, useEffect, useMemo, useRef, useState } from "react";
+import * as THREE from "three";
+import { createTerrainPaletteSampler } from "@jgengine/core/world/terrain";
+import { beginSurfaceStroke, beginTerraformStroke, editableTerrainFromSnapshot, } from "@jgengine/core/world/terraform";
+import { useGameContext } from "@jgengine/react/provider";
+import { normalizeHeightBlend, TerraformBrushCursor } from "@jgengine/shell/terrain";
+import { editorPerfMarks } from "./perfMarks.js";
+import { TERRAIN_MATERIAL_COLORS } from "./uiStore.js";
+const GROUND_PLANE = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0);
+const LOW = new THREE.Color("#3f5d34");
+const HIGH = new THREE.Color("#8f9c66");
+const COLOR_SPAN = 24;
+/** Resolves a material layer to its render color (its tint, else its palette surface color). */
+function layerColor(layer) {
+    return layer.tint ?? TERRAIN_MATERIAL_COLORS[layer.surface] ?? "#7c7f86";
+}
+/** The game's `environment({ terrain })` descriptor, when the world it declares carries one — the same descriptor `TerrainGround` samples at runtime via `createTerrainPaletteSampler`. */
+function terrainDescriptorOf(world) {
+    return world?.kind === "environment" ? world.terrain : undefined;
+}
+/** The `[min, max]` height band `TerrainGround` blends `low`→`high` across for this descriptor (mirrors `EnvironmentScene.tsx`'s `TerrainGround` heightRange). */
+function heightRangeOf(descriptor) {
+    const base = descriptor.baseHeight ?? 0;
+    const swing = descriptor.height * 1.2;
+    return [base - swing, base + swing];
+}
+function segmentsFor(snapshot) {
+    return Math.max(8, Math.min(180, Math.max(snapshot.cols, snapshot.rows)));
+}
+function boundsKey(bounds, segments) {
+    return `${bounds.minX}:${bounds.minZ}:${bounds.maxX}:${bounds.maxZ}:${segments}`;
+}
+/** Effective brush mode after the invert modifier flips raise↔lower. */
+function effectiveBrush(brush, invert) {
+    if (!invert)
+        return brush;
+    if (brush === "raise")
+        return "lower";
+    if (brush === "lower")
+        return "raise";
+    return brush;
+}
+function editFromSettings(settings, center, clickHeight) {
+    const mode = effectiveBrush(settings.brush, settings.invert);
+    const heightLimit = settings.heightLimit.min === null && settings.heightLimit.max === null
+        ? undefined
+        : {
+            ...(settings.heightLimit.min === null ? {} : { min: settings.heightLimit.min }),
+            ...(settings.heightLimit.max === null ? {} : { max: settings.heightLimit.max }),
+        };
+    return {
+        mode,
+        center,
+        radius: settings.radius,
+        strength: settings.strength,
+        falloff: settings.falloff,
+        shape: settings.shape,
+        ...(mode === "flatten"
+            ? { target: settings.flattenHeight ?? clickHeight }
+            : {}),
+        ...(mode === "noise" ? { seed: settings.noiseSeed } : {}),
+        ...(heightLimit === undefined ? {} : { heightLimit }),
+    };
+}
+const PAINT_TINT = new THREE.Color();
+const BLEND_A = new THREE.Color();
+const BLEND_B = new THREE.Color();
+/** World-unit spacing between topographic relief bands drawn on the sculpt preview. */
+const CONTOUR_INTERVAL = 1.5;
+/**
+ * Topographic relief baked into a vertex's color so elevation reads from the editor's high camera,
+ * where lighting alone leaves gentle hills invisible. Smooth cosine bands every `CONTOUR_INTERVAL`
+ * darken slopes toward each band trough (a contour-map look) and higher ground brightens slightly —
+ * a `multiply`, so painted grass/dirt/rock keep their hue. Flat ground at a band height (the common
+ * unsculpted case at y=0) is left untouched: only varying height shows the bands. `strength` 0 is a
+ * no-op.
+ */
+function applyRelief(out, height, strength) {
+    if (strength <= 0)
+        return;
+    const band = 0.5 + 0.5 * Math.cos((height / CONTOUR_INTERVAL) * Math.PI * 2);
+    const relief = 1 - strength * 0.4 * (1 - band);
+    const lift = 1 + Math.max(-0.12, Math.min(0.22, height * 0.03)) * strength;
+    out.multiplyScalar(relief * lift);
+}
+/**
+ * The vertex tone under a world point: weighted layer blend, painted surface, or a height gradient.
+ * With no painted layer/surface at the point, `paletteAt` (the game's runtime terrain palette
+ * sampler, when the world declares one) supplies the low/high colors instead of the flat editor
+ * default — so `materialRegions`/base `colors`/`material` (worn paths, rock outcrops, biome tint)
+ * show through in the editor the same way `TerrainGround` renders them at runtime.
+ */
+function toneAt(terrain, x, z, height, out, paletteAt, heightRange) {
+    const layers = terrain.layers;
+    if (layers.length > 0) {
+        const weights = terrain.weightsAt(x, z);
+        if (weights.length === layers.length) {
+            let total = 0;
+            let r = 0;
+            let g = 0;
+            let b = 0;
+            for (let l = 0; l < layers.length; l += 1) {
+                const w = weights[l] * (layers[l].opacity ?? 1);
+                if (w <= 0)
+                    continue;
+                BLEND_B.set(layerColor(layers[l]));
+                r += BLEND_B.r * w;
+                g += BLEND_B.g * w;
+                b += BLEND_B.b * w;
+                total += w;
+            }
+            if (total > 0) {
+                out.setRGB(r / total, g / total, b / total);
+                return;
+            }
+        }
+    }
+    const surface = terrain.surfaceAt(x, z);
+    const painted = surface === null ? undefined : TERRAIN_MATERIAL_COLORS[surface];
+    if (painted !== undefined) {
+        out.copy(PAINT_TINT.set(painted));
+        return;
+    }
+    if (paletteAt !== null) {
+        const palette = paletteAt(x, z);
+        const blend = normalizeHeightBlend(height, heightRange[0], heightRange[1]);
+        out.copy(BLEND_A.set(palette.low).lerp(BLEND_B.set(palette.high), blend));
+        return;
+    }
+    const t = Math.max(0, Math.min(1, (height + COLOR_SPAN * 0.25) / COLOR_SPAN));
+    out.copy(BLEND_A.copy(LOW).lerp(HIGH, t));
+}
+/**
+ * Re-samples vertex Y and vertex color from the live terrain (in place — no reallocation). When a
+ * dirty `region` is given, only vertices inside it re-sample — the whole-mesh resample per stamp is
+ * the sculpt hot path — while normals recompute across the mesh for seamless shading. Painted/blended
+ * layers win the vertex color; unpainted ground falls back to the runtime terrain palette (or the
+ * flat height gradient with no descriptor). Records rebuild time.
+ */
+function displace(geometry, terrain, bounds, region, paletteAt, heightRange, contourStrength) {
+    const started = performance.now();
+    const position = geometry.attributes.position;
+    const cx = (bounds.minX + bounds.maxX) / 2;
+    const cz = (bounds.minZ + bounds.maxZ) / 2;
+    let colors = geometry.attributes.color;
+    const full = region === null || colors === undefined || colors.count !== position.count;
+    if (colors === undefined || colors.count !== position.count) {
+        colors = new THREE.BufferAttribute(new Float32Array(position.count * 3), 3);
+        geometry.setAttribute("color", colors);
+    }
+    const tone = new THREE.Color();
+    for (let index = 0; index < position.count; index += 1) {
+        const x = position.getX(index) + cx;
+        const z = position.getZ(index) + cz;
+        if (!full && (x < region.minX || x > region.maxX || z < region.minZ || z > region.maxZ))
+            continue;
+        const height = terrain.sampleHeight(x, z);
+        position.setY(index, height);
+        toneAt(terrain, x, z, height, tone, paletteAt, heightRange);
+        applyRelief(tone, height, contourStrength);
+        colors.setXYZ(index, tone.r, tone.g, tone.b);
+    }
+    position.needsUpdate = true;
+    colors.needsUpdate = true;
+    geometry.computeVertexNormals();
+    geometry.computeBoundingSphere();
+    editorPerfMarks.record("rebuild", performance.now() - started);
+}
+function SculptMesh({ terrain, bounds, segments, revision, regionRef, meshRef, paletteAt, heightRange, contourStrength, }) {
+    const geometry = useMemo(() => {
+        const width = Math.max(1, bounds.maxX - bounds.minX);
+        const depth = Math.max(1, bounds.maxZ - bounds.minZ);
+        const geo = new THREE.PlaneGeometry(width, depth, segments, segments);
+        geo.rotateX(-Math.PI / 2);
+        return geo;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [boundsKey(bounds, segments)]);
+    useEffect(() => () => geometry.dispose(), [geometry]);
+    useEffect(() => {
+        displace(geometry, terrain, bounds, regionRef.current, paletteAt, heightRange, contourStrength);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [geometry, terrain, revision, paletteAt, heightRange, contourStrength]);
+    return (_jsx("mesh", { ref: meshRef, geometry: geometry, receiveShadow: true, children: _jsx("meshStandardMaterial", { vertexColors: true, roughness: 0.95, metalness: 0, polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -1 }) }));
+}
+/**
+ * Terrain-sculpt viewport layer: renders the editable heightfield and, while the terrain tool is
+ * active, converts pointer drags into brush strokes. A whole drag batches into one
+ * `sculptTerrain` command committed on release, so undo replays the stroke as a single step.
+ * @internal — mounted by `EditorApp`; not a game-author entry point.
+ */
+export const TerrainSculpt = memo(function TerrainSculpt({ api, ui, world, }) {
+    const ctx = useGameContext();
+    const gl = useThree((state) => state.gl);
+    const camera = useThree((state) => state.camera);
+    const controls = useThree((state) => state.controls);
+    const session = api.getSession();
+    const terrainDescriptor = useMemo(() => terrainDescriptorOf(world), [world]);
+    const paletteAt = useMemo(() => (terrainDescriptor === undefined ? null : createTerrainPaletteSampler(terrainDescriptor)), [terrainDescriptor]);
+    const heightRange = useMemo(() => (terrainDescriptor === undefined ? [0, 1] : heightRangeOf(terrainDescriptor)), [terrainDescriptor]);
+    const [, setTick] = useState(0);
+    useEffect(() => session.subscribe(() => setTick((value) => value + 1)), [session]);
+    useEffect(() => ui.subscribe(() => setTick((value) => value + 1)), [ui]);
+    const snapshot = session.getState().document.terrain ?? null;
+    const base = ctx.world.ground;
+    const uiState = ui.getState();
+    const toolActive = uiState.tool === "terrain";
+    const editableRef = useRef(null);
+    const boundsRef = useRef(null);
+    const meshRef = useRef(null);
+    const syncedRef = useRef(null);
+    const gridKeyRef = useRef(null);
+    const regionRef = useRef(null);
+    const [revision, setRevision] = useState(0);
+    const [cursor, setCursor] = useState(null);
+    const segments = snapshot === null ? 0 : segmentsFor(snapshot);
+    const gridKey = snapshot === null ? null : `${boundsKey(snapshot.bounds, segments)}:${snapshot.cellSize}`;
+    // region === null forces a whole-mesh rebuild; a stamp passes only its dirty footprint.
+    const refresh = (region = null) => {
+        regionRef.current = region;
+        setRevision((value) => value + 1);
+    };
+    // Rebuild the live terrain when the grid changes; otherwise re-sync offsets on undo/redo/import.
+    useEffect(() => {
+        if (snapshot === null) {
+            editableRef.current = null;
+            boundsRef.current = null;
+            gridKeyRef.current = null;
+            syncedRef.current = null;
+            return;
+        }
+        if (gridKeyRef.current !== gridKey || editableRef.current === null) {
+            editableRef.current = editableTerrainFromSnapshot(snapshot, base);
+            boundsRef.current = snapshot.bounds;
+            gridKeyRef.current = gridKey;
+        }
+        else if (syncedRef.current !== snapshot) {
+            editableRef.current.restore(snapshot);
+        }
+        syncedRef.current = snapshot;
+        refresh();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [snapshot, gridKey, base]);
+    useEffect(() => {
+        if (!toolActive || snapshot === null) {
+            setCursor(null);
+            return;
+        }
+        const canvas = gl.domElement;
+        const raycaster = new THREE.Raycaster();
+        const ndc = new THREE.Vector2();
+        const planeHit = new THREE.Vector3();
+        let active = null;
+        let rampFrom = null;
+        let clickHeight = 0;
+        let last = null;
+        const pick = (clientX, clientY) => {
+            const started = performance.now();
+            const mesh = meshRef.current;
+            const rect = canvas.getBoundingClientRect();
+            ndc.set(((clientX - rect.left) / rect.width) * 2 - 1, -((clientY - rect.top) / rect.height) * 2 + 1);
+            raycaster.setFromCamera(ndc, camera);
+            let result = null;
+            if (mesh !== null) {
+                const hit = raycaster.intersectObject(mesh, false)[0];
+                if (hit !== undefined)
+                    result = { x: hit.point.x, z: hit.point.z };
+            }
+            if (result === null && raycaster.ray.intersectPlane(GROUND_PLANE, planeHit) !== null) {
+                result = { x: planeHit.x, z: planeHit.z };
+            }
+            editorPerfMarks.record("raycast", performance.now() - started);
+            return result;
+        };
+        // The dirty footprint of a stamp — its brush disc plus a two-cell margin for seamless normals.
+        const stampRegion = (point) => {
+            const state = ui.getState();
+            const radius = state.terrainMode === "paint" ? state.paint.radius : state.sculpt.radius;
+            const margin = radius + (snapshot?.cellSize ?? 1) * 2;
+            return { minX: point.x - margin, maxX: point.x + margin, minZ: point.z - margin, maxZ: point.z + margin };
+        };
+        const setControls = (enabled) => {
+            if (controls !== null && "enabled" in controls)
+                controls.enabled = enabled;
+        };
+        const stampSpacing = () => {
+            const state = ui.getState();
+            return state.terrainMode === "paint"
+                ? Math.max(0.5, state.paint.radius * 0.4)
+                : Math.max(0.25, state.sculpt.spacing);
+        };
+        const stamp = (point) => {
+            if (active === null)
+                return;
+            if (active.kind === "sculpt") {
+                active.stroke.stamp(editFromSettings(ui.getState().sculpt, [point.x, point.z], clickHeight));
+            }
+            else {
+                const paint = ui.getState().paint;
+                active.stroke.stamp({
+                    mode: "paint",
+                    center: [point.x, point.z],
+                    radius: paint.radius,
+                    surface: paint.material,
+                    shape: paint.shape,
+                });
+            }
+            last = [point.x, point.z];
+            refresh(stampRegion(point));
+        };
+        const onMove = (event) => {
+            const point = pick(event.clientX, event.clientY);
+            if (point === null)
+                return;
+            const terrain = editableRef.current;
+            const y = terrain === null ? 0 : terrain.sampleHeight(point.x, point.z);
+            setCursor({ x: point.x, y, z: point.z });
+            if (active === null || rampFrom !== null)
+                return;
+            if (last === null || Math.hypot(point.x - last[0], point.z - last[1]) >= stampSpacing())
+                stamp(point);
+        };
+        const onDown = (event) => {
+            if (event.button !== 0)
+                return;
+            const point = pick(event.clientX, event.clientY);
+            if (point === null)
+                return;
+            const terrain = editableRef.current;
+            if (terrain === null)
+                return;
+            event.preventDefault();
+            const mode = ui.getState().terrainMode;
+            // Alt-click in paint mode is the eyedropper — sample the material under the cursor.
+            if (mode === "paint" && event.altKey) {
+                const sampled = terrain.surfaceAt(point.x, point.z);
+                if (sampled !== null)
+                    ui.patchPaint({ material: sampled });
+                return;
+            }
+            setControls(false);
+            clickHeight = terrain.sampleHeight(point.x, point.z);
+            last = null;
+            if (mode === "paint") {
+                active = { kind: "paint", stroke: beginSurfaceStroke(terrain) };
+                stamp(point);
+            }
+            else if (ui.getState().sculpt.brush === "ramp") {
+                active = { kind: "sculpt", stroke: beginTerraformStroke(terrain) };
+                rampFrom = [point.x, point.z];
+            }
+            else {
+                active = { kind: "sculpt", stroke: beginTerraformStroke(terrain) };
+                stamp(point);
+            }
+        };
+        const commit = () => {
+            setControls(true);
+            const current = active;
+            active = null;
+            rampFrom = null;
+            last = null;
+            if (current === null)
+                return;
+            if (current.kind === "sculpt") {
+                const delta = current.stroke.delta();
+                if (delta.indices.length > 0)
+                    session.dispatch({ type: "sculptTerrain", delta });
+            }
+            else {
+                const delta = current.stroke.delta();
+                if (delta.indices.length > 0)
+                    session.dispatch({ type: "paintTerrain", delta });
+            }
+        };
+        const onUp = (event) => {
+            if (event.button !== 0 || active === null)
+                return;
+            if (rampFrom !== null && active.kind === "sculpt") {
+                const point = pick(event.clientX, event.clientY);
+                if (point !== null) {
+                    active.stroke.stamp({
+                        ...editFromSettings(ui.getState().sculpt, rampFrom, clickHeight),
+                        mode: "ramp",
+                        to: [point.x, point.z],
+                    });
+                    refresh();
+                }
+            }
+            commit();
+        };
+        const onLeave = () => {
+            if (active !== null)
+                commit();
+            setCursor(null);
+        };
+        canvas.addEventListener("pointerdown", onDown);
+        canvas.addEventListener("pointermove", onMove);
+        canvas.addEventListener("pointerup", onUp);
+        canvas.addEventListener("pointerleave", onLeave);
+        return () => {
+            if (active !== null)
+                commit();
+            canvas.removeEventListener("pointerdown", onDown);
+            canvas.removeEventListener("pointermove", onMove);
+            canvas.removeEventListener("pointerup", onUp);
+            canvas.removeEventListener("pointerleave", onLeave);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [toolActive, snapshot, gl, camera, controls, session, ui]);
+    if (snapshot === null || editableRef.current === null || boundsRef.current === null)
+        return null;
+    return (_jsxs(_Fragment, { children: [_jsx(SculptMesh, { terrain: editableRef.current, bounds: boundsRef.current, segments: segments, revision: revision, regionRef: regionRef, meshRef: meshRef, paletteAt: paletteAt, heightRange: heightRange, contourStrength: toolActive ? 1 : 0.45 }), toolActive && cursor !== null ? (_jsx(TerraformBrushCursor, { center: [cursor.x, cursor.z], y: cursor.y + 0.1, radius: uiState.terrainMode === "paint" ? uiState.paint.radius : uiState.sculpt.radius, mode: uiState.terrainMode === "paint" ? "paint" : effectiveBrush(uiState.sculpt.brush, uiState.sculpt.invert) })) : null] }));
+});

package/dist/TriggerInspector.d.ts

@@ -0,0 +1,13 @@
+import { type TriggerSourceKind } from "@jgengine/core/scene/authoredTriggers";
+import { type MetaPatch } from "./SchemaInspector.js";
+/**
+ * Inspector block for the authored-trigger vocabulary (`on` / `action` + action params).
+ * Renders only when the game has registered at least one action for this target; params come from
+ * the declared action's ParamSchema via SchemaInspector.
+ * @internal
+ */
+export declare function TriggerInspector({ target, meta, onMeta, }: {
+    target: TriggerSourceKind;
+    meta: Record<string, unknown> | undefined;
+    onMeta: MetaPatch;
+}): import("react").JSX.Element | null;

package/dist/TriggerInspector.js

@@ -0,0 +1,60 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { getTriggerAction, listTriggerActions, readFlatTrigger, TRIGGER_ACTION_KEY, TRIGGER_LIST_KEY, TRIGGER_ON_KEY, TRIGGER_RADIUS_KEY, } from "@jgengine/core/scene/authoredTriggers";
+import { defaultParamMeta, parseParams } from "@jgengine/core/scene/sceneKinds";
+import { SchemaInspector } from "./SchemaInspector.js";
+import { INPUT, MICRO } from "./chromeStyles.js";
+import { NumberField } from "./chromeFields.js";
+const EVENTS = [
+    { value: "", label: "— none —" },
+    { value: "enter", label: "On enter" },
+    { value: "exit", label: "On exit" },
+    { value: "interact", label: "On interact" },
+];
+/**
+ * Inspector block for the authored-trigger vocabulary (`on` / `action` + action params).
+ * Renders only when the game has registered at least one action for this target; params come from
+ * the declared action's ParamSchema via SchemaInspector.
+ * @internal
+ */
+export function TriggerInspector({ target, meta, onMeta, }) {
+    const actions = listTriggerActions(target);
+    if (actions.length === 0)
+        return null;
+    const flat = readFlatTrigger(meta);
+    const multi = Array.isArray(meta?.[TRIGGER_LIST_KEY]);
+    const actionDef = flat.action.length > 0 ? getTriggerAction(flat.action) : undefined;
+    const allowedEvents = actionDef?.events;
+    const eventOptions = EVENTS.filter((entry) => entry.value === "" || allowedEvents === undefined || allowedEvents.includes(entry.value));
+    const writeTrigger = (on, action) => {
+        if (on === "" || action.length === 0) {
+            onMeta({ [TRIGGER_ON_KEY]: "", [TRIGGER_ACTION_KEY]: "", [TRIGGER_LIST_KEY]: [] }, "trigger:clear");
+            return;
+        }
+        const patch = {
+            [TRIGGER_ON_KEY]: on,
+            [TRIGGER_ACTION_KEY]: action,
+            [TRIGGER_LIST_KEY]: [],
+        };
+        const definition = getTriggerAction(action);
+        if (definition !== undefined) {
+            const defaults = defaultParamMeta(definition.schema);
+            for (const [key, value] of Object.entries(defaults)) {
+                if (meta?.[key] === undefined)
+                    patch[key] = value;
+            }
+        }
+        onMeta(patch, "trigger:set");
+    };
+    const onParamMeta = (patch, coalesce) => {
+        onMeta({ ...(meta ?? {}), ...patch }, coalesce);
+    };
+    return (_jsxs("div", { className: "space-y-2 rounded-lg border border-amber-400/15 bg-amber-500/[0.06] p-2.5", children: [_jsx("div", { className: "text-[9px] font-semibold uppercase tracking-[0.14em] text-amber-300", children: "Behavior trigger" }), multi ? (_jsxs("div", { className: "text-[10px] text-neutral-400", children: ["Multi-trigger list on this object \u2014 edit via document JSON / RPC. Clear list to use the simple editor.", _jsx("button", { type: "button", className: "mt-1 block rounded-md bg-white/[0.07] px-2 py-1 text-[10px] ring-1 ring-inset ring-white/[0.06] hover:bg-white/15", onClick: () => onMeta({ [TRIGGER_LIST_KEY]: [] }, "trigger:unlist"), children: "Clear multi-list" })] })) : (_jsxs(_Fragment, { children: [_jsxs("label", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: MICRO, children: "on" }), _jsx("select", { className: `w-36 ${INPUT}`, value: flat.on, onChange: (event) => {
+                                    const on = event.target.value;
+                                    if (on === "")
+                                        writeTrigger("", "");
+                                    else
+                                        writeTrigger(on, flat.action.length > 0 ? flat.action : (actions[0]?.id ?? ""));
+                                }, children: eventOptions.map((entry) => (_jsx("option", { value: entry.value, children: entry.label }, entry.value || "none"))) })] }), _jsxs("label", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: MICRO, children: "action" }), _jsxs("select", { className: `w-36 ${INPUT}`, value: flat.action, disabled: flat.on === "", onChange: (event) => writeTrigger(flat.on === "" ? "enter" : flat.on, event.target.value), children: [_jsx("option", { value: "", children: "\u2014 choose \u2014" }), actions.map((action) => (_jsx("option", { value: action.id, children: action.label }, action.id)))] })] }), target === "marker" && flat.on !== "" ? (_jsx(NumberField, { label: "trigger r", step: 0.5, value: typeof meta?.[TRIGGER_RADIUS_KEY] === "number" ? meta[TRIGGER_RADIUS_KEY] : typeof meta?.["radius"] === "number" ? meta["radius"] : 2.5, onCommit: (value) => onParamMeta({ [TRIGGER_RADIUS_KEY]: Math.max(0, value) }, "trigger:radius") })) : null, actionDef !== undefined && actionDef.schema.fields.some((field) => field.type !== "action") ? (_jsx(SchemaInspector, { schema: actionDef.schema, label: `${actionDef.label} params`, accent: "#fbbf24", meta: meta, onMeta: onParamMeta, note: flat.on === ""
+                            ? undefined
+                            : `${flat.on} → ${actionDef.id} (${Object.keys(parseParams(actionDef.schema, meta)).length} params)` })) : null] }))] }));
+}

package/dist/agent/AgentPanel.d.ts

@@ -0,0 +1,13 @@
+import type { EditorHostApi } from "../session.js";
+import { createDefaultAgentEndpoint } from "./endpoint.js";
+/**
+ * Dockable in-editor agent chat: humans and agents share the same RPC/undo surface.
+ * Tool calls route through `EditorHostApi.handle`; patches appear in the transcript and can be undone.
+ * @internal — mounted by `EditorChrome`.
+ */
+export declare function AgentPanel({ api, onClose, }: {
+    api: EditorHostApi;
+    onClose: () => void;
+}): import("react").JSX.Element;
+/** Re-export for hosts that want a default endpoint without the panel. */
+export { createDefaultAgentEndpoint };