@volter/sdk 0.0.0-stage → 0.5.204

package/src/kit/source-conflict.ts

@@ -0,0 +1,122 @@
+import { assertEditorServerAnswered } from '@volter/sdk/kit/editor-server-response';
+
+export interface SourceConflictResource {
+  path: string;
+  revision: number;
+  sha: string | null;
+}
+
+export interface SourceConflictNotice {
+  id: string;
+  conflictId: string;
+  label: string;
+  expectedRevision: number;
+  currentRevision: number;
+  conflicts: SourceConflictResource[];
+  attempted: Record<string, string | null>;
+  base: Record<string, string | null>;
+  reapply?: (() => Promise<void>) | undefined;
+}
+
+const listeners = new Set<(notice: SourceConflictNotice | null) => void>();
+let current: SourceConflictNotice | null = null;
+
+export function sourceConflictNotice(): SourceConflictNotice | null {
+  return current;
+}
+
+export function subscribeSourceConflict(
+  listener: (notice: SourceConflictNotice | null) => void,
+): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function clearSourceConflict(): void {
+  current = null;
+  for (const listener of listeners) listener(null);
+}
+
+export async function handleProjectMutationFailure(
+  response: Response,
+  input: {
+    label: string;
+    attempted?: Record<string, string | null>;
+    reapply?: () => Promise<void>;
+  },
+): Promise<never> {
+  const payload = (await response.json().catch(() => null)) as {
+    code?: unknown;
+    conflictId?: unknown;
+    error?: unknown;
+    expectedRevision?: unknown;
+    currentRevision?: unknown;
+    conflicts?: unknown;
+    bases?: unknown;
+  } | null;
+  if (
+    response.status === 409 &&
+    payload?.code === 'SOURCE_REVISION_CONFLICT' &&
+    typeof payload.conflictId === 'string' &&
+    Number.isInteger(payload.expectedRevision) &&
+    Number.isInteger(payload.currentRevision) &&
+    Array.isArray(payload.conflicts)
+  ) {
+    current = {
+      id: globalThis.crypto?.randomUUID?.() ?? `conflict-${Date.now()}`,
+      conflictId: payload.conflictId,
+      label: input.label,
+      expectedRevision: payload.expectedRevision as number,
+      currentRevision: payload.currentRevision as number,
+      conflicts: payload.conflicts as SourceConflictResource[],
+      attempted: { ...(input.attempted ?? {}) },
+      base:
+        payload.bases && typeof payload.bases === 'object' && !Array.isArray(payload.bases)
+          ? { ...(payload.bases as Record<string, string | null>) }
+          : {},
+      ...(input.reapply ? { reapply: input.reapply } : {}),
+    };
+    for (const listener of listeners) listener(current);
+    throw new Error(
+      `${input.label} conflicts with source revision ${current.currentRevision}; inspect it before reapplying.`,
+    );
+  }
+  throw new Error(
+    typeof payload?.error === 'string'
+      ? payload.error
+      : `${input.label} failed with HTTP ${response.status}.`,
+  );
+}
+
+export async function resolveSourceConflict(
+  notice: SourceConflictNotice,
+  resources: Record<string, string | null>,
+): Promise<void> {
+  const { sourceMutationAttribution } = await import('@volter/sdk/kit/editor-session-attribution');
+  const response = await fetch('/__editor/source-conflict/resolve', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      conflictId: notice.conflictId,
+      resources: Object.entries(resources).map(([path, content]) => ({ path, content })),
+      ...sourceMutationAttribution(),
+    }),
+  });
+  // This function REPORTS BY RETURNING, so a page fallback (which is `ok`)
+  // used to close the conflict banner over a resolution nobody applied.
+  assertEditorServerAnswered(response, 'Conflict resolution failed');
+  if (!response.ok) {
+    if (response.status === 409) {
+      await handleProjectMutationFailure(response, {
+        label: 'Resolve source conflict',
+        attempted: resources,
+      });
+    }
+    const body = (await response.json().catch(() => null)) as { error?: unknown } | null;
+    throw new Error(
+      typeof body?.error === 'string'
+        ? body.error
+        : `Conflict resolution failed (${response.status}).`,
+    );
+  }
+}

package/src/kit/stage-context.ts

