@volter/editor-game 0.5.65

package/src/ingest/active-ingest.ts

@@ -0,0 +1,251 @@
+/**
+ * THE single live-ingest slot: the shape of a mounted `{ ingest }` root's
+ * session, the one module-level variable holding it, and the queue that keeps
+ * entry to it serial.
+ *
+ * This module deliberately holds STATE and nothing else — no mounting, no
+ * teardown, no measurement. `mount-three-ingest-root.ts` /
+ * `mount-canvas-ingest-root.ts` / `mount-dom-ingest-root.ts` publish into the
+ * slot, `unmount-ingest-root.ts` empties it, and everything that merely READS a
+ * live session (`ingest-play-control.ts`, `mount-coverage.ts`,
+ * `live-ingest-facet.ts`) imports from here. Keeping the slot a leaf is what
+ * makes that whole graph acyclic.
+ */
+
+import type { EditorShellStore } from '@volter/editor-core/editor-shell-store';
+import type { MeasuredLoop } from '../host/same-realm-loop-gate';
+import type { DomAuthoringAdapter } from '../react/dom-authoring-adapter';
+import type { AuthoringAdapter } from '@volter/editor-project/adapter/authoring';
+import type { IngestMount } from './authoring/ingest-root-adapter';
+import type { SiblingMount } from './ingest-siblings';
+import type { MountCoverageInputs } from './mount-coverage';
+
+/**
+ * The ONE lifecycle control the editor consumes for an ingested game.
+ *
+ * Mount code resolves the game's raw contract and the substrate's fallback
+ * into this shape once. Consumers never choose between those mechanisms:
+ * `start` owns the cold -> started edge, while `setPaused` is present only
+ * when one complete pause/resume mechanism exists. A missing capability keeps
+ * its exact reason on `pauseGap` so Edit can refuse loudly rather than treating
+ * a fabricated no-op function as a successful hold.
+ */
+export interface IngestLifecycleControl {
+  readonly start: () => void;
+  readonly setPaused?: ((paused: boolean) => void) | undefined;
+  readonly pauseGap?: string | undefined;
+  readonly step?: (() => void) | undefined;
+  readonly canStep?: (() => boolean) | undefined;
+}
+
+export interface IngestSession {
+  store: EditorShellStore;
+  lifecycle: IngestLifecycleControl;
+  /** The capture path (a real authoring adapter over the live scene). */
+  mount?: IngestMount;
+  /** Keeps the captured game renderer sized to its container (host lifecycle). */
+  resizeObserver?: ResizeObserver;
+  /** Drops the store subscription that releases a game-held pointer lock when
+   *  the input gate closes (`ingest/game-pointer-lock.ts`). */
+  inputGateUnsubscribe?: () => void;
+}
+
+export interface IngestSession2D {
+  store: EditorShellStore;
+  lifecycle: IngestLifecycleControl;
+  adapter?: AuthoringAdapter & { dispose(): void };
+  /** The realm host box the game appended into — Scene reparents this. */
+  hostEl?: HTMLElement;
+  /** Measured loop truth for a reachable canvas realm — a verdict CARRIES the
+   *  evidence it was concluded from ({@link MeasuredLoop}). `null` when the
+   *  probe ran but learned nothing (`reason` says what it looked at) — never a
+   *  verdict forced out of an absence of evidence. */
+  loop?: () => { loop: MeasuredLoop | null; reason: string };
+  dispose: () => void;
+}
+
+export interface IngestSessionReact {
+  store: EditorShellStore;
+  lifecycle: IngestLifecycleControl;
+  stop: () => void;
+  /** Live DOM-authoring adapter; owns a session history resource. */
+  adapter: DomAuthoringAdapter;
+}
+
+/**
+ * The world kind of the currently-active ingest session, if any (F26):
+ * ingest is an ADAPTER ROUTE, not a kind of its own — D-V1
+ * collapsed the three per-kind session slots this used to fixed-priority-scan
+ * (`_session` / `_session2D` / `_sessionReact`) into the single `_active` slot
+ * below, so at most one session is ever active, of any kind, and
+ * {@link activeIngestKind} is just that slot's tag. The play surface
+ * ({@link import('./ingest-play-control').getIngestPlayControl}) and
+ * {@link isIngestActive} read it, never a slot directly.
+ */
+export type IngestKind = 'three' | 'canvas' | 'dom';
+
+/**
+ * F26 slot collapse (D-V1): at most one ingest session is EVER active, of
+ * any kind — {@link activeIngest} is the single module-level slot for it.
+ * Pre-collapse, this was three independent per-kind singletons
+ * (`_session`/`_session2D`/`_sessionReact`, one per `IngestSession*` shape
+ * above), each with its own entry guard that only tore down its OWN slot —
+ * so switching kinds leaked the prior kind's live session (the F26
+ * residual).
+ *
+ * `siblings` (D-V2, composite): a composite manifest's OTHER roots, mounted
+ * beside this session's ingest world (`ingest-siblings.ts`'s
+ * `mountIngestSiblings`) — always `[]` for every non-composite entry path
+ * (the in-tree fixture glob route, a single-world manifest).
+ * `unmount-ingest-root.ts`'s `exitActiveIngest` disposes these, reverse order,
+ * in EVERY kind's teardown path — a sibling never outlives the session it was
+ * mounted beside.
+ */
+export type ActiveIngest = (
+  | { kind: 'three'; session: IngestSession }
+  | { kind: 'canvas'; session: IngestSession2D }
+  | { kind: 'dom'; session: IngestSessionReact }
+) & {
+  siblings: SiblingMount[];
+  /** The mounted world's id — the SAME id every log line and the
+   *  `__vgaiIngest` hook's `gameId` names. Carried on the slot (rather than
+   *  re-derived) so the status facet can report WHICH world is live
+   *  without a second source of truth (S-1). */
+  worldId: string;
+  /** The coverage inputs that can only be read AT MOUNT (see
+   *  {@link MountCoverageInputs}). Absent until a mount path records them, and
+   *  absent is honestly "not measured" — never a clean bill of health. */
+  coverage?: MountCoverageInputs;
+};
+
+let _active: ActiveIngest | null = null;
+
+/** The live session, or `null`. Read it; never cache it across an await. */
+export function activeIngest(): ActiveIngest | null {
+  return _active;
+}
+
+/** THE one write to the slot. Publishing happens only after a mount SUCCEEDS,
+ *  which is what makes a non-null slot the mount evidence itself (S-1). */
+export function setActiveIngest(next: ActiveIngest | null): void {
+  _active = next;
+}
+
+export function activeIngestKind(): IngestKind | null {
+  return _active?.kind ?? null;
+}
+
+/** True if an unmodified game is currently ingested — ANY kind (F26). */
+export function isIngestActive(): boolean {
+  return activeIngestKind() !== null;
+}
+
+/** True if an unmodified PixiJS game is currently ingested. */
+export function isIngestActive2D(): boolean {
+  return _active?.kind === 'canvas';
+}
+
+/** True if an ingested native-React game is currently mounted. */
+export function isIngestActiveReact(): boolean {
+  return _active?.kind === 'dom';
+}
+
+/**
+ * D-V2: attach a composite's sibling handles onto the JUST-published session
+ * (set by the primary ingest world's own mount call, immediately before this
+ * runs) — a no-op if the slot is somehow no longer set (defensive only;
+ * nothing in that synchronous call chain clears it between the primary mount
+ * and this attach).
+ */
+export function attachIngestSiblings(siblings: readonly SiblingMount[]): void {
+  if (_active) _active.siblings = [...siblings];
+}
+
+/**
+ * Serializes ingest ENTRY, exactly as `play-mode.ts`'s `_enterQueue` does for
+ * play — and for the same reason it had to.
+ *
+ * Every entry point opens with a synchronous `exitActiveIngest()`, which reads
+ * the slot. But the slot is not assigned until AFTER the mount's awaits
+ * resolve. Two overlapping calls therefore both observe an empty slot,
+ * both tear down nothing, and both mount — leaving two live sessions. That is
+ * the react-rpg double mount: two React roots, two `<div id="window">`, two
+ * "Story Mode" buttons, intermittently, because it is a race rather than a
+ * code path. Nothing kind-specific about it; every entry point shares the
+ * shape, react merely had the test that caught it.
+ *
+ * Queued, the second caller's `exitActiveIngest()` runs after the first has
+ * published the slot, so it disposes it and exactly one session stays live.
+ * Pinned by `ingest-root-entry-race.test.ts`.
+ */
+let _enterQueue: Promise<void> = Promise.resolve();
+
+export function serializeEntry<T>(run: () => Promise<T>): Promise<T> {
+  const result = _enterQueue.then(run);
+  // Advance unconditionally so one caller's rejection can never wedge every
+  // subsequent ingest attempt — each caller still observes its OWN failure
+  // through the promise returned here (same contract as play-mode's queue).
+  _enterQueue = result.then(
+    () => undefined,
+    () => undefined,
+  );
+  return result;
+}
+
+import { registerLiveSession } from '@volter/editor-core/live-session-registry';
+// THE INGEST LANE, as the host sees it (`live-session-registry.ts`). Playing
+// is the host play-control latch, never an inferred loop
+// (`editor-session-mode.ts` records why); a deferred-ingest play counts.
+import { activeContractScenes } from './active-scene-navigation';
+import { deferredIngestPlayActive } from './deferred-ingest-session';
+import { armIngestFrameSnapshot, ingestFrameCanvas } from './ingest-frame-snapshot';
+import { handleIngestPlayControl } from './ingest-play-commands';
+import { getIngestPlayControl, ingestPlaying } from './ingest-play-control';
+// `mount-coverage.ts` imports this module back, so the pair is a CYCLE — and
+// the lane's report is read through it directly rather than pushed in by a
+// setter. A setter is what a cycle cannot survive: `mount-coverage`'s
+// module-scope `setIngestCoverageSource(...)` ran while this module's own body
+// was still in its `let`'s temporal dead zone whenever the graph happened to
+// evaluate this file first, and the editor failed to start with "Cannot access
+// 'coverageSource' before initialization" (measured on `bunnymark`,
+// 2026-09-17, when an import-sort reshuffle changed which file the graph
+// reached first). `ingestCoverageReport` is a FUNCTION DECLARATION: ESM
+// initializes it at instantiation, before any body runs, so reading it across
+// the cycle is order-independent by construction.
+import { ingestCoverageReport } from './mount-coverage';
+import { exitActiveIngest } from './unmount-ingest-root';
+
+registerLiveSession({
+  id: 'ingest',
+  priority: 1,
+  mounted: isIngestActive,
+  playing: () => ingestPlaying() || deferredIngestPlayActive(),
+  stop: exitActiveIngest,
+  instanceContainer: () => null,
+  frameCanvas: ingestFrameCanvas,
+  snapshotFrame: () => armIngestFrameSnapshot(),
+  // S-2 (the SimCity ledger): an ingest session OWNS its mount, and the
+  // first-party play boot cannot share it — `play`/`stop`/`pause`/`resume`/
+  // `step` drive the ingested game's own loop (`ingest-play-commands.ts`).
+  command: (cmd) => {
+    const control = isIngestActive() ? getIngestPlayControl() : null;
+    return control
+      ? handleIngestPlayControl(control, cmd.type, { stopEndsRun: deferredIngestPlayActive() })
+      : null;
+  },
+  scenes: activeContractScenes,
+  surface: activeIngestKind,
+  coverage: ingestCoverageReport,
+  // An ingested native-React game renders as a DOM layer under the host
+  // React — no scene graph, no renderer to introspect — and authoring is
+  // deliberately off for react ingests (the editor never writes JSX back into
+  // an unmodified game). The game is hosted, sized and disposed; play it in
+  // the Game tab.
+  authoringRefusal: () =>
+    _active?.kind === 'dom'
+      ? 'This is an ingested native-React game: its components render directly as a DOM layer ' +
+        'under the host React — there is no scene graph or renderer to introspect, and authoring ' +
+        'is deliberately off for react ingests (the editor never writes JSX back into an ' +
+        'unmodified game). The game is hosted, sized, and disposed; play it in the Game tab.'
+      : null,
+});

