@volter/editor-game 0.5.65

package/contributions/play.command.ts

@@ -0,0 +1,355 @@
+/**
+ * THE PLAY VERBS of the session wire (`@volter/editor-sdk/commands`, a
+ * `workspace.command` contribution): `play`, `stop`, `pause`, `resume`,
+ * `step`, and the paused run's `bridge-recording-export`.
+ *
+ * These left `command-listener.ts`'s switch when Play left the host (WORK.md
+ * §The workbench, P3b). What did NOT leave is the host's dispatch PROLOGUE,
+ * which still runs before any contributed handler is looked up and therefore
+ * still owns the two gates that are not Play's: the ingest play-control latch
+ * (a captured ingest answers `play`/`stop`/`pause`/`resume`/`step` itself —
+ * P4's move) and the mount-failure refusal. The prologue also refuses every
+ * OTHER command while a video export owns a paused run, reading
+ * `gameplay-export-state.ts`, which stays host-visible for exactly that (the
+ * PlayBar reads it too). The AbortController behind that flag is this file's:
+ * `stop` falls THROUGH the prologue so the handler below can cancel the export
+ * before tearing the run down.
+ *
+ * Host internals Play still holds are reached through the `@editor/*` alias
+ * the editor's Vite serves to every contribution (precedent:
+ * `instances.command.ts`); the doors a lane is meant to use are
+ * `@volter/editor-sdk/host`.
+ *
+ * `play-recording.ts` is Play's own (`../src/play/`): its idle watchdog reads
+ * every relayed command through `host.session.onCommandDispatched`, the door
+ * P4b added, so the stamp is no longer a host call. `gameplay-recording.ts`
+ * stays in the host — `components/GameplaySessionTimeline.tsx`, which
+ * `ToolHost.tsx` mounts directly for the `workspace.analytics` point, imports
+ * it, and no contribution point injects a panel's header component.
+ */
+
+import { getActiveSystems } from '@volter/editor-core/authoring/active-systems';
+import { setGameplayExportActive } from '@volter/editor-core/gameplay-export-state';
+import { stopGameplayRecording } from '../src/host/gameplay-recording';
+import { liveInstanceContainer } from '@volter/editor-core/live-session-registry';
+import type { CommandContribution } from '@volter/editor-sdk/commands';
+import { editorHost } from '@volter/editor-sdk/host';
+import type { OfflineAudioRenderer } from '@volter/editor-project/adapter';
+import { flushSync } from 'react-dom';
+import { notPlayingResult, structuredErrorResult } from '../src/command-results';
+import {
+  enterPlayMode,
+  exitPlayMode,
+  getPlayRuntimeAccess,
+  pausePlayMode,
+  resumePlayMode,
+  stepPlayMode,
+} from '../src/play/play-mode';
+import { beginPlayRecording, endPlayRecording, notePlayActivity } from '../src/play/play-recording';
+
+export const point = 'workspace.command';
+
+/** Pixel recovery is a command-time concern. Keeping this indirection here
+ * avoids loading the Pixi extraction stack merely because the control relay
+ * is listening for a future screenshot/recording command. */
+async function captureLiveCanvasFrame(
+  canvas: HTMLCanvasElement,
+): Promise<CanvasImageSource | null> {
+  const { liveCanvasFrame } = await import('@volter/editor-core/live-canvas-frame');
+  return liveCanvasFrame(canvas);
+}
+
+/** Both recording entry points keep a hidden native game's pixels current. */
+function refreshRecordingFrame(): void {
+  const runtime = getPlayRuntimeAccess();
+  if (runtime?.loop.liveness === 'loop-starved') runtime.runTicks?.(1, { render: 'last' });
+}
+
+/**
+ * The fixed-step export's audio, or `undefined` when this world has none.
+ *
+ * Two facts have to line up, and BOTH come from the live run, never from a
+ * default. The world's `AudioAdapter` must implement `renderOffline` (the
+ * offline, deterministic sibling of the recorder's real-time
+ * `acquireRecordingStream` — a paused run being stepped makes no real-time
+ * sound at all), and the run must be able to say WHERE IT STANDS on its own
+ * canonical clock, because the render is asked for an ABSOLUTE sim window.
+ * `time` is the engine's built-in debug state provider
+ * (`engine/src/runtime/debug-registry.ts`), the same one the play log stamps
+ * entries from.
+ *
+ * A world that cannot answer the clock question — an ingest root with no tick
+ * runner — gets no audio rather than a fabricated `start: 0`, which would
+ * silently render the wrong slice of the score against the right frames.
+ */
+function exportAudioSource(): { startSeconds: number; render: OfflineAudioRenderer } | undefined {
+  const audio = getActiveSystems().audio;
+  const render = audio?.renderOffline;
+  if (!audio || !render) return undefined;
+  let startSeconds: number | null = null;
+  try {
+    const time = getActiveSystems().debug?.state('time') as { simSeconds?: number } | undefined;
+    if (typeof time?.simSeconds === 'number' && Number.isFinite(time.simSeconds)) {
+      startSeconds = time.simSeconds;
+    }
+  } catch {
+    startSeconds = null;
+  }
+  if (startSeconds === null) return undefined;
+  return { startSeconds, render: render.bind(audio) };
+}
+
+/** The in-flight video export's cancel handle. Module state, like the flag it
+ *  raises in `gameplay-export-state.ts`: one paused run, one export. */
+let gameplayExportAbort: AbortController | null = null;
+
+export const commands: CommandContribution['commands'] = {
+  play: {
+    // `play` boots the game, including its full async `setup()` (asset loads,
+    // procedural worldgen); under the generic budget any substantial game
+    // reported "did not respond" while play in fact succeeded.
+    timeoutMs: 120_000,
+    derivedRefresh: 'always',
+    handle: async (cmd) => {
+      // Fix for the ghost-runtime bug — deliberately no "already running"
+      // guard here: `play` on an already-playing (or still-booting) session
+      // is a RESTART, not a no-op, matching the SDK's own documented contract
+      // (`play.start`'s summary: "Start (or restart) play mode" —
+      // `packages/vgai-sdk/src/play/lifecycle-operations.ts`). What used to
+      // make a restart unsafe was `enterPlayMode()` having no reentrancy
+      // guard for the async-boot window before it assigns `_session` — two
+      // overlapping calls ran their entire prologues concurrently and
+      // corrupted shared module state (proven by a real console-patching
+      // stack overflow — see `play-mode-reentry-ghost.test.ts`). That is
+      // fixed at the source in `enterPlayMode()` itself (a FIFO queue
+      // serializes every invocation), so every caller of THIS handler — CLI,
+      // SDK, a UI Play-button click racing a relayed command — gets a safe,
+      // clean restart for free without needing a guard here too.
+      try {
+        // D15/T-D15.6 (objection-4 fix) — `vgai play --seed <n>` relays as
+        // `cmd['seed']`; `enterPlayMode`'s explicit-config seed leg (beats
+        // manifest.determinism.defaultSeed/?vgai-seed=).
+        const seed = cmd['seed'];
+        // `vgai play --name <text>` rides the same wire as `--seed`: a plain
+        // field on the relayed command, slugified server-side into this run's
+        // log filename and journal line. Absent, everything is unchanged.
+        const runName = cmd['name'];
+        await enterPlayMode(
+          typeof seed === 'number' ? seed : undefined,
+          undefined,
+          typeof runName === 'string' ? runName : null,
+        );
+      } catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+      }
+      // PD-1 — never ack a play that did not start. `enterPlayMode()` resolving
+      // does NOT mean play is running: it also resolves for every path that
+      // abandoned this run (a Stop or a newer play landed during the async
+      // boot, invalidating this generation). Those used to return `{ok:true}`,
+      // and the CLI — seeing `playState: 'stopped'` a moment later — fell back
+      // to "✗ Play mode failed — check logs/play-*.jsonl", a message naming no
+      // cause and pointing at a log that says nothing about it. Ack the
+      // measured truth (the live registry, the same predicate `collectState`
+      // derives `playState` from) instead of the call returning.
+      // The other honest answers are adapter-owned: a root with design-time
+      // pieces is a deferred ingest Play session, a boot-mounted ingest runs
+      // through its explicit play-control latch, and a standalone `{ module }`
+      // route owns its module session. None allocates `play-mode.ts`'s
+      // first-party session object, and answering "play did not start" over a
+      // visibly running game is the same fabrication in the other direction.
+      if (!editorHost().live.playing()) {
+        return {
+          ok: false,
+          error:
+            'Play did not start: the run was superseded before it finished booting (a stop, or a ' +
+            'newer play, landed during startup). Nothing is running.',
+        };
+      }
+      // EVERY PLAY RECORDS. There is no flag and no opt-in — see
+      // `play-recording.ts` for why the capability had to stop being one an
+      // agent must remember to switch on. `cmd['record']` only NAMES the file
+      // (`vgai play --record <name>`); its absence names the clip after the
+      // durable Gameplay Session.
+      //
+      // Started here rather than inside `enterPlayMode` on purpose: this
+      // handler is the RELAYED play (`vgai play`, the SDK's `play.start`),
+      // which is exactly the population the recording exists for. A human
+      // clicking the editor's own Play button is their own witness and gets
+      // play unchanged.
+      const record = cmd['record'];
+      const recording = await beginPlayRecording(
+        liveInstanceContainer() ?? editorHost().workspace.liveDocument.container(),
+        {
+          name: typeof record === 'string' ? record : null,
+          audio: getActiveSystems().audio?.acquireRecordingStream?.() ?? null,
+          canvasFrame: captureLiveCanvasFrame,
+          // A hidden tab's game loop is STOPPED (`engine/src/core/game-loop.ts`
+          // never arms rAF while `document.hidden`), so its canvas holds one
+          // frozen frame. This is the still-capture path's own recovery — one
+          // deterministic tick, rendered — applied per recorded frame.
+          refreshFrame: refreshRecordingFrame,
+        },
+      );
+      return { ok: true, ...(recording ? { data: { recording } } : {}) };
+    },
+  },
+  stop: {
+    // `stop` waits on teardown (dispose chain, Rapier world free, renderer
+    // teardown) — routinely past the generic budget under software rendering.
+    timeoutMs: 30_000,
+    derivedRefresh: 'always',
+    handle: async () => {
+      // A video export OWNS the paused run it is stepping, and Stop is the one
+      // command the host prologue lets past its refusal so it can cancel it.
+      gameplayExportAbort?.abort(new Error('Video export cancelled by Stop.'));
+      // Finalize the clip BEFORE the surface it is photographing is torn down:
+      // a WebM is unreadable until its recorder closes it, and compositing
+      // through a teardown truncates the last seconds — which are the ones
+      // someone stopping the run wanted to look at.
+      const capture = await endPlayRecording('stop');
+      exitPlayMode();
+      return { ok: true, ...(capture ? { data: { recording: capture } } : {}) };
+    },
+  },
+  pause: {
+    derivedRefresh: 'always',
+    handle: () => {
+      pausePlayMode();
+      return { ok: true };
+    },
+  },
+  resume: {
+    derivedRefresh: 'always',
+    handle: () => {
+      resumePlayMode();
+      return { ok: true };
+    },
+  },
+  step: {
+    derivedRefresh: 'always',
+    handle: () => {
+      stepPlayMode();
+      return { ok: true };
+    },
+  },
+  // The video export hands control to the GAME (it steps a paused run frame
+  // by frame), so its budget is the game's, not the editor's.
+  'bridge-recording-export': {
+    timeoutMs: 600_000,
+    derivedRefresh: 'none',
+    handle: async (cmd) => {
+      const host = editorHost();
+      if (host.session.playState() !== 'paused')
+        return { ok: false, error: 'Pause the game before exporting video.' };
+      const container = liveInstanceContainer();
+      if (!container) return notPlayingResult();
+      if (gameplayExportAbort) return { ok: false, error: 'A video export is already active.' };
+      const { exportGameplayVideo, validateGameplayExport, assertGameplayVideoSupport } =
+        await import('../src/host/gameplay-export');
+      const exportOptions = {
+        frames: Number(cmd['frames']),
+        fps: cmd['fps'] === undefined ? 30 : Number(cmd['fps']),
+      };
+      try {
+        validateGameplayExport(exportOptions);
+      } catch (error) {
+        return structuredErrorResult(error);
+      }
+      if (gameplayExportAbort) return { ok: false, error: 'A video export is already active.' };
+      const controller = new AbortController();
+      gameplayExportAbort = controller;
+      setGameplayExportActive(true);
+      const deadline = setTimeout(
+        () => controller.abort(new Error('Video export exceeded its ten-minute deadline.')),
+        590_000,
+      );
+      const playStartedAt = host.live.runWindow()?.startedAt ?? null;
+      const unsubscribe = host.session.subscribe(() => {
+        if (
+          host.session.playState() !== 'paused' ||
+          (host.live.runWindow()?.startedAt ?? null) !== playStartedAt
+        ) {
+          controller.abort(new Error('Video export cancelled: the Play session changed.'));
+        }
+      });
+      // The world's own audio for the sim window the frame walk will cover.
+      // `renderOffline` is the fixed-step sibling of the recorder's real-time
+      // `acquireRecordingStream`; a world that does not implement it exports a
+      // genuinely video-only file, said so in the result and in the clip note.
+      const offlineAudio = exportAudioSource();
+      try {
+        await assertGameplayVideoSupport(container);
+        controller.signal.throwIfAborted();
+        const { gameplayRecordingActive } = await import('../src/host/gameplay-recording');
+        if (gameplayRecordingActive()) await stopGameplayRecording();
+        const { blob, ...result } = await exportGameplayVideo(container, exportOptions, {
+          step: () => flushSync(() => stepPlayMode()),
+          assertActive: () => {
+            notePlayActivity();
+            if (
+              host.session.playState() !== 'paused' ||
+              liveInstanceContainer() !== container ||
+              (host.live.runWindow()?.startedAt ?? null) !== playStartedAt
+            ) {
+              throw new Error('Video export interrupted: its game must remain paused and mounted.');
+            }
+          },
+          canvasFrame: captureLiveCanvasFrame,
+          signal: controller.signal,
+          ...(offlineAudio ? { audio: offlineAudio } : {}),
+        });
+        const {
+          beginGameplayRecordingSink,
+          appendGameplayRecordingChunk,
+          finishGameplayRecordingSink,
+          abortGameplayRecordingSink,
+        } = await import('@volter/editor-core/editor-api');
+        controller.signal.throwIfAborted();
+        const sink = await beginGameplayRecordingSink(
+          {
+            startedAt: new Date().toISOString(),
+            mimeType: 'video/webm',
+            purpose: 'export',
+            name: typeof cmd['name'] === 'string' ? cmd['name'] : `export-${Date.now()}`,
+          },
+          controller.signal,
+        );
+        try {
+          for (
+            let offset = 0, sequence = 0;
+            offset < blob.size;
+            offset += 4 * 1024 * 1024, sequence++
+          ) {
+            controller.signal.throwIfAborted();
+            await appendGameplayRecordingChunk(
+              sink,
+              sequence,
+              blob.slice(offset, offset + 4 * 1024 * 1024),
+              controller.signal,
+            );
+          }
+          controller.signal.throwIfAborted();
+          await finishGameplayRecordingSink(
+            sink,
+            result.audio
+              ? `fixed-step export with audio (${result.audio.codec}, ${result.audio.channels}ch @ ${result.audio.sampleRate} Hz)`
+              : 'fixed-step export, video only: this world has no AudioAdapter.renderOffline',
+            controller.signal,
+          );
+          controller.signal.throwIfAborted();
+        } catch (error) {
+          await abortGameplayRecordingSink(sink);
+          throw error;
+        }
+        return { ok: true, data: { ...result, path: sink.path } };
+      } catch (error) {
+        return structuredErrorResult(error);
+      } finally {
+        unsubscribe();
+        clearTimeout(deadline);
+        gameplayExportAbort = null;
+        setGameplayExportActive(false);
+      }
+    },
+  },
+};