@@ -0,0 +1,377 @@
+/**
+ * WHAT A STAGE IS SHOWING — the ONE derived answer every stage capability asks.
+ *
+ * ARCHITECTURE-CORE §One stage: there is one 3D stage host, and a capability is
+ * present on a stage wherever its CONDITION holds — never by the origin or kind
+ * of the document that happens to have opened it. Before this, four gates spelled
+ * that question four ways in three places (`threeSurfaceToolsApply` for the shelf
+ * rail, `showThreejsTools` in the scene panel, `studioStage`/`hasShell` in the
+ * document host), which is why a prefab's stage and the world root's stage could
+ * not be the same code.
+ *
+ * It is a FUNCTION over the stores the panels already subscribe to, not a store
+ * of its own — the method transcribed from `inspection/active-surface.ts`, whose
+ * docblock states the rule: the surface is derived, never held. Callers keep
+ * their existing `useSyncExternalStore` subscriptions (shell store, active
+ * authoring, the session registry); this module only reads.
+ */
+
+import { stageTransformDoor } from '@volter/sdk/contributions';
+import { getActiveAuthoring } from './authoring/active-adapter';
+import { CompositeAuthoringAdapter } from '@volter/sdk/kit/authoring/composite-authoring-adapter';
+import { documentStageSession } from '@volter/sdk/kit/document-stage-sessions';
+import {
+  isViewportToolContextVisible,
+  resolveViewportToolContext,
+} from './authoring/viewport-tool-context';
+import { isThreejsSurfaceVisible } from './authoring/three-root';
+import { stageStore } from './stage-store-registry';
+import { activeWorkspaceDocumentId, openWorkspaceDocuments } from '@volter/sdk/kit/workspace-document-registry';
+import type { ShellStore } from '@volter/sdk/kit/shell-store';
+
+export type StageSurface = 'three' | 'canvas' | 'dom';
+
+/** The documents painting a 2D canvas stage right now, as each says while it is mounted. */
+const canvasStageDocuments = new Map<string, number>();
+
+/** A document's canvas stage is mounted: its stage context reports the `canvas` surface (what a
+ *  2D view's keys key on) until the returned release runs. */
+export function markCanvasStageDocument(documentId: string): () => void {
+  canvasStageDocuments.set(documentId, (canvasStageDocuments.get(documentId) ?? 0) + 1);
+  return () => {
+    const left = (canvasStageDocuments.get(documentId) ?? 1) - 1;
+    if (left > 0) canvasStageDocuments.set(documentId, left);
+    else canvasStageDocuments.delete(documentId);
+  };
+}
+
+/** What the stage's document IS — the document's own `presentation()` kind
+ *  (`WorkspaceDocumentDescriptor.presentation`), folded to the subjects a
+ *  stage distinguishes. `unknown` when the descriptor declares none. */
+export type StageSubject =
+  | { readonly kind: 'composition' } // presentation 'scene' | 'world' (a scene, a manifest root)
+  | { readonly kind: 'story' } // 'story' — a piece in isolation with its parameters
+  | { readonly kind: 'artifact' } // 'asset' — an ecosystem artifact (glTF, particles, a model)
+  | { readonly kind: 'data' } // 'document' — an adapter-table document (a model, a page)
+  | { readonly kind: 'unknown' };
+
+export interface StageSelection {
+  readonly count: number;
+  /** The surface that owns the whole selection; null when empty or mixed. */
+  readonly surface: StageSurface | null;
+  /** Whether that owner is painted on this stage (hidden roots are not). */
+  readonly visible: boolean;
+}
+
+/**
+ * Whether the stage has chrome of its own, or is EMBEDDED in another surface
+ * with none (the inspector's object preview). It is a genuine condition OF THE
+ * STAGE — the same kind of fact as `surface`, `selection` and `play` — never
+ * the origin or kind of a document; and the HOST is the only thing that knows
+ * it, because an embedded preview has no workspace document at all (which is
+ * exactly why `subjectOf` answers `unknown` for one). So the host supplies it
+ * and nothing is inferred (decided 2026-09-18, an application of
+ * ARCHITECTURE-CORE §One stage's own rule).
+ */
+export type StageChrome = 'document' | 'embedded';
+
+export interface StageContext {
+  readonly documentId: string | null;
+  readonly chrome: StageChrome;
+  readonly subject: StageSubject;
+  /** The surface the stage paints; null when nothing is showing. */
+  readonly surface: StageSurface | null;
+  readonly selection: StageSelection;
+  readonly play: 'stopped' | 'playing' | 'paused';
+}
+
+const EMPTY_SELECTION: StageSelection = { count: 0, surface: null, visible: false };
+
+function stageSurfaceOf(kind: string | undefined): StageSurface | null {
+  return kind === 'three' || kind === 'canvas' || kind === 'dom' ? kind : null;
+}
+
+function subjectFromKind(kind: string | undefined): StageSubject {
+  switch (kind) {
+    case 'scene':
+    case 'world':
+      return { kind: 'composition' };
+    case 'story':
+      return { kind: 'story' };
+    case 'asset':
+      return { kind: 'artifact' };
+    case 'document':
+      return { kind: 'data' };
+    default:
+      return { kind: 'unknown' };
+  }
+}
+
+function subjectOf(documentId: string | null): StageSubject {
+  if (documentId === null) return { kind: 'unknown' };
+  const open = openWorkspaceDocuments().find((doc) => doc.descriptor.id === documentId);
+  if (!open) return { kind: 'unknown' };
+  const presentation = open.descriptor.presentation?.() ?? null;
+  const projected = subjectFromKind(presentation?.kind);
+  if (projected.kind !== 'unknown') return projected;
+  // The document's own declared KIND is the fallback, and it is a real answer
+  // rather than a guess: `presentation()` is the ADDRESSABLE projection of a
+  // document, and a document can legitimately have none while still being an
+  // artifact — `asset-documents.tsx:258` returns null for an ONLINE asset and
+  // for one with no project path, and reading only the projection took the
+  // studio stage off exactly those (measured 2026-09-18, which is why the
+  // `documentKind` prop could not simply be deleted without this).
+  return subjectFromKind(open.descriptor.kind);
+}
+
+/**
+ * Whether this adapter PAINTS a three surface at all, selection or not — the
+ * no-selection branch of what `threeSurfaceToolsApply` asked before this module
+ * existed, transcribed verbatim. A composite paints three when some child does;
+ * a single adapter paints three when it is not rect-capable and can hand back an
+ * `Object3D` for a node.
+ */
+function adapterPaintsThree(adapter: ReturnType<typeof getActiveAuthoring>): boolean {
+  if (adapter instanceof CompositeAuthoringAdapter)
+    return adapter.childAdapters().some((child) => child.kind === 'three');
+  return !adapter.rects && typeof adapter.hierarchy.object3D === 'function';
+}
+
+function worldStageContext(
+  store: ShellStore,
+  documentId: string | null,
+  subject: StageSubject,
+  chrome: StageChrome,
+): StageContext {
+  const adapter = getActiveAuthoring(store);
+  const surface: StageSurface | null =
+    isThreejsSurfaceVisible(store) && adapterPaintsThree(adapter) ? 'three' : null;
+  const play = store.playState;
+  const count = store.selectedEntityIds.size;
+  if (count === 0)
+    return { documentId, chrome, subject, surface, selection: EMPTY_SELECTION, play };
+  const context = resolveViewportToolContext(adapter, store.selectedEntityIds);
+  return {
+    documentId,
+    chrome,
+    subject,
+    surface,
+    selection: {
+      count,
+      surface: stageSurfaceOf(context?.kind),
+      visible: isViewportToolContextVisible(store, context),
+    },
+    play,
+  };
+}
+
+/**
+ * The stage a given document is showing.
+ *
+ * Two shapes answer this, and which one applies is a FACT about the document —
+ * not a kind it declares: a DOCUMENT stage has registered an
+ * `Object3DDocumentSession` (a model, a prefab story, an isolation scene) and
+ * its selection is its session's own; everything else is the WORLD stage — the
+ * manifest's roots under the shell store, whose selection is the shell's and
+ * whose surface is subject to the world-hidden eye.
+ */
+export function documentStageContext(
+  store: ShellStore,
+  documentId: string,
+  chrome: StageChrome = 'document',
+): StageContext {
+  const subject = subjectOf(documentId);
+  // A canvas document paints the 2D stage whatever else the world holds (a 3D game with a 2D
+  // root included); its keys follow this.
+  if (canvasStageDocuments.has(documentId)) {
+    const world = worldStageContext(store, documentId, subject, chrome);
+    return { ...world, surface: 'canvas' };
+  }
+  const session = documentStageSession(documentId);
+  if (session === null) {
+    // A RESOURCE document with no stage session of its own (a table, a
+    // report, a text document) shows no stage at all; only the world's own
+    // documents answer with the world stage.
+    const kind = openWorkspaceDocuments().find((doc) => doc.descriptor.id === documentId)
+      ?.descriptor.kind;
+    if (kind !== undefined && kind !== 'game' && kind !== 'scene' && kind !== 'world')
+      return {
+        documentId,
+        chrome,
+        subject,
+        surface: null,
+        selection: EMPTY_SELECTION,
+        play: store.playState,
+      };
+    return worldStageContext(store, documentId, subject, chrome);
+  }
+  // A document stage's own selection: the session reads it straight off its
+  // authoring adapter, and its stage is the only thing painting it, so an owner
+  // it reports is by construction three-owned and visible here.
+  const count = session.selection().length;
+  return {
+    documentId,
+    chrome,
+    subject,
+    surface: 'three',
+    selection: { count, surface: count > 0 ? 'three' : null, visible: true },
+    play: store.playState,
+  };
+}
+
+/** The stage the FOCUSED document is showing; the world stage when no document
+ *  is active (the shell with nothing focused still paints the world root). */
+export function focusedStageContext(store: ShellStore): StageContext {
+  const documentId = activeWorkspaceDocumentId();
+  if (documentId !== null) return documentStageContext(store, documentId);
+  return worldStageContext(store, null, { kind: 'unknown' }, 'document');
+}
+
+/**
+ * THE STORE THE FOCUSED STAGE RUNS ON — where a shared panel reads per-stage
+ * state (selection, scene/objectMap, camera pose, orbit target, tool state,
+ * view options like `showStats`/shading).
+ *
+ * `shell` is the answer for a focused document with no stage of its own — a
+ * tool tab, a text document, the Game tab. That is not a fallback in name
+ * only: the world root's stage runs on the session store (see
+ * `StageHost.tsx`'s world-root install), so a panel asked while focus sits
+ * off every stage keeps reporting the world, exactly as it did before §One
+ * stage unit 4.
+ *
+ * It is a FUNCTION, like the rest of this module: the caller keeps its own
+ * subscriptions, and a panel that reads this subscribes to
+ * `subscribeStageStores` and `subscribeWorkspaceDocuments` so a mount or a
+ * tab switch re-renders it against the new answer.
+ */
+export function focusedStageStore(shell: ShellStore): ShellStore {
+  return stageStore(activeWorkspaceDocumentId()) ?? shell;
+}
+
+/** The host transform strip on a stage's shelf (Blender's persistent rail),
+ *  where the editor viewport's own gizmo is what it drives. This is the
+ *  `gizmo` arm of {@link stageTransformDriver} and nothing else asks it. */
+export function transformToolsApply(ctx: StageContext): boolean {
+  if (ctx.surface !== 'three') return false;
+  if (ctx.selection.count === 0) return true;
+  return ctx.selection.surface === 'three' && ctx.selection.visible;
+}
+
+/**
+ * WHAT THE HOST'S TRANSFORM TOOLS DRIVE ON THIS STAGE — one answer the shelf's
+ * strip and the header's transform wells both ask.
+ *
+ * `gizmo`  `EditorViewport`'s `TransformControls`, through the stage's own
+ *          `EditorShellStore.transformMode` (`stage-store-registry.ts` — NOT
+ *          the shell's; see `ToolStrip`'s note for the measurement that
+ *          separates them). The header's four wells configure that same gizmo,
+ *          so they are drawn with it.
+ * `modal`  the stage transforms MODALLY instead and declared how
+ *          (`registerStageTransform`): a mesh module's `G`/`R`/`S`. The three
+ *          single-channel tools arm it; the all-handles tool and the header
+ *          wells are NOT DRAWN, because a modal transform is no gizmo and has
+ *          nothing for a well to configure.
+ * `none`   not a three stage, or the selection belongs to another surface —
+ *          `transformToolsApply`'s own condition, unchanged.
+ *
+ * A DOCUMENT STAGE IS NOT AUTOMATICALLY THE MODAL CASE, and assuming it was is
+ * the error this docblock replaces: measured 2026-09-19 on a prefab story, a
+ * session-painted stage DOES draw the host's gizmo on its selection. Only a
+ * stage that declares a door takes the modal arm.
+ */
+export type StageTransformDriver = 'gizmo' | 'modal' | 'none';
+
+export function stageTransformDriver(ctx: StageContext): StageTransformDriver {
+  if (!transformToolsApply(ctx)) return 'none';
+  return stageTransformDoor(ctx.documentId) === null ? 'gizmo' : 'modal';
+}
+
+/** The three tools that need a selection (ViewportOverlay, CameraInfo). */
+export function threeSelectionToolsApply(ctx: StageContext): boolean {
+  return (
+    ctx.surface === 'three' &&
+    ctx.selection.count > 0 &&
+    ctx.selection.surface === 'three' &&
+    ctx.selection.visible
+  );
+}
+
+/**
+ * THE ARTIFACT-FLAVOURED SUBJECT — a piece shown IN ISOLATION that is not the
+ * project's own live composition: an artifact (a glTF, a particle system, a
+ * model asset), a story (a prefab mounted with its parameters), or a stage
+ * EMBEDDED in another surface with no workspace document at all (the
+ * inspector's object preview, which is why nothing can infer this one and the
+ * host supplies `chrome`).
+ *
+ * This is the question `documentKind: 'source' | 'asset'` asked as a PROP the
+ * caller chose, and it is the base the two conditions below are written
+ * against, so they cannot drift apart: it drives the source adapter's
+ * `documentKind` (its "derived asset" provenance line and its `model-asset`
+ * hierarchy kind) and the `asset` performance-source kind.
+ *
+ * DATA is deliberately not here. A mesh module is the project's own CODE — it
+ * opens in an isolation scene (§A model is data) but nothing about it is a
+ * derived asset, and saying so is what the `documentKind` prop did by
+ * accident once the studio grew a data arm.
+ */
+export function assetSubjectApplies(ctx: StageContext): boolean {
+  return (
+    ctx.chrome === 'embedded' || ctx.subject.kind === 'story' || ctx.subject.kind === 'artifact'
+  );
+}
+
+/**
+ * THE STUDIO PRESENTATION — the alpha clear and the editor's own backdrop
+ * behind a piece in isolation.
+ *
+ * ARCHITECTURE-CORE §A model is data: "opening data opens an ISOLATION SCENE
+ * around it … whose story is the STUDIO". So the studio is every
+ * artifact-flavoured subject PLUS data — a mesh module, a page, anything the
+ * adapter's table calls a document.
+ *
+ * The one condition on the data arm is the LOOK, and it is a condition rather
+ * than a kind: the studio's backdrop is the EDITOR'S (the alpha canvas over the
+ * `.volter-object3d-studio-stage` bloom), and a look that declares its own
+ * `color.viewport` group has already said what the 3D viewport is painted —
+ * Blender's flat #3f3f3f — so painting the studio over it would be the editor
+ * overruling the skew.
+ *
+ * `lookPaintsViewport` is that group's presence, and it is a PARAMETER rather
+ * than a read inside here for two reasons: this module is derived-never-held
+ * and the look is not one of the stores its callers already subscribe to (the
+ * host subscribes to the theme root itself, `StageHost.tsx`); and importing
+ * the renderer's token reader here put `native-selection-style.ts` into
+ * `main.tsx`'s pinned closure for a layout predicate, which is the erosion the
+ * closure gate exists to stop (measured 2026-09-18: +1 file on `main.tsx` and
+ * on both builds). `native-selection-style.ts`'s `lookDeclaresViewportColors`
+ * is the one reader of that token, so the stage and the renderer cannot
+ * disagree about what is on screen.
+ */
+export function studioStageApplies(ctx: StageContext, lookPaintsViewport: boolean): boolean {
+  if (assetSubjectApplies(ctx)) return true;
+  return ctx.subject.kind === 'data' && !lookPaintsViewport;
+}
+
+/**
+ * THE IDENTITY-ROW FRAME — the Asset Lab shell around the stage: the row that
+ * names the thing, its type and its path, and the one registrar of the
+ * document's own workspace selection (the host registers it wherever this
+ * shell is absent, and exactly one of the two must).
+ *
+ * ARCHITECTURE-CORE §One stage: "the identity row when the subject is an
+ * ARTIFACT rather than source". It was the studio presentation's own answer
+ * until the studio gained a data arm, and it must not follow it there: a mesh
+ * module is the project's CODE, so an Asset-Lab row naming it a type and a
+ * file path, wrapped around the mesh editor's own header, would say the
+ * opposite of what the document is.
+ *
+ * An EMBEDDED stage never takes it — it has no chrome of its own by
+ * definition. Whether a STORY should keep it is the ruling's own open reading
+ * (a prefab's truth is source too); no frame of a story document has been
+ * read against that sentence, so this stays exactly what
+ * `assetSubjectApplies` says and nothing is re-decided blind.
+ */
+export function identityRowApplies(ctx: StageContext): boolean {
+  return ctx.chrome === 'document' && assetSubjectApplies(ctx);
+}

