@volter/editor-game 0.5.65

package/src/host/react-mount-runtime.ts

@@ -0,0 +1,162 @@
+/**
+ * The react-world mount's OWN react — the sixth realm doorway, finally living
+ * beside its five siblings (`r3f-entry-runtime`, `canvas-entry-runtime`,
+ * `three-ingest-runtime`, `story-dom-runtime`, `story-three-preview-runtime`)
+ * instead of inside the root resolver.
+ *
+ * Every one of those modules answers the same question for its own subject:
+ * *whose copy of this library do we build with?* Under dev the answer
+ * is always the editor's own static imports — one shared Vite instance plus the
+ * root `vite.config.ts`'s `resolve.dedupe` already collapse the editor's and
+ * the project's react onto one instance. Under the PACKAGED runtime the editor
+ * shell is a prebuilt static bundle with its own baked-in `react`/`react-dom`,
+ * disconnected from the separate project-rooted Vite instance the entry
+ * component's hooks resolve `react` through — mounting with the shell's copy
+ * produces two react instances and `useContext` throws on a `null` dispatcher
+ * (confirmed live; see `packaged.ts`'s header).
+ */
+
+import { WorldProvider as EngineWorldProvider } from '@volter/game-runtime/react/world-state';
+import type { Game } from '@volter/game-runtime/runtime/game';
+import {
+  type ComponentType,
+  createElement,
+  useEffect as reactUseEffect,
+  useRef as reactUseRef,
+} from 'react';
+import { flushSync } from 'react-dom';
+import { createRoot } from 'react-dom/client';
+import { REACT_WORLD_RUNTIME_PATH } from '@volter/editor-sdk/host';
+import { isPackagedRuntime } from '@volter/editor-core/packaged-runtime';
+
+/**
+ * The pieces of "react itself" a react-world mount needs:
+ * `createElement`/`createRoot` (to build + render the `<WorldProvider><Entry/>
+ * </WorldProvider>` tree) and the engine-published `WorldProvider`.
+ */
+export interface ReactRootMountRuntime {
+  createElement: typeof createElement;
+  createRoot: typeof createRoot;
+  useEffect: typeof reactUseEffect;
+  useRef: typeof reactUseRef;
+  /** `react-dom`'s synchronous-flush escape hatch — the design-time react
+   *  layer mount needs it from the SAME react-dom peer as `createRoot` above
+   *  (both are entry points of the same installed package). */
+  flushSync: typeof flushSync;
+  engineWorldProvider: ComponentType<{ game: Game; children?: unknown }>;
+}
+
+/** The dev default: this module's own static imports. */
+function staticReactRootMountRuntime(): ReactRootMountRuntime {
+  return {
+    createElement,
+    createRoot,
+    useEffect: reactUseEffect,
+    useRef: reactUseRef,
+    flushSync,
+    engineWorldProvider: EngineWorldProvider as unknown as ComponentType<{
+      game: Game;
+      children?: unknown;
+    }>,
+  };
+}
+
+/**
+ * Import + shape-check the packaged runtime's synthetic
+ * `/__vgai-react-world-runtime` module (`vite-plugin-module-doorways.ts`,
+ * registered only by `packaged.ts`'s project-rooted Vite instance and by
+ * `vitest.config.ts` for test coverage — never by `dev.ts`/the root
+ * `vite.config.ts`). A loud, named failure if the module resolves but is
+ * malformed — never a silent fall-through that would re-introduce the dual-
+ * instance bug it exists to prevent.
+ */
+async function loadPackagedReactRootMountRuntime(): Promise<ReactRootMountRuntime> {
+  const mod = (await import(/* @vite-ignore */ REACT_WORLD_RUNTIME_PATH)) as {
+    createElement?: unknown;
+    createRoot?: unknown;
+    useEffect?: unknown;
+    useRef?: unknown;
+    flushSync?: unknown;
+    EngineWorldProvider?: unknown;
+  };
+  if (
+    typeof mod.createElement !== 'function' ||
+    typeof mod.createRoot !== 'function' ||
+    typeof mod.useEffect !== 'function' ||
+    typeof mod.useRef !== 'function' ||
+    typeof mod.flushSync !== 'function' ||
+    typeof mod.EngineWorldProvider !== 'function'
+  ) {
+    throw new Error(
+      "The packaged runtime's synthetic react-world-runtime module " +
+        `("${REACT_WORLD_RUNTIME_PATH}") did not export createElement/createRoot/useEffect/useRef/flushSync/` +
+        'EngineWorldProvider as functions — see vite-plugin-module-doorways.ts.',
+    );
+  }
+  return {
+    createElement: mod.createElement as typeof createElement,
+    createRoot: mod.createRoot as typeof createRoot,
+    useEffect: mod.useEffect as typeof reactUseEffect,
+    useRef: mod.useRef as typeof reactUseRef,
+    flushSync: mod.flushSync as typeof flushSync,
+    engineWorldProvider: mod.EngineWorldProvider as ComponentType<{
+      game: Game;
+      children?: unknown;
+    }>,
+  };
+}
+
+let cachedPackagedReactRootMountRuntime: Promise<ReactRootMountRuntime> | null = null;
+
+/**
+ * Resolve the react-world mount's own react. A react world is an ISOLATED
+ * `createRoot` (its own DOM subtree / react tree) that does NOT need to share
+ * react with the editor's own UI — it only needs to be internally consistent
+ * (the wrapper + `WorldProvider` + the project's entry component all sharing
+ * ONE react instance), which is exactly what the packaged branch restores.
+ *
+ * Memoized twice over: `isPackagedRuntime()` is itself session-memoized, and
+ * the packaged module load is cached here, so this performs at most one
+ * `/__editor/project` fetch and one dynamic import per editor session however
+ * many react roots mount.
+ */
+export async function resolveReactRootMountRuntime(): Promise<ReactRootMountRuntime> {
+  const packaged = await isPackagedRuntime();
+  if (!packaged) return staticReactRootMountRuntime();
+  if (!cachedPackagedReactRootMountRuntime) {
+    cachedPackagedReactRootMountRuntime = loadPackagedReactRootMountRuntime();
+  }
+  return cachedPackagedReactRootMountRuntime;
+}
+
+/**
+ * `WorldProvider` is the canonical engine export from
+ * `@volter/game-runtime/react/world-state`, reached through the mount runtime above so
+ * the project's copy is used under the packaged runtime. Hosts and game
+ * entries therefore share ONE module and one React context identity.
+ *
+ * WHY THIS IS AN ENGINE EXPORT AND NOT A PER-PROJECT FILE — a finding verified
+ * empirically, kept because the trap it describes is still live for anyone
+ * tempted to reintroduce a project-local provider. Back when each project
+ * owned its own bridge module, a hand-built runtime `import('/@fs/' +
+ * projectRoot + '/…')` for it did NOT reliably land on the same module
+ * instance a react-world entry's own STATIC relative import resolved to:
+ * Vite's dev server treated the two differently at the HTTP level (a
+ * query-string divergence, confirmed by logging `import.meta.url` inside two
+ * otherwise-identical fetches) even though both targeted the identical file on
+ * disk, and browser ES module identity is keyed by the exact request URL. That
+ * alone produced TWO separate `createContext()` calls. The whole apparatus is
+ * gone: one engine module, no per-project path to diverge on.
+ */
+export async function resolveWorldProviderForProject(): Promise<
+  ComponentType<{ game: Game; children?: unknown }>
+> {
+  const runtime = await resolveReactRootMountRuntime();
+  return runtime.engineWorldProvider;
+}
+
+/** Test-only: reset the packaged react-world mount runtime cache between
+ *  tests that toggle `isPackagedRuntime()`'s own (separately memoized) result. */
+export function resetReactRootMountRuntimeCacheForTest(): void {
+  cachedPackagedReactRootMountRuntime = null;
+}