package/contributions/profiler.action.ts

@@ -0,0 +1,16 @@
+/**
+ * `Open Profiler` in the command palette — the same reveal as Debug ▸
+ * Profiler, through the action point.
+ */
+import { profilerView } from '../src/host/components/utility-view-state';
+import type { ActionContribution } from '@volter/editor-sdk/chrome';
+
+export const point = 'workspace.action';
+
+export const actions: ActionContribution['actions'] = [
+  {
+    id: 'profiler',
+    label: 'Open Profiler',
+    execute: () => profilerView.open('profiler'),
+  },
+];

package/contributions/profiler.menu.ts

@@ -0,0 +1,22 @@
+/**
+ * Debug ▸ Profiler — the menu item that selects the bench's Profiler view and
+ * reveals the drawer tab this package contributes. The host namespaces every
+ * contributed id under `tool:`, so the utility revealed is
+ * `tool:profiler.utility` (`profilerView.open` names it).
+ */
+import { profilerView } from '../src/host/components/utility-view-state';
+import type { MenuContribution } from '@volter/editor-sdk/chrome';
+
+export const point = 'workspace.menu';
+
+export const menu: MenuContribution = {
+  menu: 'debug',
+  items: [
+    {
+      id: 'profiler',
+      label: 'Profiler',
+      testId: 'menu-profiler',
+      execute: () => profilerView.open('profiler'),
+    },
+  ],
+};

