@vgai/editor 0.4.0 → 0.4.1

package/src/components/workspace-dock.css

@@ -95,6 +95,22 @@
   min-width: 0;
 }
 
+.vgai-dock-tab-close {
+  width: 22px;
+  min-width: 22px;
+  height: 22px;
+  margin-left: 2px;
+  padding: 0;
+  border-radius: var(--vgai-radius-sm);
+  color: var(--vgai-text-3);
+}
+
+.vgai-dock-tab-close:hover,
+.vgai-dock-tab-close:focus-visible {
+  color: var(--vgai-text-1);
+  background: var(--vgai-bg-3);
+}
+
 /* Runtime/world surfaces and file-backed resource documents are different
    navigation families. The adjacent-family selector makes the seam follow
    the actual Dockview rail when the user moves tabs. */

package/src/editor-api.ts

@@ -175,6 +175,7 @@ export interface AssetEntry {
   name: string;
   type: 'file' | 'directory';
   size: number;
+  modifiedAt: number;
 }
 
 /** List files and folders in a directory under public/. */
@@ -186,6 +187,7 @@ export async function listAssets(root: string, dir: string): Promise<AssetEntry[
       name: e.name,
       type: e.type === 'dir' ? 'directory' : 'file',
       size: e.size ?? 0,
+      modifiedAt: e.mtime ?? 0,
     }));
   } catch {
     return [];
@@ -387,17 +389,38 @@ export function connectHarnessChatEvents(
   };
 }
 
-/** Report the current editor state to the server (called by command-listener). */
-export async function reportEditorState(state: Record<string, unknown>): Promise<void> {
-  try {
-    await fetch(`${BASE}/state`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ ...state, _clientId: EDITOR_CLIENT_ID }),
-    });
-  } catch {
-    /* best-effort */
+// State reports can be triggered by several browser-owned transitions at once
+// (a Play click changes both play state and the active viewport, for example).
+// Keep only the newest waiting snapshot and serialize requests so an older,
+// slower POST can never land after a newer one and roll `/__editor/state` back.
+let pendingEditorState: Record<string, unknown> | null = null;
+let editorStateReportDrain: Promise<void> | null = null;
+
+async function drainEditorStateReports(): Promise<void> {
+  while (pendingEditorState) {
+    const state = pendingEditorState;
+    pendingEditorState = null;
+    try {
+      await fetch(`${BASE}/state`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ ...state, _clientId: EDITOR_CLIENT_ID }),
+      });
+    } catch {
+      /* best-effort */
+    }
   }
