@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/document-open-registry.ts

@@ -0,0 +1,200 @@
+/**
+ * A DOCUMENT KIND OWNS HOW IT OPENS — the forward half of the seam whose
+ * backward half is `workspace-document-restore.ts` (docs/WORKBENCH.md §host
+ * versus package).
+ *
+ * THE RULE. The host ADDRESSES a document (a story on a module, an asset at a
+ * path); it does not construct one. A module that can open a kind registers an
+ * opener under a named id, and every host call site — the palette, the
+ * hierarchy's double-click, the Edit tab row, the layout restore, the view
+ * protocol, the SDK's `host.workspace` door — asks for that id instead of
+ * importing the document module. When nothing has registered the id (a build
+ * whose package list does not carry that kind, a contribution that has not
+ * loaded yet) the answer is `null`, and the caller does what it already did
+ * for a document it could not open.
+ *
+ * WHY IT EXISTS. `workspace-document-restore.ts` fixed the PERSISTENCE half:
+ * the host no longer names a document module to reopen one. The opening half
+ * was still `import { openThreeStoryDocument } from './components/…'` in ten
+ * host files, which is the same serialization defect one rung earlier — a
+ * document cannot leave for a package while the shell calls its constructor by
+ * name. Measured 2026-09-18 (WORK.md §The open-source launch, phase 1 unit 4).
+ *
+ * WHAT AN ID IS. A string in the host's own vocabulary, declared beside the
+ * kind's other host-side contracts (`stories/story-document-openers.ts` is the
+ * first), with a request type declared in the SAME place so both sides of the
+ * seam are typed against one declaration rather than against each other.
+ * Several modules may register one id; they are tried in registration order
+ * until one returns a document id.
+ */
+
+import type { WorkspaceStateStore } from './workspace-document-restore';
+
+export interface DocumentOpener<Request> {
+  /** The opener id — the address vocabulary, not a module name. */
+  readonly id: string;
+  /** Which module registered it. Re-registering the same owner+id REPLACES,
+   *  so an HMR re-evaluation leaves one opener, not two. */
+  readonly owner: string;
+  /**
+   * Open (or activate) the document this request addresses, and answer its
+   * document id. `null` = this opener cannot serve THIS request (an
+   * undeclared medium, a story that is no longer exported); the next
+   * registered opener is tried.
+   *
+   * THROWING is the third answer, and it is different from `null`: "this
+   * address is MINE and it is broken" — a table that lists no such entry, a
+   * contribution whose module threw on import. The throw reaches the caller
+   * with the kind's own sentence instead of the host's generic "nothing can
+   * open this", which is the only way a reader learns which of the two
+   * happened. Only an opener that OWNS the id may throw; one of several
+   * openers sharing an id answers `null` so its siblings still get their turn.
+   */
+  readonly open: (store: WorkspaceStateStore, request: Request) => string | null;
+  /**
+   * The kind's own async settling step, awaited by
+   * {@link openRegisteredDocumentAsync} ONLY after a first synchronous attempt
+   * answered `null` — refresh the ledger this kind opens documents out of, then
+   * the attempt is made once more.
+   *
+   * It mirrors `WorkspaceDocumentRestorer.prepare` deliberately: a kind is the
+   * only thing that knows what "I might be able to open this once I have looked
+   * again" means, and the host must not hold that knowledge to address a
+   * document. Absent means one attempt is the whole answer.
+   *
+   * IT RECEIVES THE REQUEST, because settling is per-address: waiting for THIS
+   * table entry, loading THIS module, refreshing the contribution that would
+   * carry THIS id. `stories/story-opener.ts:92` is the evidence —
+   * it keeps two module-level `unsettled*` sets whose only job is to carry the
+   * failed request across to a settle that could not see it. (Existing openers
+   * that ignore the argument are unaffected; the dedupe below is by function
+   * identity, so one settle still runs once per attempt.) Like `open`, it may
+   * THROW to refuse the address with the kind's own sentence.
+   */
+  readonly settle?: (request: Request) => Promise<void>;
+  /**
+   * The kind's own POST-open readiness — `settle`'s mirror on the other side of
+   * the answer, awaited by {@link openRegisteredDocumentAsync} once an opener
+   * has produced a document id, before the caller is told the view is present.
+   *
+   * It exists because "opened" and "ready to be driven" are different instants
+   * for some kinds and the host cannot know which: an asset document answers
+   * its id the moment the tab is registered, while an immediate
+   * inspect/setField against it needs the Inspector mounted and (for a model)
+   * its live adapter installed — `waitForAssetDocumentInspector`, which the
+   * presenter used to await by hand because it knew the asset family's rule.
+   * Absent means the id IS the whole answer. May THROW to refuse.
+   *
+   * A synchronous caller ({@link openRegisteredDocument}) cannot await it, the
+   * same way it cannot settle — it gets the id and the kind's own doors are
+   * what it waits on.
+   */
+  readonly ready?: (documentId: string, request: Request) => Promise<void>;
+}
+
+// The registry is heterogeneous by construction — one id, one request type,
+// checked at both ends by the shared declaration the id comes from.
+// biome-ignore lint/suspicious/noExplicitAny: the map is keyed by id, not by type.
+const _openers = new Map<string, DocumentOpener<any>[]>();
+
+/** Install an opener. Returns the teardown. */
+export function registerDocumentOpener<Request>(opener: DocumentOpener<Request>): () => void {
+  const existing = _openers.get(opener.id) ?? [];
+  const next = existing.filter((item) => item.owner !== opener.owner);
+  next.push(opener);
+  _openers.set(opener.id, next);
+  return () => {
+    const current = _openers.get(opener.id);
+    if (!current) return;
+    const remaining = current.filter((item) => item !== opener);
+    if (remaining.length === 0) _openers.delete(opener.id);
+    else _openers.set(opener.id, remaining);
+  };
+}
+
+/** Whether anything can open this id in THIS session — what a palette asks
+ *  before offering an action that would otherwise do nothing. */
+export function hasDocumentOpener(id: string): boolean {
+  return (_openers.get(id)?.length ?? 0) > 0;
+}
+
+/**
+ * Every address this session can open, sorted. The generic answer to "what
+ * DOES this editor open?", which is what a refusal owes its reader: a build
+ * whose package list carries no opener for the kind is a configuration fact,
+ * and naming the addresses that ARE registered is the difference between
+ * "this is broken" and "this editor is not that editor".
+ */
+export function registeredDocumentOpenerIds(): readonly string[] {
+  return [..._openers.keys()].sort();
+}
+
+/**
+ * Open the document this request addresses, through whichever registered
+ * opener claims it. `null` = nothing here can open it, which is the same
+ * answer the host already gives for a story with no declared medium.
+ */
+export function openRegisteredDocument<Request>(
+  id: string,
+  store: WorkspaceStateStore,
+  request: Request,
+): string | null {
+  for (const opener of _openers.get(id) ?? []) {
+    const opened = opener.open(store, request);
+    if (opened !== null) return opened;
+  }
+  return null;
+}
+
+/**
+ * The same question, asked where the caller can wait: try the registered
+ * openers once; if none claimed the request, let each kind SETTLE (refresh the
+ * ledger it opens out of) and try once more. Used by the VIEW PROTOCOL, which
+ * is already async and is the one caller that addresses a document by a name a
+ * person or an agent typed — the subject may simply not have been fetched yet.
+ */
+export async function openRegisteredDocumentAsync<Request>(
+  id: string,
+  store: WorkspaceStateStore,
+  request: Request,
+): Promise<string | null> {
+  const openers = _openers.get(id) ?? [];
+  const direct = claim(openers, store, request);
+  if (direct) return settleReady(direct, request);
+  if (openers.length === 0) return null;
+  const settled = new Set<(request: Request) => Promise<void>>();
+  for (const opener of openers) if (opener.settle) settled.add(opener.settle);
+  for (const settle of settled) await settle(request);
+  if (settled.size === 0) return null;
+  const retried = claim(openers, store, request);
+  return retried === null ? null : settleReady(retried, request);
+}
+
+/** The first opener that answers a document id, and WHICH one — the async door
+ *  needs the identity because `ready` belongs to the opener that claimed, not
+ *  to every opener sharing the address. */
+function claim<Request>(
+  // biome-ignore lint/suspicious/noExplicitAny: the map is keyed by id, not by type.
+  openers: readonly DocumentOpener<any>[],
+  store: WorkspaceStateStore,
+  request: Request,
+): { opener: DocumentOpener<Request>; documentId: string } | null {
+  for (const opener of openers) {
+    const documentId = opener.open(store, request);
+    if (documentId !== null) return { opener, documentId };
+  }
+  return null;
+}
+
+async function settleReady<Request>(
+  claimed: { opener: DocumentOpener<Request>; documentId: string },
+  request: Request,
+): Promise<string> {
+  await claimed.opener.ready?.(claimed.documentId, request);
+  return claimed.documentId;
+}
+
+/** Test-only reset (mirrors the restore registry's own). */
+export function __resetDocumentOpenersForTest(): void {
+  _openers.clear();
+}