package/contributions/profiler.utility.tsx

@@ -0,0 +1,17 @@
+/**
+ * The Profiler as a drawer tab (W4/W4b): the engine's instrument bench —
+ * frame cost over time (Profiler) and the single-frame draw-call capture
+ * (Frame) over the inspected session's `RenderDebugAdapter` and the active
+ * document's registered render loop. Always on offer: the editor's own
+ * documents register profiler sources in edit mode, and Play supplies the
+ * running game's.
+ */
+import { ProfilerPanel } from '../src/profiler/ProfilerPanel';
+
+export const point = 'workspace.utility';
+export const title = 'Profiler';
+export const order = 20;
+
+export default function ProfilerUtility() {
+  return <ProfilerPanel />;
+}

package/contributions/react/component-board.service.ts

@@ -0,0 +1,21 @@
+/**
+ * THE DOM MEDIUM'S COMPONENT BOARD (`@volter/editor-sdk/services`, a
+ * `workspace.service` contribution): `@volter/editor-game` tells the host's component
+ * board registry that this project's `dom` stories have a `UI` board, when it
+ * exists, and what to say when it does not.
+ *
+ * TRANSCRIBED from `design-time-mount.service.ts` beside it — the same
+ * package, the same point, a sibling registry. The board module is loaded
+ * eagerly rather than behind a dynamic `import()` (which that mount uses)
+ * because `presence()` is asked the moment the host reconciles, not when a
+ * candidate appears: a promise cannot answer a verdict thunk.
+ */
+
+import { registerComponentBoard } from '@volter/editor-core/component-board-registry';
+import { uiComponentBoard } from '../../src/react/ui-component-board';
+
+export const point = 'workspace.service';
+
+export function start(): () => void {
+  return registerComponentBoard(uiComponentBoard);
+}

