@volter/sdk 0.0.0-stage → 0.5.204

package/src/kit/action-registry.ts

@@ -0,0 +1,317 @@
+import { PROJECT_ASSET_COMMANDS } from './asset-workflow/project-asset-commands';
+import { getActiveAuthoring } from '@volter/sdk/kit/authoring/active-adapter';
+import { NO_AUTHORING_ID } from '@volter/sdk/kit/authoring/no-authoring-adapter';
+import {
+  activeHierarchyRows,
+  selectAllAuthoringNodes,
+  selectAuthoringNodes,
+} from '@volter/sdk/kit/authoring/shell-document-ops';
+import { openAccountDocument } from './components/account-documents';
+import {
+  copySelection,
+  cutSelection,
+  deleteSelection,
+  duplicateSelection,
+  pasteSelection,
+} from './editor-hotkeys';
+import { invokeKeyAction } from '@volter/sdk/kit/key-actions';
+import type { ShellStore } from '@volter/sdk/kit/shell-store';
+import type { HistoryCommandSnapshot, HistoryCommands } from '@volter/sdk/kit/history/history-commands';
+import { editorKeymaps, setEditorKeymapPreference, shortcutFor } from '@volter/sdk/kit/keymap-presets';
+import { openUndoHistory } from './workspace-aux-commands';
+import { CORE_WORKSPACE_UTILITIES } from '@volter/sdk/kit/workspace-core-utilities';
+import {
+  showWorkspaceStaticPanel,
+  showWorkspaceUtility,
+  toggleWorkspaceFocus,
+} from '@volter/sdk/kit/workspace-host-commands';
+import {
+  cycleEditorWorkspace,
+  editorWorkspaces,
+  setEditorWorkspace,
+  workspaceApplies,
+} from './workspace-presets';
+import { applyWorkspaceStyle, workspaceStyles } from './workspace-style';
+import { toggleConsoleUtility } from '@volter/sdk/kit/workspace-utility-commands';
+
+export interface EditorAction {
+  id: string;
+  label: string;
+  category: 'action' | 'entity' | 'asset';
+  /**
+   * The printed hint, resolved from the ACTIVE keymap (`keymap-presets.ts`)
+   * rather than spelled here — so the palette tells the truth under `blender`
+   * as well as `volter`. Explicitly `| undefined` because a keymap may leave an
+   * action deliberately unbound, and printing a stale key would be worse than
+   * printing none.
+   */
+  shortcut?: string | undefined;
+  execute: () => void | Promise<void>;
+  /** The application menu this action is an item of (a package's `workspace.menu`), and its
+   *  label THERE — the palette's label names the menu, the menu's does not. */
+  menu?: { readonly id: string; readonly label: string } | undefined;
+}
+
+/** Build the static list of editor command actions. */
+export function buildStaticActions(
+  store: ShellStore,
+  history: HistoryCommands,
+  historySnapshot?: HistoryCommandSnapshot,
+): EditorAction[] {
+  const isMac = navigator.platform.includes('Mac');
+  const mod = isMac ? '\u2318' : 'Ctrl+';
+  const authoring = getActiveAuthoring(store);
+  const clipboardIds = [...store.selectedEntityIds];
+  const selectedId = clipboardIds[0];
+  const pasteParentId = selectedId
+    ? (authoring.hierarchy.node(selectedId)?.parentId ?? null)
+    : null;
+  const canCopy =
+    clipboardIds.length > 0 &&
+    !!authoring.structure?.copy &&
+    (authoring.structure.canCopy?.(clipboardIds) ?? true);
+  const canCut = canCopy && !!authoring.structure?.cut;
+  const canPaste =
+    !!authoring.structure?.paste && (authoring.structure.canPaste?.(pasteParentId) ?? true);
+  const clipboardActions: EditorAction[] = [
+    ...(canCut
+      ? [
+          {
+            id: 'editor.cut',
+            label: 'Cut',
+            category: 'action' as const,
+            shortcut: shortcutFor('edit.cut'),
+            execute: () => cutSelection(store),
+          },
+        ]
+      : []),
+    ...(canCopy
+      ? [
+          {
+            id: 'editor.copy',
+            label: 'Copy',
+            category: 'action' as const,
+            shortcut: shortcutFor('edit.copy'),
+            execute: () => copySelection(store),
+          },
+        ]
+      : []),
+    ...(canPaste
+      ? [
+          {
+            id: 'editor.paste',
+            label: 'Paste',
+            category: 'action' as const,
+            shortcut: shortcutFor('edit.paste'),
+            execute: () => pasteSelection(store),
+          },
+        ]
+      : []),
+  ];
+  return [
+    {
+      id: 'account.open',
+      label: 'Account and Provider Connections',
+      category: 'action',
+      execute: () => {
+        openAccountDocument();
+      },
+    },
+    {
+      id: 'editor.undo',
+      label: historySnapshot?.undoLabel ? `Undo ${historySnapshot.undoLabel}` : 'Undo',
+      category: 'action',
+      shortcut: shortcutFor('edit.undo'),
+      // H2: shell actions use the project-scoped command service. Its temporary
+      // compatibility bridge preserves chronology with producers not yet migrated.
+      execute: async () => {
+        await history.undo();
+      },
+    },
+    {
+      id: 'editor.redo',
+      label: historySnapshot?.redoLabel ? `Redo ${historySnapshot.redoLabel}` : 'Redo',
+      category: 'action',
+      shortcut: shortcutFor('edit.redo'),
+      execute: async () => {
+        await history.redo();
+      },
+    },
+    ...clipboardActions,
+    {
+      id: 'editor.duplicate',
+      label: 'Duplicate',
+      category: 'action',
+      shortcut: shortcutFor('edit.duplicate'),
+      execute: () => duplicateSelection(store),
+    },
+    {
+      id: 'editor.delete',
+      label: 'Delete Selected',
+      category: 'action',
+      shortcut: shortcutFor('edit.delete'),
+      execute: () => deleteSelection(store),
+    },
+    {
+      id: 'editor.select-all',
+      label: 'Select All',
+      category: 'action',
+      shortcut: shortcutFor('edit.selectAll'),
+      execute: () => selectAllAuthoringNodes(store),
+    },
+    {
+      id: 'editor.deselect',
+      label: 'Deselect All',
+      category: 'action',
+      shortcut: shortcutFor('edit.deselectAll') ?? shortcutFor('edit.exitScopeOrDeselect'),
+      execute: () => selectAuthoringNodes(store, []),
+    },
+    {
+      id: 'toggle.console',
+      label: 'Toggle Console',
+      category: 'action',
+      shortcut: shortcutFor('view.toggleConsole'),
+      execute: () => {
+        toggleConsoleUtility();
+      },
+    },
+    {
+      id: 'view.focusMode',
+      label: 'Toggle Focus Mode',
+      category: 'action',
+      shortcut: shortcutFor('view.focusMode'),
+      execute: () => {
+        toggleWorkspaceFocus();
+      },
+    },
+    // NAMED WORKSPACES (ARCHITECTURE-CORE §Editor chrome): one action per
+    // registered workspace, plus the cycle pair. The ruling calls for these to
+    // be palette-ready, which is exactly what this registry is — a seventh
+    // workspace would appear here on its own.
+    ...editorWorkspaces().map(
+      (choice): EditorAction => ({
+        id: `workspace.${choice.id}`,
+        label: `Workspace: ${choice.title}`,
+        category: 'action',
+        execute: () => {
+          // A workspace the project's declared shape does not meet is not a
+          // destination (ARCHITECTURE-CORE §Roots).
+          if (workspaceApplies(choice.id)) setEditorWorkspace(choice.id);
+        },
+      }),
+    ),
+    {
+      id: 'workspace.cycleNext',
+      label: 'Next Workspace',
+      category: 'action',
+      // Blender's own workspace cycle keys, and free in this registry.
+      shortcut: shortcutFor('workspace.cycleNext'),
+      execute: () => {
+        cycleEditorWorkspace(1);
+      },
+    },
+    {
+      id: 'workspace.cyclePrevious',
+      label: 'Previous Workspace',
+      category: 'action',
+      shortcut: shortcutFor('workspace.cyclePrevious'),
+      execute: () => {
+        cycleEditorWorkspace(-1);
+      },
+    },
+    // KEYMAPS (ARCHITECTURE-CORE §Editor chrome: "Keymaps are orthogonal to
+    // workspaces"). One action per registered keymap, exactly as the workspace
+    // axis above — orthogonal to it, and the switch is live.
+    ...editorKeymaps().map(
+      (choice): EditorAction => ({
+        id: `keymap.${choice.id}`,
+        label: `Keymap: ${choice.title}`,
+        category: 'action',
+        execute: () => {
+          setEditorKeymapPreference(choice.id);
+        },
+      }),
+    ),
+    // Workspace style bundles (Glass-UI spike, Unit 3): one action per named
+    // palette+material+icons+regions bundle — a third bundle appears here
+    // automatically.
+    ...workspaceStyles().map(
+      (choice): EditorAction => ({
+        id: `view.workspaceStyle.${choice.id}`,
+        label: `Workspace Style: ${choice.title}`,
+        category: 'action',
+        execute: () => {
+          applyWorkspaceStyle(choice.id);
+        },
+      }),
+    ),
+    {
+      id: 'view.undoHistory',
+      label: 'Undo History',
+      category: 'action',
+      execute: () => {
+        // Undo History is an on-demand panel, not a permanent tab. The host
+        // defaults it beside Inspector but preserves a user's later move.
+        // §8 naming: 'Undo History', not 'History'.
+        openUndoHistory();
+      },
+    },
+    {
+      id: 'view.lightExplorer',
+      label: 'Open Light Explorer',
+      category: 'action',
+      execute: () => showWorkspaceUtility(CORE_WORKSPACE_UTILITIES.lightExplorer.id),
+    },
+    ...Object.values(PROJECT_ASSET_COMMANDS)
+      .filter((command) => command.id !== PROJECT_ASSET_COMMANDS.open.id)
+      .map((command) => ({
+        id: command.id,
+        label: `${command.id
+          .replace('project-asset.', '')
+          .split('-')
+          .map((part) => part[0]?.toUpperCase() + part.slice(1))
+          .join(' ')} Project Asset`,
+        category: 'asset' as const,
+        ...(command.shortcut ? { shortcut: command.shortcut.replace('Mod', mod) } : {}),
+        execute: () => {
+          window.dispatchEvent(
+            new CustomEvent('editor:project-asset-command', { detail: { id: command.id } }),
+          );
+        },
+      })),
+    {
+      // Content and Library are permanent peer navigators; individual
+      // results open as center asset documents.
+      id: 'view.asset-library',
+      label: 'Asset Library',
+      category: 'action' as const,
+      execute: () => {
+        showWorkspaceStaticPanel('asset-library');
+      },
+    },
+  ];
+}
+
+/** Build dynamic node actions from the active authoring adapter's hierarchy.
+ *
+ *  THE NO-AUTHORING FLOOR IS A MESSAGE, NOT AN ENTITY. `makeNoAuthoringAdapter`
+ *  publishes one `role: 'boundary'` row so the panels can say "no authoring
+ *  surface" honestly; mapping it like a node put a command literally called
+ *  **Volter Entity: No authoring adapter** in the palette, whose whole effect is
+ *  to select and focus nothing (measured under the frame on a Model document,
+ *  U8 walk 3, 2026-09-20). */
+export function buildEntityActions(store: ShellStore): EditorAction[] {
+  return activeHierarchyRows(store)
+    .filter((row) => row.id !== NO_AUTHORING_ID)
+    .map((row) => ({
+      id: `entity:${row.id}`,
+      label: row.name,
+      category: 'entity' as const,
+      // Going to an entity is selecting it and framing the selection on the
+      // focused stage, which answers `viewport.frameSelection` if it has a camera.
+      execute: () => {
+        selectAuthoringNodes(store, [row.id]);
+        invokeKeyAction('viewport.frameSelection');
+      },
+    }));
+}

