@vgai/editor 0.2.0 → 0.4.0-canary.20260715.1

package/src/workspace-state-persistence.ts

@@ -0,0 +1,455 @@
+/**
+ * W5 (docs/EDITOR-WORKSPACE-SHELL-TODO.md §6.2/§9 W5 — inventory rows
+ * B17/R8) — PERSISTED WORKSPACE STATE: Dockview's serialized panel tree plus
+ * the open authored documents + active document. Restored on boot, written
+ * through (debounced) on every change. Dockview owns every physical concern:
+ * groups, sizes, tab order, collapsed edge groups, floating panels, and the
+ * maximized group. Manual hierarchy openness is NOT here — it persists in its
+ * own store (`hierarchy-expansion-state.ts`, §6.1), same key discipline.
+ *
+ * STORAGE DECISION (recorded): `localStorage`, key
+ * `vgai:workspace-state:v8`, holding a map keyed PER PROJECT by
+ * `getCurrentProject().rootPath` (the same project identity
+ * `hierarchy-expansion-state.ts` established — it prevents one game's layout
+ * leaking into another, and `rootPath` is the durable cross-session
+ * identity). Why localStorage and NOT a project-scoped metadata file
+ * (including the game manifest): layout is per-user/per-machine CONVENIENCE,
+ * not project
+ * truth — writing it into the project would dirty the user's repo from mere
+ * UI fiddling (the harness fence "no persistent scene/data edits" names
+ * exactly this hazard), would break read-only hosted `?project=` sessions,
+ * and would fight the precedent that hierarchy openness (the other §6.2
+ * persisted preference) already lives in localStorage.
+ *
+ * DOCUMENT RESTORE RULES (§9/W5 "persist+restore only documents that can
+ * truthfully reopen — verify on restore, drop silently if gone"):
+ *  - scene/game/world: NEVER persisted here. Scene and Game are opened
+ *    unconditionally by `CenterDocuments.syncCenterDocuments`; manifest
+ *    world documents are rediscovered from the active composite. Their
+ *    Dockview panels still persist as layout geometry, but none need a
+ *    synthetic restorable-document record.
+ *  - asset documents: persisted only for real file-backed specs (a serving
+ *    path). Verified via `projectFileExists()` (storage-first stat, HTTP HEAD
+ *    fallback — an existence-only probe; unlike the prefab/scene loaders'
+ *    `readProjectTextFile`, this never downloads the asset body just to check
+ *    it is still there). Asset-Lab (`asset-lab:entity:*`) and unresolved
+ *    online (`online:*`) documents are NOT persisted: a live-entity lab
+ *    session and a remote detail view are not truthfully re-resolvable from a
+ *    cold boot.
+ *  - data documents: verified against `loadedDataFiles()` after an awaited
+ *    `refreshDataFiles()` — a deleted/renamed `.data.json` is dropped.
+ *  - tool documents: `openToolDocument` self-verifies against the discovered
+ *    tool store (awaited `refreshProjectTools()` first) — unknown ids open
+ *    nothing.
+ *  - story documents: verified against the story registry after an awaited
+ *    `refreshProjectStories()` — module must load ok AND still export the
+ *    story name.
+ *  - static shell documents (`Data Assets`, `Build Profiles`): always
+ *    truthfully reopenable (Build Profiles only in server mode). Asset
+ *    Library is a permanent navigator tab, so Dockview restores its physical
+ *    placement without fabricating a center document.
+ *  - live-observation tools are never center documents. A legacy persisted
+ *    `workspace:profiler` entry migrates into the bottom Debugger; live
+ *    XState machines cannot restore because reload ended their bindings.
+ *
+ * Write-through is debounced (300ms trailing) and flushed on `pagehide`, so
+ * an immediate reload still captures the last change. Subscriptions install
+ * only AFTER the async restore finishes — a half-restored open-set must
+ * never overwrite the stored one. That wait is BOUNDED (`RESTORE_TIMEOUT_MS`):
+ * a hung verification fetch (e.g. a stalled asset-existence probe) must never
+ * block write-through + pagehide-flush installation for the whole session —
+ * layout/open-tab state is convenience state, not project truth, so
+ * availability beats completeness here. If the restore itself keeps running
+ * past the timeout, its later document-opens still land normally; only the
+ * subscription install is time-boxed, not the restore itself.
+ */
+
+import type { DockviewApi, SerializedDockview } from 'dockview-react';
+import { assetDocumentSpec, openAssetDocument } from './components/asset-documents';
+import {
+  BUILD_PROFILES_DOCUMENT_ID,
+  openBuildProfilesDocument,
+} from './components/build-documents';
+import { SCENE_DOCUMENT_ID } from './components/CenterDocuments';
+import {
+  DATA_ASSETS_DOCUMENT_ID,
+  loadedDataFiles,
+  openDataAssetsDocument,
+  openDataDocument,
+  refreshDataFiles,
+} from './components/data-documents';
+import { openDebuggerPanel } from './components/debugger-panel-state';
+import {
+  openStoryDocsDocument,
+  openStoryDocument,
+  storyDocumentState,
+} from './components/story-documents';
+import { openToolDocument } from './components/tool-documents';
+import { projectFileExists } from './editor-api';
+import { getEditorMode } from './editor-mode';
+import type { AssetKind } from './editor-store';
+import {
+  harnessChat,
+  hydrateHarnessChatLayout,
+  subscribeHarnessChatLayout,
+} from './harness-chat-layout';
+import { getCurrentProject } from './project-manager';
+import { getProjectStoryModules, refreshProjectStories } from './stories/story-registry';
+import { refreshProjectTools } from './tool-loader';
+import {
+  activateWorkspaceDocument,
+  activeWorkspaceDocumentId,
+  openWorkspaceDocuments,
+  subscribeWorkspaceDocuments,
+} from './workspace-document-registry';
+
+// v6 flattens the short-lived nested Project > Assets > source navigation.
+// Local Assets and the online Library are peer Dockview tabs in the visible
+// group below Hierarchy; Data and Stories keep their contextual/document
+// entry points instead of masquerading as permanent navigation locations.
+// v7 resets v6's short-lived four-column layout: Agent moved from the left to
+// the right and the role-specific default widths replaced equalized columns.
+// v8 introduces one isolated center document per manifest world plus the
+// world-surface/resource tab-family seam. A v7 layout cannot name those
+// panels and can restore center documents into a navigator group, so reset
+// that physical layout once instead of guessing at user intent.
+const STORAGE_KEY = 'vgai:workspace-state:v8';
+const WRITE_DEBOUNCE_MS = 300;
+/** Bound on the document-restore verification before write-through installs
+ *  anyway (module header's "wait is BOUNDED" rule). */
+const RESTORE_TIMEOUT_MS = 10_000;
+const LEGACY_PROFILER_DOCUMENT_ID = 'workspace:profiler';
+
+/** One persisted, restorable document (see the module header's rules). */
+export type PersistedDocument =
+  | { readonly t: 'asset'; readonly id: string; readonly path: string; readonly assetKind: string }
+  | { readonly t: 'data'; readonly id: string; readonly path: string }
+  | { readonly t: 'tool'; readonly id: string; readonly toolId: string }
+  | {
+      readonly t: 'story';
+      readonly id: string;
+      readonly modulePath: string;
+      readonly storyName: string;
+      readonly view?: 'preview' | 'docs';
+    }
+  | { readonly t: 'static'; readonly id: string };
+
+export interface PersistedWorkspaceState {
+  /** Dockview owns Agent geometry; this flag records whether the optional panel exists. */
+  readonly chat?: { collapsed: boolean };
+  readonly layout?: SerializedDockview;
+  readonly documents?: { open: PersistedDocument[]; activeId: string | null };
+}
+
+/** The narrow store surface every document open function needs (they all
+ *  declare the same T6.3 hand-off contract). */
+export interface WorkspaceStateStore {
+  setActiveViewportTab(tab: 'scene' | 'game'): void;
+}
+
+function browserStorage(): Storage | null {
+  try {
+    return typeof window === 'undefined' ? null : window.localStorage;
+  } catch {
+    return null;
+  }
+}
+
+function projectIdentity(): string {
+  return getCurrentProject()?.rootPath ?? '__unscoped__';
+}
+
+/** Read one project's persisted state (exported for tests). */
+export function readPersistedWorkspaceState(projectId: string): PersistedWorkspaceState | null {
+  const storage = browserStorage();
+  if (!storage) return null;
+  try {
+    const all = JSON.parse(storage.getItem(STORAGE_KEY) ?? '{}') as Record<
+      string,
+      PersistedWorkspaceState
+    >;
+    return all[projectId] ?? null;
+  } catch {
+    // A corrupt preference must never prevent the editor from opening —
+    // same failure physics as hierarchy-expansion-state.ts.
+    return null;
+  }
+}
+
+function writePersistedWorkspaceState(projectId: string, state: PersistedWorkspaceState): void {
+  const storage = browserStorage();
+  if (!storage) return;
+  try {
+    const all = JSON.parse(storage.getItem(STORAGE_KEY) ?? '{}') as Record<
+      string,
+      PersistedWorkspaceState
+    >;
+    all[projectId] = state;
+    storage.setItem(STORAGE_KEY, JSON.stringify(all));
+  } catch {
+    // Layout is convenience state; storage denial/quota is non-fatal.
+  }
+}
+
+/**
+ * Serialize the restorable half of one open document, or `null` for the
+ * kinds that must not persist (scene/game/xstate/asset-lab/online — module
+ * header). Exported for tests.
+ */
+export function persistableDocument(doc: {
+  descriptor: { id: string; kind: string };
+}): PersistedDocument | null {
+  const { id, kind } = doc.descriptor;
+  switch (kind) {
+    case 'asset': {
+      const spec = assetDocumentSpec(id);
+      if (!spec || !spec.assetPath || spec.online || spec.entityId !== undefined) return null;
+      return { t: 'asset', id, path: spec.assetPath, assetKind: spec.kind };
+    }
+    case 'data':
+      return id === DATA_ASSETS_DOCUMENT_ID
+        ? { t: 'static', id }
+        : { t: 'data', id, path: id.slice('data:'.length) };
+    case 'tool':
+      return { t: 'tool', id, toolId: id.slice('tool:'.length) };
+    case 'story': {
+      const state = storyDocumentState(id);
+      if (!state) return null;
+      return {
+        t: 'story',
+        id,
+        modulePath: state.modulePath,
+        storyName: state.storyName,
+        ...(state.mode === 'docs' ? { view: 'docs' as const } : {}),
+      };
+    }
+    case 'build-profiles':
+      return { t: 'static', id };
+    default:
+      // scene/game (managed by syncCenterDocuments), prefab/content-browser
+      // (no implementers persist yet).
+      return null;
+  }
+}
+
+/** Snapshot the CURRENT live workspace state (exported for tests). */
+export function snapshotWorkspaceState(api: Pick<DockviewApi, 'toJSON'>): PersistedWorkspaceState {
+  const chat = harnessChat();
+  const open: PersistedDocument[] = [];
+  for (const doc of openWorkspaceDocuments()) {
+    const persisted = persistableDocument(doc);
+    if (persisted) open.push(persisted);
+  }
+  return {
+    chat: { collapsed: chat.collapsed },
+    layout: api.toJSON(),
+    documents: { open, activeId: activeWorkspaceDocumentId() },
+  };
+}
+
+async function restoreAssetDocument(
+  store: WorkspaceStateStore,
+  doc: Extract<PersistedDocument, { t: 'asset' }>,
+): Promise<void> {
+  // Existence-only probe (`projectFileExists`) — a deleted asset resolves
+  // false and is dropped silently. Deliberately NOT `readProjectTextFile`:
+  // that reads the whole asset body just to throw it away here.
+  if (!(await projectFileExists(doc.path))) return;
+  openAssetDocument(store, doc.path, doc.assetKind as AssetKind);
+}
+
+function restoreStoryDocument(
+  store: WorkspaceStateStore,
+  doc: Extract<PersistedDocument, { t: 'story' }>,
+): void {
+  const module_ = getProjectStoryModules().find((m) => m.modulePath === doc.modulePath);
+  if (!module_ || !module_.ok) return;
+  if (!module_.stories.some((s) => s.name === doc.storyName)) return;
+  if (doc.view === 'docs') openStoryDocsDocument(store, doc.modulePath, doc.storyName);
+  else openStoryDocument(store, doc.modulePath, doc.storyName);
+}
+
+function restoreStaticDocument(store: WorkspaceStateStore, id: string): void {
+  if (id === LEGACY_PROFILER_DOCUMENT_ID) openDebuggerPanel('profiler');
+  else if (id === DATA_ASSETS_DOCUMENT_ID) openDataAssetsDocument(store);
+  else if (id === BUILD_PROFILES_DOCUMENT_ID && getEditorMode() === 'server')
+    openBuildProfilesDocument(store);
+}
+
+async function restoreOneDocument(
+  store: WorkspaceStateStore,
+  doc: PersistedDocument,
+): Promise<void> {
+  switch (doc.t) {
+    case 'asset':
+      return restoreAssetDocument(store, doc);
+    case 'data':
+      if (loadedDataFiles().some((f) => f.path === doc.path)) openDataDocument(store, doc.path);
+      return;
+    case 'tool':
+      openToolDocument(store, doc.toolId); // self-verifying (false = no-op)
+      return;
+    case 'story':
+      restoreStoryDocument(store, doc);
+      return;
+    case 'static':
+      restoreStaticDocument(store, doc.id);
+      return;
+  }
+}
+
+/**
+ * Restore the persisted open documents + active document (exported for
+ * tests). Verification sources (data files / tools / stories) are awaited
+ * ONCE up front — only for the kinds actually present — so every open below
+ * checks a settled store, in the original tab order.
+ */
+export async function restoreWorkspaceDocuments(
+  store: WorkspaceStateStore,
+  persisted: PersistedWorkspaceState,
+): Promise<void> {
+  const docs = persisted.documents;
+  if (!docs || docs.open.length === 0) {
+    // Still normalize the active document below when an activeId exists.
+    if (docs?.activeId) activateWorkspaceDocument(docs.activeId);
+    return;
+  }
+  if (docs.open.some((d) => d.t === 'data')) await refreshDataFiles().catch(() => {});
+  if (docs.open.some((d) => d.t === 'tool')) await refreshProjectTools().catch(() => {});
+  if (docs.open.some((d) => d.t === 'story')) {
+    const project = getCurrentProject();
+    if (project) await refreshProjectStories(project).catch(() => {});
+  }
+  for (const doc of docs.open) {
+    try {
+      await restoreOneDocument(store, doc);
+    } catch {
+      // Drop silently — a document that cannot truthfully reopen is gone.
+    }
+  }
+  // Restore the active tab. Opening activates as it goes, so end by
+  // activating the stored active id; if it did not survive restore (dropped,
+  // or it was the Game document), fall back to the scene document — there is
+  // always an active center document.
+  if (!docs.activeId || !activateWorkspaceDocument(docs.activeId)) {
+    activateWorkspaceDocument(SCENE_DOCUMENT_ID);
+  }
+}
+
+/**
+ * Install workspace-state persistence for this editor session:
+ *  1. restore open documents (async, verified — module header rules);
+ *  2. apply Dockview's serialized layout after those panel ids exist;
+ *  3. subscribe write-through (debounced 300ms, flushed on pagehide).
+ * Returns a teardown (unsubscribes; flushes a pending write).
+ */
+export function installWorkspaceStatePersistence(
+  store: WorkspaceStateStore,
+  api: DockviewApi,
+  reconcile: () => void,
+): () => void {
+  const projectId = projectIdentity();
+  const persisted = readPersistedWorkspaceState(projectId);
+  if (persisted?.chat) hydrateHarnessChatLayout(persisted.chat);
+
+  let disposed = false;
+  let postLayoutTimer: ReturnType<typeof setTimeout> | null = null;
+  let layoutApplied = false;
+  const applyPersistedLayout = () => {
+    if (layoutApplied) return;
+    layoutApplied = true;
+    if (persisted?.layout) {
+      try {
+        api.fromJSON(persisted.layout);
+      } catch {
+        // A stale/corrupt convenience layout must never block the editor.
+        api.clear();
+      }
+    }
+    // Restored layouts may omit capabilities added by a newer editor.
+    // Reconciliation adds only those missing panels and preserves every
+    // surviving group's user-selected position and size.
+    reconcile();
+    // Dockview completes part of `fromJSON` on its next render turn. A
+    // synchronous reconcile alone can therefore run before restored panel
+    // parameters are visible and leave a removed manifest-world tab behind.
+    // Reconcile once more after that turn so persisted geometry is retained
+    // while panels with no live document registration are dropped.
+    postLayoutTimer = setTimeout(() => {
+      postLayoutTimer = null;
+      if (disposed) return;
+      reconcile();
+      // `fromJSON` also restores Dockview's physical active panel. If that
+      // panel belonged to a world that no longer exists, removing it makes
+      // Dockview choose an arbitrary neighbor. The document registry is the
+      // semantic source of truth, so reassert its verified active document
+      // after stale-panel pruning.
+      const activeId = activeWorkspaceDocumentId();
+      if (activeId) api.getPanel(activeId)?.api.setActive();
+    }, 0);
+  };
+
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const unsubscribers: Array<() => void> = [];
+
+  const flush = () => {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    writePersistedWorkspaceState(projectId, snapshotWorkspaceState(api));
+  };
+  const schedule = () => {
+    if (timer !== null) clearTimeout(timer);
+    timer = setTimeout(flush, WRITE_DEBOUNCE_MS);
+  };
+  const onPageHide = () => flush();
+
+  // Subscriptions install only after restore settles (module header: a
+  // half-restored open-set must never overwrite the stored one). A teardown
+  // racing the restore is honored via `disposed`. Bounded by
+  // `RESTORE_TIMEOUT_MS`: a hung verification fetch (a stalled asset-existence
+  // probe, a network partition on the story/tool/data refresh calls, etc.)
+  // must never leave the WHOLE session with no write-through and no
+  // pagehide-flush — layout/open-tab state is convenience state, availability
+  // beats completeness. Whichever settles first wins; if the restore is
+  // still running when the timeout fires, its later document-opens still
+  // land normally (the subscriptions below are just live earlier).
+  let restoreTimer: ReturnType<typeof setTimeout> | null = null;
+  const restoreSettled = (
+    persisted ? restoreWorkspaceDocuments(store, persisted) : Promise.resolve()
+  )
+    .catch(() => {})
+    .finally(() => {
+      if (disposed) return;
+      applyPersistedLayout();
+      reconcile();
+    });
+  const restoreTimedOut = new Promise<void>((resolve) => {
+    restoreTimer = setTimeout(() => {
+      applyPersistedLayout();
+      resolve();
+    }, RESTORE_TIMEOUT_MS);
+  });
+  const restorePromise = Promise.race([restoreSettled, restoreTimedOut]).then(() => {
+    if (restoreTimer !== null) clearTimeout(restoreTimer);
+    if (disposed) return;
+    const dockviewDisposable = api.onDidLayoutChange(schedule);
+    unsubscribers.push(
+      () => dockviewDisposable.dispose(),
+      subscribeHarnessChatLayout(schedule),
+      subscribeWorkspaceDocuments(schedule),
+    );
+    window.addEventListener('pagehide', onPageHide);
+  });
+  void restorePromise;
+
+  return () => {
+    disposed = true;
+    if (postLayoutTimer !== null) clearTimeout(postLayoutTimer);
+    if (restoreTimer !== null) clearTimeout(restoreTimer);
+    for (const unsub of unsubscribers) unsub();
+    window.removeEventListener('pagehide', onPageHide);
+    if (timer !== null) flush();
+  };
+}