package/src/host/realm-services.ts

@@ -0,0 +1,148 @@
+/**
+ * THE REALM — where this editor session's project modules come from, as ONE
+ * value instead of a three-way branch repeated in every root resolver.
+ *
+ * ## The fork this closes
+ *
+ * `resolveDefaultThreeAdapter`, `resolveDefaultCanvasAdapter` and
+ * `resolveReactAdapterRootComponent` each carried their OWN copy of the same
+ * question, and the copies had already drifted. There is one dispatch now, and
+ * it is {@link RealmServices.loadEntryModule}.
+ *
+ * ## ONE LOADING LANE, TWO RUNTIMES
+ *
+ * A project module is fetched ONE way — `/@fs/` through the session's own dev
+ * server — because the session IS the editor's host. What varies is the
+ * RUNTIME: whose copy of react/fiber/pixi/three the mount builds with, the
+ * editor SHELL's or the PROJECT's own module graph.
+ *
+ *   dev      = fs × shell
+ *   packaged = fs × project graph
+ *
+ * ## What is here, and what is deliberately NOT
+ *
+ * The RUNTIME axis is already single-owner per subject — `r3f-entry-runtime`,
+ * `canvas-entry-runtime`, `react-mount-runtime`, `three-ingest-runtime` each
+ * decide it once, for everyone, from `isPackagedRuntime()`. This module names
+ * the ones root binding actually opens so a resolver asks the realm rather
+ * than importing four doorways by hand; it does not re-implement them, and it
+ * does not list the two STORY doorways (`story-dom-runtime`,
+ * `story-three-preview-runtime`) — their consumers are story/preview surfaces,
+ * not root binding, so a member here would have no caller.
+ *
+ * Ingest's served-bundle-vs-`/@fs/` choice is likewise NOT here: it is a
+ * per-PROJECT property (how that one game was vendored), so two ingested games
+ * open in the same realm can answer differently. It lives with the ingest code
+ * (`ingest/resolve-three.ts`).
+ *
+ * ## Reject, never guess
+ *
+ * Construction AWAITS `isPackagedRuntime()`, so a probe that could not get an
+ * answer REJECTS through this function to the mount site. Nothing here spends
+ * "I don't know" as "dev" — see `packaged-runtime.ts`'s header for the
+ * measured session-long mis-mount that latch caused.
+ */
+
+import {
+  type EntrypointSelectionOverride,
+  type ProjectMountEpoch,
+  projectEntryImportUrl,
+} from '@volter/editor-sdk/session/project-module-url';
+import type { AdapterSurface } from '@volter/editor-project/adapter/adapter-surface';
+import { resolveCanvasEntryAdapterForEditor } from './canvas-entry-runtime';
+import { isPackagedRuntime } from '@volter/editor-core/packaged-runtime';
+import { type ReactRootMountRuntime, resolveReactRootMountRuntime } from './react-mount-runtime';
+import {
+  resolveThreeIngestRuntimeForEditor,
+  type ThreeIngestRuntime,
+} from './three-ingest-runtime';
+
+/** Which of the two this session is in. Reported, never inferred twice. */
+export type RealmId = 'dev' | 'packaged';
+
+/**
+ * The realm's services, bound to ONE project root and ONE mount epoch — a
+ * realm value is "how THIS project's modules are reached in THIS mount
+ * generation", which is why it is constructed per resolve rather than being a
+ * module-level singleton.
+ */
+export interface RealmServices {
+  readonly id: RealmId;
+  /** The project this realm was constructed for. */
+  readonly projectRoot: string;
+  /** The mount generation every module url of this composition shares. */
+  readonly epoch: ProjectMountEpoch;
+  /**
+   * Import one root's entry module.
+   *
+   * `rootId` and `surface` identify the root for the caller's own errors;
+   * dispatch is the entry PATH. `selectionOverride` is the dev server's
+   * entrypoint swap slot, rewritten at serve time.
+   */
+  loadEntryModule(
+    entry: string,
+    rootId: string,
+    surface: AdapterSurface,
+    selectionOverride?: EntrypointSelectionOverride | undefined,
+  ): Promise<Record<string, unknown>>;
+  /** The entry namespace this realm hands back is the module's WHOLE
+   *  namespace — the honest input to `RootDeclaration.entry`'s `reach`
+   *  discriminant, which kept a second value while a bundle-map lane
+   *  existed. */
+  readonly entryReach: 'full';
+  /** The canvas doorway: turn a canvas entry namespace into its adapter. */
+  readonly pixiRuntime: typeof resolveCanvasEntryAdapterForEditor;
+  /** The react-world mount's own react/react-dom/WorldProvider. */
+  readonly reactDomRuntime: () => Promise<ReactRootMountRuntime>;
+  /** The three-ingest doorway: the namespace an ingested three game captures
+   *  against. */
+  readonly threeIngestRuntime: () => Promise<ThreeIngestRuntime>;
+}
+
+const SHARED_RUNTIMES = {
+  pixiRuntime: resolveCanvasEntryAdapterForEditor,
+  reactDomRuntime: resolveReactRootMountRuntime,
+  threeIngestRuntime: resolveThreeIngestRuntimeForEditor,
+} as const;
+
+/**
+ * dev AND packaged: `/@fs/` through the dev server, always with the mount
+ * epoch's cache-buster (`projectEntryImportUrl` — never a bare url; a
+ * byte-identical specifier is served out of the browser's module registry on
+ * remount while its cache-busted siblings are re-transformed, leaving two live
+ * copies of one module-level `let` and no error).
+ */
+function fsLoader(projectRoot: string, epoch: ProjectMountEpoch) {
+  return async (
+    entry: string,
+    _rootId: string,
+    _surface: AdapterSurface,
+    selectionOverride?: EntrypointSelectionOverride | undefined,
+  ): Promise<Record<string, unknown>> =>
+    (await import(
+      /* @vite-ignore */ projectEntryImportUrl(projectRoot, entry, epoch, selectionOverride)
+    )) as Record<string, unknown>;
+}
+
+/**
+ * Construct this session's realm for one project and one mount epoch.
+ *
+ * REJECTS rather than guessing when `isPackagedRuntime()` could not get an
+ * answer — see this module's header.
+ */
+export async function activeRealmServices(
+  projectRoot: string,
+  epoch: ProjectMountEpoch,
+): Promise<RealmServices> {
+  // The LOADING axis is `/@fs/` either way; only the runtime doorways differ,
+  // and each of those decides for itself from the same probe.
+  const packaged = await isPackagedRuntime();
+  return {
+    id: packaged ? 'packaged' : 'dev',
+    projectRoot,
+    epoch,
+    loadEntryModule: fsLoader(projectRoot, epoch),
+    entryReach: 'full',
+    ...SHARED_RUNTIMES,
+  };
+}

