@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/viewport-surface-status.tsx

@@ -0,0 +1,55 @@
+/**
+ * The 3D board's empty-viewport vocabulary, reused by every other design
+ * surface that would otherwise sit blank while it builds. Scene's root-aware
+ * loading/failure/empty states live in `SurfaceStateOverlay`; this compact
+ * label remains for object/board construction whose subject is already known.
+ *
+ * Idle / building / ready is viewport STATE, not a new overlay channel —
+ * the board already owns this shape (`ThreeBoardDocument`: idle "Open this
+ * tab…", building "Settling N stories…"). Scene's first design
+ * mount and `Object3DDocumentViewport`'s first construct are the same wait
+ * with different subjects. Copy names the subject being prepared; it does not
+ * claim a narrower phase (such as physics settling) while indexing, mounting,
+ * bounds/layout, or renderer setup is actually in flight.
+ */
+
+import { themeVars } from '@volter/sdk/widgets';
+import type { ReactNode } from 'react';
+
+/** Fixed construct tail after the board scene exists — viewport-bind, not settle. */
+export const OBJECT3D_SURFACE_BUILDING = 'Preparing the viewport…';
+
+/** Whole 3D-board construction, from component index through mounted previews. */
+export const THREE_BOARD_BUILDING = 'Preparing 3D component previews…';
+
+/** Name the candidate count when we already know it. Never a progress fraction. */
+export function threeBoardBuildingCopy(storyCount: number): string {
+  if (!Number.isFinite(storyCount) || storyCount < 1) return THREE_BOARD_BUILDING;
+  return storyCount === 1
+    ? 'Preparing 1 component preview…'
+    : `Preparing ${storyCount} component previews…`;
+}
+
+export function ViewportSurfaceStatus({
+  testId,
+  children,
+}: {
+  readonly testId: string;
+  readonly children: ReactNode;
+}) {
+  return (
+    <div
+      data-testid={testId}
+      style={{
+        position: 'absolute',
+        inset: 0,
+        padding: 16,
+        fontSize: 12,
+        color: themeVars.content.muted,
+        pointerEvents: 'none',
+      }}
+    >
+      {children}
+    </div>
+  );
+}

package/src/kit/wait-until.ts

@@ -0,0 +1,37 @@
+/**
+ * POLL UNTIL A LIVE PREDICATE HOLDS — the one wait the editor's async doors
+ * share, and the one place its cadence is spelled.
+ *
+ * It lived private in `editor-view-presentation.ts` while the presenter was
+ * the only module that addressed a document. Now that each document family
+ * answers its own address (`document-open-registry.ts`), the families do the
+ * waiting their own addresses need — a table entry that arrives on a later
+ * adapter resolution, a contribution that registers after the first
+ * discovery pass — so the helper is shared rather than duplicated four times.
+ *
+ * NOT a general scheduling utility: it polls, which is what a registry with no
+ * per-entry subscription leaves you. Where a seam DOES publish changes
+ * (`subscribeToolContributions`, `subscribeProjectAdapter`), subscribe to it.
+ */
+
+/**
+ * How long an EXPLICIT address waits for the thing it names. A view link, a
+ * restored layout and an agent's `present` are all durable intent, so a
+ * document that is merely late must still land; the window is bounded because
+ * "it is not coming" has to be sayable.
+ */
+export const DOCUMENT_REGISTRATION_TIMEOUT_MS = 10_000;
+
+/** `true` once `predicate()` holds, `false` if `timeoutMs` elapses first. */
+export async function waitUntil(predicate: () => boolean, timeoutMs = 4000): Promise<boolean> {
+  if (predicate()) return true;
+  const started = performance.now();
+  return new Promise((resolve) => {
+    const tick = () => {
+      if (predicate()) resolve(true);
+      else if (performance.now() - started >= timeoutMs) resolve(false);
+      else setTimeout(tick, 25);
+    };
+    setTimeout(tick, 0);
+  });
+}

package/src/kit/worker-call-metrics.ts