package/contributions/react/design-time-mount.service.ts

@@ -0,0 +1,60 @@
+/**
+ * THE DOM MEDIUM'S DESIGN-TIME MOUNT (`@volter/editor-sdk/services`, a
+ * `workspace.service` contribution): `@volter/editor-game` tells the host's design-time
+ * mount registry how a `dom` world mounts at design time, and when its
+ * mounted layers go stale.
+ *
+ * It is a `workspace.service` for the same reason the React/DOM Inspector
+ * beside it is: a mount is not a document, so it never opens and never
+ * persists, and what a contribution pass owns is when its registration
+ * exists. Unlike that one the stop is REAL — the registration is the only
+ * thing standing between a `dom` root and the "no package registered a mount
+ * for this medium" disclosure, so a pass that ends must take it back.
+ *
+ * THE MOUNT IS LAZY, and that is transcribed rather than invented: the canvas
+ * medium's mount has been behind a dynamic `import()` since it was written
+ * (so `pixi.js`/`@pixi/react` enter a bundle only for a project that declares
+ * a canvas root), and the same argument holds here — the board's module
+ * reaches the story registry, Storybook's preview API, the React mount
+ * runtime and the React authoring adapter. A project with no `dom` root never
+ * loads any of it, and this contribution module stays a handful of lines in
+ * the build's eager graph.
+ */
+
+import { registerDesignTimeMount } from '@volter/editor-core/authoring/design-time-mount-registry';
+
+export const point = 'workspace.service';
+
+export function start(): () => void {
+  return registerDesignTimeMount({
+    kind: 'dom',
+    owner: '@volter/editor-game/react/design-time-mount',
+    // The `ResolvedAdapter['identity']` a mount failure is reported under —
+    // the literal the host's own catch block used to spell.
+    identity: 'default-react',
+    // Deliberately absent: a dom layer's design-time hover/press testing of
+    // real UI competes with authoring gestures, so it stays behind the `eye`
+    // row's `interactive` toggle. The canvas medium declares the opposite.
+    mount: async (candidate, layer, context) => {
+      const { mountReactDesignLayer } = await import('../../src/react/design-time-react-mount');
+      return mountReactDesignLayer(candidate, layer, context);
+    },
+    reprojectWhen: (invalidate) => {
+      let stopped = false;
+      let stop: (() => void) | null = null;
+      // The hook's own module is the mount's, so binding it eagerly would
+      // load the board's whole graph for a project that has no dom root. The
+      // host only calls this when a dom candidate exists, so loading here is
+      // exactly the right moment.
+      void import('../../src/react/design-time-react-mount').then((module) => {
+        if (stopped) return;
+        stop = module.reprojectWhenStoriesRepublish(invalidate);
+      });
+      return () => {
+        stopped = true;
+        stop?.();
+        stop = null;
+      };
+    },
+  });
+}

