@vgai/editor 0.2.0

package/src/editor-store.ts

@@ -0,0 +1,2225 @@
+/**
+ * EditorStore — central editor state backed by the Three.js scene graph.
+ *
+ * The scene graph (THREE.Scene) is the single source of truth for entity data.
+ * Each entity Object3D carries its full SceneEntity descriptor in
+ * `userData['entity']`. The store reads from and writes to these descriptors,
+ * and triggers per-entity Three.js rebuilds when properties change.
+ *
+ * Full scene rebuilds (clearPreview + buildPreview) only happen on:
+ *   - Scene load
+ *   - Undo / redo
+ *   - Prefab resolution
+ *   - Asset path rename
+ */
+
+import type { PersistenceProvider } from '@engine/adapter';
+import { applyAssetRename } from '@engine/scene/asset-paths';
+import {
+  mergePrefabInstance,
+  type PrefabFile,
+  type SceneEntity,
+  type SceneEnvironment,
+  type SceneFile,
+} from '@engine/scene/scene-types';
+import { getUserData, setUserData } from '@engine/scene/user-data';
+import * as THREE from 'three';
+import type { BatchedRenderer } from 'three.quarks';
+import {
+  activeOverrideIsEditMode,
+  getActiveAuthoring,
+  hasAuthoringOverride,
+} from './authoring/active-adapter';
+import { notifyUndoableOp, registerUndoAdapter } from './authoring/undo-timeline';
+import { loadEditorState, saveEditorState, saveFile, saveThumbnail } from './editor-api';
+import { createEntityObject } from './entity-factory';
+import { diffScene } from './scene-diff';
+import type { SceneMetadata } from './scene-serializer';
+import { cleanDocument, serializeScene } from './scene-serializer';
+import {
+  applyEnvironment,
+  applyShadingOverride,
+  buildPreview,
+  registerParticles,
+  unregisterParticles,
+  updateEntityPreview,
+} from './scene-sync';
+
+/** Like Partial but explicitly allows setting fields to undefined (to clear them). */
+export type EntityUpdate = { [K in keyof SceneEntity]?: SceneEntity[K] | undefined };
+
+export type TransformMode = 'translate' | 'rotate' | 'scale';
+export type TransformSpace = 'world' | 'local';
+export type PivotMode = 'active-element' | 'median-point' | 'individual-origins';
+
+export type ShadingMode = 'solid' | 'wireframe' | 'unlit';
+
+/**
+ * Which persistence regime the CURRENT play session's edits are under —
+ * a pure readout of the decision `play-mode.ts` already makes to pick a
+ * provider (docs/MULTI-WORLD-DESIGN.md §1.F / MASTER-ARCHITECTURE-REVIEW §7.4
+ * gap 4): `'ephemeral'` for a single-world session (edits discarded on stop,
+ * `createEphemeralPersistence`), `'overlay'` for a multi-world (≥2) session
+ * (composite of per-world overlay-persisted adapters, edits survive the
+ * session). `null` while not playing. Never derive this independently of the
+ * real provider decision — see `play-mode.ts`'s `enterPlayMode`, which sets it
+ * from the SAME `_isMultiWorldSession` boolean that selects
+ * `installMultiWorldAuthoring` vs `installPlayAuthoring`.
+ */
+export type PlayEditRegime = 'ephemeral' | 'overlay' | null;
+
+export type AssetKind =
+  | 'model'
+  | 'image'
+  | 'audio'
+  | 'json'
+  | 'scene'
+  | 'prefab'
+  | 'material'
+  | 'source';
+
+export interface OnlineAssetInfo {
+  source: 'polyhaven' | 'ambientcg' | 'local';
+  id: string;
+  name: string;
+  thumbnailUrl: string;
+  type: string;
+  tags: string[];
+  license?: string;
+  author?: string;
+  sourceUrl?: string;
+}
+
+export interface AssetTab {
+  key: string;
+  label: string;
+  assetPath: string;
+  kind: AssetKind;
+  /** Present when this tab represents an online (not-yet-downloaded) asset. */
+  online?: OnlineAssetInfo;
+}
+
+export interface HelperVisibility {
+  lights: boolean;
+  cameras: boolean;
+  colliders: boolean;
+  audio: boolean;
+  splines: boolean;
+  navmesh: boolean;
+}
+
+export type ViewportAction =
+  | { type: 'focus-entity'; id: string }
+  | { type: 'focus-selection' }
+  | { type: 'set-view-preset'; preset: 'top' | 'front' | 'right' | 'perspective' }
+  | {
+      type: 'set-camera-pose';
+      position: { x: number; y: number; z: number };
+      target: { x: number; y: number; z: number };
+      fov?: number;
+    };
+
+const MAX_UNDO = 50;
+/** Cooldown (ms) to prevent tight feedback loops between auto-save and external updates. */
+const SYNC_COOLDOWN_MS = 500;
+
+function deepClone<T>(obj: T): T {
+  return JSON.parse(JSON.stringify(obj)) as T;
+}
+
+/** Ensure every entity has a UUID and a children array. Mutates in place. */
+export function assignMissingIds(entities: SceneEntity[]): void {
+  const walk = (list: SceneEntity[]) => {
+    for (const e of list) {
+      if (!e.id) e.id = crypto.randomUUID();
+      if (!e.children) e.children = [];
+      walk(e.children);
+    }
+  };
+  walk(entities);
+}
+
+/** Walk entity Object3Ds in the scene graph and call fn on each. */
+function walkEntityObjects(
+  parent: THREE.Object3D,
+  fn: (obj: THREE.Object3D, entity: SceneEntity) => void,
+): void {
+  for (const child of parent.children) {
+    if (getUserData(child, 'entityId') === undefined) continue;
+    if (getUserData(child, 'editorHelper')) continue;
+    const entity = getUserData(child, 'entity') as SceneEntity | undefined;
+    if (!entity) continue;
+    fn(child, entity);
+    walkEntityObjects(child, fn);
+  }
+}
+
+/** Walk a SceneEntity tree (JSON). */
+function walkEntities(entities: SceneEntity[], fn: (e: SceneEntity) => void): void {
+  for (const e of entities) {
+    fn(e);
+    if (e.children) walkEntities(e.children, fn);
+  }
+}
+
+export class EditorStore {
+  /**
+   * Register with the editor-global undo TIMELINE (T3.2 slice 2) once, for the
+   * lifetime of this store — first-party never "disposes" mid-session, so unlike
+   * ingest/UI sessions there is no matching `unregisterUndoAdapter` call. Safe for
+   * headless test instances too: the timeline only ever calls INTO
+   * `this.undo()`/`this.redo()` when notified, never the reverse.
+   */
+  constructor() {
+    registerUndoAdapter(this);
+  }
+
+  // --- Scene graph references (set via bindScene) ---
+  private _scene: THREE.Scene | null = null;
+  private _editorScene: THREE.Scene | null = null; // stored while game scene is active
+  private _editorObjectMap: Map<string, THREE.Object3D> | null = null; // stored during play
+  /** Pre-play snapshot of `_sceneMeta`, restored by exitPlayScene (see enterPlayScene). */
+  private _editorSceneMeta: SceneMetadata | null = null;
+  private _objectMap = new Map<string, THREE.Object3D>();
+  private _renderer: THREE.WebGLRenderer | null = null;
+  private _camera: THREE.Camera | null = null;
+  private _batchedRenderer: BatchedRenderer | null = null;
+  private _lastThumbnailTime = 0;
+  private _lastEditorStateSaveTime = 0;
+  private _orbitTarget: THREE.Vector3 | null = null;
+
+  /** Scene-level metadata (version, name, environment). Not per-entity. */
+  private _sceneMeta: SceneMetadata = { version: 1, name: 'Untitled' };
+
+  // --- UI state (not stored in scene graph) ---
+  private _selectedEntityIds = new Set<string>();
+  private _clipboard: SceneEntity[] = [];
+  private _transformMode: TransformMode = 'translate';
+  private _transformSpace: TransformSpace = 'world';
+  private _snapEnabled = false;
+  private _snapValues = { translate: 1, rotate: 15, scale: 0.25 };
+  private _snapToSurface = false;
+  private _pivotMode: PivotMode = 'active-element';
+  private _showGrid = true;
+  private _showHelpers = true;
+  private _helperVisibility: HelperVisibility = {
+    lights: true,
+    cameras: true,
+    colliders: true,
+    audio: true,
+    splines: true,
+    navmesh: true,
+  };
+  private _showStats = false;
+  private _shadingMode: ShadingMode = 'solid';
+  private _isDirty = false;
+  /**
+   * Bumped on every document mutation that sets `_isDirty`. A save captures
+   * the epoch when it serializes; its completion callback only clears
+   * `_isDirty` if the epoch is unchanged — a save resolving AFTER a newer
+   * mutation (e.g. an in-flight autosave racing an undo) must not mark the
+   * newer, still-unpersisted state as saved.
+   */
+  private _docEpoch = 0;
+  /**
+   * Exact content of the last write we issued, for own-echo detection: the
+   * file watcher reports our own saves back via SSE, and when that echo
+   * arrives after `_ignoreExternalUntil` (slow watcher under load) it must
+   * not be applied as an "external" update — the document may have moved on
+   * (undo/redo), and applying the echo would clobber the newer state.
+   */
+  private _lastSavedContent: string | null = null;
+  /** True when the most recent auto-save / manual save attempt failed. */
+  private _lastSaveFailed = false;
+  /** True while a coalesced interactive edit gesture is in progress. */
+  private _interactiveActive = false;
+  private _navMeshBaked = false;
+  private _savePath: string | null = null;
+  private _undoStack: string[] = [];
+  private _redoStack: string[] = [];
+  private _activeTabKey = '__inspector__';
+  private _assetTabs: AssetTab[] = [];
+  private _documentType: 'scene' | 'prefab' = 'scene';
+  private _playState: 'stopped' | 'playing' | 'paused' = 'stopped';
+  /** See {@link PlayEditRegime} — set by play-mode.ts on play-enter, cleared on play-exit. */
+  private _playEditRegime: PlayEditRegime = null;
+  private _activeViewportTab: 'scene' | 'game' = 'scene';
+  private _commandPaletteOpen = false;
+  private _vertexSnapActive = false;
+  private _listeners = new Set<() => void>();
+  private _viewportActionListeners = new Set<(action: ViewportAction) => void>();
+  private _version = 0;
+  /**
+   * Bumped only when post-processing-relevant state changes (environment / scene
+   * structure / play-stop scene swap). The viewport rebuilds its EffectComposer
+   * only when this changes — NOT on every notify — so a transform drag/scrub (which
+   * notifies per frame but never touches these) no longer recompiles shaders 60×/s.
+   */
+  private _composerVersion = 0;
+  private _autoSaveTimer: ReturnType<typeof setTimeout> | null = null;
+  /** Timestamp after which external updates are accepted (cooldown after auto-save). */
+  private _ignoreExternalUntil = 0;
+  /** Timestamp after which auto-save is allowed (cooldown after external update). */
+  private _suppressAutoSaveUntil = 0;
+  /** Rolling counter for sync cycles — trips a circuit breaker if too many in a short window. */
+  private _syncCycleTimestamps: number[] = [];
+  /**
+   * Deferred file-watcher/asset-move inputs received while play/ingest is
+   * active (latest wins per kind). Applied once play/ingest stops — see
+   * `setPlayState`/`_applyPendingExternalMutations`, `applyExternalUpdate`,
+   * `applyAssetMove`.
+   */
+  private _pendingExternalUpdate: SceneFile | null = null;
+  private _pendingAssetMove: { oldPath: string; newPath: string } | null = null;
+
+  // --- Bind to scene graph (call once at editor init) ---
+
+  bindScene(
+    scene: THREE.Scene,
+    renderer?: THREE.WebGLRenderer,
+    batchedRenderer?: BatchedRenderer | null,
+    camera?: THREE.Camera,
+  ): void {
+    this._scene = scene;
+    this._renderer = renderer ?? null;
+    this._batchedRenderer = batchedRenderer ?? null;
+    if (camera) this._camera = camera;
+  }
+
+  /** Set the orbit controls target reference for camera state persistence. */
+  setOrbitTarget(target: THREE.Vector3): void {
+    this._orbitTarget = target;
+  }
+
+  // --- React useSyncExternalStore integration ---
+  subscribe = (listener: () => void): (() => void) => {
+    this._listeners.add(listener);
+    return () => this._listeners.delete(listener);
+  };
+
+  getSnapshot = (): number => this._version;
+
+  private _notify(): void {
+    this._version++;
+    for (const fn of this._listeners) fn();
+  }
+
+  // --- Viewport action dispatch ---
+  // Panels call these methods; ViewportPanel subscribes and executes them.
+
+  onViewportAction = (fn: (action: ViewportAction) => void): (() => void) => {
+    this._viewportActionListeners.add(fn);
+    return () => this._viewportActionListeners.delete(fn);
+  };
+
+  private _emitViewportAction(action: ViewportAction): void {
+    for (const fn of this._viewportActionListeners) fn(action);
+  }
+
+  /** Focus the viewport camera on a specific entity. */
+  focusOnEntity(id: string): void {
+    this._emitViewportAction({ type: 'focus-entity', id });
+  }
+
+  /** Focus the viewport camera on the current selection. */
+  focusOnSelection(): void {
+    this._emitViewportAction({ type: 'focus-selection' });
+  }
+
+  /** Switch the viewport camera to a preset view (top, front, right, perspective). */
+  setViewPreset(preset: 'top' | 'front' | 'right' | 'perspective'): void {
+    this._emitViewportAction({ type: 'set-view-preset', preset });
+  }
+
+  /** Move the viewport camera to an arbitrary position/target/fov pose. */
+  setCameraPose(
+    position: { x: number; y: number; z: number },
+    target: { x: number; y: number; z: number },
+    fov?: number,
+  ): void {
+    this._emitViewportAction({
+      type: 'set-camera-pose',
+      position,
+      target,
+      ...(fov !== undefined ? { fov } : {}),
+    });
+  }
+
+  /**
+   * Live viewport camera pose, read straight from the bound Three.js camera +
+   * orbit target (`bindScene`/`setOrbitTarget` — wired by `ViewportPanel.tsx`).
+   * Null only when nothing has bound a camera yet (e.g. a headless store in a
+   * unit test that never mounted `ViewportPanel`).
+   */
+  get cameraPose(): { position: THREE.Vector3; target: THREE.Vector3; fov: number } | null {
+    if (!this._camera) return null;
+    const fov = (this._camera as THREE.PerspectiveCamera).fov;
+    return {
+      position: this._camera.position.clone(),
+      target: this._orbitTarget ? this._orbitTarget.clone() : new THREE.Vector3(),
+      fov: typeof fov === 'number' ? fov : 0,
+    };
+  }
+
+  // --- Scene graph accessors ---
+
+  /** The object map: entity ID → Three.js Object3D. */
+  get objectMap(): Map<string, THREE.Object3D> {
+    return this._objectMap;
+  }
+
+  /** The bound Three.js scene. */
+  get scene(): THREE.Scene | null {
+    return this._scene;
+  }
+
+  /** Monotonic counter bumped when post-processing inputs change (see field doc). */
+  get composerVersion(): number {
+    return this._composerVersion;
+  }
+
+  /**
+   * Build the entity tree from the live scene graph.
+   * Returns a nested SceneEntity[] matching the Three.js hierarchy.
+   * Used by SceneHierarchy and any code that needs the full tree.
+   */
+  get entities(): SceneEntity[] {
+    if (!this._scene) return [];
+    return this._buildEntityTree(this._scene);
+  }
+
+  /**
+   * Flattened id/name/childIds rows for the whole entity tree — the wire
+   * shape `editor.hierarchy.inspect` reports (see
+   * `command-listener.ts`'s `collectState`). Kept here (not in
+   * command-listener.ts) so that file — outside the `SceneEntity` allowlist
+   * (`test/authoring-inversion-guard.test.ts`) — never needs to import
+   * `SceneEntity` itself; this is the one place that walks the real tree.
+   * Entities missing an `id` (should not happen post `assignMissingIds`, but
+   * the type is optional) are skipped — there is no stable key to report.
+   */
+  hierarchyRows(): { id: string; name: string; childIds: string[] }[] {
+    const rows: { id: string; name: string; childIds: string[] }[] = [];
+    const walkTree = (list: SceneEntity[]) => {
+      for (const e of list) {
+        if (!e.id) continue;
+        rows.push({
+          id: e.id,
+          name: e.name,
+          childIds: (e.children ?? []).map((c) => c.id).filter((id): id is string => Boolean(id)),
+        });
+        if (e.children) walkTree(e.children);
+      }
+    };
+    walkTree(this.entities);
+    return rows;
+  }
+
+  /** Scene-level environment settings. */
+  get environment(): SceneEnvironment | undefined {
+    return this._sceneMeta.environment;
+  }
+
+  /** The scene's UI roots (the `ui` field) — read by UI-edit mode (K5). */
+  getSceneUI(): import('@engine/scene/schema').UIRoot[] {
+    return this._sceneMeta.ui ?? [];
+  }
+  /** Replace the scene's UI roots (UI-edit commit), mark dirty + autosave (C9). */
+  setSceneUI(roots: import('@engine/scene/schema').UIRoot[]): void {
+    this._sceneMeta.ui = roots;
+    this._isDirty = true;
+    this._docEpoch++;
+    this._autoSave();
+    this._notify();
+  }
+
+  /** Scene name. */
+  get sceneName(): string {
+    return this._sceneMeta.name;
+  }
+
+  setSceneName(name: string): void {
+    this._sceneMeta.name = name;
+    // No undo — name changes are lightweight, same as old behavior
+  }
+
+  // --- Selection ---
+  get selectedEntityId(): string | null {
+    if (this._selectedEntityIds.size === 0) return null;
+    return [...this._selectedEntityIds].at(-1)!;
+  }
+  get selectedEntityIds(): ReadonlySet<string> {
+    return this._selectedEntityIds;
+  }
+  get selectedEntity(): SceneEntity | null {
+    const id = this.selectedEntityId;
+    return id ? this.getEntityById(id) : null;
+  }
+  get selectedEntities(): SceneEntity[] {
+    return [...this._selectedEntityIds]
+      .map((id) => this.getEntityById(id))
+      .filter((e): e is SceneEntity => e !== null);
+  }
+  get transformMode(): TransformMode {
+    return this._transformMode;
+  }
+  get transformSpace(): TransformSpace {
+    return this._transformSpace;
+  }
+  get snapEnabled(): boolean {
+    return this._snapEnabled;
+  }
+  get snapValues() {
+    return this._snapValues;
+  }
+  get snapToSurface(): boolean {
+    return this._snapToSurface;
+  }
+  get pivotMode(): PivotMode {
+    return this._pivotMode;
+  }
+  get isDirty(): boolean {
+    return this._isDirty;
+  }
+  /**
+   * Coarse save status for UI affordances:
+   * 'failed' — last save attempt failed; changes are NOT on disk.
+   * 'unsaved' — there are dirty changes not yet persisted.
+   * 'saved' — in sync with disk.
+   */
+  get saveState(): 'saved' | 'unsaved' | 'failed' {
+    if (this._lastSaveFailed) return 'failed';
+    if (this._isDirty) return 'unsaved';
+    return 'saved';
+  }
+  get canUndo(): boolean {
+    return this._undoStack.length > 0;
+  }
+  get canRedo(): boolean {
+    return this._redoStack.length > 0;
+  }
+  get showGrid(): boolean {
+    return this._showGrid;
+  }
+  get showHelpers(): boolean {
+    return this._showHelpers;
+  }
+  get helperVisibility(): Readonly<HelperVisibility> {
+    return this._helperVisibility;
+  }
+  get showStats(): boolean {
+    return this._showStats;
+  }
+  get shadingMode(): ShadingMode {
+    return this._shadingMode;
+  }
+  get hasClipboard(): boolean {
+    return this._clipboard.length > 0;
+  }
+  get savePath(): string | null {
+    return this._savePath;
+  }
+  setSavePath(path: string | null): void {
+    this._savePath = path;
+    this._notify();
+  }
+  get documentType(): 'scene' | 'prefab' {
+    return this._documentType;
+  }
+
+  /** Notify subscribers after an ingest adapter mutated a live foreign object
+   *  (material/visibility). Runtime-only — no dirty/autosave (edits live on the
+   *  Object3D, not a .vscn descriptor). */
+  notifyIngestEdit(): void {
+    this._notify();
+  }
+
+  // --- Play mode scene swap ---
+
+  /** Callback to sync transform edits to game ECS. Set by play-mode, cleared on exit. */
+  private _ecsSyncTransform: ((obj: THREE.Object3D) => void) | null = null;
+
+  /** Set a callback that syncs editor transform changes to the game's ECS state. */
+  setEcsSyncTransform(fn: ((obj: THREE.Object3D) => void) | null): void {
+    this._ecsSyncTransform = fn;
+  }
+
+  /**
+   * Swap the store's active scene to the game scene. Editor scene is preserved.
+   *
+   * Also snapshots `_sceneMeta` (env/name/ui — see `getDocument`/`updateEnvironment`/
+   * `setSceneName`/`setSceneUI`). Those setters keep mutating the SAME live
+   * `_sceneMeta` object during play so the environment inspector / scene name
+   * field keep working and `getDocument()` stays consistent while playing —
+   * but any such edit must be discarded when play stops (probe: F5 in the
+   * round-1 review — `updateEnvironment` during play silently persisted with
+   * `isDirty` false). `exitPlayScene` restores this snapshot.
+   */
+  enterPlayScene(gameScene: THREE.Scene, opts: { liveHierarchy?: boolean } = {}): void {
+    if (!this._scene) return;
+    this._editorScene = this._scene;
+    this._editorObjectMap = this._objectMap;
+    this._editorSceneMeta = deepClone(this._sceneMeta);
+    this._scene = gameScene;
+
+    // In play mode the hierarchy is a LIVE view of the running scene graph, not
+    // the authored document — so surface every object, not just the ones that
+    // came from the .vscn. Objects the scene-loader tagged keep their rich
+    // descriptor (full inspector); procedurally-created / runtime-spawned
+    // objects (the ship hull, instanced asteroids, spawned bullets…) get a
+    // synthetic descriptor so they appear in the tree, are selectable, and can
+    // be nudged via the gizmo to test the game. These edits are ephemeral —
+    // nothing is written back to the .vscn (play mode never serializes).
+    //
+    // Synthesis is OPT-IN (`liveHierarchy: true` — first-party play mode only).
+    // Ingest/module mounts adopt a FOREIGN scene through this same method, and
+    // the anti-shim rule forbids fabricating a SceneEntity descriptor onto an
+    // object we don't own: their hierarchies come from the AuthoringAdapter
+    // seam (OID-derived), never from synthesized userData. Untagged foreign
+    // objects therefore stay out of the objectMap entirely by default.
+    const gameMap = new Map<string, THREE.Object3D>();
+    gameScene.traverse((obj) => {
+      if (obj === gameScene) return;
+      if (getUserData(obj, 'editorHelper')) return;
+      // Engine-owned infra (particle renderer, debug-draw) is not a game entity.
+      if (getUserData(obj, 'engineInternal')) return;
+      let eid = getUserData(obj, 'entityId') as string | undefined;
+      if (eid === undefined) {
+        if (!opts.liveHierarchy) return;
+        eid = obj.uuid;
+        setUserData(obj, 'entityId', eid);
+        setUserData(obj, 'entity', { id: eid, name: obj.name || obj.type } as SceneEntity);
+        setUserData(obj, 'liveObject', true); // marks a non-authored runtime object
+      }
+      gameMap.set(eid, obj);
+    });
+    this._objectMap = gameMap;
+
+    this._selectedEntityIds.clear();
+    this._composerVersion++; // scene swapped → composer must rebuild against the game scene
+    this._notify();
+  }
+
+  /** Restore the editor scene after play mode ends (see enterPlayScene). */
+  exitPlayScene(): void {
+    if (!this._editorScene || !this._editorObjectMap) return;
+    this._scene = this._editorScene;
+    this._objectMap = this._editorObjectMap;
+    this._editorScene = null;
+    this._editorObjectMap = null;
+    // Discard any play-time env/name/ui edits — restore the pre-play snapshot.
+    if (this._editorSceneMeta) {
+      this._sceneMeta = this._editorSceneMeta;
+      this._editorSceneMeta = null;
+    }
+    this._selectedEntityIds.clear();
+    this._composerVersion++; // scene swapped back → composer must rebuild against the editor scene
+    this._notify();
+  }
+
+  // --- Play mode state ---
+  get playState(): 'stopped' | 'playing' | 'paused' {
+    return this._playState;
+  }
+
+  /**
+   * Guard structural/history mutations while a game is running. During play the
+   * store's `_scene` is the LIVE game scene (see enterPlayScene), so undo/redo
+   * (which call clearPreview + buildPreview and rebuild the whole scene) or
+   * delete/duplicate (which splice the scene graph and objectMap) would tear the
+   * scene out from under the running GameSession. Returns true (and warns) when
+   * the named op must be blocked. The intended live-edit path during play is the
+   * incremental ECS-sync transform path, not these full-scene mutations.
+   */
+  private _blockedDuringPlay(op: string): boolean {
+    if (this._playState === 'stopped') return false;
+    console.warn(`EditorStore: "${op}" is disabled during play mode — stop the game first.`);
+    return true;
+  }
+  setPlayState(state: 'stopped' | 'playing' | 'paused'): void {
+    const wasActive = this._playState !== 'stopped';
+    this._playState = state;
+    if (state === 'playing' && this._activeViewportTab === 'scene') {
+      this._activeViewportTab = 'game';
+    }
+    if (state === 'stopped') {
+      this._activeViewportTab = 'scene';
+      // Apply anything deferred while play/ingest was active. play-mode.ts /
+      // ingest-mode.ts call exitPlayScene() (restoring the editor scene) BEFORE
+      // this — so by the time we get here `_scene` is already the editor scene,
+      // never the just-torn-down game scene (see applyExternalUpdate/applyAssetMove).
+      if (wasActive) this._applyPendingExternalMutations();
+    }
+    this._notify();
+  }
+
+  /** See {@link PlayEditRegime}. Null while not playing. */
+  get playEditRegime(): PlayEditRegime {
+    return this._playEditRegime;
+  }
+
+  /** Set by play-mode.ts's enterPlayMode/exitPlayMode — see {@link PlayEditRegime}. */
+  setPlayEditRegime(regime: PlayEditRegime): void {
+    this._playEditRegime = regime;
+    this._notify();
+  }
+
+  /** Apply deferred external-update/asset-move inputs after play/ingest stops. */
+  private _applyPendingExternalMutations(): void {
+    if (this._pendingExternalUpdate) {
+      const doc = this._pendingExternalUpdate;
+      this._pendingExternalUpdate = null;
+      this.applyExternalUpdate(doc);
+    }
+    if (this._pendingAssetMove) {
+      const { oldPath, newPath } = this._pendingAssetMove;
+      this._pendingAssetMove = null;
+      this.applyAssetMove(oldPath, newPath);
+    }
+  }
+
+  // --- Viewport tab ---
+  get activeViewportTab(): 'scene' | 'game' {
+    return this._activeViewportTab;
+  }
+  setActiveViewportTab(tab: 'scene' | 'game'): void {
+    this._activeViewportTab = tab;
+    this._notify();
+  }
+  // --- Command palette ---
+  get commandPaletteOpen(): boolean {
+    return this._commandPaletteOpen;
+  }
+  toggleCommandPalette(): void {
+    this._commandPaletteOpen = !this._commandPaletteOpen;
+    this._notify();
+  }
+  closeCommandPalette(): void {
+    if (!this._commandPaletteOpen) return;
+    this._commandPaletteOpen = false;
+    this._notify();
+  }
+
+  // --- Vertex snap ---
+  get vertexSnapActive(): boolean {
+    return this._vertexSnapActive;
+  }
+  setVertexSnapActive(active: boolean): void {
+    this._vertexSnapActive = active;
+    this._notify();
+  }
+
+  get activeTabKey(): string {
+    return this._activeTabKey;
+  }
+  get assetTabs(): readonly AssetTab[] {
+    return this._assetTabs;
+  }
+
+  /** True if any entities have a navigation role. */
+  hasNavigationEntities(): boolean {
+    if (!this._scene) return false;
+    let found = false;
+    walkEntityObjects(this._scene, (_, entity) => {
+      if (entity.navigation?.role) found = true;
+    });
+    return found;
+  }
+
+  get navMeshStale(): boolean {
+    return !this._navMeshBaked && this.hasNavigationEntities();
+  }
+
+  markNavMeshBaked(): void {
+    this._navMeshBaked = true;
+    this._notify();
+  }
+
+  // --- Selection ---
+  select(id: string | null): void {
+    this._selectedEntityIds.clear();
+    if (id) this._selectedEntityIds.add(id);
+    this._notify();
+  }
+
+  selectMultiple(ids: string[]): void {
+    this._selectedEntityIds = new Set(ids);
+    this._notify();
+  }
+
+  addToSelection(id: string): void {
+    this._selectedEntityIds.add(id);
+    this._notify();
+  }
+
+  toggleSelection(id: string): void {
+    if (this._selectedEntityIds.has(id)) {
+      this._selectedEntityIds.delete(id);
+    } else {
+      this._selectedEntityIds.add(id);
+    }
+    this._notify();
+  }
+
+  selectAll(): void {
+    const all = this.allEntities();
+    this._selectedEntityIds = new Set(all.map((e) => e.id!).filter(Boolean));
+    this._notify();
+  }
+
+  // --- Entity lookup ---
+
+  getEntityById(id: string): SceneEntity | null {
+    const obj = this._objectMap.get(id);
+    return (getUserData(obj, 'entity') as SceneEntity) ?? null;
+  }
+
+  /** Flat list of all entities in scene. */
+  allEntities(): SceneEntity[] {
+    if (!this._scene) return [];
+    const result: SceneEntity[] = [];
+    walkEntityObjects(this._scene, (_, entity) => result.push(entity));
+    return result;
+  }
+
+  // --- Undo stack ---
+
+  /** Public: push a snapshot before a drag begins (called by viewport). */
+  pushUndoSnapshot(): void {
+    this._pushUndo();
+  }
+
+  private _pushUndo(): void {
+    if (!this._scene) return;
+    // Play-mode guard (T1.6): while playing/paused, `_scene`/`_objectMap` point
+    // at the LIVE game scene (see enterPlayScene) — a fresh object graph loaded
+    // from a snapshot of the document, whose entity descriptors are runtime-only
+    // copies discarded on exitPlayScene. Pushing a snapshot here would serialize
+    // that runtime state onto the REAL undo stack: a later edit's snapshot could
+    // capture an intermediate runtime pose, and a post-stop Ctrl+Z would then
+    // restore that runtime pose into the restored editor scene. Marking dirty /
+    // scheduling autosave would similarly persist runtime state over the on-disk
+    // `.vscn`. Skip all three; the property mutation itself (already applied by
+    // the caller to the live game-scene descriptor/Object3D) still takes effect
+    // for the running game — it's just never recorded in editor history or saved.
+    if (this._playState !== 'stopped') return;
+    // During an interactive gesture (a NumberInput scrub or color-picker drag),
+    // beginInteractiveEdit() already captured ONE pre-gesture snapshot. Skip the
+    // per-event snapshot so the whole gesture collapses to a single undo step,
+    // but still mark dirty + schedule autosave so the live value persists.
+    if (!this._interactiveActive) {
+      const doc = serializeScene(this._scene, this._sceneMeta);
+      this._undoStack.push(JSON.stringify(doc));
+      if (this._undoStack.length > MAX_UNDO) this._undoStack.shift();
+      this._redoStack.length = 0;
+      // T3.2 slice 2: tag this op on the editor-global undo timeline too (only
+      // when a snapshot was actually pushed — the interactive-gesture branch
+      // above collapses a whole drag into the ONE snapshot already notified by
+      // beginInteractiveEdit's own _pushUndo call).
+      notifyUndoableOp(this);
+    }
+    this._isDirty = true;
+    this._docEpoch++;
+    this._navMeshBaked = false;
+    this._scheduleAutoSave();
+  }
+
+  /**
+   * Begin a coalesced interactive edit (continuous input gesture). Pushes exactly
+   * ONE undo snapshot for the whole gesture; intermediate mutations during the
+   * gesture do not push more. Idempotent — safe to call on every pointermove /
+   * onChange. Pair with endInteractiveEdit(). Mirrors the viewport gizmo's live
+   * drag (pushUndoSnapshot at start, no-undo live updates, commit at end).
+   */
+  beginInteractiveEdit(): void {
+    if (this._interactiveActive) return;
+    this._pushUndo();
+    this._interactiveActive = true;
+  }
+
+  /** End a coalesced interactive edit gesture. */
+  endInteractiveEdit(): void {
+    this._interactiveActive = false;
+  }
+
+  private _scheduleAutoSave(): void {
+    if (this._autoSaveTimer) clearTimeout(this._autoSaveTimer);
+    this._autoSaveTimer = setTimeout(() => this._autoSave(), 300);
+  }
+
+  /** Returns true if too many sync cycles happened recently (circuit breaker). */
+  private _isSyncLooping(): boolean {
+    const now = Date.now();
+    this._syncCycleTimestamps.push(now);
+    // Keep only timestamps from the last 5 seconds
+    while (this._syncCycleTimestamps.length > 0 && this._syncCycleTimestamps[0]! < now - 5000) {
+      this._syncCycleTimestamps.shift();
+    }
+    if (this._syncCycleTimestamps.length > 20) {
+      console.warn(
+        '[EditorStore] Sync loop detected — too many save/update cycles. Pausing sync for 5s.',
+      );
+      this._ignoreExternalUntil = now + 5000;
+      this._suppressAutoSaveUntil = now + 5000;
+      this._syncCycleTimestamps.length = 0;
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Whether and where an edit persists is decided by the ACTIVE authoring
+   * adapter's `persistence` provider — one place, not a store-wide flag per
+   * session kind (design `docs/PERSISTENCE-PROVIDER-DESIGN.md` §2). Absent
+   * provider, or an adapter that declares `capabilities.persist === false`
+   * (e.g. world2d, embed-only), means "nothing to autosave" here.
+   */
+  private _activePersistence(): PersistenceProvider | null {
+    const adapter = getActiveAuthoring(this);
+    if (!adapter.persistence || !adapter.capabilities.persist) return null;
+    return adapter.persistence;
+  }
+
+  private _autoSave(): void {
+    this._autoSaveTimer = null;
+    // Play-mode guard (T1.6, belt-and-braces): `_scene` is the live game scene
+    // while playing/paused (see enterPlayScene). `_pushUndo`/`commitLiveTransform`
+    // already skip scheduling autosave during play, and play-mode.ts installs an
+    // ephemeral persistence provider (isDirty() always false) via
+    // `setActiveAuthoring` for the duration — so this check is now a backstop
+    // against a timer that was already in flight the instant play started, not
+    // the structural decision (design §2/§7 slice 1).
+    if (this._playState !== 'stopped') return;
+    const provider = this._activePersistence();
+    if (!provider) return;
+    if (!this._scene) return;
+    // Suppressed (sync cooldown / circuit breaker): RESCHEDULE, don't drop —
+    // a dropped autosave silently strands dirty changes off-disk. The retry
+    // hits the `_suppressAutoSaveUntil` check first, so it does not feed the
+    // `_isSyncLooping` counter while waiting out the window.
+    if (Date.now() < this._suppressAutoSaveUntil) {
+      this._scheduleAutoSave();
+      return;
+    }
+    if (this._isSyncLooping()) {
+      this._scheduleAutoSave();
+      return;
+    }
+    // Delegate the actual write to the provider (first-party's `save()` calls
+    // back into `saveNow()` below — the store's existing write path/epoch
+    // discipline; an ingest/other provider writes its own destination). Failure
+    // handling for the first-party path already lives inside `saveNow()`; this
+    // catch only guards a provider whose `save()` itself throws.
+    void provider.save().catch((err) => {
+      this._lastSaveFailed = true;
+      console.warn('[EditorStore] Auto-save threw — changes are NOT saved to disk.', err);
+      this._notify();
+    });
+  }
+
+  /**
+   * Guard manual save (Ctrl/Cmd+S — `saveNow()`, which unconditionally writes
+   * `this.getDocument()` to `this._savePath`) against play mode AND any other
+   * authoring session (ingest, world2d, UI-edit, …).
+   *
+   * `_autoSave()` routes through the active adapter's persistence provider (see
+   * `_activePersistence()`) so it never reaches this method's write path for a
+   * non-first-party session. `saveNow()` itself is still the FIRST-PARTY write
+   * (the first-party provider's `save()` calls back into it) — bypassing the
+   * debounce entirely — so it needs its own guard: `hasAuthoringOverride()` is
+   * true whenever a session installed a DIFFERENT adapter via
+   * `setActiveAuthoring` (ingest/world2d/UI-edit/play), meaning `this._scene`
+   * and `this.getDocument()` no longer describe the first-party `.vscn` (or, for
+   * play, must route through the ephemeral provider instead — see design
+   * `docs/PERSISTENCE-PROVIDER-DESIGN.md` §2). During ingest specifically, an
+   * ingested foreign object carries only `userData.entityId`, never the
+   * `userData['entity']` descriptor `serializeScene` requires, so an unguarded
+   * write here would silently overwrite the previously-open first-party scene
+   * with an empty entity list (probe: F1b in the round-1 review).
+   */
+  private _blockedForSave(): boolean {
+    if (this._playState !== 'stopped') {
+      console.warn('EditorStore: "save" is disabled during play mode — stop the game first.');
+      return true;
+    }
+    // A1: the edit-mode composite is NOT a foreign override — its focused
+    // child IS the store's own first-party `.vscn` document, writing through
+    // this very path. Blocking it would silently strand the focused world's
+    // edits off-disk (isDirty stuck true forever). Only a TRUE foreign
+    // override (ingest/world2d/UI-edit/play) blocks here.
+    if (hasAuthoringOverride() && !activeOverrideIsEditMode()) {
+      console.warn(
+        'EditorStore: "save" is disabled while another authoring adapter is active — exit it first.',
+      );
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Force an immediate save (e.g. Ctrl/Cmd+S), bypassing the debounce. Resolves
+   * to whether the write succeeded and surfaces failures via saveState.
+   */
+  async saveNow(): Promise<boolean> {
+    if (this._blockedForSave()) return false;
+    if (this._autoSaveTimer) {
+      clearTimeout(this._autoSaveTimer);
+      this._autoSaveTimer = null;
+    }
+    if (!this._savePath || !this._scene) return false;
+    const content = JSON.stringify(this.getDocument(), null, 2);
+    const epoch = this._docEpoch;
+    this._ignoreExternalUntil = Date.now() + SYNC_COOLDOWN_MS;
+    this._lastSavedContent = content;
+    try {
+      const ok = await saveFile(this._savePath, content);
+      // Same epoch discipline as `_autoSave`: don't mark a newer, unpersisted
+      // mutation clean because an older save resolved.
+      if (ok && this._docEpoch === epoch) this._isDirty = false;
+      else if (!ok) this._isDirty = true;
+      this._lastSaveFailed = !ok;
+      this._notify();
+      if (ok) {
+        this._captureThumbnail();
+        this._saveEditorStateIfDue();
+      } else {
+        console.warn('[EditorStore] Save failed — changes are NOT saved to disk.');
+      }
+      return ok;
+    } catch (err) {
+      this._lastSaveFailed = true;
+      this._notify();
+      console.warn('[EditorStore] Save threw — changes are NOT saved to disk.', err);
+      return false;
+    }
+  }
+
+  private static readonly THUMBNAIL_INTERVAL_MS = 60_000;
+  private static readonly THUMBNAIL_SIZE = 256;
+
+  /**
+   * Render the bound camera's current view to a PNG data URL at `size`x`size`
+   * (game content only — editor-layer grid/helpers/gizmos excluded, same as
+   * the thumbnail path). Shared by the throttled autosave thumbnail
+   * (`_captureThumbnail`) and the on-demand `captureViewportImage` (backs the
+   * `capture-viewport` relay command / `editor.viewport.screenshot.capture`'s
+   * fresh-capture mode) — same rendering technique (offscreen render target +
+   * `readRenderTargetPixels`), so it needs no `preserveDrawingBuffer` on the
+   * live canvas's WebGL context. Returns null if no renderer/scene/camera is
+   * bound yet.
+   */
+  private _renderViewportImage(size: number): string | null {
+    if (!this._renderer || !this._scene || !this._camera) return null;
+
+    const renderSize = size * 2; // render at 2x then downscale for crisp result
+    const renderer = this._renderer;
+    const renderTarget = new THREE.WebGLRenderTarget(renderSize, renderSize);
+    const prevTarget = renderer.getRenderTarget();
+    const prevPixelRatio = renderer.getPixelRatio();
+
+    // Render without editor-layer objects (grid, helpers, gizmos)
+    const camera = this._camera as THREE.PerspectiveCamera;
+    const prevLayers = camera.layers.mask;
+    camera.layers.disableAll();
+    camera.layers.enable(0); // game content only
+
+    renderer.setPixelRatio(1);
+    renderer.setRenderTarget(renderTarget);
+    renderer.render(this._scene, camera);
+    renderer.setRenderTarget(prevTarget);
+    renderer.setPixelRatio(prevPixelRatio);
+
+    camera.layers.mask = prevLayers;
+
+    // Read pixels from the render target
+    const pixels = new Uint8Array(renderSize * renderSize * 4);
+    renderer.readRenderTargetPixels(renderTarget, 0, 0, renderSize, renderSize, pixels);
+    renderTarget.dispose();
+
+    // Flip vertically (WebGL reads bottom-up) and write to a full-size canvas
+    const fullCanvas = document.createElement('canvas');
+    fullCanvas.width = renderSize;
+    fullCanvas.height = renderSize;
+    const fullCtx = fullCanvas.getContext('2d')!;
+    const imageData = fullCtx.createImageData(renderSize, renderSize);
+    for (let y = 0; y < renderSize; y++) {
+      const srcRow = (renderSize - 1 - y) * renderSize * 4;
+      const dstRow = y * renderSize * 4;
+      imageData.data.set(pixels.subarray(srcRow, srcRow + renderSize * 4), dstRow);
+    }
+    fullCtx.putImageData(imageData, 0, 0);
+
+    // Downscale to final thumbnail size
+    const canvas = document.createElement('canvas');
+    canvas.width = size;
+    canvas.height = size;
+    const ctx2d = canvas.getContext('2d')!;
+    ctx2d.drawImage(fullCanvas, 0, 0, size, size);
+
+    return canvas.toDataURL('image/png');
+  }
+
+  private _captureThumbnail(): void {
+    const now = Date.now();
+    if (now - this._lastThumbnailTime < EditorStore.THUMBNAIL_INTERVAL_MS) return;
+    this._lastThumbnailTime = now;
+    const dataUrl = this._renderViewportImage(EditorStore.THUMBNAIL_SIZE);
+    if (dataUrl) saveThumbnail(dataUrl);
+  }
+
+  /**
+   * Fresh, on-demand viewport capture (unthrottled, unlike the periodic
+   * autosave thumbnail above) — backs the `capture-viewport` relay command.
+   * Returns null when no renderer/scene/camera is bound yet (e.g. before
+   * `ViewportPanel` has mounted).
+   */
+  captureViewportImage(size = EditorStore.THUMBNAIL_SIZE): string | null {
+    return this._renderViewportImage(size);
+  }
+
+  // --- Editor state persistence ---
+
+  private static readonly EDITOR_STATE_INTERVAL_MS = 60_000;
+
+  private _saveEditorStateIfDue(): void {
+    const now = Date.now();
+    if (now - this._lastEditorStateSaveTime < EditorStore.EDITOR_STATE_INTERVAL_MS) return;
+    this._lastEditorStateSaveTime = now;
+
+    const state: Record<string, unknown> = {
+      transformMode: this._transformMode,
+      transformSpace: this._transformSpace,
+      snapEnabled: this._snapEnabled,
+      snapValues: this._snapValues,
+      pivotMode: this._pivotMode,
+      showGrid: this._showGrid,
+      showHelpers: this._showHelpers,
+      helperVisibility: { ...this._helperVisibility },
+      showStats: this._showStats,
+      shadingMode: this._shadingMode,
+    };
+
+    if (this._savePath) {
+      state['lastScene'] = this._savePath;
+    }
+
+    if (this._camera) {
+      const cam = this._camera as THREE.PerspectiveCamera;
+      state['camera'] = {
+        position: cam.position.toArray(),
+        target: this._orbitTarget ? this._orbitTarget.toArray() : [0, 0, 0],
+      };
+    }
+
+    saveEditorState(state);
+  }
+
+  /** Restore editor state from server. Call after bindScene + loadInitialScene. */
+  async restoreEditorState(): Promise<void> {
+    const state = await loadEditorState();
+    if (!state || Object.keys(state).length === 0) return;
+
+    if (typeof state['transformMode'] === 'string') {
+      this._transformMode = state['transformMode'] as TransformMode;
+    }
+    if (typeof state['transformSpace'] === 'string') {
+      this._transformSpace = state['transformSpace'] as TransformSpace;
+    }
+    if (typeof state['snapEnabled'] === 'boolean') {
+      this._snapEnabled = state['snapEnabled'];
+    }
+    if (state['snapValues'] && typeof state['snapValues'] === 'object') {
+      Object.assign(this._snapValues, state['snapValues']);
+    }
+    if (typeof state['pivotMode'] === 'string') {
+      this._pivotMode = state['pivotMode'] as PivotMode;
+    }
+    if (typeof state['showGrid'] === 'boolean') {
+      this._showGrid = state['showGrid'];
+    }
+    if (typeof state['showHelpers'] === 'boolean') {
+      this._showHelpers = state['showHelpers'];
+    }
+    if (state['helperVisibility'] && typeof state['helperVisibility'] === 'object') {
+      Object.assign(this._helperVisibility, state['helperVisibility']);
+    }
+    if (typeof state['showStats'] === 'boolean') {
+      this._showStats = state['showStats'];
+    }
+    if (typeof state['shadingMode'] === 'string') {
+      this._shadingMode = state['shadingMode'] as ShadingMode;
+    }
+
+    // Restore camera
+    if (state['camera'] && typeof state['camera'] === 'object') {
+      const cam = state['camera'] as { position?: number[]; target?: number[] };
+      if (this._camera && cam.position && cam.position.length === 3) {
+        (this._camera as THREE.PerspectiveCamera).position.set(
+          cam.position[0]!,
+          cam.position[1]!,
+          cam.position[2]!,
+        );
+      }
+      if (this._orbitTarget && cam.target && cam.target.length === 3) {
+        this._orbitTarget.set(cam.target[0]!, cam.target[1]!, cam.target[2]!);
+      }
+    }
+
+    this._notify();
+  }
+
+  // --- Mutations ---
+
+  updateEntity(id: string, partial: EntityUpdate): void {
+    const obj = this._objectMap.get(id);
+    const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
+    if (!entity || !obj) return;
+    this._pushUndo();
+    Object.assign(entity, partial);
+    this._rebuildEntity(id);
+    this._notify();
+  }
+
+  updateTransform(
+    id: string,
+    pos: [number, number, number],
+    rot: [number, number, number, number],
+    scl: [number, number, number],
+  ): void {
+    const obj = this._objectMap.get(id);
+    const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
+    if (!entity || !obj) return;
+    this._pushUndo();
+    entity.transform = { position: pos, rotation: rot, scale: scl };
+    obj.position.set(pos[0], pos[1], pos[2]);
+    obj.quaternion.set(rot[0], rot[1], rot[2], rot[3]);
+    obj.scale.set(scl[0], scl[1], scl[2]);
+    this._notify();
+  }
+
+  /** Update transform without pushing undo — used for live gizmo drag preview. */
+  updateTransformLive(
+    id: string,
+    pos: [number, number, number],
+    rot: [number, number, number, number],
+    scl: [number, number, number],
+  ): void {
+    const obj = this._objectMap.get(id);
+    const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
+    if (!entity || !obj) return;
+    // The gizmo has already moved the Object3D — just sync the descriptor
+    entity.transform = { position: pos, rotation: rot, scale: scl };
+    // During play, also sync to ECS so the game loop doesn't overwrite
+    if (this._ecsSyncTransform) this._ecsSyncTransform(obj);
+    this._notify();
+  }
+
+  /** Rebuild an entity's Three.js preview (for handle drags where the descriptor is already mutated). */
+  rebuildEntityLive(id: string): void {
+    this._rebuildEntity(id);
+    this._notify();
+  }
+
+  /**
+   * Commit a completed live drag (gizmo or handle) (ED2).
+   *
+   * During a drag only `updateTransformLive`/`rebuildEntityLive` run, which
+   * mutate the descriptor but never mark dirty or schedule a save. The undo
+   * snapshot was already pushed at drag start, so we must NOT push another
+   * here — but we must persist the FINAL transform: mark dirty and (re)schedule
+   * the autosave so the last position is written, even if a mid-drag autosave
+   * already fired and cleared the dirty flag.
+   *
+   * Play-mode guard (T1.6): while playing/paused, the drag only ever moved the
+   * live GAME scene's Object3D (via `_ecsSyncTransform`) — there is nothing of
+   * the editor's own document to persist, so skip marking dirty / scheduling
+   * autosave entirely. Still notify so any subscribed UI refreshes.
+   */
+  commitLiveTransform(): void {
+    if (this._playState === 'stopped') {
+      this._isDirty = true;
+      this._docEpoch++;
+      this._navMeshBaked = false;
+      this._scheduleAutoSave();
+    }
+    this._notify();
+  }
+
+  addEntity(parentId: string | null, entity: SceneEntity, index?: number): void {
+    if (this._blockedDuringPlay('add entity')) return;
+    if (!this._scene) return;
+    if (!entity.id) entity.id = crypto.randomUUID();
+    assignMissingIds(entity.children ?? []);
+    this._pushUndo();
+
+    const obj = createEntityObject(entity);
+    obj.visible = entity.visible !== false;
+
+    const parent = parentId ? this._objectMap.get(parentId) : null;
+    const target = parent ?? this._scene;
+
+    if (index !== undefined) {
+      // Insert at specific index among entity children
+      const entityChildren = target.children.filter(
+        (c) => getUserData(c, 'entityId') !== undefined && !getUserData(c, 'editorHelper'),
+      );
+      const clampedIndex = Math.min(index, entityChildren.length);
+      const insertBefore = entityChildren[clampedIndex];
+      const threeIndex = insertBefore
+        ? target.children.indexOf(insertBefore)
+        : target.children.length;
+      target.children.splice(threeIndex, 0, obj);
+      obj.parent = target;
+    } else {
+      target.add(obj);
+    }
+    this._objectMap.set(entity.id, obj);
+    registerParticles(obj, this._batchedRenderer);
+
+    // If entity has children, add them recursively
+    if (entity.children) {
+      this._addChildEntities(entity.children, obj);
+    }
+
+    this._selectedEntityIds.clear();
+    this._selectedEntityIds.add(entity.id);
+    this._notify();
+  }
+
+  /** Recursively create child entity Object3Ds and add to parent. */
+  private _addChildEntities(children: SceneEntity[], parent: THREE.Object3D): void {
+    for (const child of children) {
+      if (!child.id) child.id = crypto.randomUUID();
+      const childObj = createEntityObject(child);
+      childObj.visible = child.visible !== false;
+      parent.add(childObj);
+      this._objectMap.set(child.id, childObj);
+      registerParticles(childObj, this._batchedRenderer);
+      if (child.children) {
+        this._addChildEntities(child.children, childObj);
+      }
+    }
+  }
+
+  removeEntity(id: string): void {
+    if (this._blockedDuringPlay('delete entity')) return;
+    const obj = this._objectMap.get(id);
+    if (!obj) return;
+    this._pushUndo();
+    this._removeObjectFromScene(obj);
+    this._selectedEntityIds.delete(id);
+    this._notify();
+  }
+
+  /** Remove an Object3D and all its entity children from the scene + objectMap. */
+  private _removeObjectFromScene(obj: THREE.Object3D): void {
+    // Recursively remove entity children from objectMap
+    for (const child of [...obj.children]) {
+      if (getUserData(child, 'entityId') !== undefined && !getUserData(child, 'editorHelper')) {
+        this._removeObjectFromScene(child);
+      }
+    }
+    unregisterParticles(obj, this._batchedRenderer);
+    const eid = getUserData(obj, 'entityId') as string | undefined;
+    if (eid) this._objectMap.delete(eid);
+    obj.removeFromParent();
+  }
+
+  duplicateEntity(id: string): void {
+    if (this._blockedDuringPlay('duplicate entity')) return;
+    if (!this._scene) return;
+    const obj = this._objectMap.get(id);
+    const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
+    if (!entity || !obj) return;
+
+    // Deep clone the entity descriptor with full subtree
+    const cloneEntity = this._serializeSubtree(obj);
+    const reassign = (e: SceneEntity) => {
+      e.id = crypto.randomUUID();
+      if (e.children) e.children.forEach(reassign);
+    };
+    reassign(cloneEntity);
+    cloneEntity.name = `${entity.name} (copy)`;
+
+    this._pushUndo();
+
+    // Create object and insert after original
+    const cloneObj = createEntityObject(cloneEntity);
+    cloneObj.visible = cloneEntity.visible !== false;
+    const parent = obj.parent ?? this._scene;
+    const index = parent.children.indexOf(obj);
+    if (index >= 0) {
+      parent.children.splice(index + 1, 0, cloneObj);
+      cloneObj.parent = parent;
+    } else {
+      parent.add(cloneObj);
+    }
+    this._objectMap.set(cloneEntity.id!, cloneObj);
+    registerParticles(cloneObj, this._batchedRenderer);
+
+    // Recursively add child entities
+    if (cloneEntity.children) {
+      this._addChildEntities(cloneEntity.children, cloneObj);
+    }
+
+    this._selectedEntityIds.clear();
+    this._selectedEntityIds.add(cloneEntity.id!);
+    this._notify();
+  }
+
+  /** Serialize an entity + its scene-graph children into a nested SceneEntity. */
+  private _serializeSubtree(obj: THREE.Object3D): SceneEntity {
+    const stored = getUserData(obj, 'entity') as SceneEntity;
+    const entity = deepClone(stored);
+    const children: SceneEntity[] = [];
+    for (const child of obj.children) {
+      if (getUserData(child, 'entityId') !== undefined && !getUserData(child, 'editorHelper')) {
+        children.push(this._serializeSubtree(child));
+      }
+    }
+    if (children.length > 0) {
+      entity.children = children;
+    } else {
+      delete entity.children;
+    }
+    return entity;
+  }
+
+  // --- Reparent / reorder (react-arborist onMove) ---
+  moveEntity(dragIds: string[], parentId: string | null, index: number): void {
+    if (this._blockedDuringPlay('move entity')) return;
+    if (!this._scene) return;
+
+    // Validate before pushing undo — a rejected move must not leave a
+    // no-op undo entry on the stack (T1.12c: complete or roll back, no
+    // undo-then-bail).
+    const targetParent = parentId ? this._objectMap.get(parentId) : this._scene;
+    if (!targetParent) return;
+
+    this._pushUndo();
+
+    // Collect objects and remove from old locations
+    const objects: THREE.Object3D[] = [];
+    for (const id of dragIds) {
+      const obj = this._objectMap.get(id);
+      if (!obj) continue;
+      obj.removeFromParent();
+      objects.push(obj);
+    }
+
+    // Find the insertion point among entity children of the target
+    const entityChildren = targetParent.children.filter(
+      (c) => getUserData(c, 'entityId') !== undefined && !getUserData(c, 'editorHelper'),
+    );
+    const clampedIndex = Math.min(index, entityChildren.length);
+    const insertBefore = entityChildren[clampedIndex];
+    const threeIndex = insertBefore
+      ? targetParent.children.indexOf(insertBefore)
+      : targetParent.children.length;
+
+    // Insert at the computed position
+    for (let i = 0; i < objects.length; i++) {
+      const obj = objects[i]!;
+      targetParent.children.splice(threeIndex + i, 0, obj);
+      obj.parent = targetParent;
+    }
+    this._notify();
+  }
+
+  // --- Rename ---
+  renameEntity(id: string, name: string): void {
+    const obj = this._objectMap.get(id);
+    const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
+    if (!entity || !obj) return;
+    this._pushUndo();
+    entity.name = name;
+    obj.name = name;
+    this._notify();
+  }
+
+  // --- Visibility ---
+  toggleVisibility(id: string): void {
+    const obj = this._objectMap.get(id);
+    const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
+    if (!entity || !obj) return;
+    this._pushUndo();
+    if (entity.visible === false) {
+      delete entity.visible;
+      obj.visible = true;
+    } else {
+      entity.visible = false;
+      obj.visible = false;
+    }
+    this._notify();
+  }
+
+  // --- Locking (viewport pickability) ---
+  toggleLocked(id: string): void {
+    const obj = this._objectMap.get(id);
+    const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
+    if (!entity) return;
+    this._pushUndo();
+    if (entity.locked) {
+      delete entity.locked;
+    } else {
+      entity.locked = true;
+    }
+    this._notify();
+  }
+
+  /** Check if an entity or any ancestor is locked. */
+  isEntityLocked(id: string): boolean {
+    const obj = this._objectMap.get(id);
+    if (!obj) return false;
+    const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
+    if (!entity) return false;
+    if (entity.locked) return true;
+
+    // Walk up the Three.js parent chain
+    let parent = obj.parent;
+    while (parent) {
+      const parentEntity = getUserData(parent, 'entity') as SceneEntity | undefined;
+      if (parentEntity?.locked) return true;
+      parent = parent.parent;
+    }
+    return false;
+  }
+
+  // --- Bulk delete ---
+  deleteEntities(ids: string[]): void {
+    if (this._blockedDuringPlay('delete entities')) return;
+    this._pushUndo();
+    for (const id of ids) {
+      const obj = this._objectMap.get(id);
+      if (!obj) continue;
+      this._removeObjectFromScene(obj);
+      this._selectedEntityIds.delete(id);
+    }
+    this._notify();
+  }
+
+  // --- Transform mode ---
+  setTransformMode(mode: TransformMode): void {
+    this._transformMode = mode;
+    this._notify();
+  }
+
+  setTransformSpace(space: TransformSpace): void {
+    this._transformSpace = space;
+    this._notify();
+  }
+
+  toggleSnap(): void {
+    this._snapEnabled = !this._snapEnabled;
+    this._notify();
+  }
+
+  setSnapValues(values: Partial<{ translate: number; rotate: number; scale: number }>): void {
+    this._snapValues = { ...this._snapValues, ...values };
+    this._notify();
+  }
+
+  toggleSnapToSurface(): void {
+    this._snapToSurface = !this._snapToSurface;
+    this._notify();
+  }
+
+  setPivotMode(mode: PivotMode): void {
+    this._pivotMode = mode;
+    this._notify();
+  }
+
+  updatePivot(id: string, pivot: [number, number, number]): void {
+    const obj = this._objectMap.get(id);
+    const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
+    if (!entity) return;
+    this._pushUndo();
+    const isZero = pivot[0] === 0 && pivot[1] === 0 && pivot[2] === 0;
+    if (isZero) {
+      delete entity.pivot;
+    } else {
+      entity.pivot = pivot;
+    }
+    this._rebuildEntity(id);
+    this._notify();
+  }
+
+  toggleGrid(): void {
+    this._showGrid = !this._showGrid;
+    this._notify();
+  }
+
+  toggleHelpers(): void {
+    const anyOn = Object.values(this._helperVisibility).some((v) => v);
+    const newVal = !anyOn;
+    this._showHelpers = newVal;
+    for (const key of Object.keys(this._helperVisibility) as (keyof HelperVisibility)[]) {
+      this._helperVisibility[key] = newVal;
+    }
+    this._notify();
+  }
+
+  toggleHelperType(type: keyof HelperVisibility): void {
+    this._helperVisibility[type] = !this._helperVisibility[type];
+    this._showHelpers = Object.values(this._helperVisibility).some((v) => v);
+    this._notify();
+  }
+
+  toggleStats(): void {
+    this._showStats = !this._showStats;
+    this._notify();
+  }
+
+  setShadingMode(mode: ShadingMode): void {
+    this._shadingMode = mode;
+    // Re-shade live meshes immediately (ED1) — don't wait for a full rebuild.
+    if (this._scene) applyShadingOverride(this._scene, mode);
+    this._notify();
+  }
+
+  // --- Clipboard ---
+  copyEntities(): void {
+    // Blocked during play for a subtler reason than its siblings: copying a
+    // live, runtime-mutated descriptor into the clipboard lets a post-stop
+    // paste insert that runtime snapshot into the real document (the Ctrl+C
+    // variant of the cut-during-play hazard).
+    if (this._blockedDuringPlay('copy entities')) return;
+    this._clipboard = this.selectedEntities.map((e) => deepClone(e));
+  }
+
+  cutEntities(): void {
+    if (this._blockedDuringPlay('cut entities')) return;
+    this.copyEntities();
+    const ids = [...this._selectedEntityIds];
+    this._pushUndo();
+    for (const id of ids) {
+      const obj = this._objectMap.get(id);
+      if (!obj) continue;
+      this._removeObjectFromScene(obj);
+    }
+    this._selectedEntityIds.clear();
+    this._notify();
+  }
+
+  pasteEntities(): void {
+    if (this._blockedDuringPlay('paste')) return;
+    if (this._clipboard.length === 0 || !this._scene) return;
+    this._pushUndo();
+    const newIds: string[] = [];
+    for (const template of this._clipboard) {
+      const clone = deepClone(template);
+      const reassign = (e: SceneEntity) => {
+        e.id = crypto.randomUUID();
+        if (e.children) e.children.forEach(reassign);
+      };
+      reassign(clone);
+      clone.name = `${clone.name} (copy)`;
+
+      const obj = createEntityObject(clone);
+      obj.visible = clone.visible !== false;
+      this._scene.add(obj);
+      this._objectMap.set(clone.id!, obj);
+      registerParticles(obj, this._batchedRenderer);
+      if (clone.children) {
+        this._addChildEntities(clone.children, obj);
+      }
+      newIds.push(clone.id!);
+    }
+    this._selectedEntityIds = new Set(newIds);
+    this._notify();
+  }
+
+  // --- Tags ---
+  addTag(id: string, tag: string): void {
+    const entity = this.getEntityById(id);
+    if (!entity) return;
+    const trimmed = tag.trim();
+    if (!trimmed) return;
+    if (entity.tags?.includes(trimmed)) return;
+    this._pushUndo();
+    if (!entity.tags) entity.tags = [];
+    entity.tags.push(trimmed);
+    this._notify();
+  }
+
+  removeTag(id: string, tag: string): void {
+    const entity = this.getEntityById(id);
+    if (!entity?.tags) return;
+    const idx = entity.tags.indexOf(tag);
+    if (idx < 0) return;
+    this._pushUndo();
+    entity.tags.splice(idx, 1);
+    if (entity.tags.length === 0) delete entity.tags;
+    this._notify();
+  }
+
+  /** Collect all unique tags used in the scene. */
+  allTags(): string[] {
+    const tags = new Set<string>();
+    if (this._scene) {
+      walkEntityObjects(this._scene, (_, entity) => {
+        if (entity.tags) for (const t of entity.tags) tags.add(t);
+      });
+    }
+    return [...tags].sort();
+  }
+
+  // --- Batch mutations (multi-entity editing) ---
+  /** Push undo once, then mutate each entity by id and rebuild. */
+  batchMutate(ids: string[], mutator: (entity: SceneEntity) => void): void {
+    this._pushUndo();
+    for (const id of ids) {
+      const obj = this._objectMap.get(id);
+      const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
+      if (entity) {
+        mutator(entity);
+        this._rebuildEntity(id);
+      }
+    }
+    this._notify();
+  }
+
+  // --- Environment ---
+  updateEnvironment(partial: Partial<SceneEnvironment>): void {
+    this._pushUndo();
+    this._sceneMeta.environment = { ...this._sceneMeta.environment, ...partial };
+    this._applyEnvironment();
+    this._notify();
+  }
+
+  /** Replace the entire environment object (for removing keys). */
+  setEnvironment(env: SceneEnvironment): void {
+    this._pushUndo();
+    this._sceneMeta.environment = env;
+    this._applyEnvironment();
+    this._notify();
+  }
+
+  // --- External update (live sync from disk) ---
+
+  /**
+   * Apply an external SceneFile update (e.g. from a file watcher) without
+   * pushing undo or triggering auto-save. Diffs against current state and
+   * applies only the changes, preserving selection, undo history, and camera.
+   *
+   * `rawContent`, when provided (the watcher SSE carries the file's exact
+   * bytes), enables own-echo detection: an event whose content is exactly
+   * what we last wrote is our own save reflected back, and is skipped even
+   * if it arrives after `_ignoreExternalUntil` — the document may have moved
+   * on (undo/redo) and applying the echo would clobber the newer state.
+   */
+  applyExternalUpdate(incoming: SceneFile, rawContent?: string): void {
+    if (rawContent !== undefined && rawContent === this._lastSavedContent) return;
+    // Play-mode / ingest guard: `_scene` is the LIVE game/ingested scene while
+    // playing (see enterPlayScene) — diffing and patching it here would rebuild
+    // the RUNNING scene out from under the game/ingested adapter, and the disk
+    // change would be silently lost the moment exitPlayScene restores the real
+    // editor scene (probe: F6 in the round-1 review). Defer: keep only the
+    // latest incoming doc and apply it once play/ingest stops (see setPlayState).
+    if (this._playState !== 'stopped') {
+      this._pendingExternalUpdate = incoming;
+      return;
+    }
+    if (!this._scene) return;
+    if (Date.now() < this._ignoreExternalUntil) return;
+    assignMissingIds(incoming.entities);
+    const current = this.getDocument();
+    const diff = diffScene(current, incoming);
+
+    // No-op polls must not count toward the circuit breaker (ED6) — only a
+    // poll that actually changes something is a real sync cycle.
+    if (diff.ops.length === 0 && !diff.environmentChanged && !diff.metaChanged) return;
+    if (this._isSyncLooping()) return;
+
+    this._suppressAutoSaveUntil = Date.now() + SYNC_COOLDOWN_MS;
+
+    // Process removals first (deepest-first ordering is handled by diffScene)
+    for (const op of diff.ops) {
+      if (op.type !== 'remove') continue;
+      const obj = this._objectMap.get(op.id);
+      if (!obj) continue;
+      this._removeObjectFromScene(obj);
+      this._selectedEntityIds.delete(op.id);
+    }
+
+    // Process additions
+    for (const op of diff.ops) {
+      if (op.type !== 'add') continue;
+      const entity = { ...op.entity };
+      if (!entity.id) entity.id = crypto.randomUUID();
+      const obj = createEntityObject(entity);
+      obj.visible = entity.visible !== false;
+      const parent = op.parentId ? this._objectMap.get(op.parentId) : this._scene;
+      if (!parent) continue;
+      parent.add(obj);
+      this._objectMap.set(entity.id, obj);
+      registerParticles(obj, this._batchedRenderer);
+    }
+
+    // Process updates (property changes)
+    for (const op of diff.ops) {
+      if (op.type !== 'update') continue;
+      const obj = this._objectMap.get(op.id);
+      const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
+      if (!entity || !obj) continue;
+      // Replace properties (preserve id and children). Fields absent from the
+      // incoming entity must be deleted, not left stale (ED3) — Object.assign
+      // alone would keep removed material/physics/etc.
+      const { id: _, children: __, ...fields } = op.entity;
+      for (const key of Object.keys(entity) as (keyof SceneEntity)[]) {
+        if (key === 'id' || key === 'children') continue;
+        if (!(key in fields)) delete entity[key];
+      }
+      Object.assign(entity, fields);
+      // Sync transform to Three.js object
+      if (entity.transform) {
+        const t = entity.transform;
+        if (t.position) obj.position.set(t.position[0], t.position[1], t.position[2]);
+        if (t.rotation)
+          obj.quaternion.set(t.rotation[0], t.rotation[1], t.rotation[2], t.rotation[3]);
+        if (t.scale) obj.scale.set(t.scale[0], t.scale[1], t.scale[2]);
+      }
+      this._rebuildEntity(op.id);
+    }
+
+    // Process moves (reparent/reorder). Incremental splices against a mutating
+    // sibling list can land multi-sibling reorders wrong (ED7). Instead:
+    // 1) reparent every moved object (append for now), then
+    // 2) sort each affected parent's entity children to match the FINAL target
+    //    sibling order from the incoming document.
+    const movedParents = new Set<THREE.Object3D>();
+    for (const op of diff.ops) {
+      if (op.type !== 'move') continue;
+      const obj = this._objectMap.get(op.id);
+      if (!obj) continue;
+      obj.removeFromParent();
+      const newParent = op.parentId ? this._objectMap.get(op.parentId) : this._scene;
+      if (!newParent) continue;
+      newParent.add(obj);
+      movedParents.add(newParent);
+    }
+    if (movedParents.size > 0) {
+      // Build target sibling order (parentId | null) → [childId...] from incoming.
+      const targetOrder = new Map<string | null, string[]>();
+      const collectOrder = (list: SceneEntity[], pid: string | null): void => {
+        targetOrder.set(
+          pid,
+          list.map((e) => e.id).filter((id): id is string => Boolean(id)),
+        );
+        for (const e of list) if (e.children) collectOrder(e.children, e.id ?? null);
+      };
+      collectOrder(incoming.entities, null);
+
+      for (const parent of movedParents) {
+        const pid =
+          parent === this._scene
+            ? null
+            : ((getUserData(parent, 'entityId') as string | undefined) ?? null);
+        const order = targetOrder.get(pid);
+        if (!order) continue;
+        const rankOf = (id: string | undefined): number => {
+          const i = id ? order.indexOf(id) : -1;
+          return i < 0 ? Number.MAX_SAFE_INTEGER : i;
+        };
+        // Pull out entity children, sort to target order, re-append.
+        const entityChildren = parent.children.filter(
+          (c) => getUserData(c, 'entityId') !== undefined && !getUserData(c, 'editorHelper'),
+        );
+        for (const c of entityChildren) {
+          parent.children.splice(parent.children.indexOf(c), 1);
+        }
+        entityChildren.sort(
+          (a, b) =>
+            rankOf(getUserData(a, 'entityId') as string | undefined) -
+            rankOf(getUserData(b, 'entityId') as string | undefined),
+        );
+        for (const c of entityChildren) {
+          parent.children.push(c);
+          c.parent = parent;
+        }
+      }
+    }
+
+    // Environment
+    if (diff.environmentChanged) {
+      if (diff.newEnvironment) {
+        this._sceneMeta.environment = diff.newEnvironment;
+      } else {
+        delete this._sceneMeta.environment;
+      }
+      this._applyEnvironment();
+    }
+
+    // Metadata
+    if (diff.metaChanged && diff.newName) {
+      this._sceneMeta.name = diff.newName;
+    }
+
+    this._notify();
+  }
+
+  // --- Undo / Redo ---
+  undo(): boolean {
+    // `false` tells the undo timeline "couldn't act — put the entry back"
+    // (see UndoAdapter in authoring/undo-timeline.ts).
+    if (this._blockedDuringPlay('undo')) return false;
+    if (this._undoStack.length === 0 || !this._scene) return false;
+    const currentDoc = serializeScene(this._scene, this._sceneMeta);
+    this._redoStack.push(JSON.stringify(currentDoc));
+    const doc = JSON.parse(this._undoStack.pop()!) as SceneFile;
+    this._loadFromDoc(doc);
+    // The restored state is a document mutation like any other: mark dirty and
+    // schedule autosave. Without this, an undo after a completed autosave left
+    // the store claiming "saved" while the pre-undo state stayed on disk.
+    this._isDirty = true;
+    this._docEpoch++;
+    this._navMeshBaked = false;
+    this._scheduleAutoSave();
+    // Re-validate selection
+    for (const id of [...this._selectedEntityIds]) {
+      if (!this._objectMap.has(id)) this._selectedEntityIds.delete(id);
+    }
+    this._notify();
+    return true;
+  }
+
+  redo(): boolean {
+    if (this._blockedDuringPlay('redo')) return false;
+    if (this._redoStack.length === 0 || !this._scene) return false;
+    const currentDoc = serializeScene(this._scene, this._sceneMeta);
+    this._undoStack.push(JSON.stringify(currentDoc));
+    const doc = JSON.parse(this._redoStack.pop()!) as SceneFile;
+    this._loadFromDoc(doc);
+    // Same as undo(): the restored state must be persisted.
+    this._isDirty = true;
+    this._docEpoch++;
+    this._navMeshBaked = false;
+    this._scheduleAutoSave();
+    for (const id of [...this._selectedEntityIds]) {
+      if (!this._objectMap.has(id)) this._selectedEntityIds.delete(id);
+    }
+    this._notify();
+    return true;
+  }
+
+  // --- Document load/save ---
+
+  getDocument(): SceneFile {
+    if (!this._scene) {
+      return { version: this._sceneMeta.version, name: this._sceneMeta.name, entities: [] };
+    }
+    const doc = serializeScene(this._scene, this._sceneMeta);
+    return cleanDocument(doc);
+  }
+
+  loadDocument(doc: SceneFile, savePath?: string): void {
+    if (this._blockedDuringPlay('load document')) return;
+    assignMissingIds(doc.entities);
+    this._sceneMeta = { version: doc.version, name: doc.name };
+    if (doc.environment) this._sceneMeta.environment = doc.environment;
+    if (doc.ui) this._sceneMeta.ui = doc.ui; // preserve scene-graph UI (A1/C9)
+    this._documentType = 'scene';
+    this._selectedEntityIds.clear();
+    this._undoStack.length = 0;
+    this._redoStack.length = 0;
+    this._isDirty = false;
+    this._savePath = savePath ?? null;
+
+    if (this._scene) {
+      this._rebuildScene(doc);
+    }
+    this._notify();
+
+    // Capture a thumbnail after assets have had time to load
+    if (savePath) {
+      setTimeout(() => this._captureThumbnail(), 2000);
+    }
+  }
+
+  markClean(): void {
+    this._isDirty = false;
+    this._notify();
+  }
+
+  // --- Prefab operations ---
+
+  extractAsPrefab(id: string): PrefabFile | null {
+    const obj = this._objectMap.get(id);
+    if (!obj) return null;
+    const root = this._serializeSubtree(obj);
+    // Strip instance-specific fields from the prefab root
+    delete root.id;
+    delete root.transform;
+    delete root.prefab;
+    // Strip IDs from children too
+    walkEntities(root.children ?? [], (e) => {
+      delete e.id;
+    });
+    walkEntities([root], (e) => {
+      if (e.children && e.children.length === 0) delete e.children;
+    });
+    return { version: 1, name: root.name, root };
+  }
+
+  convertToPrefabInstance(id: string, prefabPath: string): void {
+    const obj = this._objectMap.get(id);
+    const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
+    if (!entity) return;
+    this._pushUndo();
+    const keepName = entity.name;
+    const keepId = entity.id;
+    const keepTransform = entity.transform;
+    // Clear all properties
+    for (const key of Object.keys(entity) as (keyof SceneEntity)[]) {
+      delete entity[key];
+    }
+    // Set instance properties
+    entity.name = keepName;
+    if (keepId) entity.id = keepId;
+    entity.prefab = prefabPath;
+    if (keepTransform) entity.transform = keepTransform;
+    this._rebuildEntity(id);
+    this._notify();
+  }
+
+  unpackPrefab(id: string, prefabRoot: SceneEntity): void {
+    const obj = this._objectMap.get(id);
+    const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
+    if (!entity || !entity.prefab) return;
+    // Merge BEFORE pushing undo: since T1.10 an invalid prefab+instance combo
+    // throws (schema re-validation of the merged entity), and pushing first
+    // would leave a no-op undo entry (the undo-then-bail defect class — see
+    // moveEntity/T1.12).
+    let merged: SceneEntity;
+    try {
+      merged = mergePrefabInstance(prefabRoot, entity);
+    } catch (err) {
+      console.error(`EditorStore: cannot unpack invalid prefab instance "${entity.name}":`, err);
+      return;
+    }
+    this._pushUndo();
+    for (const key of Object.keys(entity) as (keyof SceneEntity)[]) {
+      delete entity[key];
+    }
+    Object.assign(entity, merged);
+    assignMissingIds(entity.children ?? []);
+    this._rebuildEntity(id);
+    this._notify();
+  }
+
+  loadPrefab(prefab: PrefabFile, savePath?: string): void {
+    if (this._blockedDuringPlay('load prefab')) return;
+    const root = deepClone(prefab.root);
+    const doc: SceneFile = {
+      version: prefab.version,
+      name: prefab.name,
+      entities: [root],
+    };
+    assignMissingIds(doc.entities);
+    this._sceneMeta = {
+      version: prefab.version,
+      name: prefab.name,
+    };
+    this._documentType = 'prefab';
+    this._selectedEntityIds.clear();
+    this._undoStack.length = 0;
+    this._redoStack.length = 0;
+    this._isDirty = false;
+    this._savePath = savePath ?? null;
+
+    if (this._scene) {
+      this._rebuildScene(doc);
+    }
+    this._notify();
+  }
+
+  getPrefabDocument(): PrefabFile | null {
+    if (this._documentType !== 'prefab') return null;
+    const doc = this.getDocument();
+    const root = doc.entities[0];
+    if (!root) return null;
+    const cleanRoot = deepClone(root);
+    walkEntities([cleanRoot], (e) => {
+      delete e.id;
+      if (e.children && e.children.length === 0) delete e.children;
+    });
+    return { version: doc.version, name: doc.name, root: cleanRoot };
+  }
+
+  /** Update all references to an asset path across the live scene. */
+  applyAssetMove(oldPath: string, newPath: string): void {
+    // Play-mode / ingest guard: same rationale as applyExternalUpdate — this
+    // does a full serialize+rebuild of `_scene`, which is the LIVE game/ingested
+    // scene while playing (probe: F6b in the round-1 review — the running
+    // game's scene was torn down and rebuilt from under it). Defer to stop.
+    if (this._playState !== 'stopped') {
+      this._pendingAssetMove = { oldPath, newPath };
+      return;
+    }
+    if (!this._scene) return;
+    this._pushUndo();
+    // Serialize, rename, rebuild
+    const doc = serializeScene(this._scene, this._sceneMeta);
+    const renamed = applyAssetRename(doc, oldPath, newPath);
+    this._sceneMeta = { version: renamed.version, name: renamed.name };
+    if (renamed.environment) this._sceneMeta.environment = renamed.environment;
+    if (renamed.ui) this._sceneMeta.ui = renamed.ui; // preserve scene-graph UI (T1.5)
+    this._rebuildScene(renamed);
+    this._notify();
+  }
+
+  // --- Asset tabs ---
+
+  setActiveTab(key: string): void {
+    this._activeTabKey = key;
+    this._notify();
+  }
+
+  openAssetTab(assetPath: string, kind: AssetKind): void {
+    const existing = this._assetTabs.find((t) => t.key === assetPath);
+    if (existing) {
+      this._activeTabKey = existing.key;
+      this._notify();
+      return;
+    }
+    const label = assetPath.split('/').pop() ?? assetPath;
+    const tab: AssetTab = { key: assetPath, label, assetPath, kind };
+    this._assetTabs.push(tab);
+    this._activeTabKey = tab.key;
+    this._notify();
+  }
+
+  openOnlineAssetTab(online: OnlineAssetInfo): void {
+    const key = `online:${online.source}:${online.id}`;
+    const existing = this._assetTabs.find((t) => t.key === key);
+    if (existing) {
+      this._activeTabKey = existing.key;
+      this._notify();
+      return;
+    }
+    const kind: AssetKind =
+      online.type === 'model'
+        ? 'model'
+        : online.type === 'animation' || online.type === 'source'
+          ? 'source'
+          : 'image';
+    const tab: AssetTab = { key, label: online.name, assetPath: '', kind, online };
+    this._assetTabs.push(tab);
+    this._activeTabKey = tab.key;
+    this._notify();
+  }
+
+  /** Update an online asset tab to point at a local path after download. */
+  resolveOnlineAssetTab(onlineKey: string, localPath: string): void {
+    const tab = this._assetTabs.find((t) => t.key === onlineKey);
+    if (!tab) return;
+    tab.assetPath = localPath;
+    delete tab.online;
+    this._notify();
+  }
+
+  closeAssetTab(key: string): void {
+    const idx = this._assetTabs.findIndex((t) => t.key === key);
+    if (idx < 0) return;
+    this._assetTabs.splice(idx, 1);
+    if (this._activeTabKey === key) {
+      this._activeTabKey = '__inspector__';
+    }
+    this._notify();
+  }
+
+  // --- Internal helpers ---
+
+  /**
+   * Rebuild a single entity's Three.js representation after its descriptor
+   * changed. This is the single choke point for every property edit that
+   * requires tearing down and recreating the entity's Object3D (mesh/material/
+   * physics/component shape changes — see updateEntity, batchMutate,
+   * updatePivot, convertToPrefabInstance, unpackPrefab).
+   *
+   * Play-mode guard: while playing/paused, `_scene`/`_objectMap` point at the
+   * LIVE game scene (see enterPlayScene). `updateEntityPreview` disposes the
+   * old Object3D (geometry/material) and swaps in a fresh, component-less
+   * preview object — which would rip a running GameComponent's Object3D out
+   * from under it and orphan any physics body/writer targeting it (probe:
+   * F4 in the round-1 review). The descriptor mutation the caller already
+   * applied still stands (and is discarded on exitPlayScene, same as any
+   * other play-time edit) — only the destructive rebuild is skipped.
+   */
+  private _rebuildEntity(id: string): void {
+    if (!this._scene) return;
+    if (this._playState !== 'stopped') {
+      console.warn(
+        'EditorStore: property change requiring a rebuild is disabled during play mode — stop the game first.',
+      );
+      return;
+    }
+    // (Ingested unmodified-game objects are edited LIVE through the
+    // IngestAuthoringAdapter — they never flow through this first-party
+    // descriptor-rebuild path.)
+    const entity = this.getEntityById(id);
+    if (!entity) return;
+    updateEntityPreview(entity, this._objectMap, this._scene, this._batchedRenderer);
+  }
+
+  /** Full scene rebuild from a SceneFile (for load, undo, redo). */
+  private _rebuildScene(doc: SceneFile): void {
+    if (!this._scene) return;
+    this._objectMap = buildPreview(
+      doc,
+      this._scene,
+      this._shadingMode,
+      this._renderer ?? undefined,
+      this._batchedRenderer,
+    );
+    // Structure (and thus composer inputs: tagged objects / selective effects) changed.
+    this._composerVersion++;
+  }
+
+  /** Apply environment from sceneMeta to the live scene. */
+  private _applyEnvironment(): void {
+    if (!this._scene) return;
+    // Remove existing environment objects
+    const envObjs: THREE.Object3D[] = [];
+    this._scene.traverse((obj) => {
+      if (getUserData(obj, 'envObject')) envObjs.push(obj);
+    });
+    for (const obj of envObjs) obj.removeFromParent();
+    this._scene.fog = null;
+    this._scene.environment = null;
+
+    applyEnvironment(this._sceneMeta.environment, this._scene, this._renderer ?? undefined);
+    this._composerVersion++;
+  }
+
+  /** Load a SceneFile into the scene without changing undo/selection state. */
+  private _loadFromDoc(doc: SceneFile): void {
+    this._sceneMeta = { version: doc.version, name: doc.name };
+    if (doc.environment) this._sceneMeta.environment = doc.environment;
+    if (doc.ui) this._sceneMeta.ui = doc.ui; // preserve scene-graph UI through undo/redo (T1.5)
+    this._rebuildScene(doc);
+  }
+
+  /** Build nested SceneEntity[] from the Three.js hierarchy (for react-arborist). */
+  private _buildEntityTree(parent: THREE.Object3D): SceneEntity[] {
+    const result: SceneEntity[] = [];
+    for (const child of parent.children) {
+      if (getUserData(child, 'entityId') === undefined) continue;
+      if (getUserData(child, 'editorHelper')) continue;
+      const stored = getUserData(child, 'entity') as SceneEntity | undefined;
+      if (!stored) continue;
+
+      const childEntities = this._buildEntityTree(child);
+      if (childEntities.length > 0) {
+        result.push({ ...stored, children: childEntities });
+      } else if (stored.children && stored.children.length > 0) {
+        // Entity descriptor has stale children — strip them
+        const { children: _, ...rest } = stored;
+        result.push(rest as SceneEntity);
+      } else {
+        result.push(stored);
+      }
+    }
+    return result;
+  }
+}