@volter/editor-core 0.5.57

package/src/creation-site-registry.ts

@@ -0,0 +1,160 @@
+/**
+ * The creation-site registry — the host-side half of the index whose
+ * source half is `server/creation-site-transform.ts`.
+ *
+ * ANTI-SHIM: the record NEVER touches the object. A `WeakMap` keyed by the
+ * constructed object is the whole storage, so an ingested game cannot see that
+ * it is being indexed — no new property, no symbol, no `userData` key, nothing
+ * enumerable, nothing a `for…in`/`Object.keys`/JSON round-trip can pick up.
+ * (This is the same rule the ingest adapter follows for its structural ids'
+ * sole exception, `userData.entityId`, which is a deliberate, documented
+ * identity tag; a provenance record has no such justification.)
+ *
+ * RESOURCE OWNERSHIP (brief-rule 4).
+ *  - THE MAP is owned by this module and scoped to the editor page's realm.
+ *    Every same-realm mount in the page shares it, which is correct: the
+ *    stamped modules are ordinary modules in that one realm and their `new`
+ *    expressions have exactly one place to report to.
+ *  - IT IS NEVER CLEARED, deliberately. A `WeakMap` holds no strong reference,
+ *    so a record dies with the object it describes — a game teardown that
+ *    dropped its scene has already emptied the registry of everything that
+ *    mattered. An explicit `clear()` on teardown would be a no-op dressed as
+ *    cleanup, and it would be WRONG for the upgrade path, where a late-captured
+ *    mount reuses objects constructed before the capture.
+ *  - THE INSTALLED GLOBAL is the ownable resource, and it has one owner:
+ *    `installGatedGameGlobals` (`gated-globals.ts`) installs it alongside the
+ *    other `__vgai*` game-realm globals, once, at the same point in the
+ *    lifecycle. {@link installCreationSiteRecorder} returns an uninstall for
+ *    tests, which is the only caller that needs to take it back down.
+ */
+
+/** A source location a stamped `new` expression reported. */
+export interface CreationSite {
+  /** Project-root-RELATIVE path, POSIX separators (e.g. `src/scripts/sim/city.js`). */
+  file: string;
+  /** 1-based. */
+  line: number;
+  /** 0-based character offset. */
+  col: number;
+}
+
+/**
+ * What the read surfaces show for one object: either the anchor, or a NAMED
+ * reason there is none. There is no third, blank state — an unanchored object
+ * says why (the honest-floor rule).
+ */
+export type CreationSiteAnchor =
+  | ({ anchored: true; kind: 'source'; display: string } & CreationSite)
+  | { anchored: false; reason: string };
+
+/** The reason for an object that exists but was not constructed by a `new`
+ *  expression in a served project module — a three.js internal, a GLTF
+ *  loader's mesh, anything from a bundled dependency. The anchoring does not
+ *  reach these, so this is what the surfaces say, verbatim. */
+export const UNANCHORED_REASON =
+  'constructed outside project source (library internals or loader output)';
+
+/** The reason for a selection with no live object behind it at all. */
+export const NO_OBJECT_REASON = 'no live object for this selection';
+
+const sites = new WeakMap<object, CreationSite>();
+
+/**
+ * How many objects each anchor has constructed — the MULTIPLICITY signal.
+ *
+ * SimCity builds all 256 tiles from one line (`const tile = new Tile(x, y)`,
+ * `src/scripts/sim/city.js:59`), so "can this edit be written at its creation
+ * site?" has a second answer beyond "is there a literal there": writing that
+ * line would move every tile, and writing it for one tile is a lie about what
+ * the source says. Nothing else in the system knows the count — the WeakMap
+ * above is deliberately un-enumerable — so it is counted here, at the one place
+ * every construction reports to.
+ *
+ * A PLAIN `Map`, not a WeakMap, and never decremented: the count is over
+ * CONSTRUCTIONS, not live objects. That is the conservative direction — a site
+ * that built and dropped a hundred objects still refuses, which costs a refusal
+ * the user can read, where a count that forgot its history would eventually let
+ * a shared site be written as if it were unique. It is keyed by the site string,
+ * so it holds no reference to anything the game owns and cannot leak an object.
+ */
+const instances = new Map<string, number>();
+
+function siteKey(site: CreationSite): string {
+  return `${site.file}:${site.line}:${site.col}`;
+}
+
+/** The global name the served prelude calls through (must match
+ *  `CREATION_SITE_GLOBAL` in `server/creation-site-transform.ts`; the pairing is
+ *  asserted by `creation-site-registry.test.ts`). */
+export const CREATION_SITE_GLOBAL = '__vgaiRecordCreationSite';
+
+type Recorder = (o: unknown, file: string, line: number, col: number) => void;
+
+/**
+ * Record one construction. FIRST WRITE WINS: a constructor that returns an
+ * already-registered object (a cache, a singleton, an interned value) must not
+ * have its true creation site overwritten by the call site that merely asked
+ * for it again.
+ */
+export function recordCreationSite(o: unknown, file: string, line: number, col: number): void {
+  if (o === null || (typeof o !== 'object' && typeof o !== 'function')) return;
+  if (sites.has(o as object)) return;
+  const site: CreationSite = { file, line, col };
+  sites.set(o as object, site);
+  const key = siteKey(site);
+  instances.set(key, (instances.get(key) ?? 0) + 1);
+}
+
+/**
+ * How many objects this anchor has constructed. `0` for a site nothing was ever
+ * recorded at. Only `1` may be written by a single-object edit; a deliberate
+ * creation-site-default edit may address the full count after naming it — see
+ * `creation-site-edit.ts`'s `CreationSiteWriteScope`.
+ */
+export function instancesAtSite(site: CreationSite): number {
+  return instances.get(siteKey(site)) ?? 0;
+}
+
+/** Test-only: forget every recorded construction count. The WeakMap needs no
+ *  equivalent (it is collected with its keys) and deliberately has none. */
+export function resetCreationSiteCountsForTest(): void {
+  instances.clear();
+}
+
+/** The raw record for an object, or `null`. */
+export function creationSiteOf(o: unknown): CreationSite | null {
+  if (o === null || (typeof o !== 'object' && typeof o !== 'function')) return null;
+  return sites.get(o as object) ?? null;
+}
+
+/** `src/scripts/sim/city.js:59` — the text the inspector shows and `vgai eval` reads. */
+export function formatCreationSite(site: CreationSite): string {
+  return `${site.file}:${site.line}`;
+}
+
+/**
+ * The read-surface answer for one object: the anchor, or the named reason there
+ * isn't one. `null`/a non-object means the caller had no live object to ask
+ * about, which is a DIFFERENT honest answer from "the library built it".
+ */
+export function creationSiteAnchor(o: unknown): CreationSiteAnchor {
+  if (o === null || o === undefined) return { anchored: false, reason: NO_OBJECT_REASON };
+  const site = creationSiteOf(o);
+  if (!site) return { anchored: false, reason: UNANCHORED_REASON };
+  return { anchored: true, kind: 'source', ...site, display: formatCreationSite(site) };
+}
+
+/**
+ * Publish {@link recordCreationSite} on `globalThis` for the served prelude.
+ * Idempotent. Returns an uninstall — see the module header for who owns this.
+ */
+export function installCreationSiteRecorder(): () => void {
+  const g = globalThis as unknown as Record<string, unknown>;
+  const existing = g[CREATION_SITE_GLOBAL];
+  if (typeof existing === 'function') return () => {};
+  const recorder: Recorder = recordCreationSite;
+  g[CREATION_SITE_GLOBAL] = recorder;
+  return () => {
+    if (g[CREATION_SITE_GLOBAL] === recorder) delete g[CREATION_SITE_GLOBAL];
+  };
+}

