@volter/editor-core 0.5.57

package/src/components/project-tool-documents.tsx

@@ -0,0 +1,410 @@
+import { Button, bg, border, danger, radius, TextArea, text } from '@volter/editor-sdk/widgets';
+import { useState, useSyncExternalStore } from 'react';
+import type { EditorAction } from '../action-registry';
+import { registerDocumentOpener } from '../document-open-registry';
+import type { ViewportTab } from '../editor-shell-store';
+import {
+  getProjectTools,
+  projectToolsVersion,
+  refreshProjectTools,
+  runProjectTool,
+  subscribeProjectTools,
+} from '../project-tools';
+import {
+  getDocumentToolContributions,
+  getGlobalToolContributions,
+  getToolContributionLoadFailures,
+  subscribeToolContributions,
+} from '../tool-loader';
+import { waitUntil } from '../wait-until';
+import {
+  activeWorkspaceDocumentId,
+  openWorkspaceDocument,
+  type WorkspaceDocumentContentProps,
+} from '../workspace-document-registry';
+import { registerWorkspaceDocumentRestorer } from '../workspace-document-restore';
+import { openToolDocument } from './tool-documents';
+import { defaultValueForSchema, ToolSchemaForm } from './tool-schema-form';
+
+export const PROJECT_TOOLS_DOCUMENT_ID = 'project-tools';
+export const PROJECT_TOOL_DOCUMENT_PREFIX = 'project-tool:';
+
+export interface ProjectToolDocumentStore {
+  setActiveViewportTab(tab: ViewportTab): void;
+}
+
+function projectToolDocumentId(name: string): string {
+  return `${PROJECT_TOOL_DOCUMENT_PREFIX}${name}`;
+}
+
+export function openProjectToolsDocument(store: ProjectToolDocumentStore): void {
+  openWorkspaceDocument({
+    id: PROJECT_TOOLS_DOCUMENT_ID,
+    title: 'Project Tools',
+    kind: 'project-tool',
+    workspaceRole: 'workspace-reference',
+    Content: ProjectToolDocumentContent,
+    closeable: true,
+    presentation: () => ({ kind: 'workspace', id: PROJECT_TOOLS_DOCUMENT_ID }),
+    // The catalog is always truthfully reopenable — it lists whatever the
+    // project declares now — so it persists with no state of its own.
+    persist: () => ({ catalog: true }),
+    onActivate: () => store.setActiveViewportTab('edit'),
+  });
+}
+
+export function openProjectToolDocument(
+  store: ProjectToolDocumentStore | null,
+  name: string,
+): boolean {
+  const tool = getProjectTools().tools.find((entry) => entry.name === name);
+  if (!tool) return false;
+  const contributions = getDocumentToolContributions().filter((item) => item.tool?.name === name);
+  if (contributions.length === 1) return openToolDocument(store, contributions[0]!.id);
+  openWorkspaceDocument({
+    id: projectToolDocumentId(name),
+    title: tool.summary || tool.name,
+    kind: 'project-tool',
+    workspaceRole: 'workspace-reference',
+    provenance: { sourcePath: tool.sourcePath, origin: tool.name },
+    Content: ProjectToolDocumentContent,
+    closeable: true,
+    presentation: () => ({ kind: 'project-tool', name }),
+    persist: () => ({ name }),
+    ...(store ? { onActivate: () => store.setActiveViewportTab('edit') } : {}),
+  });
+  return true;
+}
+
+/**
+ * THE TWO ADDRESSES THIS MODULE ANSWERS (`document-open-registry.ts`), each
+ * the other half of a `presentation()` above: the CATALOG is a workspace
+ * document (`{ kind: 'workspace', id: 'project-tools' }`), one named tool is
+ * its own kind (`{ kind: 'project-tool', name }`). Registered at module load,
+ * the shape `packages/game/src/story-documents/three-story-documents.tsx:239`
+ * uses; the presenter addresses both without importing this file.
+ */
+registerDocumentOpener<{ readonly id: string }>({
+  id: 'workspace',
+  owner: 'project-tool-documents',
+  // Every other workspace id belongs to the host's own workspace-document
+  // registry, or to the account document's opener.
+  open: (store, request) => {
+    if (request.id !== PROJECT_TOOLS_DOCUMENT_ID) return null;
+    openProjectToolsDocument(store);
+    return PROJECT_TOOLS_DOCUMENT_ID;
+  },
+});
+
+registerDocumentOpener<{ readonly name: string }>({
+  id: 'project-tool',
+  owner: 'project-tool-documents',
+  // `openProjectToolDocument` answers a boolean because it opens one of TWO
+  // documents — a single matching contribution's own tool document, or the
+  // generic runner — and the active id is which one it chose. That is exactly
+  // what the presenter read here before this was an address.
+  open: (store, request) =>
+    openProjectToolDocument(store, request.name) ? activeWorkspaceDocumentId() : null,
+  // The catalog is discovered asynchronously, so a durable address routinely
+  // names a tool before the project's tools have been read. Settling is the
+  // same refresh this kind's RESTORER prepares with (below), then the wait the
+  // presenter used to run as a poll around `open` itself.
+  settle: async (request) => {
+    await refreshProjectTools().catch(() => {});
+    if (await waitUntil(() => getProjectTools().tools.some((t) => t.name === request.name))) return;
+    throw new Error(`Project tool is not registered: ${request.name}`);
+  },
+});
+
+/** Reopen a persisted project-tool document: the catalog, or one registered
+ *  callable's generic runner. The runner is self-verifying against the
+ *  discovered catalog (`false` for a tool that is gone), which this kind's
+ *  `prepare` has settled first. */
+registerWorkspaceDocumentRestorer({
+  kind: 'project-tool',
+  owner: 'project-tool-documents',
+  prepare: () =>
+    refreshProjectTools().then(
+      () => {},
+      () => {},
+    ),
+  restore: ({ state, store }) => {
+    const record = state as { catalog?: unknown; name?: unknown } | null | undefined;
+    if (record?.catalog === true) {
+      openProjectToolsDocument(store);
+      return true;
+    }
+    return typeof record?.name === 'string' && openProjectToolDocument(store, record.name);
+  },
+});
+
+export function buildProjectToolActions(store: ProjectToolDocumentStore): EditorAction[] {
+  return [
+    {
+      id: 'project-tools:open',
+      label: 'Open Project Tools',
+      category: 'action',
+      execute: () => openProjectToolsDocument(store),
+    },
+    ...getProjectTools().tools.map((tool) => ({
+      id: `project-tool:${tool.name}`,
+      label: `Run: ${tool.summary || tool.name}`,
+      category: 'action' as const,
+      execute: () => void openProjectToolDocument(store, tool.name),
+    })),
+  ];
+}
+
+function JsonBlock({ value }: { value: unknown }) {
+  return <pre style={jsonStyle}>{JSON.stringify(value, null, 2)}</pre>;
+}
+
+export function ProjectToolDocumentContent({ documentId }: WorkspaceDocumentContentProps) {
+  useSyncExternalStore(subscribeProjectTools, projectToolsVersion);
+  useSyncExternalStore(subscribeToolContributions, getGlobalToolContributions);
+  const snapshot = getProjectTools();
+  const toolName = documentId.startsWith(PROJECT_TOOL_DOCUMENT_PREFIX)
+    ? documentId.slice(PROJECT_TOOL_DOCUMENT_PREFIX.length)
+    : null;
+  const tool = toolName ? snapshot.tools.find((entry) => entry.name === toolName) : null;
+  if (!toolName) {
+    return (
+      <div style={rootStyle} data-testid="project-tools-catalog">
+        <h2 style={headingStyle}>Project Tools</h2>
+        <p style={{ ...mutedStyle, margin: '0 0 18px', maxWidth: 720, lineHeight: 1.5 }}>
+          Explicitly registered in <code>package.json#vgai.tools</code>. Each tool is an ordinary
+          project function; a registration may pair it with optional editor contributions.
+        </p>
+        <div style={{ display: 'grid', gap: 8 }}>
+          {snapshot.tools.map((entry) => (
+            <Button
+              key={entry.name}
+              variant="ghost"
+              className="vgai-project-tool-card"
+              onClick={() => openProjectToolDocument(null, entry.name)}
+              data-testid={`project-command-card:${entry.name}`}
+            >
+              <span style={cardTitleRowStyle}>
+                <strong style={{ color: text[1], fontWeight: 600 }}>{entry.summary}</strong>
+                <span style={openLabelStyle}>Open</span>
+              </span>
+              <code style={{ color: text[2], fontSize: 'var(--vgai-font-sm)' }}>{entry.name}</code>
+              <span style={cardMetaRowStyle}>
+                <span>
+                  {entry.host} · {entry.permission.risk} · {entry.sourcePath}
+                </span>
+              </span>
+            </Button>
+          ))}
+        </div>
+        {snapshot.tools.length === 0 && snapshot.loadErrors.length === 0 && (
+          <div style={mutedStyle}>No project tools registered.</div>
+        )}
+        {snapshot.loadErrors.map((error) => (
+          <div key={`${error.sourcePath}:${error.message}`} style={errorStyle}>
+            {error.sourcePath}: {error.message}
+          </div>
+        ))}
+        {/* The server's `loadErrors` cover the CALLABLES it imported in node;
+            contributions are only scanned there and imported in the tab, so a
+            contribution that throws on import can appear nowhere else on this
+            page — which is how a standing document went invisibly absent. */}
+        {getToolContributionLoadFailures().map((failure) => (
+          <div key={`${failure.entryPath}:${failure.error}`} style={errorStyle}>
+            {failure.entryPath}: {failure.error}
+          </div>
+        ))}
+      </div>
+    );
+  }
+
+  if (!tool) {
+    return <div style={rootStyle}>This tool is no longer available.</div>;
+  }
+
+  return <ProjectToolRunner key={tool.name} tool={tool} />;
+}
+
+function ProjectToolRunner({
+  tool,
+}: {
+  tool: ReturnType<typeof getProjectTools>['tools'][number];
+}) {
+  const presentations = getDocumentToolContributions().filter(
+    (item) => item.tool?.name === tool.name,
+  );
+  const initial = defaultValueForSchema(tool.inputSchema);
+  const [input, setInput] = useState<Record<string, unknown>>(
+    initial && typeof initial === 'object' && !Array.isArray(initial)
+      ? (initial as Record<string, unknown>)
+      : {},
+  );
+  const [rawText, setRawText] = useState(() => JSON.stringify(input, null, 2));
+  const [result, setResult] = useState<unknown>(null);
+  const [running, setRunning] = useState(false);
+  const [inputError, setInputError] = useState<string | null>(null);
+
+  const runnable = tool.host === 'node';
+  const execute = async () => {
+    const confirm =
+      tool.permission.risk === 'read' ||
+      window.confirm(`${tool.permission.summary}\n\nRun ${tool.name}?`);
+    if (!confirm) return;
+    setRunning(true);
+    try {
+      setResult(await runProjectTool(tool.name, input, { confirm: true }));
+    } catch (error) {
+      setResult({ ok: false, error: { code: 'REQUEST_FAILED', message: String(error) } });
+    } finally {
+      setRunning(false);
+    }
+  };
+
+  return (
+    <div style={rootStyle} data-testid={`project-tool:${tool.name}`}>
+      <h2 style={headingStyle}>{tool.summary}</h2>
+      <code style={{ color: text[2] }}>{tool.name}</code>
+      <p style={{ color: text[2] }}>{tool.description}</p>
+      <div style={mutedStyle}>
+        {tool.host} · {tool.permission.risk} · {tool.sourcePath}
+      </div>
+      {presentations.length > 0 && (
+        <section style={{ marginTop: 18, maxWidth: 760 }}>
+          <h3 style={{ margin: '0 0 8px', fontSize: 13 }}>Presentations</h3>
+          <div style={{ display: 'grid', gap: 8 }}>
+            {presentations.map((presentation) => (
+              <Button
+                key={presentation.id}
+                variant="ghost"
+                className="vgai-project-tool-card"
+                onClick={() => openToolDocument(null, presentation.id)}
+              >
+                <span style={cardTitleRowStyle}>
+                  <strong style={{ color: text[1], fontWeight: 600 }}>{presentation.title}</strong>
+                  <span style={openLabelStyle}>Open</span>
+                </span>
+              </Button>
+            ))}
+          </div>
+        </section>
+      )}
+      {!runnable && (
+        <div style={errorStyle}>
+          This runner supports Node-hosted tools. Import the underlying function directly in browser
+          or runtime code.
+        </div>
+      )}
+      <details open={presentations.length === 0} style={{ marginTop: 18, maxWidth: 760 }}>
+        <summary style={{ cursor: 'pointer', color: text[2], fontSize: 12 }}>
+          {presentations.length > 0 ? 'Advanced · invoke native schema' : 'Input'}
+        </summary>
+        <section style={{ marginTop: 12 }}>
+          <ToolSchemaForm
+            schema={tool.inputSchema}
+            value={input}
+            onChange={(next) => {
+              setInput(next);
+              setRawText(JSON.stringify(next, null, 2));
+              setInputError(null);
+            }}
+          />
+        </section>
+        {inputError && <div style={errorStyle}>{inputError}</div>}
+        <Button
+          variant="primary"
+          disabled={!runnable || running || inputError !== null}
+          aria-busy={running}
+          onClick={() => void execute()}
+          style={{ marginTop: 16 }}
+        >
+          {running ? 'Running…' : 'Run tool'}
+        </Button>
+        <details style={{ marginTop: 16 }}>
+          <summary style={labelStyle}>Advanced JSON</summary>
+          <TextArea
+            id={`tool-input:${tool.name}`}
+            value={rawText}
+            onChange={(event) => {
+              const nextText = event.target.value;
+              setRawText(nextText);
+              try {
+                const parsed = JSON.parse(nextText) as unknown;
+                if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                  throw new Error('Input must be a JSON object.');
+                }
+                setInput(parsed as Record<string, unknown>);
+                setInputError(null);
+              } catch (error) {
+                setInputError(error instanceof Error ? error.message : String(error));
+              }
+            }}
+            rows={10}
+            data-variant="code"
+            style={textareaStyle}
+          />
+          <details>
+            <summary style={labelStyle}>Input schema</summary>
+            <JsonBlock value={tool.inputSchema} />
+          </details>
+        </details>
+      </details>
+      {result !== null && (
+        <section>
+          <div style={labelStyle}>Result</div>
+          <JsonBlock value={result} />
+        </section>
+      )}
+    </div>
+  );
+}
+
+const rootStyle: React.CSSProperties = {
+  width: '100%',
+  maxWidth: 960,
+  margin: '0 auto',
+  padding: 24,
+  boxSizing: 'border-box',
+  overflow: 'auto',
+  pointerEvents: 'auto',
+  color: text[1],
+  fontSize: 'var(--vgai-font-base)',
+};
+const headingStyle: React.CSSProperties = { margin: '0 0 6px', fontSize: 20 };
+const mutedStyle: React.CSSProperties = { color: text[2], fontSize: 'var(--vgai-font-sm)' };
+const labelStyle: React.CSSProperties = { display: 'block', margin: '14px 0 6px', color: text[1] };
+const cardTitleRowStyle: React.CSSProperties = {
+  display: 'flex',
+  width: '100%',
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  gap: 12,
+};
+const openLabelStyle: React.CSSProperties = {
+  color: text[2],
+  fontSize: 'var(--vgai-font-sm)',
+  fontWeight: 500,
+};
+const cardMetaRowStyle: React.CSSProperties = {
+  display: 'flex',
+  width: '100%',
+  minWidth: 0,
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  gap: 12,
+  color: text[2],
+  fontSize: 'var(--vgai-font-sm)',
+};
+const errorStyle: React.CSSProperties = { marginTop: 10, color: danger, whiteSpace: 'pre-wrap' };
+const textareaStyle: React.CSSProperties = {
+  width: '100%',
+  boxSizing: 'border-box',
+  resize: 'vertical',
+};
+const jsonStyle: React.CSSProperties = {
+  overflow: 'auto',
+  padding: 10,
+  background: bg.inset,
+  border: `1px solid ${border[1]}`,
+  borderRadius: radius.sm,
+  color: text[2],
+};