package/contributions/react/pasteboard.action.ts

@@ -0,0 +1,41 @@
+/**
+ * "MATERIALIZE PASTEBOARD FROM UI BOARD" in the command palette
+ * (`@volter/editor-sdk/chrome`, a `workspace.action` contribution) — the ONE
+ * action that turns the UI board's derived auto-grid into an authored
+ * pasteboard `.tsx`.
+ *
+ * It was a row in the host's own `action-registry.ts:404-423`, lazily
+ * importing `pasteboard-materialize.ts` — a host action about THIS package's
+ * design-time surface, which is the only thing that kept both files in the
+ * host (WORK.md §The open-source launch item 17). Shape transcribed from
+ * `@volter/editor-game/contributions/profiler.action.ts`: a static `actions` array, no
+ * subscribe, because this action's availability never changes — it either
+ * materializes or it refuses by name.
+ *
+ * THE OUTCOME LANDS IN THE EDITOR CONSOLE EITHER WAY, unchanged from the row
+ * it left: the success sentence names the file (which also opens), a refusal
+ * names its remedy.
+ */
+
+import { editorConsole } from '@volter/editor-core/editor-console';
+import type { ActionContribution } from '@volter/editor-sdk/chrome';
+
+export const point = 'workspace.action';
+
+export const actions: ActionContribution['actions'] = [
+  {
+    id: 'pasteboard.materialize',
+    label: 'Materialize Pasteboard from UI Board',
+    execute: async () => {
+      const { materializePasteboard } = await import('../../src/react/pasteboard-materialize');
+      try {
+        editorConsole.log(`[pasteboard] ${await materializePasteboard()}`, 'authoring');
+      } catch (error) {
+        editorConsole.error(
+          `[pasteboard] materialize refused: ${error instanceof Error ? error.message : String(error)}`,
+          'authoring',
+        );
+      }
+    },
+  },
+];