package/src/kit/stage-invalidation.ts

@@ -0,0 +1,25 @@
+/**
+ * THE EDITOR'S OWN CHANGES TO A STAGE'S PICTURE, announced.
+ *
+ * A stage whose content announces its changes (`ToolObject3DPreviewSource.
+ * onChange`) draws only when something changed (`StageHost`'s frame). The
+ * content's own changes, the camera, input on the stage, the stage store and
+ * playback are each watched there. What remains is the editor acting on a
+ * stage from outside all of those -- a view-menu toggle reaching the document
+ * session, a helper handed in, a postprocessing chunk that finished loading --
+ * and each of those calls {@link invalidateStages}.
+ *
+ * One counter for every stage rather than a flag per stage: such changes are
+ * rare, and a stage that draws one frame it did not strictly need costs
+ * nothing, while one that misses a change shows a stale picture.
+ */
+let generation = 0;
+
+export function invalidateStages(): void {
+  generation++;
+}
+
+/** Compared by each stage against the value it last drew at. */
+export function stageGeneration(): number {
+  return generation;
+}

package/src/kit/stage-store-registry.ts

@@ -0,0 +1,69 @@
+import type { ShellStore } from '@volter/sdk/kit/shell-store';
+/**
+ * WHICH STORE A STAGE RUNS ON — the live identities behind
+ * `focusedStageStore()` (`stage-context.ts`).
+ *
+ * ARCHITECTURE-CORE §One stage: no stage is on "the" store by birthright.
+ * Every mounted stage owns an `EditorShellStore` holding its own per-stage
+ * state — selection, scene/objectMap, camera pose, orbit target, tool state
+ * and view options — and the shared panels read whichever one the FOCUSED
+ * document's stage runs on. Before this, only one stage's store was reachable
+ * (the shell's), so a control mounted over a model or a prefab drove a
+ * different stage's state: the grid button toggled the world's grid, and the
+ * camera readout reported a camera nobody was looking through.
+ *
+ * A registry of live identities, deliberately shaped like
+ * `authoring/object3d-document-session-registry.ts` — the same job for the
+ * same objects, and the reason it is not merged into that module is that a
+ * stage has a store BEFORE it has a session (the world root's stage has no
+ * `Object3DDocumentSession` at all, measured 2026-09-18). A leaf module with
+ * no imports beyond the store's type, so any lane may read it without an
+ * import cycle.
+ */
+
+const stores = new Map<string, { store: ShellStore }>();
+let registryVersion = 0;
+const listeners = new Set<() => void>();
+
+function notify(): void {
+  registryVersion++;
+  for (const listener of [...listeners]) listener();
+}
+
+/** A mounted stage declares the store it runs on. Re-registering the same
+ *  document replaces it; the returned unregister drops it. */
+export function registerStageStore(documentId: string, store: ShellStore): () => void {
+  const registration = { store };
+  stores.set(documentId, registration);
+  notify();
+  return () => {
+    if (stores.get(documentId) !== registration) return;
+    stores.delete(documentId);
+    notify();
+  };
+}
+
+/** The store that document's stage runs on, or `null` for a document with no
+ *  stage of its own (a tool tab, a text document, the Game tab). */
+export function stageStore(documentId: string | null): ShellStore | null {
+  return documentId === null ? null : (stores.get(documentId)?.store ?? null);
+}
+
+/** The document whose stage runs on `store`, or null for a store no stage registered. */
+export function stageDocument(store: ShellStore): string | null {
+  for (const [documentId, registration] of stores) if (registration.store === store) return documentId;
+  return null;
+}
+
+/** `useSyncExternalStore` shape — a stage mounting or unmounting changes what
+ *  `focusedStageStore()` answers, so a panel that reads it subscribes here. */
+export function subscribeStageStores(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function stageStoresVersion(): number {
+  return registryVersion;
+}

package/src/kit/startup-failure.ts

@@ -0,0 +1,80 @@
+/**
+ * A TERMINAL STARTUP FAILURE, as the FRAME needs it: the product's loading
+ * cover (`volterCover.ts`, z-index above every part) sits over the whole
+ * editor while it opens, so an error screen drawn beneath it is seen by
+ * nobody. Measured on the owner's stream 2026-10-06: a pinned-engine refusal
+ * rendered under the cover while it said "Starting Blender…" with a moving bar
+ * forever. So whoever decides that startup failed publishes it here, and the
+ * bridge hands it to the cover (`mountEditor`'s `startup` door), which replaces
+ * its splash with the message and its fix.
+ *
+ * ANY PART OF THE BOOT PUBLISHES, not only AppRoot: a project that cannot be
+ * detected, a page with no project, an editor surface that crashed, a Blender
+ * worker that could not open the model. The newest failure is the one shown;
+ * `clearStartupFailure(source)` withdraws only that source's, so a Retry that
+ * cures one cause does not hide another.
+ *
+ * ONE REGISTRY PER PAGE, whichever copy of this module a contribution loaded
+ * it through (the packaged shell inlines the SDK while a package's
+ * contribution is served from the project's own copy), hence the
+ * `Symbol.for` key, as `document-play-extension.ts` does.
+ */
+export interface StartupFailureNotice {
+  readonly message: string;
+  readonly guidance: string | null;
+  /** The recovery as one pasteable line (`commandSequence`), when it has one. */
+  readonly command: string | null;
+  /**
+   * STILL TRYING, not refused: a slow start that may yet succeed (detection that keeps being
+   * re-asked). The cover shows it as progress under its splash, never as a refusal — a
+   * refusal is one-way, and a healthy slow start called failed is the reverse of the silent
+   * hang this door exists for (#147 review).
+   */
+  readonly transient?: boolean;
+}
+
+interface Registry {
+  /** Live failures by source, oldest first; the last is the one shown. */
+  readonly failures: Map<string, StartupFailureNotice>;
+  readonly listeners: Set<(notice: StartupFailureNotice | null) => void>;
+}
+
+const key = Symbol.for('volter.startup-failure');
+const page = globalThis as typeof globalThis & { [key]?: Registry };
+const registry: Registry = page[key] ??= { failures: new Map(), listeners: new Set() };
+
+/** The newest refusal, else the newest still-trying notice: a refusal is the stronger fact. */
+function current(): StartupFailureNotice | null {
+  const all = [...registry.failures.values()];
+  return all.filter((notice) => !notice.transient).at(-1) ?? all.at(-1) ?? null;
+}
+
+function publish(): void {
+  const notice = current();
+  for (const listener of [...registry.listeners]) {
+    try { listener(notice); } catch { /* A reader's failure is not the boot's. */ }
+  }
+}
+
+/** This page's boot failed for `source`'s reason; the cover shows it at once. */
+export function reportStartupFailure(source: string, notice: StartupFailureNotice): void {
+  registry.failures.delete(source);
+  registry.failures.set(source, notice);
+  publish();
+}
+
+/** `source`'s failure is over (a Retry got past it). Other sources' stand. */
+export function clearStartupFailure(source: string): void {
+  if (registry.failures.delete(source)) publish();
+}
+
+/** Hear this page's startup failure — at once if one is standing — and `null`
+ *  when the last one clears. */
+export function subscribeStartupFailure(
+  listener: (notice: StartupFailureNotice | null) => void,
+): () => void {
+  registry.listeners.add(listener);
+  const notice = current();
+  if (notice) listener(notice);
+  return () => { registry.listeners.delete(listener); };
+}