package/src/workspace-status-registry.ts

@@ -0,0 +1,110 @@
+/**
+ * Workspace STATUS-CONTRIBUTION registry (W0,
+ * docs/EDITOR-WORKSPACE-SHELL-TODO.md §7 — the shell-contract slice of §9
+ * W0). "Status is status, not a command" (§1.5): save/dirty/failure state,
+ * problem counts, connection/play state, build progress, and concise
+ * selection information belong in a narrow status bar — not mixed into the
+ * global command header and not spread across viewport overlays.
+ *
+ * Consumed since W4 by `components/StatusBar.tsx` (rendered under the
+ * bottom dock/drawer strip); the core contributions live in
+ * `components/status-contributions.tsx` (+ `build-documents.tsx`'s
+ * `build-progress`). Migration map: docs/workspace-shell/W0-INVENTORY.md.
+ *
+ * Idioms mirror `inspector-section-registry.ts`: module-scope state,
+ * `useSyncExternalStore`-shaped subscribe + monotonic version,
+ * `__resetForTest`, pure-logic headless tests (`Content` is never rendered
+ * here). Ids key persisted/status-bar slots, so duplicates throw (same rule
+ * as `workspace-utility-registry.ts`).
+ */
+
+import type { ComponentType } from 'react';
+
+/** The §7 status contribution contract: one compact status-bar item. */
+export interface WorkspaceStatusContribution {
+  /** Stable id — keys the status-bar slot (`data-testid`). */
+  readonly id: string;
+  /** Which end of the bar (§4.1: session state left, selection info right).
+   *  Default `'left'`. */
+  readonly align?: 'left' | 'right';
+  /** Slot order within its side (ascending; ties keep registration order).
+   *  Default `0`. */
+  readonly order?: number;
+  /** React content host — compact, passive, non-command (§1.5). Never
+   *  rendered by the registry itself. */
+  readonly Content: ComponentType;
+}
+
+// --- Module-scope state (mirrors inspector-section-registry.ts) -----------
+
+interface StoredContribution {
+  readonly contribution: WorkspaceStatusContribution;
+  readonly seq: number;
+}
+
+let _contributions: StoredContribution[] = [];
+let _seq = 0;
+let _version = 0;
+const _listeners = new Set<() => void>();
+
+function notifyChanged(): void {
+  _version++;
+  for (const fn of _listeners) fn();
+}
+
+/** Subscribe to (un)registrations. Returns an unsubscribe function. */
+export function subscribeWorkspaceStatus(fn: () => void): () => void {
+  _listeners.add(fn);
+  return () => {
+    _listeners.delete(fn);
+  };
+}
+
+/** Monotonic change counter — the `getSnapshot` for `useSyncExternalStore`. */
+export function workspaceStatusRegistryVersion(): number {
+  return _version;
+}
+
+/**
+ * Register a status contribution. Returns an unregister function.
+ * Throws on a duplicate id (ids key status-bar slots — same uniqueness rule
+ * as `registerWorkspaceUtility`).
+ */
+export function registerWorkspaceStatus(contribution: WorkspaceStatusContribution): () => void {
+  if (_contributions.some((c) => c.contribution.id === contribution.id)) {
+    throw new Error(
+      `registerWorkspaceStatus: id "${contribution.id}" is already registered — ` +
+        'status ids key status-bar slots, so they must be unique; unregister the ' +
+        'previous contribution first (docs/EDITOR-WORKSPACE-SHELL-TODO.md §7).',
+    );
+  }
+  const stored: StoredContribution = { contribution, seq: _seq++ };
+  _contributions = [..._contributions, stored];
+  notifyChanged();
+  return () => {
+    if (!_contributions.includes(stored)) return;
+    _contributions = _contributions.filter((c) => c !== stored);
+    notifyChanged();
+  };
+}
+
+/** Registered contributions for one side of the bar, in (order,
+ *  registration-sequence) order; with no argument, both sides (left first). */
+export function workspaceStatusContributions(
+  align?: 'left' | 'right',
+): WorkspaceStatusContribution[] {
+  const side = (want: 'left' | 'right') =>
+    [..._contributions]
+      .filter((c) => (c.contribution.align ?? 'left') === want)
+      .sort((a, b) => (a.contribution.order ?? 0) - (b.contribution.order ?? 0) || a.seq - b.seq)
+      .map((c) => c.contribution);
+  if (align) return side(align);
+  return [...side('left'), ...side('right')];
+}
+
+/** Test-only reset (mirrors `__resetInspectorSectionRegistryForTest`). */
+export function __resetWorkspaceStatusRegistryForTest(): void {
+  _contributions = [];
+  _seq = 0;
+  notifyChanged();
+}