package/src/kit/active-product.ts

@@ -0,0 +1,76 @@
+/**
+ * WHICH PRODUCT THIS PAGE IS — set once, by the product's own entry module,
+ * before anything mounts.
+ *
+ * A product is the last mile: thin code that stitches packages onto the kit and
+ * holds only purpose-specific choices (ARCHITECTURE-CORE §The target shape).
+ * `@volter/game-editor` and `@volter/cyclotron` each have ONE source entry which
+ * IS that product's frame entry, and the first thing it does is call
+ * `product({ … })` (`frame/product.ts`), which lands here.
+ *
+ * THE KIT KNOWS NO PRODUCT BY NAME (rule 1). This module holds a record it was
+ * HANDED and never a table of products; the two readers below ask it for a
+ * default and fall back to their own when there is none, so the host still
+ * stands up with no product at all (a Storybook page, a measurement of one
+ * surface). What it is NOT is a switch on which product is open (rule 4): a
+ * product is the running program, and this is that program telling the kit what
+ * it composed, not the kit choosing between compositions.
+ *
+ * Its two readers, both defaults and both outranked by anything the person or
+ * the project said:
+ *   - `workspace-style.ts` resolves {@link ActiveProduct.look} to a style
+ *     bundle and makes its palette/material/icons the editor's DEFAULT
+ *     appearance, beneath `~/.volter/settings.json`, the project's own
+ *     `.volter/settings.json` and the adapter's declaration;
+ *   - `workspace-presets.ts` uses {@link ActiveProduct.workspace} as the
+ *     workspace a project opens in when this checkout has none recorded and the
+ *     adapter declares none.
+ */
+
+/** What a product's entry composed, as the kit reads it. */
+export interface ActiveProduct {
+  /** The product's id — `game-editor`, `cyclotron`. Reported by the session
+   *  beside the workbench (the editor's `status` command), never read as a branch. */
+  readonly id: string;
+  /** The packages it mounts, by name, in composition order. The contributions
+   *  themselves are already in the bundle (`tool-loader.ts`); this is the list
+   *  for anything that needs to SAY what is installed. */
+  readonly packages: readonly string[];
+  /** The style bundle id this product wears by default (`workspace-style.ts`). */
+  readonly look: string;
+  /** The workspace it opens in by default (`workspace-presets.ts`). */
+  readonly workspace: string;
+  /** Use the workbench application menu instead of a second product menu. */
+  readonly nativeMenus?: boolean | undefined;
+  /** The product's own logo URL; the kit shows its own when absent. */
+  readonly logo?: string | undefined;
+}
+
+let _product: ActiveProduct | null = null;
+const listeners = new Set<() => void>();
+
+/** The composed product, or `null` on a surface no product stood up. */
+export function activeProduct(): ActiveProduct | null {
+  return _product;
+}
+
+/**
+ * Record the composition. Called once, by the product's entry, at module scope
+ * — so every default below is in force before the first module that reads one.
+ * A second call with a different id is a page with two products in it, which is
+ * the one thing this record cannot be honest about.
+ */
+export function setActiveProduct(next: ActiveProduct): void {
+  if (_product !== null && _product.id !== next.id)
+    throw new Error(
+      `Two products in one page: "${_product.id}" is already composed and "${next.id}" asked to be. ` +
+        'A product is the running program; one page runs one.',
+    );
+  _product = next;
+  for (const listener of listeners) listener();
+}
+
+export function subscribeActiveProduct(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}