@@ -0,0 +1,166 @@
+/**
+ * A LANE'S WORKER STALLS, measured by the page and carried to the editor's `status` command.
+ *
+ * WHY (measured 2026-09-16): one Blender call held its worker for over 1,800s
+ * and wedged the tab; the only report anyone got was a replay harness timing
+ * out. Separately, a 0.86s-per-call cost in a 225-mesh scene stretched under
+ * load into heartbeat timeouts that read as "tab present, did not respond". The
+ * product had a number for NEITHER. Owner ruling: a tab that stops answering is
+ * the product's defect regardless of what the machine is doing, and the product
+ * must surface it.
+ *
+ * TWO MEASUREMENTS, BOTH TAKEN FROM THE PAGE, because neither blocked party can
+ * report on itself:
+ *  - the WORKER's call times come from the lane's meter, which stamps each
+ *    `postMessage` and its reply; a blocked worker cannot send, but the side
+ *    that posted still has a clock.
+ *  - the MAIN THREAD's stalls come from the `longtask` PerformanceObserver kept
+ *    here.
+ *
+ * WHY A REGISTRY AND NOT A DIRECT IMPORT. The census sampler (`tab-census.ts`)
+ * must not pull a lane's stack into its import closure just to ask a question
+ * that is usually answered "no lane". A lane publishes its meter through
+ * `host.session.reportWorkerCallMeter` (`editor-host-door.ts`) when it
+ * constructs its runtime, the way a mounted game publishes its render-debug
+ * adapter to `authoring/active-systems`. The LONG TASKS are the host page's
+ * own, so publishing a meter is what starts the watch; no lane decides the page
+ * is watched.
+ *
+ * MEASUREMENT ONLY. Nothing here cancels, kills, or budgets a call, and no
+ * threshold is enforced anywhere: a budget is the owner's policy, and these are
+ * the numbers such a policy would have to be made from.
+ */
+
+import type { EditorHostWorkerCallMetrics } from '@volter/sdk/host';
+import type { TabStallMetrics, WorkerCallTabMetrics } from '@volter/sdk/tab-census';
+
+/** What a lane publishes: a read of its live call meter. */
+export type WorkerCallMeter = () => EditorHostWorkerCallMetrics;
+
+const meters = new Map<string, WorkerCallMeter>();
+
+/**
+ * Publish (or retract, with null) one lane's call meter, and start the page's
+ * own stall watch behind it.
+ *
+ * ONE OWNER per name: the lane's own runtime singleton, the same lifetime as
+ * the session itself. There is no per-document or per-play teardown that may
+ * retract it, because the session outlives both.
+ */
+export function setWorkerCallMeter(lane: string, read: WorkerCallMeter | null): void {
+  if (read === null) {
+    meters.delete(lane);
+    return;
+  }
+  meters.set(lane, read);
+  // The observer's lifetime is the PAGE's (its history is what "during the
+  // last call" is answered from), so it is started, never stopped.
+  startStallObserver();
+}
+
+/** A long task, kept only as long as it can still be attributed to a call. */
+interface StallEntry {
+  readonly start: number;
+  readonly duration: number;
+}
+
+/**
+ * How many recent long tasks to keep for the "during the last call" question.
+ *
+ * A long task is >50ms by spec, so this is minutes of a badly-stalled tab and
+ * nothing at all on a healthy one. Bounded because the observer runs for the
+ * life of the page.
+ */
+const STALL_HISTORY = 128;
+
+let recent: StallEntry[] = [];
+let longestTaskMs: number | null = null;
+let tasksOver100ms = 0;
+let observing = false;
+
+/**
+ * Start watching the main thread. Idempotent, and silent where the Long Tasks
+ * API does not exist (Safari/Firefox): `longestTaskMs` then stays null, which
+ * says "nobody measured" rather than the falsehood a 0 would tell.
+ *
+ * Internal: {@link setWorkerCallMeter} is the one caller, so the page's watch
+ * begins the moment a lane has calls to attribute stalls to, and no package has
+ * to know the page is watched at all.
+ */
+function startStallObserver(): () => void {
+  if (observing) return () => {};
+  if (typeof PerformanceObserver === 'undefined') return () => {};
+  let observer: PerformanceObserver;
+  try {
+    observer = new PerformanceObserver((list) => {
+      for (const entry of list.getEntries()) {
+        const duration = entry.duration;
+        if (longestTaskMs === null || duration > longestTaskMs) longestTaskMs = duration;
+        if (duration >= 100) tasksOver100ms += 1;
+        recent.push({ start: entry.startTime, duration });
+        if (recent.length > STALL_HISTORY) recent = recent.slice(-STALL_HISTORY);
+      }
+    });
+    // `buffered` picks up the boot-time stalls that happened before this ran —
+    // a cold editor boot is one of the longest tasks a session ever has, and it
+    // is not measurable any other way.
+    observer.observe({ type: 'longtask', buffered: true });
+  } catch {
+    // An unsupported entry type throws here on some engines. Same answer as an
+    // absent API: no numbers, rather than invented ones.
+    return () => {};
+  }
+  observing = true;
+  return () => {
+    observer.disconnect();
+    observing = false;
+  };
+}
+
+/** The main thread's stalls, or null until a lane's meter started the watch. */
+export function tabStallMetrics(): TabStallMetrics | null {
+  if (!observing) return null;
+  return {
+    longestTaskMs: longestTaskMs === null ? null : Math.round(longestTaskMs),
+    tasksOver100ms,
+  };
+}
+
+/**
+ * Every published lane's calls, keyed by lane, or null when no lane has
+ * published — the census then carries no `workerCalls` key at all, because
+ * "absent" and "idle" are different claims.
+ */
+export function workerCallTabMetrics(
+  now: number = performance.now(),
+): Record<string, WorkerCallTabMetrics> | null {
+  if (meters.size === 0) return null;
+  const out: Record<string, WorkerCallTabMetrics> = {};
+  for (const [lane, read] of meters) {
+    const calls = read();
+    const window = calls.lastCallWindow;
+    let duringCall: number | null = null;
+    if (window !== null) {
+      const end = window.end ?? now;
+      for (const task of recent) {
+        // Overlap, not containment: the task that matters most is the one that
+        // was ALREADY running when the call was posted.
+        if (task.start + task.duration < window.start || task.start > end) continue;
+        if (duringCall === null || task.duration > duringCall) duringCall = task.duration;
+      }
+    }
+    out[lane] = {
+      inFlightMs: calls.inFlightMs,
+      lastCallMs: calls.lastCallMs,
+      maxCallMs: calls.maxCallMs,
+      maxCallLabel: calls.maxCallLabel ?? null,
+      currentPhase: calls.currentPhase ?? null,
+      ...(calls.completedCalls === undefined ? {} : {completedCalls: calls.completedCalls}),
+      callsOver5s: calls.callsOver5s,
+      callsOver30s: calls.callsOver30s,
+      lastCallLongestTaskMs: duringCall === null ? null : Math.round(duringCall),
+      wasmMemoryMB: calls.wasmMemoryMB,
+    };
+  }
+  return out;
+}