package/src/components/scene-documents.tsx

@@ -0,0 +1,223 @@
+/** Scene-table navigation delegates rendering to installed document owners. */
+import { openRegisteredDocument } from '../document-open-registry';
+import type { ViewportTab } from '../editor-shell-store';
+import { projectAdapterFacet, type ResolvedDocumentTable, subscribeProjectAdapter } from '../project-adapter';
+import { planSceneDocument, sceneTabRow } from '../scene-document-plan';
+import { openAvailableWorkspaceDocument } from '../workspace-available-documents';
+import { activateWorkspaceDocument, setWorkspaceDocumentTitle } from '../workspace-document-registry';
+import { rootDocumentId } from '../world-document-routing';
+import { kindDocumentId, openKindDocument } from './kind-documents';
+
+export interface SceneDocumentStore { setActiveViewportTab(tab: ViewportTab): void; }
+export function reconcileSceneDocuments(_store: SceneDocumentStore, table: ResolvedDocumentTable | null): void {
+  if (!table) return;
+  for (const row of sceneTabRow(table)) {
+    if (row.plan.kind !== 'root-document') continue;
+    const id = rootDocumentId(row.plan.regionId);
+    if (id) setWorkspaceDocumentTitle(id, row.plan.title);
+  }
+}
+export function startSceneDocuments(store: SceneDocumentStore): () => void {
+  const run = () => reconcileSceneDocuments(store, projectAdapterFacet()?.scenes ?? null);
+  run();
+  return subscribeProjectAdapter(run);
+}
+
+export interface SceneOpenRefusal {
+  readonly ok: false;
+  readonly code:
+    | 'SCENE_TABLE_UNAVAILABLE'
+    | 'SCENE_NOT_FOUND'
+    | 'SCENE_NOT_OPENABLE'
+    /** Reached ONLY through the running game's own navigation, and no game is
+     *  running here. Distinct from `SCENE_NOT_OPENABLE` because it is not a
+     *  dead end: starting the game makes it openable (`scene-live-open.ts`). */
+    | 'SCENE_NAVIGATION_NOT_RUNNING'
+    | 'SCENE_DOCUMENT_NOT_MOUNTED';
+  readonly error: string;
+  readonly known?: readonly string[];
+}
+
+export type SceneOpenResult =
+  | { readonly ok: true; readonly documentId: string; readonly title: string }
+  | SceneOpenRefusal;
+
+/**
+ * OPEN one piece of the adapter's scene table by id — the Edit half of the
+ * table's `open` verb, and the same verb for a scene, a prefab, or a story
+ * state (ARCHITECTURE-CORE §Editor: "any other piece … opens as a sibling
+ * document through the same verb").
+ *
+ * Every refusal is CODED because the classes are graded differently: a table
+ * that has not loaded is a session fact, an unknown id is a caller error, an
+ * unopenable entry is the GAME's own declaration (quoted verbatim), and a
+ * document the host has not mounted is a host gap. Prose alone cannot separate
+ * them.
+ */
+/**
+ * How long {@link openSceneTableEntryWhenListed} will wait for the project
+ * adapter's table before refusing.
+ *
+ * MEASURED, not chosen: three cold `vgai edit` sessions on a
+ * `--template models` probe, opening `model:src/models/cube.blend` in a poll
+ * loop from the moment the tab connected — **6025 ms, 6831 ms, 6474 ms**, and
+ * in all three the first refusal was `SCENE_TABLE_UNAVAILABLE`, i.e. the
+ * adapter had not loaded at all. So for ~6.4 s after the editor reports
+ * "Editor ready" and the tab is present, the ONE general door for putting a
+ * document on screen answered "no". Every walk in the stage-transport unit
+ * had to wrap `editor.open` in a retry loop to get past it, and the frame
+ * hits the same window from the other side (WORK.md NEXT item 2).
+ *
+ * 15 s is that worst case with headroom for a slower box. It is a BOUND and
+ * not a fix for slowness: if opening a document ever legitimately needs
+ * longer than this, the thing to change is why, not this number.
+ */
+const SCENE_TABLE_WAIT_MS = 15_000;
+
+/**
+ * {@link openSceneTableEntry}, but WAITING for the adapter's table first.
+ *
+ * WHY THE WAIT CANNOT STOP AT THE FIRST RESOLUTION: a table resolves MORE
+ * THAN ONCE — a contributed finder (the mesh capability's models finder)
+ * registers after the first resolution and the table is resolved again with
+ * its entries — so "the adapter answered and your id is not in it" is not yet
+ * "your id does not exist". `kind-documents.tsx`'s `whenDocumentEntry` learned
+ * this on 2026-09-05 and has waited correctly ever since; this door never did,
+ * and that asymmetry IS the defect: two doors onto one table, one patient and
+ * one not.
+ *
+ * BOTH REFUSALS SURVIVE UNCHANGED. On timeout this returns exactly what the
+ * synchronous door would have returned at that moment — `SCENE_TABLE_UNAVAILABLE`
+ * if the adapter never loaded, `SCENE_NOT_FOUND` with the known ids if it did.
+ * The cost of the patience is paid by a genuinely unknown id, which now takes
+ * the full bound to be told so; that is the right side to lose on, because the
+ * alternative is the 2026-09-05 bug — refusing a document that was about to
+ * exist.
+ */
+export async function openSceneTableEntryWhenListed(
+  store: SceneDocumentStore,
+  id: string,
+): Promise<SceneOpenResult> {
+  const listed = (): boolean =>
+    projectAdapterFacet()?.scenes.entries.some((candidate) => candidate.id === id) ?? false;
+  if (!listed()) {
+    await new Promise<void>((resolve) => {
+      let done = false;
+      const finish = (): void => {
+        if (done) return;
+        done = true;
+        clearTimeout(timer);
+        stop();
+        resolve();
+      };
+      const timer = setTimeout(finish, SCENE_TABLE_WAIT_MS);
+      const stop = subscribeProjectAdapter(() => {
+        if (listed()) finish();
+      });
+      // The table can resolve between the check above and the subscribe.
+      if (listed()) finish();
+    });
+  }
+  return openSceneTableEntry(store, id);
+}
+
+export function openSceneTableEntry(store: SceneDocumentStore, id: string): SceneOpenResult {
+  const facet = projectAdapterFacet();
+  if (!facet) {
+    return {
+      ok: false,
+      code: 'SCENE_TABLE_UNAVAILABLE',
+      error: 'open: the project adapter has not loaded yet, so there is no scene table to open.',
+    };
+  }
+  const entry = facet.scenes.entries.find((candidate) => candidate.id === id);
+  if (!entry) {
+    const known = facet.scenes.entries.map((candidate) => candidate.id);
+    return {
+      ok: false,
+      code: 'SCENE_NOT_FOUND',
+      error: `open: "${id}" is not in the adapter's scene table. Known ids: ${
+        known.length > 0 ? known.join(', ') : '(the table is empty)'
+      }.`,
+      known,
+    };
+  }
+  // A KIND document (a model, a page — any entry a project contribution
+  // authors, `kind-documents.tsx`) is opened the way a Content double-click
+  // opens it. Before this, `open` fell through to the scene planner, which
+  // asked the entry for a region and refused it by name — so an agent had no
+  // door to put the model it was writing on screen (2026-09-06).
+  if (
+    entry.kind !== 'scene' &&
+    entry.kind !== 'prefab' &&
+    openKindDocument(store, entry, { activate: true })
+  ) {
+    return { ok: true, documentId: kindDocumentId(entry.id), title: entry.label };
+  }
+  const plan = planSceneDocument(entry);
+  switch (plan.kind) {
+    case 'no-document':
+      // A LIVE-REACHED scene is not a dead end — it is a scene this session
+      // cannot reach because nothing is running. The verb tries the live half
+      // FIRST (`command-listener.ts`), so arriving here means there was no
+      // game. ANY `liveReach` earns this code: the planner sets the field only
+      // for the reaches the live half actually OPENS (`scene-document-plan.ts`
+      // states which), so "present" and "start the game and ask again" are
+      // the same statement.
+      if (plan.liveReach !== undefined) {
+        return {
+          ok: false,
+          code: 'SCENE_NAVIGATION_NOT_RUNNING',
+          error: `open: ${plan.reason} No game is running in this session.`,
+        };
+      }
+      return {
+        ok: false,
+        code: 'SCENE_NOT_OPENABLE',
+        // The adapter's own sentence, unaltered — see `scene-document-plan.ts`.
+        error: `open: "${id}" has no Edit document — ${plan.reason}`,
+      };
+    case 'root-document': {
+      const documentId = rootDocumentId(plan.regionId);
+      if (!documentId) {
+        return {
+          ok: false,
+          code: 'SCENE_DOCUMENT_NOT_MOUNTED',
+          error: `open: "${id}" is region "${plan.regionId}"'s own document, and no document is mounted for that region in this session.`,
+        };
+      }
+      // Reopen the registered root document if its tab was closed.
+      openAvailableWorkspaceDocument(documentId) || activateWorkspaceDocument(documentId);
+      return { ok: true, documentId, title: plan.title };
+    }
+    case 'isolation-document': {
+      const documentId = openRegisteredDocument('scene', store, { entry, activate: true });
+      return documentId
+        ? { ok: true, documentId, title: plan.title }
+        : { ok: false, code: 'SCENE_NOT_OPENABLE', error: `No installed scene editor can open "${id}".` };
+    }
+    case 'story-document': {
+      // The composed id is the whole address; resolving it, and saying WHICH
+      // way it failed, is the story kind's own job — it reports the specific
+      // reason (an id no composed story answers to, or a module whose medium
+      // is undeclared) to the session console, and this verb refuses with the
+      // one code the caller can act on.
+      const documentId = openRegisteredDocument('story', store, {
+        storyId: plan.storyId,
+        title: plan.title,
+      });
+      if (documentId === null) {
+        return {
+          ok: false,
+          code: 'SCENE_DOCUMENT_NOT_MOUNTED',
+          error:
+            `open: "${id}" is reached by story "${plan.storyId}", and nothing in this editor ` +
+            "opened it — either this project's story registry does not hold that id, or its " +
+            'module declares no medium (declare it via `vgai.adapter.ts` regionIncludes or a ' +
+            'manifest root entry). The session console names which.',
+        };
+      }
+      return { ok: true, documentId, title: plan.title };
+    }
+  }
+}