package/src/kit/document-play-extension.ts

@@ -0,0 +1,221 @@
+/** Optional document capability. A tool owns its controls, state and runner;
+ * a document kind owns the detached stage it lends that runner. Products name
+ * neither side. The page-wide registry joins packaged and served contributions. */
+import type { ComponentType } from 'react';
+import type { ModelPlayLogEntry } from '../types';
+
+export interface DocumentPlayControlProps {
+  readonly documentId: string | undefined;
+  readonly onClose: () => void;
+}
+export interface DocumentPlayStage {
+  readonly documentId: string;
+  readonly sourcePath: string;
+  readonly root: unknown;
+  readonly camera: () => unknown;
+  /** The editing area's current draw camera, before handing its view to Play. */
+  readonly editingCamera: () => unknown;
+  readonly onFrame: (fn: (seconds: number) => void) => () => void;
+  readonly report: (title: string, detail: string) => void;
+  readonly container: HTMLElement;
+  /** The runner has updated its first drawable frame. */
+  readonly ready: () => void;
+  /** The return camera is approaching the editing pose; fade authoring chrome back in. */
+  readonly returning: () => void;
+  /** A copy of one of `root`'s materials that one object can wear alone and a runner can
+   *  recolour, keeping the document's own draw hooks; null for a material that is not the
+   *  document's. Absent, a runner clones. */
+  readonly ownMaterial?: (material: unknown) => unknown;
+  /** The copy's characters' clips, bound to `root` (the document's skins and actions), which the
+   *  runner advances on the game's clock. Absent, the document lends no animation and rigged
+   *  objects stand in their exported pose. */
+  readonly animation?: DocumentPlayAnimation;
+}
+export type DocumentPlayAnswer = { ok: true; armature: string } | { ok: false; why: string };
+
+export interface DocumentPlayActionOptions {
+  readonly fade?: number;
+  readonly loop?: boolean;
+  readonly speed?: number;
+  readonly restart?: boolean;
+}
+
+export interface DocumentPlayTrackOptions extends DocumentPlayActionOptions {
+  readonly action?: string;
+  readonly influence?: number;
+  readonly mute?: boolean;
+}
+/** A document's animation, lent to a runner. Objects are the runner's own (`root`'s descendants). */
+export interface DocumentPlayAnimation {
+  clips(object: unknown): readonly string[];
+  /** The active action (`animation_data.action`), crossfaded from the last. */
+  play(object: unknown, action: string, options?: DocumentPlayActionOptions): DocumentPlayAnswer;
+  stop(object: unknown, fade?: number): void;
+  playing(object: unknown): string | null;
+  /** An NLA track by name: an action for it, its influence, its mute; `null` gives it back. */
+  track(object: unknown, name: string, options: DocumentPlayTrackOptions | null): DocumentPlayAnswer;
+  /** A bone constraint's influence, or the object it aims at. */
+  constraint(object: unknown, bone: string, name: string, options: { influence?: number; target?: unknown }): DocumentPlayAnswer;
+  update(dt: number): void;
+  readonly warnings: readonly string[];
+  dispose(): void;
+}
+/**
+ * A RUNNING GAME'S CLOCK, as the Play tool keeps it. The numbers are the ones the runner handed
+ * the game, not the page's: `time` is the sum of every `dt` the script's `update` was given, so it
+ * stands still while paused and runs at `speed` times the page's own clock otherwise.
+ */
+export interface DocumentPlayClock {
+  /** Simulation seconds since this run began (the sum of the `dt`s the game was handed). */
+  readonly time: number;
+  /** Updates the game has run since this run began. */
+  readonly tick: number;
+  readonly paused: boolean;
+  /** Simulation seconds per real second; one of the transport's `speeds`. */
+  readonly speed: number;
+  /** While playing with no game running because the script failed to start or threw: why. The
+   *  run stays playing (a save of the script retries it); a running game clears it. */
+  readonly failure?: string | null;
+  /** A game has started in this run and is running (its first update ran). False while the run
+   *  is still preparing, and while it plays with a `failure`. Absent from a tool that predates
+   *  it, which cannot say. A reader that must know whether Play WORKED (the CLI's `play`) waits
+   *  for this or for `failure`, never for "playing" alone. */
+  readonly running?: boolean;
+}
+/**
+ * THE GAME'S TRANSPORT — what a Play tool offers beyond Play and Stop, for a layout that draws a
+ * game panel (Cyclotron's Game mode, `@volter/editor-blender`). Optional: a tool without
+ * one still plays and stops, and a layout draws only the controls a tool answers.
+ */
+export interface DocumentPlayTransport {
+  /** The speeds `setSpeed` accepts, slowest first. */
+  readonly speeds: readonly number[];
+  clock(documentId: string): DocumentPlayClock;
+  /** The clock moves every played frame, so it has a subscription of its own: `subscribe` would
+   *  re-render everything that only asks whether a document plays. */
+  subscribeClock(listener: () => void): () => void;
+  /** Hold or release the game's updates; the stage keeps drawing the frozen copy. */
+  setPaused(documentId: string, paused: boolean): void;
+  /** One update while paused, with one nominal frame's `dt`. */
+  step(documentId: string): void;
+  setSpeed(documentId: string, speed: number): void;
+  /** Begin the run again on a FRESH detached copy, the clock at zero. */
+  restart(documentId: string): void;
+  /**
+   * THE DOCUMENT COULD NOT LEND A STAGE (its rendered draw failed to prepare), so no runner
+   * ever started. The run stays playing with `failure` on the clock and a `script-error` entry
+   * (phase `stage`) in the play log, so the Game panel and `play-log` say why; Stop ends it and
+   * Restart tries again. Absent, the document stops the play and reports by notification.
+   */
+  fail?(documentId: string, sourcePath: string, failure: string): void;
+  /** Changes on every restart. The document that lends the stage keys its detached copy on it,
+   *  so a new generation is a new copy; the change is announced through `subscribe`. */
+  generation(documentId: string): number;
+  /** Whether the running game's own bot drives, and whether it offers one; a change is
+   *  announced through `subscribeClock`. Absent, the tool has no autoplay. */
+  autoplay?(documentId: string): DocumentPlayAutoplay;
+  /** Switch the bot on (it must be offered, and the game playing) or off. On drives one of the
+   *  bot's behaviours (`behavior`, required when it offers several) for at most `limit`
+   *  simulation seconds (the tool's default when absent). */
+  setAutoplay?(documentId: string, on: boolean, by: 'panel' | 'cli', request?: DocumentPlayAutoplayRequest): void;
+  /** While stopped, ask the next start to switch the bot on as soon as its script offers one
+   *  (`armed`); dropped if it offers none, or not the behaviour asked for. Absent, autoplay can
+   *  only be switched while running. */
+  armAutoplay?(documentId: string, armed: boolean, request?: DocumentPlayAutoplayRequest): void;
+}
+export interface DocumentPlayAutoplayRequest {
+  readonly behavior?: string | null;
+  readonly limit?: number | null;
+}
+/**
+ * AUTOPLAY, AS THE EDITOR OWNS IT: a game offers a bot, the editor decides whether it drives.
+ * Off whenever a run begins; a person's input in the game turns it off (`takeover`), and so does
+ * the run's limit (`limit`).
+ */
+export interface DocumentPlayAutoplay {
+  readonly on: boolean;
+  /** The running game registered a bot. */
+  readonly available: boolean;
+  /** Who made the last change: `script` is the game no longer offering a bot, `limit` the run's
+   *  simulation seconds spent. */
+  readonly by: 'panel' | 'cli' | 'takeover' | 'script' | 'limit' | null;
+  /** Armed while stopped (`armAutoplay`): the next start turns it on once a bot is offered. */
+  readonly armed?: boolean;
+  /** The behaviours the bot offers, and the one driving (or armed). Absent from older tools. */
+  readonly behaviors?: readonly string[];
+  readonly behavior?: string | null;
+  /** This run's limit and the simulation time it began at, in simulation seconds. */
+  readonly limit?: number | null;
+  readonly since?: number | null;
+  /** A person's key or pointer reached the game in this run: with autoplay off, they drive. */
+  readonly person?: boolean;
+  /** What the bot last said it is doing. */
+  readonly state?: string | null;
+  /** Why the last arm was not taken when the game started; null otherwise. */
+  readonly refused?: string | null;
+}
+/** The newest entries of one document's play log, for a panel that draws it live. */
+export interface DocumentPlayLog {
+  tail(documentId: string, last: number, kind?: string): {
+    readonly total: number;
+    readonly kinds: readonly string[];
+    readonly entries: readonly ModelPlayLogEntry[];
+  };
+  /** Every write to any document's log; several land in one frame, so coalesce. */
+  subscribe(listener: () => void): () => void;
+}
+export interface DocumentPlayExtension {
+  readonly Control: ComponentType<DocumentPlayControlProps>;
+  readonly Menu: ComponentType<DocumentPlayControlProps>;
+  playing(documentId: string): boolean;
+  /** Intended live frame shape; absent/null lets the document fill its area. */
+  aspectRatio?(documentId: string): number | null;
+  setPlaying(documentId: string, value: boolean): void;
+  escape?(documentId: string): void;
+  subscribe(listener: () => void): () => void;
+  run(stage: DocumentPlayStage): () => void;
+  /** Pause, step, speed, restart and the clock, when the tool keeps them. */
+  readonly transport?: DocumentPlayTransport;
+  /** The run's play log, when the tool keeps one. */
+  readonly log?: DocumentPlayLog;
+  /** The project path of the script this tool would run for a document's source file. */
+  scriptPath?(sourcePath: string): string;
+  /** Whether that script exists: `null` while the tool has not looked yet. A change is announced
+   *  through `subscribe`. A layout uses it to open a document as a game or as a model. */
+  hasScript?(sourcePath: string): boolean | null;
+}
+const key = Symbol.for('volter.document-play-extensions');
+interface Registry {
+  extensions: Map<string, DocumentPlayExtension>;
+  listeners: Set<() => void>;
+}
+const page = globalThis as typeof globalThis & { [key]?: Registry };
+const registry = page[key] ??= { extensions: new Map(), listeners: new Set() };
+function publish(): void { for (const listener of registry.listeners) listener(); }
+export function documentPlayExtension(kind: string): DocumentPlayExtension | null {
+  return registry.extensions.get(kind) ?? null;
+}
+/** Host shells wrap adapter entries as generic documents. Ask the capability
+ * owners about this document's identity rather than treating that wrapper's
+ * semantic kind as the adapter's registered Play kind. */
+export function documentPlaying(documentId: string): boolean {
+  for (const extension of registry.extensions.values()) {
+    if (extension.playing(documentId)) return true;
+  }
+  return false;
+}
+export function subscribeDocumentPlayExtensions(listener: () => void): () => void {
+  registry.listeners.add(listener);
+  return () => { registry.listeners.delete(listener); };
+}
+export function registerDocumentPlayExtension(kind: string, extension: DocumentPlayExtension): () => void {
+  if (registry.extensions.has(kind)) throw new Error(`A Play tool already owns ${kind} documents.`);
+  registry.extensions.set(kind, extension);
+  const stop = extension.subscribe(publish);
+  publish();
+  return () => {
+    stop();
+    if (registry.extensions.get(kind) === extension) registry.extensions.delete(kind);
+    publish();
+  };
+}