package/src/workspace-utility-commands.ts

@@ -0,0 +1,49 @@
+/** Semantic commands and failure auto-open policy for workspace utilities. */
+
+import { getBuildSession, subscribeBuildSession } from './components/build-documents';
+import { showWorkspaceUtility, toggleWorkspaceUtility } from './workspace-dock-controller';
+
+export const CONSOLE_UTILITY_ID = 'console';
+export const DEBUGGER_UTILITY_ID = 'debugger';
+export const BUILD_OUTPUT_UTILITY_ID = 'build-output';
+
+export interface UtilityAutoOpenStore {
+  subscribe(fn: () => void): () => void;
+  readonly saveState: 'saved' | 'unsaved' | 'failed';
+}
+
+/** Only actionable failures open a utility automatically. */
+export function installUtilityAutoOpen(store: UtilityAutoOpenStore): () => void {
+  let previousSave = store.saveState;
+  const stopStore = store.subscribe(() => {
+    const next = store.saveState;
+    if (next === 'failed' && previousSave !== 'failed') showWorkspaceUtility(CONSOLE_UTILITY_ID);
+    previousSave = next;
+  });
+
+  let previousBuildPhase = getBuildSession().phase;
+  const stopBuild = subscribeBuildSession(() => {
+    const session = getBuildSession();
+    if (session.phase === 'done' && previousBuildPhase !== 'done' && session.result?.ok === false) {
+      showWorkspaceUtility(BUILD_OUTPUT_UTILITY_ID);
+    }
+    previousBuildPhase = session.phase;
+  });
+
+  return () => {
+    stopStore();
+    stopBuild();
+  };
+}
+
+/** Legacy shell events remain stable while their physical implementation is Dockview. */
+export function installUtilityEvents(): () => void {
+  const onToggleConsole = () => toggleWorkspaceUtility(CONSOLE_UTILITY_ID);
+  const onShowBuildOutput = () => showWorkspaceUtility(BUILD_OUTPUT_UTILITY_ID);
+  window.addEventListener('editor:toggle-console', onToggleConsole);
+  window.addEventListener('editor:show-build-output', onShowBuildOutput);
+  return () => {
+    window.removeEventListener('editor:toggle-console', onToggleConsole);
+    window.removeEventListener('editor:show-build-output', onShowBuildOutput);
+  };
+}