@jgengine/editor 0.18.1 → 0.21.0

package/dist/shell/AnimationGraphPanel.js

@@ -0,0 +1,180 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { markerCatalogId } from "@jgengine/core/world/authoredObjects";
+import { animationMetaPatch, clearAnimGraph, effectiveAnimGraph, readAnimationSettingResult, setTransitionDuration, storeAnimGraph, } from "../modelAnimationAuthoring.js";
+import { shallowArrayEqual, useStoreSelector } from "../useStoreSelector.js";
+import { graphParamControls, graphTriggers, MAX_PREVIEW_SECONDS, recordTrigger, simulateGraphPreview, } from "./animGraphPreview.js";
+import { initialClipPreviewState } from "./clipPreview.js";
+import { FOCUS_RING, INPUT_CLS, NUMERIC } from "./theme.js";
+import { EmptyState, IconButton } from "./ui.js";
+const SOURCE_LABEL = {
+    authored: "Stored on this placement",
+    locomotion: "Built from the placement's states and one-shots",
+    auto: "Derived from the rig's clip names",
+};
+function conditionText(condition) {
+    return `${condition.param} ${condition.op} ${String(condition.value)}`;
+}
+function stateClips(state) {
+    if (state.kind === "clip")
+        return state.clip;
+    if (state.kind === "blend1D")
+        return state.points.map((point) => `${point.clip}@${point.at}`).join(" · ");
+    return state.points.map((point) => `${point.clip}@${point.at[0]},${point.at[1]}`).join(" · ");
+}
+/**
+ * Graph mode of the Animation dock: the selected placement's animation graph (layers, states,
+ * transitions), a scrubbed preview driven by the headless graph runtime and shown on the rig in the
+ * viewport, trigger buttons that record presses on the timeline, and crossfade editing that stores
+ * the graph on the placement as an undoable edit.
+ *
+ * @internal
+ */
+export function AnimationGraphPanel({ session, ui, rigged, }) {
+    const selection = useStoreSelector(session, (state) => state.selection, shallowArrayEqual);
+    const markers = useStoreSelector(session, (state) => state.document.markers);
+    const target = useMemo(() => {
+        for (const id of selection) {
+            const marker = markers.find((entry) => entry.id === id);
+            if (marker === undefined)
+                continue;
+            if (readAnimationSettingResult({ markers }, marker.id).diagnostics.length > 0)
+                return { marker, asset: undefined };
+            const catalogId = markerCatalogId(marker);
+            const asset = catalogId === null ? undefined : rigged.find((entry) => entry.id === catalogId);
+            if (asset?.url !== undefined && asset.clips !== undefined)
+                return { marker, asset };
+        }
+        return null;
+    }, [selection, markers, rigged]);
+    if (target === null) {
+        return (_jsx(EmptyState, { icon: "film", title: "Animation graph", badge: "Placed rig", description: "Select a placed instance of a rigged asset to see the graph it plays: layers, states and transitions, with a scrubbed preview on the rig in the viewport." }));
+    }
+    return _jsx(GraphInspector, { session: session, ui: ui, marker: target.marker, asset: target.asset }, target.marker.id);
+}
+function GraphInspector({ session, ui, marker, asset, }) {
+    const clips = asset?.clips ?? [];
+    const document = useStoreSelector(session, (state) => state.document);
+    const { setting, diagnostics } = readAnimationSettingResult(document, marker.id);
+    const invalid = diagnostics.length > 0;
+    const effective = useMemo(() => invalid || asset === undefined ? null : effectiveAnimGraph(setting, clips), [JSON.stringify(setting), invalid, asset, clips]);
+    const graph = effective?.graph ?? null;
+    const controls = useMemo(() => (graph === null ? [] : graphParamControls(graph)), [graph]);
+    const triggerNames = useMemo(() => (graph === null ? [] : graphTriggers(graph)), [graph]);
+    const [time, setTime] = useState(0);
+    const [playing, setPlaying] = useState(false);
+    const [params, setParams] = useState({});
+    const [triggers, setTriggers] = useState([]);
+    useEffect(() => { if (invalid)
+        setPlaying(false); }, [invalid]);
+    const durations = useStoreSelector(ui, (state) => state.clipPreview?.clipDurations);
+    const frame = useMemo(() => {
+        if (graph === null)
+            return null;
+        const merged = {};
+        for (const control of controls)
+            merged[control.name] = params[control.name] ?? (control.kind === "boolean" ? false : 0);
+        return simulateGraphPreview({ graph, durations: durations ?? {}, time, params: merged, triggers });
+    }, [graph, controls, params, triggers, time, durations]);
+    useEffect(() => {
+        if (asset?.url === undefined)
+            return;
+        const current = ui.getState().clipPreview;
+        const sameAsset = current?.source.assetId === asset.id;
+        ui.patch({
+            clipPreview: {
+                source: { assetId: asset.id, label: asset.label, url: asset.url, clips },
+                driver: initialClipPreviewState(null),
+                duration: 0,
+                ...(sameAsset && current?.clipDurations !== undefined ? { clipDurations: current.clipDurations } : {}),
+            },
+        });
+        return () => {
+            if (ui.getState().clipPreview?.source.assetId === asset.id)
+                ui.patch({ clipPreview: null });
+        };
+    }, [asset?.id, asset?.url, asset?.label, clips, ui]);
+    useEffect(() => {
+        const current = ui.getState().clipPreview;
+        if (asset === undefined || current === null || current.source.assetId !== asset.id)
+            return;
+        if (graph === null || frame === null) {
+            if (current.graphPose !== undefined)
+                ui.patch({ clipPreview: { ...current, graphPose: undefined } });
+            return;
+        }
+        ui.patch({ clipPreview: { ...current, graphPose: { graph, clips: frame.clips, ...(frame.rootMotion === true ? { rootMotion: true } : {}) } } });
+    }, [graph, frame, asset?.id, ui, durations]);
+    const timeRef = useRef(time);
+    timeRef.current = time;
+    useEffect(() => {
+        if (!playing)
+            return;
+        let handle = 0;
+        let last = performance.now();
+        const tick = (now) => {
+            const next = timeRef.current + Math.min(0.05, Math.max(0, (now - last) / 1000));
+            last = now;
+            if (next >= MAX_PREVIEW_SECONDS) {
+                setTime(MAX_PREVIEW_SECONDS);
+                setPlaying(false);
+                return;
+            }
+            setTime(next);
+            handle = requestAnimationFrame(tick);
+        };
+        handle = requestAnimationFrame(tick);
+        return () => cancelAnimationFrame(handle);
+    }, [playing]);
+    const commit = (next) => session.dispatch({ type: "setMarker", id: marker.id, patch: { meta: { ...marker.meta, ...animationMetaPatch(next) } } }, { coalesce: `animation:${marker.id}` });
+    if (invalid)
+        return (_jsxs("div", { className: "space-y-2 p-3 text-[11px]", children: [_jsxs("div", { role: "alert", "aria-label": "Animation diagnostics", className: "space-y-1 text-amber-200", children: [_jsx("p", { children: "The saved animation override is invalid. Its graph cannot be previewed or edited until repaired or replaced." }), diagnostics.map((entry) => _jsxs("div", { children: [_jsxs("div", { className: "break-all", children: [entry.path, ": ", entry.message] }), _jsx("div", { children: entry.repair })] }, `${entry.path}:${entry.message}`))] }), _jsxs("div", { className: "flex gap-2", children: [_jsx("button", { type: "button", className: SMALL_BUTTON, onClick: () => commit(undefined), children: "Remove invalid animation override" }), _jsx("button", { type: "button", className: SMALL_BUTTON, onClick: () => commit("auto"), children: "Replace invalid override with Auto" })] }), _jsx("p", { className: "text-neutral-500", children: "Replacement discards the invalid override and can be undone. Repair its saved fields through the existing marker metadata API to retain the intended graph." })] }));
+    if (graph === null || effective === null || frame === null || asset === undefined) {
+        return (_jsx(EmptyState, { icon: "film", title: "No graph", badge: marker.label ?? marker.id, description: "This placement plays no graph: its animation is off, a single clip, or the rig has no idle clip. Pick Custom or Auto in the inspector's Animation section." }));
+    }
+    const weights = new Map(frame.clips.map((clip) => [`${clip.layer}:${clip.clip}`, clip.weight]));
+    const trigger = (name) => setTriggers((current) => recordTrigger(current, name, timeRef.current));
+    return (_jsxs("div", { className: "flex min-h-0 flex-1 flex-col", children: [_jsxs("div", { className: "flex h-7 shrink-0 items-center gap-1.5 border-b border-white/[0.06] px-2", children: [_jsx("span", { className: "text-[10px] uppercase tracking-wider text-neutral-500", children: marker.label ?? marker.id }), _jsxs("span", { className: "text-[10px] text-neutral-600", children: [asset.label, " \u00B7 ", SOURCE_LABEL[effective.source]] }), _jsx("div", { className: "ml-auto flex items-center gap-1", children: effective.source === "authored" ? (_jsx("button", { type: "button", className: SMALL_BUTTON, onClick: () => commit(clearAnimGraph(setting)), title: "Drop the stored graph", children: "Use derived graph" })) : (_jsx("button", { type: "button", className: SMALL_BUTTON, onClick: () => commit(storeAnimGraph(setting, graph)), title: "Store this graph on the placement", children: "Store graph" })) })] }), _jsxs("div", { className: "flex min-h-0 flex-1 gap-3 overflow-auto p-3", children: [_jsxs("div", { className: "flex w-64 shrink-0 flex-col gap-2", children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(IconButton, { icon: playing ? "pause" : "play", label: playing ? "Pause preview" : "Play preview", size: 14, active: playing, onClick: () => setPlaying((value) => !value) }), _jsx("button", { type: "button", className: SMALL_BUTTON, onClick: () => {
+                                            setPlaying(false);
+                                            setTime(0);
+                                            setTriggers([]);
+                                        }, children: "Reset" }), _jsxs("span", { className: `ml-auto text-[10px] text-neutral-400 ${NUMERIC}`, children: [time.toFixed(2), " s"] })] }), _jsxs("label", { className: "flex flex-col gap-1", children: [_jsx("span", { className: "text-[9px] uppercase tracking-wider text-neutral-600", children: "Scrub" }), _jsx("input", { type: "range", min: 0, max: MAX_PREVIEW_SECONDS, step: 0.01, value: time, "aria-label": "Graph preview time", className: `h-2 w-full accent-cyan-400 ${FOCUS_RING}`, onChange: (event) => {
+                                            setPlaying(false);
+                                            setTime(Number(event.target.value));
+                                        } }), _jsx(TriggerTicks, { triggers: triggers })] }), controls.map((control) => control.kind === "boolean" ? (_jsxs("label", { className: "flex items-center gap-2 text-[11px] text-neutral-300", children: [_jsx("input", { type: "checkbox", checked: params[control.name] === true, "aria-label": `Parameter ${control.name}`, onChange: (event) => setParams((current) => ({ ...current, [control.name]: event.target.checked })) }), control.name] }, control.name)) : (_jsxs("label", { className: "flex flex-col gap-1", children: [_jsxs("div", { className: "flex items-center justify-between text-[9px] uppercase tracking-wider text-neutral-600", children: [_jsx("span", { children: control.name }), _jsx("span", { className: NUMERIC, children: Number(params[control.name] ?? 0).toFixed(2) })] }), _jsx("input", { type: "range", min: control.min, max: control.max, step: (control.max - control.min) / 200, value: Number(params[control.name] ?? 0), "aria-label": `Parameter ${control.name}`, className: `h-2 w-full accent-cyan-400 ${FOCUS_RING}`, onChange: (event) => setParams((current) => ({ ...current, [control.name]: Number(event.target.value) })) })] }, control.name))), triggerNames.length > 0 ? (_jsxs("div", { className: "flex flex-col gap-1", children: [_jsx("span", { className: "text-[9px] uppercase tracking-wider text-neutral-600", children: "Triggers at the playhead" }), _jsx("div", { className: "flex flex-wrap gap-1", children: triggerNames.map((name) => (_jsx("button", { type: "button", className: SMALL_BUTTON, onClick: () => trigger(name), children: name }, name))) })] })) : null, frame.events.length > 0 ? (_jsxs("div", { className: "flex flex-col gap-0.5", children: [_jsx("span", { className: "text-[9px] uppercase tracking-wider text-neutral-600", children: "Clip events" }), frame.events.slice(-6).map((event, index) => (_jsxs("span", { className: `text-[10px] text-amber-200/80 ${NUMERIC}`, children: [event.at.toFixed(2), " s \u00B7 ", event.name, " (", event.clip, ")"] }, index)))] })) : null] }), _jsx("div", { className: "flex min-w-0 flex-1 flex-col gap-3", children: graph.layers.map((layer) => (_jsxs("section", { className: "rounded-[6px] border border-white/[0.07] bg-white/[0.02]", "aria-label": `Layer ${layer.id}`, children: [_jsxs("header", { className: "flex items-center gap-2 border-b border-white/[0.06] px-2.5 py-1.5", children: [_jsx("span", { className: "text-[11px] font-medium text-neutral-100", children: layer.id }), _jsxs("span", { className: "text-[10px] text-neutral-500", children: ["entry ", layer.entry] }), layer.mask !== undefined ? _jsxs(Chip, { children: ["mask ", layer.mask.join(", ")] }) : null, layer.additive === true ? _jsx(Chip, { children: "additive" }) : null, layer.weight !== undefined ? _jsxs(Chip, { children: ["weight ", layer.weight] }) : null, _jsxs("span", { className: "ml-auto text-[10px] text-cyan-200", children: ["\u25B6 ", frame.states[layer.id]] })] }), _jsxs("div", { className: "grid grid-cols-2 gap-3 p-2.5", children: [_jsxs("div", { className: "flex flex-col gap-1", children: [_jsx("span", { className: "text-[9px] uppercase tracking-wider text-neutral-600", children: "States" }), Object.entries(layer.states).map(([name, state]) => {
+                                                    const active = frame.states[layer.id] === name;
+                                                    const clipsOfState = state.kind === "clip" ? [state.clip] : state.points.map((point) => point.clip);
+                                                    const weight = clipsOfState.reduce((sum, clip) => sum + (weights.get(`${layer.id}:${clip}`) ?? 0), 0);
+                                                    return (_jsxs("div", { className: `rounded-[5px] border px-2 py-1 ${active ? "border-cyan-400/40 bg-cyan-500/10" : "border-white/[0.05]"}`, children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx("span", { className: "text-[11px] text-neutral-100", children: name }), _jsx("span", { className: "text-[10px] text-neutral-500", children: state.kind }), _jsx("span", { className: `ml-auto text-[10px] text-neutral-400 ${NUMERIC}`, children: weight > 0 ? weight.toFixed(2) : "" })] }), _jsx("div", { className: "truncate text-[10px] text-neutral-500", title: stateClips(state), children: stateClips(state) }), _jsx("div", { className: "mt-1 h-1 rounded bg-white/[0.05]", children: _jsx("div", { className: "h-1 rounded bg-cyan-400/70", style: { width: `${Math.round(Math.min(1, weight) * 100)}%` } }) })] }, name));
+                                                })] }), _jsxs("div", { className: "flex flex-col gap-1", children: [_jsx("span", { className: "text-[9px] uppercase tracking-wider text-neutral-600", children: "Transitions" }), layer.transitions.length === 0 ? _jsx("span", { className: "text-[10px] text-neutral-600", children: "None" }) : null, layer.transitions.map((transition, index) => (_jsx(TransitionRow, { transition: transition, onTrigger: transition.trigger === undefined ? undefined : () => trigger(transition.trigger), onDuration: (duration) => commit(setTransitionDuration(setting, graph, layer.id, index, duration)) }, index)))] })] })] }, layer.id))) })] })] }));
+}
+const SMALL_BUTTON = `rounded-[5px] border border-white/[0.08] bg-white/[0.03] px-2 py-0.5 text-[10px] text-neutral-300 transition-colors hover:bg-white/[0.07] ${FOCUS_RING}`;
+function Chip({ children }) {
+    return _jsx("span", { className: "rounded-[4px] bg-white/[0.05] px-1.5 py-0.5 text-[9px] text-neutral-400", children: children });
+}
+function TriggerTicks({ triggers }) {
+    if (triggers.length === 0)
+        return null;
+    return (_jsx("div", { className: "relative h-3", "aria-label": "Recorded triggers", children: triggers.map((entry, index) => (_jsx("span", { title: `${entry.name} at ${entry.at.toFixed(2)} s`, className: "absolute top-0 h-3 w-0.5 bg-amber-300/80", style: { left: `${(entry.at / MAX_PREVIEW_SECONDS) * 100}%` } }, index))) }));
+}
+function TransitionRow({ transition, onTrigger, onDuration, }) {
+    const [draft, setDraft] = useState(String(transition.duration ?? 0.2));
+    useEffect(() => setDraft(String(transition.duration ?? 0.2)), [transition.duration]);
+    const label = `${transition.from} → ${transition.to}`;
+    return (_jsxs("div", { className: "flex items-center gap-1.5 rounded-[5px] border border-white/[0.05] px-2 py-1", children: [_jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("div", { className: "truncate text-[11px] text-neutral-100", children: label }), _jsx("div", { className: "truncate text-[10px] text-neutral-500", children: [
+                            transition.trigger === undefined ? null : `trigger ${transition.trigger}`,
+                            ...(transition.when ?? []).map(conditionText),
+                            transition.exitTime === undefined ? null : `exit ${transition.exitTime}`,
+                        ]
+                            .filter((part) => part !== null)
+                            .join(" · ") || "always" })] }), _jsx("input", { className: `${INPUT_CLS} h-6 w-14 px-1 text-right text-[11px] ${NUMERIC}`, value: draft, "aria-label": `Crossfade seconds for ${label}`, inputMode: "decimal", onChange: (event) => setDraft(event.target.value), onBlur: () => {
+                    const value = Number(draft);
+                    if (Number.isFinite(value) && value !== (transition.duration ?? 0.2))
+                        onDuration(value);
+                    else
+                        setDraft(String(transition.duration ?? 0.2));
+                }, onKeyDown: (event) => {
+                    if (event.key === "Enter")
+                        event.target.blur();
+                } }), _jsx("span", { className: "text-[9px] text-neutral-600", children: "s" }), onTrigger !== undefined ? _jsx(IconButton, { icon: "play", label: `Trigger ${transition.trigger}`, size: 11, onClick: onTrigger }) : null] }));
+}