package/contributions/react/react-inspector.service.ts

@@ -0,0 +1,85 @@
+/**
+ * THE REACT/DOM INSPECTOR (`@volter/editor-sdk/services`, a `workspace.service`
+ * contribution): the rich CSS/layout section that stands in for the shell's
+ * generic property grid on a node owned by a react or DOM adapter — borders,
+ * radii, shadows, gradients, filters, fonts, alignment, the breakpoint strip
+ * and the eyedropper, each descriptor mapped to its widget instead of a text
+ * field.
+ *
+ * ## Why this is a package and not the host's
+ *
+ * It was `packages/editor/src/authoring/react-inspector-section.tsx`,
+ * registered at module scope and reached by ONE line in the host's entry:
+ * `main.tsx:33`, `import './authoring/react-inspector-section';`. A bare
+ * side-effect import has no `from`, so the closure gate's walk never followed
+ * it — and behind it came the whole React/DOM design-time surface, 28 files
+ * and 14,274 lines, into every editor boot, a `models` build that authors no
+ * DOM included. The gate was corrected first (PR #7225) so this cut could be
+ * measured rather than asserted.
+ *
+ * ## Why its own package rather than `@volter/editor-game`
+ *
+ * Because `@volter/editor-game` already imports the surface this section drives from
+ * two unrelated lanes — `src/play/react-play-live-authoring.ts` and the
+ * ingest lane's DOM mount both reach `ReactRootAuthoringAdapter` — and the
+ * planned design skew (a Figma-shaped canvas) wants the same surface and is
+ * not a game. A surface a game editor and a design editor both author lives
+ * in neither.
+ *
+ * ## The seam, which is not a new one
+ *
+ * `@editor/inspector-section-registry` is the host's own registry and has been
+ * "the PERMANENT, sanctioned adapter-module seam" since it was written; the
+ * package REGISTERS, and the host names no lane. The service point is
+ * transcribed from `@volter/editor-game`'s `story-documents.service.ts`, which installs
+ * a story-scoped Inspector section the same way and for the same reason: a
+ * section is not a document, so it never opens and never persists, and what a
+ * contribution pass owns is when its registration exists.
+ *
+ * The `tool.inspector` point was CONSIDERED AND REJECTED with the reason here:
+ * it pins a contributed section to the wrench glyph at
+ * `CONTRIBUTED_SECTION_ORDER + declared`, while this section CLAIMS
+ * `PROPERTIES_SECTION_ID` and composes the node's own property GROUPS in
+ * `GROUP_SECTION_ORDER`. Routing it through that point would have moved the
+ * blocks below every contributed section and left the thin generic grid
+ * showing beside them.
+ *
+ * ## What has NOT moved, and why
+ *
+ * THE ADAPTERS THEMSELVES MOVED HERE on 2026-09-18 (phase 1 unit 12):
+ * `react-world-authoring-adapter.ts` and `dom-authoring-adapter.ts` are
+ * `@volter/editor-game/src/react/` files now. The blocker this docblock used to name —
+ * "`authoring/design-time-layers.ts` CONSTRUCTS the React adapter" — is gone,
+ * because the design-time mount is a REGISTRATION now
+ * (`@editor/authoring/design-time-mount-registry`), so both constructions
+ * moved into this package with `mountReactLayer` and the pair had no host
+ * importer left. `@volter/editor-game`'s play-live authoring and four modules of its
+ * ingest lane import them as `@volter/editor-game/react/…`; that package declares the
+ * dependency.
+ *
+ * Still host files, reached through `@editor/*` — the shape units 4 and 5
+ * landed — and each with the host importer that keeps it there:
+ * the DOM projection and the CSS inspection estate
+ * (`components/RootSelectionOverlay.tsx`); the surgical JSX writer and the
+ * structural write pipe (`authoring/r3f-source-authoring-adapter.ts`,
+ * `@vgai/canvas/pixi-source-write-target.ts`); the breakpoint state
+ * (`components/BoardRulers.tsx`); `authoring/react-story-board.ts`, the
+ * board's geometry, which four host surfaces read
+ * (`components/RootSelectionOverlay.tsx:98`,
+ * `components/ReactCanvasControls.tsx:15`, `pasteboard-materialize.ts:20`,
+ * `canvas-board/CanvasBoardDocument.tsx:57`) because they draw chrome OVER
+ * the board. Each is its own unit with its own seam; none of them is in the
+ * host's EAGER closure, which is what these cuts buy.
+ */
+
+import { ensureReactInspectorSectionRegistered } from '../../src/react/react-inspector-section';
+
+export const point = 'workspace.service';
+
+export function start(): () => void {
+  ensureReactInspectorSectionRegistered();
+  // The stop is a no-op, and that is the same lifetime this had as a host
+  // module: its registration group is HMR-owned, and the section outlives any
+  // one contribution pass. Nothing here holds a resource a pass may end.
+  return () => {};
+}

