@jgengine/editor 0.18.1 → 0.21.0

package/dist/modelAnimationAuthoring.d.ts

@@ -1,3 +1,5 @@
+import type { AnimGraph } from "@jgengine/core/anim/animGraph";
+import { type AuthoredAnimationDiagnostic, type AuthoredAnimationDocumentLike } from "@jgengine/core/world/authoredAnimation";
 /**
  * Authoring model for a placement's `ModelConfig.animation`, persisted on a marker's `meta.animation`
  * and consumed by the shell exactly like a game-authored config. Pure data + reducers, no JSX — the
@@ -38,18 +40,29 @@ export interface AuthoredAnimationStates {
 }
 /** Structurally compatible with `ModelAnimationConfig`, but every field optional for authoring. */
 export interface AuthoredAnimationConfig {
+    auto?: true;
+    clock?: "real" | "game";
     clip?: string;
     loop?: boolean;
     timeScale?: number;
+    paused?: boolean;
+    time?: number;
     states?: AuthoredAnimationStates;
-    oneShots?: Record<string, string>;
+    oneShots?: Record<string, string | readonly string[]>;
+    /** A stored animation graph; takes over from `states`/`oneShots` at play time. */
+    graph?: AnimGraph;
 }
 /** The value stored at `meta.animation`. */
 export type AnimationSetting = AuthoredAnimationConfig | "auto" | "none";
 /** Which authoring mode a stored setting represents. `default` = no override key. */
 export type AnimationMode = "default" | "auto" | "none" | "custom";
-/** 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 declare function readAnimationSetting(meta: Record<string, unknown> | undefined): AnimationSetting | undefined;
+/** Validates a placement's animation with its saved-document repair locations. @internal */
+export declare function readAnimationSettingResult(document: AuthoredAnimationDocumentLike, markerId: string): {
+    setting: AnimationSetting | undefined;
+    diagnostics: readonly AuthoredAnimationDiagnostic[];
+};
 /** The authoring mode a stored setting maps to. */
 export declare function animationMode(setting: AnimationSetting | undefined): AnimationMode;
 /**
@@ -61,11 +74,21 @@ export declare function setAnimationMode(setting: AnimationSetting | undefined,
 /** A concrete custom config derived from a rigged asset's clip roles — the `custom` mode seed. */
 export declare function defaultCustomConfig(clips: readonly string[]): AuthoredAnimationConfig;
 /** Sets or clears (null) a locomotion state clip; forces the setting into `custom`. */
-export declare function setLocomotionClip(setting: AnimationSetting | undefined, role: LocomotionRole, clipName: string | null): AuthoredAnimationConfig;
+export declare function setLocomotionClip(setting: AnimationSetting | undefined, role: LocomotionRole, clipName: string | null, clips?: readonly string[]): AuthoredAnimationConfig;
 /** Sets or clears (null) a numeric locomotion tuning. */
-export declare function setLocomotionNumber(setting: AnimationSetting | undefined, key: LocomotionNumber, value: number | null): AuthoredAnimationConfig;
-/** Binds or clears (null) a one-shot event to a clip. */
-export declare function setOneShotClip(setting: AnimationSetting | undefined, event: string, clipName: string | null): AuthoredAnimationConfig;
+export declare function setLocomotionNumber(setting: AnimationSetting | undefined, key: LocomotionNumber, value: number | null, clips?: readonly string[]): AuthoredAnimationConfig;
+/** Binds or clears (null) a one-shot event's clip or variant list. */
+export declare function setOneShotClip(setting: AnimationSetting | undefined, event: string, clipName: string | readonly string[] | null): AuthoredAnimationConfig;
+/** Sets a single playback clip, explicitly replacing speed-driven states and a stored graph. @internal */
+export declare function setPlaybackClip(setting: AnimationSetting | undefined, clip: string | null): AuthoredAnimationConfig;
+/** Changes a playback scalar while preserving role mappings, variants and the stored graph. @internal */
+export declare function setPlaybackNumber(setting: AnimationSetting | undefined, key: "time" | "timeScale", value: number | null): AuthoredAnimationConfig;
+/** Chooses the playback clock without replacing mappings, graph, or other authored fields. @internal */
+export declare function setPlaybackClock(setting: AnimationSetting | undefined, clock: "real" | "game"): AuthoredAnimationConfig;
+/** Requests loaded-rig role inference, or removes that request, retaining explicit overrides whole. @internal */
+export declare function setAutomaticRoles(setting: AnimationSetting | undefined, derive: boolean): AuthoredAnimationConfig;
+/** Changes a playback toggle without replacing the remaining authored settings. @internal */
+export declare function setPlaybackBoolean(setting: AnimationSetting | undefined, key: "paused" | "loop", value: boolean): AuthoredAnimationConfig;
 /**
  * The meta patch that persists a setting (or clears the override when undefined). Shallow-merges onto
  * `marker.meta` via `setMarker`; an undefined value drops out of the saved JSON document.
@@ -73,3 +96,23 @@ export declare function setOneShotClip(setting: AnimationSetting | undefined, ev
 export declare function animationMetaPatch(setting: AnimationSetting | undefined): {
     animation: AnimationSetting | undefined;
 };
+/** Where the graph a placement plays comes from. */
+export type AnimGraphSource = "authored" | "locomotion" | "auto";
+/**
+ * The graph a placement plays at run time: its stored `graph`, else the locomotion graph of its
+ * custom `states`/`oneShots`, else the one clip roles derive for `"auto"` and no-override placements.
+ * `null` for `"none"`, a single-clip config, or a rig whose clips have no idle.
+ */
+export declare function effectiveAnimGraph(setting: AnimationSetting | undefined, clips: readonly string[]): {
+    graph: AnimGraph;
+    source: AnimGraphSource;
+} | null;
+/** Stores `graph` on the placement, keeping its other fields; the stored graph wins at play time. */
+export declare function storeAnimGraph(setting: AnimationSetting | undefined, graph: AnimGraph): AuthoredAnimationConfig;
+/** Removes a stored graph so `states`/`oneShots` (or clip roles) drive the placement again. */
+export declare function clearAnimGraph(setting: AnimationSetting | undefined): AnimationSetting | undefined;
+/**
+ * Sets one transition's crossfade seconds in `graph` and stores the result, so editing a derived
+ * graph turns it into an authored one.
+ */
+export declare function setTransitionDuration(setting: AnimationSetting | undefined, graph: AnimGraph, layerId: string, index: number, duration: number): AuthoredAnimationConfig;