package/dist/shell/AnimationPanel.d.ts

@@ -3,7 +3,9 @@ import type { EditorAssetEntry } from "../AssetBrowser.js";
 import type { EditorHostApi } from "../session.js";
 import type { EditorUiStore } from "../uiStore.js";
 /**
- * Animation dock with two modes:
+ * Animation dock with three modes:
+ * - **Graph** — the selected placement's animation graph with a scrubbed, triggerable preview posed
+ *   on the rig in the viewport (see {@link AnimationGraphPanel}).
  * - **Path** — scrub/play the editor orbit camera along authored scene polylines (real path points,
  *   no fabricated keyframes).
  * - **Clips** — preview a rigged asset's animation clips in the viewport (scrub, loop, speed) via the

package/dist/shell/AnimationPanel.js

@@ -3,6 +3,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { markerCatalogId } from "@jgengine/core/world/authoredObjects";
 import { shallowArrayEqual, useStoreSelector } from "../useStoreSelector.js";
 import { advancePreview, clipEntriesFromRef, initialClipPreviewState, MAX_PREVIEW_SPEED, MIN_PREVIEW_SPEED, scrubPreview, selectPreviewClip, setPreviewLoop, setPreviewSpeed, togglePreviewPlaying, } from "./clipPreview.js";
+import { AnimationGraphPanel } from "./AnimationGraphPanel.js";
 import { listScrubbablePaths, samplePathAt } from "./pathFlythrough.js";
 import { FOCUS_RING, INPUT_CLS, NUMERIC } from "./theme.js";
 import { EmptyState, IconButton } from "./ui.js";
@@ -13,7 +14,9 @@ function riggedAssets(assets) {
     return assets.filter((entry) => entry.url !== undefined && entry.clips !== undefined && entry.clips.length > 0);
 }
 /**
- * Animation dock with two modes:
+ * Animation dock with three modes:
+ * - **Graph** — the selected placement's animation graph with a scrubbed, triggerable preview posed
+ *   on the rig in the viewport (see {@link AnimationGraphPanel}).
  * - **Path** — scrub/play the editor orbit camera along authored scene polylines (real path points,
  *   no fabricated keyframes).
  * - **Clips** — preview a rigged asset's animation clips in the viewport (scrub, loop, speed) via the
@@ -23,9 +26,7 @@ function riggedAssets(assets) {
  */
 export function AnimationPanel({ session, api, ui, assets, }) {
     const rigged = useMemo(() => riggedAssets(assets), [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");
+    const [mode, setMode] = useState(() => (rigged.length > 0 ? "graph" : "path"));
     // Tear down the viewport preview when the panel unmounts; leaving clip mode tears down in the
     // tab click below.
     useEffect(() => () => {
@@ -33,13 +34,14 @@ export function AnimationPanel({ session, api, ui, assets, }) {
             ui.patch({ clipPreview: null });
     }, [ui]);
     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"],
+                        ["graph", "Graph"],
                         ["clips", "Clip preview"],
+                        ["path", "Path flythrough"],
                     ].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)
+                            if (id !== mode && 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 }))] }));
+                        }, children: label }, id))) }) }), mode === "path" ? (_jsx(PathFlythrough, { session: session, api: api })) : mode === "graph" ? (_jsx(AnimationGraphPanel, { session: session, ui: ui, rigged: rigged })) : (_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, }) {

package/dist/shell/PlayModeBar.d.ts

@@ -12,8 +12,9 @@ export declare function usePlayControl(api: EditorHostApi): RuntimePlayControl;
  * controls (`runtime_pause` / `runtime_resume` / `runtime_step`); Exit returns to edit.
  * @internal
  */
-export declare function PlayModeBar({ gameId, api, onExit, }: {
+export declare function PlayModeBar({ gameId, api, onExit, exitLabel, }: {
     gameId: string;
     api: EditorHostApi;
     onExit: () => void;
+    exitLabel?: string;
 }): import("react").JSX.Element;

package/dist/shell/PlayModeBar.js

@@ -19,7 +19,7 @@ export function usePlayControl(api) {
  * controls (`runtime_pause` / `runtime_resume` / `runtime_step`); Exit returns to edit.
  * @internal
  */
-export function PlayModeBar({ gameId, api, onExit, }) {
+export function PlayModeBar({ gameId, api, onExit, exitLabel = "Editor", }) {
     const play = usePlayControl(api);
     const pause = () => {
         api.handle({ method: "runtime_pause" });
@@ -32,5 +32,5 @@ export function PlayModeBar({ gameId, api, onExit, }) {
     };
     return (_jsxs("header", { className: `pointer-events-auto relative z-[60] flex h-12 shrink-0 items-center gap-2 border-b ${BORDER} bg-[#111318] px-2.5`, role: "banner", "aria-label": "Play mode", children: [_jsxs("div", { className: "flex min-w-0 items-center gap-2.5", children: [_jsx("div", { className: "flex h-7 w-7 shrink-0 items-center justify-center rounded-[6px] bg-gradient-to-br from-emerald-500/30 to-cyan-500/25 text-[11px] font-bold tracking-wide text-emerald-200 ring-1 ring-inset ring-emerald-400/30", "aria-hidden": "true", children: "JG" }), _jsxs("div", { className: "min-w-0 leading-tight", children: [_jsx("div", { className: "truncate text-[13px] font-semibold text-neutral-100", children: gameId }), _jsx("div", { className: "text-[10px] text-neutral-500", children: "Play mode" })] }), _jsxs("span", { className: `ml-1 hidden items-center gap-1.5 rounded-full px-2 py-0.5 text-[10px] sm:flex ${play.paused
                             ? "bg-amber-500/15 text-amber-200 ring-1 ring-inset ring-amber-400/25"
-                            : "bg-emerald-500/15 text-emerald-200 ring-1 ring-inset ring-emerald-400/25"}`, children: [_jsx("span", { className: `h-1.5 w-1.5 rounded-full ${play.paused ? "bg-amber-400" : "bg-emerald-400 animate-pulse"}` }), play.paused ? "Paused" : "Playing"] })] }), _jsxs("div", { className: "ml-auto flex shrink-0 items-center gap-1", children: [_jsx(IconButton, { icon: play.paused ? "play" : "pause", label: play.paused ? "Resume simulation" : "Pause simulation", onClick: () => (play.paused ? resume() : pause()), active: play.paused }), _jsx(IconButton, { icon: "step", label: "Step one frame (pause required)", onClick: step, disabled: !play.paused }), _jsx(ToolbarDivider, {}), _jsxs("button", { type: "button", onClick: onExit, title: "Return to the editor (F2+E)", className: `flex h-8 items-center gap-1.5 rounded-[6px] border border-white/[0.07] bg-[#191d24] px-3 text-[12px] font-medium text-neutral-200 transition-colors hover:bg-[#1f242d] ${FOCUS_RING}`, children: [_jsx(Icon, { name: "panel", size: 12 }), "Editor"] })] })] }));
+                            : "bg-emerald-500/15 text-emerald-200 ring-1 ring-inset ring-emerald-400/25"}`, children: [_jsx("span", { className: `h-1.5 w-1.5 rounded-full ${play.paused ? "bg-amber-400" : "bg-emerald-400 animate-pulse"}` }), play.paused ? "Paused" : "Playing"] })] }), _jsxs("div", { className: "ml-auto flex shrink-0 items-center gap-1", children: [_jsx(IconButton, { icon: play.paused ? "play" : "pause", label: play.paused ? "Resume simulation" : "Pause simulation", onClick: () => (play.paused ? resume() : pause()), active: play.paused }), _jsx(IconButton, { icon: "step", label: "Step one frame (pause required)", onClick: step, disabled: !play.paused }), _jsx(ToolbarDivider, {}), _jsxs("button", { type: "button", onClick: onExit, title: "Return to the editor (F2+E)", className: `flex h-8 items-center gap-1.5 rounded-[6px] border border-white/[0.07] bg-[#191d24] px-3 text-[12px] font-medium text-neutral-200 transition-colors hover:bg-[#1f242d] ${FOCUS_RING}`, children: [_jsx(Icon, { name: "panel", size: 12 }), exitLabel] })] })] }));
 }

package/dist/shell/SceneToolbar.d.ts

@@ -8,7 +8,7 @@ export declare const ADD_VOLUME_ENTRIES: readonly {
  * Contextual scene toolbar under the app bar: tools, gizmo modes, gizmo space, pivot,
  * snapping, viewport overlays, framing, projection, and the Add menu.
  */
-export declare function SceneToolbar({ tool, gizmoMode, gizmoSpace, gizmoPivot, snapMode, gridSize, rotationSnapDeg, scaleSnap, cameraProjection, showGrid, showContours, showSurfaceGrid, showElevation, placementActive, onSetTool, onSetGizmoMode, onSetGizmoSpace, onSetGizmoPivot, onSetSnapMode, onSetGridSize, onSetRotationSnapDeg, onSetScaleSnap, onSetCameraProjection, onToggleGrid, onToggleContours, onToggleSurfaceGrid, onToggleElevation, onFrame, onStartPlacement, onOpenAssistant, assistantOpen, }: {
+export declare function SceneToolbar({ tool, gizmoMode, gizmoSpace, gizmoPivot, snapMode, gridSize, rotationSnapDeg, scaleSnap, cameraProjection, showGrid, showContours, showSurfaceGrid, showElevation, placementActive, onSetTool, onSetGizmoMode, onSetGizmoSpace, onSetGizmoPivot, onSetSnapMode, onSetGridSize, onSetRotationSnapDeg, onSetScaleSnap, onSetCameraProjection, onToggleGrid, onToggleContours, onToggleSurfaceGrid, onToggleElevation, onFrame, onStartPlacement, onOpenAssistant, assistantOpen, allowedKinds, }: {
     tool: EditorTool;
     gizmoMode: GizmoMode;
     gizmoSpace: GizmoSpace;
@@ -40,4 +40,5 @@ export declare function SceneToolbar({ tool, gizmoMode, gizmoSpace, gizmoPivot,
     onStartPlacement: (tool: PlacementTool) => void;
     onOpenAssistant: () => void;
     assistantOpen: boolean;
+    allowedKinds?: readonly string[];
 }): import("react").JSX.Element;

package/dist/shell/SceneToolbar.js

@@ -70,7 +70,7 @@ const PIVOT_LABEL = {
  * Contextual scene toolbar under the app bar: tools, gizmo modes, gizmo space, pivot,
  * snapping, viewport overlays, framing, projection, and the Add menu.
  */
-export function SceneToolbar({ tool, gizmoMode, gizmoSpace, gizmoPivot, snapMode, gridSize, rotationSnapDeg, scaleSnap, cameraProjection, showGrid, showContours, showSurfaceGrid, showElevation, placementActive, onSetTool, onSetGizmoMode, onSetGizmoSpace, onSetGizmoPivot, onSetSnapMode, onSetGridSize, onSetRotationSnapDeg, onSetScaleSnap, onSetCameraProjection, onToggleGrid, onToggleContours, onToggleSurfaceGrid, onToggleElevation, onFrame, onStartPlacement, onOpenAssistant, assistantOpen, }) {
+export function SceneToolbar({ tool, gizmoMode, gizmoSpace, gizmoPivot, snapMode, gridSize, rotationSnapDeg, scaleSnap, cameraProjection, showGrid, showContours, showSurfaceGrid, showElevation, placementActive, onSetTool, onSetGizmoMode, onSetGizmoSpace, onSetGizmoPivot, onSetSnapMode, onSetGridSize, onSetRotationSnapDeg, onSetScaleSnap, onSetCameraProjection, onToggleGrid, onToggleContours, onToggleSurfaceGrid, onToggleElevation, onFrame, onStartPlacement, onOpenAssistant, assistantOpen, allowedKinds, }) {
     const [addOpen, setAddOpen] = useState(false);
     const [snapOpen, setSnapOpen] = useState(false);
     const [pivotOpen, setPivotOpen] = useState(false);
@@ -79,7 +79,8 @@ export function SceneToolbar({ tool, gizmoMode, gizmoSpace, gizmoPivot, snapMode
         lastSnapRef.current = snapMode;
     // Recomputed every render (opening the menu rerenders): studios may register after the chrome
     // mounts (game modules load lazily), and a once-on-mount snapshot would silently hide them.
-    const studioKinds = listSceneKinds().filter((definition) => definition.addCategory !== undefined);
+    const allowed = (kind) => allowedKinds === undefined || allowedKinds.includes(kind);
+    const studioKinds = listSceneKinds().filter((definition) => definition.addCategory !== undefined && allowed(definition.kind));
     const pick = (placement) => {
         setAddOpen(false);
         onStartPlacement(placement);
@@ -112,7 +113,7 @@ 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))), [...studioKinds.reduce((groups, definition) => {
+                            : "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.filter(allowed).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.filter((entry) => ("kind" in entry.tool && allowed(entry.tool.kind))).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;
@@ -120,7 +121,7 @@ export function SceneToolbar({ tool, gizmoMode, gizmoSpace, gizmoPivot, snapMode
                                             ? { 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
+                                                : { 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", disabled: !allowed("route"), className: MENU_ITEM, onClick: () => pick({ tool: "path", kind: "route" }), children: "Draw path (route)" }), _jsx("button", { type: "button", disabled: !allowed("road"), 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/TopAppBar.d.ts

@@ -8,10 +8,11 @@ export type TopBarSaveState = "idle" | "saving" | "saved" | "error";
  * edit mode; Play mode mounts {@link PlayModeBar}, which wires the same controls to the
  * runtime pause/step RPCs so mode switches keep shell chrome.
  */
-export declare function TopAppBar({ gameId, onExitToGame, dirty, saveState, lastSavedAt, saveAvailable, saveError, canUndo, canRedo, onUndo, onRedo, onSave, onPlay, onWalk, onHud, onImport, onExport, onCopyJson, onOpenPalette, onToggleHelp, onResetLayout, }: {
+export declare function TopAppBar({ gameId, onExitToGame, exitLabel, dirty, saveState, lastSavedAt, saveAvailable, saveError, canUndo, canRedo, onUndo, onRedo, onSave, onPlay, onWalk, onHud, onImport, onExport, onCopyJson, onOpenPalette, onToggleHelp, onResetLayout, }: {
     gameId: string;
     /** When set (editor summoned over a game), renders an "Exit to game" control that closes the editor. */
     onExitToGame?: () => void;
+    exitLabel?: string;
     dirty: boolean;
     saveState: TopBarSaveState;
     /** Epoch ms of the last successful save this session; omit/null when never saved. */

package/dist/shell/TopAppBar.js

@@ -34,7 +34,7 @@ function SaveStatus({ dirty, saveState, lastSavedAt, }) {
  * edit mode; Play mode mounts {@link PlayModeBar}, which wires the same controls to the
  * runtime pause/step RPCs so mode switches keep shell chrome.
  */
-export function TopAppBar({ gameId, onExitToGame, dirty, saveState, lastSavedAt = null, saveAvailable, saveError, canUndo, canRedo, onUndo, onRedo, onSave, onPlay, onWalk, onHud, onImport, onExport, onCopyJson, onOpenPalette, onToggleHelp, onResetLayout, }) {
+export function TopAppBar({ gameId, onExitToGame, exitLabel = "Exit to game", dirty, saveState, lastSavedAt = null, saveAvailable, saveError, canUndo, canRedo, onUndo, onRedo, onSave, onPlay, onWalk, onHud, onImport, onExport, onCopyJson, onOpenPalette, onToggleHelp, onResetLayout, }) {
     const [menuOpen, setMenuOpen] = useState(false);
     const menuRef = useRef(null);
     useEffect(() => {
@@ -56,7 +56,7 @@ export function TopAppBar({ gameId, onExitToGame, dirty, saveState, lastSavedAt
         };
     }, [menuOpen]);
     const menuItem = `flex w-full items-center gap-2 rounded-[5px] px-2.5 py-1.5 text-left text-[12px] text-neutral-300 transition-colors hover:bg-cyan-500/15 hover:text-cyan-100 ${FOCUS_RING}`;
-    return (_jsxs("header", { className: `pointer-events-auto relative z-[60] flex h-12 shrink-0 items-center gap-2 border-b ${BORDER} bg-[#111318] px-2.5`, children: [_jsxs("div", { className: "flex min-w-0 items-center gap-2.5", children: [onExitToGame !== undefined ? (_jsxs("button", { type: "button", onClick: onExitToGame, title: "Close the editor and return to the game (F2+Q)", className: `flex h-8 shrink-0 items-center gap-1.5 rounded-[6px] border border-white/[0.08] bg-black/30 pl-2 pr-2.5 text-[12px] text-neutral-300 transition-colors hover:border-white/[0.16] hover:bg-white/[0.06] hover:text-neutral-100 ${FOCUS_RING}`, children: [_jsx(Icon, { name: "chevronRight", size: 14, className: "rotate-180" }), "Exit to game"] })) : null, _jsx("div", { className: "flex h-7 w-7 shrink-0 items-center justify-center rounded-[6px] bg-gradient-to-br from-cyan-500/30 to-indigo-500/25 text-[11px] font-bold tracking-wide text-cyan-200 ring-1 ring-inset ring-cyan-400/30", "aria-hidden": "true", children: "JG" }), _jsxs("div", { className: "min-w-0 leading-tight", children: [_jsx("div", { className: "truncate text-[13px] font-semibold text-neutral-100", children: gameId }), _jsx("div", { className: "text-[10px] text-neutral-500", children: "Scene Editor" })] }), _jsx("div", { className: "ml-1 hidden md:block", children: _jsx(SaveStatus, { dirty: dirty, saveState: saveState, lastSavedAt: lastSavedAt }) })] }), _jsx("div", { className: "flex flex-1 justify-center px-2", children: _jsxs("button", { type: "button", onClick: onOpenPalette, "aria-label": "Open command palette", className: `flex h-8 w-full max-w-[420px] items-center gap-2 rounded-[6px] border border-white/[0.08] bg-black/30 px-3 text-[12px] text-neutral-500 transition-colors hover:border-white/[0.14] hover:text-neutral-400 ${FOCUS_RING}`, children: [_jsx(Icon, { name: "search", size: 13 }), _jsx("span", { className: "min-w-0 flex-1 truncate text-left", children: "Search or run a command\u2026" }), _jsxs("span", { className: "hidden items-center gap-0.5 sm:flex", children: [_jsx(Kbd, { children: "Ctrl" }), _jsx(Kbd, { children: "K" })] })] }) }), _jsxs("div", { className: "flex shrink-0 items-center gap-1", children: [_jsx(IconButton, { icon: "undo", label: "Undo (Ctrl+Z)", onClick: onUndo, disabled: !canUndo, tone: "ghost" }), _jsx(IconButton, { icon: "redo", label: "Redo (Ctrl+Y)", onClick: onRedo, disabled: !canRedo, tone: "ghost" }), _jsx(ToolbarDivider, {}), _jsxs("button", { type: "button", onClick: onPlay, className: `flex h-8 items-center gap-1.5 rounded-[6px] bg-emerald-600 px-3.5 text-[12px] font-semibold text-white shadow-sm shadow-emerald-950/40 transition-colors hover:bg-emerald-500 ${FOCUS_RING}`, title: "Enter Play mode (F2+E toggles back)", children: [_jsx(Icon, { name: "play", size: 12 }), "Play"] }), _jsx(IconButton, { icon: "pause", label: "Pause \u2014 available in Play mode", disabled: true }), _jsx(IconButton, { icon: "step", label: "Step one frame \u2014 available in Play mode", disabled: true }), _jsx(ToolbarDivider, {}), _jsx(IconButton, { icon: "walk", label: "Walk the world", onClick: onWalk, tone: "ghost" }), _jsx(IconButton, { icon: "panel", label: "Lay out HUD panels", onClick: onHud, tone: "ghost" }), _jsx(ToolbarDivider, {}), saveAvailable ? (_jsxs("button", { type: "button", onClick: onSave, disabled: saveState === "saving", title: saveError ?? "Write the scene to the game's editor.scene.json (Ctrl+S)", className: `flex h-8 items-center gap-1.5 rounded-[6px] px-3 text-[12px] font-medium transition-colors ${FOCUS_RING} ${saveState === "error"
+    return (_jsxs("header", { className: `pointer-events-auto relative z-[60] flex h-12 shrink-0 items-center gap-2 border-b ${BORDER} bg-[#111318] px-2.5`, children: [_jsxs("div", { className: "flex min-w-0 items-center gap-2.5", children: [onExitToGame !== undefined ? (_jsxs("button", { type: "button", onClick: onExitToGame, title: `${exitLabel} (F2+Q)`, className: `flex h-8 shrink-0 items-center gap-1.5 rounded-[6px] border border-white/[0.08] bg-black/30 pl-2 pr-2.5 text-[12px] text-neutral-300 transition-colors hover:border-white/[0.16] hover:bg-white/[0.06] hover:text-neutral-100 ${FOCUS_RING}`, children: [_jsx(Icon, { name: "chevronRight", size: 14, className: "rotate-180" }), exitLabel] })) : null, _jsx("div", { className: "flex h-7 w-7 shrink-0 items-center justify-center rounded-[6px] bg-gradient-to-br from-cyan-500/30 to-indigo-500/25 text-[11px] font-bold tracking-wide text-cyan-200 ring-1 ring-inset ring-cyan-400/30", "aria-hidden": "true", children: "JG" }), _jsxs("div", { className: "min-w-0 leading-tight", children: [_jsx("div", { className: "truncate text-[13px] font-semibold text-neutral-100", children: gameId }), _jsx("div", { className: "text-[10px] text-neutral-500", children: "Scene Editor" })] }), _jsx("div", { className: "ml-1 hidden md:block", children: _jsx(SaveStatus, { dirty: dirty, saveState: saveState, lastSavedAt: lastSavedAt }) })] }), _jsx("div", { className: "flex flex-1 justify-center px-2", children: _jsxs("button", { type: "button", onClick: onOpenPalette, "aria-label": "Open command palette", className: `flex h-8 w-full max-w-[420px] items-center gap-2 rounded-[6px] border border-white/[0.08] bg-black/30 px-3 text-[12px] text-neutral-500 transition-colors hover:border-white/[0.14] hover:text-neutral-400 ${FOCUS_RING}`, children: [_jsx(Icon, { name: "search", size: 13 }), _jsx("span", { className: "min-w-0 flex-1 truncate text-left", children: "Search or run a command\u2026" }), _jsxs("span", { className: "hidden items-center gap-0.5 sm:flex", children: [_jsx(Kbd, { children: "Ctrl" }), _jsx(Kbd, { children: "K" })] })] }) }), _jsxs("div", { className: "flex shrink-0 items-center gap-1", children: [_jsx(IconButton, { icon: "undo", label: "Undo (Ctrl+Z)", onClick: onUndo, disabled: !canUndo, tone: "ghost" }), _jsx(IconButton, { icon: "redo", label: "Redo (Ctrl+Y)", onClick: onRedo, disabled: !canRedo, tone: "ghost" }), _jsx(ToolbarDivider, {}), _jsxs("button", { type: "button", onClick: onPlay, className: `flex h-8 items-center gap-1.5 rounded-[6px] bg-emerald-600 px-3.5 text-[12px] font-semibold text-white shadow-sm shadow-emerald-950/40 transition-colors hover:bg-emerald-500 ${FOCUS_RING}`, title: "Enter Play mode (F2+E toggles back)", children: [_jsx(Icon, { name: "play", size: 12 }), "Play"] }), _jsx(IconButton, { icon: "pause", label: "Pause \u2014 available in Play mode", disabled: true }), _jsx(IconButton, { icon: "step", label: "Step one frame \u2014 available in Play mode", disabled: true }), _jsx(ToolbarDivider, {}), _jsx(IconButton, { icon: "walk", label: "Walk the world", onClick: onWalk, tone: "ghost" }), _jsx(IconButton, { icon: "panel", label: "Lay out HUD panels", onClick: onHud, tone: "ghost" }), _jsx(ToolbarDivider, {}), saveAvailable ? (_jsxs("button", { type: "button", onClick: onSave, disabled: saveState === "saving", title: saveError ?? "Write the scene to the game's editor.scene.json (Ctrl+S)", className: `flex h-8 items-center gap-1.5 rounded-[6px] px-3 text-[12px] font-medium transition-colors ${FOCUS_RING} ${saveState === "error"
                             ? "bg-rose-600/90 text-white hover:bg-rose-500"
                             : dirty
                                 ? "bg-cyan-600 text-white shadow-sm shadow-cyan-950/40 hover:bg-cyan-500"

package/dist/shell/WorkspaceRail.js

@@ -8,7 +8,7 @@ export const WORKSPACES = [
     { id: "assets", label: "Assets", icon: "image", supported: true },
     { id: "materials", label: "Materials", icon: "sphere", supported: true },
     { id: "scripting", label: "Scripting", icon: "script", supported: true },
-    { id: "animation", label: "Animation", icon: "film", supported: false },
+    { id: "animation", label: "Animation", icon: "film", supported: true },
     { id: "audio", label: "Audio", icon: "audio", supported: false },
     { id: "lighting", label: "Lighting", icon: "bulb", supported: true },
     { id: "ai", label: "AI", icon: "sparkle", supported: true },

package/dist/shell/animGraphPreview.d.ts

@@ -0,0 +1,58 @@
+import { type AnimClipOutput, type AnimGraph, type AnimParams } from "@jgengine/core/anim/animGraph";
+/**
+ * Editor animation-graph preview: pure logic, no JSX. Replays a graph from its entry states to a
+ * scrub time with fixed steps, arming each recorded trigger at its time, so scrubbing back and forth
+ * always shows the same pose the runtime would reach.
+ *
+ * @internal
+ */
+/** A trigger pressed during preview, at a time on the scrub timeline. */
+export interface GraphPreviewTrigger {
+    at: number;
+    name: string;
+}
+/** Inputs for {@link simulateGraphPreview}. */
+export interface GraphPreviewInput {
+    graph: AnimGraph;
+    /** Clip durations in seconds from the loaded rig; unknown clips count as one second. */
+    durations: Readonly<Record<string, number>>;
+    time: number;
+    params: AnimParams;
+    triggers: readonly GraphPreviewTrigger[];
+    /** Fixed step in seconds. Default 1/30. */
+    step?: number;
+}
+/** What the rig shows at the scrub time. */
+export interface GraphPreviewFrame {
+    time: number;
+    /** Current state per layer id. */
+    states: Record<string, string>;
+    clips: AnimClipOutput[];
+    /** Clip events fired from zero to `time`, with when they fired. */
+    events: {
+        at: number;
+        name: string;
+        clip: string;
+    }[];
+    /** Active root-motion playback stays in place in the editor, matching the collision-authoritative shell. */
+    rootMotion?: true;
+}
+/** Longest preview timeline the scrubber offers, in seconds. */
+export declare const MAX_PREVIEW_SECONDS = 20;
+/** Replays `graph` from its entry states to `time` and reports the pose there. */
+export declare function simulateGraphPreview(input: GraphPreviewInput): GraphPreviewFrame;
+/** Every clip name a graph plays. */
+export declare function graphClipNames(graph: AnimGraph): string[];
+/** Every trigger name a graph's transitions listen for, in first-seen order. */
+export declare function graphTriggers(graph: AnimGraph): string[];
+/** A parameter the preview needs a control for: blend inputs and condition operands. */
+export interface GraphParamControl {
+    name: string;
+    kind: "number" | "boolean";
+    min: number;
+    max: number;
+}
+/** Parameters a graph reads, with a range covering its blend points and condition values. */
+export declare function graphParamControls(graph: AnimGraph): GraphParamControl[];
+/** Adds a trigger press at `at`, keeping the log in time order. */
+export declare function recordTrigger(triggers: readonly GraphPreviewTrigger[], name: string, at: number): GraphPreviewTrigger[];

package/dist/shell/animGraphPreview.js

@@ -0,0 +1,95 @@
+import { createAnimGraphRuntime, } from "@jgengine/core/anim/animGraph";
+/** Longest preview timeline the scrubber offers, in seconds. */
+export const MAX_PREVIEW_SECONDS = 20;
+/** Replays `graph` from its entry states to `time` and reports the pose there. */
+export function simulateGraphPreview(input) {
+    const step = input.step ?? 1 / 30;
+    const time = Math.max(0, Math.min(MAX_PREVIEW_SECONDS, input.time));
+    const runtime = createAnimGraphRuntime(input.graph);
+    const clips = {};
+    for (const name of graphClipNames(input.graph))
+        clips[name] = input.durations[name] ?? 1;
+    const pending = [...input.triggers].filter((trigger) => trigger.at <= time).sort((a, b) => a.at - b.at);
+    const events = [];
+    let elapsed = 0;
+    let next = 0;
+    let out = runtime.advance(0, input.params, clips);
+    while (elapsed < time - 1e-9) {
+        const dt = Math.min(step, time - elapsed);
+        while (next < pending.length && pending[next].at <= elapsed + 1e-9)
+            runtime.trigger(pending[next++].name);
+        out = runtime.advance(dt, input.params, clips);
+        elapsed += dt;
+        for (const event of out.events)
+            events.push({ at: elapsed, name: event.name, clip: event.clip });
+    }
+    if (next < pending.length) {
+        while (next < pending.length)
+            runtime.trigger(pending[next++].name);
+        out = runtime.advance(0, input.params, clips);
+    }
+    const states = {};
+    for (const layer of input.graph.layers)
+        states[layer.id] = runtime.stateOf(layer.id) ?? layer.entry;
+    return { time, states, clips: out.clips, events, ...(out.rootMotion === true ? { rootMotion: true } : {}) };
+}
+/** Every clip name a graph plays. */
+export function graphClipNames(graph) {
+    const names = new Set();
+    for (const layer of graph.layers) {
+        for (const state of Object.values(layer.states)) {
+            if (state.kind === "clip") {
+                names.add(state.clip);
+                for (const clip of state.variants ?? [])
+                    names.add(clip);
+            }
+            else
+                for (const point of state.points)
+                    names.add(point.clip);
+        }
+    }
+    return [...names];
+}
+/** Every trigger name a graph's transitions listen for, in first-seen order. */
+export function graphTriggers(graph) {
+    const names = new Set();
+    for (const layer of graph.layers)
+        for (const transition of layer.transitions)
+            if (transition.trigger !== undefined)
+                names.add(transition.trigger);
+    return [...names];
+}
+/** Parameters a graph reads, with a range covering its blend points and condition values. */
+export function graphParamControls(graph) {
+    const controls = new Map();
+    const widen = (name, value) => {
+        const kind = typeof value === "boolean" ? "boolean" : "number";
+        const current = controls.get(name) ?? { name, kind, min: 0, max: 1 };
+        if (kind === "number") {
+            current.min = Math.min(current.min, value);
+            current.max = Math.max(current.max, value * 1.25, value + 0.5);
+        }
+        controls.set(name, current);
+    };
+    for (const layer of graph.layers) {
+        for (const state of Object.values(layer.states)) {
+            if (state.kind === "blend1D")
+                for (const point of state.points)
+                    widen(state.param, point.at);
+            if (state.kind === "blend2D") {
+                for (const point of state.points) {
+                    widen(state.params[0], point.at[0]);
+                    widen(state.params[1], point.at[1]);
+                }
+            }
+        }
+        for (const transition of layer.transitions)
+            for (const condition of transition.when ?? [])
+                widen(condition.param, condition.value);
+    }
+    return [...controls.values()];
+}
+/** Adds a trigger press at `at`, keeping the log in time order. */
+export function recordTrigger(triggers, name, at) {
+    return [...triggers, { at, name }].sort((a, b) => a.at - b.at);
+}

package/dist/shell/clipPreview.d.ts

@@ -1,3 +1,4 @@
+import type { AnimClipOutput, AnimGraph } from "@jgengine/core/anim/animGraph";
 import { type ClipRole } from "@jgengine/core/game/clipRoles";
 import type { ModelAnimationConfig } from "@jgengine/core/game/playableGame";
 /**
@@ -39,6 +40,14 @@ export interface ClipPreviewSession {
     readonly source: ClipPreviewSource;
     readonly driver: ClipPreviewState;
     readonly duration: number;
+    /** Every clip's duration, published by the viewport layer once the GLB loads. */
+    readonly clipDurations?: Readonly<Record<string, number>>;
+    /** When set, the viewport poses the rig from this graph output instead of playing `driver`'s clip. */
+    readonly graphPose?: {
+        readonly graph: AnimGraph;
+        readonly clips: readonly AnimClipOutput[];
+        readonly rootMotion?: true;
+    };
 }
 /** Playback state of the clip preview driver. `time` is seconds into the clip. */
 export interface ClipPreviewState {

package/dist/useDocumentSave.d.ts

@@ -0,0 +1,20 @@
+import type { EditorSession } from "@jgengine/core/editor/commands";
+/** Document save lifecycle owned by the mounted authoring session, across viewport modes. */
+export interface EditorDocumentSave {
+    available: boolean;
+    dirty: boolean;
+    saveState: "idle" | "saving" | "saved" | "error";
+    saveError: string | null;
+    lastSavedAt: number | null;
+    doSave(): void;
+}
+/** Save status shared with editor chrome without changing the viewport component identity. @internal */
+export declare const EditorDocumentSaveContext: import("react").Context<EditorDocumentSave | undefined>;
+type SaveFn = (json: string) => Promise<{
+    ok: boolean;
+    path?: string;
+    error?: string;
+}>;
+/** Keep the acknowledged document and pending/error status alive while editor chrome unmounts. @internal */
+export declare function useDocumentSave(session: EditorSession, save: SaveFn | undefined, onResult?: (ok: boolean, detail: string) => void): EditorDocumentSave;
+export {};