+  editorStateReportDrain = null;
+  // A caller cannot interleave with the synchronous block above, but keep
+  // this defensive restart so future refactors cannot strand a late report.
+  if (pendingEditorState) editorStateReportDrain = drainEditorStateReports();
+}
+
+/** Report the current editor state to the server (called by command-listener). */
+export function reportEditorState(state: Record<string, unknown>): Promise<void> {
+  pendingEditorState = state;
+  editorStateReportDrain ??= drainEditorStateReports();
+  return editorStateReportDrain;
 }
 
 /** Report a command result back to the server so the SDK/CLI gets the response.
@@ -775,7 +798,7 @@ export async function flushLogEntries(entries: LogEntry[]): Promise<boolean> {
 // SSRF-allowlist reasons to stay server-side) that writes into
 // `<project>/public/asset-library/...` via raw `node:fs`, not
 // `StorageBackend` — there is no browser-mode equivalent. The server-only
-// Asset Library navigator is unavailable in browser mode; the functions below are a
+// Asset Library document is absent in browser mode; the functions below are a
 // defensive backstop for any other caller: read-only lookups degrade to an
 // honest empty result (no fetch attempted), the one mutating call
 // (`downloadOnlineAsset`) throws instead.
@@ -818,6 +841,33 @@ export interface AssetFileOption {
   includes?: { relativePath: string; url: string; size: number }[];
 }
 
+export type AssetDeliveryIssueCode =
+  | 'offline'
+  | 'quota-limited'
+  | 'license-blocked'
+  | 'unavailable'
+  | 'provider-error';
+
+export class AssetDeliveryError extends Error {
+  constructor(
+    readonly code: AssetDeliveryIssueCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'AssetDeliveryError';
+  }
+}
+
+export function assetDeliveryIssueMessage(code: AssetDeliveryIssueCode): string {
+  return {
+    offline: 'Network delivery is offline. SSD assets remain available.',
+    'quota-limited': 'The remote provider quota is exhausted. Retry after the provider resets it.',
+    'license-blocked': 'This delivery is blocked because its license terms are not accepted.',
+    unavailable: 'No healthy SSD, cloud, or remote delivery is available for this variant.',
+    'provider-error': 'The remote provider could not return delivery metadata. Retry the request.',
+  }[code];
+}
+
 export interface OnlineAssetPreview {
   path: string;
   format: string;
@@ -861,6 +911,7 @@ export async function loadDownloadedAssets(): Promise<void> {
     const data = (await res.json()) as {
       downloaded: { source: string; id: string; path: string }[];
     };
+    downloadedAssetPaths.clear();
     for (const entry of data.downloaded) {
       downloadedAssetPaths.set(assetCacheKey(entry.source, entry.id), `/${entry.path}`);
     }
@@ -889,7 +940,10 @@ export async function searchOnlineAssets(params: {
   if (params.limit != null) qs.set('limit', String(params.limit));
 
   const res = await fetch(`${BASE}/asset-library/search?${qs}`);
-  if (!res.ok) return { assets: [], total: 0 };
+  if (!res.ok) {
+    const body = (await res.json().catch(() => null)) as { error?: string } | null;
+    throw new Error(body?.error ?? `Asset Library search failed (${res.status}).`);
+  }
   return (await res.json()) as { assets: OnlineAsset[]; total: number };
 }
 
@@ -897,10 +951,26 @@ export async function searchOnlineAssets(params: {
 export async function getOnlineAssetFiles(source: string, id: string): Promise<AssetFileOption[]> {
   if (isBrowserMode()) return [];
   const qs = new URLSearchParams({ source, id });
-  const res = await fetch(`${BASE}/asset-library/files?${qs}`);
+  let res: Response;
+  try {
+    res = await fetch(`${BASE}/asset-library/files?${qs}`);
+  } catch (error) {
+    throw new AssetDeliveryError(
+      'offline',
+      error instanceof Error ? error.message : assetDeliveryIssueMessage('offline'),
+    );
+  }
   if (!res.ok) {
     const body = (await res.json().catch(() => null)) as { error?: string } | null;
-    throw new Error(body?.error ?? `Asset delivery lookup failed (${res.status}).`);
+    const code: AssetDeliveryIssueCode =
+      res.status === 403
+        ? 'license-blocked'
+        : res.status === 429
+          ? 'quota-limited'
+          : res.status === 404
+            ? 'unavailable'
+            : 'provider-error';
+    throw new AssetDeliveryError(code, body?.error ?? assetDeliveryIssueMessage(code));
   }
   const data = (await res.json()) as { files: AssetFileOption[] };
   return data.files;
@@ -918,6 +988,21 @@ export async function getOnlineAssetPreview(
   return (await res.json()) as OnlineAssetPreview;
 }
 
+export interface AppliedAssetImportHistory {
+  assetPath: string;
+  beforeToken: string;
+  afterToken: string;
+}
+
+export interface DownloadOnlineAssetResult {
+  ok: boolean;
+  path?: string;
+  alreadyExists?: boolean;
+  provenanceOperationId?: string;
+  history?: AppliedAssetImportHistory;
+  error?: string;
+}
+
 /** Download an online asset into the project's public/asset-library/ folder. */
 export async function downloadOnlineAsset(params: {
   source: string;
@@ -925,8 +1010,10 @@ export async function downloadOnlineAsset(params: {
   name: string;
   url: string;
   format: string;
+  jobId?: string;
   includes?: { relativePath: string; url: string; size: number }[];
-}): Promise<{ ok: boolean; path?: string; alreadyExists?: boolean; error?: string }> {
+  signal?: AbortSignal;
+}): Promise<DownloadOnlineAssetResult> {
   if (isBrowserMode()) {
     throw new Error(
       'Downloading online assets needs the Node dev server (Poly Haven/ambientcg access is proxied ' +
@@ -936,14 +1023,10 @@ export async function downloadOnlineAsset(params: {
   const res = await fetch(`${BASE}/asset-library/download`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(params),
+    body: JSON.stringify({ ...params, signal: undefined }),
+    ...(params.signal ? { signal: params.signal } : {}),
   });
-  const result = (await res.json()) as {
-    ok: boolean;
-    path?: string;
-    alreadyExists?: boolean;
-    error?: string;
-  };
+  const result = (await res.json()) as DownloadOnlineAssetResult;
   // Cache the local path on success
   if (result.ok && result.path) {
     downloadedAssetPaths.set(assetCacheKey(params.source, params.id), `/${result.path}`);
@@ -952,6 +1035,60 @@ export async function downloadOnlineAsset(params: {
   return result;
 }
 
+/** Re-run a saved catalog import plan and atomically replace its project directory. */
+export async function reimportProjectAsset(
+  assetPath: string,
+  plan: import('./asset-workflow/import-contract').AssetImportPlan,
+  signal?: AbortSignal,
+): Promise<{ ok: boolean; path?: string; provenanceOperationId?: string; error?: string }> {
+  if (isBrowserMode()) {
+    throw new Error('Reimport requires the Node editor server and the original catalog delivery.');
+  }
+  const response = await fetch(`${BASE}/asset-library/reimport`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ assetPath, plan }),
+    ...(signal ? { signal } : {}),
+  });
+  const result = (await response.json()) as {
+    ok: boolean;
+    path?: string;
+    provenanceOperationId?: string;
+    error?: string;
+  };
+  if (!response.ok) throw new Error(result.error ?? `Reimport failed (${response.status}).`);
+  return result;
+}
+
+/** Capture a content-addressed server snapshot for one imported asset directory. */
+export async function captureProjectAssetHistory(assetPath: string): Promise<string> {
+  if (isBrowserMode()) throw new Error('Imported asset history requires the Node editor server.');
+  const response = await fetch(`${BASE}/asset-library/history/capture`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ assetPath }),
+  });
+  const result = (await response.json()) as { ok?: boolean; token?: string; error?: string };
+  if (!response.ok || !result.token) {
+    throw new Error(result.error ?? `Asset history capture failed (${response.status}).`);
+  }
+  return result.token;
+}
+
+/** Restore an exact imported-directory + provenance snapshot during undo/redo. */
+export async function restoreProjectAssetHistory(assetPath: string, token: string): Promise<void> {
+  if (isBrowserMode()) throw new Error('Imported asset history requires the Node editor server.');
+  const response = await fetch(`${BASE}/asset-library/history/restore`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ assetPath, token }),
+  });
+  if (!response.ok) {
+    const result = (await response.json().catch(() => null)) as { error?: string } | null;
+    throw new Error(result?.error ?? `Asset history restore failed (${response.status}).`);
+  }
+}
+
 /** Get Poly Haven categories for a given asset type. */
 export async function getAssetLibraryCategories(type: string, source?: string): Promise<string[]> {
   if (isBrowserMode()) return [];

package/src/editor-store.ts

@@ -15,6 +15,7 @@
  */
 
 import type { PersistenceProvider } from '@engine/adapter';
+import type { ViewportShadingMode } from '@engine/render/viewport-shading';
 import { applyAssetRename } from '@engine/scene/asset-paths';
 import { parseSceneFile } from '@engine/scene/parse';
 import {
@@ -50,7 +51,6 @@ import type { SceneMetadata } from './scene-serializer';
 import { cleanDocument, serializeScene } from './scene-serializer';
 import {
   applyEnvironment,
-  applyShadingOverride,
   buildPreview,
   clearMaterialRefCache,
   registerParticles,
@@ -65,7 +65,7 @@ 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';
+export type ShadingMode = ViewportShadingMode;
 
 /**
  * Which persistence regime the current play session exposes. D19 makes play
@@ -98,6 +98,7 @@ export interface OnlineAssetInfo {
 }
 
 export interface HelperVisibility {
+  bounds: boolean;
   lights: boolean;
   cameras: boolean;
   colliders: boolean;
@@ -205,6 +206,7 @@ export class EditorStore {
   private _showGrid = true;
   private _showHelpers = true;
   private _helperVisibility: HelperVisibility = {
+    bounds: false,
     lights: true,
     cameras: true,
     colliders: true,
@@ -1887,8 +1889,8 @@ export class EditorStore {
 
   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);
+    // View-only state. The viewport applies it during its own render and
+    // restores native materials before returning to editor/game code.
     this._notify();
   }
 
@@ -2474,7 +2476,6 @@ export class EditorStore {
     this._objectMap = buildPreview(
       doc,
       this._scene,
-      this._shadingMode,
       this._renderer ?? undefined,
       this._batchedRenderer,
     );

package/src/editor-viewport.ts

@@ -20,8 +20,9 @@ import {
   suppressWorldEnvironment,
 } from './authoring/world-hidden-viewport';
 import { isWorldHidden } from './authoring/world-session-state';
+import { downloadOnlineAssetWithHistory } from './components/asset-editor-persistence';
 import { themeVars, zIndex } from './design-system';
-import { downloadOnlineAsset, getDownloadedAssetPath, getOnlineAssetFiles } from './editor-api';
+import { getDownloadedAssetPath, getOnlineAssetFiles } from './editor-api';
 import { EDITOR_LAYER } from './editor-layers';
 import type { EditorStore } from './editor-store';
 import { applyEntityGizmos } from './gizmo-registry';
@@ -519,8 +520,12 @@ export class EditorViewport {
     const MIN = 0.5;
     const color = new THREE.Color(0x579eff);
 
-    // Add new
-    for (const id of this._store.selectedEntityIds) {
+    // Selection bounds are always visible. The Bounds diagnostic expands the
+    // same native BoxHelper path to every authored/runtime entity.
+    const ids = this._store.helperVisibility.bounds
+      ? this._objectMap.keys()
+      : this._store.selectedEntityIds;
+    for (const id of ids) {
       const obj = this._objectMap.get(id);
       if (!obj) continue;
 
@@ -1946,8 +1951,8 @@ export class EditorViewport {
         });
       };
 
-      const doDownload = (dlParams: Parameters<typeof downloadOnlineAsset>[0]) => {
-        downloadOnlineAsset(dlParams)
+      const doDownload = (dlParams: Parameters<typeof downloadOnlineAssetWithHistory>[0]) => {
+        downloadOnlineAssetWithHistory(dlParams)
           .then((result) => {
             if (result.ok && result.path) {
               resolveEntity(result.path);
@@ -1969,7 +1974,7 @@ export class EditorViewport {
       };
 
       if (online.url) {
-        const dlParams: Parameters<typeof downloadOnlineAsset>[0] = {
+        const dlParams: Parameters<typeof downloadOnlineAssetWithHistory>[0] = {
           source: online.source,
           id: online.id,
           name: online.name,
@@ -1988,7 +1993,7 @@ export class EditorViewport {
             });
             return;
           }
-          const params: Parameters<typeof downloadOnlineAsset>[0] = {
+          const params: Parameters<typeof downloadOnlineAssetWithHistory>[0] = {
             source: online.source,
             id: online.id,
             name: online.name,

package/src/game-viewport-state.ts

@@ -0,0 +1,28 @@
+import type { ViewportShadingMode } from '@engine/render/viewport-shading';
+import { setGameViewportShadingMode } from './play-mode';
+
+let mode: ViewportShadingMode = 'solid';
+let version = 0;
+const listeners = new Set<() => void>();
+
+export function gameViewportShadingMode(): ViewportShadingMode {
+  return mode;
+}
+
+export function setGameDocumentShadingMode(next: ViewportShadingMode): void {
+  const changed = mode !== next;
+  mode = next;
+  setGameViewportShadingMode(next);
+  if (!changed) return;
+  version++;
+  for (const listener of listeners) listener();
+}
+
+export function subscribeGameViewportShading(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function gameViewportShadingVersion(): number {
+  return version;
+}

package/src/model-thumbnail.ts

@@ -138,22 +138,22 @@ export class ModelThumbnailRenderer {
     this.scene.add(group);
 
     // Auto-frame the camera around the model
-    const box = new THREE.Box3().setFromObject(group);
+    const box = modelPreviewBounds(group);
     if (box.isEmpty()) {
       this.scene.remove(group);
       throw new Error('Model contains no previewable geometry.');
     }
     const center = box.getCenter(new THREE.Vector3());
-    const size = box.getSize(new THREE.Vector3());
-    const maxDim = Math.max(size.x, size.y, size.z) || 1;
+    const sphere = box.getBoundingSphere(new THREE.Sphere());
     const fovRad = (this.camera.fov * Math.PI) / 180;
-    const dist = (maxDim / (2 * Math.tan(fovRad / 2))) * 1.3; // 1.3× padding
+    const dist = (Math.max(sphere.radius, 0.0001) / Math.sin(fovRad / 2)) * 1.18;
+    const direction = new THREE.Vector3(0.65, 0.45, 0.65).normalize();
 
     // Position camera at a 3/4 angle (slightly above, rotated 30° from front)
     this.camera.position.set(
-      center.x + dist * 0.65,
-      center.y + dist * 0.45,
-      center.z + dist * 0.65,
+      center.x + dist * direction.x,
+      center.y + dist * direction.y,
+      center.z + dist * direction.z,
     );
     this.camera.lookAt(center);
     this.camera.near = dist * 0.01;
@@ -165,10 +165,14 @@ export class ModelThumbnailRenderer {
     else this.renderer.setClearColor(0x000000, 0);
     this.renderer.clear();
     this.renderer.render(this.scene, this.camera);
+    const outputCanvas = strengthenThinThumbnailSilhouette(
+      this.renderer.domElement,
+      spec.background === 'neutral',
+    );
     const dataUrl =
       spec.output === 'webp'
-        ? this.renderer.domElement.toDataURL('image/webp', 0.86)
-        : this.renderer.domElement.toDataURL('image/png');
+        ? outputCanvas.toDataURL('image/webp', 0.86)
+        : outputCanvas.toDataURL('image/png');
 
     // Clean up the loaded GLTF to free GPU memory
     this.scene.remove(group);
@@ -207,6 +211,90 @@ export class ModelThumbnailRenderer {
   }
 }
 
+function strengthenThinThumbnailSilhouette(
+  source: HTMLCanvasElement,
+  neutralBackground: boolean,
+): HTMLCanvasElement {
+  const canvas = document.createElement('canvas');
+  canvas.width = source.width;
+  canvas.height = source.height;
+  const context = canvas.getContext('2d', { willReadFrequently: true });
+  if (!context) return source;
+  context.drawImage(source, 0, 0);
+  const image = context.getImageData(0, 0, canvas.width, canvas.height);
+  const visible = new Uint8Array(canvas.width * canvas.height);
+  let visibleCount = 0;
+  for (let pixel = 0; pixel < visible.length; pixel++) {
+    const offset = pixel * 4;
+    const isVisible = neutralBackground
+      ? Math.abs(image.data[offset]! - 32) > 3 ||
+        Math.abs(image.data[offset + 1]! - 36) > 3 ||
+        Math.abs(image.data[offset + 2]! - 42) > 3
+      : image.data[offset + 3]! > 8;
+    if (isVisible) {
+      visible[pixel] = 1;
+      visibleCount++;
+    }
+  }
+  const ratio = visibleCount / visible.length;
+  if (ratio < 0.0001) return canvas;
+  const original = new Uint8ClampedArray(image.data);
+  if (neutralBackground) {
+    for (let pixel = 0; pixel < visible.length; pixel++) {
+      if (!visible[pixel]) continue;
+      const offset = pixel * 4;
+      const luminance =
+        original[offset]! * 0.2126 +
+        original[offset + 1]! * 0.7152 +
+        original[offset + 2]! * 0.0722;
+      if (luminance >= 88) continue;
+      const lift = 88 - luminance;
+      image.data[offset] = Math.min(255, original[offset]! + lift);
+      image.data[offset + 1] = Math.min(255, original[offset + 1]! + lift);
+      image.data[offset + 2] = Math.min(255, original[offset + 2]! + lift);
+    }
+  }
+  const dilationPasses = ratio < 0.004 ? 2 : ratio < 0.02 ? 1 : 0;
+  let currentVisible = visible;
+  for (let pass = 0; pass < dilationPasses; pass++) {
+    const nextVisible = currentVisible.slice();
+    const passPixels = new Uint8ClampedArray(image.data);
+    for (let y = 1; y < canvas.height - 1; y++) {
+      for (let x = 1; x < canvas.width - 1; x++) {
+        const pixel = y * canvas.width + x;
+        if (currentVisible[pixel]) continue;
+        const neighbor = [pixel - 1, pixel + 1, pixel - canvas.width, pixel + canvas.width].find(
+          (candidate) => currentVisible[candidate],
+        );
+        if (neighbor === undefined) continue;
+        const targetOffset = pixel * 4;
+        const sourceOffset = neighbor * 4;
+        image.data.set(passPixels.subarray(sourceOffset, sourceOffset + 4), targetOffset);
+        nextVisible[pixel] = 1;
+      }
+    }
+    currentVisible = nextVisible;
+  }
+  context.putImageData(image, 0, 0);
+  return canvas;
+}
+
+/** Bind-pose geometry bounds avoid malformed/outlier skin transforms shrinking a preview to a dot. */
+export function modelPreviewBounds(model: THREE.Object3D): THREE.Box3 {
+  model.updateWorldMatrix(true, true);
+  const bounds = new THREE.Box3();
+  const candidate = new THREE.Box3();
+  model.traverseVisible((object) => {
+    const renderable = object as THREE.Mesh | THREE.Line | THREE.Points;
+    if (!renderable.geometry) return;
+    if (!renderable.geometry.boundingBox) renderable.geometry.computeBoundingBox();
+    if (!renderable.geometry.boundingBox) return;
+    candidate.copy(renderable.geometry.boundingBox).applyMatrix4(object.matrixWorld);
+    bounds.union(candidate);
+  });
+  return bounds;
+}
+
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: This format dispatcher keeps each Three.js loader path visible in one place.
 export async function loadModelThumbnailObject(
   spec: ModelThumbnailSpec & { format: ModelThumbnailFormat },

package/src/play-mode.ts

@@ -18,6 +18,7 @@ import type { PerformanceProfiler } from '@engine/dev/performance-profiler';
 import type { GameComponentClass } from '@engine/ecs/game-component';
 import * as gameComponentModule from '@engine/ecs/game-component';
 import { logHmrSwapMiss } from '@engine/ecs/hmr-swap-report';
+import type { ViewportShadingMode } from '@engine/render/viewport-shading';
 import type { GameSession } from '@engine/runtime/create-runtime';
 import {
   type DebugVirtualInputTarget,
@@ -688,6 +689,23 @@ export function getGameAudio() {
   return null;
 }
 
+/** Apply a render-only diagnostic mode to every compatible live Three root. */
+export function setGameViewportShadingMode(mode: ViewportShadingMode): number {
+  if (!_session?.game) return 0;
+  let applied = 0;
+  for (const world of _session.game.roots) {
+    if (!isFirstPartyMounted(world.mounted)) continue;
+    world.mounted.setViewportShadingMode(mode);
+    applied++;
+  }
+  return applied;
+}
+
+/** Honest capability check for the Game toolbar's first-party Three diagnostic views. */
+export function gameViewportShadingSupported(): boolean {
+  return Boolean(_session?.game.roots.some((world) => isFirstPartyMounted(world.mounted)));
+}
+
 /** Get the running game's scene (for editor Scene tab rendering). */
 export function getGameScene(): THREE.Scene | null {
   return _session?.scene ?? null;
@@ -829,11 +847,20 @@ async function enterPlayModeInner(explicitSeed?: number): Promise<void> {
   // Patch console → editorConsole tagged [game]
   patchConsole();
 
-  // Start log session and register sink for JSONL persistence
-  await startLogSession();
+  // Start log session and register sink for JSONL persistence. Start, every
+  // flush, and end share ONE permanent promise tail. `exitPlayMode()` stays
+  // synchronous for UI callers, but a restart's start is queued after the
+  // prior run's final flush/end; otherwise that late end closes the NEW
+  // server session and every later 200ms flush receives a 409. Keeping start
+  // on the tail also handles Stop arriving while start itself is in flight:
+  // Stop's end queues behind it, then the epoch check below prevents the
+  // cancelled run from installing a sink/interval after Stop.
+  const logSessionStart = _logFlushChain.then(() => startLogSession());
+  _logFlushChain = logSessionStart;
+  await logSessionStart;
+  if (epoch !== _playEpoch) return;
   _pendingEntries = [];
   _lastPersistedDebugEventSeq = 0;
-  _logFlushChain = Promise.resolve();
   editorConsole.setSink((entry: ConsoleEntry) => {
     // Wave 5 (AC-A1.5's play-log half): stamp {tick, simT} from the live
     // session's built-in `time` provider so log entries correlate

package/src/project-tool-discovery.ts

@@ -24,7 +24,7 @@
 
 import { connectToolFileEvents } from './asset-events';
 import { onProjectChange } from './project-manager';
-import { refreshProjectTools } from './tool-loader';
+import { refreshProjectToolContributions } from './tool-loader';
 
 /**
  * Start the project-tool discovery lifecycle: one immediate discovery pass,
@@ -32,10 +32,10 @@ import { refreshProjectTools } from './tool-loader';
  * Returns a stop function that disconnects both subscriptions (the pass in
  * flight is left to finish — `refreshProjectTools` never throws).
  */
-export function startProjectToolDiscovery(): () => void {
-  void refreshProjectTools();
-  const stopProjectWatch = onProjectChange(() => void refreshProjectTools());
-  const stopToolFileWatch = connectToolFileEvents(() => void refreshProjectTools());
+export function startProjectToolContributionDiscovery(): () => void {
+  void refreshProjectToolContributions();
+  const stopProjectWatch = onProjectChange(() => void refreshProjectToolContributions());
+  const stopToolFileWatch = connectToolFileEvents(() => void refreshProjectToolContributions());
   return () => {
     stopProjectWatch();
     stopToolFileWatch();