package/src/host/recording-preview.ts

@@ -0,0 +1,106 @@
+/** Two-Hz filmstrip encoding. HTMLCanvasElement.toBlob can synchronously flush
+ * GPU work before returning; keeping only its callback async does not protect
+ * the game loop. Transfer an ImageBitmap; draw/downscale and encode in a worker.
+ * One pending image bounds memory. Stop settles it and closes every owned bitmap.
+ * Unsupported workers/canvases report a preview error; never silently fall back
+ * to blocking the main thread. The video recorder can continue without previews.
+ */
+export function createRecordingPreviewEncoder() {
+  let worker: Worker | null = null;
+  let stopped = false;
+  let pending: { resolve: (blob: Blob) => void; reject: (error: Error) => void } | null = null;
+  const source = `
+    let canvas;
+    onmessage = async ({data}) => {
+      const {bitmap, width, height, type, quality} = data;
+      try {
+        if (!canvas) canvas = new OffscreenCanvas(width, height);
+        if (canvas.width !== width) canvas.width = width;
+        if (canvas.height !== height) canvas.height = height;
+        const context = canvas.getContext('2d');
+        if (!context) throw new Error('No worker canvas context');
+        context.globalCompositeOperation = 'copy';
+        context.drawImage(bitmap, 0, 0, width, height);
+        bitmap.close();
+        const blob = await canvas.convertToBlob({type, quality});
+        postMessage({blob});
+      } catch (error) {
+        bitmap.close();
+        postMessage({error: error instanceof Error ? error.message : String(error)});
+      }
+    };
+  `;
+  function fail(error: Error) {
+    const job = pending;
+    pending = null;
+    worker?.terminate();
+    worker = null;
+    job?.reject(error);
+  }
+  return {
+    encode(
+      canvas: HTMLCanvasElement,
+      width: number,
+      height: number,
+      type: string,
+      quality: number,
+    ): Promise<Blob> {
+      if (stopped) return Promise.reject(new Error('Recording preview encoder stopped'));
+      if (pending) return Promise.reject(new Error('Recording preview already in flight'));
+      return new Promise<Blob>((resolve, reject) => {
+        const job = { resolve, reject };
+        pending = job;
+        try {
+          if (!worker) {
+            const url = URL.createObjectURL(new Blob([source], { type: 'text/javascript' }));
+            try {
+              worker = new Worker(url);
+            } finally {
+              URL.revokeObjectURL(url);
+            }
+            worker.onmessage = ({ data }: MessageEvent<{ blob?: Blob; error?: string }>) => {
+              if (data.error || !data.blob) {
+                fail(new Error(data.error ?? 'No recording preview image'));
+                return;
+              }
+              const job = pending;
+              pending = null;
+              job?.resolve(data.blob);
+            };
+            worker.onerror = (event) => {
+              event.preventDefault();
+              fail(new Error(event.message || 'Recording preview worker failed'));
+            };
+            worker.onmessageerror = () =>
+              fail(new Error('Recording preview worker message failed'));
+          }
+          // Snapshot cost belongs in the main-thread profile too. Do not replace
+          // this with toDataURL/getImageData: those force synchronous readback.
+          createImageBitmap(canvas).then(
+            (bitmap) => {
+              if (stopped || pending !== job || !worker) {
+                bitmap.close();
+                return;
+              }
+              try {
+                worker.postMessage({ bitmap, width, height, type, quality }, [bitmap]);
+              } catch (error) {
+                bitmap.close();
+                fail(error instanceof Error ? error : new Error(String(error)));
+              }
+            },
+            (error) => {
+              if (pending === job) fail(error instanceof Error ? error : new Error(String(error)));
+            },
+          );
+        } catch (error) {
+          fail(error instanceof Error ? error : new Error(String(error)));
+        }
+      });
+    },
+    dispose() {
+      stopped = true;
+      fail(new Error('Recording preview encoder stopped'));
+    },
+  };
+}