package/dist/modelAnimationAuthoring.js

@@ -1,4 +1,6 @@
-import { rolesFromClips } from "@jgengine/core/game/clipRoles";
+import { readAuthoredAnimation } from "@jgengine/core/world/authoredAnimation";
+import { animGraphFromConfig } from "@jgengine/core/anim/locomotionGraph";
+import { resolveAnimationConfig, rolesFromClips } from "@jgengine/core/game/clipRoles";
 /**
  * Authoring model for a placement's `ModelConfig.animation`, persisted on a marker's `meta.animation`
  * and consumed by the shell exactly like a game-authored config. Pure data + reducers, no JSX — the
@@ -22,48 +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;
-    }
-    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) {
@@ -78,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
@@ -100,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) {
@@ -114,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)
@@ -126,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
@@ -162,3 +160,59 @@ export function setOneShotClip(setting, event, clipName) {
 export function animationMetaPatch(setting) {
     return { animation: setting };
 }
+/**
+ * The graph a placement plays at run time: its stored `graph`, else the locomotion graph of its
+ * custom `states`/`oneShots`, else the one clip roles derive for `"auto"` and no-override placements.
+ * `null` for `"none"`, a single-clip config, or a rig whose clips have no idle.
+ */
+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 || states.idle.trim().length === 0)
+            return null;
+        const graph = animGraphFromConfig({
+            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" };
+    }
+    const resolved = resolveAnimationConfig("auto", clips);
+    const graph = resolved === undefined ? undefined : animGraphFromConfig(resolved);
+    return graph === undefined ? null : { graph, source: "auto" };
+}
+/** Stores `graph` on the placement, keeping its other fields; the stored graph wins at play time. */
+export function storeAnimGraph(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;
+    return Object.keys(rest).length === 0 ? undefined : rest;
+}
+/**
+ * Sets one transition's crossfade seconds in `graph` and stores the result, so editing a derived
+ * graph turns it into an authored one.
+ */
+export function setTransitionDuration(setting, graph, layerId, index, duration) {
+    const next = {
+        ...graph,
+        layers: graph.layers.map((layer) => layer.id !== layerId
+            ? layer
+            : {
+                ...layer,
+                transitions: layer.transitions.map((transition, i) => i === index ? { ...transition, duration: Math.max(0, Number.isFinite(duration) ? duration : 0) } : transition),
+            }),
+    };
+    return storeAnimGraph(setting, next);
+}

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 */
@@ -105,6 +109,7 @@ export type EditorBridgeRequest = {
     color?: string;
     label?: string;
     rotationY?: number;
+    catalogId?: string;
     meta?: Record<string, unknown>;
 } | {
     method: "set_marker";
@@ -113,6 +118,7 @@ export type EditorBridgeRequest = {
     color?: string;
     label?: string;
     rotationY?: number;
+    catalogId?: string;
     meta?: Record<string, unknown>;
 } | {
     method: "set_note";
@@ -150,6 +156,11 @@ export type EditorBridgeRequest = {
     height?: number;
 } | {
     method: "scene_summary";
+} | {
+    method: "get_simulation";
+} | {
+    method: "set_simulation";
+    simulation: EditorSimulation | null;
 } | {
     method: "export_document";
 } | {
@@ -292,6 +303,10 @@ export type EditorBridgeRequest = {
 } | {
     method: "delete_prefab";
     prefabId: string;
+} | {
+    method: "set_prefab_static_bake";
+    prefabId: string;
+    bake: StaticPrefabBake | null;
 } | {
     method: "list_collections";
 } | {
@@ -338,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[];
@@ -496,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 {
     /**
@@ -573,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;
@@ -584,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. */
@@ -609,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,6 +1,7 @@
-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";
 import { emitEditorConsole } from "./shell/consoleSink.js";
 registerBuiltinSceneKinds();
 /** The accepted run modes, in canonical order — the runtime guard behind {@link EditorRunMode}. @internal */
@@ -22,11 +23,19 @@ export function getEditorHost() {
 }
 /** Builds and installs an editor host for a game: session, visibility, assets, and RPC handling. @internal */
 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)
@@ -37,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();
@@ -70,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 };
@@ -99,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,
@@ -110,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);
@@ -155,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])),
@@ -179,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.d.ts

@@ -0,0 +1,16 @@
+import type { EditorSession } from "@jgengine/core/editor/index";
+import type { EditorAssetEntry } from "../AssetBrowser.js";
+import type { EditorUiStore } from "../uiStore.js";
+/**
+ * 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 declare function AnimationGraphPanel({ session, ui, rigged, }: {
+    session: EditorSession;
+    ui: EditorUiStore;
+    rigged: readonly EditorAssetEntry[];
+}): import("react").JSX.Element;