package/src/delegate-harness-registry.ts

@@ -0,0 +1,143 @@
+/**
+ * WHICH CODING HARNESSES CAN BE DELEGATED TO — the eleventh registry in the
+ * family of `workspace-document-restore.ts` (a kind owns its persisted state),
+ * `document-open-registry.ts` (a kind owns how it opens), `chrome-slot-registry
+ * .ts` (the host owns the place, a package owns what sits there),
+ * `content-entry-source-registry.ts` (the host owns the Content scope, a
+ * package owns why a component is content) and the seven since. Here: the host
+ * owns the DELEGATE FORM — the task text, the isolation choice, the branch
+ * name, the button, the notice line and `delegateEditorTask` itself — and a
+ * package owns WHICH AGENTS EXIST.
+ *
+ * WHY IT EXISTS. `components/WorktreeSwitcher.tsx`'s Delegate form was the
+ * single edge holding `api/agents.ts` and its three wire modules in the
+ * editor's eager import closure (WORK.md §The open-source launch, the four
+ * that remained of the harness bucket): it called `getHarnessChatSnapshot()`
+ * to list which harnesses are installed, and it named two of them by hand
+ * (`claude`, `codex`) for its container isolation. A base library for making
+ * IDEs should not know the name of a coding agent.
+ *
+ * THE DOOR THE RECORD NAMED WAS A BIGGER ONE, AND THE CODE DID NOT WANT IT.
+ * Unit 21 specified "a chrome slot that can hand its filler a dismiss/refresh
+ * callback", i.e. the whole form becoming `@vgai/agents`' surface. Measured
+ * against the form: of its ~120 lines, everything but the harness `<Select>`
+ * is the worktree board's own vocabulary — the branch slug, the three
+ * isolations, the copy about sibling checkouts and bounded containers, and
+ * `delegateEditorTask` (`api/worktrees.ts`, a `keep`-bucket module whose wire
+ * already takes a `harness` string). Moving it would have put the board's
+ * delegation UI inside the agents package AND changed `ChromeSlotFiller` —
+ * whose whole claim is that a slot is a PLACE, rendered `<filler.Content />`
+ * with no props — for every existing filler. What the host actually cannot
+ * answer is one question, so one question is what it asks.
+ *
+ * ASKED PER ISOLATION, because the answer differs and only the source knows
+ * how: a worktree or in-place delegation needs a harness that is INSTALLED and
+ * can start, while a bounded container authenticates the harness inside its
+ * own temporary home, so "installed here" is not the question. The host passes
+ * the isolation and reads a list; which of its harnesses satisfies which is
+ * the package's to decide.
+ *
+ * NOTHING REGISTERED IS A REAL ANSWER. With no source, the picker says "No
+ * harness ready" and Delegate stays disabled — the same honest emptiness a
+ * document kind with no registered opener gives. That is not a regression
+ * risk for any shipped build: `WorktreeSwitcher` renders only in `server`
+ * editor mode, and every dev session loads `@vgai/agents` through
+ * `SESSION_PACKAGES` (`server/project-tools.ts`), while a build with no
+ * session has no board at all.
+ */
+
+/** How a delegated task is isolated from the caller's checkout — the board's
+ *  own vocabulary, passed to a source as the question's context. */
+export type DelegateIsolation = 'worktree' | 'current' | 'container';
+
+export interface DelegateHarness {
+  /** The value `delegateEditorTask({ harness })` takes. */
+  readonly id: string;
+  /** What the picker shows. */
+  readonly label: string;
+}
+
+export interface DelegateHarnessSource {
+  /** Which module registered it. Re-registering the same owner REPLACES, so
+   *  an HMR re-evaluation leaves one source, not two. */
+  readonly owner: string;
+  /** Ascending; ties keep registration order. */
+  readonly order?: number;
+  /** Asking is a fetch, so this is async; the form re-asks whenever the
+   *  isolation or the registry version changes. */
+  readonly harnesses: (isolation: DelegateIsolation) => Promise<readonly DelegateHarness[]>;
+}
+
+const _sources: DelegateHarnessSource[] = [];
+const listeners = new Set<() => void>();
+let version = 0;
+
+function publish(): void {
+  version++;
+  for (const listener of listeners) listener();
+}
+
+/** Install a source. Returns the teardown. */
+export function registerDelegateHarnessSource(source: DelegateHarnessSource): () => void {
+  const stale = _sources.findIndex((item) => item.owner === source.owner);
+  if (stale >= 0) _sources.splice(stale, 1);
+  _sources.push(source);
+  _sources.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+  publish();
+  return () => {
+    const at = _sources.indexOf(source);
+    if (at < 0) return;
+    _sources.splice(at, 1);
+    publish();
+  };
+}
+
+/**
+ * THE HOST'S ONE QUESTION. Every source's answer, in registration order, with
+ * the first claim on an id winning — two packages offering the same harness is
+ * one harness, and the one that registered earlier named it.
+ *
+ * A source that throws is skipped rather than taking the form down with it:
+ * the picker degrades to the harnesses that did answer, which is the same
+ * shape as no source at all.
+ */
+export async function delegateHarnesses(
+  isolation: DelegateIsolation,
+): Promise<readonly DelegateHarness[]> {
+  const seen = new Set<string>();
+  const out: DelegateHarness[] = [];
+  for (const source of _sources) {
+    let answered: readonly DelegateHarness[];
+    try {
+      answered = await source.harnesses(isolation);
+    } catch {
+      continue;
+    }
+    for (const harness of answered) {
+      if (seen.has(harness.id)) continue;
+      seen.add(harness.id);
+      out.push(harness);
+    }
+  }
+  return out;
+}
+
+/** The form's `useSyncExternalStore` subscription: a source arriving with a
+ *  contribution pass re-asks the question. */
+export function subscribeDelegateHarnessSources(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function delegateHarnessRegistryVersion(): number {
+  return version;
+}
+
+/** Test-only reset (mirrors the restore, open, chrome-slot and content-entry
+ *  registries'). */
+export function __resetDelegateHarnessSourcesForTest(): void {
+  _sources.length = 0;
+  publish();
+}

package/src/document-context-registry.ts

@@ -0,0 +1,177 @@
+import {
+  object3DDocumentSession,
+  object3DDocumentStageAnnounced,
+} from './authoring/object3d-document-session-registry';
+import { DOCUMENT_REGISTRATION_TIMEOUT_MS, waitUntil } from './wait-until';
+
+/**
+ * THE OPEN DOCUMENT'S OWN CONTEXT, published for the REPL door.
+ *
+ * A tool document (`workspace.document`) may hand the host ONE object — the
+ * live session it edits through — and `editor.document.run(ctx => …)`
+ * (`vgai eval`) runs a wire-carried step against it, in Edit mode, without
+ * play. This is the "explore in the REPL, commit as source" half of the
+ * parity program's one spine (docs/BLENDER-PARITY.md §Execution model): the
+ * mesh document publishes its `MeshEditSession`, whose `ctx` is the
+ * bpy-shaped edit context, so an agent phrases a modeling step the way the
+ * corpus does — context + selection + op — and reads the result back.
+ *
+ * Keyed by workspace document id; the door resolves the ACTIVE document and
+ * refuses by name when it published nothing (a data sheet, a story). A
+ * document re-publishes whenever its session object changes (a reload swaps
+ * it); publishing returns the unpublish.
+ *
+ * ITS SIBLING FACT, and the reason they share a module: whether a contributed
+ * document has MOUNTED AT ALL. Both are things a contribution's own React root
+ * tells the host about itself, and both exist because `ToolHost.tsx` renders
+ * that contribution into a SEPARATE root (`createEditorRoot(...).render(...)`),
+ * which React schedules — so nothing in the host's own commit can say whether
+ * the contribution has rendered yet. Every door that must not read a document
+ * "before it decided what it is" waits on one of these two.
+ */
+
+const _contexts = new Map<string, unknown>();
+const _listeners = new Set<() => void>();
+const _mounted = new Set<string>();
+const _mountListeners = new Set<() => void>();
+
+let _version = 0;
+
+function _notifyContexts(): void {
+  _version += 1;
+  for (const listener of [..._listeners]) listener();
+}
+
+export function publishDocumentContext(documentId: string, context: unknown): () => void {
+  _contexts.set(documentId, context);
+  _notifyContexts();
+  return () => {
+    if (_contexts.get(documentId) === context) _contexts.delete(documentId);
+  };
+}
+
+/**
+ * THE PUBLISHED CONTEXT HAS MOVED — said by the package that DRIVES the
+ * document, not by the one that published it.
+ *
+ * The context object is a live handle, so a package can change what it answers
+ * without ever republishing: `@volter/editor-blender` reads the engine through its RNA
+ * door and the answer decides which Properties TABS exist for the selected
+ * datablock (an armature has a Bone tab, a cube does not). Nothing in the
+ * host's own stores moves when that answer arrives, so before this existed the
+ * inspector had no reason to re-compose and the rail stayed at whatever the
+ * first render could see.
+ *
+ * `use-active-inspection.ts` subscribes to {@link documentContextVersion}, so
+ * this makes the whole inspection re-derive — matches included.
+ */
+export function notifyDocumentContextChanged(documentId: string): void {
+  if (!_contexts.has(documentId)) return;
+  _notifyContexts();
+}
+
+export function subscribeDocumentContexts(listener: () => void): () => void {
+  _listeners.add(listener);
+  return () => {
+    _listeners.delete(listener);
+  };
+}
+
+export function documentContextVersion(): number {
+  return _version;
+}
+
+export function documentContextFor(documentId: string): unknown {
+  return _contexts.get(documentId);
+}
+
+/** Opening a document activates its tab before an async model import can
+ * publish its context. The REPL waits for that publication; it never executes
+ * against a placeholder or mistakes a loading document for an unsupported one. */
+export function waitForDocumentContext(documentId: string, timeoutMs = 10_000): Promise<unknown> {
+  const current = documentContextFor(documentId);
+  if (current !== undefined) return Promise.resolve(current);
+  return new Promise((resolve) => {
+    const onPublish = () => {
+      const context = documentContextFor(documentId);
+      if (context === undefined) return;
+      clearTimeout(timeout);
+      _listeners.delete(onPublish);
+      resolve(context);
+    };
+    const timeout = setTimeout(() => {
+      _listeners.delete(onPublish);
+      resolve(undefined);
+    }, timeoutMs);
+    _listeners.add(onPublish);
+  });
+}
+
+export function __resetDocumentContextsForTest(): void {
+  _contexts.clear();
+  _mounted.clear();
+}
+
+/**
+ * A CONTRIBUTED DOCUMENT'S REACT ROOT HAS COMMITTED — published by the host's
+ * own wrapper INSIDE that root (`ToolHost.tsx`), so every child effect has run
+ * by the time it fires. That ordering is the whole point: it is what lets an
+ * opener's `ready` read an absent stage announcement as "this document has no
+ * stage" rather than "the stage has not rendered yet"
+ * (`authoring/object3d-document-session-registry.ts`).
+ */
+export function markContributedDocumentMounted(documentId: string): () => void {
+  _mounted.add(documentId);
+  for (const listener of [..._mountListeners]) listener();
+  return () => {
+    _mounted.delete(documentId);
+  };
+}
+
+/** Resolves once this document's contribution has committed, `false` if the
+ *  bounded window elapses first — the same shape and reason as
+ *  {@link waitForDocumentContext} above. */
+export function waitForContributedDocumentMount(
+  documentId: string,
+  timeoutMs = 10_000,
+): Promise<boolean> {
+  if (_mounted.has(documentId)) return Promise.resolve(true);
+  return new Promise((resolve) => {
+    const onMount = () => {
+      if (!_mounted.has(documentId)) return;
+      clearTimeout(timeout);
+      _mountListeners.delete(onMount);
+      resolve(true);
+    };
+    const timeout = setTimeout(() => {
+      _mountListeners.delete(onMount);
+      resolve(false);
+    }, timeoutMs);
+    _mountListeners.add(onMount);
+  });
+}
+
+/**
+ * THE SHARED HALF OF EVERY OPENER'S `ready` (`document-open-registry.ts`): a
+ * document whose stage announced itself
+ * (`authoring/object3d-document-session-registry.ts`) is not ready to be
+ * driven until that stage has registered its session, and one that announced
+ * nothing is ready already. Each caller has already waited for its own MOUNT
+ * to settle — the asset family for its Inspector, a contributed document for
+ * the React root above — which is what makes an absent announcement mean
+ * "this document has no stage" rather than "the stage has not rendered yet".
+ *
+ * The refusal sentence is the one `editor-view-presentation.ts` used to throw,
+ * moved to the kinds' own side unchanged.
+ */
+export async function awaitAnnouncedObject3DDocumentSession(documentId: string): Promise<void> {
+  if (!object3DDocumentStageAnnounced(documentId)) return;
+  if (
+    await waitUntil(
+      () => object3DDocumentSession(documentId) !== null,
+      DOCUMENT_REGISTRATION_TIMEOUT_MS,
+    )
+  )
+    return;
+  throw new Error(`The requested Object3D view did not mount for document: ${documentId}`);
+}

package/src/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();
+}