package/src/kit/active-project.ts

@@ -0,0 +1,155 @@
+/**
+ * THE ACTIVE PROJECT — the one store every surface reads the open project
+ * from, and nothing else. Split out of `project-manager.ts` so a host that
+ * only needs to know WHICH project is open (a bounded host, the
+ * contribution loader) does not carry the server boot path — the launcher,
+ * the server-project probe, the recent-projects list — and the server-SDK
+ * barrel those import. `project-manager.ts` re-exports everything here, so
+ * its importers are unchanged; a surface below the shell imports THIS file.
+ */
+
+import type { LearnMetadata } from '@volter/project/manifest/schema';
+import type { HierarchyProjection } from '@volter/sdk/kit/hierarchy-projection';
+
+/** One `run[]` declaration as the manifest carries it: the envelope plus the
+ *  kind's own fields (spelled here, not imported, so a bounded host's closure
+ *  stays free of the engine's kind registry). */
+export interface ConfigurationDeclaration {
+  readonly id: string;
+  readonly kind: string;
+  readonly [param: string]: unknown;
+}
+
+export interface ProjectConfig {
+  /** Project-file schema version. Kept distinct from game and engine versions. */
+  manifestVersion: 2;
+  name: string;
+  /** The authored game's own release version. */
+  version: string;
+  /** Exact engine identity the project is pinned to. */
+  engine: { version: string };
+  /** Editor-only organization. It never changes which runtime roots mount. */
+  authoring?: { hierarchy?: HierarchyProjection | undefined } | undefined;
+  resolution?: { width: number; height: number } | undefined;
+  appId?: string | undefined;
+  /**
+   * Multiplayer server config from the manifest (`server.room` — the Colyseus
+   * room this game registers), if declared. Carried here so edit-mode
+   * networking can answer "does this project declare a server" from the
+   * already-parsed manifest, NOT by re-reading `volter.project.json` through the
+   * asset-scoped `StorageBackend.read` (which resolves under `public/` and so
+   * returns the SPA fallback for a root manifest — the bug that left the
+   * player-count picker hidden on the local dev server).
+   */
+  /** The manifest's run configurations (ARCHITECTURE-CORE §The project model). */
+  configurations?: readonly ConfigurationDeclaration[] | undefined;
+  /**
+   * Derived from the manifest roots. `false` means the editor must not
+   * fabricate its native Three scene document for this project. Optional
+   * only for legacy callers/tests; current project readers always provide it.
+   */
+  hasThreeRoot?: boolean | undefined;
+  /** How many roots the manifest declares — what MOUNTS. Zero is a real
+   *  shape (ARCHITECTURE-CORE §Roots): the chrome that only means something
+   *  for a running world (transport, instances, play state, analytics) is
+   *  derived from this, never from a project kind. */
+  rootCount?: number | undefined;
+  /**
+   * The project's default scene path, or `null` when the manifest's first
+   * world declares no scene (e.g. an `entry`-only world — §7.1-12). Always
+   * present when derived from the manifest (`readProjectView`, server-side).
+   * Consumers must NOT default a missing/null value to a guessed path: a
+   * guess resolves to a file nobody declared, and writing to it silently
+   * creates a placeholder the project never asked for.
+   */
+  defaultScene?: string | null | undefined;
+  /**
+   * FT-5 learner-facing metadata from the manifest's `learn` block. Carried
+   * for BUNDLED EXAMPLES opened read-only in the hosted editor so the shell
+   * can offer the example's Learn-site lesson ("This example has a lesson →",
+   * G6); absent everywhere else.
+   */
+  learn?: LearnMetadata | undefined;
+}
+
+export interface ActiveProject {
+  /** Absolute path to the project root (as passed via URL param / env). */
+  rootPath: string;
+  /** Parsed volter.project.json project configuration plus derived editor fields. */
+  config: ProjectConfig;
+}
+
+let _activeProject: ActiveProject | null = null;
+const _listeners = new Set<() => void>();
+
+function _notify(): void {
+  for (const fn of _listeners) fn();
+}
+
+/**
+ * Set or clear the active project directly (project screen and bounded hosts).
+ *
+ * This is also where a project SESSION ends: switching to a different project
+ * without a page reload is a real path (the project screen's five open sites),
+ * and the editor's module-level session singletons do not reset themselves on
+ * it. Anything that must not outlive the previous project registers with
+ * {@link onProjectSessionEnd} — see `project-session-reset.ts`, the one
+ * subscriber, for the list.
+ */
+export function setActiveProject(project: ActiveProject | null): void {
+  const previous = _activeProject;
+  _activeProject = project;
+  // Only a genuine CHANGE of project ends a session: re-setting the same
+  // project (a config refresh after a manifest save) is not a switch, and
+  // resetting session state under it would drop a live mount for nothing.
+  if (previous && previous.rootPath !== project?.rootPath) {
+    for (const fn of _sessionEndListeners) fn();
+  }
+  _notify();
+}
+
+/**
+ * The boot/open path's own assignment: install the project just resolved
+ * WITHOUT the session-end notice — a session ends on a SWITCH
+ * ({@link setActiveProject}); resolving a project at boot or re-reading its
+ * manifest is not one. Same notify as the setter.
+ */
+export function assignActiveProject(project: ActiveProject): ActiveProject {
+  _activeProject = project;
+  _notify();
+  return project;
+}
+
+/** Get the currently open project, or null if none. */
+export function getCurrentProject(): ActiveProject | null {
+  return _activeProject;
+}
+
+/** Subscribe to project changes. Returns unsubscribe function. */
+export function onProjectChange(fn: () => void): () => void {
+  _listeners.add(fn);
+  return () => _listeners.delete(fn);
+}
+
+const _sessionEndListeners = new Set<() => void>();
+
+/**
+ * Subscribe to the END of a project session — fired by {@link setActiveProject}
+ * when a DIFFERENT project (or none) takes over.
+ *
+ * The sibling of {@link onProjectChange}, and deliberately not the same hook:
+ * `onProjectChange` means "re-derive against whatever project is open now" and
+ * fires for every notify, while this one means "the previous project's live
+ * state is over, drop it". Nothing but `project-session-reset.ts` subscribes;
+ * add a reset there rather than a second subscriber here.
+ */
+export function onProjectSessionEnd(fn: () => void): () => void {
+  _sessionEndListeners.add(fn);
+  return () => _sessionEndListeners.delete(fn);
+}
+
+/** The identity every per-project cache keys on: the open project's folder,
+ *  and a fixed unscoped key when no project is active. */
+export function activeProjectKey(): string {
+  return getCurrentProject()?.rootPath ?? '__unscoped__';
+}

