@volter/editor-game 0.5.65

package/src/ingest/mount-coverage.ts

@@ -0,0 +1,296 @@
+/**
+ * THE INSTRUMENT: what a mount MEASURED about itself, assembled from the live
+ * session slot and handed to the pure derivation in `coverage/capability-coverage.ts`.
+ *
+ * Everything here is a measurement or the plumbing of one — the mount-time
+ * one-shot probe (the editor capabilities reached),
+ * the live re-read of the loop verdict, the once-per-mount
+ * console door, and the report the status facet and the `__vgaiIngest` hook
+ * both serve. Mount PLUMBING lives in the `mount-*-ingest-root.ts` siblings
+ * and deliberately not here: a reader asking "what did the editor actually
+ * measure about this game, and where does that number come from" should have
+ * exactly this file open.
+ */
+
+import type { AdapterReach } from '../host/adapter-reach';
+import { getActiveSystems } from '@volter/editor-core/authoring/active-systems';
+import { ingestDataWriterNow } from '../host/authoring/ingest-data-writer';
+import { ingestOwnershipNow } from '../host/authoring/ingest-source-persistence';
+import {
+  type CapabilityCoverageReport,
+  createCapabilityCoverageConsole,
+  type DataWriterFacts,
+  deriveCapabilityCoverage,
+  measureGameContract,
+  SYSTEM_ADAPTER_SLOTS,
+  type SystemAdapterMeasurement,
+  type WriteReachFacts,
+} from '../host/coverage/capability-coverage';
+import { inspectSystemAdapterSeam } from '@volter/editor-core/coverage/system-seam-evidence';
+import { editorConsole } from '@volter/editor-core/editor-console';
+import {
+  type MeasuredLoop,
+  measuredLoop,
+  type SameRealmLoopVerdict,
+} from '../host/same-realm-loop-gate';
+import {
+  type ContractSurface,
+  projectContractSystemAdapters,
+} from '@volter/game-runtime/adapter/ingest/contract-system-adapters';
+import type { VgaiGameContract } from '@volter/editor-project/adapter/ingest/game-contract';
+import type { SystemAdapters } from '@volter/editor-project/adapter/system-adapter';
+import { activeIngest } from './active-ingest';
+import type { IngestMount } from './authoring/ingest-root-adapter';
+import { activeIngestContract } from './ingest-play-control';
+
+/**
+ * The half of {@link deriveCapabilityCoverage}'s facts that is a property of THIS
+ * mount and cannot be re-read later: the editor capabilities this mount
+ * reached, with the mechanism that reached them. Everything else the
+ * coverage report needs (the loop verdict, the declared
+ * contract — its systems surface included — and the ownership answer) is read
+ * live at report time, because all of them move after the mount and a frozen
+ * copy would start lying.
+ */
+export interface MountCoverageInputs {
+  readonly reach: AdapterReach | null;
+  /** How this mount reached the game's runtime, in the mount's own words,
+   *  carried into the warning a missing capability prints. */
+  readonly reachMechanism: string | null;
+  /** Read on demand because a loop verdict may arrive only after the first
+   *  pause probe. Every surface supplies its own real control verdict, and a
+   *  route with no gate at all supplies the reason there will never be one. */
+  readonly loop: () => { loop: MeasuredLoop | null; reason: string | null };
+  /**
+   * How much of the mounted world an edit can actually be written back to, read
+   * LIVE for the same reason the loop verdict is: a world keeps streaming
+   * objects in, and a count frozen at first capture would start lying.
+   *
+   * ABSENT ⇒ this route has no three authoring adapter to ask (a DOM or
+   * canvas ingest), and the persistence row says only what ownership answered —
+   * never a reach claim nobody measured.
+   */
+  readonly writeReach?: (() => WriteReachFacts) | undefined;
+}
+
+/**
+ * The console door for the coverage report (`coverage/capability-coverage.ts`) —
+ * gaps as one warning block, the rest as one info block, ONCE per mount.
+ */
+const _coverageConsole = createCapabilityCoverageConsole((block) => {
+  if (block.level === 'warn') editorConsole.warn(block.message, 'ingest');
+  else editorConsole.log(block.message, 'ingest');
+});
+
+/** Distinguishes consecutive mounts of the SAME world for the console door's
+ *  once-per-mount guard — remounting a game is a new answer, not a repeat. */
+let _mountSeq = 0;
+let _mountToken = '';
+
+/** Open a new coverage answer for `sessionId`: a new mount is a new report even
+ *  for the same world, and the console door's once-guard keys on this token. */
+export function beginMountCoverage(sessionId: string): void {
+  _mountToken = `${sessionId}#${++_mountSeq}`;
+}
+
+/**
+ * The loop facts for a three-route mount, read live.
+ *
+ * A verdict is a MEASUREMENT, produced by the gate's own probe at the first
+ * pause — and it travels WITH the evidence it was concluded from
+ * ({@link MeasuredLoop}), which is what keeps it distinguishable from the
+ * manifest's declared intent word. Where the mount installed no gate at all the
+ * honest answer is "no verdict will ever be measured here", never the
+ * pending-probe sentence, which promises a measurement that does not come.
+ */
+export function threeMountLoopFacts(mount: IngestMount): {
+  loop: MeasuredLoop | null;
+  reason: string | null;
+} {
+  const loop = measuredLoop(mount.realmLoopVerdict?.());
+  const reason = mount.realmLoopVerdict?.()?.reason ?? null;
+  if (loop !== null || reason !== null) return { loop, reason };
+  if (mount.realmLoopVerdict) return { loop: null, reason: null };
+  return { loop: null, reason: LOOP_PROBE_ABSENT };
+}
+
+/**
+ * The loop facts for a native-React (`dom`) mount — its SIBLING to
+ * {@link threeMountLoopFacts}, and the reason it exists as a named function
+ * rather than a literal at the mount site.
+ *
+ * This route used to assert `loop: 'gated'` outright, on the strength of the
+ * sentence below. That sentence is true and it is still printed, but it
+ * describes a MECHANISM, not a measurement of one: no probe on this route has
+ * ever held this game's scheduling and watched whether anything ran anyway
+ * (`ingest/same-realm-loop-gate.ts`'s `verifySameRealmLoopControl` is the only
+ * thing that can answer that, and nothing calls it here). The word it emitted
+ * was the manifest's DECLARED intent vocabulary wearing a measurement's
+ * clothes, so the coverage report printed `loop ✓ gated` about every
+ * native-React ingest — including one whose own `setInterval` the host's play
+ * pause never touches.
+ *
+ * Same shape and same reason as `mount-canvas-ingest-root.ts`'s two branches,
+ * which reach the identical conclusion about their own unprobed controls.
+ */
+export function domMountLoopFacts(): { loop: null; reason: string } {
+  return {
+    loop: null,
+    reason:
+      "⏸ calls the host runtime's own play pause on this route, but no probe has measured " +
+      "whether that reaches this game's frames — an unmodified React game that schedules its " +
+      'own timers is not held by the host loop',
+  };
+}
+
+/** What a mount with no loop gate at all can honestly say about its frames. */
+export const LOOP_PROBE_ABSENT =
+  'this mount installs no loop gate, so no verdict will ever be measured here — nothing in ' +
+  "the editor holds this game's frames";
+
+/**
+ * The terminal state of every `SystemAdapters` slot for a live mount.
+ *
+ * TWO independent sources, deliberately: `bound` is read off the editor's own
+ * live registry (the very object its panels call, so a slot that "registered"
+ * but never reached the registry reports honestly), while `empty`/`malformed`
+ * come from the game's declared carrier. Nothing consults the route or the
+ * game's id, and no slot is bound and empty at once — a bound adapter wins,
+ * because the registry is the stronger measurement.
+ *
+ * Exported and pure over its inputs so the whole table is unit-testable with no
+ * browser and no live session.
+ */
+export function measureSystemAdapters(
+  active: SystemAdapters,
+  contract: VgaiGameContract | null,
+  /** The mount's surface when the caller has one — see
+   *  `contract-system-adapters.ts`'s header for the one slot it decides
+   *  (`physics`, whose vocabulary follows the surface). */
+  surface?: ContractSurface | undefined,
+): readonly SystemAdapterMeasurement[] {
+  const projection = projectContractSystemAdapters(contract?.systems, surface);
+  const empty = new Map(projection.empty.map((e) => [e.slot as string, e.evidence]));
+  const malformed = new Map(projection.malformed.map((m) => [m.slot as string, m.reason]));
+  return SYSTEM_ADAPTER_SLOTS.map((slot): SystemAdapterMeasurement => {
+    if (active[slot] != null) {
+      return {
+        slot,
+        state: 'bound',
+        proof: inspectSystemAdapterSeam({
+          slot,
+          adapter: active[slot] as NonNullable<SystemAdapters[typeof slot]>,
+          subject: 'game',
+        }),
+      };
+    }
+    const evidence = empty.get(slot);
+    if (evidence !== undefined) return { slot, state: 'empty', evidence };
+    const reason = malformed.get(slot);
+    if (reason !== undefined) return { slot, state: 'malformed', evidence: reason };
+    return { slot, state: 'unanswered' };
+  });
+}
+
+/**
+ * THE coverage report for the live mount — re-derived on every read (see
+ * {@link MountCoverageInputs} for what is frozen at mount and what is not).
+ * `null` when nothing is mounted, or when the mounted route recorded no
+ * coverage inputs: not measured is its own answer, never a clean one.
+ *
+ * The contract comes from `activeIngestContract` — the same read
+ * `getIngestPlayControl` acts on, so a game that declared its contract
+ * somewhere the host cannot see reports the same gap the editor actually has,
+ * and one that declared it through a host-added contract shim beside the game
+ * gets credit for exactly what the play control can use.
+ */
+/**
+ * The declared data writer's state, in the coverage vocabulary. `absent` — the
+ * common case — is `null`, not a gap: a game with no data file to write is not
+ * missing anything.
+ */
+function dataWriterFacts(): DataWriterFacts | null {
+  const state = ingestDataWriterNow();
+  switch (state.state) {
+    case 'absent':
+      return null;
+    case 'loading':
+      return { state: 'loading' };
+    case 'ready':
+      return { state: 'ready', dataFile: state.writer.dataFile };
+    default:
+      return { state: 'failed', reason: state.reason };
+  }
+}
+
+export function ingestCoverageReport(): CapabilityCoverageReport | null {
+  const active = activeIngest();
+  const inputs = active?.coverage;
+  if (!active || !inputs) return null;
+  const ownership = ingestOwnershipNow();
+  const loop = inputs.loop();
+  const contract = activeIngestContract();
+  return deriveCapabilityCoverage({
+    worldId: active.worldId,
+    reach: inputs.reach,
+    // The session's own render substrate IS the surface kind the coverage
+    // derivation needs (`IngestKind` and `AdapterSurface` are the same three
+    // words by construction), so nothing has to be declared twice.
+    surface: active.kind,
+    reachMechanism: inputs.reachMechanism,
+    loop: loop.loop,
+    loopReason: loop.reason,
+    contract: measureGameContract(contract),
+    // `active.kind` IS the surface (`IngestKind` and `ContractSurface` are the
+    // same three words by construction), so the physics slot's keying is
+    // checked against the surface this mount actually is.
+    systemAdapters: measureSystemAdapters(getActiveSystems(), contract, active.kind),
+    ownership: ownership
+      ? {
+          writable: ownership.writable,
+          reason: ownership.reason ?? null,
+          recorder: ownership.recorder ?? null,
+        }
+      : null,
+    dataWriter: dataWriterFacts(),
+    // The `project.*` family is about the opened PROJECT, not this mount, and
+    // it has one producer for both lanes (`@volter/editor-game/coverage/live-project-verbs.ts`).
+    // Reporting it here too would print two verdicts for one capability.
+    projectVerbs: [],
+    writeReach: inputs.writeReach?.() ?? null,
+  });
+}
+
+/**
+ * Record this mount's frozen coverage inputs and say the result out loud, once.
+ *
+ * Called from every mount path right after the session is published, so the
+ * report describes a mount that exists.
+ */
+export function recordMountCoverage(inputs: MountCoverageInputs): void {
+  const active = activeIngest();
+  if (!active) return;
+  active.coverage = inputs;
+  const report = ingestCoverageReport();
+  if (report) _coverageConsole.report(_mountToken, report);
+}
+
+/**
+ * Report the MEASURED loop verdict for a three ingest mount (honesty
+ * gate, ARCHITECTURE-CORE §Editor).
+ *
+ * `loop` is a claim about whether anything in this editor actually controls the
+ * game's frames, so it is only ever printed from the gate's own probe
+ * (`ingest/same-realm-loop-gate.ts`) — never inferred from the manifest. A
+ * route that does no gating at all passes `undefined` and this says nothing,
+ * which is also honest.
+ */
+export function reportMeasuredLoop(
+  worldId: string,
+  verdict: SameRealmLoopVerdict | undefined,
+): void {
+  if (!verdict) return;
+  const line = `Ingest "${worldId}" loop: ${verdict.loop} — ${verdict.reason}`;
+  if (verdict.loop === 'gated') editorConsole.log(line, 'ingest');
+  else editorConsole.warn(line, 'adapter');
+}