package/src/kit/workspace-areas.ts

@@ -0,0 +1,191 @@
+/**
+ * THE ACTIVE WORKSPACE'S EDITOR AREAS — the live store the dock reads, and the
+ * one place an area document is opened and closed.
+ *
+ * **A Blender editor AREA is an editor group; the drawer holds utilities**
+ * (orchestrator ruling 2026-09-19; WORK.md §Inspection parity I5). Blender's UV
+ * Editing is a side-by-side split of the centre, Shading and Animation a
+ * top/bottom split, and both the dock and the Code-OSS frame have exactly that
+ * shape in editor groups. So a workspace's second editor is a
+ * `workspace.document` contribution opened into a second group — never a
+ * drawer utility — and this module is the seam: `workspace-presets.ts`
+ * publishes the active workspace's `areas` here on every switch, and this
+ * module opens what that list names and closes what it no longer does.
+ *
+ * WHY THE OPEN LIVES HERE AND NOT IN THE DOCK. The dock is a RECONCILER: it
+ * draws whatever the document registry holds, and `reconcileWorkspace` runs on
+ * every mutation, so opening a document from inside it is a write during a
+ * read. The registry is the truth; the frame places it (`volterDocuments.ts`'s
+ * `reconcileAreaDocumentPanels`), and under the frame the layout host places
+ * the same registry entry in a VS Code editor group instead. One list, two
+ * hosts — the shape every U8 seam takes.
+ *
+ * WHY IT IS A MODULE AND NOT A REACT EFFECT. A workspace switch arrives from
+ * four places (the menu, a registered action, `editor.workspace(id)`, the
+ * per-project restore at boot) and three of them have no component mounted to
+ * run an effect. `setWorkspaceAreas` is called by the same function that
+ * publishes the regions, so the two halves of "apply this workspace" cannot
+ * drift apart.
+ */
+
+import type { WorkspaceAreaContribution } from '@volter/sdk/layout-arrangements';
+import { openToolDocument, toolDocumentId } from './components/tool-documents';
+import { subscribeToolContributions } from './tool-loader';
+import { closeWorkspaceDocument, openWorkspaceDocuments } from '@volter/sdk/kit/workspace-document-registry';
+
+let _declared: readonly WorkspaceAreaContribution[] = [];
+let _areas: readonly WorkspaceAreaContribution[] = [];
+/** Ratios an area's own document asked for ({@link setWorkspaceAreaRatio}), by area id. */
+const _ratios = new Map<string, number>();
+let _version = 0;
+const _listeners = new Set<() => void>();
+
+/** The active workspace's areas, in declaration order, each at the ratio its document asked
+ *  for when it asked for one. */
+export function activeWorkspaceAreas(): readonly WorkspaceAreaContribution[] {
+  return _areas;
+}
+
+/** Monotonic counter behind {@link subscribeWorkspaceAreas}. */
+export function workspaceAreasVersion(): number {
+  return _version;
+}
+
+export function subscribeWorkspaceAreas(listener: () => void): () => void {
+  _listeners.add(listener);
+  return () => _listeners.delete(listener);
+}
+
+/** The area one open document fills, or `null` — the dock's lookup. */
+export function workspaceAreaFor(documentId: string): WorkspaceAreaContribution | null {
+  return _areas.find((area) => toolDocumentId(area.document) === documentId) ?? null;
+}
+
+/**
+ * THE WHOLE OPEN PASS LEAVES THE MODULE EVALUATION, and this is the second and
+ * correct form of a fix the first attempt got half right.
+ *
+ * MEASURED TWICE, live, on a fresh `--template models` scaffold:
+ *  1. `subscribeToolContributions(...)` at this file's top level →
+ *     "editor app failed to start: ReferenceError: Cannot access 'listeners'
+ *     before initialization at subscribeToolContributions
+ *     (tool-loader.ts:372) at workspace-areas.ts:41", x3. The WHOLE editor
+ *     down, not a degraded panel.
+ *  2. The same subscription moved to the first `setWorkspaceAreas` call →
+ *     the SAME error, one frame deeper: `... at ensureSubscribedToContributions
+ *     ... at setWorkspaceAreas ... at publishWorkspaceRegions
+ *     (workspace-presets.ts:119) at workspace-presets.ts:164`.
+ *
+ * The second reading is the one that names the real shape:
+ * `workspace-presets.ts` calls `publishWorkspaceRegions()` AT MODULE SCOPE
+ * (line 389 in source), so "the first publish" IS during module evaluation —
+ * deferring to it deferred nothing. And this module is in one import cycle
+ * with `tool-loader` (`workspace-areas` -> `components/tool-documents` ->
+ * `tool-loader`), so every binding over there is still in its temporal dead
+ * zone at that moment. `subscribeToolContributions` was merely the first of
+ * this module's reaches into it; `openToolDocument` is the other, and it
+ * would have thrown next.
+ *
+ * So the pass is queued as a MICROTASK. ES module evaluation is synchronous
+ * end to end, so a microtask queued during it runs after the last module has
+ * finished — every binding initialized, no ordering to reason about. The
+ * publish itself stays synchronous: `_areas`, the version and the listeners
+ * are this module's own state and nothing else's, and the dock must see the
+ * new list on the same tick the workspace changed.
+ */
+let subscribed = false;
+let pendingPass = false;
+
+function runOpenPass(): void {
+  pendingPass = false;
+  if (!subscribed) {
+    subscribed = true;
+    // THE CONTRIBUTIONS ARRIVE AFTER THE WORKSPACE, EVERY TIME. A project's
+    // packages import asynchronously, so the workspace restored at boot
+    // publishes its `areas` while `blender-uv-editor.document` is still
+    // loading and `openToolDocument` truthfully opens nothing. Contributions
+    // changing is the other half of the same event — including a SAVE, which
+    // re-evaluates the module and must re-open the document against the fresh
+    // component.
+    subscribeToolContributions(scheduleOpenPass);
+  }
+  const areas = _areas;
+  const wanted = new Set(areas.map((area) => toolDocumentId(area.document)));
+  // CLOSING IS BY AREA, NOT BY ID SET DIFFERENCE. A document that is open and
+  // carries an `area` but is not in the new list is this module's to close,
+  // and nothing else in the editor opens one — so the sweep reads the registry
+  // rather than remembering what it opened, which is what survives a reload
+  // that rebuilt the registry underneath.
+  for (const open of openWorkspaceDocuments()) {
+    if (!open.descriptor.area) continue;
+    if (wanted.has(open.descriptor.id)) continue;
+    closeWorkspaceDocument(open.descriptor.id);
+  }
+  for (const area of areas) {
+    // `openToolDocument` is self-verifying: a contribution that has not loaded
+    // yet opens nothing and answers false, and the subscription above runs
+    // this pass again when it arrives. No queue, no retry timer.
+    openToolDocument(area.document, { activate: false }, area.id);
+  }
+}
+
+function scheduleOpenPass(): void {
+  if (pendingPass) return;
+  pendingPass = true;
+  queueMicrotask(runOpenPass);
+}
+
+function areasKey(areas: readonly WorkspaceAreaContribution[]): string {
+  return areas.map((area) => `${area.id}|${area.document}|${area.place}|${area.ratio}`).join(' ');
+}
+
+/**
+ * Publish the active workspace's areas (`workspace-presets.ts`), opening the
+ * documents it names and closing the ones the previous workspace had.
+ */
+export function setWorkspaceAreas(areas: readonly WorkspaceAreaContribution[]): void {
+  _declared = areas;
+  scheduleOpenPass();
+  publishAreas();
+}
+
+/**
+ * AN AREA'S DOCUMENT CHANGED ITS JOB, and asks for the size that job needs — or, with `null`,
+ * for the workspace's declared ratio back. The model workspace's bottom area is the Timeline in
+ * Movie mode and the Game panel in Game mode (`@volter/editor-blender`): one document, two
+ * jobs, and Blender's measured Timeline strip (63 px of an 880-px column) shows the Game
+ * panel's play log as one clipped line.
+ *
+ * It is the same BOOTSTRAP the declared ratio is, applied the same way: under the frame a
+ * changed ratio stands the area up again (`volterDocuments.ts`), exactly as a workspace switch
+ * that puts a different document there does, and a person's drag on the sash is theirs until
+ * the next change of job. An id the active workspace does not declare is remembered and has no
+ * effect until one does.
+ */
+export function setWorkspaceAreaRatio(areaId: string, ratio: number | null): void {
+  if (ratio !== null && !(ratio > 0 && ratio < 1))
+    throw new Error(`An area's ratio is its share of the split, between 0 and 1; got ${ratio}.`);
+  if ((_ratios.get(areaId) ?? null) === ratio) return;
+  if (ratio === null) _ratios.delete(areaId);
+  else _ratios.set(areaId, ratio);
+  publishAreas();
+}
+
+function publishAreas(): void {
+  const next = _declared.map((area) => {
+    const ratio = _ratios.get(area.id);
+    return ratio === undefined || ratio === area.ratio ? area : { ...area, ratio };
+  });
+  const changed = areasKey(next) !== areasKey(_areas);
+  _areas = next;
+  if (!changed) return;
+  _version += 1;
+  for (const listener of _listeners) listener();
+}
+
+/** Re-run the open pass without changing the list — the door for "the
+ *  contributions finished loading", which is when a workspace applied at boot
+ *  can finally find the document it named. */
+export function reopenWorkspaceAreas(): void {
+  scheduleOpenPass();
+}

