@jgengine/editor 0.19.0 → 0.22.0

package/dist/modelAnimationAuthoring.js

@@ -1,4 +1,4 @@
-import { parseAnimGraph } from "@jgengine/core/anim/animGraph";
+import { readAuthoredAnimation } from "@jgengine/core/world/authoredAnimation";
 import { animGraphFromConfig } from "@jgengine/core/anim/locomotionGraph";
 import { resolveAnimationConfig, rolesFromClips } from "@jgengine/core/game/clipRoles";
 /**
@@ -24,51 +24,14 @@ export const LOCOMOTION_NUMBERS = ["walkSpeed", "runSpeed", "fadeSec"];
  * `combat.hitReaction` / `entity.died`; the rest fire when the game calls `playEntityAnimation`.
  */
 export const ONE_SHOT_EVENTS = ["attack", "hit", "death", "jump", "interact", "cheer"];
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-/** Reads and shape-validates the animation override from a marker's meta; undefined when absent/invalid. */
+/** Reads a whole valid override, retaining authored fields; malformed values return undefined. */
 export function readAnimationSetting(meta) {
-    const value = meta?.["animation"];
-    if (value === "auto" || value === "none")
-        return value;
-    if (!isRecord(value))
-        return undefined;
-    const config = {};
-    if (typeof value["clip"] === "string")
-        config.clip = value["clip"];
-    if (typeof value["loop"] === "boolean")
-        config.loop = value["loop"];
-    if (typeof value["timeScale"] === "number")
-        config.timeScale = value["timeScale"];
-    if (isRecord(value["states"])) {
-        const raw = value["states"];
-        const states = {};
-        for (const role of LOCOMOTION_ROLES)
-            if (typeof raw[role] === "string")
-                states[role] = raw[role];
-        for (const key of LOCOMOTION_NUMBERS)
-            if (typeof raw[key] === "number")
-                states[key] = raw[key];
-        if (Object.keys(states).length > 0)
-            config.states = states;
-    }
-    if (isRecord(value["oneShots"])) {
-        const raw = value["oneShots"];
-        const oneShots = {};
-        for (const [event, clip] of Object.entries(raw)) {
-            if (typeof clip === "string")
-                oneShots[event] = clip;
-            else if (Array.isArray(clip) && typeof clip[0] === "string")
-                oneShots[event] = clip[0];
-        }
-        if (Object.keys(oneShots).length > 0)
-            config.oneShots = oneShots;
-    }
-    const graph = parseAnimGraph(value["graph"]);
-    if (graph !== undefined)
-        config.graph = graph;
-    return config;
+    return readAnimationSettingResult({ markers: [{ id: "animation", meta }] }, "animation").setting;
+}
+/** Validates a placement's animation with its saved-document repair locations. @internal */
+export function readAnimationSettingResult(document, markerId) {
+    const result = readAuthoredAnimation(document, markerId);
+    return { setting: result.animation, diagnostics: result.diagnostics };
 }
 /** The authoring mode a stored setting maps to. */
 export function animationMode(setting) {
@@ -83,14 +46,6 @@ export function animationMode(setting) {
 function asConfig(setting) {
     return setting !== undefined && setting !== "auto" && setting !== "none" ? setting : {};
 }
-function normalizeConfig(config) {
-    const next = { ...config };
-    if (next.states !== undefined && Object.keys(next.states).length === 0)
-        delete next.states;
-    if (next.oneShots !== undefined && Object.keys(next.oneShots).length === 0)
-        delete next.oneShots;
-    return next;
-}
 /**
  * Switches authoring mode. `custom` seeds from the asset's clip-role defaults (so the user starts from
  * a working config, then overrides) when there is no existing object config; the other modes are the
@@ -105,7 +60,7 @@ export function setAnimationMode(setting, mode, clips = []) {
         return "none";
     if (setting !== undefined && setting !== "auto" && setting !== "none")
         return setting;
-    return normalizeConfig(defaultCustomConfig(clips));
+    return defaultCustomConfig(clips);
 }
 /** A concrete custom config derived from a rigged asset's clip roles — the `custom` mode seed. */
 export function defaultCustomConfig(clips) {
@@ -119,9 +74,9 @@ export function defaultCustomConfig(clips) {
         states.run = roles.run[0];
     const oneShots = {};
     for (const event of ONE_SHOT_EVENTS) {
-        const variant = roles[event]?.[0];
-        if (variant !== undefined)
-            oneShots[event] = variant;
+        const variants = roles[event];
+        if (variants !== undefined && variants.length > 0)
+            oneShots[event] = variants.length === 1 ? variants[0] : [...variants];
     }
     const config = {};
     if (Object.keys(states).length > 0)
@@ -131,34 +86,72 @@ export function defaultCustomConfig(clips) {
     return config;
 }
 /** Sets or clears (null) a locomotion state clip; forces the setting into `custom`. */
-export function setLocomotionClip(setting, role, clipName) {
+export function setLocomotionClip(setting, role, clipName, clips = []) {
     const config = asConfig(setting);
-    const states = { ...config.states };
+    const states = { ...(config.states ?? (clipName === null ? undefined : defaultCustomConfig(clips).states)) };
     if (clipName === null)
         delete states[role];
     else
         states[role] = clipName;
-    return normalizeConfig({ ...config, states });
+    return { ...config, ...(config.states !== undefined || Object.keys(states).length > 0 ? { states } : {}) };
 }
 /** Sets or clears (null) a numeric locomotion tuning. */
-export function setLocomotionNumber(setting, key, value) {
+export function setLocomotionNumber(setting, key, value, clips = []) {
     const config = asConfig(setting);
-    const states = { ...config.states };
+    const states = { ...(config.states ?? (value === null || !Number.isFinite(value) ? undefined : defaultCustomConfig(clips).states)) };
     if (value === null || !Number.isFinite(value))
         delete states[key];
     else
         states[key] = value;
-    return normalizeConfig({ ...config, states });
+    return { ...config, ...(config.states !== undefined || Object.keys(states).length > 0 ? { states } : {}) };
 }
-/** Binds or clears (null) a one-shot event to a clip. */
+/** Binds or clears (null) a one-shot event's clip or variant list. */
 export function setOneShotClip(setting, event, clipName) {
     const config = asConfig(setting);
     const oneShots = { ...config.oneShots };
-    if (clipName === null)
+    if (clipName === null || (Array.isArray(clipName) && clipName.length === 0))
         delete oneShots[event];
     else
-        oneShots[event] = clipName;
-    return normalizeConfig({ ...config, oneShots });
+        oneShots[event] = typeof clipName === "string" ? clipName : clipName.length === 1 ? clipName[0] : [...clipName];
+    const next = { ...config, oneShots };
+    if (Object.keys(oneShots).length === 0)
+        delete next.oneShots;
+    return next;
+}
+/** Sets a single playback clip, explicitly replacing speed-driven states and a stored graph. @internal */
+export function setPlaybackClip(setting, clip) {
+    if (clip === null) {
+        const { clip: _clip, ...config } = asConfig(setting);
+        return config;
+    }
+    const { states: _states, graph: _graph, auto: _auto, ...config } = asConfig(setting);
+    return { ...config, clip };
+}
+/** Changes a playback scalar while preserving role mappings, variants and the stored graph. @internal */
+export function setPlaybackNumber(setting, key, value) {
+    const config = { ...asConfig(setting) };
+    if (value === null || !Number.isFinite(value))
+        delete config[key];
+    else
+        config[key] = key === "time" ? Math.max(0, value) : value;
+    return config;
+}
+/** Chooses the playback clock without replacing mappings, graph, or other authored fields. @internal */
+export function setPlaybackClock(setting, clock) {
+    return { ...(setting === "auto" ? { auto: true } : asConfig(setting)), clock };
+}
+/** Requests loaded-rig role inference, or removes that request, retaining explicit overrides whole. @internal */
+export function setAutomaticRoles(setting, derive) {
+    const config = { ...asConfig(setting) };
+    if (derive)
+        config.auto = true;
+    else
+        delete config.auto;
+    return config;
+}
+/** Changes a playback toggle without replacing the remaining authored settings. @internal */
+export function setPlaybackBoolean(setting, key, value) {
+    return { ...asConfig(setting), [key]: value };
 }
 /**
  * The meta patch that persists a setting (or clears the override when undefined). Shallow-merges onto
@@ -175,14 +168,19 @@ export function animationMetaPatch(setting) {
 export function effectiveAnimGraph(setting, clips) {
     if (setting === "none")
         return null;
+    if (setting !== undefined && setting !== "auto" && setting.auto === true) {
+        const resolved = resolveAnimationConfig(setting, clips);
+        const graph = resolved === undefined ? undefined : animGraphFromConfig(resolved);
+        return graph === undefined ? null : { graph, source: setting.graph !== undefined ? "authored" : setting.states !== undefined ? "locomotion" : "auto" };
+    }
     if (setting !== undefined && setting !== "auto") {
         if (setting.graph !== undefined)
             return { graph: setting.graph, source: "authored" };
         const states = setting.states;
-        if (states?.idle === undefined)
+        if (states?.idle === undefined || states.idle.trim().length === 0)
             return null;
         const graph = animGraphFromConfig({
-            states: { ...states, idle: states.idle, walk: states.walk ?? states.idle },
+            states: { ...states, idle: states.idle, walk: states.walk === undefined || states.walk.trim().length === 0 ? states.idle : states.walk },
             ...(setting.oneShots === undefined ? {} : { oneShots: setting.oneShots }),
         });
         return graph === undefined ? null : { graph, source: "locomotion" };
@@ -193,15 +191,14 @@ export function effectiveAnimGraph(setting, clips) {
 }
 /** Stores `graph` on the placement, keeping its other fields; the stored graph wins at play time. */
 export function storeAnimGraph(setting, graph) {
-    return normalizeConfig({ ...asConfig(setting), graph });
+    return { ...asConfig(setting), graph };
 }
 /** Removes a stored graph so `states`/`oneShots` (or clip roles) drive the placement again. */
 export function clearAnimGraph(setting) {
     if (setting === undefined || setting === "auto" || setting === "none")
         return setting;
     const { graph: _graph, ...rest } = setting;
-    const next = normalizeConfig(rest);
-    return Object.keys(next).length === 0 ? undefined : next;
+    return Object.keys(rest).length === 0 ? undefined : rest;
 }
 /**
  * Sets one transition's crossfade seconds in `graph` and stores the result, so editing a derived

package/dist/session.d.ts

@@ -1,7 +1,11 @@
+import type { EditorSimulation } from "@jgengine/core/editor/simulation";
+import type { MaterialAsset, MaterialSelector } from "@jgengine/core/material/materialAsset";
+import type { StaticPrefabBake } from "@jgengine/core/editor/staticPrefab";
 import { type DocumentLiveSync, type DocumentPatch, type EditorCatalogDefinition, type EditorCommand, type EditorDocument, type EditorGridPaletteEntry, type EditorKindVisibility, type EditorLayersInput, type EditorSession, type EditorSessionState, type RuntimeEntityState, type RuntimePlayControl } from "@jgengine/core/editor/index";
 import type { TerraformMode, TerrainMaterialLayer } from "@jgengine/core/world/terraform";
 import type { ParamSchema } from "@jgengine/core/scene/sceneKinds";
 import type { TerrainField } from "@jgengine/core/world/terrain";
+import type { ModelMaterialSlotInfo } from "@jgengine/shell/render/materialAsset";
 /** How the editor hosts the game: frozen placement view, roamable world, the real game, or HUD-layout authoring. */
 export type EditorRunMode = "edit" | "walk" | "play" | "hud";
 /** The accepted run modes, in canonical order — the runtime guard behind {@link EditorRunMode}. @internal */
@@ -152,6 +156,11 @@ export type EditorBridgeRequest = {
     height?: number;
 } | {
     method: "scene_summary";
+} | {
+    method: "get_simulation";
+} | {
+    method: "set_simulation";
+    simulation: EditorSimulation | null;
 } | {
     method: "export_document";
 } | {
@@ -294,6 +303,10 @@ export type EditorBridgeRequest = {
 } | {
     method: "delete_prefab";
     prefabId: string;
+} | {
+    method: "set_prefab_static_bake";
+    prefabId: string;
+    bake: StaticPrefabBake | null;
 } | {
     method: "list_collections";
 } | {
@@ -340,6 +353,26 @@ export type EditorBridgeRequest = {
     color?: string;
     label?: string;
     meta?: Record<string, unknown>;
+} | {
+    method: "list_material_assets";
+} | {
+    method: "list_material_slots";
+    id: string;
+} | {
+    method: "upsert_material_asset";
+    asset: MaterialAsset;
+    coalesce?: string;
+} | {
+    method: "remove_material_asset";
+    id: string;
+} | {
+    method: "assign_material_asset";
+    ids: string[];
+    materialId: string;
+    selector: MaterialSelector;
+} | {
+    method: "clear_material_assets";
+    ids: string[];
 } | {
     method: "assign_material";
     ids: string[];
@@ -498,6 +531,25 @@ export interface EditorAssetInfo {
     kind: string;
     url?: string;
 }
+/** Canonical imported slot names and mesh prerequisites reported by the loaded model. */
+export type EditorMaterialSlotInfo = Readonly<Omit<ModelMaterialSlotInfo, "uvSets">> & {
+    readonly uvSets: readonly number[];
+};
+/** A live model-source observation; loading and unavailable reports never contain fabricated slots. */
+export type EditorMaterialSlotReport = {
+    status: "ready";
+    slots: readonly EditorMaterialSlotInfo[];
+} | {
+    status: "loading";
+} | {
+    status: "unavailable";
+    reason: string;
+};
+/** A marker's current imported-model inventory, including an explicit availability state. */
+export type EditorMaterialSlotInventory = EditorMaterialSlotReport & {
+    id: string;
+    sourceUrl?: string;
+};
 /** Rolling frame-rate sample published by the in-canvas PerfProbe. */
 export interface EditorPerfSample {
     /**
@@ -575,6 +627,10 @@ export interface EditorHostApi {
     subscribeFocus(listener: (target: EditorFocusTarget | null) => void): () => void;
     getAssets(): readonly EditorAssetInfo[];
     setAssets(assets: readonly EditorAssetInfo[]): void;
+    /** Read observed slot data for the marker's current model URL; headless or unloaded sources are unavailable. */
+    getMaterialSlots(id: string): EditorMaterialSlotInventory;
+    /** Publish a loaded-model observation only while its marker still resolves to this source URL. */
+    reportMaterialSlots(id: string, sourceUrl: string, report: EditorMaterialSlotReport): boolean;
     getCatalogDefinitions(): readonly EditorCatalogDefinition[];
     getPerf(): EditorPerfSample | null;
     setPerf(sample: EditorPerfSample): void;
@@ -586,6 +642,8 @@ export interface EditorHostApi {
     getTerrainSampler(): TerrainField | null;
     setTerrainSampler(field: TerrainField | null): void;
     getMode(): EditorRunMode;
+    /** Immutable authored snapshot captured on entering an isolated playtest. */
+    getPlayDocument(): EditorDocument | null;
     setMode(mode: EditorRunMode): void;
     subscribeMode(listener: (mode: EditorRunMode) => void): () => void;
     /** Play-mode pause/step gate consumed by the runtime publisher. */
@@ -611,6 +669,10 @@ export declare function createEditorHost(options: {
         y: number;
         z: number;
     } | null) => void;
+    validateDocument?: (document: EditorDocument) => void;
+    isolatedPlaytest?: boolean;
+    publishGlobal?: boolean;
+    persistAssetUrls?: boolean;
 }): {
     session: EditorSession;
     api: EditorHostApi;

package/dist/session.js

@@ -1,4 +1,4 @@
-import { createDocumentLiveSync, createEditorSession, createRuntimePlayControl, installDocumentLiveSync, listEditorKinds, normalizeEditorLayers, resolveCatalogDefinitions, seedEditorCatalogs, } from "@jgengine/core/editor/index";
+import { createDocumentLiveSync, cloneEditorDocument, createEditorSession, createRuntimePlayControl, installDocumentLiveSync, listEditorKinds, normalizeEditorLayers, resolveCatalogDefinitions, seedEditorCatalogs, } from "@jgengine/core/editor/index";
 import { registerBuiltinSceneKinds } from "@jgengine/core/scene/builtinSceneKinds";
 import { EDITOR_RPC_HANDLERS } from "./handlers/index.js";
 import { warmNavBake } from "./handlers/navmesh.js";
@@ -26,9 +26,16 @@ export function createEditorHost(options) {
     warmNavBake();
     const catalogDefinitions = options.catalogs ?? [];
     const document = seedEditorCatalogs(normalizeEditorLayers(options.layers), catalogDefinitions);
-    const session = createEditorSession(document);
+    let mode = "edit";
+    const session = createEditorSession(document, 100, (candidate) => {
+        if (options.isolatedPlaytest && mode === "play")
+            throw new Error("Return to editor before changing the authored scene");
+        options.validateDocument?.(candidate);
+    });
     const liveSync = createDocumentLiveSync(document);
-    const uninstallLiveSync = installDocumentLiveSync(liveSync);
+    let uninstallLiveSync = installDocumentLiveSync(liveSync);
+    let playDocument = null;
+    let playSync = null;
     let lastMirroredDocument = session.getState().document;
     const unsubscribeSessionMirror = session.subscribe((state) => {
         if (state.document === lastMirroredDocument)
@@ -39,9 +46,17 @@ export function createEditorHost(options) {
     let visibility = {};
     let focusTarget = null;
     let assets = [...(options.assets ?? [])];
+    const materialSlotReports = new Map();
+    const materialSource = (id) => {
+        const marker = session.getState().document.markers.find((item) => item.id === id);
+        if (!marker)
+            return { reason: `No authored model marker ${id}.` };
+        const catalogId = marker.catalogId ?? marker.meta?.catalogId;
+        const sourceUrl = assets.find((asset) => asset.id === catalogId)?.url;
+        return sourceUrl ? { sourceUrl } : { reason: `Marker ${id} has no URL-backed catalog model.` };
+    };
     let perf = null;
     let terrainSampler = null;
-    let mode = "edit";
     let playControl = createRuntimePlayControl(false);
     const visibilityListeners = new Set();
     const focusListeners = new Set();
@@ -72,7 +87,7 @@ export function createEditorHost(options) {
     const api = {
         gameId: options.gameId,
         getSession: () => session,
-        getLiveSync: () => liveSync,
+        getLiveSync: () => playSync ?? liveSync,
         getVisibility: () => visibility,
         setVisibility(next) {
             visibility = { ...next };
@@ -101,6 +116,31 @@ export function createEditorHost(options) {
         getAssets: () => assets,
         setAssets(next) {
             assets = [...next];
+            for (const [id, inventory] of materialSlotReports) {
+                if (materialSource(id).sourceUrl !== inventory.sourceUrl)
+                    materialSlotReports.delete(id);
+            }
+        },
+        getMaterialSlots(id) {
+            const source = materialSource(id);
+            const inventory = materialSlotReports.get(id);
+            if (source.sourceUrl === undefined || inventory?.sourceUrl !== source.sourceUrl) {
+                materialSlotReports.delete(id);
+                return { id, ...source, status: "unavailable", reason: source.reason ?? "This model has no loaded slot inventory. Select it and open the Materials workspace." };
+            }
+            return structuredClone(inventory);
+        },
+        reportMaterialSlots(id, sourceUrl, report) {
+            if (materialSource(id).sourceUrl !== sourceUrl)
+                return false;
+            const previous = materialSlotReports.get(id);
+            if (previous?.sourceUrl === sourceUrl && previous.status !== "loading" && report.status === "loading")
+                return true;
+            materialSlotReports.delete(id);
+            materialSlotReports.set(id, structuredClone({ ...report, id, sourceUrl }));
+            if (materialSlotReports.size > 64)
+                materialSlotReports.delete(materialSlotReports.keys().next().value);
+            return true;
         },
         getCatalogDefinitions: () => resolveCatalogDefinitions(session.getState().document, catalogDefinitions),
         getPerf: () => perf,
@@ -112,9 +152,16 @@ export function createEditorHost(options) {
             terrainSampler = field;
         },
         getMode: () => mode,
+        getPlayDocument: () => playDocument === null ? null : cloneEditorDocument(playDocument),
         setMode(next) {
             if (next === mode)
                 return;
+            if (options.isolatedPlaytest) {
+                uninstallLiveSync();
+                playDocument = next === "play" ? cloneEditorDocument(session.getState().document) : null;
+                playSync = playDocument === null ? null : createDocumentLiveSync(playDocument);
+                uninstallLiveSync = installDocumentLiveSync(playSync ?? liveSync);
+            }
             mode = next;
             if (next === "play") {
                 playControl = createRuntimePlayControl(false);
@@ -157,7 +204,8 @@ export function createEditorHost(options) {
             const ctx = {
                 api,
                 session,
-                liveSync,
+                liveSync: playSync ?? liveSync,
+                persistAssetUrls: options.persistAssetUrls,
                 gameId: options.gameId,
                 catalogDefinitions: defs,
                 catalogById: new Map(defs.map((definition) => [definition.id, definition])),
@@ -181,8 +229,9 @@ export function createEditorHost(options) {
             }
         },
     };
-    const uninstallHost = installEditorHost(api);
+    const uninstallHost = options.publishGlobal === false ? () => { } : installEditorHost(api);
     const dispose = () => {
+        materialSlotReports.clear();
         unsubscribeSessionMirror();
         uninstallLiveSync();
         uninstallHost();

package/dist/shell/AnimationGraphPanel.js

@@ -1,7 +1,7 @@
 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, readAnimationSetting, setTransitionDuration, storeAnimGraph, } from "../modelAnimationAuthoring.js";
+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";
@@ -38,6 +38,8 @@ export function AnimationGraphPanel({ session, ui, rigged, }) {
             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)
@@ -51,9 +53,11 @@ export function AnimationGraphPanel({ session, ui, rigged, }) {
     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 setting = readAnimationSetting(marker.meta);
-    const effective = useMemo(() => effectiveAnimGraph(setting, clips), [JSON.stringify(setting), clips]);
+    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]);
@@ -61,6 +65,8 @@ function GraphInspector({ session, ui, marker, asset, }) {
     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)
@@ -71,7 +77,7 @@ function GraphInspector({ session, ui, marker, asset, }) {
         return simulateGraphPreview({ graph, durations: durations ?? {}, time, params: merged, triggers });
     }, [graph, controls, params, triggers, time, durations]);
     useEffect(() => {
-        if (asset.url === undefined)
+        if (asset?.url === undefined)
             return;
         const current = ui.getState().clipPreview;
         const sameAsset = current?.source.assetId === asset.id;
@@ -87,18 +93,18 @@ function GraphInspector({ session, ui, marker, asset, }) {
             if (ui.getState().clipPreview?.source.assetId === asset.id)
                 ui.patch({ clipPreview: null });
         };
-    }, [asset.id, asset.url, asset.label, clips, ui]);
+    }, [asset?.id, asset?.url, asset?.label, clips, ui]);
     useEffect(() => {
         const current = ui.getState().clipPreview;
-        if (current === null || current.source.assetId !== asset.id)
+        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 } } });
-    }, [graph, frame, asset.id, ui, durations]);
+        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(() => {
@@ -121,7 +127,9 @@ function GraphInspector({ session, ui, marker, asset, }) {
         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 (graph === null || effective === null || frame === null) {
+    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]));

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"] }) })] }));
 }