@volter/sdk 0.0.0-stage → 0.5.204

package/src/kit/finders/scenes-from-entrypoint-selection.ts

@@ -0,0 +1,387 @@
+/**
+ * FINDER — scenes from the entrypoint's active-scene selection.
+ *
+ * ARCHITECTURE-CORE §The editor protocol, "Zero inference": discovery may be a
+ * LIBRARY, and this is one. It only ever runs because an adapter SELECTED it
+ * (`{ finder: 'scenesFromEntrypointSelection', … }`); the engine never runs a
+ * finder nobody selected, which `packages/engine/test/finder-import-boundary.test.ts`
+ * enforces mechanically rather than by policy.
+ *
+ * Why the ENTRYPOINT and not a folder: it is a LOAD-BEARING source — a
+ * reference the game itself executes. The review test is "would the game break
+ * if this fact lied?", and here it would: change the entrypoint's selection
+ * table and the game changes with it. A `src/scenes/` convention can drift
+ * silently; this cannot.
+ *
+ * Two answers, and the difference is declared rather than sniffed:
+ *   - the adapter names a `selection` identifier ⇒ read that module-level
+ *     table and answer one entry per key, each reachable through it — plus
+ *     WHICH key the entrypoint indexes it with right now (`scenes[activeScene]`
+ *     → `const activeScene = 'main'`), marked `reach.active`. That reference is
+ *     load-bearing for the same reason the table is: the running world renders
+ *     exactly that key's composition, which is why the host can treat the
+ *     active entry as the region's own standing document rather than a second
+ *     tab beside it;
+ *   - the adapter names none ⇒ the entrypoint mounts ONE composition, and the
+ *     answer is the single-scene DEGENERATE table: the region's own
+ *     composition, opened by mounting the region.
+ *
+ * ON `typescript`: this module parses the entrypoint's own TSX with the
+ * TypeScript compiler API — the same parser `packages/sdk/src/kit/ui-source/
+ * oid-transform.ts` and `packages/sdk/src/kit/asset-workflow/project-content.ts`
+ * already use for exactly this kind of question (volter has `typescript`; it does
+ * NOT have @babel/*). It is a HOST-SIDE-ONLY dependency: finders are importable
+ * only by the adapter loader, `adapter-module.ts` imports nothing from this
+ * directory, and a game's `editor/volter.adapter.ts` therefore never pulls a parser into
+ * its own bundle.
+ */
+
+import {
+  indexingIdentifier,
+  propertyKey,
+  selectionTable,
+} from '@volter/sdk/session/entrypoint-selection-readers';
+import type {
+  DocumentEntry,
+  SceneSource,
+  ScenesFromEntrypointSelectionParams,
+} from '@volter/project/adapter/adapter-module';
+import { EXPORTED_COMPOSITION_REGIONS } from '@volter/project/adapter/adapter-module';
+import type { FinderResult } from '@volter/project/adapter/finders/finder-result';
+import ts from 'typescript';
+
+/** One region's entrypoint, as the host reads it off the manifest + disk. */
+export interface EntrypointSource {
+  /** The region (== manifest root) id. */
+  readonly regionId: string;
+  /** Project-relative path of the root's `entry` module. */
+  readonly path: string;
+  /** The module's bytes; `null` when they could not be read. */
+  readonly source: string | null;
+}
+
+export interface ScenesFromEntrypointSelectionInput {
+  /**
+   * Every region the host mounts from an exported composition (a root with an
+   * `entry`), in manifest order.
+   */
+  readonly entrypoints: readonly EntrypointSource[];
+  /**
+   * Resolve one of the entrypoint's own import specifiers to a project-relative
+   * path. Supplied by the host because extension/index resolution is a
+   * filesystem question and this function is pure. Absent, or answering `null`,
+   * means the produced entry carries no `source` — an honest omission rather
+   * than a guessed path.
+   */
+  readonly resolveModule?: (specifier: string, fromPath: string) => string | null;
+}
+
+/** Strip the directory and extension from a project-relative path. */
+function basename(path: string): string {
+  const file = path.replaceAll('\\', '/').split('/').pop() ?? path;
+  return file.replace(/\.[jt]sx?$/, '');
+}
+
+function parse(path: string, source: string): ts.SourceFile {
+  return ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+}
+
+/**
+ * The name the module's own default export carries — the game's own word for
+ * this composition, so the editor's tab reads `World`, not `world.tsx`.
+ * `undefined` when the default export is anonymous or absent.
+ */
+function defaultExportName(sf: ts.SourceFile): string | undefined {
+  for (const statement of sf.statements) {
+    if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
+      const expression = statement.expression;
+      if (ts.isIdentifier(expression)) return expression.text;
+      continue;
+    }
+    const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : undefined;
+    const isDefault = modifiers?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword);
+    if (!isDefault) continue;
+    if (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) {
+      return statement.name?.text;
+    }
+  }
+  return undefined;
+}
+
+/** Local identifier -> the import it came from. */
+interface ImportedBinding {
+  readonly specifier: string;
+  /** The exported name this binding reads; `undefined` for a default import. */
+  readonly exported?: string;
+}
+
+function recordClauseBindings(
+  clause: ts.ImportClause,
+  specifier: string,
+  bindings: Map<string, ImportedBinding>,
+): void {
+  if (clause.name) bindings.set(clause.name.text, { specifier });
+  const named = clause.namedBindings;
+  if (!named || !ts.isNamedImports(named)) return;
+  for (const element of named.elements) {
+    bindings.set(element.name.text, {
+      specifier,
+      exported: (element.propertyName ?? element.name).text,
+    });
+  }
+}
+
+function importedBindings(sf: ts.SourceFile): Map<string, ImportedBinding> {
+  const bindings = new Map<string, ImportedBinding>();
+  for (const statement of sf.statements) {
+    if (!ts.isImportDeclaration(statement) || !statement.importClause) continue;
+    if (!ts.isStringLiteral(statement.moduleSpecifier)) continue;
+    recordClauseBindings(statement.importClause, statement.moduleSpecifier.text, bindings);
+  }
+  return bindings;
+}
+
+/**
+ * The string a module-level `const <name> = '…'` binds, or `undefined`.
+ *
+ * `const` and a STRING LITERAL are both required: a `let` can be reassigned and
+ * a computed initializer is not a fact the source states, so neither can be
+ * reported as the key the game executes. A type annotation
+ * (`const activeScene: keyof typeof scenes = 'main'`) is irrelevant here — the
+ * initializer is what runs.
+ */
+function moduleLevelString(sf: ts.SourceFile, name: string): string | undefined {
+  for (const statement of sf.statements) {
+    if (!ts.isVariableStatement(statement)) continue;
+    if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || declaration.name.text !== name) continue;
+      const initializer = declaration.initializer;
+      if (initializer && ts.isStringLiteral(initializer)) return initializer.text;
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * WHICH key the entrypoint mounts at its slot right now, read off the source
+ * the game itself executes.
+ *
+ * Every failure is a NOTE and answers `undefined`: an unread active key costs
+ * a retitle, while a guessed one would open the wrong composition as the
+ * region's own document.
+ */
+function activeSelectionKey(
+  entrypoint: EntrypointSource,
+  sf: ts.SourceFile,
+  selection: string,
+  keys: readonly string[],
+  notes: string[],
+): string | undefined {
+  const identifier = indexingIdentifier(sf, selection);
+  if (identifier === undefined) {
+    notes.push(
+      `scenesFromEntrypointSelection: ${entrypoint.path} never indexes \`${selection}\`, so ` +
+        'which of its compositions the entrypoint mounts is not stated in the source and no ' +
+        'entry is settled as the active one.',
+    );
+    return undefined;
+  }
+  if (identifier === null) {
+    notes.push(
+      `scenesFromEntrypointSelection: ${entrypoint.path} indexes \`${selection}\` with ` +
+        'something other than one single identifier, so the key it mounts cannot be read ' +
+        'statically.',
+    );
+    return undefined;
+  }
+  const key = moduleLevelString(sf, identifier);
+  if (key === undefined) {
+    notes.push(
+      `scenesFromEntrypointSelection: ${entrypoint.path} indexes \`${selection}\` with ` +
+        `\`${identifier}\`, which is not a module-level \`const\` bound to a string literal, ` +
+        'so the key it mounts cannot be read statically.',
+    );
+    return undefined;
+  }
+  if (!keys.includes(key)) {
+    notes.push(
+      `scenesFromEntrypointSelection: ${entrypoint.path} mounts \`${selection}\` under ` +
+        `"${key}", which is not a key of that table. The entrypoint and its own selection ` +
+        'table disagree.',
+    );
+    return undefined;
+  }
+  return key;
+}
+
+/** The identifier a selection entry's value names, if it names one at all. */
+function propertyIdentifier(property: ts.ObjectLiteralElementLike): string | undefined {
+  if (ts.isShorthandPropertyAssignment(property)) return property.name.text;
+  if (ts.isPropertyAssignment(property) && ts.isIdentifier(property.initializer)) {
+    return property.initializer.text;
+  }
+  return undefined;
+}
+
+function sourceFor(
+  binding: ImportedBinding | undefined,
+  fromPath: string,
+  resolveModule: ScenesFromEntrypointSelectionInput['resolveModule'],
+): SceneSource | undefined {
+  if (!binding || !resolveModule) return undefined;
+  const path = resolveModule(binding.specifier, fromPath);
+  if (!path) return undefined;
+  return binding.exported === undefined ? { path } : { path, export: binding.exported };
+}
+
+/**
+ * Which entrypoints this selection targets.
+ *
+ * The RULE form is every exported-composition region. A named region with no
+ * matching entrypoint becomes a note, not a silent omission.
+ */
+function targetedEntrypoints(
+  params: ScenesFromEntrypointSelectionParams,
+  entrypoints: readonly EntrypointSource[],
+  notes: string[],
+): EntrypointSource[] {
+  if (params.regions === EXPORTED_COMPOSITION_REGIONS) {
+    return [...entrypoints];
+  }
+  const found: EntrypointSource[] = [];
+  for (const regionId of params.regions) {
+    const match = entrypoints.find((entry) => entry.regionId === regionId);
+    if (match) found.push(match);
+    else {
+      notes.push(
+        `scenesFromEntrypointSelection: region "${regionId}" is selected but the project ` +
+          'declares no root with that id and an entry.',
+      );
+    }
+  }
+  return found;
+}
+
+/** DEGENERATE: the entrypoint mounts one composition, and mounting the region
+ *  IS opening it. Labelled by the module's own default export — the game's own
+ *  word for this composition. */
+function degenerateEntry(entrypoint: EntrypointSource, sf: ts.SourceFile): DocumentEntry {
+  return {
+    id: entrypoint.regionId,
+    label: defaultExportName(sf) ?? basename(entrypoint.path),
+    kind: 'scene',
+    region: entrypoint.regionId,
+    authorable: true,
+    reach: { kind: 'root-mount' },
+    source: { path: entrypoint.path },
+    finder: 'scenesFromEntrypointSelection',
+  };
+}
+
+/**
+ * One entry per key of the entrypoint's own selection table, plus WHICH of
+ * them the entrypoint currently mounts at the slot (`active`).
+ */
+function selectionEntries(
+  entrypoint: EntrypointSource,
+  sf: ts.SourceFile,
+  selection: string,
+  resolveModule: ScenesFromEntrypointSelectionInput['resolveModule'],
+  notes: string[],
+): { entries: DocumentEntry[]; active: string | undefined } {
+  const table = selectionTable(sf, selection);
+  if (!table) {
+    notes.push(
+      `scenesFromEntrypointSelection: ${entrypoint.path} declares no module-level ` +
+        `\`const ${selection} = { … }\` selection table. Nothing is assumed in its ` +
+        'place — fix the adapter’s `selection` or the entrypoint.',
+    );
+    return { entries: [], active: undefined };
+  }
+
+  const bindings = importedBindings(sf);
+  const keys: string[] = [];
+  const built: { key: string; label: string; source: SceneSource | undefined }[] = [];
+  for (const property of table.properties) {
+    const key = propertyKey(property);
+    if (key === undefined) {
+      notes.push(
+        `scenesFromEntrypointSelection: ${entrypoint.path}'s \`${selection}\` has an ` +
+          'entry whose key is computed, so it cannot be named statically.',
+      );
+      continue;
+    }
+    const identifier = propertyIdentifier(property);
+    keys.push(key);
+    built.push({
+      key,
+      label: identifier ?? key,
+      source: sourceFor(
+        identifier ? bindings.get(identifier) : undefined,
+        entrypoint.path,
+        resolveModule,
+      ),
+    });
+  }
+
+  const active = activeSelectionKey(entrypoint, sf, selection, keys, notes);
+  const entries = built.map(({ key, label, source }) => ({
+    id: key,
+    label,
+    kind: 'scene' as const,
+    region: entrypoint.regionId,
+    authorable: true,
+    reach: {
+      kind: 'entrypoint-selection' as const,
+      selection,
+      key,
+      ...(key === active ? { active: true } : {}),
+    },
+    ...(source ? { source } : {}),
+    finder: 'scenesFromEntrypointSelection' as const,
+  }));
+  return { entries, active };
+}
+
+/**
+ * Answer the scene table this finder's selection describes.
+ *
+ * Pure: every input is passed in, nothing is read from disk, and an
+ * unanswerable question becomes a NOTE rather than a fabricated entry.
+ */
+export function scenesFromEntrypointSelection(
+  params: ScenesFromEntrypointSelectionParams,
+  input: ScenesFromEntrypointSelectionInput,
+): FinderResult {
+  const notes: string[] = [];
+  const entries: DocumentEntry[] = [];
+  const active: string[] = [];
+
+  for (const entrypoint of targetedEntrypoints(params, input.entrypoints, notes)) {
+    if (entrypoint.source === null) {
+      notes.push(
+        `scenesFromEntrypointSelection: could not read ${entrypoint.path} (region ` +
+          `"${entrypoint.regionId}"), so its scenes are unknown — not empty.`,
+      );
+      continue;
+    }
+    const sf = parse(entrypoint.path, entrypoint.source);
+    if (params.selection === undefined) {
+      entries.push(degenerateEntry(entrypoint, sf));
+      continue;
+    }
+    const found = selectionEntries(entrypoint, sf, params.selection, input.resolveModule, notes);
+    entries.push(...found.entries);
+    if (found.active !== undefined) active.push(found.active);
+  }
+
+  // The ACTIVE key settles the default outright: the entrypoint states which
+  // composition it mounts, so this is the finder READING an answer rather than
+  // choosing between candidates. Failing that, one candidate settles it; two or
+  // more is a choice, and a choice belongs to the adapter author.
+  const settled =
+    active.length === 1 ? active[0] : entries.length === 1 ? entries[0]?.id : undefined;
+  return settled !== undefined ? { entries, default: settled, notes } : { entries, notes };
+}

package/src/kit/frame/frame-parts.ts

@@ -0,0 +1,30 @@
+/**
+ * WHETHER THE WORKBENCH IS SHOWING A PART — the one fact about the Code-OSS frame's layout a page
+ * module needs without importing the bridge. The bridge records each part as the workbench offers
+ * or withdraws it (`bridge.tsx`'s `offerVolterPart`); `null` means there is no frame, and the
+ * editor's panels are in the page.
+ */
+let framed = false;
+const shown = new Set<string>();
+const listeners = new Set<() => void>();
+
+/** The bridge: a part was offered (`true`) or withdrawn (`false`). */
+export function setFramePartShown(part: string, isShown: boolean): void {
+  framed = true;
+  if (shown.has(part) === isShown) return;
+  if (isShown) shown.add(part);
+  else shown.delete(part);
+  for (const listener of listeners) listener();
+}
+
+/** Whether the frame shows `part`; `null` without a frame. */
+export function framePartShown(part: string): boolean | null {
+  return framed ? shown.has(part) : null;
+}
+
+export function subscribeFrameParts(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}

package/src/kit/framed-document-capture.ts

@@ -0,0 +1,34 @@
+/**
+ * A document whose subject runs in a same-origin frame (the Build Player runs
+ * the project's own build in one) registers that frame here, so the capture
+ * door photographs what runs inside it: the composite of the frame's own
+ * document, not the editor's DOM around an `<iframe>` it cannot see into.
+ *
+ * `canvasFrame` is the composite's same-frame seam (`CaptureOptions`): the
+ * frame's canvases are its game's, created without `preserveDrawingBuffer`,
+ * so only the frame can copy them right after it renders.
+ */
+
+export interface FramedCapture {
+  /** The element of the frame's document to composite. */
+  readonly container: () => HTMLElement | null;
+  readonly canvasFrame: (canvas: HTMLCanvasElement) => Promise<CanvasImageSource | null>;
+}
+
+const framed = new WeakMap<HTMLIFrameElement, FramedCapture>();
+
+export function registerFramedCapture(frame: HTMLIFrameElement, capture: FramedCapture): void {
+  framed.set(frame, capture);
+}
+
+/** The framed subject inside a document's content, when it has one. */
+export function framedCapture(
+  content: HTMLElement,
+): { readonly container: HTMLElement; readonly canvasFrame: FramedCapture['canvasFrame'] } | null {
+  for (const frame of Array.from(content.querySelectorAll('iframe'))) {
+    const capture = framed.get(frame);
+    const container = capture?.container();
+    if (capture && container) return { container, canvasFrame: capture.canvasFrame };
+  }
+  return null;
+}

package/src/kit/game-globals-prelude.ts

@@ -0,0 +1,143 @@
+/**
+ * The lexical shadow prepended to every project/game module so `globalThis`,
+ * `window`, and `document` resolve to the mount's game realm instead of the
+ * real host objects. This is how raw listeners, timers, storage calls, and
+ * game-global properties stay attributable without touching editor globals.
+ *
+ * It lives in its own module, apart from `gated-globals.ts`, because it has THREE
+ * consumers spanning two TypeScript programs:
+ *   - `gated-globals.ts` (browser) re-exports it, and installs the proxies;
+ *   - `browser-transpile.ts` (browser) prepends it to client-transpiled source;
+ *   - `vite-plugin-game-globals.ts` (Node) prepends it at transform time, and is
+ *     reachable from `tsconfig.server.json` via `server/dev.ts`.
+ *
+ * That last one is the constraint: the server program compiles without the DOM
+ * lib, so it cannot pull in `gated-globals.ts` (whose proxy code names `window`,
+ * `document`, and `EventListenerOrEventListenerObject`). This module names none
+ * of them, so both programs can import the ONE definition. The dev server used to
+ * keep a hand-copied duplicate policed by a source-text sync test; extracting the
+ * constant deletes the copy and the test with it.
+ *
+ * Safe ahead of a module's own `import` statements: ESM imports are hoisted, so a
+ * leading `const window = …` still shadows for the whole module body. See
+ * `gated-globals.ts` for the proxy semantics it reaches.
+ *
+ * S-5 (the SimCity ingest ledger) added the SCHEDULING half. Shadowing `window`
+ * alone never reached a bare `setInterval(this.simulate, 1000)` — that resolves
+ * to the global binding, not to `window.setInterval` — which is exactly how a
+ * "gated" SimCity mount kept simulating after pause. The scheduling names are
+ * shadowed onto the same-realm loop gate
+ * (`ingest/same-realm-loop-gate.ts`, installed by `gated-globals.ts`), which is
+ * a pure pass-through until something holds it, so an ungated session's timing
+ * is unchanged. `.bind` is not optional: these are window methods and a bare
+ * call would hand them an `undefined` receiver ("Illegal invocation"), the same
+ * trap the `set` proxy's receiver comment records.
+ */
+/**
+ * MULTI-INSTANCE: the prelude for a module belonging to mount `mountId`.
+ *
+ * The mount id is BAKED IN at transform time rather than discovered at runtime
+ * from `import.meta.url`. Reading the module's own url would have worked —
+ * every project module under a mount already carries `?volter-mount=<id>` — and
+ * it needed no parameter. It was rejected because it silently constrains the
+ * prelude to ES-MODULE evaluation forever: `import.meta` is a SyntaxError in a
+ * `new Function` body, so any future non-module evaluation path would break at
+ * runtime with a message naming neither this file nor the reason. A test
+ * evaluating the prelude that way is what surfaced it. The transform already
+ * knows the mount id, so baking it costs one argument and keeps the prelude
+ * evaluable anywhere.
+ *
+ * With no mount id the same resolver selects the default realm. Hosted/client
+ * transpile paths therefore receive the same isolation semantics rather than
+ * a weaker fallback realm.
+ */
+export function gameGlobalsPrelude(mountId?: string): string {
+  const realm = `(__volterHost.__volterGameRealm?__volterHost.__volterGameRealm(${JSON.stringify(mountId ?? '')}):null)`;
+  return PRELUDE_HEAD.replace('__VOLTER_REALM__', realm);
+}
+
+/**
+ * The page's real global object, as an expression that names no identifier a project can shadow
+ * and compiles no code from a string.
+ *
+ * A module may itself declare `globalThis` (the prelude does), so reading the host through that
+ * identifier before its declaration would hit the declaration's TDZ. The expression instead puts
+ * a getter on `Object.prototype` for a moment and reads it as a bare name: a bare name that no
+ * scope declares is looked up on the global object, which inherits from `Object.prototype`, so the
+ * getter runs with the global object as `this`. It is the published `globalThis` polyfill
+ * (mathiasbynens.be/notes/globalthis), with `Object` itself reached through a literal. When
+ * `Object.prototype` will not take the getter (a project froze it), the global is read as `self`
+ * or `global` instead, so one project's freeze does not break every module that loads after it.
+ *
+ * It replaced a call of the Function constructor on the string 'return globalThis', which a
+ * content security policy without 'unsafe-eval' refuses: under such a policy every project module
+ * failed on its first line.
+ *
+ * This is lifecycle instrumentation, not a security sandbox: arbitrary same-realm code can reach
+ * the same object, which is why the architecture does not claim a browsing-context boundary.
+ */
+export const HOST_GLOBAL_EXPRESSION =
+  "(()=>{const O=({}).constructor;try{O.defineProperty(O.prototype,'__volterHostOf',{get(){return this},configurable:true});" +
+  'try{return __volterHostOf}finally{delete O.prototype.__volterHostOf}}' +
+  // A project may have frozen Object.prototype, and then the getter cannot be put there. The
+  // global is then read by a name the prelude itself does not declare: `self` (a window or a
+  // worker), then `global` (Node). Each is tried alone, because a project that declares the
+  // name makes even `typeof` of it throw until its declaration runs. `window` and `globalThis`
+  // are not tried: the prelude declares both in this same statement.
+  "catch(d){try{if(typeof self!=='undefined')return self}catch(s){}" +
+  "try{if(typeof global!=='undefined')return global}catch(g){}throw d}})()";
+
+/** How every prelude begins: the text a transform looks for to know a module already has one. */
+export const GAME_GLOBALS_PRELUDE_START = `const __volterHost=${HOST_GLOBAL_EXPRESSION},`;
+
+const PRELUDE_HEAD =
+  GAME_GLOBALS_PRELUDE_START +
+  '__volterR=__VOLTER_REALM__,' +
+  '__volterGlobal=((__volterR&&__volterR.globalThis)||__volterHost.__volterGameWindow||__volterHost),' +
+  'globalThis=__volterGlobal,' +
+  '__volterSched=((__volterR&&__volterR.timers)||__volterHost.__volterGameTimers||__volterHost),' +
+  // Bind or pass through UNCHANGED. `.bind` is not optional for a real window
+  // method — a bare call would hand it an `undefined` receiver ("Illegal
+  // invocation"), the same trap `gated-globals.ts`'s `set` trap records — but
+  // an environment missing the API entirely (a Node-side transpile test, a
+  // worker) must degrade at the CALL site, not explode at module load.
+  '__volterBind=function(n){var f=__volterSched[n];' +
+  "return typeof f==='function'?f.bind(__volterSched):f;}," +
+  'console=((__volterR&&__volterR.console)||__volterHost.__volterGameConsole||__volterHost.console),' +
+  'window=((__volterR&&__volterR.window)||__volterHost.__volterGameWindow||__volterGlobal.window),' +
+  'document=((__volterR&&__volterR.document)||__volterHost.__volterGameDocument||__volterGlobal.document),' +
+  '__volterWindowBind=function(n){var f=window&&window[n];' +
+  "return typeof f==='function'?f.bind(window):f;}," +
+  'localStorage=(window&&window.localStorage),' +
+  'sessionStorage=(window&&window.sessionStorage),' +
+  'location=(window&&window.location),' +
+  "addEventListener=__volterWindowBind('addEventListener')," +
+  "removeEventListener=__volterWindowBind('removeEventListener')," +
+  "dispatchEvent=__volterWindowBind('dispatchEvent')," +
+  // PROJECT-SCOPED fetch: `__volterProjectFetch`, when a host installs one,
+  // answers a root-absolute `fetch('/shaders/…')` from project code against
+  // the project's own files; everywhere else this binds the host's own fetch (bound
+  // to the REAL global: native fetch called on a proxied window receiver
+  // throws "Illegal invocation"). The browser twin of the dev server's
+  // `vite-plugin-project-root-absolute-assets` rule: a root-absolute request
+  // made BY PROJECT CODE resolves inside the project.
+  // RESOLVED AT CALL TIME, not at module evaluation. Binding the hook once,
+  // when the module evaluated, captured whatever existed THEN: a canvas
+  // project's world evaluated on RELOAD before the bridge had installed the
+  // hook, so Pixi's atlas fetch of `/sprites/survivor.json` went to the host
+  // and got the SPA's index.html — `Unexpected token '<'`, the scene gutted to
+  // one row (build-45 gate, 2026-09-02); and after a library download the
+  // bridge mints a NEW hook over a new url map, which an already-evaluated
+  // module would never see. Reading the host's property on every call keeps
+  // every module on the current bridge, with the same host-fetch fallback.
+  'fetch=function(){var f=__volterHost.__volterProjectFetch;' +
+  'return f?f.apply(null,arguments):__volterHost.fetch.apply(__volterHost,arguments)},' +
+  "setTimeout=__volterBind('setTimeout')," +
+  "clearTimeout=__volterBind('clearTimeout')," +
+  "setInterval=__volterBind('setInterval')," +
+  "clearInterval=__volterBind('clearInterval')," +
+  "requestAnimationFrame=__volterBind('requestAnimationFrame')," +
+  "cancelAnimationFrame=__volterBind('cancelAnimationFrame');\n";
+
+/** The no-mount prelude — the constant every existing consumer already uses. */
+export const GAME_GLOBALS_PRELUDE = gameGlobalsPrelude();

package/src/kit/game-surface-defaults.ts

@@ -0,0 +1,33 @@
+/**
+ * A game's DOM surface starts from a page's text defaults, as the game's
+ * `<body>` does when it ships: otherwise the editor's own typography (11px, its
+ * line height and colour) inherits into the game's DOM.
+ *
+ * The defaults are a ZERO-specificity rule (`:where(...)`), not inline style, so
+ * the game's own page rules win over them as they do in its build: a game's
+ * `html`/`body` rules arrive scoped as `:scope` (`scoped-game-css.ts`), on this
+ * same element, and an inline `font: initial` beat them — a game that sets its
+ * font on `body` rendered in the browser's default serif in the editor.
+ */
+
+/** The attribute that marks an element as a game's page surface. */
+export const GAME_SURFACE_ATTRIBUTE = 'data-volter-game-surface';
+
+const DEFAULTS_STYLE_MARK = 'data-volter-game-surface-defaults';
+
+const DEFAULTS_CSS =
+  `:where([${GAME_SURFACE_ATTRIBUTE}]){font:initial;color:initial;letter-spacing:normal;` +
+  'word-spacing:normal;text-align:start;text-indent:0;text-transform:none;' +
+  'white-space:normal;direction:ltr;cursor:auto}';
+
+/** Mark `element` as a game surface, installing the defaults rule once per document. */
+export function markGameSurface(element: HTMLElement): void {
+  const document = element.ownerDocument;
+  if (!document.querySelector(`style[${DEFAULTS_STYLE_MARK}]`)) {
+    const style = document.createElement('style');
+    style.setAttribute(DEFAULTS_STYLE_MARK, '');
+    style.textContent = DEFAULTS_CSS;
+    (document.head ?? document.documentElement).prepend(style);
+  }
+  element.setAttribute(GAME_SURFACE_ATTRIBUTE, '');
+}