package/src/host/roots/module-root.ts

@@ -0,0 +1,203 @@
+/**
+ * A `{ module }` root: the project's OWN adapter module is the mechanism.
+ *
+ * The editor imports the game folder's declared module (path-guarded before,
+ * shape-checked after — both loud, named failures, never a silent `undefined`
+ * or a crash deep inside `mount`), then wraps its `mount` so that what the
+ * editor actually REACHES is measured off the real mounted surface and every
+ * capability short of a native root's is warned about by name.
+ */
+
+import {
+  type ProjectMountEpoch,
+  projectEntryImportUrl,
+} from '@volter/editor-sdk/session/project-module-url';
+import { relativePathRejection } from '@volter/editor-sdk/session/relative-path-guard';
+import type { RootAdapter, SurfaceAdapter } from '@volter/editor-project/adapter';
+import type { AdapterSurface } from '@volter/editor-project/adapter/adapter-surface';
+import { assertNever } from '@volter/editor-project/adapter/adapter-surface';
+import type { HostContextFor } from '@volter/editor-project/adapter/host-context';
+import type { MountedRootFor } from '@volter/editor-project/adapter/root-adapter';
+import type { ResolvedAdapterRoot } from '@volter/editor-project/manifest/load';
+import { formatCapabilityWarning, measureAdapterReach } from '../adapter-reach';
+
+/**
+ * Validate `adapter.module` is a game-folder-RELATIVE path with no `..`
+ * escape. The rule itself is `relative-path-guard.ts`'s
+ * `relativePathRejection` — the ONE spelling every trust boundary in the
+ * editor shares. Only the MESSAGES are local: a manifest author needs to be
+ * told which declaration is wrong.
+ *
+ * Returns the normalized (slash-joined, no leading/trailing slash) path — the
+ * one thing the shared predicate does not do, because normalization is not a
+ * trust decision.
+ */
+export function guardModulePath(world: ResolvedAdapterRoot, moduleId: string): string {
+  const fail = (reason: string): never => {
+    throw new Error(
+      `resolveRootBinding: world "${world.id}" declares { module: "${moduleId}" } — ${reason} ` +
+        '(the module path must be game-folder-relative, normalized, with no `..` escape).',
+    );
+  };
+
+  const rejection = relativePathRejection(moduleId);
+  if (rejection === 'empty') fail('the module path is empty');
+  if (rejection === 'nul') fail('the module path contains a NUL byte');
+  if (rejection === 'absolute') fail('the module path is absolute, not game-folder-relative');
+  if (rejection === 'traversal') {
+    fail('the module path contains a `..` segment and would escape the game folder');
+  }
+  // POSIX-only beyond the shared rule: a module id reaches Vite as a URL.
+  if (moduleId.includes('\\')) fail('the module path contains a backslash (not POSIX-relative)');
+
+  const normalized = moduleId
+    .split('/')
+    .filter((seg) => seg.length > 0 && seg !== '.')
+    .join('/');
+  if (normalized === '') fail('the module path resolves to nothing (empty after normalization)');
+
+  return normalized;
+}
+
+/**
+ * Runtime shape every `RootAdapter` must satisfy — the module branch cannot
+ * trust TypeScript alone (the imported value is `unknown` until checked).
+ *
+ * Parameterized by surface: the checked SHAPE is surface-independent
+ * (`{ id, mount }` are the same members for every `K`), so the caller passes
+ * the world's DECLARED surface and gets a `RootAdapter<K>` back. The surface
+ * itself is a manifest CLAIM no structural check can verify — that is exactly
+ * what {@link withCapabilityWarning} measures post-mount, against the real
+ * mounted root, and what `module-mode.ts` re-checks against the mounted
+ * result's own `kind` tag.
+ */
+function guardModuleShape<K extends AdapterSurface>(
+  world: ResolvedAdapterRoot,
+  moduleId: string,
+  candidate: unknown,
+): asserts candidate is RootAdapter<K> {
+  const fail = (reason: string): never => {
+    throw new Error(
+      `resolveRootBinding: world "${world.id}"'s custom adapter module "${moduleId}" ${reason} ` +
+        '— a { module } adapter must default-export an object shaped like `RootAdapter`: ' +
+        '`{ id: string, mount(host): Promise<MountedThreeRoot> }`.',
+    );
+  };
+
+  if (candidate === null || typeof candidate !== 'object') {
+    fail('has no default export (or it is not an object)');
+  }
+  const obj = candidate as Record<string, unknown>;
+  if (typeof obj['id'] !== 'string' || obj['id'].length === 0) {
+    fail('default-exports an object with no non-empty string `id`');
+  }
+  if (typeof obj['mount'] !== 'function') {
+    fail('default-exports an object with no `mount` function');
+  }
+}
+
+/** How a `{ module }` world reaches the editor: the project's own adapter
+ *  module IS the mechanism, so anything missing is missing from that module. */
+const MODULE_ADAPTER_MECHANISM =
+  'this world mounts through the project’s own adapter module, so every capability the editor ' +
+  'has here is one that module hands it';
+
+/**
+ * Wrap a custom adapter's `mount` so that, once it resolves, what the editor
+ * actually REACHES is measured off the real mounted surface. There is nothing
+ * to compare against and nothing to declare: the bar is a native root, and a
+ * gap keeps warning until it is closed. The warning never blocks the mount.
+ *
+ * The `editorConsole.warn(...)` call is a LAZY dynamic import: this resolver is
+ * imported by headless Node/vitest suites with no `window`, and
+ * `editor-console.ts`'s module top level touches `window` unconditionally.
+ */
+function withCapabilityWarning<K extends AdapterSurface>(
+  world: ResolvedAdapterRoot,
+  adapter: RootAdapter<K>,
+): RootAdapter<K> {
+  return {
+    id: adapter.id,
+    async mount(host: HostContextFor<K>): Promise<MountedRootFor<K>> {
+      const mounted = await adapter.mount(host);
+      const warning = formatCapabilityWarning(
+        world.id,
+        measureAdapterReach(mounted),
+        MODULE_ADAPTER_MECHANISM,
+        // The MOUNT's own surface, so a provider this surface cannot have (a
+        // DOM root's 3D `transforms`) is not warned about forever. Read off
+        // `mounted`, not `world`, for the same reason the reach beside it is:
+        // this is what actually mounted, not what was declared.
+        mounted.kind,
+      );
+      if (warning) {
+        const { editorConsole } = await import('@volter/editor-core/editor-console');
+        editorConsole.warn(warning, 'adapter');
+      }
+      return mounted;
+    },
+  };
+}
+
+/**
+ * Resolve a `{ module }` adapter world: import the game folder's declared
+ * module through the same project-import route every other root entry takes
+ * (so it inherits the root `vite.config.ts`'s `resolve.dedupe: ['three',
+ * 'pixi.js']` collapse), guard it, and tag it with the manifest's declared
+ * surface.
+ *
+ * The module is imported through `projectEntryImportUrl` (`/@fs/`, mount-epoch
+ * cache-busted), like every other project module.
+ *
+ * Returns the module's own namespace beside the tagged adapter: for a
+ * `{ module }` root THAT namespace is the root's static surface — the project
+ * declared this module as the root's mechanism — and it becomes the
+ * declaration's `entry` (see `binding-resolver.ts`).
+ */
+export async function resolveModuleAdapter(
+  world: ResolvedAdapterRoot,
+  projectRoot: string,
+  epoch: ProjectMountEpoch,
+): Promise<{ readonly resolved: SurfaceAdapter; readonly module: Record<string, unknown> }> {
+  const { adapter } = world;
+  if (adapter.type !== 'module') {
+    throw new Error(`resolveModuleAdapter: world "${world.id}" is not a { module } world.`);
+  }
+
+  const normalizedPath = guardModulePath(world, adapter.module);
+  // A `{ module }` root is project-owned code that can share modules with its
+  // sibling roots, so it takes the same mount epoch they do.
+  const modulePath = projectEntryImportUrl(projectRoot, normalizedPath, epoch);
+  const mod = (await import(/* @vite-ignore */ modulePath)) as Record<string, unknown>;
+  const candidate = mod['default'];
+
+  // The manifest's declared surface is the discriminant, so each branch names
+  // the module's adapter at ITS OWN surface — `guardModuleShape<K>` performs
+  // the identical runtime check in all three, and the result is paired with
+  // the tag rather than flattened through a three-shaped channel.
+  switch (world.surface) {
+    case 'three': {
+      guardModuleShape<'three'>(world, adapter.module, candidate);
+      return {
+        resolved: { surface: 'three', adapter: withCapabilityWarning(world, candidate) },
+        module: mod,
+      };
+    }
+    case 'canvas': {
+      guardModuleShape<'canvas'>(world, adapter.module, candidate);
+      return {
+        resolved: { surface: 'canvas', adapter: withCapabilityWarning(world, candidate) },
+        module: mod,
+      };
+    }
+    case 'dom': {
+      guardModuleShape<'dom'>(world, adapter.module, candidate);
+      return {
+        resolved: { surface: 'dom', adapter: withCapabilityWarning(world, candidate) },
+        module: mod,
+      };
+    }
+    default:
+      return assertNever(world.surface, 'resolveModuleAdapter');
+  }
+}