package/src/kit/document-preview-source.ts

@@ -0,0 +1,20 @@
+import type { EditorCameraState } from '../index';
+
+export const DOCUMENT_PREVIEW_WIDTH = 320;
+export const DOCUMENT_PREVIEW_HEIGHT = 180;
+export const DOCUMENT_PREVIEW_RECIPE = 'document-preview-v4';
+
+export interface DocumentPreviewCaptureRequest {
+  readonly width: number;
+  readonly height: number;
+  readonly camera?: EditorCameraState | undefined;
+}
+
+/** The document owner supplies pixels and dependency identity; the host owns
+ * scheduling, disk cache, visibility priority, and tile state. */
+export interface DocumentPreviewSource {
+  /** Stable identity for source and imported-dependency state. */
+  revision(): string;
+  subscribe(listener: () => void): () => void;
+  capture(request: DocumentPreviewCaptureRequest): Promise<string>;
+}

package/src/kit/document-renderer-session.ts

@@ -0,0 +1,138 @@
+import {
+  isEditorPresentationActive,
+  subscribeEditorPresentationActivity,
+} from '@volter/sdk/kit/editor-presentation-activity';
+
+/**
+ * The frame-loop + renderer lifetime for one Object3D document viewport.
+ *
+ * Deactivate ≠ dispose.
+ *
+ * The layout host keeps every open document mounted. A tab
+ * flip only flips `active`. Destroying the `WebGLRenderer` on deactivate is
+ * a full context teardown + recreate on the next flip — measured live on
+ * `examples/third-person` at 4296 ms for the first 3D-board activation and
+ * 4015 ms for the second (doctor `--timings-only`). Pause the RAF loop
+ * instead; the canvas keeps its last frame and the program cache / IBL bake
+ * survive. Real document CLOSE unmounts the host, and {@link dispose} is the
+ * one path that frees the context.
+ */
+
+export class DocumentRendererSession {
+  private rafId = 0;
+  private running = false;
+  private disposed = false;
+  private active = false;
+  private readonly unsubscribeActivity: () => void;
+
+  constructor(
+    private readonly frame: (time: number, resumed: boolean) => void,
+    private readonly releaseRenderer: () => void,
+  ) {
+    this.unsubscribeActivity = subscribeEditorPresentationActivity(() => this.syncActivity());
+  }
+
+  get isDisposed(): boolean {
+    return this.disposed;
+  }
+
+  get isRunning(): boolean {
+    return this.running;
+  }
+
+  /**
+   * Tab flip. `false` pauses the loop and keeps the GPU surface. `true`
+   * resumes it. Neither constructs nor disposes a renderer.
+   */
+  setActive(active: boolean): void {
+    if (this.disposed) return;
+    this.active = active;
+    this.syncActivity();
+  }
+
+  private syncActivity(): void {
+    if (this.active && isEditorPresentationActive()) this.start();
+    else this.stop();
+  }
+
+  /** Resizing clears the drawing buffer. Repaint immediately while visible;
+   * a suspended document redraws as soon as its presentation resumes. */
+  redraw(): void {
+    if (this.running && !this.disposed && isEditorPresentationActive()) {
+      this.guardedFrame(performance.now());
+    }
+  }
+
+  /** The one teardown path — document CLOSE / host unmount. */
+  dispose(): void {
+    this.stop();
+    if (this.disposed) return;
+    this.disposed = true;
+    this.unsubscribeActivity();
+    this.releaseRenderer();
+  }
+
+  private start(): void {
+    if (this.disposed || this.running) return;
+    this.running = true;
+    // A tab activation is a direct request to present this document. Draw one
+    // frame in the activation turn, then join the browser's animation clock.
+    // Waiting for the first rAF made a visible tab inherit Chromium's former
+    // background cadence (the 1 Hz signature) even when the page itself was
+    // visible; users saw the old canvas for that whole interval. Subsequent
+    // presentation remains ordinary rAF-driven work.
+    // Let content reset its delta baseline without advancing by the hidden interval.
+    this.guardedFrame(performance.now(), true);
+    if (!this.running || this.disposed) return;
+    this.rafId = requestAnimationFrame(this.tick);
+  }
+
+  /** The last frame's failure text, so a persistent fault narrates ONCE
+   *  rather than sixty times a second, and a recovered loop resets. */
+  private lastFrameFailure: string | null = null;
+
+  /**
+   * One frame, and the loop survives it. A throw out of a rAF callback used
+   * to be the end of this document's presentation: the exception left
+   * `tick` before it rescheduled, so the stage froze on whatever it last
+   * drew and nothing said why. Measured (2026-09-04, the mesh document's
+   * session swap): three's "Cannot read properties of null (reading
+   * 'precision')" from one frame drawn between a disposed overlay and the
+   * scene swap killed the stage for the rest of the session. The frame's
+   * failure goes to the console WITH its stack — that is what reaches the
+   * doors — and the next frame is drawn, because a transient race recovers
+   * on its own and a persistent fault is still better shown than frozen.
+   */
+  private guardedFrame(time: number, resumed = false): void {
+    try {
+      this.frame(time, resumed);
+      this.lastFrameFailure = null;
+    } catch (caught) {
+      const text = caught instanceof Error ? caught.message : String(caught);
+      if (text !== this.lastFrameFailure) {
+        this.lastFrameFailure = text;
+        // biome-ignore lint/suspicious/noConsole: a document frame that threw must narrate itself
+        console.error('[document renderer] a frame threw; the loop continues:', caught);
+      }
+    }
+  }
+
+  private stop(): void {
+    this.running = false;
+    if (this.rafId !== 0) {
+      cancelAnimationFrame(this.rafId);
+      this.rafId = 0;
+    }
+  }
+
+  private readonly tick = (time: number): void => {
+    if (!this.running || this.disposed) return;
+    if (!isEditorPresentationActive()) {
+      this.stop();
+      return;
+    }
+    this.guardedFrame(time);
+    if (!this.running || this.disposed) return;
+    this.rafId = requestAnimationFrame(this.tick);
+  };
+}

package/src/kit/document-stage-sessions.ts

@@ -0,0 +1,26 @@
+/**
+ * Which open documents run a stage session of their own, and what that session has selected —
+ * the part of a media integration's document session the kit's stage context reads. The Three
+ * integration registers each Object3D document session here as it registers it for itself; the
+ * kit names no viewport.
+ */
+export interface DocumentStageSession {
+  readonly documentId: string;
+  /** The session's own selection, read straight off its authoring adapter. */
+  selection(): readonly string[];
+}
+
+const sessions = new Map<string, DocumentStageSession>();
+
+/** Register a document's stage session. Returns the teardown. */
+export function registerDocumentStageSession(session: DocumentStageSession): () => void {
+  sessions.set(session.documentId, session);
+  return () => {
+    if (sessions.get(session.documentId) === session) sessions.delete(session.documentId);
+  };
+}
+
+/** The document's stage session, or null when it runs none (a table, a report, the world). */
+export function documentStageSession(documentId: string): DocumentStageSession | null {
+  return sessions.get(documentId) ?? null;
+}