@volter/editor-core 0.5.57

package/server/frame-workbench.ts

@@ -0,0 +1,259 @@
+/**
+ * THE SESSION OWNS THE FRAME. This module is where it does.
+ *
+ * `vgai edit` IS the Code-OSS workbench, and the workbench is two things: the
+ * remote extension host (a child process, serving the VS Code page) and the
+ * one-origin proxy (a listener in THIS process, `frame-proxy.ts`). Both belong
+ * to the session, which is the only owner that can be right: they exist to
+ * serve this project's session, they must die when it does, and a `vgai edit`
+ * that merely REUSES a live session must not have to adopt somebody else's
+ * children.
+ *
+ * RESOURCE OWNERSHIP, stated once (the rule that cost a game-scoped clock).
+ *  - OWNER: this session process. It spawns the REH into its own process group
+ *    and listens for the proxy itself.
+ *  - SHARERS: none. The CLI allocates the two reserved ports and hands them
+ *    over; after that it owns nothing of the frame. A second `vgai edit` on
+ *    this project reuses the session and therefore reuses the frame.
+ *  - THE ONE TEARDOWN: the host's shutdown task list (`dev.ts`/`packaged.ts`'s
+ *    `createProcessShutdown`), which is the same path `vgai close`, SIGTERM and
+ *    the idle timer all take — the path that already ends run configurations.
+ *    Nothing else may stop it.
+ *
+ * WHERE THE WORKBENCH IS comes from the project's own declaration
+ * (`.vgai/workbench.json`) or `vgai edit --workbench <dir>`; the CLI resolves it
+ * once to refuse early and passes the directory here. `@volter/editor-sdk/session/
+ * workbench-locator` is the one resolver and the one set of refusal texts.
+ */
+
+import { type ChildProcess, spawn } from 'node:child_process';
+import { createConnection } from 'node:net';
+import { workbenchProductId } from '@volter/editor-sdk/session/product-locator';
+import {
+  resolveWorkbench,
+  type WorkbenchIdentity,
+  workbenchUrl,
+} from '@volter/editor-sdk/session/workbench-locator';
+import { startFrameProxy } from './frame-proxy';
+import { stopProcess } from './process-shutdown';
+import { sessionProduct } from './session-product';
+
+/** The workbench directory the CLI resolved and handed over. */
+const WORKBENCH_DIR_ENV = 'VGAI_WORKBENCH_DIR';
+/** The reserved port for the Code-OSS server. */
+const FRAME_PORT_ENV = 'VGAI_FRAME_PORT';
+/** The reserved port for the one-origin proxy — the url a person opens. */
+const FRAME_PROXY_PORT_ENV = 'VGAI_FRAME_PROXY_PORT';
+
+export interface FrameLaunch {
+  readonly workbenchDir: string;
+  readonly rehPort: number;
+  readonly proxyPort: number;
+}
+
+/**
+ * What this session was told to frame, or `null` when it was told nothing.
+ * Reading the three together is deliberate: a launch with a workbench and no
+ * ports, or ports and no workbench, is a caller bug and reads as "not framed"
+ * rather than as half a frame.
+ */
+export function frameLaunchFromEnv(): FrameLaunch | null {
+  const workbenchDir = process.env[WORKBENCH_DIR_ENV];
+  const rehPort = Number(process.env[FRAME_PORT_ENV]);
+  const proxyPort = Number(process.env[FRAME_PROXY_PORT_ENV]);
+  if (!workbenchDir || !Number.isInteger(rehPort) || !Number.isInteger(proxyPort)) return null;
+  return { workbenchDir, rehPort, proxyPort };
+}
+
+/**
+ * The url the workbench will answer on, known before anything starts.
+ *
+ * The tab bijection needs it at `createEditorServer` time — under the frame the
+ * session's ONE tab is the workbench page, not this server's own — and it is
+ * pure arithmetic over the reserved port, so nothing has to have booted yet.
+ */
+export function frameWorkbenchUrl(launch: FrameLaunch, projectRoot: string): string {
+  return workbenchUrl(launch.proxyPort, projectRoot);
+}
+
+export interface FrameWorkbench {
+  /** What this session is running, for `EditorState.workbench` and `vgai status`. */
+  readonly identity: WorkbenchIdentity;
+  readonly url: string;
+  /**
+   * STOP THE CODE-OSS SERVER — the detached CHILD, and the one thing here that
+   * can outlive this process. Unconditional in the shutdown list: it waits on
+   * nothing, least of all a tab (`dev.ts`'s task list).
+   */
+  stopServer(): Promise<void>;
+  /**
+   * CLOSE THE ONE-ORIGIN PROXY — a listener in THIS process, and the tab's only
+   * route to this session: the page's origin is the proxy's, so every
+   * `/__editor/*` call it makes, the tab-close ACK BEACON included, arrives
+   * here first. So it closes with the HTTP server, AFTER the tab-close notice,
+   * and not with the child above. Measured 2026-09-21: closing it beside the
+   * child turned every `vgai close` from `session-end-acked … ms 26` into
+   * `session-end-unacked … ms 2002` — the page was told, closed itself, and
+   * its beacon had nowhere to land.
+   */
+  closeProxy(): Promise<void>;
+  /** Both, in one call — for the boot error path and the source-restart exit,
+   *  where there is no tab to preserve a route for. */
+  stop(): Promise<void>;
+}
+
+/** True while something is listening on `port` of loopback. */
+function portTaken(port: number): Promise<boolean> {
+  return new Promise((done) => {
+    const socket = createConnection({ host: '127.0.0.1', port });
+    const settle = (taken: boolean) => {
+      socket.destroy();
+      done(taken);
+    };
+    socket.once('connect', () => settle(true));
+    socket.once('error', () => settle(false));
+    socket.setTimeout(750, () => settle(false));
+  });
+}
+
+async function waitForPort(
+  port: number,
+  what: string,
+  child: ChildProcess,
+  timeoutMs: number,
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    if (await portTaken(port)) return;
+    if (child.exitCode !== null) {
+      throw new Error(`${what} exited (code ${child.exitCode}) before it listened on ${port}.`);
+    }
+    if (Date.now() > deadline) {
+      throw new Error(`${what} never listened on ${port} within ${Math.round(timeoutMs / 1000)}s.`);
+    }
+    await new Promise((settle) => setTimeout(settle, 500));
+  }
+}
+
+/**
+ * Start the workbench for this session: the REH, then the proxy in front of it
+ * and of this process.
+ *
+ * The argv is the same string whichever kind the workbench is — a release is
+ * meant to be measured against the sources, and a boot that differed in a flag
+ * would be measuring the flag.
+ */
+export async function startFrameWorkbench(options: {
+  launch: FrameLaunch;
+  projectRoot: string;
+  sessionPort: number;
+  /**
+   * EXTRA ENVIRONMENT FOR THE REH, and through it for its extension host.
+   * Today that is the Chat view's runtime handoff (`frontend-handoff.ts`): the
+   * bundled supercode frontend reads `SUPERCODE_FRONTEND_*` at activation. It is
+   * a SPAWN argument and not a later call because a child's environment cannot
+   * be changed after it starts — which is why the session starts its harness
+   * runtime before it gets here, and why there is deliberately no
+   * restart-the-REH path when one arrives late.
+   */
+  env?: Readonly<Record<string, string>>;
+  log: (line: string) => void;
+}): Promise<FrameWorkbench> {
+  const { launch, projectRoot, sessionPort, log } = options;
+  // A WORKBENCH IS ONE PRODUCT'S (P3): the editor kit and one product's
+  // workbench half are overlaid on the fork together, so a release or checkout
+  // built for the other product is refused here BY NAME. The session is the
+  // right place for it — the CLI checks the same pair before a server exists,
+  // and this is the read that spawns. A project whose product cannot be
+  // resolved is not judged: `/__editor/served-modules` is the door that says
+  // why, in its own words.
+  const product = sessionProduct(projectRoot);
+  const workbench = resolveWorkbench(
+    launch.workbenchDir,
+    product === null ? undefined : workbenchProductId(product.name),
+  );
+
+  for (const [port, what] of [
+    [launch.rehPort, 'the Code-OSS server'],
+    [launch.proxyPort, 'the one-origin proxy'],
+  ] as const) {
+    if (await portTaken(port)) {
+      throw new Error(
+        `This project reserves port ${port} for ${what}, and something is already listening there. ` +
+          `Free it (\`lsof -nP -iTCP:${port} -sTCP:LISTEN\`) — the frame never drifts to another port.`,
+      );
+    }
+  }
+
+  log(
+    `frame: Code-OSS ${workbench.kind} ${workbench.commit.slice(0, 12)} (${workbench.dir}) on ${launch.rehPort}`,
+  );
+  const reh = spawn(
+    workbench.serverBin,
+    [
+      '--host',
+      '127.0.0.1',
+      '--port',
+      String(launch.rehPort),
+      '--without-connection-token',
+      projectRoot,
+    ],
+    {
+      cwd: workbench.cwd,
+      stdio: 'ignore',
+      detached: true,
+      env: { ...process.env, ...options.env },
+    },
+  );
+  let proxy: { close(): Promise<void> } | null = null;
+  const closeProxy = async (): Promise<void> => {
+    const closing = proxy?.close() ?? Promise.resolve();
+    proxy = null;
+    await closing;
+  };
+  // 2 s between SIGTERM and SIGKILL, not `stopProcess`'s 5 s default: this
+  // runs as ONE TASK of the session's shutdown list, which bounds each task at
+  // 4 s so the whole shutdown fits inside `vgai close`'s 5.5 s grace. The
+  // escalation must COMPLETE inside that window — the REH is detached into its
+  // own process group, so the group SIGKILL `vgai close` sends at 5.5 s never
+  // reaches it, and a REH that outlives this process is an orphan on the
+  // reserved `frame` port that refuses the next `vgai edit` by name (measured
+  // 2026-09-21 under load average ~30).
+  const stopServer = (): Promise<void> => stopProcess(reh, 2_000);
+  const stop = async (): Promise<void> => {
+    await Promise.all([closeProxy(), stopServer()]);
+  };
+  try {
+    await waitForPort(launch.rehPort, 'the Code-OSS server', reh, 300_000);
+    log(
+      `frame: one-origin proxy on ${launch.proxyPort} → workbench ${launch.rehPort} + session ${sessionPort}`,
+    );
+    const started = await startFrameProxy({
+      port: launch.proxyPort,
+      upstreamPort: launch.rehPort,
+      sessionPort,
+      projectRoot,
+      // WHICH WAY ROUND THE PAGE PAINTS, from the product resolved above —
+      // the same read that decides which workbench may spawn decides the
+      // workbench's first frame, so there is one resolution and not two.
+      colorTheme: product?.colorTheme ?? null,
+      log,
+    });
+    proxy = started;
+    return {
+      identity: {
+        kind: workbench.kind,
+        dir: workbench.dir,
+        commit: workbench.commit,
+        product: workbench.product,
+      },
+      url: started.url,
+      stopServer,
+      closeProxy,
+      stop,
+    };
+  } catch (error) {
+    await stop();
+    throw error;
+  }
+}