package/contributions/react/story-documents.service.ts

@@ -0,0 +1,44 @@
+/**
+ * THE ISOLATED STORY DOCUMENT (`@volter/editor-sdk/services`, a
+ * `workspace.service` contribution): the center document a portable CSF story
+ * opens as on the DOM/canvas surface, with its `Story Args` Inspector section
+ * and its `Actions`/`Interactions`/`Accessibility` utilities, plus the
+ * Storybook Docs companion.
+ *
+ * The three-medium turntable is `@volter/editor-game`'s own contribution of the same
+ * name. They were one service while both documents lived in `@volter/editor-game`;
+ * splitting them is what lets a product compose one medium without the other,
+ * and neither registers anything the other needs.
+ *
+ * A SERVICE and not a `workspace.document`: this is not ONE tab the host opens
+ * by contribution id — it is a kind with an unbounded set of documents, one
+ * per (module, story), each carrying its own arg overrides and action log.
+ * What the contribution pass owns is when its registrations exist; the
+ * documents themselves open through their addresses
+ * (`@editor/document-open-registry` for the address,
+ * `@editor/workspace-document-restore` for the persisted state), so the kit
+ * names no module here.
+ *
+ * What stays the KIT's, deliberately: the story REGISTRY and discovery, the
+ * declared medium and the project's story regions, the arg descriptors and the
+ * Content grid's component thumbnail — portable CSF is the kit's design-time
+ * state (ARCHITECTURE-CORE §The target shape), read by the project adapter,
+ * the inspection projection, the coverage families and the Edit tab row.
+ */
+
+import { ensureStoryContributionsRegistered } from '../../src/react/story-documents/story-documents';
+
+export const point = 'workspace.service';
+
+export function start(): () => void {
+  // The module registers its opener and restorer at module scope; this call
+  // installs the story-scoped Inspector section and utilities, which used to
+  // happen at editor boot. It is idempotent and returns nothing; the
+  // registration group it owns is HMR-safe by construction.
+  ensureStoryContributionsRegistered();
+  // The stop is a no-op, and that is the same lifetime this had as a host
+  // module: its registration group is HMR-owned, and an open story document
+  // outlives any one contribution pass. Nothing here holds a resource a pass
+  // may end.
+  return () => {};
+}