package/src/ingest/active-scene-navigation.ts

@@ -0,0 +1,43 @@
+/**
+ * The BOUND scenes projection of whatever game is live in this session, or
+ * `null`.
+ *
+ * One question, one reader. The `open` verb's live half
+ * (`scene-live-open.ts`) needs the very object the mount installed — the same
+ * one the inspector's scene picker drives, carrying that mount's held-repaint
+ * seam — so it is resolved off the single ingest slot (`active-ingest.ts`),
+ * never rebuilt from the contract and never taken from a COMPOSITE adapter's
+ * `stories` pass-through (that is a fresh delegating object; the projection's
+ * `goToScene` does not survive it).
+ *
+ * The marker, not the session kind, is what decides: a plain `StoriesProvider`
+ * (a react world's design-time CSF states) is not a game's own screens and must
+ * not be navigated as though it were.
+ */
+
+import {
+  type ContractScenesStories,
+  isContractScenesStories,
+} from '../host/authoring/contract-scenes-stories';
+import type { AuthoringAdapter } from '@volter/editor-project/adapter/authoring';
+import { activeIngest } from './active-ingest';
+
+export function activeContractScenes(): ContractScenesStories | null {
+  const active = activeIngest();
+  if (!active) return null;
+  // Every kind's own live authoring adapter — asked the same question, so a
+  // projection bound on a lane that does not have one today answers the day it
+  // does, without a second reader here.
+  const adapter: AuthoringAdapter | null | undefined = (() => {
+    switch (active.kind) {
+      case 'canvas':
+        return active.session.adapter;
+      case 'dom':
+        return active.session.adapter;
+      case 'three':
+        return active.session.mount?.authoring;
+    }
+  })();
+  const stories = adapter?.stories;
+  return isContractScenesStories(stories) ? stories : null;
+}