package/server/frontend-handoff.ts

@@ -0,0 +1,229 @@
+/**
+ * THE AI IN THE TAB GETS ITS RUNTIME FROM THE SESSION, AT SPAWN.
+ *
+ * ARCHITECTURE-CORE §The core is Code-OSS, rule 7: the agent's front end is the
+ * workbench's own Chat view, filled by `sdk/frontend-vscode`, and its back end is
+ * the harness runtime this session already runs. This module is the wire between
+ * them, and it is four environment variables.
+ *
+ * WHY ENV, AND WHY AT SPAWN. The extension's second connection path (its README,
+ * "The runtime's environment handover") reads `SUPERCODE_FRONTEND_URL`,
+ * `_CLIENT_ID`, `_CREDENTIAL_FILE` and `_PERMISSIONS` from the EXTENSION HOST's
+ * environment at activation — the same shape supercode's own CLI uses to launch
+ * the pi frontend, without the `PI` infix. A Code-OSS server passes its
+ * environment to its extension host, and `frame-workbench.ts` spawns that server,
+ * so the handover costs no pasted token and no route of ours. The price is that
+ * env is FIXED AT SPAWN: whatever the runtime is when the REH starts is what the
+ * panel gets, which is why the session starts the runtime first.
+ *
+ * WHY THE SESSION MINTS RATHER THAN FORWARDS. The runtime's receipt carries a
+ * BOOTSTRAP bearer (`crates/harness/src/live_runtime.rs`), and handing that to a
+ * frontend would give it the runtime's own authority. Every supercode frontend
+ * instead asks the runtime's loopback mint door for a credential scoped to its
+ * own client id and grant, and gives it back on the way out. That door's reader
+ * and caller are supercode's, not ours —
+ * `@volter-ai-dev/supercode-harness-sdk/live-runtime`, extracted there from
+ * `sdk/teams`'s HTTP door when this became its second consumer.
+ *
+ * WHAT THE SESSION NEVER DOES is read the credential file back. It receives 64
+ * hex bytes from the mint door, writes them 0600 where only this user can read
+ * them, and hands over the PATH; the extension re-checks the file's identity
+ * across the open (`sdk/frontend-vscode`'s `credential.ts`).
+ *
+ * RESOURCE OWNERSHIP, stated once:
+ *  - OWNER: the `HarnessChatService` that minted it. It holds exactly one
+ *    handoff at a time and replaces it only by disposing the previous one.
+ *  - SHARERS: the REH child, which received the path in its environment and may
+ *    re-read it across an extension-host reload for as long as the session lives.
+ *  - THE ONE TEARDOWN: `dispose()`, called from the service's `close()` — the
+ *    same shutdown list that stops the REH. Nothing else may revoke it, because
+ *    a revoked grant with a live panel is a chat that has silently gone deaf.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { chmodSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/** `observe` watches, `interact` sends, `approve` answers a permission request.
+ *  `terminate` is deliberately NOT here: the panel may drive the agent and answer
+ *  for it, and may not kill the session the terminal and the CLI also hold. */
+export const FRONTEND_PERMISSIONS = 'observe,interact,approve';
+
+/**
+ * THE OTHER HALF OF THE HANDOVER: why there is no runtime, when there is none.
+ *
+ * The four `SUPERCODE_FRONTEND_*` variables above hand the extension a runtime. This one hands
+ * it the SENTENCE instead — B9c's refusal, which names the harness and its own login command —
+ * and `sdk/frontend-vscode` 0.1.3 reads it at activation and shows it as the session's first
+ * turn. Without it the Chat view was indistinguishable from a working one: "Build with Agent"
+ * and a live input over an agent that would never answer (measured on the 0.1.1 bytes, gate 6).
+ *
+ * It is never set beside the four: a handoff either carries a runtime or carries the reason it
+ * does not.
+ */
+export const FRONTEND_UNAVAILABLE_ENV = 'SUPERCODE_FRONTEND_UNAVAILABLE';
+
+/** The four variables, and the one call that ends the grant they carry. */
+export interface FrontendHandoff {
+  /** Spread into the REH spawn's environment. Empty means there is nothing to hand over. */
+  readonly env: Readonly<Record<string, string>>;
+  /** The client id the runtime's lease coordinator will see. */
+  readonly clientId: string;
+  /** True when the runtime's mint door answered; false when it 404'd and the receipt's own
+   *  bearer was handed over instead (see the measurement in `mintFrontendHandoff`). */
+  readonly minted: boolean;
+  /** Revoke the grant and delete the credential file. Idempotent. */
+  dispose(): Promise<void>;
+}
+
+interface LiveRuntimeReceipt {
+  readonly base_url: string;
+  readonly token: string;
+}
+
+interface LiveRuntimeDoor {
+  findLiveReceipt(runtimeId: string, env?: NodeJS.ProcessEnv): LiveRuntimeReceipt | null;
+  mintFrontendCredential(
+    receipt: LiveRuntimeReceipt,
+    options: { clientId: string; grant: 'interactive' | 'observer' },
+  ): Promise<string>;
+  revokeFrontendCredential(
+    receipt: LiveRuntimeReceipt,
+    options: { clientId: string },
+  ): Promise<number | undefined>;
+}
+
+function moduleCandidate(root: string | undefined, file: string): string[] {
+  if (!root) return [];
+  return [root.endsWith('.mjs') ? root : join(root, file)];
+}
+
+/**
+ * The supercode door, resolved the way every other optional supercode import in
+ * this server is: the published package first, a sibling checkout after, and a
+ * refusal that names every location tried rather than an opaque `ERR_MODULE_NOT_FOUND`.
+ */
+async function importLiveRuntimeDoor(engineRoot: string): Promise<LiveRuntimeDoor> {
+  const sibling = join(dirname(engineRoot), 'supercode', 'sdk', 'typescript', 'live-runtime.mjs');
+  const cwdSibling = join(
+    dirname(resolve(process.cwd())),
+    'supercode',
+    'sdk',
+    'typescript',
+    'live-runtime.mjs',
+  );
+  const failures: string[] = [];
+  for (const candidate of [
+    ...moduleCandidate(process.env['SUPERCODE_SDK_PATH'], 'live-runtime.mjs'),
+    '@volter-ai-dev/supercode-harness-sdk/live-runtime',
+    sibling,
+    cwdSibling,
+  ]) {
+    try {
+      const specifier = candidate.startsWith('/') ? pathToFileURL(candidate).href : candidate;
+      const module = (await import(specifier)) as Partial<LiveRuntimeDoor>;
+      if (module.findLiveReceipt && module.mintFrontendCredential && module.revokeFrontendCredential) {
+        return module as LiveRuntimeDoor;
+      }
+      failures.push(`${candidate}: missing findLiveReceipt/mintFrontendCredential/revokeFrontendCredential`);
+    } catch (error) {
+      failures.push(`${candidate}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  throw new Error(
+    `The supercode live-runtime door could not be loaded, so the Chat view has no runtime to attach to. Tried:\n  ${failures.join('\n  ')}`,
+  );
+}
+
+/**
+ * Mint one scoped credential for a runtime this session started, and return the
+ * environment the extension host reads at activation.
+ *
+ * `runtimeSessionId` is `ManagedRuntime.handle.runtime_id` — the same string the
+ * runtime wrote into its receipt as `runtime_session_id`.
+ */
+export async function mintFrontendHandoff(options: {
+  readonly engineRoot: string;
+  readonly runtimeSessionId: string;
+  /** Where the 0600 credential goes. One directory per session, removed with it. */
+  readonly directory: string;
+}): Promise<FrontendHandoff> {
+  const door = await importLiveRuntimeDoor(options.engineRoot);
+  const receipt = door.findLiveReceipt(options.runtimeSessionId);
+  if (!receipt) {
+    throw new Error(
+      `Supercode registered no live receipt for runtime ${options.runtimeSessionId}, so there is nothing for the Chat view to attach to.`,
+    );
+  }
+  const clientId = `vgai-editor-${process.pid}-${randomUUID().slice(0, 8)}`;
+  // THERE ARE TWO HTTP SERVERS IN A SUPERCODE RUNTIME, and a MANAGED runtime's receipt
+  // points at the one WITHOUT the mint door. Measured against supercode 0.4.36 on
+  // 2026-09-21, on a runtime started through `startManagedRuntime`:
+  //
+  //   POST /rpc                                    200   (frontend.v2.describe answered)
+  //   POST /_supercode/frontend-credentials/mint   404   {"error":"not found"}
+  //   …the same path with no bearer                401   — so it IS supercode's server
+  //
+  // `crates/harness/src/server.rs`: `handle_http_conn` (~:2611) serves the mint door and is
+  // what `supercode serve` runs; `handle_frontend_http_conn` (~:2962) is what
+  // `insert_hosted_runtime` starts and registers in the receipt, and it serves `POST /rpc`,
+  // `GET /frontend/events` and the observer assets — everything else is that 404.
+  //
+  // So the credential is minted WHEN THE DOOR EXISTS and is the receipt's own bearer when it
+  // does not. That is not an invention: it is supercode's own fallback, transcribed from
+  // `sdk/teams`'s HTTP door (`if (!/^mint 404/.test(error.message)) throw error;`), and it is
+  // still SCOPED — the generated frontend client sends `x-supercode-client-id` and
+  // `x-supercode-permissions` on every request (`sdk/frontend/client.mjs` :104-105), and
+  // `coordinated_http_client` (~:2491) takes the supplied id for an unbound credential and
+  // RESTRICTS the authorization to the header's permissions. What the fallback loses is the
+  // server-side BINDING: a client that stripped those headers would keep the bootstrap's
+  // authorization. Serving the mint door on the frontend server is supercode's to add.
+  let token: string;
+  let minted: boolean;
+  try {
+    token = await door.mintFrontendCredential(receipt, { clientId, grant: 'interactive' });
+    minted = true;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!/^mint 404/.test(message)) throw error;
+    token = receipt.token;
+    minted = false;
+  }
+  // The reader's own rules (`sdk/frontend-vscode`'s `credential.ts`): a regular,
+  // private, single-linked file of exactly 64 lowercase hex bytes. Checked HERE too,
+  // because a malformed secret should name the door it came from rather than surface later
+  // as "the credential is malformed" from inside an extension host with no logs a person reads.
+  if (!/^[0-9a-f]{64}$/.test(token)) {
+    throw new Error(
+      `The runtime's ${minted ? 'mint door' : 'receipt'} carried ${token.length} bytes that are not 64 hex characters; the Chat view's credential reader would refuse them.`,
+    );
+  }
+  mkdirSync(options.directory, { recursive: true, mode: 0o700 });
+  chmodSync(options.directory, 0o700);
+  const credentialFile = join(options.directory, 'frontend-credential');
+  // `mode` on `writeFileSync` is masked by the umask, so the chmod is not redundant:
+  // a 0022 umask would leave 0644 and the extension refuses a world-readable credential.
+  writeFileSync(credentialFile, token, { mode: 0o600 });
+  chmodSync(credentialFile, 0o600);
+  let disposed = false;
+  return {
+    env: {
+      SUPERCODE_FRONTEND_URL: receipt.base_url,
+      SUPERCODE_FRONTEND_CLIENT_ID: clientId,
+      SUPERCODE_FRONTEND_CREDENTIAL_FILE: credentialFile,
+      SUPERCODE_FRONTEND_PERMISSIONS: FRONTEND_PERMISSIONS,
+    },
+    clientId,
+    minted,
+    async dispose() {
+      if (disposed) return;
+      disposed = true;
+      rmSync(options.directory, { recursive: true, force: true });
+      // Only a MINTED grant is ours to give back; the receipt's own bearer is the runtime's
+      // and dies with it. A runtime that has already exited cannot take anything back either,
+      // and saying so would be reporting the shutdown we are already performing.
+      if (minted) await door.revokeFrontendCredential(receipt, { clientId }).catch(() => undefined);
+    },
+  };
+}

package/server/game-globals-shadow.ts

@@ -0,0 +1,113 @@
+/**
+ * Pure predicate for the `vgai-game-globals` Vite plugin in `dev.ts` — split
+ * out into its own side-effect-free module so it's unit-testable without
+ * booting Vite/Express (`dev.ts`'s module top-level calls `main()`, which
+ * starts real servers — importing it directly in a test would do that).
+ *
+ * The prelude used to be scoped to `projectRoots` alone (an opened project's
+ * own `/src/`), which covers first-party project code and play-mode's game
+ * examples but NOT the in-tree ingest fixtures' same-realm
+ * ingest-fixture entry modules — those live under this EDITOR
+ * PACKAGE's own `packages/editor/src/ingest/games/**` tree (every surface —
+ * holds the former `games-2d`/`games-react` siblings),
+ * which `ingest/registry.ts` pulls into the SAME Vite module graph via
+ * `import.meta.glob` (they are ordinary `/src/` modules Vite already knows
+ * about statically — not an external project folder), so they were served
+ * UNSHADOWED: a vendored game's raw `window`/`document` input listeners ran
+ * for its entire mount regardless of editor focus.
+ */
+import path from 'node:path';
+import { isEditorLanePath } from '@volter/editor-sdk/session/tool-contribution-convention';
+import { isPathInside } from './server-utils';
+
+/**
+ * The same-realm ingest-fixture root, given this editor package's own `src/`
+ * directory. Fixed (not runtime-discovered) — this folder is part of THIS
+ * package's source tree, not a project a user opens. It was a LIST of two
+ * once the per-library fixture directories merged into one; the
+ * signature stays plural because the caller wires an array of roots and
+ * nothing is gained by narrowing it.
+ */
+export function ingestGameShadowRoots(editorSrcRoot: string): string[] {
+  return [
+    path.resolve(editorSrcRoot, 'ingest/games'),
+    // THE GAME'S OWN SOURCE, which until now was the half that got missed.
+    // The root above covers only the host-authored manifest folder — the
+    // entry shim, a contract shim — while every line of the game itself lives
+    // under `vendor/games/<id>/src/`, outside it. A source-vendored game
+    // therefore ran its raw `window`/`document` listeners and its own rAF
+    // loop UNSHADOWED for its entire mount, so play-mode's input gate and
+    // pause reached nothing in it. Measured on the racing-game ingest, whose
+    // `controls/Keyboard.ts` binds `window.addEventListener('keydown')`
+    // directly and whose Vehicle drives a `useFrame` loop: with only the
+    // manifest folder shadowed, `editor.pause()` left the coverage `loop` row
+    // at `loop: null` — the host held no gate over it.
+    //
+    // Bundle-vendored games are deliberately NOT covered: they are BUILT
+    // output under `public/ingest/<id>/`, which `isShadowableModulePath`
+    // already declines (no `/src/` segment) and which the prelude's lexical
+    // shadow is not safe to prepend to anyway.
+    path.resolve(editorSrcRoot, '../../../vendor/games'),
+  ];
+}
+
+/**
+ * True if `file` is a `/src/` TS/JS module — the shape the prelude assumes
+ * (a lexically-scoped `const window=…,document=…;` prepended to the top of
+ * the module body; see `gated-globals.ts`'s doc comment for why that's safe
+ * even ahead of the module's own `import` statements).
+ *
+ * DEPENDENCY CODE IS NEVER THE PROJECT'S OWN, and the `/src/` test alone does
+ * not say so: a project whose own path contains a `src` segment makes every
+ * file under its `node_modules/` match — including Vite's project-local
+ * optimized-deps cache (`<project>/node_modules/.vite-editor/deps/three.js`,
+ * `editorViteCacheDir`). Measured on an ingest whose manifest folder lives
+ * under `packages/editor/src/ingest/games/`: the prebundled
+ * `three.js` was instrumented by `vite-plugin-creation-site`, so
+ * `DRACOLoader`'s worker — which it builds by `DRACOWorker.toString()` and
+ * hands to a Blob URL — carried the recorder identifier into a realm that has
+ * no such binding. `__vgaiCS$ is not defined` in a `blob:` URL, every Draco
+ * mesh failed to decode, `useGLTF` suspended forever, and the scene mounted
+ * EMPTY with no error naming any of it. Ordinary projects were safe only by
+ * accident of their path.
+ */
+export function isShadowableModulePath(file: string): boolean {
+  if (file.includes('/node_modules/') || isEditorLanePath(file)) return false;
+  return /\.(ts|tsx|js|jsx)$/.test(file) && file.includes('/src/');
+}
+
+/**
+ * True if `file` should get the `GAME_GLOBALS_PRELUDE` shadow prepended:
+ * a shadowable module path under any of `roots` (an opened project's root,
+ * or one of {@link ingestGameShadowRoots}).
+ */
+export function shouldShadowGameGlobals(file: string, roots: Iterable<string>): boolean {
+  if (!isShadowableModulePath(file)) return false;
+  // Containment, not a string prefix: a bare `startsWith` shadows every module
+  // of the SIBLING project `<root>-old/src/…` as if it belonged to `<root>`.
+  for (const root of roots) {
+    if (isPathInside(root, file)) return true;
+  }
+  return false;
+}
+
+/** A project (or ingest-fixture) stylesheet, not a dependency. */
+export function isGameCssPath(file: string): boolean {
+  return file.endsWith('.css') && !file.includes('/node_modules/') && !isEditorLanePath(file);
+}
+
+/**
+ * True if Vite-imported game CSS must be rewritten into `@scope` so
+ * `html`/`body`/`*` rules cannot restyle the editor document. The sibling
+ * of {@link shouldShadowGameGlobals} for stylesheets: first-party worlds
+ * `import './style.css'`, which Vite injects as a page sheet unless this
+ * transform contains it the same way `server/scoped-game-css.ts` contains
+ * a declared ingest stylesheet.
+ */
+export function shouldScopeGameCss(file: string, roots: Iterable<string>): boolean {
+  if (!isGameCssPath(file)) return false;
+  for (const root of roots) {
+    if (isPathInside(root, file)) return true;
+  }
+  return false;
+}