@volter/editor-game 0.5.67 → 0.5.69

package/src/host/gated-globals.ts

@@ -248,7 +248,7 @@ function realmFunction(value: unknown, receiver: object): unknown {
  * one pauses its siblings. Neither is fixable in the presentation layer.
  *
  * The lookup key comes from the MODULE'S OWN URL: every project module served
- * under a mount carries `?vgai-mount=<id>` (the isolation transform), and the
+ * under a mount carries `?volter-mount=<id>` (the isolation transform), and the
  * prelude passes `import.meta.url` to {@link gameRealmForModuleUrl}. So a
  * module resolves its own realm with no plugin involvement and no threading.
  */
@@ -402,7 +402,7 @@ export function gameSurfaces(): { surface: HTMLElement; gate: () => boolean }[]
  */
 function gateFor(id: string): () => boolean {
   // AND THE SURFACE TERM (U2). `surfaceHoldsKeyboard()` is true standalone and
-  // under the frame is the workbench's own "is the vgai pane the active
+  // under the frame is the workbench's own "is the volter pane the active
   // editor?", so a keystroke aimed at Monaco in the group beside a running
   // game never reaches the game's listeners. It is read HERE, once, rather
   // than folded into each lane's own predicate, because this is the one place
@@ -434,7 +434,7 @@ function realmGenerationGate(id: string, live: RealmLiveness): () => boolean {
 function mountIdOfUrl(moduleUrl: string): string {
   const query = moduleUrl.split('?')[1];
   if (query === undefined) return DEFAULT_REALM_ID;
-  return new URLSearchParams(query).get('vgai-mount') ?? DEFAULT_REALM_ID;
+  return new URLSearchParams(query).get('volter-mount') ?? DEFAULT_REALM_ID;
 }
 
 /** The realm whose code is synchronously executing right now. Console capture
@@ -865,12 +865,12 @@ export function makeGatedProxy<T extends EventTarget>(
   };
 
   /** Report a refused navigation on the page's own console — which is a real
-   *  product door: `vgai status` reports page console errors. */
+   *  product door: `volter-game-editor status` reports page console errors. */
   const refuseNavigation = (attempt: string): void => {
     // A NEW native console.error site, suppressed to keep this task's diff at
     // zero new lint warnings — and it is deliberately native rather than
     // `editorConsole`: game code runs in the page, and the page console is the
-    // surface `vgai status` already reads (same reasoning as
+    // surface `volter-game-editor status` already reads (same reasoning as
     // `ingest-root-adapter.ts`'s loop-gate warning).
     // biome-ignore lint/suspicious/noConsole: see comment above
     console.error(refusedNavigationMessage(attempt));
@@ -1115,9 +1115,9 @@ function createOwnedRealmProxy<T extends EventTarget>(
     if (refusalReported) return;
     refusalReported = true;
     const realm = options.realmId ? `"${options.realmId}"` : 'the default realm';
-    // biome-ignore lint/suspicious/noConsole: game code runs in the page, and the page console is the surface `vgai status` reads (same reasoning as `refuseNavigation` above)
+    // biome-ignore lint/suspicious/noConsole: game code runs in the page, and the page console is the surface `volter-game-editor status` reads (same reasoning as `refuseNavigation` above)
     console.warn(
-      `vgai: a stopped game tried to register ${what} on its ${options.role} after its realm ` +
+      `volter: a stopped game tried to register ${what} on its ${options.role} after its realm ` +
         `(${realm}) was reclaimed; refused. Later refusals in this generation are silent.`,
     );
   };
@@ -1460,10 +1460,10 @@ function publishDefaultRealmGlobals(): void {
   const g = globalThis as unknown as Record<string, unknown>;
   const base = gameRealmForMountId();
   loopGate = defaultLoopGate;
-  g['__vgaiGameTimers'] = base.timers;
-  g['__vgaiGameWindow'] = base.window;
-  g['__vgaiGameDocument'] = base.document;
-  g['__vgaiGameConsole'] = base.console;
+  g['__volterGameTimers'] = base.timers;
+  g['__volterGameWindow'] = base.window;
+  g['__volterGameDocument'] = base.document;
+  g['__volterGameConsole'] = base.console;
 }
 
 /**
@@ -1494,8 +1494,8 @@ export function installGatedGameGlobals(): void {
   // The microtask pop bounds the window: it runs when the current synchronous
   // evaluation chunk yields, before the mount's own import().then
   // continuation (queued later) can run editor code.
-  g['__vgaiGameModuleUrls'] = loadedGameRealmModuleUrls;
-  g['__vgaiGameRealm'] = (mountId: string): GameRealm => {
+  g['__volterGameModuleUrls'] = loadedGameRealmModuleUrls;
+  g['__volterGameRealm'] = (mountId: string): GameRealm => {
     executingRealms.push(mountId);
     queueMicrotask(() => {
       const at = executingRealms.lastIndexOf(mountId);

package/src/host/ingest/registry.ts

@@ -47,7 +47,7 @@ import type { ResolvedAdapter, ResolvedAdapterRoot } from '@volter/editor-projec
 import { loadGameManifest, type ResolvedGameManifest } from '@volter/editor-project/manifest/load';
 
 /** The one manifest glob. Every in-tree ingest fixture, whatever its surface. */
-const manifestModules = import.meta.glob('./games/*/vgai.project.json', {
+const manifestModules = import.meta.glob('./games/*/volter.project.json', {
   eager: true,
   import: 'default',
 }) as Record<string, unknown>;
@@ -58,7 +58,7 @@ const manifestModules = import.meta.glob('./games/*/vgai.project.json', {
  * the editor's realm. `.d.ts` is excluded: an ambient declaration file
  * is not a module and must never become a dynamic-import chunk.
  *
- * `vgai.adapter.ts` is excluded too, and for a different reason: it is not a
+ * `volter.adapter.ts` is excluded too, and for a different reason: it is not a
  * GAME module at all. It is host-realm DECLARATION (see {@link adapterModules}),
  * read without booting anything, and a manifest that named it as an `entry` or
  * a `contractShim` would be nonsense — so it is not in the set those fields
@@ -68,15 +68,15 @@ export const entryModules = import.meta.glob([
   './games/*/*.js',
   './games/*/*.ts',
   '!./games/*/*.d.ts',
-  '!./games/*/vgai.adapter.ts',
+  '!./games/*/volter.adapter.ts',
 ]) as Record<string, () => Promise<unknown>>;
 
 /**
- * THE ADAPTER GLOB — one `vgai.adapter.ts` per ingest game, keyed by game id.
+ * THE ADAPTER GLOB — one `volter.adapter.ts` per ingest game, keyed by game id.
  *
  * ARCHITECTURE-CORE §The editor protocol: "Placement follows REALM: game-realm
  * code (a shim that runs inside the game) lives with the game's bundle;
- * host-realm declaration (`vgai.adapter.ts`) lives where the host can import it
+ * host-realm declaration (`volter.adapter.ts`) lives where the host can import it
  * as a real module — a repo-vendored bundle's adapter file lives in the host's
  * in-tree registry, never inside the verbatim-served bundle." This directory IS
  * that registry, so it holds BOTH populations:
@@ -86,7 +86,7 @@ export const entryModules = import.meta.glob([
  *     its bytes are served verbatim from `public/ingest/<id>/` and hashed by
  *     `vendor/games/verify-unaltered.mjs`, so nothing host-owned may go there.
  *
- * A folder with no `vgai.project.json` is invisible to {@link manifestModules}
+ * A folder with no `volter.project.json` is invisible to {@link manifestModules}
  * and therefore to {@link discoverIngestEntries} — the second population adds no
  * fixtures, only declarations.
  *
@@ -98,18 +98,18 @@ export const entryModules = import.meta.glob([
  * be used to fix that file"). Vite resolves the glob statically in dev and in
  * a production build alike, so no generated dispatch table is needed.
  */
-const adapterModules = import.meta.glob('./games/*/vgai.adapter.ts') as Record<
+const adapterModules = import.meta.glob('./games/*/volter.adapter.ts') as Record<
   string,
   () => Promise<unknown>
 >;
 
 /** The adapter module's filename — the contract's ONE spelling, host side. */
-const ADAPTER_FILENAME = 'vgai.adapter.ts';
+const ADAPTER_FILENAME = 'volter.adapter.ts';
 
 /** This directory's repo path, so a published `modulePath` names a real file. */
 const REGISTRY_REPO_DIR = 'packages/editor/src/ingest/games';
 
-const ADAPTER_KEY_RE = /^\.\/games\/([^/]+)\/vgai\.adapter\.ts$/;
+const ADAPTER_KEY_RE = /^\.\/games\/([^/]+)\/volter\.adapter\.ts$/;
 
 /**
  * THE LOOKUP KEY IS THE GAME ID; THE STORAGE KEY IS THE FOLDER NAME. What makes
@@ -124,8 +124,8 @@ const ADAPTER_KEY_RE = /^\.\/games\/([^/]+)\/vgai\.adapter\.ts$/;
  *
  * The invariant is therefore `folder id === the id that game's manifest
  * declares`, for BOTH populations this registry serves — in-tree fixtures
- * (`./games/<id>/vgai.project.json`) and public bundles
- * (`public/ingest/<id>/vgai.project.json`, whose registry folder holds only the
+ * (`./games/<id>/volter.project.json`) and public bundles
+ * (`public/ingest/<id>/volter.project.json`, whose registry folder holds only the
  * adapter file). It is guarded ONCE, statically, in
  * `packages/editor/test/ingest-adapter-modules.test.ts`, which reads both id
  * spaces off disk — the only realm that can, since `public/` is outside the
@@ -167,7 +167,7 @@ export const assetUrls = import.meta.glob('./games/*/assets/**', {
   import: 'default',
 }) as Record<string, string>;
 
-const MANIFEST_KEY_RE = /^\.\/games\/([^/]+)\/vgai\.project\.json$/;
+const MANIFEST_KEY_RE = /^\.\/games\/([^/]+)\/volter\.project\.json$/;
 
 /** Folder-relative glob key for a file inside a discovered game's folder. */
 export function gameFileKey(folderId: string, relPath: string): string {
@@ -206,14 +206,14 @@ function buildEntry(folderId: string, raw: unknown): IngestEntry {
   const roots = declaredRoots(manifest);
   if (roots.length !== 1) {
     throw new Error(
-      `ingest registry: "${folderId}/vgai.project.json" must declare exactly one root ` +
+      `ingest registry: "${folderId}/volter.project.json" must declare exactly one root ` +
         `(found ${roots.length}).`,
     );
   }
   const root = roots[0]!;
   if (root.adapter.type !== 'ingest') {
     throw new Error(
-      `ingest registry: "${folderId}/vgai.project.json"'s root must be an { ingest } root ` +
+      `ingest registry: "${folderId}/volter.project.json"'s root must be an { ingest } root ` +
         `(found adapter identity "${root.adapter.identity}").`,
     );
   }

package/src/host/play-control-hook.ts

@@ -4,7 +4,7 @@
  * `PlayBar` renders two different transports — the native one (title "Play
  * (run game)") and the ingest one (label "Run ingested game") — and anything
  * outside the component that needs to find "the play control" was matching a
- * LABEL. `vgai doctor` polled for the native string as its editor-readiness
+ * LABEL. A probe polled for the native string as its editor-readiness
  * boundary and therefore waited out its whole timeout budget on every ingest
  * project, which renders the other one (SimCity ingest dogfood, S-6).
  *

package/src/host/playwright-shim.ts

@@ -8,7 +8,7 @@
  * `page-script` relay op constructs one per call and hands it to a
  * reconstructed step function; a real `@playwright/test` `Page` drives the SAME
  * step file when the spec runs under `PageTransport`
- * (`packages/vgai-live/src/game-client/client.ts`) in CI. That duality is why
+ * (`packages/volter-live/src/game-client/client.ts`) in CI. That duality is why
  * `createPageShim`'s return value is typed `as Page` — every implemented member
  * matches Playwright's own shape closely enough that a step written against it
  * compiles against the real type too.
@@ -41,7 +41,7 @@
  * under both `PageTransport` (real Playwright, real closures) and
  * `RelayTransport` (this shim, serialized) must be written as though ALWAYS
  * serialized — inline every value the step needs; see
- * `packages/vgai-live/src/game-client/client.ts`'s `GameClient.page()` doc comment for
+ * `packages/volter-live/src/game-client/client.ts`'s `GameClient.page()` doc comment for
  * the client-facing half of this contract.
  */
 

package/src/host/projection/pixi.ts

@@ -179,8 +179,8 @@ export class PixiProjector {
     if (rect.width <= 0 || rect.height <= 0) return null;
     const mapped = this.mapping?.pointFromClient?.(clientX, clientY, rect) ?? null;
     if (this.mapping?.pointFromClient) return mapped;
-    const logicalWidth = Number(surface.dataset?.['vgaiStageWidth'] ?? rect.width);
-    const logicalHeight = Number(surface.dataset?.['vgaiStageHeight'] ?? rect.height);
+    const logicalWidth = Number(surface.dataset?.['volterStageWidth'] ?? rect.width);
+    const logicalHeight = Number(surface.dataset?.['volterStageHeight'] ?? rect.height);
     if (!(logicalWidth > 0) || !(logicalHeight > 0)) return null;
     return {
       x: (clientX - rect.left) * (logicalWidth / rect.width),

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

@@ -54,7 +54,7 @@ function staticReactRootMountRuntime(): ReactRootMountRuntime {
 
 /**
  * Import + shape-check the packaged runtime's synthetic
- * `/__vgai-react-world-runtime` module (`vite-plugin-module-doorways.ts`,
+ * `/__volter-react-world-runtime` module (`vite-plugin-module-doorways.ts`,
  * registered only by `packaged.ts`'s project-rooted Vite instance and by
  * `vitest.config.ts` for test coverage — never by `dev.ts`/the root
  * `vite.config.ts`). A loud, named failure if the module resolves but is

package/src/host/roots/canvas-root.tsx

@@ -134,7 +134,7 @@ function canvasWorldAdapter(
         throw new Error(
           `canvas world "${id}": this lane has already mounted this canvas. @pixi/react keys ` +
             'its reconciler roots off the canvas element, so re-using one would resurrect a ' +
-            'root whose Application is destroyed. Hand each mount a fresh canvas (every vgai ' +
+            'root whose Application is destroyed. Hand each mount a fresh canvas (every volter ' +
             'host already does).',
         );
       }
@@ -307,6 +307,18 @@ function canvasWorldAdapter(
           // the host only gates/advances it.
           mountedApp.ticker.update(elapsedMs);
         },
+        // Pixi's own hit test finds only interactive objects (`eventMode` static or dynamic), so a
+        // 2D layer claims its tappable objects and lets every other point fall through to the world beneath.
+        hitTest(x: number, y: number): boolean {
+          if (disposed) return false;
+          // Pixi points its boundary at the last rendered scene inside each of its own pointer
+          // handlers; a hit test asked from outside them does the same, or finds no root.
+          const boundary = mountedApp.renderer.events.rootBoundary;
+          const rendered = mountedApp.renderer.lastObjectRendered;
+          if (!rendered) return false;
+          boundary.rootTarget = rendered;
+          return boundary.hitTest(x, y) !== null;
+        },
         resize(width: number, height: number): void {
           if (disposed) return;
           // `autoDensity: true` makes Pixi re-stamp `canvas.style.width`/

package/src/host/roots/r3f-root.tsx

@@ -208,7 +208,7 @@ function threeWorldAdapter(id: string, component: ComponentType, runtime: R3FRun
         Fragment,
         null,
         content,
-        createElement(MountEffectsReady, { key: 'vgai-mount-effects-ready' }),
+        createElement(MountEffectsReady, { key: 'volter-mount-effects-ready' }),
       );
       // A reconcile-time crash (e.g. a missing `extend` catalogue entry)
       // surfaces as an uncaught window error and `onCreated` never fires —

package/src/host/scene-view-drawability.ts

@@ -21,7 +21,7 @@
  * throw, attributes it to that scene, and stops re-throwing it forever.
  *
  * The game is NOT lost when this fires: its own renderer keeps drawing into its
- * own canvas, which the host adopted, so the Game tab and `vgai screenshot`
+ * own canvas, which the host adopted, so the Game tab and `volter-game-editor screenshot`
  * show the real thing. What is lost is the editor-camera Scene view of it,
  * which is exactly what the message says.
  */

package/src/host/sdk/tools.ts

@@ -5,7 +5,7 @@
  * input/result schemas, structured error codes, and the metadata a caller reads
  * before invoking (`permission`, `host`, `mutates`, `supportsDryRun`). The
  * contract exists because a tool is called across a process boundary — CLI to
- * editor to node host, and `vgai mcp` to an external agent over stdio — where
+ * editor to node host, and `volter mcp` to an external agent over stdio — where
  * you cannot throw. `ToolRegistry.dispatch` turns every expected failure
  * (unknown name, bad input, an `impl` throw, a bad return) into a typed outcome
  * instead.

package/src/host/served-bundle-runtime-modules.ts

@@ -172,6 +172,8 @@ export const BUNDLE_RUNTIME_MODULE_LOADERS: Record<string, () => Promise<unknown
   // against the same sweep.
   '@colyseus/sdk': () => import('@colyseus/sdk'), // template main.ts
   'react-dom': () => import('react-dom'), // template main.ts
+  'pixi.js': () => import('pixi.js'), // template main.ts (a `canvas` root)
+  '@pixi/react': () => import('@pixi/react'), // template main.ts (a `canvas` root)
   // ---- Editor-citizen modules PROJECT TOOL CONTRIBUTIONS import. A
   // contribution is project source rendered inside the editor's own panels,
   // so these must resolve to the editor's LIVE modules — a second copy of the

package/src/host/staged-projects.ts

@@ -20,5 +20,5 @@ export function isSafeIngestId(id: string): boolean {
 }
 
 export function publicIngestManifestUrl(id: string): string {
-  return `${PUBLIC_INGEST_BASE}${id}/vgai.project.json`;
+  return `${PUBLIC_INGEST_BASE}${id}/volter.project.json`;
 }

package/src/host/stories/story-pixi-preview.ts

@@ -350,7 +350,7 @@ const FIRST_FRAME_TIMEOUT_MS = PIXI_MOUNT_TIMEOUT_MS;
  * Wait until every collected `Application` has PRESENTED a frame with content
  * in it — the readiness test a capture of a canvas story owes itself.
  *
- * MEASURED DEFECT (this is why the function exists): `vgai screenshot
+ * MEASURED DEFECT (this is why the function exists): `volter-game-editor screenshot
  * <file>.stories.tsx` photographed a `@pixi/react` story blank. The capture
  * lane's own readiness test is "the container has committed child nodes", and
  * `<Application>` commits its `<canvas>` on the FIRST commit — before

package/src/host/stories/story-three-preview.ts

@@ -150,7 +150,7 @@ export interface MountedStoryObject3D {
 
 /** The name of the wrapper `<group>` every story is rendered into, so its root
  *  `Object3D` can be extracted unambiguously from fiber's scene. */
-export const PREVIEW_ROOT_NAME = 'vgai:story-preview-root';
+export const PREVIEW_ROOT_NAME = 'volter:story-preview-root';
 
 /** How long to wait for fiber's first commit before giving up. The LAST-RESORT
  *  ceiling only: a reconcile-time crash is now caught by

package/src/host/three-ingest-runtime.ts

@@ -4,7 +4,7 @@
  * `canvas-entry-runtime.ts`'s `resolveCanvasPixiForEditor`.
  *
  * See `../vite-plugin-module-doorways.ts` for the measured failure this
- * closes and for why the ingest lane does not borrow `/__vgai-r3f-runtime`.
+ * closes and for why the ingest lane does not borrow `/__volter-r3f-runtime`.
  *
  * A mount site resolves this ONCE and hands what it gets to everything it
  * builds for that game. Nothing further down reaches for a static import: a

package/src/ingest/active-ingest.ts

@@ -108,7 +108,7 @@ export type ActiveIngest = (
 ) & {
   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
+   *  `__volterIngest` 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;

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

@@ -20,7 +20,7 @@ import {
   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';
+import type { VolterGameContract } from '@volter/editor-project/adapter/ingest/game-contract';
 
 type ReadableDomRoot = OverlayElement & DomElementLike & { readonly ownerDocument?: Document };
 
@@ -50,7 +50,7 @@ function iframeDocumentRoot(hostEl: HTMLElement): ReadableDomRoot | null {
 
 function resolveGameDomRoot(
   hostEl: HTMLElement,
-  declaredRoot: VgaiGameContract['root'] | undefined,
+  declaredRoot: VolterGameContract['root'] | undefined,
 ): ReadableDomRoot | null {
   if (isReadableDomRoot(declaredRoot)) return declaredRoot;
   return iframeDocumentRoot(hostEl) ?? (isReadableDomRoot(hostEl) ? hostEl : null);
@@ -143,7 +143,7 @@ export function withDetectedDomSurface(args: {
   primary: AuthoringAdapter;
   worldId: string;
   hostEl: HTMLElement;
-  declaredRoot?: VgaiGameContract['root'];
+  declaredRoot?: VolterGameContract['root'];
   store: EditorShellStore;
 }): AuthoringAdapter {
   const gameRoot = resolveGameDomRoot(args.hostEl, args.declaredRoot);
@@ -158,7 +158,7 @@ export function withDetectedDomSurface(args: {
   // refuse every detected DOM sibling before the ingest could mount.
   const domUiJournalId = `${args.worldId}/dom-ui`;
   const liveUiRoot: DomElementLike & OidElementLike = {
-    tagName: 'vgai-dom-surface',
+    tagName: 'volter-dom-surface',
     id: '',
     className: '',
     get children() {

package/src/ingest/authoring/ingest-root-adapter.ts

@@ -385,7 +385,7 @@ function bootWindowPageErrors(startedAt: number): string[] {
 /**
  * Wait for the game's world to be BUILT, declaration first.
  *
- * A game that declares `window.vgaiGame.ready` is awaited exactly once and the
+ * A game that declares `window.volterGame.ready` is awaited exactly once and the
  * measured poll never runs — the game states when it is done, so the host has
  * nothing to estimate. Everything else keeps {@link waitForSceneToSettle},
  * which is the MEASURED fallback and is labelled as such wherever readiness is
@@ -408,7 +408,7 @@ async function awaitWorldReady(
       return 'declared';
     } catch (err) {
       editorConsole.error(
-        `Ingest game "${gameId}" declared \`window.vgaiGame.ready\` and it REJECTED (${String(err)}) ` +
+        `Ingest game "${gameId}" declared \`window.volterGame.ready\` and it REJECTED (${String(err)}) ` +
           '— the world was already captured, so the host fell back to the measured settle wait. ' +
           'This root now reports readiness as measured.',
         'ingest',
@@ -442,8 +442,8 @@ async function waitForSceneToSettle(scene: THREE.Scene, maxMs = 5000): Promise<v
  * Some games append their canvas to `document.body` — reparent it into the
  * host. A DOM-hybrid game (React/R3F with HTML UI: HUDs, overlay panels, drei
  * `<Html>` portals) can declare the element that OWNS its canvas via
- * `window.vgaiGame.root` (the declared game→host contract, game-contract.ts;
- * `__vgaiGameRoot` is the pre-contract alias). Adopting only the bare canvas
+ * `window.volterGame.root` (the declared game→host contract, game-contract.ts;
+ * `__volterGameRoot` is the pre-contract alias). Adopting only the bare canvas
  * would strand that UI at page level over the editor chrome, and following the
  * canvas would require the game to know host layout internals — an arcane
  * demand. Adopt the declared root wholesale so the game's own DOM structure
@@ -472,7 +472,7 @@ function adoptGameDomRoot(hostEl: HTMLElement, surface: HTMLElement): HTMLElemen
   const realmWindow = ingestGameRealmWindow();
   const declaredRoot =
     readIngestGameContract()?.root ??
-    (realmWindow as unknown as { __vgaiGameRoot?: unknown }).__vgaiGameRoot;
+    (realmWindow as unknown as { __volterGameRoot?: unknown }).__volterGameRoot;
   const declared =
     declaredRoot instanceof HTMLElement && declaredRoot.contains(surface) ? declaredRoot : surface;
   if (declared.contains(hostEl)) return hostEl;
@@ -516,7 +516,7 @@ export async function mountIngestGame(
   // Host policy, not per-game CSS — see `game-realm-page.ts` for the four
   // page-shaped assumptions this covers and why each one breaks an in-realm
   // mount. Registered on the DEFAULT realm because an ingest descriptor's
-  // module urls carry no `?vgai-mount=` (binding-resolver.ts's
+  // module urls carry no `?volter-mount=` (binding-resolver.ts's
   // `resolveIngestDescriptor` builds bare `fsImportPath` urls).
   const realmPage = setGameSurface(hostEl);
 
@@ -614,10 +614,10 @@ export async function mountIngestGame(
   // Signal COLD MOUNT before the entry executes: editor mounts are for
   // inspection first, so a session-driven game MAY defer its side-effects
   // (backend connection, narrative, audio) until the editor's play control
-  // dispatches 'vgai:ingest-play' (getIngestPlayControl, ingest/mount-ingest-root.ts).
+  // dispatches 'volter:ingest-play' (getIngestPlayControl, ingest/mount-ingest-root.ts).
   // Rendering must continue regardless — capture needs a frame — and games
   // that ignore the flag behave exactly as before (opt-in, never demanded).
-  (window as unknown as { __vgaiMountCold?: boolean }).__vgaiMountCold = true;
+  (window as unknown as { __volterMountCold?: boolean }).__volterMountCold = true;
   // THE BOOT WINDOW OPENS HERE (M29). Everything the page throws from this
   // instant until the mount resolves belongs to this game's boot, and it is the
   // fact that separates "crashed before ready" from "never became ready" — the
@@ -650,7 +650,7 @@ export async function mountIngestGame(
     // boots in the background parks here instead of dying, with the trap still
     // installed, so the first frame after the human foregrounds the tab is the
     // captured one. `setCaptureWait` is what keeps that park from reading as a
-    // hung mount — `vgai status` names it.
+    // hung mount — `volter-game-editor status` names it.
     rt = await capture.waitForCapture({
       timeoutMs,
       onWait: (wait) => setCaptureWait(game.id, wait),
@@ -797,10 +797,10 @@ export async function mountIngestGame(
     // well after `setPaused` returned. Nothing else would notify the store, and
     // `collectState` is push-based — the control API would keep serving a
     // snapshot taken before the measurement existed, reporting `loop: null`
-    // forever. Broadcast so `vgai status` sees the verdict it just produced.
+    // forever. Broadcast so `volter-game-editor status` sees the verdict it just produced.
     onVerdict: () => store.shell.notifyIngestEdit(),
   });
-  // The game's DECLARED system surface (`window.vgaiGame.systems`), projected
+  // The game's DECLARED system surface (`window.volterGame.systems`), projected
   // onto the host's ordinary `SystemAdapters.debug`. `activateCapturedThreeIngest`
   // hands `mounted.systems` straight to `setActiveSystems`, so a shim that
   // declares verbs makes `game.commands()`/`game.state()` work through the same

package/src/ingest/capture-wait-report.ts

@@ -7,13 +7,13 @@
  * background — the normal human path — no longer burns its window unable to
  * draw. What it does instead is WAIT, potentially for as long as the human
  * takes to come back to the tab, and a wait is exactly the state every door
- * used to report as silence: nothing mounted, nothing failed, `vgai status`
+ * used to report as silence: nothing mounted, nothing failed, `volter-game-editor status`
  * counting down a clock that was not running. So the wait is published:
- * `collectState`'s `ingestCaptureWait` carries it, and `vgai status` prints
+ * `collectState`'s `ingestCaptureWait` carries it, and `volter-game-editor status` prints
  * "waiting for first visible frame — tab is hidden" instead of a countdown.
  *
  * A LIVE VIEW, never a snapshot — same rule as `IngestMount.realmLoopVerdict`
- * and the `__vgaiIngest` hook's `reflected`/`sceneChildren`: the elapsed
+ * and the `__volterIngest` hook's `reflected`/`sceneChildren`: the elapsed
  * numbers move on their own, so a frozen copy starts lying the instant it is
  * taken. The slot holds the window itself and derives the report at read time.
  *
@@ -27,7 +27,7 @@
 import { notifyLiveSessionsChanged } from '@volter/editor-sdk/kit/live-session-registry';
 import type { VisibleCaptureWindow } from '@volter/threejs-runtime/adapter/ingest/visible-capture-window';
 
-/** The wait as `vgai status` reports it. */
+/** The wait as `volter-game-editor status` reports it. */
 export interface CaptureWaitStatus {
   /** The world whose first frame is being waited for. */
   readonly worldId: string;

package/src/ingest/discovery-public-ingest.ts

@@ -3,7 +3,7 @@
  *
  * The three sibling of `surface-canvas.ts` (the pixi lane, which is the idiom
  * benchmark this file is modelled on): a game vendored under
- * `public/ingest/<id>/` carries its own declarative `vgai.project.json`, and
+ * `public/ingest/<id>/` carries its own declarative `volter.project.json`, and
  * its id resolves it into the SAME `IngestGame` descriptor every other three
  * ingest route produces. Adding a fourth vendored game is a folder plus a
  * manifest — no edit to this file, no per-game page, no branch anywhere.
@@ -81,7 +81,7 @@ function readVendoredIngestRoot(
   const roots = declaredRoots(manifest);
   if (roots.length !== 1) {
     throw new Error(
-      `vendored ingest discovery: "${folderId}/vgai.project.json" must declare exactly one root ` +
+      `vendored ingest discovery: "${folderId}/volter.project.json" must declare exactly one root ` +
         `(found ${roots.length}).`,
     );
   }
@@ -92,7 +92,7 @@ function readVendoredIngestRoot(
     root.adapter.identity !== expect.identity
   ) {
     throw new Error(
-      `vendored ingest discovery: "${folderId}/vgai.project.json" must declare one ` +
+      `vendored ingest discovery: "${folderId}/volter.project.json" must declare one ` +
         `${expect.surface} { ingest } root (found surface "${root.surface}", adapter identity ` +
         `"${root.adapter.identity}").`,
     );
@@ -161,7 +161,7 @@ export function buildPublicCanvasIngestGame(
 }
 
 /**
- * Resolve a vendored game id against `public/ingest/<id>/vgai.project.json`.
+ * Resolve a vendored game id against `public/ingest/<id>/volter.project.json`.
  *
  * `null` means "no such vendored three ingest" (no manifest served at that
  * path) — the caller falls through to its own unknown-id report. A manifest

package/src/ingest/dom-stub-mark.ts

@@ -4,4 +4,4 @@
  * page can retire the stub whose id it supplies itself (`served-html-boot.ts`).
  * Shared here because the two sides must agree on one mark.
  */
-export const DOM_STUB_MARK = 'vgaiDomStub';
+export const DOM_STUB_MARK = 'volterDomStub';

package/src/ingest/entry-load.ts

@@ -3,7 +3,7 @@
  * editor's realm, preceded by the host-added contract module the manifest names
  * in `ingest.contractShim` when it declares one.
  *
- * ORDER IS THE WHOLE CONTRACT. The shim assigns `window.vgaiGame` synchronously
+ * ORDER IS THE WHOLE CONTRACT. The shim assigns `window.volterGame` synchronously
  * at top level (see the field's schema description), so it must be evaluated
  * BEFORE the game's entry — a game that reads the declaration during its own
  * module evaluation would otherwise see nothing, and a shim that lazily

package/src/ingest/game-contract-realm.ts

@@ -1,13 +1,13 @@
 import { gameRealmForMountId } from '../host/gated-globals';
 import {
   readGameContract,
-  type VgaiGameContract,
+  type VolterGameContract,
 } from '@volter/editor-project/adapter/ingest/game-contract';
 
 /**
  * The browser realm used by the singleton ingest routes.
  *
- * Vendored ingest entry graphs deliberately carry no `?vgai-mount=` query:
+ * Vendored ingest entry graphs deliberately carry no `?volter-mount=` query:
  * they share the editor's Pixi/Three packages and run in the default gated
  * realm. Realm hardening keeps game-owned expandos on that realm's window
  * proxy, so host code must read the contract from the same proxy rather than
@@ -28,7 +28,7 @@ export function ingestGameRealmWindow(): Window {
  * reached by every `bridge-call`) degrading instead of throwing
  * `window is not defined` at them.
  */
-export function readIngestGameContract(): VgaiGameContract | null {
+export function readIngestGameContract(): VolterGameContract | null {
   if (typeof window === 'undefined') return null;
   return readGameContract(ingestGameRealmWindow());
 }

package/src/ingest/game-pointer-lock.ts

@@ -59,7 +59,7 @@ export function installGamePointerLockGate(): void {
     if (entry && !entry.gate()) {
       // A NEW native console.error site, suppressed to keep this task's diff at
       // zero new lint warnings — and native on purpose: this fires from a game's
-      // own click handler in the page, and the page console is what `vgai
+      // own click handler in the page, and the page console is what `volter-game-editor
       // status` reads.
       // biome-ignore lint/suspicious/noConsole: see comment above
       console.error(

package/src/ingest/ingest-canvas-scene-document.tsx

@@ -136,8 +136,8 @@ export function IngestCanvasSceneContent({
     <div
       ref={containerRef}
       data-testid="world-document:ingest-canvas-scene"
-      data-vgai-backdrop-color={active ? CANVAS_SCENE_BACKGROUND : undefined}
-      data-vgai-backdrop-policy={active ? 'dark-frost' : undefined}
+      data-volter-backdrop-color={active ? CANVAS_SCENE_BACKGROUND : undefined}
+      data-volter-backdrop-policy={active ? 'dark-frost' : undefined}
       style={{
         position: 'absolute',
         inset: 0,
@@ -148,7 +148,7 @@ export function IngestCanvasSceneContent({
       }}
     >
       <CanvasSceneBackdrop view={view} documentId={documentId} />
-      <RootSelectionOverlay adapter={adapter} view={view} transformModeAware />
+      <RootSelectionOverlay adapter={adapter} view={view} transformModeAware presentationId={documentId} />
       <SurfaceStateOverlay
         explanation={surfaceExplanation}
         testId="ingest-canvas-surface-status"