package/src/ingest/mount-dom-ingest-root.ts

@@ -0,0 +1,282 @@
+/**
+ * Mount a `{ ingest }` root on the DOM surface — an unmodified native-React
+ * game, mounted through the EXACT SAME react-world host stack `default-react`/
+ * multi-world react roots use, NOT the capture-based three/canvas bridge (there
+ * is no scene to capture; the mounted tree IS React, D-N1).
+ */
+
+import { measureAdapterReach } from '../host/adapter-reach';
+import { setActiveAuthoring } from '@volter/editor-core/authoring/active-adapter';
+import { setActiveSystems } from '@volter/editor-core/authoring/active-systems';
+import { clearMountFailureReports } from '@volter/editor-core/authoring/mount-failure-report';
+import { resolveAllRoots } from '../host/binding-resolver';
+import { editorConsole } from '@volter/editor-core/editor-console';
+import type { EditorShellStore } from '@volter/editor-core/editor-shell-store';
+import { setGameInputGate } from '../host/gated-globals';
+import { authoringJournal } from '../host/history/json-history-resource';
+import { acquireLiveDocument, liveDocumentContainer } from '@volter/editor-core/live-document';
+import { DomAuthoringAdapter } from '../react/dom-authoring-adapter';
+import type { ResolvedAdapterRoot, ResolvedGameManifest } from '@volter/editor-project/manifest/load';
+import { serializeEntry, setActiveIngest } from './active-ingest';
+import { landIngestBootInEdit } from './ingest-boot-viewport';
+import { ingestHookEvidence, publishIngestHook, reactDomEvidence } from './ingest-evidence-hook';
+import { bindIngestLifecycle } from './ingest-play-control';
+import { domMountLoopFacts, type MountCoverageInputs, recordMountCoverage } from './mount-coverage';
+import { getIngestGameDom, ingestGameDomProjectRoot } from './surface-dom';
+import { exitActiveIngest } from './unmount-ingest-root';
+
+/** How a react ingest reaches the game: it mounts through the host's own
+ *  native React runtime, so whatever the editor cannot do here is the
+ *  adapter's own missing surface, not an unreachable realm. */
+const REACT_MECHANISM =
+  "this world mounts in the host's native React runtime, so the editor is limited only by " +
+  'what its authoring adapter provides';
+
+/** The coverage inputs both react routes record — identical by construction,
+ *  because both mount through the same native runtime. */
+function domMountCoverage(adapter: DomAuthoringAdapter): MountCoverageInputs {
+  return {
+    reach: measureAdapterReach({ authoring: adapter }),
+    reachMechanism: REACT_MECHANISM,
+    loop: domMountLoopFacts,
+  };
+}
+
+/**
+ * Mount a discovered native-React fixture game (`ingest/surface-dom.ts`'s glob
+ * discovery is the lookup).
+ *
+ * Reuses `resolveAllRoots` + universal `createGameRuntime` rather than
+ * hand-building a `DomHostContext`/`Game`: a
+ * single-element `roots` array gets EVERY host concern for free (the
+ * absolutely-positioned DOM-root layer, a real `Game`, dispose via
+ * `session.stop()`) with zero reinvention — `resolveAllRoots`'s
+ * `MULTI_WORLD_ALLOWED_IDENTITIES` gate only fires for `roots.length > 1`
+ * (see that function's doc comment), so a ONE-element manifest containing an
+ * `ingest-react` world resolves cleanly through it despite that identity
+ * being excluded from real multi-world manifests.
+ *
+ * D-N8 v2 / D-K4: the active authoring override is a real
+ * `DomAuthoringAdapter` — a structural-path DOM walker over the mounted
+ * react tree, applying edits live (never to source, see that file's doc
+ * comment). The published `reach` is MEASURED off this real adapter
+ * (`adapter-reach.ts`), not hard-coded, so every capability it does not
+ * provide keeps warning.
+ */
+async function mountDomIngestRootInner(store: EditorShellStore, folderId: string): Promise<void> {
+  const game = getIngestGameDom(folderId);
+  if (!game) {
+    editorConsole.error(`Unknown react ingest game: ${folderId}`, 'ingest');
+    return;
+  }
+  const projectRoot = ingestGameDomProjectRoot(folderId);
+  if (!projectRoot) {
+    editorConsole.error(
+      `React ingest "${folderId}": no __VGAI_ENGINE_ROOT__ available to resolve its entry`,
+      'ingest',
+    );
+    return;
+  }
+  // The Game document exists only while a runtime does, so install it (and
+  // wait for its panel to commit) before reading the container it owns.
+  await acquireLiveDocument();
+  const gameContainer = liveDocumentContainer();
+  if (!gameContainer) {
+    editorConsole.error('Game container not mounted — cannot ingest (react)', 'ingest');
+    return;
+  }
+  // D-V1: tear down WHATEVER kind is currently active, not just a prior
+  // react session — closes the cross-kind leak (F26 residual).
+  exitActiveIngest();
+
+  store.setPlayState('playing');
+  editorConsole.log(`Ingesting unmodified native-React game: ${game.manifest.name}`, 'ingest');
+
+  // F26: same cold-mount announcement as the other ingest routes — the react
+  // world's entry executes in the editor realm and may declare the game
+  // contract to defer its session until ▶. Opt-in, never demanded.
+  (window as unknown as { __vgaiMountCold?: boolean }).__vgaiMountCold = true;
+  const { createGameRuntime } = await import('@volter/game-runtime/runtime/create-runtime');
+  const specs = await resolveAllRoots(game.manifest, projectRoot);
+  const w = gameContainer.clientWidth;
+  const h = gameContainer.clientHeight;
+  const session = await createGameRuntime({
+    container: gameContainer,
+    roots: specs,
+    width: w,
+    height: h,
+  });
+
+  // D-K4: construct the real authoring adapter over the mounted world's live
+  // DOM root (its style edits are live-only — there is no source path here and
+  // no sidecar any more). The adapter has its own `selection` provider
+  // (store-backed, same shape as `ReactRootAuthoringAdapter.selection`), so —
+  // unlike a `{ module }` adapter with none — it is installed directly, never
+  // `withStoreSelection`-wrapped.
+  const root = session.game.roots[0]!.reactRoot();
+  // A held surface: its journal is the WORLD's, so undo survives a remount of
+  // this game (`../history/json-history-resource.ts`).
+  const adapter = new DomAuthoringAdapter(root, store, {
+    journal: authoringJournal(folderId),
+  });
+  // Unlike the capture routes, a react ingest mounts through the NATIVE
+  // runtime — its Game.play pause/resume IS the honest control (D10). Named
+  // (rather than inlined below) so `setPausedPresent`'s D-L1 `typeof`
+  // check reads the SAME real control the session actually installs, never
+  // an independent literal.
+  const setPaused = (p: boolean) => (p ? session.game.play.pause() : session.game.play.resume());
+  const lifecycle = bindIngestLifecycle({ setPaused });
+
+  setActiveIngest({
+    kind: 'dom',
+    session: {
+      store,
+      lifecycle,
+      stop: () => session.stop(),
+      adapter,
+    },
+    siblings: [],
+    worldId: folderId,
+  });
+  // Same play-mode input gate every other same-realm ingest route drives (R2c).
+  // The former per-surface `games-2d`/`games-react` fixture
+  // trees into the single `ingest/games` tree, which IS what
+  // `game-globals-shadow.ts` roots its shadow at — so a native-React fixture's
+  // own listeners are shadowed on the same terms as every other surface's now
+  // (this comment used to record the opposite, from the R-N6 residual).
+  setGameInputGate(() => store.playState === 'playing' && store.activeViewportTab === 'play');
+
+  setActiveAuthoring(adapter);
+  setActiveSystems({});
+  landIngestBootInEdit(store);
+  store.notifyIngestEdit();
+  clearMountFailureReports(); // D-W3: mount succeeded
+
+  const coverage = domMountCoverage(adapter);
+  recordMountCoverage(coverage);
+
+  publishIngestHook('__vgaiIngestReact', {
+    gameId: folderId,
+    worldId: game.worldId,
+    ...ingestHookEvidence(adapter),
+    noAuthoring: false,
+    // D-K4: MEASURED off the real adapter (`adapter-reach.ts`) — a
+    // hierarchy+inspector+persistence adapter with no `transforms` reports a
+    // standing `transforms` gap, never a hard-coded claim.
+    reach: coverage.reach,
+    // D-L1: the doctor MOUNTED-bar evidence accessor —
+    // see `reactDomEvidence`'s own doc comment.
+    domEvidence: () => reactDomEvidence(root, adapter),
+    // D-L1: honest `typeof === 'function'` check on the REAL session
+    // control this route just installed above — never an independent
+    // literal `true` (mirrors `__vgaiSiblingMounts`'s identical discipline).
+    setPausedPresent: typeof lifecycle.setPaused === 'function',
+  });
+}
+
+/**
+ * D-Y2 (slice S2) — the manifest-route sibling of {@link mountDomIngestRoot}: an
+ * EXTERNAL-FOLDER `ingest-react` world (the opened project's OWN
+ * `vgai.project.json`, not the in-tree `ingest/games/<id>` fixture registry)
+ * enters the same react ingest session. Exactly the same roots-path recipe
+ * (one-element `resolveAllRoots` + roots-path `createGameRuntime`) and the same
+ * `DomAuthoringAdapter` D-K4 wiring — only the SOURCE of
+ * `world`/`projectRoot` differs (the opened project's manifest +
+ * `project.rootPath`, via `mount-ingest-root.ts`'s react route, instead of
+ * `getIngestGameDom`/`ingestGameDomProjectRoot`'s vendored-fixture lookup).
+ * `resolveIngestReactAdapter`'s own guards (`entry` required, no `scene`) run
+ * unchanged inside `resolveAllRoots` — this function
+ * adds no new validation of its own, mirroring
+ * `mountCanvasIngestRootFromManifest`'s relationship to its vendored sibling.
+ */
+export async function mountDomIngestRootFromManifest(
+  store: EditorShellStore,
+  manifest: ResolvedGameManifest,
+  world: ResolvedAdapterRoot,
+  projectRoot: string,
+): Promise<void> {
+  // The Game document exists only while a runtime does, so install it (and
+  // wait for its panel to commit) before reading the container it owns.
+  await acquireLiveDocument();
+  const gameContainer = liveDocumentContainer();
+  if (!gameContainer) {
+    editorConsole.error('Game container not mounted — cannot ingest (react)', 'ingest');
+    return;
+  }
+  // D-V1: tear down WHATEVER kind is currently active, not just a prior
+  // react session — closes the cross-kind leak (F26 residual).
+  exitActiveIngest();
+
+  store.setPlayState('playing');
+  editorConsole.log(
+    `Ingesting unmodified native-React game (external folder): ${world.id}`,
+    'ingest',
+  );
+
+  // F26: same cold-mount announcement the vendored route makes — an
+  // external-folder game may declare the game contract too.
+  (window as unknown as { __vgaiMountCold?: boolean }).__vgaiMountCold = true;
+  const { createGameRuntime } = await import('@volter/game-runtime/runtime/create-runtime');
+  const specs = await resolveAllRoots({ ...manifest, roots: [world] }, projectRoot);
+  const w = gameContainer.clientWidth;
+  const h = gameContainer.clientHeight;
+  const session = await createGameRuntime({
+    container: gameContainer,
+    roots: specs,
+    width: w,
+    height: h,
+  });
+
+  // D-K4: same adapter construction as the vendored route.
+  const root = session.game.roots[0]!.reactRoot();
+  const adapter = new DomAuthoringAdapter(root, store, {
+    journal: authoringJournal(world.id),
+  });
+  // Same honest control as the vendored route (D10): a manifest-routed react
+  // ingest mounts through the NATIVE runtime, so Game.play pause/resume IS
+  // real. Named (D-L1) so `setPausedPresent` checks the SAME real control.
+  const setPaused = (p: boolean) => (p ? session.game.play.pause() : session.game.play.resume());
+  const lifecycle = bindIngestLifecycle({ setPaused });
+
+  setActiveIngest({
+    kind: 'dom',
+    session: {
+      store,
+      lifecycle,
+      stop: () => session.stop(),
+      adapter,
+    },
+    siblings: [],
+    worldId: world.id,
+  });
+  setGameInputGate(() => store.playState === 'playing' && store.activeViewportTab === 'play');
+
+  setActiveAuthoring(adapter);
+  setActiveSystems({});
+  landIngestBootInEdit(store);
+  store.notifyIngestEdit();
+  clearMountFailureReports(); // D-W3: mount succeeded
+
+  const coverage = domMountCoverage(adapter);
+  recordMountCoverage(coverage);
+
+  publishIngestHook('__vgaiIngestReact', {
+    worldId: world.id,
+    ...ingestHookEvidence(adapter),
+    noAuthoring: false,
+    // D-K4: see mountDomIngestRoot's identical comment — MEASURED, never
+    // hard-coded.
+    reach: coverage.reach,
+    // D-L1: see mountDomIngestRoot's identical comment.
+    domEvidence: () => reactDomEvidence(root, adapter),
+    setPausedPresent: typeof lifecycle.setPaused === 'function',
+  });
+}
+
+/**
+ * Mount a discovered native-React fixture game by its folder id. Serialized
+ * through the shared entry queue; see `active-ingest.ts`'s `serializeEntry`.
+ */
+export function mountDomIngestRoot(store: EditorShellStore, folderId: string): Promise<void> {
+  return serializeEntry(() => mountDomIngestRootInner(store, folderId));
+}