package/src/kit/adapter-editor-config.ts

@@ -0,0 +1,25 @@
+import type { AdapterEditorConfiguration } from '@volter/project/adapter/adapter-module';
+import { activeProjectKey } from '@volter/sdk/kit/active-project';
+
+// Published by the adapter loader; consumers need no dependency on its module graph.
+let configuration: AdapterEditorConfiguration = {};
+let owner: string | null = null;
+const EMPTY: AdapterEditorConfiguration = Object.freeze({});
+const listeners = new Set<() => void>();
+
+export function adapterEditorConfiguration(): AdapterEditorConfiguration {
+  return owner !== null && owner === activeProjectKey() ? configuration : EMPTY;
+}
+
+export function setAdapterEditorConfiguration(value: AdapterEditorConfiguration = {}): void {
+  owner = activeProjectKey();
+  configuration = value;
+  for (const listener of listeners) listener();
+}
+
+export function subscribeAdapterEditorConfiguration(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}

package/src/kit/adapter-module.ts

@@ -0,0 +1,7 @@
+/** The game's adapter module lives beside `volter.project.json`, by contract.
+ *
+ *  IN A MODULE OF ITS OWN, with no imports, because the CLI reads it: the launcher's adapter check
+ *  (`editor-core/server/project-adapter-required.ts`) imported it from `ui-source/adapter-region-includes`,
+ *  which imports `typescript`, and the CLI bundle then carried TypeScript and died on start
+ *  ("Dynamic require of "fs" is not supported"). */
+export const ADAPTER_MODULE_FILENAME = 'editor/volter.adapter.ts';

