@volter/sdk 0.0.0-stage → 0.5.204

package/src/kit/command-listener.ts

@@ -0,0 +1,2182 @@
+import { captureSizeFromCommand } from '@volter/sdk/kit/capture-size';
+import { getProjectStoryModules } from '@volter/sdk/kit/stories/story-registry';
+import {
+  applyViewPreset,
+  setViewPresentation,
+  studioPresets,
+  viewPresentation,
+  viewPresets,
+  viewPresentationBinding,
+  boundViewPresentations,
+  viewDrawReport,
+  type PresentationLayer,
+} from '@volter/sdk/kit/viewport-presentation';
+import { environmentImages } from '@volter/sdk/kit/environment-images';
+import { documentViewport } from '@volter/sdk/kit/document-viewports';
+import { inspectionNodeMedia } from '@volter/sdk/kit/inspection-node-media';
+import { isGameplayExportActive } from './gameplay-export-state';
+
+/**
+ * Command listener — receives commands from the editor server via SSE
+ * and dispatches them to the ShellStore and play-mode functions.
+ *
+ * The server broadcasts `editor-command` events sent by the SDK/CLI.
+ * This module translates them into store method calls.
+ */
+
+import type {
+  DocumentProbeStep,
+  EditorView,
+  InspectedHierarchy,
+  InspectedInspection,
+  InspectedWriteDestination,
+  HelperVisibility as SdkHelperVisibility,
+} from '@volter/sdk';
+import { type AssetKind, setSelectedAsset } from '@volter/sdk/kit/asset-selection';
+import { assetCapabilities, assetDocumentKind } from '@volter/sdk/kit/asset-capabilities';
+import { systemsForInstance } from '@volter/sdk/kit/authoring/active-systems';
+import { getMountFailureReports } from '@volter/sdk/kit/mount-failure-report';
+import {
+  activeDocumentAuthoring,
+  activeHierarchyRows,
+  activeSaveDestination,
+  activeSaveState,
+  activeSelectionCreationSite,
+  activeSelectionIds,
+  activeSelectionWriteAnchorKind,
+} from '@volter/sdk/kit/authoring/shell-document-ops';
+import { noteCommandDispatched } from './command-dispatch';
+import { contributedCommandDerivedRefresh } from '@volter/sdk/kit/command-registry';
+import { resolveContributedCommand } from './resolve-contributed-command';
+import {
+  isAssetDocumentId,
+  openAssetDocument,
+  waitForAssetDocumentInspector,
+} from '@volter/sdk/kit/components/asset-documents';
+import { openSceneTableEntryWhenListed } from './components/scene-documents';
+import { systemAdapterEpoch } from '@volter/sdk/kit/system-seam-evidence';
+import {
+  connectEvents,
+  reportCommandListener,
+  reportCommandReceived,
+  reportCommandResult,
+  reportEditorState,
+  reportPlayBootPhase,
+} from '@volter/sdk/kit/editor-api';
+import { captureEditorChrome } from './editor-chrome-capture';
+import type { ConsoleEntry } from '@volter/sdk/kit/editor-console';
+import { editorConsole } from '@volter/sdk/kit/editor-console';
+import { currentEditorView } from './editor-current-view';
+import { editorIsPlaying } from '@volter/sdk/kit/editor-session-mode';
+import type { HelperVisibility } from '@volter/sdk/kit/shell-store';
+import type { ShellStore } from '@volter/sdk/kit/shell-store';
+import { collectEditorStateFacets, reusableFacetKeys } from '@volter/sdk/kit/editor-state-facets';
+import {
+  hierarchyPanelSnapshot,
+  nextHierarchyPanelSnapshot,
+  serializeHierarchyPanel,
+} from './hierarchy-panel-view';
+import { announcePhotograph, withdrawPhotograph } from '@volter/sdk/kit/photograph-notice';
+import type { HistoryCommands } from '@volter/sdk/kit/history/history-commands';
+import {
+  anyLiveSessionMounted,
+  anyLiveSessionPlaying,
+  dispatchLiveCommand,
+  liveRunWindow,
+  liveScenes,
+  remountLiveSelection,
+  subscribeLiveSessions,
+} from '@volter/sdk/kit/live-session-registry';
+import { setPlayBootPhaseReporter } from '@volter/sdk/kit/play-boot-phase';
+import { projectAdapterFacet, subscribeProjectAdapter } from '@volter/sdk/kit/project-adapter';
+import { getProjectModuleSplitReports } from '@volter/sdk/kit/project-module-split';
+import { onSessionEndedChange, sessionEndedRefusal, sessionEndedState } from '@volter/sdk/kit/session-tombstone';
+import { prepareSessionClose } from './session-close';
+import { scheduleDeferredFullReport } from './state-report-deferral';
+import { rendererResourceCounts } from '@volter/sdk/kit/renderer-resource-counts';
+import {
+  subscribeViewportActivationTimings,
+  viewportActivationTimings,
+} from '@volter/sdk/kit/viewport-activation-timings';
+
+type AssertSameKeys<P, Q> = [keyof P] extends [keyof Q]
+  ? [keyof Q] extends [keyof P]
+    ? true
+    : false
+  : false;
+type RequireTrue<T extends true> = T;
+/**
+ * Compile-time drift guard (W3a N1) — its consumer is `tsc` itself. The SDK
+ * republishes `HelperVisibility` for control-API clients, and the
+ * `{ ...store.helperVisibility }` spread in `collectState` below typechecks
+ * happily even when the SDK mirror is MISSING keys (spreads skip excess
+ * property checks) — exactly how `joints`/`lod` drifted out of the SDK
+ * pre-W3a. This alias fails `npm run typecheck` the moment either side gains
+ * a key the other lacks.
+ */
+export type HelperVisibilityMirrorInSync = RequireTrue<
+  AssertSameKeys<HelperVisibility, SdkHelperVisibility>
+>;
+
+import {
+  type CommandResult,
+  isRelayCommandType,
+  type RelayCommandDerivedRefresh,
+  type RelayCommandType,
+  relayCommandDerivedRefresh,
+} from '@volter/sdk/session/command-table';
+import { editorMaterials, isEditorMaterialId } from '@volter/sdk/widgets';
+import {
+  copyAuthoringNodes,
+  createAuthoringNode,
+  cutAuthoringNodes,
+  duplicateAuthoringNode,
+  duplicateManyAuthoringNodes,
+  groupAuthoringNodes,
+  pasteAuthoringNodes,
+  removeAuthoringNode,
+  removeManyAuthoringNodes,
+  reorderAuthoringNode,
+  reparentAuthoringNode,
+  ungroupAuthoringNode,
+  unwrapAuthoringNode,
+  wrapAuthoringNode,
+} from '@volter/sdk/kit/authoring/consumer-actions';
+import { resolvePanelAuthoring } from '@volter/sdk/kit/authoring/panel-authoring';
+import { ontologyInvariantFacet } from './coverage/session-vitals';
+import { documentContextFor, waitForDocumentContext } from '@volter/sdk/kit/document-context-registry';
+import { executeCommand, openCommandPalette } from '@volter/sdk/kit/editor-commands';
+import { runDocumentProbe } from './editor-document-probe';
+import {
+  captureActiveEditorDocument,
+  presentEditorView,
+  revealStaticPanel,
+} from './editor-view-presentation';
+import { toolGameplaySessions } from '@volter/sdk/kit/gameplay-sessions';
+import {
+  InspectionRemovalUnavailableError,
+  inspectActiveSubject,
+  removeActiveInspectionField,
+  runActiveInspectionAction,
+  setActiveInspectionField,
+} from './inspection/active-subject';
+import { measuredReadinessWarning, readinessFacet } from '@volter/sdk/kit/readiness';
+import { deriveReportedPlayState } from './reported-play-state';
+import { openLiveSceneEntry } from './scene-live-open';
+import { editorMaterialSnapshot, setEditorMaterialPreference } from '@volter/sdk/kit/theme-preference';
+import { GAME_DOCUMENT_ID } from '@volter/sdk/kit/workspace-document-ids';
+import {
+  activateWorkspaceDocument,
+  activeWorkspaceDocumentId,
+  closeWorkspaceDocument,
+  openWorkspaceDocuments,
+} from '@volter/sdk/kit/workspace-document-registry';
+import { availableWorkspaceDocuments } from '@volter/sdk/kit/workspace-available-documents';
+import { activeWorkspaceUtility } from '@volter/sdk/kit/workspace-host-commands';
+import {
+  activeEditorWorkspace,
+  editorWorkspaceIds,
+  isEditorWorkspaceId,
+  setEditorWorkspace,
+  whenEditorWorkspaceApplied,
+} from '@volter/sdk/kit/workspace-presets';
+import {
+  activeWorkspaceStyleId,
+  applyWorkspaceStyle,
+  workspaceStyleDifferences,
+  workspaceStyles,
+} from '@volter/sdk/kit/workspace-style';
+import { documentContributionForKind } from '@volter/sdk/kit/tool-loader';
+import { toggleConsoleUtility } from '@volter/sdk/kit/workspace-utility-commands';
+import { worldAdoptionFacet } from './world-adoption';
+
+export interface EditorCommand {
+  type: string;
+  _requestId?: string;
+  [key: string]: unknown;
+}
+
+/** Browser-listener scheduling seam. The live relay holds presentation until
+ * its acknowledgement settles; direct callers fall back to the next task. */
+export interface CommandHandlingOptions {
+  deferPresentation?: ((present: () => void) => void) | undefined;
+  /** The session's own undo/redo queue — see {@link connectCommandListener}'s
+   *  `history` parameter for why the verbs go through it rather than through
+   *  `store.projectHistory` directly. */
+  history?: HistoryCommands | undefined;
+}
+
+const REPEATED_DEBUG_READS = new Set([
+  'state',
+  'stateAll',
+  'providers',
+  'commands',
+  'events',
+  'snapshot',
+]);
+
+/**
+ * The coverage proof a read-only debug call can add to the current adapter epoch.
+ *
+ * The first successful read still earns a full status derivation so coverage immediately reflects
+ * the operation. Repeating that same proof cannot change any derived facet: forcing another full
+ * 4,000-node hierarchy/coverage walk on every `waitSimTime` clock poll only stalls the game being
+ * measured. A provider name is part of a `state` proof because each declared provider is graded
+ * independently; adapter epoch keeps a remount's first read from reusing the retired mount's proof.
+ */
+function repeatedDebugReadProofKeys(command: EditorCommand): readonly string[] {
+  if (command['type'] !== 'bridge-call') return [];
+  const method = command['method'];
+  if (typeof method !== 'string' || !REPEATED_DEBUG_READS.has(method)) return [];
+  const instance = command['instance'] as string | undefined;
+  try {
+    const debug = systemsForInstance(instance).debug;
+    if (debug === undefined) return [];
+    const prefix = [systemAdapterEpoch(debug), instance ?? ''].join(':');
+    const key = (member: string, provider = '') => [prefix, member, provider].join(':');
+    if (method === 'snapshot') {
+      // `snapshot` dispatches these three reads in one batch; the next lightweight `state(time)`
+      // poll is therefore already the same current-epoch proof, not a second first use.
+      return [key('snapshot'), key('state', 'time'), key('stateAll'), key('events')];
+    }
+    const provider = method === 'state' ? String((command['callArgs'] as unknown[])?.[0]) : '';
+    return [key(method, provider)];
+  } catch {
+    // An unresolved instance is a real command failure. Keep the conservative full refresh so its
+    // status/error facets cannot be hidden behind the optimization for successful repeated reads.
+    return [];
+  }
+}
+
+interface CompletedCommandRefresh {
+  readonly derived: RelayCommandDerivedRefresh;
+  /** A successful, explicit game read or command may have changed the mounted
+   *  scene. During Play it earns one settled full report; ordinary input,
+   *  presence and repeated reads do not. */
+  readonly playFullReport: 'none' | 'explicit' | 'if-content-changed';
+}
+
+function completedCommandDerivedRefresh(
+  command: EditorCommand,
+  succeeded: boolean,
+  reportedProofs: Set<string>,
+): CompletedCommandRefresh {
+  const proofKeys = repeatedDebugReadProofKeys(command);
+  const repeated =
+    succeeded && proofKeys.length > 0 && proofKeys.every((key) => reportedProofs.has(key));
+  if (succeeded) {
+    for (const key of proofKeys) reportedProofs.add(key);
+  }
+  return {
+    derived: repeated
+      ? 'none'
+      : succeeded && proofKeys.length > 0
+        ? 'always'
+        : (contributedCommandDerivedRefresh(command['type']) ??
+          relayCommandDerivedRefresh(command['type'])),
+    playFullReport:
+      succeeded && !repeated && proofKeys.length > 0
+        ? 'explicit'
+        : succeeded && command['type'] === 'bridge-call' && command['method'] === 'invoke'
+          ? 'if-content-changed'
+          : 'none',
+  };
+}
+
+function playCommandOwesDerivedRefresh(
+  derivedRefresh: RelayCommandDerivedRefresh,
+  playFullReport: CompletedCommandRefresh['playFullReport'],
+  contentVersion: number,
+  lastFullContentVersion: number,
+): boolean {
+  if (derivedRefresh === 'none') return false;
+  return !(
+    derivedRefresh === 'if-content-changed' &&
+    playFullReport === 'none' &&
+    contentVersion === lastFullContentVersion
+  );
+}
+
+/**
+ * The refusal for `editor.select(id)` on an id no authoring surface owns, or
+ * `null` when the id resolves.
+ *
+ * The resolvers are the ones a selection's own CONSUMERS use, and both of them,
+ * for the reason `entity-object.ts` records: the active adapter's
+ * `hierarchy.node` (what the hierarchy panel and the inspector resolve against)
+ * and `entityObject3D` (what the gizmo and the selection brackets resolve
+ * against). Neither is a superset of the other, so checking only one would
+ * refuse ids the editor can genuinely select.
+ *
+ * It used to consult neither: `editor.select('Player')` wrote the string
+ * straight into the store's selection set, and the inspector then composed a
+ * SUBJECT for it (measured 2026-08-14 on the translated platformer: `id:
+ * "Player"`, a blank title and an `R3F source` kind label for an entity that has
+ * never existed; through a composite the same id reached `children[0]` and drew
+ * a full transform section reading all zeros). A selection is a claim about an
+ * entity, so an id nothing owns is refused by name here rather than fabricated
+ * downstream.
+ */
+function unresolvedSelectionRefusal(store: ShellStore, id: string): string | null {
+  // Resolve through the same document-scoped binding as Hierarchy and
+  // Inspector. Asset Lab documents publish their own adapter while the scene
+  // adapter remains globally active; asking the latter would reject the exact
+  // ids editor.hierarchy() just reported for the open asset/story.
+  const adapter = activeDocumentAuthoring(store);
+  if (adapter.hierarchy.node(id) !== null) return null;
+  // A live object the adapter's tree does not list (a runtime-built child) is
+  // still a subject when the medium that draws it answers for it.
+  if (inspectionNodeMedia(adapter, id) !== null) return null;
+  return (
+    `select: no entity with id "${id}" — neither the active authoring adapter's ` +
+    `hierarchy nor the live object index owns it, so there is nothing to select. ` +
+    `Read the ids that exist with editor.hierarchy() (the rows the panel is ` +
+    `rendering) or editor.status().entities.`
+  );
+}
+
+function applyControlSelection(
+  store: ShellStore,
+  ids: readonly string[],
+  options: CommandHandlingOptions | undefined,
+): void {
+  // Object3D documents own selection outside the scene store. This is also
+  // the route used by human hierarchy clicks and present-view, and is what
+  // lets semantic Asset Lab subjects (bones, physics bodies, joints) update
+  // their native highlight and Inspector state.
+  const ownSelection = documentViewport(activeWorkspaceDocumentId())?.selection;
+  if (ownSelection) {
+    ownSelection.apply(ids);
+    return;
+  }
+  const present = store.applySelectionBeforePresentation(ids);
+  if (options?.deferPresentation) options.deferPresentation(present);
+  else setTimeout(present, 0);
+}
+
+/** #145 — what the human's tab is actually showing right now: page
+ *  visibility + window focus. `null` outside a real browser (the relay's
+ *  node-side tests). The agent reads this to know whether the user is
+ *  LOOKING at the shared session before deciding how to narrate/verify;
+ *  `connectCommandListener` re-reports state on visibilitychange/focus/blur
+ *  so the server's `/__editor/state` snapshot stays current between
+ *  commands.
+ *
+ *  P21 — `reportedAt` is stamped HERE, at read time, and it is the field that
+ *  makes the other two honest. A CLI banner that says "the tab is hidden" is
+ *  reading a snapshot with no age on it; the owner was told that repeatedly
+ *  while looking straight at the foregrounded tab. With an age attached, the
+ *  reader can see the difference between a reading taken 40ms ago and one
+ *  taken 40 seconds ago, and no downstream surface has to invent a story to
+ *  fill the gap. */
+function collectPresence(): {
+  visibility: DocumentVisibilityState;
+  focused: boolean;
+  reportedAt: number;
+} | null {
+  if (typeof document === 'undefined') return null;
+  return {
+    visibility: document.visibilityState,
+    focused: document.hasFocus(),
+    reportedAt: Date.now(),
+  };
+}
+
+/**
+ * The facets `collectState` will REUSE from a previous snapshot when it is
+ * given one — the hierarchy walk and the capability GRADING families. They are
+ * the whole measured cost of a collect (see `state-report-deferral.ts`), and
+ * none of them can change without a mount or an edit, which the deferred full
+ * collect that always follows a reusing one picks up.
+ *
+ * Everything NOT named here is derived fresh on every single report, including
+ * the fields a reader needs the instant they change: play state, loop
+ * liveness, selection, active document, save state, presence, and every error
+ * and warning channel.
+ *
+ * THE HOST'S HALF ONLY. The four capability-GRADING families
+ * (`rootCoverage`, `systemCoverage`, `projectCoverage`, `authoringCoverage`)
+ * used to be listed here; they are `@volter/editor-game`'s now
+ * (`contributions/coverage.service.ts`) and declare their own reusable keys
+ * on `session.reportFacet`, which {@link reusableFacetKeys} reads back. Both
+ * blockers P5b measured against that move are gone: the facet registry
+ * carries reusable key names and hands the collect its `reuse` snapshot, and
+ * the vitals' union call is now a subscription to the SAME five-second sample
+ * (`coverage/session-vitals.ts`'s `onSessionSample`) rather than a second
+ * timer. What is left in the host is the question the grade was asked ABOUT —
+ * `authoring/mounted-root-subjects.ts` — which was never a grade.
+ */
+export const REUSABLE_DERIVED_FACETS = ['entities', 'entityCount', 'ontologyInvariants'] as const;
+
+/** The immediate interaction report is a PATCH over the last full state. The
+ * server already owns that full snapshot; resending these unchanged,
+ * tree-scale facets on every runtime structure/store notification turns a
+ * large Play world into megabytes of duplicate control traffic per frame.
+ *
+ * A contributed facet's own reusable keys are stripped the same way — read
+ * live, because a contribution pass adds and removes facets while the session
+ * runs. */
+function currentStatePatch(state: Record<string, unknown>): Record<string, unknown> {
+  const patch = { ...state };
+  for (const facet of REUSABLE_DERIVED_FACETS) delete patch[facet];
+  for (const facet of reusableFacetKeys()) delete patch[facet];
+  return { ...patch, _statePatch: true };
+}
+
+export function collectState(
+  store: ShellStore,
+  /**
+   * A previous full snapshot whose {@link REUSABLE_DERIVED_FACETS} this collect
+   * may copy instead of re-deriving, or `null`/omitted for a full collect.
+   *
+   * This is the interaction path's escape from a 76ms-to-1.3s synchronous
+   * derivation on every store notification. It is deliberately a caller's
+   * choice rather than an internal cache: only the caller knows whether it is
+   * on a user's critical path, and only the caller can promise the deferred
+   * full collect that makes the reused halves current again.
+   */
+  reuse: Record<string, unknown> | null = null,
+): Record<string, unknown> {
+  // S-1 (the SimCity ledger's false-alive ingest status): `store.playState` is
+  // editor UI STATE — ingest and module mode both write 'playing' into it
+  // without ever owning the `play-mode.ts` session the whole debug seam gates
+  // on, and ingest writes it BEFORE its mount is even attempted. Reporting it
+  // verbatim is how a session printed `playState: "playing"` in the same breath
+  // as `game.state()` refusing with "not in play mode", and how a mount that
+  // threw still reported itself alive. Derive it from what is actually running.
+  const mountFailures = getMountFailureReports();
+  const activeDocumentId = activeWorkspaceDocumentId();
+  const selectedIds = activeSelectionIds(store);
+  const gameplaySessions = toolGameplaySessions.getSnapshot();
+  // ONE walk, read by both `entityCount` and `entities` below. It used to be
+  // called once for each, and the walk is the expensive half of this whole
+  // function (23ms of a 76ms collect at 251 nodes, measured 2026-08-19) — two
+  // identical breadth-first traversals of the same tree in the same tick.
+  const hierarchyRows =
+    (reuse?.['entities'] as ReturnType<typeof activeHierarchyRows> | undefined) ??
+    activeHierarchyRows(store);
+  return {
+    playState: deriveReportedPlayState({
+      storePlayState: store.playState,
+      liveMounted: anyLiveSessionMounted(),
+      livePlaying: anyLiveSessionPlaying(),
+      mountFailures,
+    }),
+    // The lane's successful run window, independent of recording or document kind.
+    liveRunWindow: liveRunWindow(),
+    // Every world whose mount FAILED, with the error that killed it. `[]` on a
+    // healthy session; non-empty with `ingest: null` is what a dead game looks
+    // like from the control API, instead of a silent "playing". (`ingest` and
+    // `ingestCaptureWait` are the ingest lane's own facets, registered by it.)
+    mountFailures: mountFailures.map((r) => ({ ...r })),
+    // Every project story module that did not load or compose, with its error. A story that
+    // fails drops its prefab from the scene table with nothing else to show for it: `[]` on a
+    // healthy project; the console carries the module the failure was traced to.
+    storyFailures: getProjectStoryModules().flatMap((module_) =>
+      module_.ok ? [] : [{ modulePath: module_.modulePath, error: module_.error }],
+    ),
+    // PD-3 — every project module that was evaluated more than once during
+    // the current mount, i.e. every module whose module-level state the roots
+    // no longer share. `[]` on a healthy mount. A split does not fail the
+    // mount (both copies run), so this is the ONLY machine-readable signal
+    // that it happened at all.
+    moduleSplits: getProjectModuleSplitReports().map((s) => ({ path: s.path, urls: [...s.urls] })),
+    // The project's own ADAPTER, resolved (project-adapter.ts): which module
+    // supplied the binding table (`editor/volter.adapter.ts`, or the declared native
+    // default), the regions derived for it, and its scene table. `null` means
+    // NOBODY HAS LOOKED YET — deliberately distinct from a loaded adapter with
+    // an empty table, which is a real (and gradable) answer.
+    adapter: projectAdapterFacet(),
+    // DECLARED READINESS, per root (`readiness.ts`). One row per mounted root
+    // saying WHO answers "is this ready" — the host's own completed mount, the
+    // game's `window.volterGame.ready`, or a host-side measured wait. `[]` means
+    // nothing has mounted, which is not "nothing is ready".
+    readiness: readinessFacet().map((entry) => ({ ...entry })),
+    // The ONE sentence for a project whose readiness is entirely measured. It
+    // is the visibility half of the declared-vs-measured rule: an undeclared
+    // game still works, it just stops being silent about it. `null` when
+    // nothing is mounted or at least one root declared.
+    readinessWarning: measuredReadinessWarning(),
+    // WHICH WORLD the capture adopted for a self-booting root and how
+    // (`declared` from the game's contract, or the trap's measured
+    // first-non-host-render), plus every DISTINCT world that rendered
+    // afterwards. The adoption itself is unchanged; this is the reader that
+    // used to not exist for a permanent, silent choice.
+    worldAdoption: worldAdoptionFacet().map((entry) => ({ ...entry })),
+    presence: collectPresence(),
+    // Target-blaster friction #3 (#146 ledger): the play-verify loop's error
+    // channel — the same current-run-fenced uncaught-error list the relay
+    // snapshot carries (see collectPlayRunPageErrors), so the editor's `status` command answers
+    // "did anything go wrong since play started" without a second command.
+    // [] while stopped or when nothing threw.
+    pageErrors: collectPlayRunPageErrors(),
+    // The OTHER half of the same question, and the half that was missing: an
+    // otherwise-HEALTHY run that logged errors. `pageErrors` above is the
+    // 'runtime' slice (uncaught error/unhandledrejection) and is rendered only
+    // by the play-FAILED path, so a game that threw five `console.error`s
+    // during a fine-looking play run said nothing to any CLI reader — the same
+    // "already in the JSON and invisible in practice" failure PD-13 describes.
+    // Disjoint from `pageErrors` by construction (see collectConsoleErrors), so
+    // the two counts sum.
+    consoleErrors: collectConsoleErrors(),
+    // The SESSION-lifetime half — everything the two play-fenced facets above
+    // do not claim, which before `installEditorConsoleCapture()` was
+    // everything an editor frame logged while play was stopped and reached no
+    // reader at all (see `collectSessionErrors`). Disjoint from both by
+    // construction, so all three counts sum.
+    sessionErrors: collectSessionErrors(),
+    // Warnings had NO CLI-facing facet whatsoever until this one.
+    sessionWarnings: collectSessionWarnings(),
+    // GPU ownership is measured independently from DOM canvas attachment.
+    // These live counters make context-budget regressions observable without
+    // waiting for the browser to evict the oldest viewport.
+    rendererResources: {
+      ...rendererResourceCounts(),
+    },
+    // The ontology's LIVE invariants, re-derived on read. Every row is present
+    // every time — including the ones this session cannot measure, which say so
+    // rather than vanishing (`coverage/ontology-invariants.ts`).
+    ontologyInvariants:
+      reuse?.['ontologyInvariants'] ?? ontologyInvariantFacet().map((row) => ({ ...row })),
+    // What only a running lane knows — its loop's time scale and liveness,
+    // its seed, a pending restart, and the four capability-GRADING families
+    // (`editor-state-facets.ts`). `reuse` rides through: a facet that declared
+    // reusable keys serves them from the snapshot instead of re-deriving.
+    ...collectEditorStateFacets(reuse),
+    selectedEntityId: selectedIds[0] ?? null,
+    selectedEntityIds: selectedIds,
+    // The machine door onto the creation-site index: the source
+    // location that constructed the SELECTED object, or the named reason there
+    // isn't one. `null` only when nothing is selected or the active adapter
+    // indexes no creation sites.
+    selectedCreationSite: activeSelectionCreationSite(store),
+    // The WRITE-side half of the same answer: which lane an edit to the
+    // selection would take (`WriteAnchorKind`). A sweep needs it to find one
+    // representative subject per lane — the anchor above cannot distinguish a
+    // JSX prop from a construction literal, nor either from a body-placed
+    // spawn, and those have different correctness contracts.
+    selectedWriteAnchorKind: activeSelectionWriteAnchorKind(store),
+    activeViewportTab: store.activeViewportTab,
+    activeDocumentId,
+    activeUtilityId: activeWorkspaceUtility(),
+    gameplaySession: {
+      selectedSessionId: gameplaySessions.selectedSessionId,
+      latestSessionId: gameplaySessions.sessions[0]?.id ?? null,
+      selectedStatus: gameplaySessions.selectedSession?.status ?? null,
+      cursorMs: gameplaySessions.cursorMs,
+      liveEdgeMs: gameplaySessions.liveEdgeMs,
+    },
+    // The registry is the authority for which center subjects EXIST. Doctor
+    // uses this to photograph the project's actual component boards instead
+    // of spending long activation windows guessing every medium-specific id.
+    openDocumentIds: openWorkspaceDocuments().map((document) => document.descriptor.id),
+    availableDocuments: availableWorkspaceDocuments().map((entry) => ({
+      id: entry.descriptor.id,
+      category: entry.category,
+      default: entry.default,
+    })),
+    // W2: asset viewers are center workspace documents now; this facet keeps
+    // its legacy key vocabulary for control-API consumers — the active ASSET
+    // document's key, or the '__inspector__' sentinel. The sentinel does NOT
+    // imply a visible Inspector: that surface is selection-owned.
+    activeTabKey: (() => {
+      const activeId = activeWorkspaceDocumentId();
+      return activeId && isAssetDocumentId(activeId) ? activeId : '__inspector__';
+    })(),
+    // The viewport's keys (grid, helpers, stats, shading, helper visibility, the
+    // transform tool, space and snap, the camera) are the Three set's status
+    // facet (`viewport-status-facet.ts`), spread in above.
+    entityCount: hierarchyRows.length,
+    // Persistence truth comes from the ACTIVE adapter's PersistenceProvider —
+    // never a per-format store field.
+    savePath: activeSaveDestination(store),
+    // SDK clients need the same persistence truth the editor UI exposes.
+    saveState: activeSaveState(store),
+    // Hierarchy facet (B3-followup): the real node tree, flattened to
+    // id/name/childIds rows (same shape editor.hierarchy.inspect declares),
+    // read from the ACTIVE authoring adapter.
+    entities: hierarchyRows,
+    // Design-surface first-frame stamps. Doctor `--timings` subtracts these
+    // from its `active-tab` ack so a tab flip is a measured wait, not a
+    // blank canvas with no number.
+    viewportActivationTimings: viewportActivationTimings(),
+  };
+}
+
+/**
+ * The answer a caller gets when a command HANDLER threw instead of returning.
+ *
+ * Two things must happen and neither used to: the caller is told what killed
+ * its command (rather than timing out against a message about the tab), and
+ * the failure is logged so it reaches `editorConsole` — which is what
+ * `collectSessionErrors` reads, and therefore what the editor's `status` command prints. The
+ * browser's own `unhandledrejection` path did the second job only for the
+ * FIRST occurrence, because the console capture dedupes an identical message.
+ */
+export function commandThrewResult(cmd: EditorCommand, error: unknown): CommandResult {
+  const message = error instanceof Error ? error.message : String(error);
+  const text = `editor command "${String(cmd['type'])}" threw: ${message}`;
+  // biome-ignore lint/suspicious/noConsole: this IS the loud leg — editorConsole is fed by the console, and it is what the editor's `status` command prints.
+  console.error(text, error);
+  return { ok: false, error: text };
+}
+
+
+/** THE ONE PLAY-RUN FENCE all four error facets below split on: `true` when a
+ *  console entry logged at `timestamp` belongs to the most recent play run.
+ *
+ *  Closed at BOTH ends (the live registry's newest run window), which is
+ *  what makes the play facets and the session facets a genuine partition of the
+ *  session's error entries — every entry belongs to exactly one side, so the
+ *  counts sum with nothing double-counted and nothing dropped. With an
+ *  open-ended window a single play run captured the rest of the session: every
+ *  later editor error read as "during the play run" and was reported only by a
+ *  banner that renders while play is live. */
+function inPlayRun(timestamp: number): boolean {
+  const window = liveRunWindow();
+  if (!window || timestamp < window.startedAt) return false;
+  return window.endedAt === null || timestamp <= window.endedAt;
+}
+
+/** #146 — uncaught page errors from the CURRENT play run, for the editor's `status` command
+ *  and for `@volter/editor-game`'s `bridge-call` snapshot, which imports it from here
+ *  (the two must report the same set; the facet moves when Play does).
+ *  Reads the editor console's 'runtime'-source error entries
+ *  (fed by `installEditorConsoleCapture`'s window error/unhandledrejection
+ *  capture — the same events, same message format as `window.__volter`'s own
+ *  pageErrors ring buffer), fenced to the play run. Same 100-cap as the bridge
+ *  (`PAGE_ERROR_CAP`), keeping the most recent. */
+export function collectPlayRunPageErrors(): string[] {
+  return editorConsole
+    .getEntries()
+    .filter((e) => e.level === 'error' && e.source === 'runtime' && inPlayRun(e.timestamp))
+    .slice(-100)
+    .map((e) => (e.count > 1 ? `${e.message} (×${e.count})` : e.message));
+}
+
+/** How many of the newest console-error messages the summary carries, and how
+ *  far each is truncated. A banner that reprints every message on a noisy run
+ *  stops being readable, which is the failure mode this exists to fix (same
+ *  reasoning as `authoringWarningsWarning`'s per-file summary in the CLI); the
+ *  full text is in the editor console and the run's `logs/play-*.jsonl`. */
+const CONSOLE_ERROR_SAMPLE = 3;
+const CONSOLE_ERROR_MESSAGE_CAP = 200;
+
+/** Error-level editor-console entries from the CURRENT play run that
+ *  `collectPlayRunPageErrors` above does NOT already report — i.e. everything except
+ *  the 'runtime' source. That exclusion is what makes the two facets disjoint,
+ *  so a reader can add the counts without double-counting one error.
+ *
+ *  The dominant member is source 'game': `play-mode.ts`'s console patch funnels
+ *  the running game's own `console.error` here, and that channel reached no CLI
+ *  reader at all. `count` totals OCCURRENCES (the console store collapses
+ *  identical consecutive messages into one entry with a `count`), so a loop
+ *  erroring every frame reports the real number rather than 1. Fenced to
+ *  the live run window exactly like `collectPlayRunPageErrors`, and `{count: 0,
+ *  recent: []}` while stopped. */
+function collectConsoleErrors(): { count: number; recent: string[] } {
+  return summarizeEntries(
+    editorConsole
+      .getEntries()
+      .filter((e) => e.level === 'error' && e.source !== 'runtime' && inPlayRun(e.timestamp)),
+  );
+}
+
+/** The shared `{count, recent}` shape: `count` totals OCCURRENCES (the console
+ *  store collapses identical consecutive messages into one entry carrying a
+ *  `count`), `recent` is the newest few, source-tagged and truncated. */
+function summarizeEntries(entries: readonly ConsoleEntry[]): { count: number; recent: string[] } {
+  const count = entries.reduce((sum, e) => sum + e.count, 0);
+  const recent = entries.slice(-CONSOLE_ERROR_SAMPLE).map((e) => {
+    const source = e.source ? `[${e.source}] ` : '';
+    const repeats = e.count > 1 ? ` (×${e.count})` : '';
+    const message =
+      e.message.length > CONSOLE_ERROR_MESSAGE_CAP
+        ? `${e.message.slice(0, CONSOLE_ERROR_MESSAGE_CAP)}…`
+        : e.message;
+    return `${source}${message}${repeats}`;
+  });
+  return { count, recent };
+}
+
+/** Error-level entries from the whole EDITOR SESSION that the two play-fenced
+ *  facets above do NOT report — i.e. everything logged outside the most recent
+ *  play run's window (`inPlayRun`). That exclusion is what keeps all three
+ *  disjoint, exactly as `collectConsoleErrors` excludes source 'runtime'.
+ *
+ *  Measured defect this closes: a human watching the editor's browser console
+ *  saw real errors — Content-tab story previews throwing `useRapier must be
+ *  used within <Physics>` — while the editor's `status` command reported `consoleErrors:
+ *  {count: 0}` and `pageErrors: []`. Nothing was wrong with either facet: both
+ *  are fenced to a play run, and the ONLY funnel from a raw `console.error`
+ *  into the store was play-mode's patch, installed at play start and removed at
+ *  play stop. Outside play, an editor-frame error existed in the browser
+ *  console and nowhere else. `installEditorConsoleCapture()` (editor boot) now
+ *  feeds the store for the whole session, and this is the facet that reports
+ *  it — including uncaught page errors ('runtime') thrown outside a play run,
+ *  which `collectPlayRunPageErrors` deliberately still does not claim.
+ *
+ *  Fence: since editor page load (the store starts empty at boot), NOT since
+ *  play start. */
+function collectSessionErrors(): { count: number; recent: string[] } {
+  return summarizeEntries(
+    editorConsole.getEntries().filter((e) => e.level === 'error' && !inPlayRun(e.timestamp)),
+  );
+}
+
+/** Warn-level entries from the whole editor session. No play-fenced facet
+ *  reports warnings at ALL — `console.warn` had no CLI-facing channel of any
+ *  kind — so this one is not narrowed to outside-play: narrowing it would
+ *  simply re-hide every warning a play run emits. Same `{count, recent}`
+ *  discipline as the error facets; the `[source]` tag on each sample is what
+ *  tells a reader whether a warning came from the game, the editor, or the
+ *  server. */
+function collectSessionWarnings(): { count: number; recent: string[] } {
+  return summarizeEntries(editorConsole.getEntries().filter((e) => e.level === 'warn'));
+}
+
+/**
+ * `document-script` relay op — `editor.document.run(ctx => …)`. The same
+ * wire contract as `page-script` (a step's own source, reconstructed here;
+ * closures do not survive), bound not to a page shim but to the object the
+ * ACTIVE document published as its context. Refuses by name when no document
+ * is active or the active one published nothing, so an agent is never told
+ * a step ran against a document that has no session to run it on.
+ */
+async function handleDocumentScript(cmd: EditorCommand): Promise<CommandResult> {
+  const src = cmd['src'];
+  if (typeof src !== 'string') {
+    return { ok: false, error: 'document-script requires a string "src" (the step\'s toString())' };
+  }
+  const documentId = activeWorkspaceDocumentId();
+  if (!documentId) {
+    return {
+      ok: false,
+      error: 'document-script: no document is active',
+      data: { code: 'DOCUMENT_SCRIPT_UNAVAILABLE' },
+    };
+  }
+  await waitForDocumentContext(documentId);
+  const context = documentContextFor(documentId);
+  if (activeWorkspaceDocumentId() !== documentId) {
+    return {
+      ok: false,
+      error: 'document-script: the active document changed while its context was loading',
+      data: { code: 'DOCUMENT_SCRIPT_UNAVAILABLE', documentId },
+    };
+  }
+  if (context === undefined) {
+    return {
+      ok: false,
+      error:
+        `document-script: the active document (${documentId}) publishes no context to run ` +
+        'against — a document opts in through its `publishContext` prop (the mesh document ' +
+        'publishes its session).',
+      data: { code: 'DOCUMENT_SCRIPT_UNAVAILABLE', documentId },
+    };
+  }
+  let step: (ctx: unknown, info: { documentId: string }) => unknown;
+  try {
+    step = new Function('ctx', 'info', `return (${src})(ctx, info)`) as typeof step;
+  } catch (err) {
+    return {
+      ok: false,
+      error: `document-script: failed to reconstruct the step function from source — ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+      data: { code: 'DOCUMENT_SCRIPT_ERROR' },
+    };
+  }
+  try {
+    const result = await step(context, { documentId });
+    return { ok: true, data: { result: result === undefined ? null : result } };
+  } catch (err) {
+    return {
+      ok: false,
+      error: `document-script: step threw — ${err instanceof Error ? err.message : String(err)}`,
+      data: { code: 'DOCUMENT_SCRIPT_ERROR' },
+    };
+  }
+}
+
+/**
+ * Exported (alongside `collectState` above) so unit tests can dispatch
+ * commands directly against a headless `ShellStore`, with no SSE/server
+ * round-trip — see `packages/editor/test/command-listener.test.ts`, notably
+ * the false-ack regression test: an unrecognized command must return
+ * `{ok:false}`, never fall through to a fabricated `{ok:true}`.
+ */
+export async function handleCommand(
+  store: ShellStore,
+  cmd: EditorCommand,
+  options?: CommandHandlingOptions,
+): Promise<CommandResult> {
+  // EVERY relayed command is observed (`command-dispatch.ts`): Play's idle
+  // watchdog reads it, and a stamp filed per-case would quietly exclude
+  // whichever case someone forgot.
+  noteCommandDispatched(cmd['type'] as string);
+  // A video export OWNS the paused run it is stepping frame by frame, so no
+  // other command may touch it mid-export. `stop` is the one exception and
+  // falls THROUGH: the export's cancel handle lives with the verb that
+  // started it (`@volter/editor-game`'s `play.command.ts`), and its `stop` handler
+  // aborts the controller before tearing the run down. The FLAG stays host
+  // state (`gameplay-export-state.ts`) because two surfaces outside that verb
+  // read it — this prologue and the PlayBar's transport ownership.
+  if (isGameplayExportActive() && cmd['type'] !== 'stop') {
+    return {
+      ok: false,
+      error: 'Video export owns this paused run. Stop it to cancel before another command.',
+    };
+  }
+  // A running lane answers its own play verbs first (`LiveSession.command`,
+  // the live registry): an ingested game owns its mount, so the first-party
+  // boot must never be handed its container.
+  const answered = dispatchLiveCommand(cmd as { type: string });
+  if (answered) return answered;
+  if (cmd['type'] === 'play' || cmd['type'] === 'restart') {
+    // NO live ingest, but a mount FAILED — refuse with the failure instead of
+    // letting `enterPlayMode` boot a first-party composition over an ingest
+    // manifest. It cannot: `resolveRootBinding` throws for every ingest
+    // identity by construction, and the sentence it throws is about
+    // `ThreeHostContext` not carrying an `EditorStore` — true, internal, and
+    // about a mechanism the reader was never using. MEASURED on the
+    // bubbo-bubbo canvas ingest: the real cause was a capture window spent on
+    // a hidden tab, and the editor's `play` command reported the resolver's contract note,
+    // naming neither the game nor the reason. A failed mount is the answer to
+    // "why can't I play this", whichever lane failed.
+    const failures = getMountFailureReports();
+    if (failures.length > 0) {
+      return {
+        ok: false,
+        error:
+          `this project's ${failures.length === 1 ? 'root' : 'roots'} did not mount, so there ` +
+          `is nothing to ${cmd['type'] === 'play' ? 'play' : 'restart'}: ` +
+          failures.map((f) => `"${f.worldId}" (${f.identity}) — ${f.message}`).join('; '),
+      };
+    }
+  }
+  // The dispatch keys off the TABLE's union, not off a raw string. Two things
+  // follow, and they are the whole point of `command-table.ts`: a `case` whose
+  // label is not a row does not compile, and a row with no `case` fails the
+  // exhaustiveness check in the `default` below. The runtime guard in front of
+  // it is what makes the narrowing honest — an unknown string from an older
+  // CLI still reaches the "unknown command type" answer.
+  // A PACKAGE'S verb (`@volter/sdk/commands`, `command-registry.ts`):
+  // answered by its own handler, through the same relay, ack and derivation
+  // as the host's table below. Asked first so a contributed verb never
+  // reads as "editor page predates this CLI".
+  const contributed = await resolveContributedCommand(cmd['type']);
+  if (contributed) {
+    try {
+      const answer = await contributed.handle(cmd);
+      return {
+        ok: answer.ok,
+        ...(answer.error !== undefined ? { error: answer.error } : {}),
+        ...(answer.data !== undefined ? { data: answer.data } : {}),
+      };
+    } catch (error) {
+      return commandThrewResult(cmd, error);
+    }
+  }
+  if (!isRelayCommandType(cmd['type'])) {
+    return {
+      ok: false,
+      error:
+        `unknown command type "${cmd['type']}" — not one of the editor's own, and no package this ` +
+        'project declares contributes it (or the editor page predates this CLI)',
+      data: { code: 'UNKNOWN_COMMAND_TYPE' },
+    };
+  }
+  const commandType: RelayCommandType = cmd['type'];
+  switch (commandType) {
+    case 'session-prepare-close':
+      await prepareSessionClose();
+      return { ok: true };
+    // Selection
+    case 'select': {
+      const id = (cmd['id'] as string | null) ?? null;
+      if (id !== null) {
+        const refusal = unresolvedSelectionRefusal(store, id);
+        if (refusal) return { ok: false, error: refusal };
+      }
+      applyControlSelection(store, id ? [id] : [], options);
+      break;
+    }
+    case 'select-multiple': {
+      const ids = cmd['ids'] as string[];
+      // All-or-nothing: a partial selection silently dropping the id the caller
+      // cared about is the same fabrication in a quieter form.
+      for (const id of ids) {
+        const refusal = unresolvedSelectionRefusal(store, id);
+        if (refusal) return { ok: false, error: refusal };
+      }
+      applyControlSelection(store, ids, options);
+      break;
+    }
+    case 'select-all': {
+      applyControlSelection(
+        store,
+        activeHierarchyRows(store).map((row) => row.id),
+        options,
+      );
+      break;
+    }
+
+    // Panels
+    case 'viewport-tab': {
+      // The tab is which document has focus: `play` is the Game document, `edit` any other.
+      // Asking for one activates that document; the workspace owns focus.
+      const tab = cmd['tab'];
+      if (tab !== 'edit' && tab !== 'play') {
+        return { ok: false, error: `viewport-tab requires "edit" or "play", got ${String(tab)}.` };
+      }
+      const open = openWorkspaceDocuments().map((document) => document.descriptor.id);
+      const target =
+        tab === 'play'
+          ? open.find((id) => id === GAME_DOCUMENT_ID)
+          : (open.find((id) => id === 'workspace:scene') ?? open.find((id) => id !== GAME_DOCUMENT_ID));
+      if (!target || !activateWorkspaceDocument(target)) {
+        return {
+          ok: false,
+          error:
+            tab === 'play'
+              ? 'viewport-tab play: no Game document is open. Start Play first.'
+              : 'viewport-tab edit: no document other than Game is open.',
+        };
+      }
+      break;
+    }
+    // FOCUS A PANEL. The vocabulary is the static-panel REGISTRY, resolved by
+    // `revealStaticPanel` at call time — the same resolution and the same
+    // refusal a view's `panel` gets, and the same reveal the Window menu's own
+    // items use. This handler recognises no panel by name.
+    case 'show-panel': {
+      try {
+        const panel = cmd['panel'];
+        if (typeof panel !== 'string' || panel.trim() === '') {
+          return { ok: false, error: 'show-panel requires a non-empty "panel".' };
+        }
+        return { ok: true, data: { panel: await revealStaticPanel(panel) } };
+      } catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    }
+    // W2: the legacy right-rail tab commands keep their key vocabulary but
+    // now drive the CENTER workspace documents (`asset-documents.tsx`).
+    // '__inspector__' ("show the Inspector") is a no-op now: the Inspector is
+    // selection-owned, so a command cannot force it open without a subject.
+    case 'active-tab': {
+      const key = cmd['key'] as string;
+      // The ack must MEAN the document is in front. This handler used to
+      // discard `activateWorkspaceDocument`'s boolean, so asking for a
+      // document that does not exist acked `ok` while the workspace kept
+      // showing whatever tab was already there — and every caller that
+      // photographs, inspects or drives "the active document" then read a
+      // surface it never asked for and had no way to notice (doctor's walk
+      // photographed the UI board and filed it as the Scene). The refusal
+      // lists what IS open, because a wrong id is nearly always a stale or
+      // misspelled one and the registry already knows the real set.
+      if (key !== '__inspector__' && !activateWorkspaceDocument(key)) {
+        const open = openWorkspaceDocuments().map((d) => d.descriptor.id);
+        return {
+          ok: false,
+          error:
+            `No open workspace document with id "${key}" — nothing was activated. ` +
+            (open.length > 0
+              ? `Open documents: ${open.join(', ')}.`
+              : 'No documents are open in this workspace.'),
+        };
+      }
+      break;
+    }
+    case 'select-asset': {
+      // The OTHER half of the browser's selection-vs-open contract
+      // (`asset-selection.ts`): a single click SELECTS an asset and fills the
+      // Inspector; a double click OPENS its document. Only `open` had a verb,
+      // so every `asset.inspector` contribution — a project's own Inspector
+      // door — was reachable by mouse alone.
+      const path = cmd['path'];
+      if (typeof path !== 'string' || path.trim() === '') {
+        return { ok: false, error: 'select-asset requires a non-empty "path".' };
+      }
+      // No existence check, for the same reason `open-asset-tab` has none:
+      // the sections that match report their own failures (the Edit Mesh
+      // door says "exports no build()"), and a second file-exists door here
+      // would answer for a tier it cannot see (a hosted project's source has
+      // no `public/` listing). An unknown path selects and the Inspector
+      // shows nothing matched, which is the same answer the browser gives.
+      const clean = path.replace(/^\/+/, '');
+      const name = clean.split('/').pop() ?? clean;
+      const capability = assetCapabilities(name);
+      setSelectedAsset({
+        path,
+        name,
+        kind: assetDocumentKind(capability) ?? 'unknown',
+        capabilities: capability,
+        origin: 'project',
+      });
+      break;
+    }
+    case 'open-asset-tab': {
+      const kind = cmd['kind'] as AssetKind;
+      const documentId = openAssetDocument(cmd['path'] as string, kind);
+      if (!(await waitForAssetDocumentInspector(documentId, kind))) {
+        return {
+          ok: false,
+          error: `Asset document did not finish mounting its Inspector: ${documentId}`,
+        };
+      }
+      break;
+    }
+    case 'close-asset-tab': {
+      // Legacy key vocabulary: the deleted store-era `closeAssetTab` only
+      // ever acted on asset tabs and no-op'd for anything else (scene/game/
+      // story keys included). `closeWorkspaceDocument` itself has no such
+      // guard — it closes ANY registered id, pinned or not (`closeable:
+      // false` is only a UI-affordance rule, not a registry invariant; see
+      // workspace-document-registry.ts) — so this command must keep the
+      // no-op itself. `isAssetDocumentId` is exactly the legacy asset key
+      // vocabulary check (project asset path / `asset-editor:entity:<id>` /
+      // `online:<source>:<id>` — see asset-documents.tsx), so gating on it
+      // blocks the pinned `workspace:scene`/`workspace:game` ids (and any
+      // story `story:<path>#<name>` id) while preserving the real behavior
+      // for actual asset tabs.
+      const key = cmd['key'] as string;
+      if (isAssetDocumentId(key)) closeWorkspaceDocument(key);
+      break;
+    }
+    case 'toggle-command-palette':
+      // The palette is the workbench's; the frame hands over the opener that
+      // shows it (`editor-commands.ts`).
+      openCommandPalette();
+      break;
+    case 'toggle-console':
+      toggleConsoleUtility();
+      break;
+    // RELOAD THIS PAGE — `@volter/game-live`'s `page.reload()` and P20's prescribed
+    // recovery. Deliberately NOT routed through `page-script`: that verb is
+    // gated on a mounted game surface, and the one thing a reload has to fix —
+    // a page whose module-scope loaders and page-lifetime asset caches hold
+    // bytes that have since changed on disk — is just as real with play
+    // stopped, and just as real in a product that has no game at all.
+    //
+    // It is the HOST's for that last reason. It was a `@volter/editor-game` command
+    // contribution until walk 5, so `page.reload()` answered `unknown command
+    // type "page-reload"` in Cyclotron, which declares no `@volter/editor-game`.
+    //
+    // Scheduled for the NEXT task rather than run inline, so this handler can
+    // return and the caller's ack can travel before the navigation tears the
+    // channel down: the client acks the ORDER here and waits for the new page
+    // load on the server's own tab table.
+    case 'page-reload':
+      setTimeout(() => {
+        window.location.reload();
+      }, 0);
+      return { ok: true, data: { scheduled: true } };
+    // NAMED WORKSPACES (ARCHITECTURE-CORE §Editor chrome) — the session
+    // operation `editor.workspace(id)`, the third of the ruling's three
+    // switching doors beside `Window → Workspace` and the registered actions.
+    // A wrong id refuses and NAMES the vocabulary: this is a fixed registry,
+    // so the refusal can be complete.
+    case 'set-workspace': {
+      const id = cmd['workspace'];
+      if (!isEditorWorkspaceId(id)) {
+        return {
+          ok: false,
+          error: `set-workspace requires one of ${editorWorkspaceIds().join(', ')}, got ${String(id)}.`,
+        };
+      }
+      if (activeEditorWorkspace() === id)
+        return { ok: true, data: { workspace: id, applied: true } };
+      // Registered BEFORE the store flip — the dock's rebuild is what resolves
+      // it, and that can land before this handler's next await point. Bounded,
+      // because the store flip is real whether or not a dock is mounted to
+      // follow it: a hung wait would otherwise be reported as "the editor did
+      // not respond", which names the wrong thing.
+      const rebuilt = whenEditorWorkspaceApplied().then(() => true);
+      setEditorWorkspace(id);
+      const applied = await Promise.race([
+        rebuilt,
+        new Promise<boolean>((resolve) => setTimeout(() => resolve(false), 3000)),
+      ]);
+      // NOTHING REVEALS A DRAWER UTILITY HERE ANY MORE. `drawerUtility` was
+      // this line's reason and it is retired: a Blender editor AREA is an
+      // EDITOR GROUP, not a drawer view (orchestrator ruling 2026-09-19), so
+      // the node editor and the UV editor are `workspace.document`
+      // contributions the workspace opens into `volter:area:<id>`
+      // (`workspace-areas.ts`) and the drawer keeps only the utilities that
+      // are not Blender areas.
+      return { ok: true, data: { workspace: id, applied } };
+    }
+    case 'set-style': {
+      const id = cmd['style'];
+      const ids = workspaceStyles().map((bundle) => bundle.id);
+      if (typeof id !== 'string' || !ids.includes(id)) {
+        return {
+          ok: false,
+          error: `set-style requires one of ${ids.join(', ')}, got ${String(id)}.`,
+        };
+      }
+      applyWorkspaceStyle(id);
+      // Reported from the axes, not echoed: a bundle applies through the
+      // settings layer that DECLARES each axis (`updatePreferenceSettings`),
+      // so what the chrome wears is what this answers.
+      const applied = activeWorkspaceStyleId();
+      if (applied !== id) {
+        return {
+          ok: false,
+          error: `set-style applied "${id}" but the editor is wearing ${applied === null ? 'a custom mix of axes' : `"${applied}"`} (${workspaceStyleDifferences(id).join('; ')}).`,
+          data: { style: applied, differences: workspaceStyleDifferences(id) },
+        };
+      }
+      return { ok: true, data: { style: id } };
+    }
+    case 'viewport-presentation': {
+      // A view's PRESENTATION (`kit/viewport-presentation`): what it draws with, lights by and
+      // shows behind the scene. With a `layer`, the person's choice is recorded first — the
+      // same write the toolbar's Lighting and Exposure make — and the view answers resolved.
+      const requested = cmd['documentId'];
+      if (typeof requested !== 'string' || requested === '') {
+        return { ok: false, error: 'viewport-presentation needs a `documentId` (a document stage).' };
+      }
+      // The view is bound under its stage's id, the workspace's `document:` wrapper around the
+      // document id `currentView` reports; either spelling reaches it.
+      const documentId =
+        viewPresentationBinding(requested) === null && viewPresentationBinding(`document:${requested}`) !== null
+          ? `document:${requested}`
+          : requested;
+      const layer = cmd['layer'];
+      if (layer !== undefined) {
+        if (typeof layer !== 'object' || layer === null) {
+          return { ok: false, error: 'viewport-presentation `layer` must be a presentation layer object.' };
+        }
+        setViewPresentation(documentId, layer as PresentationLayer);
+      }
+      // Or a NAMED view (`*.view.ts`), put on the view whole.
+      const preset = cmd['preset'];
+      if (preset !== undefined) {
+        if (typeof preset !== 'string' || !applyViewPreset(documentId, preset)) {
+          return {
+            ok: false,
+            error: `viewport-presentation \`preset\` must be one of: ${viewPresets().map((one) => one.id).join(', ') || '(none registered)'}.`,
+          };
+        }
+      }
+      return {
+        ok: true,
+        data: {
+          presentation: viewPresentation(documentId),
+          binding: viewPresentationBinding(documentId),
+          bound: boundViewPresentations(),
+          lastDraw: viewDrawReport(documentId),
+          presets: studioPresets().map((preset) => preset.id),
+          viewPresets: viewPresets().map((one) => one.id),
+          environmentImages: environmentImages().map((one) => one.id),
+        },
+      };
+    }
+    case 'set-appearance': {
+      // The MATERIAL apart from the bundle that usually carries it.
+      // Appearance is palette × material by ruling (ARCHITECTURE-CORE
+      // §Editor chrome), so nothing through the session could otherwise ask
+      // "is it the blur or the palette?" about a stall a style switch
+      // produces. This is the door that measures the axes apart; it applies
+      // through the same preference writer the menu uses, so what the chrome
+      // wears afterwards is what it answers.
+      const material = cmd['material'];
+      if (material === undefined) {
+        return { ok: false, error: 'set-appearance needs a `material` to set.' };
+      }
+      if (!isEditorMaterialId(material)) {
+        const ids = editorMaterials().map((choice) => choice.id);
+        return {
+          ok: false,
+          error: `set-appearance material must be one of ${ids.join(', ')}, got ${String(material)}.`,
+        };
+      }
+      setEditorMaterialPreference(material);
+      return {
+        ok: true,
+        data: { material: editorMaterialSnapshot(), style: activeWorkspaceStyleId() },
+      };
+    }
+    case 'present-view': {
+      try {
+        const presented = await presentEditorView(store, cmd['view'] as EditorView);
+        return { ok: true, data: { ...presented } };
+      } catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    }
+    case 'current-view':
+      return { ok: true, data: { view: currentEditorView(store) } };
+    case 'inspect': {
+      // `editor.inspect` — the SERIALIZED projection of the inspection model
+      // (`inspection/serialize.ts`), composed from the same live state, by the
+      // same composer, as the column and the compact card
+      // (`inspection/active-subject.ts`). The `InspectedInspection` annotation
+      // is the drift check: the SDK's wire mirror and the editor's own
+      // serialized shape are structurally compared by `tsc` on every build —
+      // including its `{none:true}` arm, which is what a human seeing no
+      // inspector at all serializes to.
+      const subject: InspectedInspection = inspectActiveSubject(store);
+      return { ok: true, data: { subject } };
+    }
+    case 'run-inspection-action': {
+      try {
+        const actionId = cmd['actionId'];
+        if (typeof actionId !== 'string' || actionId.trim() === '') {
+          throw new Error('run-inspection-action requires a non-empty actionId.');
+        }
+        const subject: InspectedInspection = await runActiveInspectionAction(store, actionId);
+        return { ok: true, data: { subject } };
+      } catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    }
+    case 'run-command': {
+      // `editor.command(id, args)` — the ONE door to a command by id (U8's
+      // ruling 1: "so the editor's `eval` command reaches it through the frame's command
+      // service"). Under the frame that IS `ICommandService`; standalone it is
+      // the views registry, and `editor-commands.ts` owns both arms plus
+      // the refusal that names the id shape that would have worked.
+      try {
+        const commandId = cmd['commandId'];
+        if (typeof commandId !== 'string' || commandId.trim() === '') {
+          throw new Error('run-command requires a non-empty commandId.');
+        }
+        const result = await executeCommand(commandId, cmd['args']);
+        // The command's own answer, as far as it survives the wire: a view
+        // verb answers with its state, a workbench command usually with
+        // nothing. `undefined` is not JSON, so it is reported as null rather
+        // than dropping the key and making "ran, said nothing" look like a
+        // malformed reply.
+        return { ok: true, data: { result: result === undefined ? null : result } };
+      } catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    }
+    case 'hierarchy': {
+      // `editor.hierarchy` — the hierarchy panel's OWN rendered row tree,
+      // serialized. Not a fresh walk of the adapter: the panel publishes the
+      // rows and predicates it rendered with and this serializes those, so the
+      // door cannot report a tree the human is not looking at
+      // (`hierarchy-panel-view.ts` header). `editor.status().entities` answers a
+      // deliberately DIFFERENT question — the raw adapter tree, unprojected.
+      const snapshot = hierarchyPanelSnapshot();
+      if (snapshot === null) {
+        return {
+          ok: false,
+          error:
+            'the hierarchy panel (GameHierarchy) is not mounted — no row tree is rendered, so there is nothing to report. Open the Hierarchy panel in the workspace dock and retry.',
+        };
+      }
+      const hierarchy: InspectedHierarchy = serializeHierarchyPanel(snapshot, {
+        playState: store.playState,
+        activeViewportTab: store.activeViewportTab,
+      });
+      return { ok: true, data: { hierarchy } };
+    }
+    // EXPAND/COLLAPSE ALL, and they ship as a pair for a reason. The machine
+    // door uses the panel's own mutations. Reading the raw adapter hierarchy
+    // here would fabricate rows the panel has not rendered and would make
+    // collapsed-branch certification meaningless; and expanding without a way
+    // back is a ONE-WAY door — the fold is written to this project's persisted
+    // preference, and a chevron's own click is not drivable through the
+    // control API (`editor.document.click` refuses editor chrome by name), so
+    // for as long as `expand-hierarchy-all` stood alone, no reader that used
+    // it could ever see the tree's REST STATE again. Both call the toolbar's
+    // own actions, so the human and machine paths cannot diverge. The ack
+    // resolves on the panel's NEXT PUBLISHED SNAPSHOT, so a `hierarchy()` in
+    // the same breath reads the mutated tree rather than the one before it.
+    case 'expand-hierarchy-all':
+    case 'collapse-hierarchy-all': {
+      const expanding = cmd['type'] === 'expand-hierarchy-all';
+      const snapshot = hierarchyPanelSnapshot();
+      if (snapshot === null) {
+        return {
+          ok: false,
+          error: `the hierarchy panel (GameHierarchy) is not mounted — no row tree is rendered, so there is nothing to ${expanding ? 'expand' : 'collapse'}. Open the Hierarchy panel in the workspace dock and retry.`,
+        };
+      }
+      const committed = nextHierarchyPanelSnapshot();
+      if (expanding) snapshot.expandAll();
+      else snapshot.collapseAll();
+      try {
+        await committed;
+      } catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+      }
+      return { ok: true, data: {} };
+    }
+    // UNDO/REDO over the control API. The keyboard shortcut and the command
+    // palette have always had this; an agent authoring through the editor did
+    // not — and for an ingest root, whose only authoring surface IS the editor,
+    // that left an edit with no way back. Same queue, same guards, same
+    // per-transaction semantics as the key press.
+    case 'undo':
+    case 'redo': {
+      const history = options?.history;
+      if (!history) {
+        return {
+          ok: false,
+          error: `${String(cmd['type'])}: this editor has no history session attached, so there is nothing to undo.`,
+        };
+      }
+      const moved = cmd['type'] === 'undo' ? await history.undo() : await history.redo();
+      const snapshot = history.getSnapshot();
+      return {
+        ok: true,
+        data: {
+          moved,
+          canUndo: snapshot.canUndo,
+          canRedo: snapshot.canRedo,
+          undoLabel: snapshot.undoLabel,
+          redoLabel: snapshot.redoLabel,
+        },
+      };
+    }
+    case 'set-inspection-field': {
+      try {
+        const path = cmd['path'];
+        if (typeof path !== 'string' || path.trim() === '') {
+          throw new Error('set-inspection-field requires a non-empty field path.');
+        }
+        // THE ACK NAMES ITS DESTINATION. A write with no persistence route
+        // still ACKs `ok` — it lands on the live object — so without `write`
+        // the caller cannot tell a persisted edit from a vanished one, and
+        // `scripts/doctor-walk.ts` graded a healthy consent-off session as a
+        // silent no-op on exactly that ambiguity.
+        const written: { subject: InspectedInspection; write: InspectedWriteDestination } =
+          await setActiveInspectionField(store, path, cmd['value']);
+        return { ok: true, data: { subject: written.subject, write: written.write } };
+      } catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    }
+    // THE OTHER HALF OF THE WRITE DOOR, and the only one that can express
+    // byte-ABSENCE. `set-inspection-field` writes a VALUE, so reverting a prop
+    // an authoring gesture APPENDED leaves an explicit `[0, 0, 0]` where the
+    // source carried nothing — the file ends one attribute heavier than it
+    // started and no byte-level round trip can close. The human revert arrow
+    // has reached `io.remove` since it shipped; the control API had no door at
+    // all, which made every agent-driven edit/revert unverifiable at byte
+    // level on lanes that were in fact healthy.
+    //
+    // Same io, same persistence pipe, same awaited per-edit ack as `set`.
+    case 'remove-inspection-field': {
+      try {
+        const path = cmd['path'];
+        if (typeof path !== 'string' || path.trim() === '') {
+          throw new Error('remove-inspection-field requires a non-empty field path.');
+        }
+        const removed: { subject: InspectedInspection; write: InspectedWriteDestination } =
+          await removeActiveInspectionField(store, path);
+        return { ok: true, data: { subject: removed.subject, write: removed.write } };
+      } catch (error) {
+        // A LANE WITH NO REMOVAL DOOR IS NOT A FAILED REMOVAL, and the caller
+        // has to be able to tell them apart without matching prose: an
+        // instrument grades the first UNVERIFIABLE (an unreached seam) and the
+        // second FAILED (a removal that ran and left the bytes changed).
+        if (error instanceof InspectionRemovalUnavailableError) {
+          return { ok: false, error: error.message, data: { code: 'REMOVAL_UNAVAILABLE' } };
+        }
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    }
+    // THE STRUCTURE OPS over the control API — the same operations the
+    // hierarchy row's context menu performs, on the same
+    // `authoring/consumer-actions.ts` helpers, so there is one implementation
+    // and not a second that can disagree with the menu.
+    //
+    // A COMMAND VERB rather than inspector `quickActions` deliberately:
+    // `inspect().quickActions` reports the verbs a human sees on the
+    // inspector's identity row, and a dozen structure icons there would be
+    // either a UI redesign or a list of actions nobody can see — both worse
+    // than transcribing what the component verbs already established for
+    // exactly this gap (`@volter/editor-game/contributions/component-verbs.command.ts`,
+    // which is where `extract-component`/`fork-component` live now).
+    //
+    // `id`/`ids` default to the current selection, the menu's own subject. An
+    // op the active adapter does not provide answers `ok: false` naming it,
+    // never a silent no-op.
+    case 'structure-op': {
+      try {
+        const op = String(cmd['op'] ?? '');
+        // THE ACTIVE DOCUMENT'S ADAPTER AND ITS SELECTION, which is the pair
+        // every other consumer of this seam already reads (`editor-hotkeys.ts`'s
+        // `actionSelectionIds`, the hierarchy panel, `editor.status()`). This
+        // case read `getActiveAuthoring` + the SHELL store instead, so on a
+        // document whose adapter owns its own selection — the Blender Model
+        // document, whose Outliner publishes Blender row ids — it refused with
+        // "the active authoring adapter exposes no structure provider" while
+        // the document's own adapter had one and the panel was drawing its
+        // selection (measured 2026-09-21: `editor.structure('duplicate')` on a
+        // selected Torus, B6's last named leftover).
+        const adapter = resolvePanelAuthoring(store).adapter;
+        const selected = activeSelectionIds(store);
+        const ids = Array.isArray(cmd['ids'])
+          ? (cmd['ids'] as unknown[]).filter((v): v is string => typeof v === 'string')
+          : typeof cmd['id'] === 'string' && cmd['id'].trim() !== ''
+            ? [cmd['id']]
+            : selected;
+        const first = ids[0];
+        const needsId = (): string => {
+          if (!first) throw new Error(`structure-op "${op}" needs an id or a selected row.`);
+          return first;
+        };
+        const optional = (key: string): string | undefined =>
+          typeof cmd[key] === 'string' && (cmd[key] as string).trim() !== ''
+            ? (cmd[key] as string)
+            : undefined;
+        const structure = adapter.structure;
+        if (!structure) {
+          return {
+            ok: false,
+            error: 'structure-op: the active authoring adapter exposes no structure provider.',
+          };
+        }
+        switch (op) {
+          case 'create': {
+            const kind = optional('kind');
+            if (!kind) return { ok: false, error: 'structure-op "create" needs a `kind`.' };
+            const created = createAuthoringNode(adapter, kind, optional('parentId'));
+            return { ok: true, data: { id: created.id, write: await created.ack } };
+          }
+          case 'delete': {
+            const write =
+              ids.length > 1 && structure.removeMany
+                ? await removeManyAuthoringNodes(adapter, ids)
+                : await removeAuthoringNode(adapter, needsId());
+            return { ok: true, data: { write } };
+          }
+          case 'duplicate': {
+            if (ids.length > 1 && structure.duplicateMany) {
+              const write = await duplicateManyAuthoringNodes(adapter, ids);
+              return { ok: true, data: { write } };
+            }
+            const copy = duplicateAuthoringNode(adapter, needsId());
+            return { ok: true, data: { id: copy.id, write: await copy.ack } };
+          }
+          case 'reparent': {
+            const parentId = optional('parentId') ?? null;
+            return {
+              ok: true,
+              data: { write: await reparentAuthoringNode(adapter, needsId(), parentId) },
+            };
+          }
+          case 'reorder': {
+            if (!structure.reorder) {
+              return { ok: false, error: 'structure-op: this adapter has no `reorder`.' };
+            }
+            const before = optional('beforeSiblingId') ?? null;
+            return {
+              ok: true,
+              data: { write: await reorderAuthoringNode(adapter, needsId(), before) },
+            };
+          }
+          case 'wrap': {
+            if (!structure.wrap) {
+              return { ok: false, error: 'structure-op: this adapter has no `wrap`.' };
+            }
+            return {
+              ok: true,
+              data: { write: await wrapAuthoringNode(adapter, needsId(), optional('tag')) },
+            };
+          }
+          case 'unwrap': {
+            if (!structure.unwrap) {
+              return { ok: false, error: 'structure-op: this adapter has no `unwrap`.' };
+            }
+            return { ok: true, data: { write: await unwrapAuthoringNode(adapter, needsId()) } };
+          }
+          case 'group': {
+            if (!structure.group) {
+              return { ok: false, error: 'structure-op: this adapter has no `group`.' };
+            }
+            const grouped = groupAuthoringNodes(adapter, ids);
+            return { ok: true, data: { id: grouped.id, write: await grouped.ack } };
+          }
+          case 'ungroup': {
+            if (!structure.ungroup) {
+              return { ok: false, error: 'structure-op: this adapter has no `ungroup`.' };
+            }
+            const ungrouped = ungroupAuthoringNode(adapter, needsId());
+            return { ok: true, data: { ids: ungrouped.ids, write: await ungrouped.ack } };
+          }
+          case 'copy': {
+            if (!structure.copy) {
+              return { ok: false, error: 'structure-op: this adapter has no `copy`.' };
+            }
+            return { ok: true, data: { copied: await copyAuthoringNodes(adapter, ids) } };
+          }
+          case 'cut': {
+            if (!structure.cut) {
+              return { ok: false, error: 'structure-op: this adapter has no `cut`.' };
+            }
+            const outcome = await cutAuthoringNodes(adapter, ids);
+            return outcome === false
+              ? { ok: false, error: 'structure-op "cut" was refused by the adapter.' }
+              : { ok: true, data: { write: outcome } };
+          }
+          case 'paste': {
+            if (!structure.paste) {
+              return { ok: false, error: 'structure-op: this adapter has no `paste`.' };
+            }
+            const parentId =
+              optional('parentId') ??
+              (first ? (adapter.hierarchy.node(first)?.parentId ?? null) : null);
+            const outcome = await pasteAuthoringNodes(adapter, parentId);
+            return outcome === false
+              ? { ok: false, error: 'structure-op "paste" was refused by the adapter.' }
+              : { ok: true, data: { write: outcome } };
+          }
+          default:
+            return {
+              ok: false,
+              error:
+                `structure-op: unknown op ${JSON.stringify(op)}. Known ops: create, delete, ` +
+                'duplicate, reparent, reorder, wrap, unwrap, group, ungroup, copy, cut, paste.',
+            };
+        }
+      } catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    }
+    case 'document-probe': {
+      // `editor.document.*` — the scoped editor-chrome door. Every refusal
+      // (no active document, unmounted surface, target outside the scope)
+      // comes back as the step's own honest error text, because the scope
+      // NAME is the useful half of the answer
+      // (`editor-document-probe.ts`'s header).
+      try {
+        const result = await runDocumentProbe(cmd['step'] as DocumentProbeStep);
+        return { ok: true, data: { ...result } };
+      } catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    }
+    case 'capture-active-document': {
+      const requested = captureSizeFromCommand(cmd);
+      if ('error' in requested) return { ok: false, error: requested.error };
+      try {
+        if (cmd['view']) await presentEditorView(store, cmd['view'] as EditorView);
+        const capture = await captureActiveEditorDocument(store, requested.size);
+        announcePhotograph(capture.base64);
+        return { ok: true, data: { ...capture } };
+      } catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    }
+    case 'capture-editor-chrome': {
+      // The editor PAGE itself — see `editor-chrome-capture.ts`. The page is
+      // photographed at its own LAYOUT; `scale` chooses only how many output
+      // pixels one CSS pixel becomes, defaulting to the display's own ratio.
+      // A stroke weight compared against a 2x reference needs `scale: 2`.
+      const scale = cmd['scale'];
+      if (scale !== undefined && (typeof scale !== 'number' || !(scale > 0) || scale > 4)) {
+        return {
+          ok: false,
+          error:
+            'capture-editor-chrome: "scale" must be a number greater than 0 and no more than 4 ' +
+            '(output pixels per CSS pixel; the frame crosses the relay as base64 PNG). ' +
+            "It defaults to the page's own devicePixelRatio.",
+        };
+      }
+      const region = cmd['region'];
+      if (region !== undefined && region !== 'page' && region !== 'document' && region !== 'play') {
+        return { ok: false, error: 'capture-editor-chrome: "region" is "page", "document" or "play".' };
+      }
+      const name = cmd['name'];
+      if (name !== undefined && (typeof name !== 'string' || name.trim() === '' || name.length > 80)) {
+        return { ok: false, error: 'capture-editor-chrome: "name" is a few words saying what the photograph is of (1 to 80 characters).' };
+      }
+      try {
+        // The whole page holds the corner picture; a document or play region never does.
+        if (region === undefined || region === 'page') withdrawPhotograph();
+        const capture = await captureEditorChrome(store, {
+          ...(scale === undefined ? {} : { scale: scale as number }),
+          ...(region === undefined ? {} : { region }),
+        });
+        announcePhotograph(capture.base64, typeof name === 'string' ? name.trim() : undefined);
+        return { ok: true, data: { ...capture } };
+      } catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    }
+    /**
+     * OPEN one piece of the adapter's scene table by id — the table's ONE
+     * `open` verb (ARCHITECTURE-CORE §Editor). One verb for a scene, a prefab,
+     * or a story state, because the table makes them siblings: they differ only
+     * in instance site.
+     *
+     * TWO CLIENTS, one verb. With a game LIVE in this session the live half
+     * answers first (`scene-live-open.ts`): the running game IS the surface, so
+     * a `game-contract` scene is opened by asking the game to navigate and a
+     * `root-mount` scene by showing the document it draws into. It answers
+     * `null` for the reaches that are the Edit workspace's
+     * (`components/scene-documents.tsx`), which then runs unchanged.
+     *
+     * Both halves answer from the SAME declared field — the live half switches
+     * on `entry.reach.kind`, and the Edit half's `liveReach` is derived from
+     * `entry.reach` alone (`scene-document-plan.ts`'s `liveReachOf`).
+     * `authorable` decides the Edit DOCUMENT and nothing else — it is not asked
+     * here, because whether a running game can be sent to one of its own screens
+     * is the game's contract to answer, not the host's opinion of whether that
+     * screen is authorable.
+     *
+     * The two halves agree about every reach the live half REACHES:
+     * `liveReach` is `'game-contract' | 'root-mount' | 'entrypoint-selection'`,
+     * exactly the set that ends `ok: true` there when the session can honour
+     * it, so with nothing running both refuse as
+     * `SCENE_NAVIGATION_NOT_RUNNING` rather than as a dead end.
+     * A session with no remount seam still refuses `entrypoint-selection`
+     * as `SCENE_NOT_OPENABLE_LIVE` — that is a session fact, not a reach
+     * fact.
+     *
+     * Every refusal is CODED, because the classes are graded differently and
+     * prose cannot separate them: `SCENE_NOT_FOUND` names the ids that DO
+     * exist, `SCENE_NOT_OPENABLE` quotes the adapter's own declared reason
+     * verbatim rather than paraphrasing a claim about someone else's game, and
+     * `SCENE_NAVIGATION_NOT_RUNNING` says the scene is live-only rather than
+     * unreachable.
+     */
+    // The document table the host resolved (ARCHITECTURE-CORE §The project
+    // model, "Documents, not scenes"), as the wire projection `getState`
+    // already carries. A COMMAND rather than a state read so a standing
+    // document that lists the table (a production's Shots bin) is driven the
+    // same way every other surface is.
+    case 'document-table': {
+      const facet = projectAdapterFacet();
+      if (!facet) {
+        return {
+          ok: false,
+          error: 'The project adapter has not resolved yet — no document table to list.',
+          data: { code: 'SCENE_TABLE_UNAVAILABLE' },
+        };
+      }
+      return {
+        ok: true,
+        data: {
+          default: facet.scenes.default ?? null,
+          entries: facet.scenes.entries,
+          pending: facet.documentsPending === true,
+        },
+      };
+    }
+
+    case 'open': {
+      const id = cmd['id'];
+      if (typeof id !== 'string' || id.trim() === '') {
+        return { ok: false, error: 'open requires a non-empty scene-table entry id.' };
+      }
+      // Play's `open()` is live navigation. Edit's `open()` is the tab row —
+      // an ingest mount is not Play (ARCHITECTURE-CORE: every authorable scene
+      // is an Edit document). Routing ingest through the live half is how
+      // opening GameScreen put the Play document up.
+      // A deferred ingest run is a real Play SESSION even though it does not
+      // allocate `play-mode.ts`'s first-party session object. Use the shared
+      // mode predicate so opening an adapter scene reaches that running game's
+      // contract instead of silently falling back to its Edit document.
+      const liveGame = editorIsPlaying();
+      // An entry whose KIND has its own document editor (a model, a machine, a page) opens in
+      // that editor during Play too; only the rest navigate the running game.
+      const entry = liveGame
+        ? projectAdapterFacet()?.scenes.entries.find(
+            (candidate) => candidate.id === id && documentContributionForKind(candidate.kind) === undefined,
+          )
+        : undefined;
+      // The running lane's own remount (Play), asked of the live
+      // registry so this verb names no lane.
+      const remountSelection = liveGame
+        ? async (args: { selection: string; key: string; regionId: string }) =>
+            (await remountLiveSelection(args)) ?? {
+              ok: false as const,
+              error: 'No running lane can remount with a selection.',
+            }
+        : undefined;
+      const live = entry
+        ? await openLiveSceneEntry(entry, {
+            scenes: liveScenes,
+            activateGameDocument: () => activateWorkspaceDocument(GAME_DOCUMENT_ID),
+            gameDocumentId: GAME_DOCUMENT_ID,
+            ...(remountSelection ? { remountSelection } : {}),
+          })
+        : null;
+      const opened = live ?? (await openSceneTableEntryWhenListed(id));
+      return opened.ok
+        ? {
+            ok: true,
+            data: {
+              documentId: opened.documentId,
+              title: opened.title,
+              ...('scene' in opened && opened.scene ? { scene: opened.scene } : {}),
+              ...('restart' in opened && opened.restart ? { restart: true } : {}),
+            },
+          }
+        : {
+            ok: false,
+            error: opened.error,
+            data: {
+              code: opened.code,
+              ...(opened.known === undefined ? {} : { known: [...opened.known] }),
+            },
+          };
+    }
+
+    // The REPL door over the ACTIVE document's published context — Edit mode,
+    // no play gate (`document-context-registry.ts`).
+    case 'document-script':
+      return handleDocumentScript(cmd);
+
+    // Version-skew honesty (the false-ack fix):
+    // every unrecognized command type used to fall through to `return {ok:
+    // true}` below — a silent lie: the browser did NOTHING, but the SDK/CLI
+    // caller was told it succeeded. Reporting a structured failure must hold
+    // for ANY unrecognized `type`, not just the ones known about today. The
+    // `data.code` marker is what the SDK maps to its `*_UNSUPPORTED` codes;
+    // the prose is for humans only.
+    default: {
+      // Unreachable: `isRelayCommandType` above already answered for anything
+      // outside the table. This assignment is the EXHAUSTIVENESS CHECK — it
+      // compiles only while every row of `RELAY_COMMANDS` has a case here.
+      const unhandled: never = commandType;
+      return {
+        ok: false,
+        error: `unknown command type "${String(unhandled)}" — editor page predates this CLI`,
+        data: { code: 'UNKNOWN_COMMAND_TYPE' },
+      };
+    }
+  }
+
+  return { ok: true };
+}
+
+/**
+ * Connect the command listener to the editor server's SSE stream.
+ * Dispatches incoming commands to the store and play-mode functions.
+ * Reports state after each command and on initial connect.
+ */
+export function connectCommandListener(
+  store: ShellStore,
+  /**
+   * The session's own undo/redo queue — the SAME object the keyboard shortcut
+   * and the command palette drive, so a relayed undo is the user's undo and not
+   * a second path into history. Omitted by the isolated component tests that
+   * only need the listener's transport half; the verbs then refuse by name
+   * rather than reaching for `store.projectHistory` behind the queue's back.
+   */
+  history?: HistoryCommands,
+): () => void {
+  // Browser mode (Phase A2): the `volter` CLI control channel is server-only (it
+  // is an SSE command stream + state POSTs to `/__editor/*`, which do not exist
+  // without a Node server). Skip it — otherwise the EventSource retry-loops
+  // against a 404 and every `reportEditorState` POSTs into the void.
+  const source = connectEvents();
+
+  // The last FULL snapshot this page sent. Every report on a user's critical
+  // path reuses its derived facets rather than re-deriving them — see
+  // `state-report-deferral.ts` for the measurement that bought this.
+  let lastFullState: Record<string, unknown> | null = null;
+  /**
+   * The store's `contentVersion` at the moment `lastFullState` was collected.
+   *
+   * The facets `collectState` is allowed to REUSE are the tree-scale ones — the
+   * hierarchy rows and the capability grading. When the store notifies with
+   * nothing but a selection change, `contentVersion` holds still, and every
+   * reused facet in `lastFullState` is therefore already current: scheduling a
+   * full re-derivation to "make it current again" re-derives an answer it
+   * already has. Measured at N=20000 on the canvas lane as a 54-70ms
+   * `IdleRequestCallback @ command-listener.ts` block after EVERY click.
+   */
+  let lastFullContentVersion = -1;
+  // One entry per read-only debug proof in the CURRENT adapter epoch. The epoch is in the key, so
+  // remounts naturally pay for (and publish) their own first proof while repeated clock/snapshot
+  // polls reuse the full report that already contains the identical verdict.
+  const reportedDebugReadProofs = new Set<string>();
+  /**
+   * A Play scene transition is a burst, not one store notification. The
+   * translated FPS measured 4,523 hierarchy objects and several asynchronous
+   * React commits between `unity.load_scene.MainScene` returning and the tree
+   * becoming quiescent. Re-deriving on every notification caused 325-430ms
+   * main-thread blocks and eventually starved the command relay; deriving on
+   * the command's first notification left the cached hierarchy at IntroMenu.
+   *
+   * Arm exactly one refresh for the burst and move it behind a short quiet
+   * window. Once it lands, ordinary runtime structure, input, state polling,
+   * presence and store reports cannot arm another one. A later explicit game
+   * command/read or Play boundary can arm the next transition honestly.
+   */
+  let playFullReportArmed = false;
+  let playSettleTimer: ReturnType<typeof setTimeout> | null = null;
+  let playCommandContentVersion: number | null = null;
+  let playCommandContentTimer: ReturnType<typeof setTimeout> | null = null;
+  // A tombstone stops POSTing snapshots too. the editor's `status` command reads the server's
+  // last snapshot, so a corpse that kept reporting would keep MINTING
+  // fresh-looking state for a session that no longer exists — the exact
+  // impersonation the tombstone latch exists to end.
+  const reportLatestState = () => {
+    if (sessionEndedState() !== null) return;
+    lastFullState = collectState(store);
+    lastFullContentVersion = store.contentVersion;
+    void reportEditorState(lastFullState);
+  };
+  let cancelDeferredFullReport: (() => void) | null = null;
+  const cancelPlaySettledFullReport = () => {
+    if (playSettleTimer !== null) {
+      clearTimeout(playSettleTimer);
+      playSettleTimer = null;
+    }
+    cancelDeferredFullReport?.();
+    cancelDeferredFullReport = null;
+  };
+  const clearPlayCommandContentCandidate = () => {
+    playCommandContentVersion = null;
+    if (playCommandContentTimer !== null) clearTimeout(playCommandContentTimer);
+    playCommandContentTimer = null;
+  };
+  const schedulePlaySettledFullReport = () => {
+    clearPlayCommandContentCandidate();
+    playFullReportArmed = true;
+    cancelPlaySettledFullReport();
+    playSettleTimer = setTimeout(() => {
+      playSettleTimer = null;
+      cancelDeferredFullReport = scheduleDeferredFullReport(() => {
+        cancelDeferredFullReport = null;
+        playFullReportArmed = false;
+        reportLatestState();
+      });
+    }, 250);
+  };
+  const armPlayCommandContentCandidate = (baseline: number) => {
+    if (store.contentVersion !== baseline) {
+      schedulePlaySettledFullReport();
+      return;
+    }
+    clearPlayCommandContentCandidate();
+    playCommandContentVersion = baseline;
+    playCommandContentTimer = setTimeout(clearPlayCommandContentCandidate, 1_000);
+  };
+  const editorIsActivelyPlaying = () => editorIsPlaying() && store.playState === 'playing';
+  const settleUnscopedPlayCommandRefresh = (commandStartContentVersion: number | null) => {
+    if (commandStartContentVersion !== null) {
+      // A successful relayed command whose declared policy still owes a
+      // derived refresh must not disappear merely because it does not carry
+      // one of the special debug-invoke transition scopes above. Read commands
+      // reach here only when contentVersion moved; `always` mutation/boundary
+      // commands reach here by declaration. Ordinary store notifications have
+      // no command baseline and remain cheap during Play.
+      schedulePlaySettledFullReport();
+    } else if (
+      playCommandContentVersion !== null &&
+      store.contentVersion !== playCommandContentVersion
+    ) {
+      schedulePlaySettledFullReport();
+    } else if (playFullReportArmed && store.contentVersion !== lastFullContentVersion) {
+      // A transition already earned one refresh. Keep moving that ONE
+      // refresh behind the mount burst; this does not arm periodic work.
+      schedulePlaySettledFullReport();
+    }
+  };
+  const handledByPlayReportGate = (
+    playFullReport: CompletedCommandRefresh['playFullReport'],
+    commandStartContentVersion: number | null,
+    derivedRefresh: RelayCommandDerivedRefresh,
+  ): boolean => {
+    if (!editorIsActivelyPlaying()) return false;
+    if (
+      !playCommandOwesDerivedRefresh(
+        derivedRefresh,
+        playFullReport,
+        store.contentVersion,
+        lastFullContentVersion,
+      )
+    )
+      return true;
+    if (playFullReport === 'explicit') {
+      schedulePlaySettledFullReport();
+    } else if (playFullReport === 'if-content-changed') {
+      armPlayCommandContentCandidate(commandStartContentVersion ?? store.contentVersion);
+    } else settleUnscopedPlayCommandRefresh(commandStartContentVersion);
+    return true;
+  };
+  /**
+   * Report NOW with everything cheap fresh, and make the expensive halves
+   * current in the background.
+   *
+   * This is the path every interaction takes. The immediate POST is what keeps
+   * the "UI Play/Stop is visible to the editor's `status` command immediately" contract and
+   * every other same-tick freshness promise in this file — playState, loop
+   * liveness, selection, save state, presence and the error channels are all
+   * derived fresh here. What it does NOT do is re-walk the hierarchy and
+   * re-grade every capability on the frame the user clicked; a single deferred
+   * full collect does that once, however many changes arrived in the burst.
+   */
+  const reportCurrentState = (
+    /**
+     * `'if-content-changed'` skips the deferred full re-derivation when the
+     * store's `contentVersion` has not moved since the last full collect —
+     * see `lastFullContentVersion`. ONLY the store-notification path may ask
+     * for it: every other trigger here (restart-required, the ingest capture
+     * wait, the adapter load, focus/blur, a completed command) can change a
+     * reused facet WITHOUT any store notification at all, and the store's
+     * version knows nothing about them.
+     */
+    derivedRefresh: RelayCommandDerivedRefresh = 'always',
+    playFullReport: CompletedCommandRefresh['playFullReport'] = 'none',
+    commandStartContentVersion: number | null = null,
+  ) => {
+    if (sessionEndedState() !== null) return;
+    if (lastFullState === null) {
+      // Nothing to reuse yet — the honest floor is to pay for a real collect
+      // rather than report a fabricated or empty derivation.
+      reportLatestState();
+      return;
+    }
+    const state = collectState(store, lastFullState);
+    lastFullState = state;
+    void reportEditorState(currentStatePatch(state));
+    if (derivedRefresh === 'none') return;
+    if (handledByPlayReportGate(playFullReport, commandStartContentVersion, derivedRefresh)) return;
+    // Pause/stop leave a complete, stable surface and must publish it. Any
+    // pending Play refresh is superseded by this non-presenting full report.
+    cancelPlaySettledFullReport();
+    clearPlayCommandContentCandidate();
+    playFullReportArmed = false;
+    if (
+      derivedRefresh === 'if-content-changed' &&
+      store.contentVersion === lastFullContentVersion
+    ) {
+      return;
+    }
+    if (cancelDeferredFullReport !== null) return;
+    cancelDeferredFullReport = scheduleDeferredFullReport(() => {
+      cancelDeferredFullReport = null;
+      reportLatestState();
+    });
+  };
+  let storeReportScheduled = false;
+  /** A burst that included any trigger OTHER than a store notify takes the
+   *  deferred full refresh unconditionally — see `reportCurrentState`'s
+   *  `derivedRefresh` argument for why the store's version cannot speak for
+   *  those. Widening, never narrowing: one such trigger in a burst is enough. */
+  let storeReportNeedsFullRefresh = false;
+  let reportedStorePlayState = store.playState;
+  const scheduleStateReport = (needsFullRefresh: boolean) => {
+    // One editor action commonly emits several store notifications. Collapse
+    // that synchronous burst into one current snapshot without delaying it a
+    // frame — UI Play/Stop must be visible to the editor's `status` command immediately even
+    // though no relayed command caused the transition.
+    if (needsFullRefresh) storeReportNeedsFullRefresh = true;
+    if (storeReportScheduled) return;
+    storeReportScheduled = true;
+    queueMicrotask(() => {
+      storeReportScheduled = false;
+      const forceRefresh = storeReportNeedsFullRefresh;
+      storeReportNeedsFullRefresh = false;
+      const playBoundary = reportedStorePlayState !== store.playState;
+      reportedStorePlayState = store.playState;
+      reportCurrentState(
+        forceRefresh ? 'always' : 'if-content-changed',
+        playBoundary && store.playState === 'playing' ? 'explicit' : 'none',
+      );
+    });
+  };
+  const reportStoreChange = () => scheduleStateReport(false);
+  const reportExternalChange = () => scheduleStateReport(true);
+  const unsubscribeStoreReport = store.subscribe(reportStoreChange);
+  // R1 — restart-required transitions don't flow through the store (they
+  // have their own listener set in play-mode.ts), but the editor's `status` command readers
+  // need `restartRequired` fresh even when NO editor command caused the
+  // change (an external agent editing an R3F entry mid-play is exactly the
+  // silent-staleness case R1 closes). Re-POST state on every transition.
+  const unsubscribeRestartReport = subscribeLiveSessions(reportExternalChange);
+  // Same reason, for the ingest capture wait: it starts and ends outside any
+  // store notification (a mount awaiting its game's first frame), and on a
+  // hidden tab it can hold for as long as the human is away. Without this the
+  // server's snapshot would predate the wait entirely, so the editor's `status` command would
+  // answer "nothing is ingested" for a mount that is very much in flight. The
+  // wait's OTHER transition — parked↔running as the tab hides and shows —
+  // already re-POSTs through `reportPresence`'s `visibilitychange` listener.
+  // Same reason again, for the project's ADAPTER: it loads asynchronously at
+  // editor init and on project switches, outside any store notification. The
+  // adapter facet is the proof that a project's `editor/volter.adapter.ts` (or the
+  // declared native default) loaded at all, so a snapshot that predates the
+  // load would answer "no adapter" for one that is loaded and live.
+  const unsubscribeAdapterReport = subscribeProjectAdapter(reportExternalChange);
+  // A viewport's first completed frame also lands outside the store. Report
+  // it proactively so remote readers can poll the server-held state instead
+  // of injecting no-op `active-tab` commands while a large board is rendering.
+  const unsubscribeViewportActivationReport =
+    subscribeViewportActivationTimings(reportExternalChange);
+
+  // Report initial state
+  reportLatestState();
+  // …and the standing fact the state snapshot cannot carry: this page is now
+  // running a command listener. Before this, a page that beat but never got
+  // here was indistinguishable from a healthy one until somebody sent a
+  // command and watched it hang. See `reportCommandListener`.
+  void reportCommandListener(true);
+  // The other standing fact of that shape: which step of a play boot this page
+  // is inside. Wired HERE because this is the module that owns "facts this page
+  // reports upstream", and because a phase is only useful to a reader who can
+  // also see the command it explains. See `play-boot-phase.ts`.
+  setPlayBootPhaseReporter(reportPlayBootPhase);
+
+  // And again on every RE-open. The server drops a tab's health snapshot
+  // when its connection goes, and a tab with no health is deliberately never
+  // chosen as the command controller (`editor-sse.ts`'s `selectedController`:
+  // an identified tab that has not reported yet is connected but not
+  // command-ready). Without this, a reconnect — the control socket's backoff
+  // after any blip — left the tab uncontrollable until the next store
+  // change, presence event, or command happened to fire.
+  source.addEventListener('open', () => {
+    // A reconnect is transport state, not a project mutation. In Play, a full
+    // reconnect collect was enough to stall a large world and provoke another
+    // disconnect; reuse the last honest derived facets and publish the cheap
+    // liveness/presence fields immediately.
+    reportCurrentState('if-content-changed');
+    // Listener readiness belongs to the PAGE, but the server deliberately
+    // drops its cached proof when this page has no connection left. Re-prove
+    // it on the successor connection instead of leaving status at
+    // `not attached` until some unrelated state transition happens.
+    void reportCommandListener(sessionEndedState() === null);
+  });
+
+  // A page whose session has ENDED must leave the bijection's account of live
+  // tabs rather than sit in it answering probes. Reporting the listener
+  // detached is exactly the fact `server/server-utils.ts`'s
+  // `commandListenerHealth` already prints per tab (`not attached`), so the
+  // server's own tab table names the corpse without a second liveness notion
+  // beside it. The `resume` branch of the lease's recovery re-attaches.
+  const unsubscribeTombstone = onSessionEndedChange((state) => {
+    void reportCommandListener(state === null);
+  });
+
+  source.addEventListener('editor-command', (e: MessageEvent) => {
+    try {
+      const cmd = JSON.parse(e.data as string) as EditorCommand;
+      const requestId = cmd._requestId;
+      const commandStartContentVersion = store.contentVersion;
+      // A tombstone answers, and what it answers is a REFUSAL naming its state.
+      // Silence here would be worse than the defect: the caller would wait out
+      // its whole budget and then be told the tab did not respond — a sentence
+      // about a healthy tab, for a page that is dead.
+      const tombstone = sessionEndedState();
+      if (tombstone !== null) {
+        const error = sessionEndedRefusal(tombstone, String(cmd['type']));
+        if (requestId) void reportCommandResult(requestId, false, error);
+        return;
+      }
+      // Receipt FIRST, before any work: it answers "this tab's command
+      // listener is running", which is the one thing the relay cannot observe
+      // and the thing a long-budget command (`play`'s 120s) otherwise spends
+      // its whole budget failing to learn. Not awaited — the work must not
+      // queue behind it. See `server/server-utils.ts`'s `RELAY_DELIVERY_ACK_MS`.
+      if (requestId) void reportCommandReceived(requestId);
+      let present: (() => void) | undefined;
+      handleCommand(store, cmd, {
+        deferPresentation: (effect) => {
+          present = effect;
+        },
+        ...(history ? { history } : {}),
+      })
+        // A handler that THROWS must still answer its caller. Without this leg
+        // the rejection reached only the browser's `unhandledrejection`
+        // channel: the relay's caller got nothing and timed out into
+        // "the tab is present … and did not respond" — which blames the tab
+        // for a defect in the command — and the console capture DEDUPES a
+        // repeated message, so the SECOND occurrence of the same failure left
+        // the session journal completely silent. Measured 2026-08-15 on a
+        // racing-game ingest mount (`capture-viewport` with a non-number
+        // `size`; see `captureSizeFromCommand`).
+        .catch((error: unknown) => commandThrewResult(cmd, error))
+        .then((result) => {
+          // Report command result back to server (so SDK/CLI gets the response)
+          if (requestId) {
+            const ack = reportCommandResult(
+              requestId,
+              result.ok,
+              result.error,
+              result.data,
+              present !== undefined,
+            );
+            if (present) {
+              // Do not merely queue behind the result send in the same task: wait until the original
+              // caller's response has finished. Only then may a 500-row hierarchy reveal or inspector
+              // preview monopolize the page's main thread. Presentation still runs after the bounded
+              // receipt wait if the server vanished.
+              const schedule = () => window.setTimeout(present!, 0);
+              void ack.then(schedule, schedule);
+            }
+          } else if (present) {
+            window.setTimeout(present, 0);
+          }
+          // The selection SET is already current even when its React presentation is deferred, so
+          // this snapshot reports the applied truth without waiting for hierarchy/Inspector work
+          // — nor, now, for a re-walk and re-grade of the whole project (`reportCurrentState`).
+          const refresh = completedCommandDerivedRefresh(cmd, result.ok, reportedDebugReadProofs);
+          reportCurrentState(refresh.derived, refresh.playFullReport, commandStartContentVersion);
+        });
+    } catch {
+      /* ignore malformed events */
+    }
+  });
+
+  // When the server switches projects, reload to pick up the new project's files
+  source.addEventListener('project-changed', () => {
+    window.location.reload();
+  });
+
+  // #145 — presence freshness: the state snapshot the server holds is only
+  // re-POSTed after commands, so visibility/focus changes between commands
+  // would go stale. Report on the three events that change presence.
+  //
+  // Through `reportCurrentState`, never a full collect: a focus/blur used to
+  // re-derive the entire status surface on the event's own frame, which was
+  // measured at 1221ms (`DOMWindow.onfocus`) and 1306ms (`DOMWindow.onblur`)
+  // of main-thread block on a game-heavy project. Tabbing into the editor
+  // froze it for over a second, every time, and nothing a focus changes is in
+  // the expensive half.
+  // Wrapped, never passed directly: this is an EVENT listener, and handing the
+  // browser's `Event` straight into `reportCurrentState`'s argument would make
+  // the refresh policy depend on an accident of the DOM signature.
+  const reportPresence = (): void => reportCurrentState();
+  document.addEventListener('visibilitychange', reportPresence);
+  window.addEventListener('focus', reportPresence);
+  window.addEventListener('blur', reportPresence);
+
+  // pageErrors freshness (target-blaster friction #3): a runtime error
+  // between commands must reach the server snapshot too, or the editor's `status` command
+  // reads stale-clean. Deferred a tick so the boot-installed error-capture
+  // listener (`installEditorConsoleCapture`, which feeds editorConsole — the
+  // list collectPlayRunPageErrors/collectSessionErrors read) runs FIRST regardless of
+  // registration order.
+  const reportAfterError = () => setTimeout(reportPresence, 0);
+  window.addEventListener('error', reportAfterError);
+  window.addEventListener('unhandledrejection', reportAfterError);
+
+  return () => {
+    // Reported BEFORE the socket closes, so it still has a channel to travel
+    // on. A teardown that also loses the connection is reported by the
+    // server's own `close` handler; this is the case where the page keeps its
+    // channel and stops listening.
+    void reportCommandListener(false);
+    cancelDeferredFullReport?.();
+    cancelDeferredFullReport = null;
+    if (playSettleTimer !== null) clearTimeout(playSettleTimer);
+    playSettleTimer = null;
+    clearPlayCommandContentCandidate();
+    unsubscribeTombstone();
+    unsubscribeStoreReport();
+    unsubscribeRestartReport();
+    unsubscribeAdapterReport();
+    unsubscribeViewportActivationReport();
+    document.removeEventListener('visibilitychange', reportPresence);
+    window.removeEventListener('focus', reportPresence);
+    window.removeEventListener('blur', reportPresence);
+    window.removeEventListener('error', reportAfterError);
+    window.removeEventListener('unhandledrejection', reportAfterError);
+    source.close();
+  };
+}