@jgengine/editor 0.14.0 → 0.15.0

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." },

package/dist/session.d.ts

@@ -82,6 +82,30 @@ export type EditorBridgeRequest = {
     color?: string;
     label?: string;
     meta?: Record<string, unknown>;
+} | {
+    method: "add_path";
+    id: string;
+    points: {
+        x: number;
+        y?: number;
+        z: number;
+    }[];
+    kind?: string;
+    width?: number;
+    color?: string;
+    label?: string;
+    meta?: Record<string, unknown>;
+} | {
+    method: "add_marker";
+    id: string;
+    kind: string;
+    x: number;
+    y?: number;
+    z: number;
+    color?: string;
+    label?: string;
+    rotationY?: number;
+    meta?: Record<string, unknown>;
 } | {
     method: "set_marker";
     id: string;
@@ -114,8 +138,16 @@ export type EditorBridgeRequest = {
     x?: number;
     y?: number;
     z?: number;
+    distance?: number;
+    pitch?: number;
+    yaw?: number;
+    height?: number;
 } | {
     method: "camera_frame";
+    distance?: number;
+    pitch?: number;
+    yaw?: number;
+    height?: number;
 } | {
     method: "scene_summary";
 } | {
@@ -499,6 +531,25 @@ export interface EditorPerfSample {
         avgMs: number;
     }[];
 }
+/**
+ * Where the editor orbit camera looks, plus optional placement so a single `camera_goto`/
+ * `camera_frame` can compose an aerial. `x/y/z` is the orbit target (pan-only when that is all that
+ * is set — the historical behavior); `distance`, `pitch` (degrees above the horizon), `yaw`
+ * (degrees), and `height` reposition the camera around that target when provided.
+ */
+export interface EditorFocusTarget {
+    x: number;
+    y: number;
+    z: number;
+    /** Radial distance from the target to the camera, world units. */
+    distance?: number;
+    /** Elevation above the horizon, degrees (90 = straight-down aerial). */
+    pitch?: number;
+    /** Azimuth around the target, degrees. */
+    yaw?: number;
+    /** Explicit camera height above the target; overrides the pitch-derived height. */
+    height?: number;
+}
 /** The live editor's global control surface — session, visibility, camera focus, assets, mode, RPC. */
 export interface EditorHostApi {
     gameId: string;
@@ -508,21 +559,9 @@ export interface EditorHostApi {
     getVisibility(): EditorKindVisibility;
     setVisibility(next: EditorKindVisibility): void;
     subscribeVisibility(listener: () => void): () => void;
-    getFocusTarget(): {
-        x: number;
-        y: number;
-        z: number;
-    } | null;
-    setFocusTarget(target: {
-        x: number;
-        y: number;
-        z: number;
-    } | null): void;
-    subscribeFocus(listener: (target: {
-        x: number;
-        y: number;
-        z: number;
-    } | null) => void): () => void;
+    getFocusTarget(): EditorFocusTarget | null;
+    setFocusTarget(target: EditorFocusTarget | null): void;
+    subscribeFocus(listener: (target: EditorFocusTarget | null) => void): () => void;
     getAssets(): readonly EditorAssetInfo[];
     setAssets(assets: readonly EditorAssetInfo[]): void;
     getCatalogDefinitions(): readonly EditorCatalogDefinition[];

package/dist/shell/AnimationPanel.js

@@ -26,11 +26,8 @@ export function AnimationPanel({ session, api, ui, assets, }) {
     // Default to clips only when the scene has rigged assets but no scrubbable path yet.
     const paths = useStoreSelector(session, (state) => state.document.paths);
     const [mode, setMode] = useState(() => rigged.length > 0 && listScrubbablePaths(paths).length === 0 ? "clips" : "path");
-    // Tear down the viewport preview whenever the panel leaves clip mode or unmounts.
-    useEffect(() => {
-        if (mode !== "clips" && ui.getState().clipPreview !== null)
-            ui.patch({ clipPreview: null });
-    }, [mode, ui]);
+    // Tear down the viewport preview when the panel unmounts; leaving clip mode tears down in the
+    // tab click below.
     useEffect(() => () => {
         if (ui.getState().clipPreview !== null)
             ui.patch({ clipPreview: null });
@@ -38,7 +35,11 @@ export function AnimationPanel({ session, api, ui, assets, }) {
     return (_jsxs("div", { className: "flex min-h-0 flex-1 flex-col", children: [_jsx("div", { className: "flex h-8 shrink-0 items-center gap-1.5 border-b border-white/[0.06] px-2", children: _jsx("div", { className: "flex items-center gap-0.5", role: "tablist", "aria-label": "Animation mode", children: [
                         ["path", "Path flythrough"],
                         ["clips", "Clip preview"],
-                    ].map(([id, label]) => (_jsx("button", { type: "button", role: "tab", "aria-selected": mode === id, className: `rounded-[5px] px-2 py-0.5 text-[10px] uppercase tracking-wider transition-colors ${FOCUS_RING} ${mode === id ? "bg-cyan-500/15 text-cyan-200" : "text-neutral-500 hover:text-neutral-300"}`, onClick: () => setMode(id), children: label }, id))) }) }), mode === "path" ? (_jsx(PathFlythrough, { session: session, api: api })) : (_jsx(ClipPreview, { session: session, ui: ui, rigged: rigged }))] }));
+                    ].map(([id, label]) => (_jsx("button", { type: "button", role: "tab", "aria-selected": mode === id, className: `rounded-[5px] px-2 py-0.5 text-[10px] uppercase tracking-wider transition-colors ${FOCUS_RING} ${mode === id ? "bg-cyan-500/15 text-cyan-200" : "text-neutral-500 hover:text-neutral-300"}`, onClick: () => {
+                            if (id !== "clips" && ui.getState().clipPreview !== null)
+                                ui.patch({ clipPreview: null });
+                            setMode(id);
+                        }, children: label }, id))) }) }), mode === "path" ? (_jsx(PathFlythrough, { session: session, api: api })) : (_jsx(ClipPreview, { session: session, ui: ui, rigged: rigged }))] }));
 }
 /** Clip-preview mode: pick a rigged asset (placed instance or catalog) and play its clips in the viewport. */
 function ClipPreview({ session, ui, rigged, }) {
@@ -125,22 +126,15 @@ function PathFlythrough({ session, api }) {
     const [playing, setPlaying] = useState(false);
     const [loop, setLoop] = useState(true);
     const playRef = useRef({ playing: false, loop: true, progress: 0, pathId: null });
+    // selectedId is raw intent; a removed path falls back to the first scrubbable one at read time.
     const selected = scrubbable.find((entry) => entry.id === selectedId) ?? scrubbable[0] ?? null;
     const selectedPath = selected === null ? undefined : paths.find((path) => path.id === selected.id);
-    useEffect(() => {
-        if (selected !== null && selectedId !== selected.id)
-            setSelectedId(selected.id);
-        if (selected === null && selectedId !== null)
-            setSelectedId(null);
-    }, [selected, selectedId]);
-    useEffect(() => {
-        playRef.current = {
-            playing,
-            loop,
-            progress,
-            pathId: selected?.id ?? null,
-        };
-    }, [playing, loop, progress, selected?.id]);
+    playRef.current = {
+        playing,
+        loop,
+        progress,
+        pathId: selected?.id ?? null,
+    };
     const applyProgress = useCallback((next, pathId) => {
         const path = session.getState().document.paths.find((entry) => entry.id === pathId);
         if (path === undefined)

package/dist/shell/CommandPalette.js

@@ -13,13 +13,9 @@ export function CommandPalette({ commands, onClose, initialQuery = "", }) {
     const [query, setQuery] = useState(initialQuery);
     const [cursor, setCursor] = useState(0);
     const [recentIds, setRecentIds] = useState(() => loadRecentCommandIds());
-    const inputRef = useRef(null);
     const listRef = useRef(null);
     const filtered = useMemo(() => filterPaletteCommands(commands, query, recentIds).slice(0, 40), [commands, query, recentIds]);
     const clampedCursor = Math.min(cursor, Math.max(0, filtered.length - 1));
-    useEffect(() => {
-        inputRef.current?.focus();
-    }, []);
     useEffect(() => {
         const row = listRef.current?.children[clampedCursor];
         if (row instanceof HTMLElement)
@@ -32,7 +28,7 @@ export function CommandPalette({ commands, onClose, initialQuery = "", }) {
         onClose();
         command.run();
     };
-    return (_jsx("div", { className: "pointer-events-auto absolute inset-0 z-[70] flex items-start justify-center bg-black/50 pt-[12vh] backdrop-blur-[2px]", onClick: onClose, children: _jsxs("div", { role: "dialog", "aria-label": "Command palette", className: "w-[520px] max-w-[92vw] overflow-hidden rounded-[8px] border border-white/10 bg-[#14171d] shadow-2xl shadow-black/60", onClick: (event) => event.stopPropagation(), children: [_jsxs("div", { className: "flex items-center gap-2 border-b border-white/[0.07] px-3", children: [_jsx(Icon, { name: "search", size: 14, className: "shrink-0 text-neutral-500" }), _jsx("input", { ref: inputRef, value: query, onChange: (event) => {
+    return (_jsx("div", { className: "pointer-events-auto absolute inset-0 z-[70] flex items-start justify-center bg-black/50 pt-[12vh] backdrop-blur-[2px]", onClick: onClose, children: _jsxs("div", { role: "dialog", "aria-label": "Command palette", className: "w-[520px] max-w-[92vw] overflow-hidden rounded-[8px] border border-white/10 bg-[#14171d] shadow-2xl shadow-black/60", onClick: (event) => event.stopPropagation(), children: [_jsxs("div", { className: "flex items-center gap-2 border-b border-white/[0.07] px-3", children: [_jsx(Icon, { name: "search", size: 14, className: "shrink-0 text-neutral-500" }), _jsx("input", { autoFocus: true, value: query, onChange: (event) => {
                                 setQuery(event.target.value);
                                 setCursor(0);
                             }, onKeyDown: (event) => {

package/dist/shell/HierarchyPanel.js

@@ -44,10 +44,8 @@ export const HierarchyPanel = memo(function HierarchyPanel({ session, api, onAdd
     const [query, setQuery] = useState("");
     const [collapsedKinds, setCollapsedKinds] = useState({});
     const [collapsedNodes, setCollapsedNodes] = useState({});
-    const [visibilityTick, setVisibilityTick] = useState(0);
-    useEffect(() => api.subscribeVisibility(() => setVisibilityTick((value) => value + 1)), [api]);
-    void visibilityTick;
-    const visibility = api.getVisibility();
+    const visibilityStore = useMemo(() => ({ getState: api.getVisibility, subscribe: api.subscribeVisibility }), [api]);
+    const visibility = useStoreSelector(visibilityStore, (v) => v);
     const rows = useMemo(() => flattenOutliner(document, { view, query, collapsedKinds, collapsedNodes }), [document, view, query, collapsedKinds, collapsedNodes]);
     const total = document.markers.length + document.volumes.length + document.paths.length + document.annotations.length;
     const scrollRef = useRef(null);
@@ -79,15 +77,8 @@ export const HierarchyPanel = memo(function HierarchyPanel({ session, api, onAdd
     const [activeId, setActiveId] = useState(null);
     const [renamingId, setRenamingId] = useState(null);
     const [renameDraft, setRenameDraft] = useState("");
-    const renameInputRef = useRef(null);
-    useEffect(() => {
-        if (activeId !== null && !navigableIds.includes(activeId))
-            setActiveId(navigableIds[0] ?? null);
-    }, [activeId, navigableIds]);
-    useEffect(() => {
-        if (renamingId !== null)
-            renameInputRef.current?.focus();
-    }, [renamingId]);
+    // Raw intent clamped at read time: a filtered-away active row falls back to the first row.
+    const effectiveActiveId = activeId === null ? null : navigableIds.includes(activeId) ? activeId : (navigableIds[0] ?? null);
     const focusTree = () => {
         scrollRef.current?.focus({ preventScroll: true });
     };
@@ -129,7 +120,7 @@ export const HierarchyPanel = memo(function HierarchyPanel({ session, api, onAdd
     const onListFocus = () => {
         if (renamingId !== null)
             return;
-        if (activeId !== null && navigableIds.includes(activeId))
+        if (effectiveActiveId !== null)
             return;
         const seed = selectedId !== undefined && navigableIds.includes(selectedId)
             ? selectedId
@@ -142,7 +133,7 @@ export const HierarchyPanel = memo(function HierarchyPanel({ session, api, onAdd
             return;
         if (navigableIds.length === 0)
             return;
-        const currentIndex = activeId === null ? -1 : navigableIds.indexOf(activeId);
+        const currentIndex = effectiveActiveId === null ? -1 : navigableIds.indexOf(effectiveActiveId);
         if (event.key === "ArrowDown" || event.key === "ArrowUp") {
             event.preventDefault();
             const delta = event.key === "ArrowDown" ? 1 : -1;
@@ -164,17 +155,17 @@ export const HierarchyPanel = memo(function HierarchyPanel({ session, api, onAdd
             activateId(navigableIds[navigableIds.length - 1], event.shiftKey);
             return;
         }
-        if (event.key === "Enter" && activeId !== null) {
+        if (event.key === "Enter" && effectiveActiveId !== null) {
             event.preventDefault();
-            api.handle({ method: "camera_goto", id: activeId });
+            api.handle({ method: "camera_goto", id: effectiveActiveId });
             return;
         }
-        if (event.key === "F2" && activeId !== null) {
+        if (event.key === "F2" && effectiveActiveId !== null) {
             event.preventDefault();
-            const row = rows.find((entry) => (entry.type === "kindItem" && entry.ids[0] === activeId) ||
-                (entry.type === "treeItem" && entry.id === activeId));
+            const row = rows.find((entry) => (entry.type === "kindItem" && entry.ids[0] === effectiveActiveId) ||
+                (entry.type === "treeItem" && entry.id === effectiveActiveId));
             if (row !== undefined && (row.type === "kindItem" || row.type === "treeItem")) {
-                beginRename(activeId, row.label);
+                beginRename(effectiveActiveId, row.label);
             }
         }
     };
@@ -245,7 +236,7 @@ export const HierarchyPanel = memo(function HierarchyPanel({ session, api, onAdd
             return;
         session.dispatch({ type: "setObjectFlags", ids: [...ids], patch: { locked: true } });
     };
-    const activeDescendant = hierarchyActiveDescendantId(activeId, navigableIds);
+    const activeDescendant = hierarchyActiveDescendantId(effectiveActiveId, navigableIds);
     return (_jsxs(_Fragment, { children: [_jsxs("div", { className: "space-y-1.5 border-b border-white/[0.06] p-2", children: [_jsxs("div", { className: "flex items-center gap-1.5", children: [_jsxs("div", { className: "relative min-w-0 flex-1", children: [_jsx(Icon, { name: "search", size: 12, className: "pointer-events-none absolute left-2 top-1/2 -translate-y-1/2 text-neutral-600" }), _jsx("input", { type: "search", value: query, onChange: (event) => setQuery(event.target.value), placeholder: "Search\u2026", "aria-label": "Search scene objects", className: `h-7 w-full pl-7 pr-2 ${INPUT_CLS}` })] }), _jsx(IconButton, { icon: "plus", label: "Add object\u2026", onClick: onAdd })] }), _jsxs("div", { className: "flex items-center gap-1.5", children: [_jsx(Segmented, { ariaLabel: "Outliner grouping", value: view, onChange: setView, options: [
                                     { value: "kind", label: "By kind", icon: "layers" },
                                     { value: "tree", label: "Tree", icon: "folder" },
@@ -273,7 +264,7 @@ export const HierarchyPanel = memo(function HierarchyPanel({ session, api, onAdd
                                 const hidden = rowHidden(row.ids);
                                 const collectionOnlyLock = locked &&
                                     row.ids.every((id) => isEditorObjectCollectionLocked(document, id) && !isEditorObjectSelfLocked(document, id));
-                                const active = activeId === primaryId;
+                                const active = effectiveActiveId === primaryId;
                                 const renaming = renamingId === primaryId && row.ids.length === 1;
                                 return (_jsxs("div", { id: hierarchyRowDomId(primaryId), role: "treeitem", "aria-selected": rowSelected, "aria-level": 2, style: { height: ROW_HEIGHT }, className: `group flex w-full items-center gap-0.5 rounded-[5px] pl-6 pr-0.5 text-[11px] transition-colors ${dropActive
                                         ? "bg-cyan-500/25 ring-1 ring-inset ring-cyan-300/50"
@@ -294,7 +285,7 @@ export const HierarchyPanel = memo(function HierarchyPanel({ session, api, onAdd
                                                 event.preventDefault();
                                                 setActiveId(primaryId);
                                                 onRowContextMenu?.({ clientX: event.clientX, clientY: event.clientY }, primaryId);
-                                            }, children: [_jsx(Icon, { name: kindIcon(row.kind), size: 13, className: `shrink-0 ${rowSelected || active ? "text-cyan-300" : "text-neutral-500"}` }), renaming ? (_jsx("input", { ref: renameInputRef, value: renameDraft, onChange: (event) => setRenameDraft(event.target.value), onBlur: commitRename, onKeyDown: (event) => {
+                                            }, children: [_jsx(Icon, { name: kindIcon(row.kind), size: 13, className: `shrink-0 ${rowSelected || active ? "text-cyan-300" : "text-neutral-500"}` }), renaming ? (_jsx("input", { autoFocus: true, value: renameDraft, onChange: (event) => setRenameDraft(event.target.value), onBlur: commitRename, onKeyDown: (event) => {
                                                         event.stopPropagation();
                                                         if (event.key === "Enter") {
                                                             event.preventDefault();
@@ -331,7 +322,7 @@ export const HierarchyPanel = memo(function HierarchyPanel({ session, api, onAdd
                             const hidden = isEditorObjectHidden(document, row.id);
                             const collectionOnlyLock = isEditorObjectCollectionLocked(document, row.id) && !isEditorObjectSelfLocked(document, row.id);
                             const dragging = draggingObjectId === row.id;
-                            const active = activeId === row.id;
+                            const active = effectiveActiveId === row.id;
                             const renaming = renamingId === row.id;
                             const expanded = row.hasChildren ? collapsedNodes[row.id] !== true : undefined;
                             return (_jsxs("div", { id: hierarchyRowDomId(row.id), role: "treeitem", "aria-selected": rowSelected, "aria-level": row.depth + 1, "aria-expanded": expanded, style: { height: ROW_HEIGHT, paddingLeft: `${row.depth * 12}px` }, className: `group flex items-center ${hidden ? "opacity-55" : ""}`, children: [row.hasChildren ? (_jsx("button", { type: "button", tabIndex: -1, "aria-label": collapsedNodes[row.id] === true ? "Expand children" : "Collapse children", className: `flex h-4 w-4 shrink-0 items-center justify-center text-neutral-500 transition-colors hover:text-neutral-200 ${FOCUS_RING}`, onMouseDown: preventFocusSteal, onClick: () => setCollapsedNodes((previous) => ({ ...previous, [row.id]: !(previous[row.id] === true) })), children: _jsx(Icon, { name: collapsedNodes[row.id] === true ? "chevronRight" : "chevronDown", size: 10 }) })) : (_jsx("span", { className: "w-4 shrink-0", "aria-hidden": "true" })), _jsxs("button", { type: "button", tabIndex: -1, draggable: true, className: `flex h-full min-w-0 flex-1 items-center gap-1.5 truncate rounded-[5px] px-1.5 text-left text-[11px] transition-colors ${FOCUS_RING} ${materialDrop || reparentDrop
@@ -364,7 +355,7 @@ export const HierarchyPanel = memo(function HierarchyPanel({ session, api, onAdd
                                             if (commitMaterialDrop(event, [row.id]))
                                                 return;
                                             commitReparentDrop(event, row.id);
-                                        }, children: [_jsx(Icon, { name: kindIcon(row.kind), size: 13, className: `shrink-0 ${rowSelected || active ? "text-cyan-300" : "text-neutral-500"}` }), renaming ? (_jsx("input", { ref: renameInputRef, value: renameDraft, onChange: (event) => setRenameDraft(event.target.value), onBlur: commitRename, onKeyDown: (event) => {
+                                        }, children: [_jsx(Icon, { name: kindIcon(row.kind), size: 13, className: `shrink-0 ${rowSelected || active ? "text-cyan-300" : "text-neutral-500"}` }), renaming ? (_jsx("input", { autoFocus: true, value: renameDraft, onChange: (event) => setRenameDraft(event.target.value), onBlur: commitRename, onKeyDown: (event) => {
                                                     event.stopPropagation();
                                                     if (event.key === "Enter") {
                                                         event.preventDefault();

package/dist/shell/PlayModeBar.d.ts

@@ -1,4 +1,11 @@
+import type { RuntimePlayControl } from "@jgengine/core/editor/index";
 import type { EditorHostApi } from "../session.js";
+/**
+ * Subscribe to the host runtime play-control (pause / pending steps) as an external store.
+ * Shared by the play-mode chrome pieces so none of them hand-rolls a `setState` mirror.
+ * @internal
+ */
+export declare function usePlayControl(api: EditorHostApi): RuntimePlayControl;
 /**
  * Slim shell chrome for Play mode — same app-bar language as edit mode so switching modes
  * does not feel like an app swap. Pause / Resume / Step drive the existing runtime play

package/dist/shell/PlayModeBar.js

@@ -1,8 +1,18 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useState } from "react";
+import { useMemo } from "react";
+import { useStoreSelector } from "../useStoreSelector.js";
 import { Icon } from "./icons.js";
 import { BORDER, FOCUS_RING } from "./theme.js";
 import { IconButton, ToolbarDivider } from "./ui.js";
+/**
+ * Subscribe to the host runtime play-control (pause / pending steps) as an external store.
+ * Shared by the play-mode chrome pieces so none of them hand-rolls a `setState` mirror.
+ * @internal
+ */
+export function usePlayControl(api) {
+    const store = useMemo(() => ({ getState: api.getPlayControl, subscribe: api.subscribePlayControl }), [api]);
+    return useStoreSelector(store, (play) => play);
+}
 /**
  * Slim shell chrome for Play mode — same app-bar language as edit mode so switching modes
  * does not feel like an app swap. Pause / Resume / Step drive the existing runtime play
@@ -10,8 +20,7 @@ import { IconButton, ToolbarDivider } from "./ui.js";
  * @internal
  */
 export function PlayModeBar({ gameId, api, onExit, }) {
-    const [play, setPlay] = useState(() => api.getPlayControl());
-    useEffect(() => api.subscribePlayControl(setPlay), [api]);
+    const play = usePlayControl(api);
     const pause = () => {
         api.handle({ method: "runtime_pause" });
     };

package/dist/shell/SceneToolbar.js

@@ -112,11 +112,15 @@ export function SceneToolbar({ tool, gizmoMode, gizmoSpace, gizmoPivot, snapMode
                     ? "border-cyan-400/30 bg-cyan-500/15 text-cyan-100"
                     : "border-white/[0.07] bg-[#191d24] text-neutral-300 hover:bg-[#1f242d]"}`, children: [_jsx(Icon, { name: "camera", size: 12 }), cameraProjection === "perspective" ? "Persp" : "Ortho"] }), _jsx(ToolbarDivider, {}), _jsxs("div", { className: "relative", children: [_jsxs("button", { type: "button", onClick: () => setAddOpen((value) => !value), "aria-expanded": addOpen, className: `flex h-7 items-center gap-1.5 rounded-[5px] px-2.5 text-[12px] font-medium transition-colors ${FOCUS_RING} ${addOpen || placementActive
                             ? "bg-cyan-600 text-white shadow-sm shadow-cyan-950/40"
-                            : "border border-white/[0.07] bg-[#191d24] text-neutral-200 hover:bg-[#1f242d]"}`, children: [_jsx(Icon, { name: "plus", size: 12 }), "Add"] }), _jsxs(MenuShell, { open: addOpen, onClose: () => setAddOpen(false), children: [_jsx("div", { className: `px-2 pb-1 pt-1.5 ${MICRO_LABEL}`, children: "Markers" }), WELL_KNOWN_MARKER_KINDS.map((kind) => (_jsx("button", { type: "button", className: MENU_ITEM, onClick: () => pick({ tool: "marker", kind }), children: kind }, kind))), _jsx("div", { className: `px-2 pb-1 pt-2 ${MICRO_LABEL}`, children: "Volumes" }), ADD_VOLUME_ENTRIES.map((entry) => (_jsx("button", { type: "button", className: MENU_ITEM, onClick: () => pick(entry.tool), children: entry.label }, entry.label))), _jsx("div", { className: `px-2 pb-1 pt-2 ${MICRO_LABEL}`, children: "Studios" }), studioKinds.map((definition) => (_jsxs("button", { type: "button", className: `${MENU_ITEM}`, style: { color: definition.accent ?? "#34d399" }, onClick: () => pick(definition.target === "path"
-                                    ? { tool: "path", kind: definition.kind }
-                                    : definition.target === "volume"
-                                        ? { tool: "volume", kind: definition.kind, shape: "box" }
-                                        : { tool: "marker", kind: definition.kind }), children: [definition.label, definition.target === "path" ? (definition.pathShape === "line" ? " (draw line)" : " (lasso)") : ""] }, definition.kind))), _jsx("div", { className: `px-2 pb-1 pt-2 ${MICRO_LABEL}`, children: "Paths & notes" }), _jsx("button", { type: "button", className: MENU_ITEM, onClick: () => pick({ tool: "path", kind: "route" }), children: "Draw path (route)" }), _jsx("button", { type: "button", className: MENU_ITEM, onClick: () => pick({ tool: "path", kind: "road" }), children: "Draw road" }), _jsx("button", { type: "button", className: MENU_ITEM, onClick: () => pick({ tool: "note" }), children: "Note" })] })] }), _jsx("div", { className: "ml-auto flex items-center gap-1", children: _jsxs("button", { type: "button", onClick: onOpenAssistant, className: `flex h-7 items-center gap-1.5 rounded-[5px] px-2.5 text-[12px] transition-colors ${FOCUS_RING} ${assistantOpen
+                            : "border border-white/[0.07] bg-[#191d24] text-neutral-200 hover:bg-[#1f242d]"}`, children: [_jsx(Icon, { name: "plus", size: 12 }), "Add"] }), _jsxs(MenuShell, { open: addOpen, onClose: () => setAddOpen(false), children: [_jsx("div", { className: `px-2 pb-1 pt-1.5 ${MICRO_LABEL}`, children: "Markers" }), WELL_KNOWN_MARKER_KINDS.map((kind) => (_jsx("button", { type: "button", className: MENU_ITEM, onClick: () => pick({ tool: "marker", kind }), children: kind }, kind))), _jsx("div", { className: `px-2 pb-1 pt-2 ${MICRO_LABEL}`, children: "Volumes" }), ADD_VOLUME_ENTRIES.map((entry) => (_jsx("button", { type: "button", className: MENU_ITEM, onClick: () => pick(entry.tool), children: entry.label }, entry.label))), [...studioKinds.reduce((groups, definition) => {
+                                    const category = definition.addCategory ?? "Studios";
+                                    (groups.get(category) ?? groups.set(category, []).get(category)).push(definition);
+                                    return groups;
+                                }, new Map())].map(([category, defs]) => (_jsxs("div", { children: [_jsx("div", { className: `px-2 pb-1 pt-2 ${MICRO_LABEL}`, children: category }), defs.map((definition) => (_jsxs("button", { type: "button", className: `${MENU_ITEM}`, style: { color: definition.accent ?? "#34d399" }, onClick: () => pick(definition.target === "path"
+                                            ? { tool: "path", kind: definition.kind }
+                                            : definition.target === "volume"
+                                                ? { tool: "volume", kind: definition.kind, shape: "box" }
+                                                : { tool: "marker", kind: definition.kind }), children: [definition.label, definition.target === "path" ? (definition.pathShape === "line" ? " (draw line)" : " (lasso)") : ""] }, definition.kind)))] }, category))), _jsx("div", { className: `px-2 pb-1 pt-2 ${MICRO_LABEL}`, children: "Paths & notes" }), _jsx("button", { type: "button", className: MENU_ITEM, onClick: () => pick({ tool: "path", kind: "route" }), children: "Draw path (route)" }), _jsx("button", { type: "button", className: MENU_ITEM, onClick: () => pick({ tool: "path", kind: "road" }), children: "Draw road" }), _jsx("button", { type: "button", className: MENU_ITEM, onClick: () => pick({ tool: "note" }), children: "Note" })] })] }), _jsx("div", { className: "ml-auto flex items-center gap-1", children: _jsxs("button", { type: "button", onClick: onOpenAssistant, className: `flex h-7 items-center gap-1.5 rounded-[5px] px-2.5 text-[12px] transition-colors ${FOCUS_RING} ${assistantOpen
                         ? "border border-violet-400/40 bg-violet-500/20 text-violet-100"
                         : "border border-white/[0.07] bg-[#191d24] text-neutral-300 hover:bg-[#1f242d] hover:text-neutral-100"}`, title: "AI assistant \u2014 drives the scene through the same RPC and undo as the toolbar", children: [_jsx(Icon, { name: "sparkle", size: 13 }), "AI"] }) })] }));
 }

package/dist/shell/fields.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef, useState } from "react";
+import { useRef, useState } from "react";
 import { AXIS_COLORS, FOCUS_RING, INPUT_CLS, NUMERIC } from "./theme.js";
 /** Pixels of pointer drag per `step` of value change when scrubbing an axis chip. */
 const DRAG_PX_PER_STEP = 4;
@@ -15,14 +15,12 @@ function formatValue(value, precision) {
  * values on change and re-normalizes its text on blur. Invalid text never commits.
  */
 export function AxisNumberField({ axis, label, value, onCommit, step = 0.1, precision = 3, disabled = false, mixed = false, }) {
-    const [text, setText] = useState(() => (mixed ? "—" : formatValue(value, precision)));
+    // `text` only exists while the input has focus; otherwise the shown value derives from props.
+    const [text, setText] = useState("");
     const [editing, setEditing] = useState(false);
     const inputRef = useRef(null);
     const dragRef = useRef(null);
-    useEffect(() => {
-        if (!editing)
-            setText(mixed ? "—" : formatValue(value, precision));
-    }, [value, precision, editing, mixed]);
+    const formatted = mixed ? "—" : formatValue(value, precision);
     const commitText = (raw) => {
         if (raw === "—" || raw.trim().length === 0)
             return;
@@ -69,7 +67,10 @@ export function AxisNumberField({ axis, label, value, onCommit, step = 0.1, prec
         }
     };
     const colors = axis !== undefined ? AXIS_COLORS[axis] : null;
-    return (_jsxs("label", { title: `Drag to adjust ${label} · Alt-click or focus input to type`, onPointerDown: onScrubPointerDown, onPointerMove: onScrubPointerMove, onPointerUp: onScrubPointerUp, className: `flex min-w-0 flex-1 cursor-ew-resize items-center overflow-hidden rounded-[5px] border border-white/[0.08] bg-black/30 focus-within:border-cyan-400/50 ${editing ? "cursor-text" : ""}`, children: [_jsxs("span", { className: `relative flex h-6.5 w-6 shrink-0 select-none items-center justify-center border-r border-white/[0.06] bg-white/[0.03] text-[10px] font-semibold uppercase ${colors !== null ? colors.text : "text-neutral-500"}`, children: [colors !== null ? _jsx("span", { className: `absolute inset-y-0 left-0 w-0.5 ${colors.bar}` }) : null, label] }), _jsx("input", { ref: inputRef, type: "text", inputMode: "decimal", value: text, disabled: disabled, "aria-label": label, onFocus: () => setEditing(true), onDoubleClick: (event) => {
+    return (_jsxs("label", { title: `Drag to adjust ${label} · Alt-click or focus input to type`, onPointerDown: onScrubPointerDown, onPointerMove: onScrubPointerMove, onPointerUp: onScrubPointerUp, className: `flex min-w-0 flex-1 cursor-ew-resize items-center overflow-hidden rounded-[5px] border border-white/[0.08] bg-black/30 focus-within:border-cyan-400/50 ${editing ? "cursor-text" : ""}`, children: [_jsxs("span", { className: `relative flex h-6.5 w-6 shrink-0 select-none items-center justify-center border-r border-white/[0.06] bg-white/[0.03] text-[10px] font-semibold uppercase ${colors !== null ? colors.text : "text-neutral-500"}`, children: [colors !== null ? _jsx("span", { className: `absolute inset-y-0 left-0 w-0.5 ${colors.bar}` }) : null, label] }), _jsx("input", { ref: inputRef, type: "text", inputMode: "decimal", value: editing ? text : formatted, disabled: disabled, "aria-label": label, onFocus: () => {
+                    setText(formatted);
+                    setEditing(true);
+                }, onDoubleClick: (event) => {
                     event.stopPropagation();
                     event.currentTarget.select();
                 }, onChange: (event) => {
@@ -78,7 +79,6 @@ export function AxisNumberField({ axis, label, value, onCommit, step = 0.1, prec
                 }, onBlur: (event) => {
                     setEditing(false);
                     commitText(event.target.value);
-                    setText(formatValue(Number.isFinite(Number(event.target.value)) ? Number(event.target.value) : value, precision));
                 }, onKeyDown: (event) => {
                     if (event.key === "Enter")
                         event.currentTarget.blur();