@jgengine/editor 0.14.0 → 0.15.0

package/dist/EditorApp.js

@@ -261,7 +261,6 @@ export function EditorApp({ gameId, playable, layers, catalogs, save, modeChip,
     if (readoutStoreRef.current === null)
         readoutStoreRef.current = createTerrainReadoutStore();
     const readout = readoutStoreRef.current;
-    const [mode, setModeState] = useState("edit");
     const catalogAssets = useMemo(() => {
         try {
             const ids = playable.game.assets.ids();
@@ -286,7 +285,8 @@ export function EditorApp({ gameId, playable, layers, catalogs, save, modeChip,
         };
     }, [gameId, resolvedLayers, catalogs, catalogAssets]);
     useEffect(() => host.dispose, [host]);
-    useEffect(() => host.api.subscribeMode(setModeState), [host]);
+    const modeStore = useMemo(() => ({ getState: host.api.getMode, subscribe: host.api.subscribeMode }), [host]);
+    const mode = useStoreSelector(modeStore, (m) => m);
     const [pendingDraft, setPendingDraft] = useState(null);
     useEffect(() => {
         const draft = readDraft(gameId);

package/dist/EditorCameraDriver.d.ts

@@ -1,5 +1,10 @@
 import type { EditorHostApi } from "./session.js";
-/** Smoothly pans the orbit camera to the editor host's focus target when it changes. */
+/**
+ * Drives the editor orbit camera from the host's focus target. When the target carries only a
+ * point, the camera pans to keep it centered (the historical behavior). When it also carries
+ * placement (`distance`/`pitch`/`yaw`/`height`), the camera is repositioned to that orbit pose —
+ * how `camera_goto`/`camera_frame` compose an aerial without the KeyF-buries-in-terrain problem.
+ */
 export declare const EditorCameraDriver: import("react").MemoExoticComponent<({ api }: {
     api: EditorHostApi;
 }) => null>;

package/dist/EditorCameraDriver.js

@@ -1,6 +1,12 @@
 import { useThree } from "@react-three/fiber";
 import { memo, useEffect } from "react";
-/** Smoothly pans the orbit camera to the editor host's focus target when it changes. */
+import { orbitCameraPosition } from "./camera/orbitFraming.js";
+/**
+ * Drives the editor orbit camera from the host's focus target. When the target carries only a
+ * point, the camera pans to keep it centered (the historical behavior). When it also carries
+ * placement (`distance`/`pitch`/`yaw`/`height`), the camera is repositioned to that orbit pose —
+ * how `camera_goto`/`camera_frame` compose an aerial without the KeyF-buries-in-terrain problem.
+ */
 export const EditorCameraDriver = memo(function EditorCameraDriver({ api }) {
     const controls = useThree((state) => state.controls);
     const camera = useThree((state) => state.camera);
@@ -8,6 +14,24 @@ export const EditorCameraDriver = memo(function EditorCameraDriver({ api }) {
         return api.subscribeFocus((target) => {
             if (target === null || controls === null || controls.target === undefined)
                 return;
+            const hasPlacement = target.distance !== undefined ||
+                target.pitch !== undefined ||
+                target.yaw !== undefined ||
+                target.height !== undefined;
+            if (hasPlacement) {
+                controls.target.set(target.x, target.y, target.z);
+                const distance = target.distance ?? camera.position.distanceTo(controls.target);
+                const pose = orbitCameraPosition({
+                    target,
+                    distance,
+                    pitchDeg: target.pitch ?? 45,
+                    yawDeg: target.yaw,
+                    height: target.height,
+                });
+                camera.position.set(pose.x, pose.y, pose.z);
+                controls.update();
+                return;
+            }
             const previous = controls.target.clone();
             controls.target.set(target.x, target.y, target.z);
             camera.position.add(controls.target.clone().sub(previous));

package/dist/EditorChrome.js

@@ -15,6 +15,7 @@ import { buildOutlinerGroups } from "./outlinerModel.js";
 import { importAssetToHost, loadDroppedAssets, } from "./assetImport.js";
 import { newPlacementId } from "./uiStore.js";
 import { useF2Chord } from "./useF2Chord.js";
+import { useStoreVersion } from "./useStoreSelector.js";
 import { TerrainPanel } from "./TerrainPanel.js";
 import { LightingPanel } from "./LightingPanel.js";
 import { InspectorPanel } from "./InspectorPanel.js";
@@ -112,10 +113,10 @@ const LEFT_PAGES = [
  * and host RPC. Mounted by `EditorApp`; not a game-author entry point.
  */
 export function EditorChrome({ gameId, session, api, assets, ui, baselineDocument, save, networkSnapshot, importAsset = importAssetToHost, onRegisterAsset, onExitEditor, }) {
-    const [, setTick] = useState(0);
     const layoutRef = useRef(null);
     layoutRef.current ??= createShellLayoutStore(gameId);
     const layout = layoutRef.current;
+    useStoreVersion(session, ui, layout);
     const consoleRef = useRef(null);
     consoleRef.current ??= createEditorConsoleStore();
     const consoleStore = consoleRef.current;
@@ -171,9 +172,6 @@ export function EditorChrome({ gameId, session, api, assets, ui, baselineDocumen
     useF2Chord("KeyE", () => api.setMode("play"));
     // F2+Q leaves the editor entirely (back to the game) — only meaningful when summoned over one.
     useF2Chord("KeyQ", useCallback(() => onExitEditor?.(), [onExitEditor]));
-    useEffect(() => session.subscribe(() => setTick((value) => value + 1)), [session]);
-    useEffect(() => ui.subscribe(() => setTick((value) => value + 1)), [ui]);
-    useEffect(() => layout.subscribe(() => setTick((value) => value + 1)), [layout]);
     const copySelection = useCallback(() => {
         const current = session.getState();
         if (current.selection.length === 0)

package/dist/InspectorPanel.js

@@ -6,6 +6,7 @@ import { getSceneKind, isSceneKind, parseParams, } from "@jgengine/core/scene/sc
 import { getAssetGenerator } from "@jgengine/core/scene/assetGenerator";
 import { markerCatalogId } from "@jgengine/core/world/authoredObjects";
 import { useGameContext } from "@jgengine/react/provider";
+import { useDebouncedCommit } from "@jgengine/react/useDebouncedCommit";
 import { canAuthorTrigger, clearMaterialAssignmentPatch, clearTriggerInstallPatch, defaultTriggerInstallPatch, hasAuthoredTrigger, hasMaterialAssignment, } from "./authoredComponentMeta.js";
 import { SchemaInspector } from "./SchemaInspector.js";
 import { TriggerInspector } from "./TriggerInspector.js";
@@ -21,6 +22,16 @@ import { Icon, kindIcon } from "./shell/icons.js";
 import { CoverageSection } from "./shell/scatterCoverage.js";
 import { FOCUS_RING, INPUT_CLS, NUMERIC } from "./shell/theme.js";
 import { CollapsibleSection, EmptyState, IconButton, PanelTabs } from "./shell/ui.js";
+/** Live-mirrored, debounced density slider — grass regen only fires on pause/release, not per step (#1372). */
+function VegetationDensitySlider({ density, sliderMax, onMeta, }) {
+    const { value: local, onInput, flush } = useDebouncedCommit(density, (next) => onMeta({ density: next }, "veg:density"));
+    return (_jsxs("label", { className: "block space-y-1", children: [_jsxs("span", { className: "flex items-center justify-between", children: [_jsx("span", { className: "text-[9px] font-semibold uppercase tracking-wider text-neutral-500", children: "density /m\u00B2" }), _jsx("span", { className: "text-cyan-200", children: local.toFixed(2) })] }), _jsx("input", { type: "range", min: 0, max: sliderMax, step: sliderMax / 200, className: "w-full accent-emerald-400", value: Math.min(local, sliderMax), onChange: (event) => onInput(Number(event.target.value)), onPointerUp: flush, onKeyUp: flush, onBlur: flush })] }));
+}
+/** Live-mirrored, debounced item/seed text — avoids a scene patch (and grass regen) per keystroke (#1372). */
+function VegetationTextField({ label, field, value, placeholder, onMeta, }) {
+    const { value: local, onInput, flush } = useDebouncedCommit(value, (next) => onMeta({ [field]: next }, `veg:${field}`));
+    return (_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: label }), _jsx("input", { className: `w-32 ${INPUT}`, value: local, placeholder: placeholder, onChange: (event) => onInput(event.target.value), onBlur: flush })] }));
+}
 function VegetationFields({ volume, onMeta, }) {
     const settings = readVegetationSettings(volume);
     if (settings === null)
@@ -29,7 +40,7 @@ function VegetationFields({ volume, onMeta, }) {
     const areaM2 = (footprint.maxX - footprint.minX) * (footprint.maxZ - footprint.minZ);
     const sliderMax = settings.item === "grass" ? 12 : 1;
     const estimated = Math.floor(areaM2 * settings.density);
-    return (_jsxs("div", { className: "space-y-2", children: [_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: "item" }), _jsx("input", { className: `w-32 ${INPUT}`, value: settings.item, placeholder: "grass", onChange: (event) => onMeta({ item: event.target.value }, "veg:item") })] }), _jsxs("label", { className: "block space-y-1", children: [_jsxs("span", { className: "flex items-center justify-between", children: [_jsx("span", { className: "text-[9px] font-semibold uppercase tracking-wider text-neutral-500", children: "density /m\u00B2" }), _jsx("span", { className: "text-cyan-200", children: settings.density.toFixed(2) })] }), _jsx("input", { type: "range", min: 0, max: sliderMax, step: sliderMax / 200, className: "w-full accent-emerald-400", value: Math.min(settings.density, sliderMax), onChange: (event) => onMeta({ density: Number(event.target.value) }, "veg:density") })] }), _jsx(NumberField, { label: "density", step: 0.01, value: settings.density, onCommit: (value) => onMeta({ density: Math.max(0, value) }, "veg:density") }), _jsx(NumberField, { label: "min scale", step: 0.05, value: settings.minScale, onCommit: (value) => onMeta({ minScale: value }, "veg:minScale") }), _jsx(NumberField, { label: "max scale", step: 0.05, value: settings.maxScale, onCommit: (value) => onMeta({ maxScale: value }, "veg:maxScale") }), _jsx(NumberField, { label: "spacing", step: 0.25, value: settings.minDistance, onCommit: (value) => onMeta({ minDistance: Math.max(0, value) }, "veg:minDistance") }), _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", { className: `w-32 ${INPUT}`, value: settings.seed, placeholder: "reroll\u2026", onChange: (event) => onMeta({ seed: event.target.value }, "veg:seed") })] }), _jsxs("div", { className: "text-[10px] text-neutral-500", children: ["\u2248 ", estimated.toLocaleString(), " ", settings.item === "grass" ? "blades" : "placements", " over ", Math.round(areaM2).toLocaleString(), " m\u00B2"] })] }));
+    return (_jsxs("div", { className: "space-y-2", children: [_jsx(VegetationTextField, { label: "item", field: "item", value: settings.item, placeholder: "grass", onMeta: onMeta }), _jsx(VegetationDensitySlider, { density: settings.density, sliderMax: sliderMax, onMeta: onMeta }), _jsx(NumberField, { label: "density", step: 0.01, value: settings.density, onCommit: (value) => onMeta({ density: Math.max(0, value) }, "veg:density") }), _jsx(NumberField, { label: "min scale", step: 0.05, value: settings.minScale, onCommit: (value) => onMeta({ minScale: value }, "veg:minScale") }), _jsx(NumberField, { label: "max scale", step: 0.05, value: settings.maxScale, onCommit: (value) => onMeta({ maxScale: value }, "veg:maxScale") }), _jsx(NumberField, { label: "spacing", step: 0.25, value: settings.minDistance, onCommit: (value) => onMeta({ minDistance: Math.max(0, value) }, "veg:minDistance") }), _jsx(VegetationTextField, { label: "seed", field: "seed", value: settings.seed, placeholder: "reroll\u2026", onMeta: onMeta }), _jsxs("div", { className: "text-[10px] text-neutral-500", children: ["\u2248 ", estimated.toLocaleString(), " ", settings.item === "grass" ? "blades" : "placements", " over ", Math.round(areaM2).toLocaleString(), " m\u00B2"] })] }));
 }
 /** Builds the resolver-facing view of a document object for a registered scene kind's inspector. */
 function markerObject(marker) {

package/dist/ParentPickerMenu.js

@@ -1,5 +1,5 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useMemo, useState } from "react";
 import { FOCUS_RING, INPUT_CLS, NUMERIC } from "./shell/theme.js";
 /**
  * Searchable parent-target menu for hierarchy / viewport "Parent to…".
@@ -8,17 +8,13 @@ import { FOCUS_RING, INPUT_CLS, NUMERIC } from "./shell/theme.js";
  */
 export function ParentPickerMenu({ x, y, candidates, onPick, onClose, }) {
     const [query, setQuery] = useState("");
-    const inputRef = useRef(null);
-    useEffect(() => {
-        inputRef.current?.focus();
-    }, []);
     const filtered = useMemo(() => {
         const q = query.trim().toLowerCase();
         if (q.length === 0)
             return candidates;
         return candidates.filter((entry) => entry.label.toLowerCase().includes(q) || entry.id.toLowerCase().includes(q));
     }, [candidates, query]);
-    return (_jsxs(_Fragment, { children: [_jsx("div", { className: "pointer-events-auto fixed inset-0 z-[60]", onPointerDown: onClose, onContextMenu: (event) => event.preventDefault() }), _jsxs("div", { role: "menu", "aria-label": "Parent to object", className: "pointer-events-auto fixed z-[61] flex max-h-72 w-64 flex-col overflow-hidden rounded-md border border-white/15 bg-neutral-900/95 shadow-2xl backdrop-blur-sm", style: { left: x, top: y }, onContextMenu: (event) => event.preventDefault(), children: [_jsx("div", { className: "border-b border-white/10 px-3 py-1.5 text-[10px] font-semibold uppercase tracking-wider text-white/45", children: "Parent to\u2026" }), _jsx("div", { className: "border-b border-white/10 p-1.5", children: _jsx("input", { ref: inputRef, value: query, onChange: (event) => setQuery(event.target.value), onKeyDown: (event) => {
+    return (_jsxs(_Fragment, { children: [_jsx("div", { className: "pointer-events-auto fixed inset-0 z-[60]", onPointerDown: onClose, onContextMenu: (event) => event.preventDefault() }), _jsxs("div", { role: "menu", "aria-label": "Parent to object", className: "pointer-events-auto fixed z-[61] flex max-h-72 w-64 flex-col overflow-hidden rounded-md border border-white/15 bg-neutral-900/95 shadow-2xl backdrop-blur-sm", style: { left: x, top: y }, onContextMenu: (event) => event.preventDefault(), children: [_jsx("div", { className: "border-b border-white/10 px-3 py-1.5 text-[10px] font-semibold uppercase tracking-wider text-white/45", children: "Parent to\u2026" }), _jsx("div", { className: "border-b border-white/10 p-1.5", children: _jsx("input", { autoFocus: true, value: query, onChange: (event) => setQuery(event.target.value), onKeyDown: (event) => {
                                 if (event.key === "Escape") {
                                     event.preventDefault();
                                     onClose();

package/dist/RuntimePlayBridge.js

@@ -1,9 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import { useFrame } from "@react-three/fiber";
 import { useGameContext } from "@jgengine/react/provider";
 import { MICRO } from "./chromeStyles.js";
-import { PlayModeBar } from "./shell/PlayModeBar.js";
+import { PlayModeBar, usePlayControl } from "./shell/PlayModeBar.js";
 const PUBLISH_MS = 100;
 function metaValues(meta) {
     if (meta === null || typeof meta !== "object" || Array.isArray(meta))
@@ -83,11 +83,9 @@ export function RuntimePlayPublisher({ api }) {
  * @internal
  */
 export function RuntimePlayInspectorChrome({ gameId, api, onExit, }) {
-    const [play, setPlay] = useState(() => api.getPlayControl());
+    const play = usePlayControl(api);
     const [summary, setSummary] = useState(null);
     const [selectedId, setSelectedId] = useState(null);
-    const [detail, setDetail] = useState("");
-    useEffect(() => api.subscribePlayControl(setPlay), [api]);
     useEffect(() => {
         const tick = () => {
             const result = api.handle({ method: "runtime_summary" });
@@ -99,17 +97,14 @@ export function RuntimePlayInspectorChrome({ gameId, api, onExit, }) {
         const timer = setInterval(tick, PUBLISH_MS);
         return () => clearInterval(timer);
     }, [api]);
-    useEffect(() => {
-        if (selectedId === null) {
-            setDetail("");
-            return;
-        }
+    const detail = useMemo(() => {
+        if (selectedId === null)
+            return "";
         const got = api.handle({ method: "runtime_get", id: selectedId });
-        if (!got.ok) {
-            setDetail(got.error ?? "missing");
-            return;
-        }
-        setDetail(JSON.stringify(got.result, null, 2));
+        if (!got.ok)
+            return got.error ?? "missing";
+        return JSON.stringify(got.result, null, 2);
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- entityCount/play are poll-tick cache keys
     }, [api, selectedId, summary?.entityCount, play.pendingSteps, play.paused]);
     const nudgeSelected = (axis, delta) => {
         if (selectedId === null)

package/dist/SchemaInspector.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from "react";
 import { parseParams, randomizeGroupParams, resetGroupParams, } from "@jgengine/core/scene/sceneKinds";
+import { useDebouncedCommit } from "@jgengine/react/useDebouncedCommit";
 import { BORDER, CONTROL, FOCUS_RING, INPUT_CLS, MICRO_LABEL } from "./shell/theme.js";
 const INPUT = `px-2 py-1 ${INPUT_CLS}`;
 const MICRO = MICRO_LABEL;
@@ -19,22 +20,56 @@ function PresetRow({ schema, onMeta }) {
 function labelOf(field) {
     return field.label ?? field.key;
 }
+/** Range field: live-mirrored thumb + readout, debounced commit, flush on release/blur/keyup (#1372). */
+function RangeField({ field, value, coalesce, onMeta, }) {
+    const { value: local, onInput, flush } = useDebouncedCommit(value, (next) => onMeta({ [field.key]: next }, coalesce));
+    return (_jsxs("label", { className: "block space-y-1", children: [_jsxs("span", { className: "flex items-center justify-between", children: [_jsx("span", { className: MICRO, children: labelOf(field) }), _jsxs("span", { className: "text-cyan-200", children: [local.toFixed(field.step !== undefined && field.step >= 1 ? 0 : 2), field.unit ?? ""] })] }), _jsx("input", { type: "range", min: field.min, max: field.max, step: field.step ?? (field.max - field.min) / 100, value: local, className: "w-full accent-emerald-400", onChange: (event) => onInput(Number(event.target.value)), onPointerUp: flush, onKeyUp: flush, onBlur: flush })] }));
+}
+/** Number field: debounced commit, flush on blur (#1372). */
+function NumberInputField({ field, value, coalesce, onMeta, }) {
+    const { value: local, onInput, flush } = useDebouncedCommit(value, (next) => onMeta({ [field.key]: next }, coalesce));
+    return (_jsxs("label", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: MICRO, children: labelOf(field) }), _jsx("input", { type: "number", step: field.step ?? 1, className: `w-32 ${INPUT}`, value: local, onChange: (event) => {
+                    const next = Number(event.target.value);
+                    if (Number.isFinite(next))
+                        onInput(next);
+                }, onBlur: flush })] }));
+}
+/** Color field: debounced commit while the picker drags, flush on blur (#1372). */
+function ColorField({ field, value, coalesce, onMeta, }) {
+    const { value: local, onInput, flush } = useDebouncedCommit(value, (next) => onMeta({ [field.key]: next }, coalesce));
+    return (_jsxs("label", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: MICRO, children: labelOf(field) }), _jsx("input", { type: "color", className: `h-7 w-14 cursor-pointer rounded-[5px] border border-white/10 bg-black/40 ${FOCUS_RING}`, value: local, onChange: (event) => onInput(event.target.value), onBlur: flush })] }));
+}
+/** Text field: debounced commit while typing, flush on blur (#1372). */
+function TextField({ field, value, coalesce, onMeta, }) {
+    const { value: local, onInput, flush } = useDebouncedCommit(value, (next) => onMeta({ [field.key]: next }, coalesce));
+    return (_jsxs("label", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: MICRO, children: labelOf(field) }), _jsx("input", { className: `w-32 min-w-0 ${INPUT}`, value: local, onChange: (event) => onInput(event.target.value), onBlur: flush })] }));
+}
+/** Seed field: debounced text commit while typing (reroll button commits immediately) (#1372). */
+function SeedField({ field, value, coalesce, onMeta, }) {
+    const { value: local, onInput, flush } = useDebouncedCommit(value, (next) => onMeta({ [field.key]: next }, coalesce));
+    return (_jsxs("div", { className: "flex items-center gap-2", children: [_jsxs("label", { className: "flex min-w-0 flex-1 items-center gap-2", children: [_jsx("span", { className: MICRO, children: labelOf(field) }), _jsx("input", { className: `w-full min-w-0 ${INPUT}`, value: local, placeholder: "reroll\u2026", onChange: (event) => onInput(event.target.value), onBlur: flush })] }), _jsx("button", { type: "button", className: BTN, title: "Reroll seed", onClick: () => {
+                    flush();
+                    onMeta({ [field.key]: `r${Math.abs(Math.round((local.length + 1) * 2654435761)).toString(36).slice(0, 6)}${local.length}` }, coalesce);
+                }, children: "\u27F3" })] }));
+}
+/** Weighted-list field: debounced item/weight commits share one mirrored array; add/remove commit now (#1372). */
+function WeightedListField({ field, value, coalesce, onMeta, }) {
+    const { value: list, onInput, flush } = useDebouncedCommit(value, (next) => onMeta({ [field.key]: next }, coalesce));
+    // Add/remove are discrete structural edits — commit them immediately through the same mirror.
+    const setNow = (next) => {
+        onInput(next);
+        flush();
+    };
+    return (_jsxs("div", { className: "space-y-1", children: [_jsx("div", { className: MICRO, children: labelOf(field) }), list.map((entry, index) => (_jsxs("div", { className: "flex items-center gap-1", children: [_jsx("input", { className: `min-w-0 flex-1 ${INPUT}`, value: entry.item, placeholder: field.itemLabel ?? "id", onChange: (event) => onInput(list.map((e, i) => (i === index ? { ...e, item: event.target.value } : e))), onBlur: flush }), _jsx("input", { type: "number", step: 1, min: 0, className: `w-14 ${INPUT}`, value: entry.weight, onChange: (event) => onInput(list.map((e, i) => (i === index ? { ...e, weight: Math.max(0, Number(event.target.value)) } : e))), onBlur: flush }), _jsx("button", { type: "button", className: `${CONTROL} px-1.5 py-1 text-neutral-400 hover:bg-rose-500/20 hover:text-rose-200 disabled:opacity-40`, disabled: list.length <= 1, onClick: () => setNow(list.filter((_, i) => i !== index)), children: "\u00D7" })] }, index))), _jsx("button", { type: "button", className: `w-full ${BTN}`, onClick: () => setNow([...list, { item: "", weight: 1 }]), children: "+ row" })] }));
+}
 function FieldRow({ field, meta, onMeta }) {
     const params = parseParams({ fields: [field] }, meta);
     const coalesce = `kind:${field.key}`;
     switch (field.type) {
-        case "range": {
-            const value = params[field.key];
-            return (_jsxs("label", { className: "block space-y-1", children: [_jsxs("span", { className: "flex items-center justify-between", children: [_jsx("span", { className: MICRO, children: labelOf(field) }), _jsxs("span", { className: "text-cyan-200", children: [value.toFixed(field.step !== undefined && field.step >= 1 ? 0 : 2), field.unit ?? ""] })] }), _jsx("input", { type: "range", min: field.min, max: field.max, step: field.step ?? (field.max - field.min) / 100, value: value, className: "w-full accent-emerald-400", onChange: (event) => onMeta({ [field.key]: Number(event.target.value) }, coalesce) })] }));
-        }
-        case "number": {
-            const value = params[field.key];
-            return (_jsxs("label", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: MICRO, children: labelOf(field) }), _jsx("input", { type: "number", step: field.step ?? 1, className: `w-32 ${INPUT}`, value: value, onChange: (event) => {
-                            const next = Number(event.target.value);
-                            if (Number.isFinite(next))
-                                onMeta({ [field.key]: next }, coalesce);
-                        } })] }));
-        }
+        case "range":
+            return _jsx(RangeField, { field: field, value: params[field.key], coalesce: coalesce, onMeta: onMeta });
+        case "number":
+            return _jsx(NumberInputField, { field: field, value: params[field.key], coalesce: coalesce, onMeta: onMeta });
         case "bool": {
             const value = params[field.key];
             return (_jsxs("label", { className: "flex items-center gap-1.5 text-[10px] text-neutral-400", children: [_jsx("input", { type: "checkbox", className: "accent-emerald-400", checked: value, onChange: (event) => onMeta({ [field.key]: event.target.checked }, coalesce) }), labelOf(field)] }));
@@ -43,23 +78,14 @@ function FieldRow({ field, meta, onMeta }) {
             const value = params[field.key];
             return (_jsxs("label", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: MICRO, children: labelOf(field) }), _jsx("select", { className: `w-32 ${INPUT}`, value: value, onChange: (event) => onMeta({ [field.key]: event.target.value }, coalesce), children: field.options.map((option) => (_jsx("option", { value: option.value, children: option.label ?? option.value }, option.value))) })] }));
         }
-        case "color": {
-            const value = params[field.key];
-            return (_jsxs("label", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: MICRO, children: labelOf(field) }), _jsx("input", { type: "color", className: `h-7 w-14 cursor-pointer rounded-[5px] border border-white/10 bg-black/40 ${FOCUS_RING}`, value: value, onChange: (event) => onMeta({ [field.key]: event.target.value }, coalesce) })] }));
-        }
-        case "text": {
-            const value = params[field.key];
-            return (_jsxs("label", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: MICRO, children: labelOf(field) }), _jsx("input", { className: `w-32 min-w-0 ${INPUT}`, value: value, onChange: (event) => onMeta({ [field.key]: event.target.value }, coalesce) })] }));
-        }
-        case "seed": {
-            const value = params[field.key];
-            return (_jsxs("div", { className: "flex items-center gap-2", children: [_jsxs("label", { className: "flex min-w-0 flex-1 items-center gap-2", children: [_jsx("span", { className: MICRO, children: labelOf(field) }), _jsx("input", { className: `w-full min-w-0 ${INPUT}`, value: value, placeholder: "reroll\u2026", onChange: (event) => onMeta({ [field.key]: event.target.value }, coalesce) })] }), _jsx("button", { type: "button", className: BTN, title: "Reroll seed", onClick: () => onMeta({ [field.key]: `r${Math.abs(Math.round((value.length + 1) * 2654435761)).toString(36).slice(0, 6)}${value.length}` }, coalesce), children: "\u27F3" })] }));
-        }
-        case "weightedList": {
-            const list = params[field.key];
-            const set = (next) => onMeta({ [field.key]: next }, coalesce);
-            return (_jsxs("div", { className: "space-y-1", children: [_jsx("div", { className: MICRO, children: labelOf(field) }), list.map((entry, index) => (_jsxs("div", { className: "flex items-center gap-1", children: [_jsx("input", { className: `min-w-0 flex-1 ${INPUT}`, value: entry.item, placeholder: field.itemLabel ?? "id", onChange: (event) => set(list.map((e, i) => (i === index ? { ...e, item: event.target.value } : e))) }), _jsx("input", { type: "number", step: 1, min: 0, className: `w-14 ${INPUT}`, value: entry.weight, onChange: (event) => set(list.map((e, i) => (i === index ? { ...e, weight: Math.max(0, Number(event.target.value)) } : e))) }), _jsx("button", { type: "button", className: `${CONTROL} px-1.5 py-1 text-neutral-400 hover:bg-rose-500/20 hover:text-rose-200 disabled:opacity-40`, disabled: list.length <= 1, onClick: () => set(list.filter((_, i) => i !== index)), children: "\u00D7" })] }, index))), _jsx("button", { type: "button", className: `w-full ${BTN}`, onClick: () => set([...list, { item: "", weight: 1 }]), children: "+ row" })] }));
-        }
+        case "color":
+            return _jsx(ColorField, { field: field, value: params[field.key], coalesce: coalesce, onMeta: onMeta });
+        case "text":
+            return _jsx(TextField, { field: field, value: params[field.key], coalesce: coalesce, onMeta: onMeta });
+        case "seed":
+            return _jsx(SeedField, { field: field, value: params[field.key], coalesce: coalesce, onMeta: onMeta });
+        case "weightedList":
+            return _jsx(WeightedListField, { field: field, value: params[field.key], coalesce: coalesce, onMeta: onMeta });
         case "action":
             return null; // Action buttons are rendered by the group section, which owns the whole schema.
     }

package/dist/TerrainPanel.js

@@ -1,9 +1,10 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useState } from "react";
+import { 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 { SliderRow } from "./chromeFields.js";
+import { useStoreVersion } from "./useStoreSelector.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]`;
@@ -49,10 +50,8 @@ function PaintControls({ session, ui }) {
 }
 /** The terrain-tool panel: create/clear the heightfield and drive the sculpt/paint controls. */
 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]);
+    useStoreVersion(ui, session);
     const uiState = ui.getState();
     const document = session.getState().document;
     const hasTerrain = document.terrain !== undefined;

package/dist/TerrainReadout.js

@@ -115,9 +115,7 @@ export function TerrainReadout({ groundHeightAt, region, showContours, showSurfa
     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]);
+    planeRef.current.constant = -(guides.summary.mean ?? 0);
     useFrame((_, delta) => {
         accum.current += delta;
         if (accum.current < CURSOR_SAMPLE_INTERVAL)

package/dist/agent/AgentPanel.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useStoreVersion } from "../useStoreSelector.js";
 import { BORDER, CONTROL, FOCUS_RING, INPUT_CLS, MICRO_LABEL, PANEL_BG } from "../shell/theme.js";
 const BTN = `${CONTROL} px-2 py-1 text-[11px] disabled:opacity-40`;
 const INPUT = `px-2 py-1 ${INPUT_CLS}`;
@@ -44,17 +45,12 @@ export function AgentPanel({ api, onClose, embedded = false, }) {
     const [contextTick, setContextTick] = useState(0);
     const listRef = useRef(null);
     const endpoint = useMemo(() => buildEndpoint(url, apiKey), [url, apiKey]);
-    const context = useMemo(() => packAgentContext(api), [api, contextTick]);
-    useEffect(() => {
-        const unsubSession = api.getSession().subscribe(() => setContextTick((v) => v + 1));
-        const unsubMode = api.subscribeMode(() => setContextTick((v) => v + 1));
-        const unsubFocus = api.subscribeFocus(() => setContextTick((v) => v + 1));
-        return () => {
-            unsubSession();
-            unsubMode();
-            unsubFocus();
-        };
-    }, [api]);
+    // Coarse invalidation of the packed context: any session/mode/focus change (or a finished agent
+    // turn, via contextTick) rebuilds the memo.
+    const modeSource = useMemo(() => ({ subscribe: api.subscribeMode }), [api]);
+    const focusSource = useMemo(() => ({ subscribe: api.subscribeFocus }), [api]);
+    const contextVersion = useStoreVersion(api.getSession(), modeSource, focusSource);
+    const context = useMemo(() => packAgentContext(api), [api, contextTick, contextVersion]);
     useEffect(() => {
         const el = listRef.current;
         if (el !== null)

package/dist/camera/orbitFraming.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Pure aerial-framing math for the editor orbit camera. `camera_goto`/`camera_frame` used to only
+ * pan the orbit *target*, leaving distance and pitch wherever the artist last dragged them — so a
+ * `KeyF` frame could bury the camera inside terrain or a building and composing a clean district
+ * aerial took many guess-the-y-offset round-trips. These helpers turn an explicit
+ * distance + pitch (+ optional yaw / height) into a camera position, and derive a fit-to-region
+ * distance from document bounds so one call frames a whole district from above.
+ *
+ * Dependency-free and side-effect-free so it is trivially unit-testable and safe to import into the
+ * R3F camera driver.
+ */
+/** A world-space point the orbit camera looks at. */
+export interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+/** Axis-aligned bounds as produced by `editorDocumentBounds`. */
+export interface Bounds3 {
+    min: Vec3;
+    max: Vec3;
+}
+/** Inputs to {@link orbitCameraPosition}. */
+export interface OrbitFrameInput {
+    /** Point the camera orbits and looks at. */
+    target: Vec3;
+    /** Radial distance from target to camera, in world units. Clamped to a small positive minimum. */
+    distance: number;
+    /** Elevation above the horizon, degrees: 0 = level with the target, 90 = straight-down aerial. */
+    pitchDeg: number;
+    /** Azimuth around the target, degrees: 0 looks along +Z toward the target, increasing toward +X. */
+    yawDeg?: number;
+    /**
+     * Explicit camera height above the target (world units). When set it overrides the pitch-derived
+     * height, letting a caller pin a fixed altitude while pitch still sets the horizontal pull-back.
+     */
+    height?: number;
+}
+/** Clamp a pitch to the horizon..straight-down range the orbit rig can express. */
+export declare function clampPitchDeg(pitchDeg: number): number;
+/**
+ * Camera position for an orbit rig framing `target` at the given distance, pitch, and yaw. Pitch is
+ * measured up from the horizon (90° = directly overhead); `height`, when provided, replaces the
+ * pitch-derived vertical offset. Pure: same inputs always yield the same position.
+ */
+export declare function orbitCameraPosition(input: OrbitFrameInput): Vec3;
+/** Center point of axis-aligned bounds. */
+export declare function boundsCenter(bounds: Bounds3): Vec3;
+/** Options for {@link frameDistanceForBounds}. */
+export interface FrameDistanceOptions {
+    /** Vertical field of view of the camera, degrees. Default 50 (the shell's default perspective FOV). */
+    fovDeg?: number;
+    /** Extra breathing room around the region as a multiplier on its radius. Default 1.25. */
+    margin?: number;
+}
+/**
+ * Distance at which the camera fits the whole `bounds` region into its vertical FOV — the value
+ * `camera_frame` uses when a caller asks for an aerial but does not pin an explicit distance, so a
+ * district frames itself instead of burying the camera. Uses the region's XZ half-diagonal plus its
+ * vertical extent as the radius to cover.
+ */
+export declare function frameDistanceForBounds(bounds: Bounds3, options?: FrameDistanceOptions): number;

package/dist/camera/orbitFraming.js

@@ -0,0 +1,69 @@
+/**
+ * Pure aerial-framing math for the editor orbit camera. `camera_goto`/`camera_frame` used to only
+ * pan the orbit *target*, leaving distance and pitch wherever the artist last dragged them — so a
+ * `KeyF` frame could bury the camera inside terrain or a building and composing a clean district
+ * aerial took many guess-the-y-offset round-trips. These helpers turn an explicit
+ * distance + pitch (+ optional yaw / height) into a camera position, and derive a fit-to-region
+ * distance from document bounds so one call frames a whole district from above.
+ *
+ * Dependency-free and side-effect-free so it is trivially unit-testable and safe to import into the
+ * R3F camera driver.
+ */
+const DEG_TO_RAD = Math.PI / 180;
+/** Smallest distance we will place the camera at, so `distance: 0` never collapses onto the target. */
+const MIN_DISTANCE = 0.01;
+/** Clamp a pitch to the horizon..straight-down range the orbit rig can express. */
+export function clampPitchDeg(pitchDeg) {
+    if (!Number.isFinite(pitchDeg))
+        return 45;
+    return Math.max(0, Math.min(90, pitchDeg));
+}
+/**
+ * Camera position for an orbit rig framing `target` at the given distance, pitch, and yaw. Pitch is
+ * measured up from the horizon (90° = directly overhead); `height`, when provided, replaces the
+ * pitch-derived vertical offset. Pure: same inputs always yield the same position.
+ */
+export function orbitCameraPosition(input) {
+    const distance = Math.max(MIN_DISTANCE, Number.isFinite(input.distance) ? input.distance : MIN_DISTANCE);
+    const pitchRad = clampPitchDeg(input.pitchDeg) * DEG_TO_RAD;
+    const yawRad = (Number.isFinite(input.yawDeg) ? input.yawDeg : 0) * DEG_TO_RAD;
+    const horizontal = distance * Math.cos(pitchRad);
+    const vertical = distance * Math.sin(pitchRad);
+    const height = input.height !== undefined && Number.isFinite(input.height) ? input.height : vertical;
+    return {
+        x: input.target.x + horizontal * Math.sin(yawRad),
+        y: input.target.y + height,
+        z: input.target.z + horizontal * Math.cos(yawRad),
+    };
+}
+/** Center point of axis-aligned bounds. */
+export function boundsCenter(bounds) {
+    return {
+        x: (bounds.min.x + bounds.max.x) / 2,
+        y: (bounds.min.y + bounds.max.y) / 2,
+        z: (bounds.min.z + bounds.max.z) / 2,
+    };
+}
+/**
+ * Distance at which the camera fits the whole `bounds` region into its vertical FOV — the value
+ * `camera_frame` uses when a caller asks for an aerial but does not pin an explicit distance, so a
+ * district frames itself instead of burying the camera. Uses the region's XZ half-diagonal plus its
+ * vertical extent as the radius to cover.
+ */
+export function frameDistanceForBounds(bounds, options = {}) {
+    const fovDeg = clampFovDeg(options.fovDeg ?? 50);
+    const margin = options.margin !== undefined && Number.isFinite(options.margin) ? options.margin : 1.25;
+    const halfX = (bounds.max.x - bounds.min.x) / 2;
+    const halfZ = (bounds.max.z - bounds.min.z) / 2;
+    const halfY = (bounds.max.y - bounds.min.y) / 2;
+    const radius = Math.hypot(halfX, halfZ) + Math.max(0, halfY);
+    const halfFovRad = (fovDeg / 2) * DEG_TO_RAD;
+    const tan = Math.tan(halfFovRad);
+    const distance = tan > 1e-4 ? (radius * Math.max(0.1, margin)) / tan : radius;
+    return Math.max(MIN_DISTANCE, distance);
+}
+function clampFovDeg(fovDeg) {
+    if (!Number.isFinite(fovDeg))
+        return 50;
+    return Math.max(1, Math.min(179, fovDeg));
+}

package/dist/chromeFields.js

@@ -1,13 +1,18 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useDebouncedCommit } from "@jgengine/react/useDebouncedCommit";
 import { INPUT } from "./chromeStyles.js";
 export function NumberField({ label, value, onCommit, step = 1, }) {
-    return (_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: label }), _jsx("input", { type: "number", step: step, className: `w-32 ${INPUT}`, value: value, onChange: (event) => {
+    // Mirror locally + debounce the commit so a held spinner / paste doesn't storm scene regen (#1372).
+    const { value: local, onInput, flush } = useDebouncedCommit(value, onCommit);
+    return (_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: label }), _jsx("input", { type: "number", step: step, className: `w-32 ${INPUT}`, value: local, onChange: (event) => {
                     const next = Number(event.target.value);
                     if (!Number.isFinite(next))
                         return;
-                    onCommit(next);
-                } })] }));
+                    onInput(next);
+                }, onBlur: flush })] }));
 }
 export function SliderRow({ label, value, min, max, step, onChange, format, }) {
-    return (_jsxs("label", { className: "block space-y-1", children: [_jsxs("span", { className: "flex items-center justify-between", children: [_jsx("span", { className: "text-[9px] font-semibold uppercase tracking-wider text-neutral-500", children: label }), _jsx("span", { className: "text-cyan-200", children: format ? format(value) : value.toFixed(2) })] }), _jsx("input", { type: "range", min: min, max: max, step: step, value: value, onChange: (event) => onChange(Number(event.target.value)), className: "w-full accent-amber-400" })] }));
+    // The readout + thumb track the live local value; onChange is debounced and flushed on release (#1372).
+    const { value: local, onInput, flush } = useDebouncedCommit(value, onChange);
+    return (_jsxs("label", { className: "block space-y-1", children: [_jsxs("span", { className: "flex items-center justify-between", children: [_jsx("span", { className: "text-[9px] font-semibold uppercase tracking-wider text-neutral-500", children: label }), _jsx("span", { className: "text-cyan-200", children: format ? format(local) : local.toFixed(2) })] }), _jsx("input", { type: "range", min: min, max: max, step: step, value: local, onChange: (event) => onInput(Number(event.target.value)), onPointerUp: flush, onKeyUp: flush, onBlur: flush, className: "w-full accent-amber-400" })] }));
 }

package/dist/handlers/document.d.ts

@@ -1,3 +1,3 @@
 import type { HandlerTable } from "./context.js";
 /** Document, selection, camera, mode, asset placement, and status verbs. */
-export declare const documentHandlers: Pick<HandlerTable, "editor_status" | "set_mode" | "perf_report" | "list_layers" | "list_selection" | "get_marker" | "get_volume" | "set_transform" | "set_volume" | "set_path" | "set_marker" | "set_note" | "set_meta" | "apply_preset" | "select" | "clear_selection" | "camera_goto" | "camera_frame" | "scene_summary" | "export_document" | "import_document" | "dispatch" | "undo" | "redo" | "list_assets" | "place_asset" | "batch_set_properties" | "assign_material" | "set_object_flags">;
+export declare const documentHandlers: Pick<HandlerTable, "editor_status" | "set_mode" | "perf_report" | "list_layers" | "list_selection" | "get_marker" | "get_volume" | "set_transform" | "set_volume" | "set_path" | "add_path" | "add_marker" | "set_marker" | "set_note" | "set_meta" | "apply_preset" | "select" | "clear_selection" | "camera_goto" | "camera_frame" | "scene_summary" | "export_document" | "import_document" | "dispatch" | "undo" | "redo" | "list_assets" | "place_asset" | "batch_set_properties" | "assign_material" | "set_object_flags">;