@jgengine/editor 0.13.0 → 0.15.0-next.0

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.
     }
@@ -82,10 +108,15 @@ function GroupSection({ title, accent, fields, schema, meta, onMeta, defaultColl
  * seam owns the inspector. Replaces the hand-written per-kind field blocks (`ScatterFields`).
  * @internal — mounted by `EditorChrome`'s inspector; not a game-author entry point.
  */
-export function SchemaInspector({ schema, label, accent = "#34d399", note, meta, onMeta, }) {
+export function SchemaInspector({ schema, label, accent = "#34d399", note, meta, onMeta, hideKeys, }) {
     const groups = schema.groups ?? [];
     const grouped = new Set(groups.map((group) => group.id));
+    const hidden = hideKeys === undefined || hideKeys.length === 0 ? null : new Set(hideKeys);
+    const visible = hidden === null ? schema.fields : schema.fields.filter((field) => !hidden.has(field.key));
     // Fields with no group (or a group not declared in schema.groups) render first, headerless.
-    const ungrouped = schema.fields.filter((field) => field.group === undefined || !grouped.has(field.group));
-    return (_jsxs("div", { className: "space-y-2 rounded-lg border p-2.5", style: { borderColor: `${accent}26`, backgroundColor: `${accent}10` }, children: [_jsx("div", { className: "text-[9px] font-semibold uppercase tracking-[0.14em]", style: { color: accent }, children: label }), _jsx(PresetRow, { schema: schema, onMeta: onMeta }), ungrouped.map((field) => field.type === "action" ? (_jsx(ActionButton, { field: field, schema: schema, onMeta: onMeta }, field.key)) : (_jsx(FieldRow, { field: field, meta: meta, onMeta: onMeta }, field.key))), groups.map((group) => (_jsx(GroupSection, { title: group.label, accent: accent, fields: schema.fields.filter((field) => field.group === group.id), schema: schema, meta: meta, onMeta: onMeta, defaultCollapsed: group.collapsed ?? false }, group.id))), note !== undefined && note.length > 0 ? _jsx("div", { className: "text-[10px] text-neutral-500", children: note }) : null] }));
+    const ungrouped = visible.filter((field) => field.group === undefined || !grouped.has(field.group));
+    return (_jsxs("div", { className: "space-y-2 rounded-lg border p-2.5", style: { borderColor: `${accent}26`, backgroundColor: `${accent}10` }, children: [_jsx("div", { className: "text-[9px] font-semibold uppercase tracking-[0.14em]", style: { color: accent }, children: label }), _jsx(PresetRow, { schema: schema, onMeta: onMeta }), ungrouped.map((field) => field.type === "action" ? (_jsx(ActionButton, { field: field, schema: schema, onMeta: onMeta }, field.key)) : (_jsx(FieldRow, { field: field, meta: meta, onMeta: onMeta }, field.key))), groups
+                .map((group) => ({ group, fields: visible.filter((field) => field.group === group.id) }))
+                .filter((entry) => entry.fields.length > 0)
+                .map(({ group, fields }) => (_jsx(GroupSection, { title: group.label, accent: accent, fields: fields, schema: schema, meta: meta, onMeta: onMeta, defaultCollapsed: group.collapsed ?? false }, group.id))), note !== undefined && note.length > 0 ? _jsx("div", { className: "text-[10px] text-neutral-500", children: note }) : null] }));
 }

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">;

package/dist/handlers/document.js

@@ -2,6 +2,20 @@ import { editorDocumentBounds, listEditorKinds, summarizeEditorSession, } from "
 import { resolvePlaceAsset, toEditorMarker } from "@jgengine/core/world/placeAsset";
 import { findSchemaPreset, getSceneKind, validateParams } from "@jgengine/core/scene/sceneKinds";
 import { EDITOR_RUN_MODES } from "../session.js";
+import { boundsCenter, frameDistanceForBounds } from "../camera/orbitFraming.js";
+/** Collect the finite placement fields present on a camera request into a focus-target patch. */
+function cameraPlacement(request) {
+    const placement = {};
+    if (typeof request.distance === "number" && Number.isFinite(request.distance))
+        placement.distance = request.distance;
+    if (typeof request.pitch === "number" && Number.isFinite(request.pitch))
+        placement.pitch = request.pitch;
+    if (typeof request.yaw === "number" && Number.isFinite(request.yaw))
+        placement.yaw = request.yaw;
+    if (typeof request.height === "number" && Number.isFinite(request.height))
+        placement.height = request.height;
+    return placement;
+}
 /** True when any of `ids` names a placeable object (marker/volume/path/note) in the document — used
  * to reject batch mutations that would match nothing, so the caller hears an honest `ok:false`. */
 function documentHasAnyId(doc, ids) {
@@ -134,6 +148,49 @@ export const documentHandlers = {
         });
         return { ok: true, result: ctx.session.getState().document.paths.find((p) => p.id === request.id) };
     },
+    add_path: (ctx, request) => {
+        if (request.points.length < 2)
+            return { ok: false, error: "add_path needs at least 2 points" };
+        const kind = request.kind ?? "route";
+        const invalid = validateMetaForKind(kind, request.meta);
+        if (invalid !== null)
+            return { ok: false, error: invalid };
+        const path = {
+            id: request.id,
+            kind,
+            points: request.points.map((point) => ({ x: point.x, y: point.y ?? 0, z: point.z })),
+            ...(request.width === undefined ? {} : { width: request.width }),
+            ...(request.color === undefined ? {} : { color: request.color }),
+            ...(request.label === undefined ? {} : { label: request.label }),
+            ...(request.meta === undefined ? {} : { meta: request.meta }),
+        };
+        // addPath re-ids on a document-global collision, so read the created id back from the selection.
+        const { applied, state } = ctx.dispatchGuarded({ type: "addPath", path });
+        if (!applied)
+            return { ok: false, error: "add_path rejected: no effect" };
+        const createdId = state.selection[0] ?? request.id;
+        return { ok: true, result: state.document.paths.find((p) => p.id === createdId) };
+    },
+    add_marker: (ctx, request) => {
+        const invalid = validateMetaForKind(request.kind, request.meta);
+        if (invalid !== null)
+            return { ok: false, error: invalid };
+        const marker = {
+            id: request.id,
+            kind: request.kind,
+            position: { x: request.x, y: request.y ?? 0, z: request.z },
+            ...(request.rotationY === undefined ? {} : { rotationY: request.rotationY }),
+            ...(request.color === undefined ? {} : { color: request.color }),
+            ...(request.label === undefined ? {} : { label: request.label }),
+            ...(request.meta === undefined ? {} : { meta: request.meta }),
+        };
+        // addMarker re-ids on a document-global collision, so read the created id back from the selection.
+        const { applied, state } = ctx.dispatchGuarded({ type: "addMarker", marker });
+        if (!applied)
+            return { ok: false, error: "add_marker rejected: no effect" };
+        const createdId = state.selection[0] ?? request.id;
+        return { ok: true, result: state.document.markers.find((m) => m.id === createdId) };
+    },
     set_marker: (ctx, request) => {
         const marker = ctx.session.getState().document.markers.find((m) => m.id === request.id);
         if (marker === undefined)
@@ -218,6 +275,7 @@ export const documentHandlers = {
         return { ok: true, result: { selection: [] } };
     },
     camera_goto: (ctx, request) => {
+        const placement = cameraPlacement(request);
         if (request.id !== undefined) {
             const state = ctx.session.getState();
             const marker = state.document.markers.find((m) => m.id === request.id);
@@ -225,26 +283,32 @@ export const documentHandlers = {
             const point = marker?.position ?? volume?.center;
             if (point === undefined)
                 return { ok: false, error: `id not found: ${request.id}` };
-            ctx.api.setFocusTarget({ ...point });
+            const target = { x: point.x, y: point.y, z: point.z, ...placement };
+            ctx.api.setFocusTarget(target);
             ctx.session.dispatch({ type: "select", ids: [request.id] });
-            return { ok: true, result: { target: point } };
+            return { ok: true, result: { target } };
         }
         if (request.x === undefined || request.z === undefined) {
             return { ok: false, error: "camera_goto requires id or x/z" };
         }
-        const target = { x: request.x, y: request.y ?? 0, z: request.z };
+        const target = { x: request.x, y: request.y ?? 0, z: request.z, ...placement };
         ctx.api.setFocusTarget(target);
         return { ok: true, result: { target } };
     },
-    camera_frame: (ctx) => {
+    camera_frame: (ctx, request) => {
         const bounds = editorDocumentBounds(ctx.session.getState().document);
         if (bounds === null)
             return { ok: false, error: "document is empty" };
-        const target = {
-            x: (bounds.min.x + bounds.max.x) / 2,
-            y: (bounds.min.y + bounds.max.y) / 2,
-            z: (bounds.min.z + bounds.max.z) / 2,
-        };
+        const center = boundsCenter(bounds);
+        const placement = cameraPlacement(request);
+        // An aerial is requested when the caller supplies any camera placement. Fit the region into the
+        // camera's FOV when no explicit distance is given, so one call frames a whole district from
+        // above instead of burying the camera at the last-used distance.
+        const wantsAerial = Object.keys(placement).length > 0;
+        const resolved = wantsAerial && placement.distance === undefined
+            ? { ...placement, distance: frameDistanceForBounds(bounds, { fovDeg: 50 }) }
+            : placement;
+        const target = { ...center, ...resolved };
         ctx.api.setFocusTarget(target);
         return { ok: true, result: { target, bounds } };
     },
@@ -259,6 +323,11 @@ export const documentHandlers = {
     }),
     export_document: (ctx) => ({ ok: true, result: { json: ctx.session.exportJson(true) } }),
     import_document: (ctx, request) => {
+        // Name the expected param instead of letting a missing/mis-keyed value fall into JSON.parse as
+        // the literal string "undefined" and surface a cryptic "JSON Parse error: Unexpected identifier".
+        if (typeof request.json !== "string") {
+            return { ok: false, error: "import_document requires a `json` param — the document JSON text (as export_document returns in result.json)" };
+        }
         ctx.session.dispatch({ type: "importJson", json: request.json });
         return { ok: true, result: summarizeEditorSession(ctx.session.getState()) };
     },

package/dist/mcp/fieldSpec.js

@@ -44,14 +44,16 @@ export const RPC_FIELD_SCHEMAS = {
     set_transform: [req(s("id")), n("x"), n("y"), n("z"), n("rotationY")],
     set_volume: [req(s("id")), n("radius"), n("height"), n("x"), n("y"), n("z")],
     set_path: [req(s("id")), s("kind"), n("width"), s("color"), s("label"), o("meta")],
+    add_path: [req(s("id")), req(oa("points", [req(n("x")), n("y"), req(n("z"))])), s("kind"), n("width"), s("color"), s("label"), o("meta")],
+    add_marker: [req(s("id")), req(s("kind")), req(n("x")), n("y"), req(n("z")), s("color"), s("label"), n("rotationY"), o("meta")],
     set_marker: [req(s("id")), s("kind"), s("color"), s("label"), n("rotationY"), o("meta")],
     set_note: [req(s("id")), s("text"), o("meta")],
     set_meta: [req(s("id")), req(o("patch"))],
     apply_preset: [req(s("id")), req(s("preset"))],
     select: [req(sa("ids"))],
     clear_selection: [],
-    camera_goto: [s("id"), n("x"), n("y"), n("z")],
-    camera_frame: [],
+    camera_goto: [s("id"), n("x"), n("y"), n("z"), n("distance"), n("pitch"), n("yaw"), n("height")],
+    camera_frame: [n("distance"), n("pitch"), n("yaw"), n("height")],
     scene_summary: [],
     export_document: [],
     import_document: [req(s("json"))],

package/dist/mcp/tools.js

@@ -22,13 +22,15 @@ const TOOL_DESCRIPTIONS = [
     { name: "set_transform", description: "Move a marker or volume center by id." },
     { name: "set_volume", description: "Patch a volume radius/height/center." },
     { name: "set_path", description: "Patch a path's kind/width/color/label and merge-patch its meta (studio sliders: scatter density, pole spacing, …). Validated against the kind schema." },
+    { name: "add_path", description: "Author a new path/route into the scene document from an ordered list of ≥2 {x,z} (optional y) points — the headless one-shot for placing a route without an export/import roundtrip. kind defaults to `route`; width/color/label/meta are optional and meta is validated against the kind schema. Re-ids on a document-global id collision." },
+    { name: "add_marker", description: "Author a new point marker into the scene document at x/z (optional y) — the headless one-shot for placing a logical marker (spawn, checkpoint, pickup, bounty, or a game's own custom kind) without an export/import roundtrip. kind is required; color/label/rotationY/meta are optional and meta is validated against the kind schema when registered. Re-ids on a document-global id collision." },
     { name: "set_marker", description: "Patch a marker's kind/color/label/rotationY and merge-patch its meta. Validated against the kind schema when registered." },
     { name: "set_note", description: "Patch a note's text and merge-patch its meta." },
     { name: "set_meta", description: "Merge-patch the meta bag of any document object (marker/volume/path/note) by id — the generic studio-slider primitive. Rejected if it violates the kind's param schema." },
     { name: "apply_preset", description: "Apply a named preset bundle from the object's kind schema (e.g. a city archetype like manhattan/ruralohio) as one meta patch, ready to tweak afterwards." },
     { name: "select", description: "Select editor object ids." },
-    { name: "camera_goto", description: "Focus the editor camera on an id or world x/z." },
-    { name: "camera_frame", description: "Frame the whole editor document." },
+    { name: "camera_goto", description: "Focus the editor camera on an id or world x/z. Optional distance/pitch/yaw/height reposition the orbit camera (pitch is degrees above the horizon; 90 = straight-down aerial) so an aerial composes in one call." },
+    { name: "camera_frame", description: "Frame the whole editor document. Optional distance/pitch/yaw/height compose an aerial; when pitch is set without distance the region is auto-fit into view so the camera never buries in terrain." },
     { name: "scene_summary", description: "Compact summary of the editor document and bounds." },
     { name: "export_document", description: "Export the editor document as JSON text." },
     { name: "import_document", description: "Replace the session document from JSON text." },