package/src/components/stage-keyboard.tsx

@@ -0,0 +1,37 @@
+/**
+ * A STAGE'S OWN KEYBOARD ACTIONS — the transform modes, the view presets,
+ * Frame, pivot, snap and the vertex-snap hold, bound for the stage whose
+ * document is ACTIVE.
+ *
+ * They belong to the STAGE, and until 2026-09-19 they were mounted from
+ * `stage-overlay-set.tsx`, which a stage only reaches when it has the shell
+ * above it (`StageHost.tsx`'s `shellStore && !chromeless`). A document
+ * contributed by a PACKAGE mounts outside `EditorProvider`, so the Model
+ * document reached NONE of them: measured live in the Code-OSS frame on a
+ * models project, the editor's action table held 29 entries — the shell set
+ * alone — and the stage's nine (`transform.combined/translate/rotate/scale`,
+ * `viewport.toggleSnap/frameSelection/cyclePivot/snapToFloor`, the four view
+ * presets) were absent, so G/R/S on the Model stage answered nothing at all.
+ * The overlay set is an OVERLAY condition (a bounded host must not pay for
+ * the collaboration client it reaches); which keys a stage answers is not,
+ * and the two were one line by accident.
+ *
+ * The ONE registry still means ONE holder (`hotkeys.ts`'s scope table, and
+ * `key-actions.ts`'s action table under the frame): the active
+ * document's stage, which is exactly the condition below.
+ *
+ * Lazily imported by `StageHost.tsx` so a bounded host neither loads nor pays
+ * for `editor-hotkeys.ts`'s closure — the same boundary, and the same reason,
+ * as `StageOverlays.tsx`.
+ */
+import { useEffect } from 'react';
+import { registerEditorViewportHotkeys } from '../editor-hotkeys';
+import type { StageHandle } from './stage-overlay-set';
+
+export function StageKeyboardBinding({ stage }: { readonly stage: StageHandle }): null {
+  useEffect(
+    () => registerEditorViewportHotkeys(stage.store, stage.viewport, stage.canvas),
+    [stage.store, stage.viewport, stage.canvas],
+  );
+  return null;
+}