package/src/kit/workspace-aux-commands.ts

@@ -0,0 +1,11 @@
+import { showWorkspaceAuxiliary } from '@volter/sdk/kit/workspace-host-commands';
+
+export function openUndoHistory(): void {
+  showWorkspaceAuxiliary('undo-history');
+}
+
+export function installAuxiliaryEvents(): () => void {
+  const onShowHistory = () => openUndoHistory();
+  window.addEventListener('editor:show-history-tab', onShowHistory);
+  return () => window.removeEventListener('editor:show-history-tab', onShowHistory);
+}

package/src/kit/workspace-available-documents.ts

@@ -0,0 +1,142 @@
+/** Discoverable documents are independent of open tabs. Closing a tab keeps its
+ * project-owned descriptor available to Content and to session restoration. */
+
+import {
+  closeWorkspaceDocument,
+  openWorkspaceDocument,
+  openWorkspaceDocuments,
+  WORKSPACE_DOCUMENT_KINDS,
+  type WorkspaceDocumentDescriptor,
+} from '@volter/sdk/kit/workspace-document-registry';
+import { liveDocumentHeld } from '@volter/sdk/kit/live-document';
+import { registerWorkspaceDocumentRestorer } from '@volter/sdk/kit/workspace-document-restore';
+import { projectAdapterFacet, subscribeProjectAdapter } from '@volter/sdk/kit/project-adapter';
+
+export interface AvailableWorkspaceDocument {
+  readonly descriptor: WorkspaceDocumentDescriptor;
+  readonly category: string;
+  /** Set only when this is the root's own document, never an isolated scene. */
+  readonly rootId?: string | undefined;
+  readonly default: boolean;
+}
+let documents: readonly AvailableWorkspaceDocument[] = [];
+const listeners = new Set<() => void>();
+const pending = new Map<string, boolean>();
+let sessionStarted = false;
+let hasDocumentsRestoring = false;
+let defaultOpened = false;
+export function requestAvailableWorkspaceDocument(id: string, active = true): void {
+  pending.set(id, active);
+  restoreAvailableDocuments();
+}
+const notify = () => {
+  for (const listener of listeners) listener();
+};
+export const availableWorkspaceDocuments = () => documents;
+export function subscribeAvailableWorkspaceDocuments(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function openAvailableWorkspaceDocument(id: string, activate = true): boolean {
+  const entry = documents.find((item) => item.descriptor.id === id);
+  if (!entry) return false;
+  openWorkspaceDocument(
+    { ...entry.descriptor, closeable: true, persist: () => ({ availableDocumentId: id }) },
+    { activate },
+  );
+  return true;
+}
+
+/** A document restored or opened by default while Play holds the game opens behind it. */
+function restoreAvailableDocuments(): void {
+  for (const [id, active] of pending) {
+    if (openAvailableWorkspaceDocument(id, active && !liveDocumentHeld())) pending.delete(id);
+  }
+  if (sessionStarted && !hasDocumentsRestoring && !defaultOpened) {
+    // A root's fallback must wait for the project's declared document. Boards
+    // can register before the asynchronous document finders have settled.
+    const facet = projectAdapterFacet();
+    if (!facet || facet.documentsPending) return;
+    const declared = facet.scenes.entries.find((entry) => entry.id === facet.scenes.default);
+    if (
+      (declared && declared.kind !== 'scene' && declared.kind !== 'prefab') ||
+      openWorkspaceDocuments().some((document) => !document.descriptor.area)
+    ) return;
+    const entry = documents.find((item) => item.default);
+    if (entry) {
+      defaultOpened = true;
+      openAvailableWorkspaceDocument(entry.descriptor.id, !liveDocumentHeld());
+    }
+  }
+}
+
+subscribeProjectAdapter(restoreAvailableDocuments);
+
+export function registerAvailableWorkspaceDocument(
+  descriptor: WorkspaceDocumentDescriptor,
+  options: { category: string; default?: boolean; rootId?: string | undefined },
+): string {
+  const previous = documents.find((item) => item.descriptor.id === descriptor.id);
+  if (
+    previous?.descriptor.Content === descriptor.Content &&
+    previous?.descriptor.title === descriptor.title &&
+    previous.descriptor.provenance?.sourcePath === descriptor.provenance?.sourcePath &&
+    previous.descriptor.provenance?.rootId === descriptor.provenance?.rootId &&
+    previous.descriptor.Toolbar === descriptor.Toolbar &&
+    previous.descriptor.Shelf === descriptor.Shelf &&
+    previous.descriptor.preview === descriptor.preview &&
+    previous.default === (options.default ?? false) &&
+    previous.category === options.category &&
+    previous.rootId === options.rootId
+  )
+    return descriptor.id;
+  const entry = {
+    descriptor,
+    category: options.category,
+    default: options.default ?? false,
+    rootId: options.rootId,
+  };
+  documents = previous
+    ? documents.map((item) => (item.descriptor.id === descriptor.id ? entry : item))
+    : [...documents, entry];
+  notify();
+  restoreAvailableDocuments();
+  return descriptor.id;
+}
+
+export function unregisterAvailableWorkspaceDocument(id: string): void {
+  if (!documents.some((item) => item.descriptor.id === id)) return;
+  documents = documents.filter((item) => item.descriptor.id !== id);
+  closeWorkspaceDocument(id, { discardDirty: true });
+  notify();
+}
+
+for (const kind of WORKSPACE_DOCUMENT_KINDS) {
+  registerWorkspaceDocumentRestorer({
+    kind,
+    owner: 'workspace-available-documents',
+    restore: ({ state, active }) => {
+      const id = (state as { availableDocumentId?: unknown } | null)?.availableDocumentId;
+      if (typeof id !== 'string') return false;
+      pending.set(id, active);
+      restoreAvailableDocuments();
+      return true;
+    },
+    beginRestore: ({ hasDocumentsToRestore }) => {
+      sessionStarted = true;
+      hasDocumentsRestoring = hasDocumentsToRestore;
+      restoreAvailableDocuments();
+    },
+  });
+}
+export function resetAvailableWorkspaceDocuments(): void {
+  documents = [];
+  pending.clear();
+  sessionStarted = false;
+  hasDocumentsRestoring = false;
+  defaultOpened = false;
+  notify();
+}

package/src/kit/workspace-core-utilities.ts

@@ -0,0 +1,31 @@
+/** The identity inventory of the HOST's own utility tabs — the ones
+ *  `components/core-utilities.tsx` registers. */
+export const CORE_WORKSPACE_UTILITIES = {
+  console: { id: 'console', title: 'Console' },
+  lightExplorer: { id: 'light-explorer', title: 'Light Explorer' },
+} as const;
+
+/**
+ * Utility tabs a PACKAGE registers, whose ids the host still declares.
+ *
+ * A tab id keys persisted dock state and is part of the shareable view address
+ * space (`EDITOR_VIEW_BUILT_IN_UTILITY_IDS` in `@volter/sdk`, which this
+ * list must equal), so the address is the host's even when the surface is not:
+ * the package imports its row from here rather than spelling the id twice.
+ * `@volter/editor-game` registers all four — the story trio through
+ * `story-documents.service.ts`, Generations through `generation.service.ts`.
+ * Build Output is NOT here: it is a `workspace.utility` CONTRIBUTION, so the
+ * loader namespaces its id as `tool:build-output.utility` and no host
+ * declaration exists.
+ */
+export const CONTRIBUTED_WORKSPACE_UTILITIES = {
+  storyActions: { id: 'story-actions', title: 'Actions' },
+  storyInteractions: { id: 'story-interactions', title: 'Interactions' },
+  storyAccessibility: { id: 'story-accessibility', title: 'Accessibility' },
+  generations: { id: 'generations', title: 'Generations' },
+} as const;
+
+export const BUILT_IN_WORKSPACE_UTILITIES = [
+  ...Object.values(CORE_WORKSPACE_UTILITIES),
+  ...Object.values(CONTRIBUTED_WORKSPACE_UTILITIES),
+] as const;