package/src/kit/adapter-observation.ts

@@ -0,0 +1,49 @@
+/**
+ * THE LOADED ADAPTER'S OBSERVATION DECLARATIONS, held host-side with their
+ * closures intact.
+ *
+ * Pushed rather than pulled, for exactly the reason `presentation-surface.ts`
+ * is: the reader is an ingest MOUNT, and having the mount import
+ * `project-adapter.ts` would drag the whole loader graph (the finder namespace,
+ * the manifest fetchers, the story registry) into the mount's module closure.
+ * `project-adapter.ts` stays the one place the table is decided; this is the
+ * one place the part that cannot travel over the wire is kept.
+ *
+ * "Cannot travel" is the whole reason this module exists separately from the
+ * `/__editor/state` facet. A declaration's `answer` is a CLOSURE evaluated
+ * against the mounted game, so the facet publishes only the statically readable
+ * half — id, kind, and whether an answer is bound — while the closures stay
+ * here, in the host realm, reachable by the mount that has a game to evaluate
+ * them against.
+ */
+
+import type {
+  AdapterInputBinding,
+  ObservationDeclaration,
+} from '@volter/project/adapter/adapter-module';
+
+let _declarations: readonly ObservationDeclaration[] = [];
+let _input: AdapterInputBinding | null = null;
+
+/** Written by `project-adapter.ts` on every load — including with `[]`, so a
+ *  project switch cannot leave the previous game's closures reachable. */
+export function setAdapterObservations(declarations: readonly ObservationDeclaration[]): void {
+  _declarations = declarations;
+}
+
+/** What the loaded adapter declares. Empty before the first load, and for a
+ *  project whose adapter declares none — both are "nothing to project", which
+ *  is the only distinction a mount needs. */
+export function adapterObservations(): readonly ObservationDeclaration[] {
+  return _declarations;
+}
+
+/** The loaded adapter's app-owned input binding, or `null` when it declares none. */
+export function adapterInputBinding(): AdapterInputBinding | null {
+  return _input;
+}
+
+/** Written beside {@link setAdapterObservations} on every project load. */
+export function setAdapterInputBinding(binding: AdapterInputBinding | null): void {
+  _input = binding;
+}