package/src/ingest/authoring/ingest-dom-surface-authoring.ts

@@ -0,0 +1,191 @@
+/**
+ * Turns a readable canvas game's own DOM UI into an ordinary nested authoring
+ * surface. Detection stays at the mount boundary; once built, the editor sees
+ * only AuthoringAdapter/CompositeAuthoringAdapter currency.
+ */
+
+import { CompositeAuthoringAdapter } from '@volter/editor-core/authoring/composite-authoring-adapter';
+import {
+  findCanvasUiElements,
+  findPrimaryCanvas,
+  type OverlayElement,
+} from '../../host/coverage/capability-coverage';
+import type { EditorShellStore } from '@volter/editor-core/editor-shell-store';
+import { authoringJournal } from '../../host/history/json-history-resource';
+import { sourceWriteBackendIfPrimed } from '@volter/editor-core/ui-source/tier-source-write-backend';
+import { DomAuthoringAdapter, type DomElementLike } from '../../react/dom-authoring-adapter';
+import {
+  type OidElementLike,
+  ReactRootAuthoringAdapter,
+  walkOidTree,
+} from '../../react/react-world-authoring-adapter';
+import type { AuthoringAdapter } from '@volter/editor-project/adapter';
+import type { VgaiGameContract } from '@volter/editor-project/adapter/ingest/game-contract';
+
+type ReadableDomRoot = OverlayElement & DomElementLike & { readonly ownerDocument?: Document };
+
+function isReadableDomRoot(value: unknown): value is ReadableDomRoot {
+  const candidate = value as Partial<ReadableDomRoot> | null;
+  return (
+    candidate !== null &&
+    typeof candidate === 'object' &&
+    typeof candidate.tagName === 'string' &&
+    candidate.children !== undefined &&
+    typeof candidate.getBoundingClientRect === 'function'
+  );
+}
+
+function iframeDocumentRoot(hostEl: HTMLElement): ReadableDomRoot | null {
+  try {
+    const iframe =
+      hostEl.tagName.toLowerCase() === 'iframe'
+        ? (hostEl as HTMLIFrameElement)
+        : (hostEl.querySelector('iframe') as HTMLIFrameElement | null);
+    const body = iframe?.contentDocument?.body;
+    return isReadableDomRoot(body) ? body : null;
+  } catch {
+    return null;
+  }
+}
+
+function resolveGameDomRoot(
+  hostEl: HTMLElement,
+  declaredRoot: VgaiGameContract['root'] | undefined,
+): ReadableDomRoot | null {
+  if (isReadableDomRoot(declaredRoot)) return declaredRoot;
+  return iframeDocumentRoot(hostEl) ?? (isReadableDomRoot(hostEl) ? hostEl : null);
+}
+
+function withMutationSubscription(
+  adapter: DomAuthoringAdapter | ReactRootAuthoringAdapter,
+  gameRoot: ReadableDomRoot,
+): AuthoringAdapter {
+  const subscribe = (listener: () => void): (() => void) => {
+    const unsubscribe = adapter.subscribe(listener);
+    const Observer = gameRoot.ownerDocument?.defaultView?.MutationObserver;
+    if (!Observer) return unsubscribe;
+    const observer = new Observer(() => listener());
+    observer.observe(gameRoot as unknown as Node, {
+      childList: true,
+      subtree: true,
+    });
+    return () => {
+      observer.disconnect();
+      unsubscribe();
+    };
+  };
+  return new Proxy(adapter, {
+    get(target, property) {
+      if (property === 'subscribe') return subscribe;
+      const value = Reflect.get(target, property, target);
+      return typeof value === 'function' ? value.bind(target) : value;
+    },
+  });
+}
+
+/**
+ * Which authoring adapter this mount's DOM UI gets — decided by ONE probe, the
+ * same probe and the same two outcomes `ingest-siblings.ts`'s
+ * `mountReactSibling` already uses for a react sibling layer: does the live DOM
+ * actually carry `data-oid` stamps?
+ *
+ * - **Stamped** ⇒ {@link ReactRootAuthoringAdapter} over the OID tree, with the
+ *   dev-server source-write backend. Node ids are OID-derived, so the HUD's own
+ *   JSX — the component the elements came from — is the subject, and a
+ *   className/style/text edit prepares next-file text and commits it through
+ *   `/__ui-source/write`. For a REPO-VENDORED game that endpoint's
+ *   `writeEditableSource` routes the write through
+ *   `server/vendored-lock-recorder.ts`, exactly as a three root's writes are
+ *   routed — the choke point is the endpoint, not the adapter, so this lane
+ *   inherits lock recording without knowing anything about vendoring.
+ * - **Unstamped** ⇒ {@link DomAuthoringAdapter} unchanged: structural ids
+ *   over the live DOM and no write seam at all. That is the honest answer for
+ *   DOM the stamping pipeline declined to instrument (a bundled/minified ingest,
+ *   a foreign game excluded by identity) — never a write seam over source the
+ *   editor cannot address.
+ *
+ * A PARTIALLY stamped tree counts as stamped: `walkOidTree` already skips
+ * untagged elements transparently and attaches their children to the nearest
+ * tagged ancestor, so this stays a single "any node at all?" question rather
+ * than a completeness one.
+ *
+ * The ROUTE gates the backend, not the adapter choice (`../ui-source/tier-
+ * source-write-backend.ts`): on a host that serves no `/__ui-source/*`
+ * recorder the OID lane still gives correct selection/inspection and reports
+ * its writes unavailable through `persistence.destination`.
+ */
+function domSurfaceAdapter(
+  liveUiRoot: DomElementLike & OidElementLike,
+  store: EditorShellStore,
+  /** The detected surface's own id — a held surface, so its journal is the
+   *  world's and survives the ingest remounting (see the ownership block in
+   *  `../history/json-history-resource.ts`). */
+  domUiJournalId: string,
+): DomAuthoringAdapter | ReactRootAuthoringAdapter {
+  if (walkOidTree(liveUiRoot).nodes.size === 0) {
+    return new DomAuthoringAdapter(liveUiRoot, store, {
+      journal: authoringJournal(domUiJournalId),
+    });
+  }
+  const writeBackend = sourceWriteBackendIfPrimed('An ingested game’s DOM UI surface');
+  return new ReactRootAuthoringAdapter(liveUiRoot, store, {
+    ...(writeBackend ? { writeBackend } : {}),
+  });
+}
+
+/**
+ * Preserve `primary` byte-for-byte when this mount has no readable canvas/UI
+ * split. Otherwise expose Canvas as the runtime surface and DOM UI as its
+ * nested document. The UI root's children are getters over live geometry, so
+ * menus that appear later enter the same surface without a mirror tree.
+ */
+export function withDetectedDomSurface(args: {
+  primary: AuthoringAdapter;
+  worldId: string;
+  hostEl: HTMLElement;
+  declaredRoot?: VgaiGameContract['root'];
+  store: EditorShellStore;
+}): AuthoringAdapter {
+  const gameRoot = resolveGameDomRoot(args.hostEl, args.declaredRoot);
+  if (!gameRoot) return args.primary;
+  const canvas = findPrimaryCanvas(gameRoot);
+  if (!canvas || findCanvasUiElements(gameRoot, canvas).length === 0) return args.primary;
+
+  const domUiId = `${args.worldId}:dom-ui`;
+  // Composite world ids are editor identity and legitimately use `:`. A
+  // history resource id is a project-relative path and must not: conflating
+  // the two made ResourceRegistry parse `world:dom-ui/...` as a URL scheme and
+  // refuse every detected DOM sibling before the ingest could mount.
+  const domUiJournalId = `${args.worldId}/dom-ui`;
+  const liveUiRoot: DomElementLike & OidElementLike = {
+    tagName: 'vgai-dom-surface',
+    id: '',
+    className: '',
+    get children() {
+      const currentCanvas = findPrimaryCanvas(gameRoot);
+      return currentCanvas
+        ? (findCanvasUiElements(gameRoot, currentCanvas) as DomElementLike[] & OidElementLike[])
+        : [];
+    },
+    // A synthetic container the host manufactured, not a rendered element —
+    // it carries no oid of its own, and `walkOidTree` transparently skips an
+    // untagged node, attaching the game's real HUD elements as tree roots.
+    getAttribute: () => null,
+  };
+  const dom = withMutationSubscription(
+    domSurfaceAdapter(liveUiRoot, args.store, domUiJournalId),
+    gameRoot,
+  );
+  const canvasId = `${args.worldId}:canvas`;
+  return new CompositeAuthoringAdapter([
+    { worldId: canvasId, kind: 'canvas', adapter: args.primary },
+    {
+      worldId: domUiId,
+      kind: 'dom',
+      role: 'surface',
+      label: 'DOM UI',
+      parentRootId: canvasId,
+      adapter: dom,
+    },
+  ]);
+}