@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/editor-store.ts

@@ -11,10 +11,12 @@
  *   - Undo / redo
  *   - Prefab resolution
  *   - Asset path rename
+ *   - Referenced material asset changes
  */
 
 import type { PersistenceProvider } from '@engine/adapter';
 import { applyAssetRename } from '@engine/scene/asset-paths';
+import { parseSceneFile } from '@engine/scene/parse';
 import {
   mergePrefabInstance,
   type PrefabFile,
@@ -30,9 +32,19 @@ import {
   getActiveAuthoring,
   hasAuthoringOverride,
 } from './authoring/active-adapter';
-import { notifyUndoableOp, registerUndoAdapter } from './authoring/undo-timeline';
-import { loadEditorState, saveEditorState, saveFile, saveThumbnail } from './editor-api';
+import {
+  loadEditorState,
+  readProjectTextFile,
+  saveEditorState,
+  saveFile,
+  saveThumbnail,
+} from './editor-api';
+import { editorConsole } from './editor-console';
 import { createEntityObject } from './entity-factory';
+import type { HistoryService } from './history/history-service';
+import { getProjectFileHistory } from './history/project-file-history';
+import { sha256Hex } from './history/snapshot-store';
+import type { ResourceDescriptor, ResourceDriver } from './history/types';
 import { diffScene } from './scene-diff';
 import type { SceneMetadata } from './scene-serializer';
 import { cleanDocument, serializeScene } from './scene-serializer';
@@ -40,6 +52,7 @@ import {
   applyEnvironment,
   applyShadingOverride,
   buildPreview,
+  clearMaterialRefCache,
   registerParticles,
   unregisterParticles,
   updateEntityPreview,
@@ -55,16 +68,10 @@ 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`.
+ * Which persistence regime the current play session exposes. D19 makes play
+ * edits ephemeral for every world count; `overlay` remains in the type while
+ * older/external session surfaces migrate, but native play no longer selects
+ * it by cardinality. `null` while not playing.
  */
 export type PlayEditRegime = 'ephemeral' | 'overlay' | null;
 
@@ -90,15 +97,6 @@ export interface OnlineAssetInfo {
   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;
@@ -106,6 +104,7 @@ export interface HelperVisibility {
   audio: boolean;
   splines: boolean;
   navmesh: boolean;
+  skeletons: boolean;
 }
 
 export type ViewportAction =
@@ -119,24 +118,38 @@ export type ViewportAction =
       fov?: number;
     };
 
-const MAX_UNDO = 50;
 /** Cooldown (ms) to prevent tight feedback loops between auto-save and external updates. */
 const SYNC_COOLDOWN_MS = 500;
+const sceneEncoder = new TextEncoder();
+const sceneDecoder = new TextDecoder();
 
 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 {
+/**
+ * Ensure every entity has a UUID and a children array. Mutates in place.
+ * Returns `true` iff at least one entity was missing an `id` and got one
+ * assigned here — callers that persist to disk (`loadDocument`) use this to
+ * know the freshly-assigned ids need writing back, not just holding in
+ * memory (see that call site's comment for why: an id assigned here but
+ * never persisted is exactly the `apply-diff`/`vgai status` id-mismatch
+ * trap).
+ */
+export function assignMissingIds(entities: SceneEntity[]): boolean {
+  let assignedAny = false;
   const walk = (list: SceneEntity[]) => {
     for (const e of list) {
-      if (!e.id) e.id = crypto.randomUUID();
+      if (!e.id) {
+        e.id = crypto.randomUUID();
+        assignedAny = true;
+      }
       if (!e.children) e.children = [];
       walk(e.children);
     }
   };
   walk(entities);
+  return assignedAny;
 }
 
 /** Walk entity Object3Ds in the scene graph and call fn on each. */
@@ -163,17 +176,6 @@ function walkEntities(entities: SceneEntity[], fn: (e: SceneEntity) => void): vo
 }
 
 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
@@ -209,6 +211,7 @@ export class EditorStore {
     audio: true,
     splines: true,
     navmesh: true,
+    skeletons: false,
   };
   private _showStats = false;
   private _shadingMode: ShadingMode = 'solid';
@@ -229,16 +232,21 @@ export class EditorStore {
    * (undo/redo), and applying the echo would clobber the newer state.
    */
   private _lastSavedContent: string | null = null;
+  /** #131 — consecutive saves skipped because the on-disk file changed under
+   *  the editor and could not be adopted (see `_resolveSaveConflict`). */
+  private _saveConflictSkips = 0;
   /** 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 _history: HistoryService | null = null;
+  private _historyDescriptor: ResourceDescriptor | null = null;
+  private _unregisterHistoryDriver: (() => void) | null = null;
+  private _pendingHistoryEdit: { label: string; beforeBytes: Uint8Array } | null = null;
+  private _historyGestureActive = false;
+  private _historyRevision = 0;
   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. */
@@ -270,6 +278,8 @@ export class EditorStore {
    * `applyAssetMove`.
    */
   private _pendingExternalUpdate: SceneFile | null = null;
+  /** A referenced material changed while play owned the live scene. */
+  private _pendingMaterialRefresh = false;
   private _pendingAssetMove: { oldPath: string; newPath: string } | null = null;
 
   // --- Bind to scene graph (call once at editor init) ---
@@ -299,11 +309,174 @@ export class EditorStore {
 
   getSnapshot = (): number => this._version;
 
+  get projectHistory(): HistoryService | null {
+    return this._history;
+  }
+
+  async saveMaterialAsReference(id: string, path: string, content: string): Promise<boolean> {
+    return this._writeFileAndMutateDocument(
+      path,
+      content,
+      { label: `Save ${path.split('/').pop() ?? 'Material'}`, kind: 'material' },
+      (entity) => {
+        if (entity.id !== id) return false;
+        delete entity.material;
+        entity.materialRef = path;
+        return true;
+      },
+    );
+  }
+
+  async savePrefabAndConvertInstance(id: string, path: string, content: string): Promise<boolean> {
+    return this._writeFileAndMutateDocument(
+      path,
+      content,
+      { label: `Save ${path.split('/').pop() ?? 'Prefab'}`, kind: 'prefab' },
+      (entity) => {
+        if (entity.id !== id) return false;
+        const replacement: SceneEntity = {
+          id: entity.id,
+          name: entity.name,
+          prefab: `/${path}`,
+          ...(entity.transform ? { transform: entity.transform } : {}),
+        };
+        for (const key of Object.keys(entity) as (keyof SceneEntity)[]) delete entity[key];
+        Object.assign(entity, replacement);
+        return true;
+      },
+    );
+  }
+
+  private async _writeFileAndMutateDocument(
+    path: string,
+    content: string,
+    options: { label: string; kind: 'material' | 'prefab' },
+    mutate: (entity: SceneEntity) => boolean,
+  ): Promise<boolean> {
+    const history = this._history;
+    const descriptor = this._historyDescriptor;
+    if (!history || !descriptor || this._playState !== 'stopped') return false;
+    this._finishHistoryEdit();
+    const document = structuredClone(this.getDocument());
+    let changed = false;
+    walkEntities(document.entities, (entity) => {
+      if (!changed) changed = mutate(entity);
+    });
+    if (!changed) return false;
+    const documentBytes = sceneEncoder.encode(JSON.stringify(cleanDocument(document), null, 2));
+    return getProjectFileHistory(history).writeWithResources(
+      path,
+      content,
+      { ...options, contentType: 'application/json' },
+      [{ resource: descriptor.key, bytes: documentBytes, contentType: 'application/json' }],
+    );
+  }
+
   private _notify(): void {
+    if (!this._interactiveActive && !this._historyGestureActive) this._finishHistoryEdit();
     this._version++;
     for (const fn of this._listeners) fn();
   }
 
+  attachHistory(history: HistoryService): void {
+    if (this._history === history) return;
+    if (this._history) throw new Error('EditorStore is already attached to project history.');
+    this._history = history;
+    this._bindDocumentHistory(
+      this._documentType,
+      this._savePath ??
+        (this._documentType === 'prefab'
+          ? 'prefabs/__untitled__.prefab.json'
+          : 'scenes/__untitled__.vscn.json'),
+    );
+  }
+
+  private _bindDocumentHistory(kind: 'scene' | 'prefab', location: string): void {
+    const history = this._history;
+    if (!history) return;
+    const projectLocation = location.replace(/^\/+/, '');
+    const normalizedLocation = `project://${projectLocation}`;
+    if (
+      this._historyDescriptor?.kind === kind &&
+      this._historyDescriptor.location === normalizedLocation
+    ) {
+      return;
+    }
+    if (this._historyDescriptor) history.expireResources([this._historyDescriptor.key]);
+    this._unregisterHistoryDriver?.();
+    this._historyDescriptor = history.registry.registerProject(kind, projectLocation);
+    const driver: ResourceDriver = {
+      descriptor: this._historyDescriptor,
+      capture: async () => {
+        const bytes = this._captureDocumentBytes();
+        return {
+          revision: this._historyRevision,
+          contentType: 'application/json',
+          bytes,
+          sha256: await sha256Hex(bytes),
+        };
+      },
+      preflight: async (expected) => {
+        const actualSha256 = await sha256Hex(this._captureDocumentBytes());
+        return actualSha256 === expected.sha256
+          ? { ok: true }
+          : {
+              ok: false,
+              reason: 'content-conflict',
+              actualRevision: this._historyRevision,
+              actualSha256,
+            };
+      },
+      restore: async (snapshot) => {
+        const doc = JSON.parse(
+          sceneDecoder.decode(history.snapshots.read(snapshot).bytes),
+        ) as SceneFile;
+        this._pendingHistoryEdit = null;
+        this._loadFromDoc(doc);
+        this._historyRevision++;
+        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();
+      },
+      estimateBytes: (snapshot) => snapshot.byteLength,
+    };
+    this._unregisterHistoryDriver = history.registerDriver(driver);
+  }
+
+  private _captureDocumentBytes(): Uint8Array {
+    return sceneEncoder.encode(JSON.stringify(this.getDocument(), null, 2));
+  }
+
+  private _finishHistoryEdit(): void {
+    const pending = this._pendingHistoryEdit;
+    const history = this._history;
+    const descriptor = this._historyDescriptor;
+    if (!pending || !history || !descriptor) return;
+    this._pendingHistoryEdit = null;
+    const afterBytes = this._captureDocumentBytes();
+    this._historyRevision++;
+    void history
+      .recordAppliedTransaction(
+        { label: pending.label, resources: [descriptor.key], scope: 'project' },
+        [
+          {
+            resource: descriptor.key,
+            beforeBytes: pending.beforeBytes,
+            afterBytes,
+            contentType: 'application/json',
+          },
+        ],
+      )
+      .catch(() => {
+        // The structured error is exposed by HistoryService.getSnapshot().
+      });
+  }
+
   // --- Viewport action dispatch ---
   // Panels call these methods; ViewportPanel subscribes and executes them.
 
@@ -420,27 +593,16 @@ export class EditorStore {
     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 {
+    if (name === this._sceneMeta.name) return;
+    this._beginHistoryEdit('Rename Scene');
     this._sceneMeta.name = name;
-    // No undo — name changes are lightweight, same as old behavior
+    this._notify();
   }
 
   // --- Selection ---
@@ -493,10 +655,10 @@ export class EditorStore {
     return 'saved';
   }
   get canUndo(): boolean {
-    return this._undoStack.length > 0;
+    return this._history?.getSnapshot().canUndo ?? false;
   }
   get canRedo(): boolean {
-    return this._redoStack.length > 0;
+    return this._history?.getSnapshot().canRedo ?? false;
   }
   get showGrid(): boolean {
     return this._showGrid;
@@ -507,6 +669,21 @@ export class EditorStore {
   get helperVisibility(): Readonly<HelperVisibility> {
     return this._helperVisibility;
   }
+  isSkeletonVisible(id: string): boolean {
+    return Boolean(getUserData(this._objectMap.get(id), 'skeletonVisible'));
+  }
+
+  setSkeletonVisible(id: string, visible: boolean): void {
+    const object = this._objectMap.get(id);
+    if (!object) return;
+    setUserData(object, 'skeletonVisible', visible);
+    object.traverse((child) => {
+      if (getUserData(child, 'editorHelperType') !== 'skeletons') return;
+      setUserData(child, 'skeletonEnabled', visible);
+      child.visible = visible || this._helperVisibility.skeletons;
+    });
+    this._notify();
+  }
   get showStats(): boolean {
     return this._showStats;
   }
@@ -521,6 +698,12 @@ export class EditorStore {
   }
   setSavePath(path: string | null): void {
     this._savePath = path;
+    // #131: the disk state of the NEW path is unknown — a stale baseline from
+    // the previous path would false-flag a save-as over an existing file as a
+    // conflict. Null keeps the guard inert until the first write establishes
+    // a fresh baseline (save-as intentionally overwrites its target).
+    this._lastSavedContent = null;
+    this._saveConflictSkips = 0;
     this._notify();
   }
   get documentType(): 'scene' | 'prefab' {
@@ -548,7 +731,7 @@ export class EditorStore {
    * 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
+   * `setSceneName`). 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
@@ -676,6 +859,10 @@ export class EditorStore {
       this._pendingAssetMove = null;
       this.applyAssetMove(oldPath, newPath);
     }
+    if (this._pendingMaterialRefresh) {
+      this._pendingMaterialRefresh = false;
+      this.refreshMaterialAssets();
+    }
   }
 
   // --- Viewport tab ---
@@ -709,13 +896,6 @@ export class EditorStore {
     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;
@@ -782,20 +962,21 @@ export class EditorStore {
     return result;
   }
 
-  // --- Undo stack ---
+  // --- Project history ---
 
-  /** Public: push a snapshot before a drag begins (called by viewport). */
+  /** Capture the document before a transform drag begins (called by viewport). */
   pushUndoSnapshot(): void {
-    this._pushUndo();
+    this._beginHistoryEdit('Transform Selection');
+    if (this._history) this._historyGestureActive = true;
   }
 
-  private _pushUndo(): void {
+  private _beginHistoryEdit(label = 'Edit Scene'): 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
+    // that runtime state into project history: 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
@@ -803,20 +984,19 @@ export class EditorStore {
     // 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;
+    this._history?.assertCanRecordAppliedChange();
     // 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);
+      if (this._history) {
+        this._pendingHistoryEdit = {
+          label,
+          beforeBytes: sceneEncoder.encode(JSON.stringify(cleanDocument(doc), null, 2)),
+        };
+      }
     }
     this._isDirty = true;
     this._docEpoch++;
@@ -831,15 +1011,16 @@ export class EditorStore {
    * onChange. Pair with endInteractiveEdit(). Mirrors the viewport gizmo's live
    * drag (pushUndoSnapshot at start, no-undo live updates, commit at end).
    */
-  beginInteractiveEdit(): void {
+  beginInteractiveEdit(label = 'Edit Properties'): void {
     if (this._interactiveActive) return;
-    this._pushUndo();
+    this._beginHistoryEdit(label);
     this._interactiveActive = true;
   }
 
   /** End a coalesced interactive edit gesture. */
   endInteractiveEdit(): void {
     this._interactiveActive = false;
+    this._finishHistoryEdit();
   }
 
   private _scheduleAutoSave(): void {
@@ -883,7 +1064,7 @@ export class EditorStore {
   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`
+    // while playing/paused (see enterPlayScene). `_beginHistoryEdit`/`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
@@ -913,6 +1094,10 @@ export class EditorStore {
     void provider.save().catch((err) => {
       this._lastSaveFailed = true;
       console.warn('[EditorStore] Auto-save threw — changes are NOT saved to disk.', err);
+      // W4: the failure must also land in the EDITOR console — the utility
+      // policy reveals Console on saveState → 'failed', so the entry the
+      // user sees there is real.
+      editorConsole.error('Auto-save failed — changes are NOT saved to disk.', 'editor');
       this._notify();
     });
   }
@@ -969,6 +1154,38 @@ export class EditorStore {
     if (!this._savePath || !this._scene) return false;
     const content = JSON.stringify(this.getDocument(), null, 2);
     const epoch = this._docEpoch;
+
+    // #131 — unobserved-external-change guard. If the bytes on disk no longer
+    // match what this editor last wrote (or loaded — `_captureDiskBaseline`),
+    // someone else (an agent, another tool) edited the file while our watch
+    // channel missed it (drvfs inotify gaps, poll latency). Blind-writing the
+    // in-memory doc would permanently destroy that edit — the exact data-loss
+    // path found in blind run #4's investigation. Adopt the disk version
+    // instead: worst case that reverts the human's last ~300ms gesture, while
+    // blind-writing loses ALL of the external writer's work. Best-effort by
+    // design: no baseline yet (null) or an unreadable disk falls through to
+    // the normal write.
+    if (this._lastSavedContent !== null) {
+      let disk: string | null = null;
+      try {
+        disk = await readProjectTextFile(this._savePath);
+      } catch {
+        disk = null;
+      }
+      if (disk !== null && disk !== this._lastSavedContent && disk !== content) {
+        const outcome = this._resolveSaveConflict(disk);
+        if (outcome === 'adopted') return false; // store now matches disk; nothing to write
+        if (outcome === 'retry') {
+          this._scheduleAutoSave();
+          return false;
+        }
+        // 'overwrite': disk content is unadoptable (unparseable / non-scene
+        // document / retries exhausted) — proceed to the loud write below so
+        // dirty changes are never stranded off-disk forever.
+      }
+    }
+    this._saveConflictSkips = 0;
+
     this._ignoreExternalUntil = Date.now() + SYNC_COOLDOWN_MS;
     this._lastSavedContent = content;
     try {
@@ -984,31 +1201,121 @@ export class EditorStore {
         this._saveEditorStateIfDue();
       } else {
         console.warn('[EditorStore] Save failed — changes are NOT saved to disk.');
+        // W4: mirror into the editor Console — the utility policy reveals it
+        // on saveState → 'failed', so the entry there must be real. Identical
+        // consecutive failures collapse via count.
+        editorConsole.error(
+          `Save failed — changes are NOT saved to disk (${this._savePath}).`,
+          'editor',
+        );
       }
       return ok;
     } catch (err) {
       this._lastSaveFailed = true;
       this._notify();
       console.warn('[EditorStore] Save threw — changes are NOT saved to disk.', err);
+      editorConsole.error(
+        `Save failed — changes are NOT saved to disk (${this._savePath}).`,
+        'editor',
+      );
       return false;
     }
   }
 
+  /**
+   * #131 — decide what `saveNow()` does about a file that changed on disk
+   * since our last known write. Returns:
+   * - `'adopted'`  — the disk version was applied into the store (or was a
+   *   semantic no-op, e.g. an external formatter run); the doc is clean and
+   *   nothing should be written.
+   * - `'retry'`    — could not adopt right now (sync circuit breaker, a torn
+   *   mid-write read, a non-scene document); the caller reschedules autosave
+   *   and skips this write.
+   * - `'overwrite'`— adoption failed repeatedly (`_saveConflictSkips` > 3);
+   *   write anyway, LOUDLY, so dirty changes are never stranded forever
+   *   (an invalid file on disk gets restored to validity by the write).
+   */
+  private _resolveSaveConflict(disk: string): 'adopted' | 'retry' | 'overwrite' {
+    if (this._documentType === 'scene') {
+      let incoming: SceneFile | null = null;
+      try {
+        incoming = parseSceneFile(JSON.parse(disk));
+      } catch {
+        incoming = null; // torn mid-write read or genuinely invalid JSON
+      }
+      if (incoming) {
+        // Our own save cooldown must not block adopting a conflict we just
+        // detected ourselves.
+        this._ignoreExternalUntil = 0;
+        const applied = this.applyExternalUpdate(incoming, disk);
+        if (applied) {
+          this._lastSavedContent = disk;
+          this._isDirty = false;
+          this._saveConflictSkips = 0;
+          const msg =
+            `${this._savePath} changed on disk while the editor held unsaved changes — ` +
+            'adopted the disk version; re-apply your last edit if it disappeared';
+          editorConsole.warn(msg, 'scene');
+          console.warn(`[EditorStore] ${msg}`);
+          this._notify();
+          return 'adopted';
+        }
+        // Dropped by the sync circuit breaker — its own 5s window bounds the
+        // retries; do NOT count these toward the overwrite escalation (a sync
+        // storm is exactly when a forced write would ping-pong).
+        return 'retry';
+      }
+    }
+    this._saveConflictSkips++;
+    if (this._saveConflictSkips <= 3) {
+      console.warn(
+        `[EditorStore] ${this._savePath} changed on disk but could not be adopted ` +
+          `(unparseable or non-scene document) — retrying (${this._saveConflictSkips}/3) before overwriting.`,
+      );
+      return 'retry';
+    }
+    const msg =
+      `${this._savePath} changed on disk but the disk version could not be adopted — ` +
+      'OVERWRITING it with the editor version to avoid stranding unsaved changes';
+    editorConsole.error(msg, 'scene');
+    console.warn(`[EditorStore] ${msg}`);
+    return 'overwrite';
+  }
+
+  /**
+   * #131 — baseline `_lastSavedContent` with the exact bytes on disk right
+   * after a document load, so the save-conflict guard is armed from t=0 (an
+   * agent's first external edit typically lands before the human's first
+   * save). Fire-and-forget: a failed read just leaves the guard inert (null
+   * baseline), which is the pre-#131 behavior. The `_savePath` / null checks
+   * make a late resolution harmless if the user switched documents or a save
+   * already established a fresher baseline. Known millisecond-scale race: an
+   * external edit landing between the load and this read becomes the
+   * baseline, so the next save would not flag it — the SSE/poll watch channel
+   * covers that window.
+   */
+  private async _captureDiskBaseline(path: string): Promise<void> {
+    try {
+      const raw = await readProjectTextFile(path);
+      if (raw !== null && this._savePath === path && this._lastSavedContent === null) {
+        this._lastSavedContent = raw;
+      }
+    } catch {
+      /* mocked/absent backend or unreadable file — guard stays inert */
+    }
+  }
+
   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.
+   * Render the bound camera's current view to a PNG data URL at `size`x`size`.
+   * Autosave thumbnails request game content only; an explicit SDK/editor
+   * viewport capture requests every camera layer so grid/helpers/gizmos are
+   * represented honestly. Both use the same offscreen render-target technique,
+   * so neither needs `preserveDrawingBuffer` on the live WebGL canvas.
    */
-  private _renderViewportImage(size: number): string | null {
+  private _renderViewportImage(size: number, includeEditorLayers: boolean): string | null {
     if (!this._renderer || !this._scene || !this._camera) return null;
 
     const renderSize = size * 2; // render at 2x then downscale for crisp result
@@ -1017,11 +1324,14 @@ export class EditorStore {
     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
+    if (includeEditorLayers) {
+      camera.layers.enableAll();
+    } else {
+      camera.layers.disableAll();
+      camera.layers.enable(0); // clean project thumbnail: game content only
+    }
 
     renderer.setPixelRatio(1);
     renderer.setRenderTarget(renderTarget);
@@ -1063,7 +1373,7 @@ export class EditorStore {
     const now = Date.now();
     if (now - this._lastThumbnailTime < EditorStore.THUMBNAIL_INTERVAL_MS) return;
     this._lastThumbnailTime = now;
-    const dataUrl = this._renderViewportImage(EditorStore.THUMBNAIL_SIZE);
+    const dataUrl = this._renderViewportImage(EditorStore.THUMBNAIL_SIZE, false);
     if (dataUrl) saveThumbnail(dataUrl);
   }
 
@@ -1074,7 +1384,7 @@ export class EditorStore {
    * `ViewportPanel` has mounted).
    */
   captureViewportImage(size = EditorStore.THUMBNAIL_SIZE): string | null {
-    return this._renderViewportImage(size);
+    return this._renderViewportImage(size, true);
   }
 
   // --- Editor state persistence ---
@@ -1174,7 +1484,7 @@ export class EditorStore {
     const obj = this._objectMap.get(id);
     const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
     if (!entity || !obj) return;
-    this._pushUndo();
+    this._beginHistoryEdit(`Edit ${entity.name}`);
     Object.assign(entity, partial);
     this._rebuildEntity(id);
     this._notify();
@@ -1189,7 +1499,7 @@ export class EditorStore {
     const obj = this._objectMap.get(id);
     const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
     if (!entity || !obj) return;
-    this._pushUndo();
+    this._beginHistoryEdit(`Transform ${entity.name}`);
     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]);
@@ -1242,6 +1552,7 @@ export class EditorStore {
       this._navMeshBaked = false;
       this._scheduleAutoSave();
     }
+    this._historyGestureActive = false;
     this._notify();
   }
 
@@ -1250,7 +1561,7 @@ export class EditorStore {
     if (!this._scene) return;
     if (!entity.id) entity.id = crypto.randomUUID();
     assignMissingIds(entity.children ?? []);
-    this._pushUndo();
+    this._beginHistoryEdit(`Add ${entity.name}`);
 
     const obj = createEntityObject(entity);
     obj.visible = entity.visible !== false;
@@ -1305,7 +1616,9 @@ export class EditorStore {
     if (this._blockedDuringPlay('delete entity')) return;
     const obj = this._objectMap.get(id);
     if (!obj) return;
-    this._pushUndo();
+    this._beginHistoryEdit(
+      `Delete ${(getUserData(obj, 'entity') as SceneEntity | undefined)?.name ?? 'Entity'}`,
+    );
     this._removeObjectFromScene(obj);
     this._selectedEntityIds.delete(id);
     this._notify();
@@ -1341,7 +1654,7 @@ export class EditorStore {
     reassign(cloneEntity);
     cloneEntity.name = `${entity.name} (copy)`;
 
-    this._pushUndo();
+    this._beginHistoryEdit(`Duplicate ${entity.name}`);
 
     // Create object and insert after original
     const cloneObj = createEntityObject(cloneEntity);
@@ -1396,7 +1709,9 @@ export class EditorStore {
     const targetParent = parentId ? this._objectMap.get(parentId) : this._scene;
     if (!targetParent) return;
 
-    this._pushUndo();
+    this._beginHistoryEdit(
+      `Move ${dragIds.length === 1 ? 'Entity' : `${dragIds.length} Entities`}`,
+    );
 
     // Collect objects and remove from old locations
     const objects: THREE.Object3D[] = [];
@@ -1431,7 +1746,7 @@ export class EditorStore {
     const obj = this._objectMap.get(id);
     const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
     if (!entity || !obj) return;
-    this._pushUndo();
+    this._beginHistoryEdit(`Rename ${entity.name}`);
     entity.name = name;
     obj.name = name;
     this._notify();
@@ -1442,7 +1757,7 @@ export class EditorStore {
     const obj = this._objectMap.get(id);
     const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
     if (!entity || !obj) return;
-    this._pushUndo();
+    this._beginHistoryEdit(`${entity.visible === false ? 'Show' : 'Hide'} ${entity.name}`);
     if (entity.visible === false) {
       delete entity.visible;
       obj.visible = true;
@@ -1458,7 +1773,7 @@ export class EditorStore {
     const obj = this._objectMap.get(id);
     const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
     if (!entity) return;
-    this._pushUndo();
+    this._beginHistoryEdit(`${entity.locked ? 'Unlock' : 'Lock'} ${entity.name}`);
     if (entity.locked) {
       delete entity.locked;
     } else {
@@ -1488,7 +1803,7 @@ export class EditorStore {
   // --- Bulk delete ---
   deleteEntities(ids: string[]): void {
     if (this._blockedDuringPlay('delete entities')) return;
-    this._pushUndo();
+    this._beginHistoryEdit(`Delete ${ids.length} ${ids.length === 1 ? 'Entity' : 'Entities'}`);
     for (const id of ids) {
       const obj = this._objectMap.get(id);
       if (!obj) continue;
@@ -1533,7 +1848,7 @@ export class EditorStore {
     const obj = this._objectMap.get(id);
     const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
     if (!entity) return;
-    this._pushUndo();
+    this._beginHistoryEdit(`Set ${entity.name} Pivot`);
     const isZero = pivot[0] === 0 && pivot[1] === 0 && pivot[2] === 0;
     if (isZero) {
       delete entity.pivot;
@@ -1591,7 +1906,7 @@ export class EditorStore {
     if (this._blockedDuringPlay('cut entities')) return;
     this.copyEntities();
     const ids = [...this._selectedEntityIds];
-    this._pushUndo();
+    this._beginHistoryEdit(`Cut ${ids.length} ${ids.length === 1 ? 'Entity' : 'Entities'}`);
     for (const id of ids) {
       const obj = this._objectMap.get(id);
       if (!obj) continue;
@@ -1604,7 +1919,9 @@ export class EditorStore {
   pasteEntities(): void {
     if (this._blockedDuringPlay('paste')) return;
     if (this._clipboard.length === 0 || !this._scene) return;
-    this._pushUndo();
+    this._beginHistoryEdit(
+      `Paste ${this._clipboard.length} ${this._clipboard.length === 1 ? 'Entity' : 'Entities'}`,
+    );
     const newIds: string[] = [];
     for (const template of this._clipboard) {
       const clone = deepClone(template);
@@ -1636,7 +1953,7 @@ export class EditorStore {
     const trimmed = tag.trim();
     if (!trimmed) return;
     if (entity.tags?.includes(trimmed)) return;
-    this._pushUndo();
+    this._beginHistoryEdit(`Add Tag to ${entity.name}`);
     if (!entity.tags) entity.tags = [];
     entity.tags.push(trimmed);
     this._notify();
@@ -1647,7 +1964,7 @@ export class EditorStore {
     if (!entity?.tags) return;
     const idx = entity.tags.indexOf(tag);
     if (idx < 0) return;
-    this._pushUndo();
+    this._beginHistoryEdit(`Remove Tag from ${entity.name}`);
     entity.tags.splice(idx, 1);
     if (entity.tags.length === 0) delete entity.tags;
     this._notify();
@@ -1667,7 +1984,7 @@ export class EditorStore {
   // --- 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();
+    this._beginHistoryEdit(`Edit ${ids.length} ${ids.length === 1 ? 'Entity' : 'Entities'}`);
     for (const id of ids) {
       const obj = this._objectMap.get(id);
       const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
@@ -1681,7 +1998,7 @@ export class EditorStore {
 
   // --- Environment ---
   updateEnvironment(partial: Partial<SceneEnvironment>): void {
-    this._pushUndo();
+    this._beginHistoryEdit('Edit Environment');
     this._sceneMeta.environment = { ...this._sceneMeta.environment, ...partial };
     this._applyEnvironment();
     this._notify();
@@ -1689,14 +2006,59 @@ export class EditorStore {
 
   /** Replace the entire environment object (for removing keys). */
   setEnvironment(env: SceneEnvironment): void {
-    this._pushUndo();
+    this._beginHistoryEdit('Replace Environment');
     this._sceneMeta.environment = env;
     this._applyEnvironment();
     this._notify();
   }
 
+  /**
+   * Re-apply the AUTHORED environment to the live scene and bump
+   * `composerVersion` — the restore half of the world-hidden eye's
+   * environment suppression (`world-hidden-viewport.ts`'s
+   * `suppressWorldEnvironment`). Truth is `_sceneMeta.environment`; nothing
+   * is snapshotted at suppress time. No undo push (nothing authored changed)
+   * and no notify — the caller (`editor-viewport.ts`'s `syncFromStore`) runs
+   * INSIDE a notify, and `ViewportPanel`'s subscriber checks
+   * `composerVersion` right after `syncFromStore` returns, so the composer
+   * rebuild this triggers is picked up in the same tick.
+   */
+  reapplyEnvironment(): void {
+    this._applyEnvironment();
+  }
+
+  /** Rebuild the stopped authoring scene after a referenced `.mat.json`
+   * changes. This is view maintenance only: descriptors/history/dirty state
+   * stay untouched. */
+  refreshMaterialAssets(): void {
+    clearMaterialRefCache();
+    if (!this._scene) return;
+    if (this._playState !== 'stopped') {
+      this._pendingMaterialRefresh = true;
+      return;
+    }
+    this._pendingMaterialRefresh = false;
+    this._rebuildScene(this.getDocument());
+    this._notify();
+  }
+
   // --- External update (live sync from disk) ---
 
+  /**
+   * Whether `rawContent` (exact bytes from a file-watcher event) is exactly
+   * what this editor itself last wrote to `_savePath` — i.e. an autosave
+   * echo, not a genuine external edit. Callers that want to gate on "did
+   * something ELSE change this file" (e.g. the dirty-notice check in
+   * `DefaultEditorLayout`'s `onSceneChanged`, run-3 friction #1) use this to
+   * tell the two apart before deciding whether to notify — `applyExternalUpdate`
+   * performs the same comparison internally but only AFTER already deciding
+   * to apply, which is too late for a caller that wants to skip notifying on
+   * a plain echo.
+   */
+  isOwnEchoContent(rawContent: string): boolean {
+    return rawContent === this._lastSavedContent;
+  }
+
   /**
    * Apply an external SceneFile update (e.g. from a file watcher) without
    * pushing undo or triggering auto-save. Diffs against current state and
@@ -1707,9 +2069,16 @@ export class EditorStore {
    * 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.
+   *
+   * Returns whether the store now semantically matches `incoming`: `true`
+   * when the diff was applied OR was a no-op (own echo / zero ops); `false`
+   * when the update was deferred (play mode) or dropped (sync cooldown,
+   * circuit breaker, no scene). `saveNow()`'s unobserved-external-change
+   * guard (#131) relies on this to know whether adopting the disk version
+   * actually happened before it marks the document clean.
    */
-  applyExternalUpdate(incoming: SceneFile, rawContent?: string): void {
-    if (rawContent !== undefined && rawContent === this._lastSavedContent) return;
+  applyExternalUpdate(incoming: SceneFile, rawContent?: string): boolean {
+    if (rawContent !== undefined && rawContent === this._lastSavedContent) return true;
     // 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
@@ -1718,18 +2087,18 @@ export class EditorStore {
     // latest incoming doc and apply it once play/ingest stops (see setPlayState).
     if (this._playState !== 'stopped') {
       this._pendingExternalUpdate = incoming;
-      return;
+      return false;
     }
-    if (!this._scene) return;
-    if (Date.now() < this._ignoreExternalUntil) return;
+    if (!this._scene) return false;
+    if (Date.now() < this._ignoreExternalUntil) return false;
     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;
+    if (diff.ops.length === 0 && !diff.environmentChanged && !diff.metaChanged) return true;
+    if (this._isSyncLooping()) return false;
 
     this._suppressAutoSaveUntil = Date.now() + SYNC_COOLDOWN_MS;
 
@@ -1856,49 +2225,6 @@ export class EditorStore {
     }
 
     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;
   }
 
@@ -1914,22 +2240,48 @@ export class EditorStore {
 
   loadDocument(doc: SceneFile, savePath?: string): void {
     if (this._blockedDuringPlay('load document')) return;
-    assignMissingIds(doc.entities);
+    const idsWereAssigned = 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._pendingHistoryEdit = null;
+    this._historyGestureActive = false;
     this._isDirty = false;
     this._savePath = savePath ?? null;
+    // #131: reset the save-conflict baseline (a previous document's bytes
+    // must never be compared against this document's disk file), then
+    // re-arm it with this file's exact on-disk bytes.
+    this._lastSavedContent = null;
+    this._saveConflictSkips = 0;
+    if (savePath) void this._captureDiskBaseline(savePath);
+    this._bindDocumentHistory('scene', savePath ?? 'scenes/__untitled__.vscn.json');
 
     if (this._scene) {
       this._rebuildScene(doc);
     }
     this._notify();
 
+    // The `apply-diff`/`vgai status` id-persistence trap: an entity loaded
+    // from a file with no (or partial) `id` fields gets one assigned above,
+    // IN MEMORY ONLY — `assignMissingIds` never touches disk. `vgai status`
+    // reports these freshly-assigned ids (they're the only ids this running
+    // session has), but until this block existed nothing ever wrote them
+    // back to `savePath`, so the exact id `status` just handed out could
+    // never resolve against the file `apply-diff` reads (it matches strictly
+    // on the FILE's persisted id). Marking the document dirty and going
+    // through the ordinary autosave path here closes the loop the same way
+    // any other edit persists: the file catches up to the ids this session
+    // is already handing out, automatically, ~300ms after load, with no
+    // user/agent action required. Gated on `savePath` for the same reason
+    // the disk-baseline capture above is: a path-less doc (e.g. the no-
+    // project fallback scene) is explicitly never written until the user
+    // gives it a real save target.
+    if (idsWereAssigned && savePath) {
+      this._isDirty = true;
+      this._scheduleAutoSave();
+    }
+
     // Capture a thumbnail after assets have had time to load
     if (savePath) {
       setTimeout(() => this._captureThumbnail(), 2000);
@@ -1965,7 +2317,7 @@ export class EditorStore {
     const obj = this._objectMap.get(id);
     const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
     if (!entity) return;
-    this._pushUndo();
+    this._beginHistoryEdit(`Convert ${entity.name} to Prefab`);
     const keepName = entity.name;
     const keepId = entity.id;
     const keepTransform = entity.transform;
@@ -1997,7 +2349,7 @@ export class EditorStore {
       console.error(`EditorStore: cannot unpack invalid prefab instance "${entity.name}":`, err);
       return;
     }
-    this._pushUndo();
+    this._beginHistoryEdit(`Unpack ${entity.name}`);
     for (const key of Object.keys(entity) as (keyof SceneEntity)[]) {
       delete entity[key];
     }
@@ -2022,10 +2374,17 @@ export class EditorStore {
     };
     this._documentType = 'prefab';
     this._selectedEntityIds.clear();
-    this._undoStack.length = 0;
-    this._redoStack.length = 0;
+    this._pendingHistoryEdit = null;
+    this._historyGestureActive = false;
     this._isDirty = false;
     this._savePath = savePath ?? null;
+    // #131: same baseline reset+re-arm as loadDocument. Prefab conflicts are
+    // not adoptable (applyExternalUpdate speaks SceneFile), but the baseline
+    // still gates the loud retry/overwrite path instead of a silent clobber.
+    this._lastSavedContent = null;
+    this._saveConflictSkips = 0;
+    if (savePath) void this._captureDiskBaseline(savePath);
+    this._bindDocumentHistory('prefab', savePath ?? 'prefabs/__untitled__.prefab.json');
 
     if (this._scene) {
       this._rebuildScene(doc);
@@ -2057,76 +2416,23 @@ export class EditorStore {
       return;
     }
     if (!this._scene) return;
-    this._pushUndo();
+    this._beginHistoryEdit('Update Asset References');
     // 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();
-  }
+  // (The former right-rail asset-tab model — `AssetTab`, `openAssetTab`,
+  // `openEntityAssetTab`, `openOnlineAssetTab`, `resolveOnlineAssetTab`,
+  // `closeAssetTab`, `setActiveTab` — was deleted in W2 of the workspace-
+  // shell program: asset viewers open as CENTER workspace documents via
+  // `components/asset-documents.tsx` + `workspace-document-registry.ts`
+  // (docs/workspace-shell/W0-INVENTORY.md rows R2–R7), and the Inspector is
+  // never displaced from the right rail again.)
 
   // --- Internal helpers ---
 
@@ -2196,7 +2502,6 @@ export class EditorStore {
   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);
   }