@vgai/engine 0.5.1 → 0.5.3

package/src/{scene → ecs}/user-data.ts

@@ -15,24 +15,24 @@
  *
  * ## Key reference
  *
- * Serialization / identity (load-bearing — editor identity + scene I/O):
- * - `entity`              — the full {@link SceneEntity} descriptor backing this
- *                           Object3D. Source of truth the editor reads/writes and
- *                           the serializer walks to rebuild `.vscn.json`.
+ * Serialization / identity (load-bearing — editor identity):
  * - `entityId`            — the entity's stable string id. Presence also marks an
  *                           Object3D as a "real" entity (vs editor helper/env object).
  *
- * Runtime scene-query overrides (read by `scene-query.ts`):
- * - `tags`                — string[] tag override; falls back to `entity.tags`.
- * - `components`          — component record or name[] override; falls back to
- *                           `entity.components`.
+ * Runtime scene-query metadata (read by `scene-query.ts` and `scene-index.ts`):
+ * - `tags`                — string[] tags for `queryByTag` and the live index.
+ * - `attributes`          — per-object `Record<string, string|number|boolean>`
+ *                           of game-defined attributes (P2 `observe`). Written
+ *                           through `SceneIndex.setAttribute`, which emits an
+ *                           `attributechanged` signal; JSON-simple values only,
+ *                           so an attribute survives serialization unchanged.
  *
- * Runtime gameplay metadata (set by the scene loader):
+ * Runtime gameplay metadata:
  * - `forward`             — `[x,y,z]` model-space visual forward exported as
  *                           ordinary glTF extras for asset-facing validation.
  * - `navRole`             — `'walkable' | 'obstacle'` navmesh role; collected at runtime.
  * - `pivot`              — `[x,y,z]` local-space pivot for rotate/scale-around-pivot.
- * - `splineCurve`         — resolved THREE curve built from the entity's spline.
+ * - `splineCurve`         — resolved THREE curve for a spline-following object.
  * - `_camera`             — THREE.Camera owned by a camera entity (collected on load).
  * - `_particleSystem`     — three.quarks ParticleSystem (scene-sync registration + census).
  * - `gaussianSplat`       — native Spark splat metadata used for renderer discovery,
@@ -41,7 +41,7 @@
  * Animation (load-bearing — ED5 disposal contract):
  * - `_animMixer`          — THREE.AnimationMixer driving this subtree's clips.
  * - `_animClips`          — Map<string, AnimationClip> discovered on the GLTF (E5 —
- *                           lets a GameComponent build its own XState-driven
+ *                           lets game code build its own XState-driven
  *                           binding via `bindXStateAnimation` over the SAME
  *                           mixer; see xstate-animation-binding.ts).
  * - `_availableClips`     — string[] of clip names discovered on the GLTF
@@ -58,9 +58,8 @@
  * - `__shadeUnlit`        — generated unlit material(s) for the unlit view mode.
  *
  * Unmodified-game ingestion (editor-only, see `editor/src/ingest/`):
- * - `__ingest`            — `true` on every Object3D minted by ingestion (vs the
- *                           first-party scene loader); routes edits to live
- *                           mutation instead of descriptor rebuild.
+ * - `__ingest`            — `true` on every Object3D minted by ingestion; routes
+ *                           edits to live mutation.
  * - `__ingestNextId`      — monotonic id counter stashed on the captured Scene
  *                           root so re-reflects keep minting unique ids.
  *
@@ -69,10 +68,6 @@
  *                           (particle BatchedRenderer, debug-draw + its subtree).
  *                           The editor's play-mode hierarchy skips these so they
  *                           don't show up as selectable "entities".
- * - `liveObject`          — `true` on a runtime/procedural Object3D that the editor
- *                           surfaced in the play-mode hierarchy with a *synthetic*
- *                           descriptor (it has no `.vscn` record). Marks it as
- *                           ephemeral: selectable/movable for testing, never saved.
  * - `authoringRoot`       — explicit opt-in for a runtime descendant to become
  *                           its own authoring object instead of a part of the
  *                           nearest ancestor owner.
@@ -81,8 +76,6 @@
  *                           implementation parts without adding wrappers.
  * - `authoringLabel`      — authored literal name (or component tag fallback)
  *                           for that source-backed component instance.
- * - `behaviorType`        — registry key on the compatibility R3F Behavior
- *                           attachment group; authoring projects it as a component.
  * - `editorHelper`        — `true` for editor-only helper objects (gizmos, wireframes).
  * - `editorHelperType`    — which kind of helper (lights/particles/pivot/navmesh/...).
  * - `editorIcon`          — `true` for editor billboard icon sprites.
@@ -95,9 +88,7 @@
 
 import type * as THREE from 'three';
 import type { ParticleSystem } from 'three.quarks';
-import type { AnyActor } from 'xstate';
 import type { XStateAnimationBinding } from '../animation/xstate-animation-binding';
-import type { SceneEntity } from './scene-types';
 
 /** The kinds of editor helper objects tagged via `editorHelperType`. */
 export type EditorHelperType =
@@ -121,22 +112,17 @@ export type EditorHelperType =
   | 'particle-shape'
   | 'pivot'
   | 'navmesh'
-  | 'skeletons'
-  // Per-component viewport gizmo contributions (W3a extension contract,
-  // critique O11): objects a project GameComponent's `static editorGizmo`
-  // hook draws for entities carrying that component.
-  | 'components';
+  | 'skeletons';
 
 /**
  * Maps each canonical accessor name to its value type. This is the single
  * source of truth for what every known `userData` key holds.
  */
 export interface UserDataSchema {
-  entity: SceneEntity;
   entityId: string;
   forward: [number, number, number];
   tags: string[];
-  components: Record<string, unknown> | string[];
+  attributes: Record<string, string | number | boolean>;
   navRole: 'walkable' | 'obstacle';
   pivot: [number, number, number];
   splineCurve: THREE.Curve<THREE.Vector3>;
@@ -147,18 +133,16 @@ export interface UserDataSchema {
   _animMixer: THREE.AnimationMixer;
   _animClips: Map<string, THREE.AnimationClip>;
   _availableClips: string[];
-  _xstateAnimation: XStateAnimationBinding & { readonly actor: AnyActor };
+  _xstateAnimation: XStateAnimationBinding;
   __sharedGeometry: boolean;
   __shadeOrig: THREE.Material | THREE.Material[];
   __shadeUnlit: THREE.Material[];
   __ingest: boolean;
   __ingestNextId: number;
   engineInternal: boolean;
-  liveObject: boolean;
   authoringRoot: boolean;
   authoringInstance: string;
   authoringLabel: string;
-  behaviorType: string;
   editorHelper: boolean;
   editorHelperType: EditorHelperType;
   editorIcon: boolean;
@@ -181,11 +165,10 @@ export type UserDataKey = keyof UserDataSchema;
  * literal strings appear in exactly this one place.
  */
 export const UserDataKeys = {
-  entity: 'entity',
   entityId: 'entityId',
   forward: 'forward',
   tags: 'tags',
-  components: 'components',
+  attributes: 'attributes',
   navRole: 'navRole',
   pivot: 'pivot',
   splineCurve: 'splineCurve',
@@ -203,11 +186,9 @@ export const UserDataKeys = {
   __ingest: '__ingest',
   __ingestNextId: '__ingestNextId',
   engineInternal: 'engineInternal',
-  liveObject: 'liveObject',
   authoringRoot: 'authoringRoot',
   authoringInstance: 'authoringInstance',
   authoringLabel: 'authoringLabel',
-  behaviorType: 'behaviorType',
   editorHelper: 'editorHelper',
   editorHelperType: 'editorHelperType',
   editorIcon: 'editorIcon',

package/src/index.ts

@@ -18,15 +18,15 @@
  * Groups (import order below is alphabetical-by-specifier, per the repo's
  * biome `organizeImports` rule, not by group — see this list instead):
  *   - game setup contract: `GameContext`/`GameCleanup`/`GameSetupFn`, `fromSetup`
- *   - component model: `GameComponent`, `AdapterSurface`
- *   - manifest-driven mount: `mountManifestWorlds` + its option/result types
- *   - scene file entry point: `parseSceneFile`/`parsePrefabFile`
- *   - game manifest (vgai.game.json) entry point: `loadGameManifest`
+ *   - surface vocabulary: `AdapterSurface`
+ *   - manifest-driven mount: `mountManifestRoots` + its option/result types
+ *   - asset-format entry points: `parseMaterialFile` (.mat.json), `parseInstancesFile`
+ *   - game manifest (vgai.project.json) entry point: `loadGameManifest`
  */
 
 export type { AdapterSurface } from './adapter/adapter-surface';
-export { fromSetup } from './adapter/vgai-scene-game-adapter';
-export { GameComponent } from './ecs/game-component';
+export { fromSetup } from './adapter/setup-three-root-adapter';
+export { AssetParseError, parseInstancesFile, parseMaterialFile } from './asset-formats/parse';
 export type {
   AdapterRoot,
   GameManifest,
@@ -42,7 +42,5 @@ export type {
   MountedManifestSession,
   MountManifestOptions,
 } from './runtime/mount-manifest';
-export { mountManifestWorlds } from './runtime/mount-manifest';
+export { mountManifestRoots } from './runtime/mount-manifest';
 export type { GameCleanup, GameContext, GameSetupFn } from './runtime/types';
-export { parsePrefabFile, parseSceneFile, SceneParseError } from './scene/parse';
-export type { PrefabFile, SceneFile } from './scene/schema';

package/src/input/input-manager.ts

@@ -1,5 +1,5 @@
+import { AssetParseError } from '../asset-parse-error';
 import { resolveUrl } from '../loader';
-import { SceneParseError } from '../scene/parse';
 import type {
   ActionValueOf,
   ActionValueSource,
@@ -39,9 +39,8 @@ function isTextEntryFocused(): boolean {
 }
 
 /**
- * Thrown by `InputManager.setVirtualAction`/`tapVirtualAction` (Task 1.4,
- * E2E-TESTING-BUILD-PLAN.md / SYNTHETIC-PLAYER-SPEC.md §3.2) for an
- * action name that was never `registerAction`/`loadMap`-ed. Carries a
+ * Thrown by `InputManager.setVirtualAction`/`tapVirtualAction` (Task 1.4)
+ * for an action name that was never `registerAction`/`loadMap`-ed. Carries a
  * machine-readable `code` and `data.registered` (every declared action name)
  * rather than requiring a caller to parse the message.
  */
@@ -60,12 +59,12 @@ export class InputActionError extends Error {
 }
 
 /**
- * Thrown by `InputManager.scheduleActionAtTick` (D15/T-D15.5,
- * docs/D15-DETERMINISM-DESIGN.md §2.c) when the named `tick` has already
- * elapsed — scheduling only ever applies to the CURRENT or a future tick,
- * never one already serviced by `poll()`. Carries `data.currentTick` — the
- * NEXT tick `poll()` will service (not the tick that just elapsed) — so a
- * caller can retry by scheduling for `data.currentTick` or later.
+ * Thrown by `InputManager.scheduleActionAtTick` (D15/T-D15.5) when the
+ * named `tick` has already elapsed — scheduling only ever applies to the
+ * CURRENT or a future tick, never one already serviced by `poll()`.
+ * Carries `data.currentTick` — the NEXT tick `poll()` will service (not
+ * the tick that just elapsed) — so a caller can retry by scheduling for
+ * `data.currentTick` or later.
  */
 export class InputTickError extends Error {
   readonly code = 'TICK_ALREADY_PASSED' as const;
@@ -360,7 +359,7 @@ export class InputManager {
   private static isStickActive(v: Vector2): boolean {
     return Math.hypot(v.x, v.y) > 0.3;
   }
-  // Task 1.4 (E2E-TESTING-BUILD-PLAN.md) — action-level virtual input
+  // Task 1.4 — action-level virtual input
   // for a synthetic player, promoted from hollowstone's `VirtualInput`. Held
   // digitals OR into isPressed alongside binding contributions (like
   // touchButtonsDown above); tap queues, then is promoted to "active" for
@@ -382,14 +381,13 @@ export class InputManager {
   private virtualDigitalJustReleased = new Set<string>();
   private virtualScalarValues = new Map<string, number>();
   private virtualVector2Values = new Map<string, Vector2>();
-  // D15/T-D15.5 (docs/D15-DETERMINISM-DESIGN.md §2.c) — tick-indexed input
-  // scheduling + post-gate recording.
+  // D15/T-D15.5 — tick-indexed input scheduling + post-gate recording.
   //
   // `currentTick` is a FALLBACK, self-incrementing counter, used only when a
   // caller never tells `poll()` which tick it's servicing (every existing
   // bare/headless caller — tests, a mount with no `Game` shell behind it —
   // keeps this exact pre-existing behavior, zero regression). The REAL
-  // per-world wiring (`vgai-scene-game-adapter.ts`) instead passes the
+  // per-world wiring (`setup-three-root-adapter.ts`) instead passes the
   // shared `Game`-level tick counter into every `poll(tick)` call — this is
   // deliberate: an InputManager-local counter drifts from the actual game
   // tick for a paused/frozen world (its `poll()` isn't called every game
@@ -422,7 +420,7 @@ export class InputManager {
    *  action}`) emitted whenever a scheduled entry is discarded because its
    *  target tick's input phase never ran. Wired by whoever constructs this
    *  `InputManager` with access to a `DebugRegistry`
-   *  (`vgai-scene-game-adapter.ts`, the same seed spot as
+   *  (`setup-three-root-adapter.ts`, the same seed spot as
    *  `setVirtualInputTarget`/`setInputActionsSource`) — `null` (the
    *  default) for a bare/headless `InputManager`, in which case a drop
    *  stays silent (matching pre-D15/T-D15.5 behavior). */
@@ -634,7 +632,7 @@ export class InputManager {
   /**
    * Load action map from a .inputmap.json file. Validated via
    * `InputMapFileSchema` (T4.6) — a malformed input map throws a
-   * `SceneParseError` naming the file, not a deep TypeError once the bad
+   * `AssetParseError` naming the file, not a deep TypeError once the bad
    * data reaches `isPressed`/`isJustPressed`/`isJustReleased`.
    */
   async loadMap(url: string) {
@@ -646,14 +644,14 @@ export class InputManager {
       }
       const json = await res.json();
       const result = InputMapFileSchema.safeParse(json);
-      if (!result.success) throw new SceneParseError(result.error.issues, url);
+      if (!result.success) throw new AssetParseError(result.error.issues, url);
       data = result.data;
     } catch (err) {
       const message = `InputManager.loadMap: failed to load input map "${url}": ${
         err instanceof Error ? err.message : String(err)
       }`;
       console.error(message);
-      throw err instanceof SceneParseError ? err : new Error(message);
+      throw err instanceof AssetParseError ? err : new Error(message);
     }
     this.applyParsedMap(data);
   }
@@ -661,7 +659,7 @@ export class InputManager {
   /**
    * F3 — `loadMap`'s synchronous, no-`fetch` sibling: apply an already-in-
    * memory (or freshly-deserialized) input-map DOCUMENT, validated through
-   * the identical `InputMapFileSchema` (throws `SceneParseError` naming no
+   * the identical `InputMapFileSchema` (throws `AssetParseError` naming no
    * file, matching `loadMap`'s error shape minus the URL). This is the other
    * half of the F3 persist round-trip: `toInputMapFile()` serializes,
    * `loadMapObject` re-applies — no network/file I/O required, so it's also
@@ -669,7 +667,7 @@ export class InputManager {
    */
   loadMapObject(data: unknown): InputMapFile {
     const result = InputMapFileSchema.safeParse(data);
-    if (!result.success) throw new SceneParseError(result.error.issues);
+    if (!result.success) throw new AssetParseError(result.error.issues);
     this.applyParsedMap(result.data);
     return result.data;
   }
@@ -723,7 +721,8 @@ export class InputManager {
     }
   }
 
-  /** The names of all registered actions (for the InputAdapter to enumerate). */
+  /** The names of all registered actions (r3f `world-context` enumerates these
+   *  for its input-binding projection). */
   actionNames(): string[] {
     return [...this.actions.keys()];
   }
@@ -732,7 +731,7 @@ export class InputManager {
    * Poll gamepads and virtual look stick (call at start of frame).
    *
    * `tick` (D15/T-D15.3/.5) — the GAME tick this call services. Pass the
-   * live, shared `Game` tick counter here (`vgai-scene-game-adapter.ts` does,
+   * live, shared `Game` tick counter here (`setup-three-root-adapter.ts` does,
    * via `DebugRegistry.getGameTick()`) so `scheduleActionAtTick`'s numbering
    * never drifts from the actual game tick — the bug an earlier revision of
    * this feature had: an InputManager-LOCAL counter, incremented once per
@@ -2007,8 +2006,7 @@ export class InputManager {
   }
 
   // ==========================================================================
-  // Task 1.4 (E2E-TESTING-BUILD-PLAN.md / SYNTHETIC-PLAYER-SPEC.md §3.2)
-  // — action-level virtual input for a synthetic player. Promoted from
+  // Task 1.4 — action-level virtual input for a synthetic player. Promoted from
   // hollowstone's proven `VirtualInput` (`bot/virtual-input.ts`): a bot drives
   // NAMED ACTIONS (not raw devices), and its contributions join action
   // resolution at exactly the same points binding contributions do (see
@@ -2183,13 +2181,12 @@ export class InputManager {
   }
 
   /**
-   * D15/T-D15.5 (`docs/D15-DETERMINISM-DESIGN.md` §2.c) — schedule a virtual
-   * actuation for exactly `tick`: applied at the START of that tick's
-   * `poll()` (composing with `runTicks` — a schedule for tick 500 fires
-   * exactly once the sim has been driven through tick 500, regardless of
-   * burst size). A digital `true` produces a genuine `isJustPressed` edge
-   * exactly at the target tick (not merely a held value — see
-   * `applyScheduledActionsForTick`).
+   * D15/T-D15.5 — schedule a virtual actuation for exactly `tick`: applied
+   * at the START of that tick's `poll()` (composing with `runTicks` — a
+   * schedule for tick 500 fires exactly once the sim has been driven through
+   * tick 500, regardless of burst size). A digital `true` produces a genuine
+   * `isJustPressed` edge exactly at the target tick (not merely a held value
+   * — see `applyScheduledActionsForTick`).
    *
    * Throws `InputActionError` for an unregistered `action` and the same
    * valueType-mismatch error every typed getter throws (`assertValueType`) —
@@ -2222,7 +2219,7 @@ export class InputManager {
    *  `'input.schedule.dropped'` (`{tick, action}`) whenever it discards a
    *  scheduled entry for a tick whose input phase never ran. Called once by
    *  whoever constructs this `InputManager` with a `DebugRegistry` behind it
-   *  (`vgai-scene-game-adapter.ts`), the same seed spot as
+   *  (`setup-three-root-adapter.ts`), the same seed spot as
    *  `setVirtualInputTarget`/`setInputActionsSource` — never called directly
    *  by gameplay code. */
   setDebugEmit(fn: ((event: string, detail?: unknown) => void) | null): void {

package/src/input/input-types.ts

@@ -90,8 +90,8 @@ export type ActionValueOf<T extends ActionValueType> = T extends 'digital'
  * value. Returned by the `*Source` sibling of each typed getter (e.g. `getScalarSource`).
  */
 export interface ActionValueSource {
-  /** The binding kind that produced the current value. `'virtual'` (Task 1.4,
-   *  E2E-TESTING-BUILD-PLAN.md) is not a real `InputBinding` — it marks a
+  /** The binding kind that produced the current value. `'virtual'`
+   *  (Task 1.4) is not a real `InputBinding` — it marks a
    *  value written by `InputManager.setVirtualAction` (the synthetic-player
    *  seat), not a device binding. */
   bindingType: InputBinding['type'] | 'virtual';

package/src/input/schema.ts

@@ -1,10 +1,10 @@
 // T4.6 — the `.inputmap.json` schema.
 //
-// Was TS-types-only (`input-types.ts`) until T4.6 authored this Zod schema —
-// see docs/BACKBONE-TASKS.md T4.6. `InputManager.loadMap` (input-manager.ts)
-// is this schema's runtime reader: it parses via this schema, then copies
-// each action's `bindings` array (and its declared `valueType`, F1) straight
-// into `this.actions`/`this.actionValueTypes`.
+// Was TS-types-only (`input-types.ts`) until T4.6 authored this Zod schema.
+// `InputManager.loadMap` (input-manager.ts) is this schema's runtime reader: it
+// parses via this schema, then copies each action's `bindings` array (and its
+// declared `valueType`, F1) straight into
+// `this.actions`/`this.actionValueTypes`.
 //
 // Every field has a `.describe()` (repo policy — powers
 // `scripts/generate-schema.ts` and the T4.1/T4.6 schema-walk coverage test).

package/src/loader.ts

@@ -14,6 +14,7 @@ import * as THREE from 'three';
 import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
 import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
 import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
 
 let _prefix = '/';
 
@@ -49,9 +50,65 @@ export const textureLoader = new THREE.TextureLoader(loadingManager);
 export const dracoLoader = new DRACOLoader(loadingManager);
 dracoLoader.setDecoderPath('/jsm/libs/draco/gltf/');
 
+/**
+ * Shared KTX2Loader for decoding KHR_texture_basisu (KTX2/Basis) textures.
+ *
+ * Vendored and served EXACTLY like the DRACO decoder above — the Basis
+ * transcoder js/wasm live in repo-root `public/jsm/libs/basis/` (the editor)
+ * and `packages/editor/template/public/jsm/libs/basis/` (a scaffolded game's
+ * own build), pinned in `vendor/upstream-assets.lock.json`, and KTX2Loader
+ * appends `basis_transcoder.js` / `.wasm` to this absolute path.
+ *
+ * Without this wiring, the Asset Budget's "Compress textures · KTX2" output
+ * is a GLB nothing in the engine can load — which is why the op and this
+ * loader landed together.
+ */
+export const ktx2Loader = new KTX2Loader(loadingManager);
+ktx2Loader.setTranscoderPath('/jsm/libs/basis/');
+
+let ktx2SupportDetected = false;
+
+/**
+ * Teach the shared KTX2Loader which compressed formats THIS GPU accepts.
+ *
+ * KTX2Loader refuses to transcode until it has seen a renderer, and the
+ * answer is a property of the page's GPU rather than of any one renderer —
+ * so the FIRST renderer to exist supplies it and every later one is a no-op.
+ * Called by the engine's own renderer setup (`setup/setup-renderer.ts`) and
+ * by the editor's viewport, which between them cover every surface that
+ * parses a GLB.
+ *
+ * This sits on the MOUNT path, so it must never throw for a renderer it
+ * cannot question. `detectSupport` reads `renderer.extensions.has/get` (or
+ * `renderer.hasFeature` on a WebGPU renderer) — surface a headless stand-in
+ * (the test harnesses' fake renderers, any non-WebGL host) does not have.
+ * Such a renderer is skipped WITHOUT latching, so the first renderer that
+ * can actually answer still configures the loader for the whole page.
+ */
+export function detectKtx2Support(renderer: THREE.WebGLRenderer): void {
+  if (ktx2SupportDetected) return;
+  const probe = renderer as unknown as
+    | {
+        isWebGPURenderer?: boolean;
+        hasFeature?: unknown;
+        extensions?: { has?: unknown; get?: unknown };
+      }
+    | null
+    | undefined;
+  const canAnswer =
+    probe != null &&
+    (probe.isWebGPURenderer === true
+      ? typeof probe.hasFeature === 'function'
+      : typeof probe.extensions?.has === 'function' && typeof probe.extensions?.get === 'function');
+  if (!canAnswer) return;
+  ktx2Loader.detectSupport(renderer);
+  ktx2SupportDetected = true;
+}
+
 /** Pre-configured GLTFLoader using the shared manager, with DRACO decoding wired in. */
 export const gltfLoader = new GLTFLoader(loadingManager);
 gltfLoader.setDRACOLoader(dracoLoader);
+gltfLoader.setKTX2Loader(ktx2Loader);
 // EXT_meshopt_compression decoding (three's own bundled decoder — inline
 // wasm, no fetch). Without this, a meshopt-compressed GLB — including the
 // output of the editor's Asset Budget "Compress · meshopt" action (W4a M3) —

package/src/manifest/editor-port.ts

@@ -0,0 +1,69 @@
+/**
+ * The editor's built-in port fallback, and the paired HMR-socket derivation.
+ *
+ * ONE owner for the number, because it is spelled in a launcher (`vgai edit`),
+ * three servers (dev / prod / packaged), and a client default — a duplicated
+ * literal across those drifts silently.
+ *
+ * **Why not Vite's 5173.** It used to be exactly that, and 5173 is the default
+ * of every Vite app on the machine. On a box running any other Vite dev server
+ * the engine-repo editor and that app fight over one port, and — worse —
+ * `http://…:5173` can resolve to a FOREIGN application. Measured 2026-08-07:
+ * an unrelated process on 5173 was what the editor's tab self-heal opened.
+ *
+ * **The band.** 20000-20199 is vgai's own reserved band: fixed, hand-picked
+ * ports that must never be minted for a worktree session. Machine-local
+ * allocations start at 20200, so one can never land on this default by chance.
+ * 20173 keeps Vite's memorable `173` tail while sitting in a range nothing
+ * else claims.
+ */
+export const DEFAULT_EDITOR_PORT = 20_173;
+
+/**
+ * The Vite HMR websocket port paired with an editor port.
+ *
+ * Editor ports in 20000-29999 map into the parallel 30000-39999 band, so two
+ * worktree sessions cannot collide merely because their editor ports differ
+ * by 100. Anything outside that band keeps the simple +100 offset.
+ *
+ * `DEFAULT_EDITOR_PORT` derives 30173 through the first arm — no special case,
+ * which is the point: the old expression carried a hardcoded `5173 -> 24678`
+ * exception precisely because the default sat outside the band it designed.
+ */
+export function editorHmrPort(editorPort: number): number {
+  return editorPort >= 20_000 && editorPort < 30_100 ? editorPort + 10_000 : editorPort + 100;
+}
+
+/**
+ * Wrap a bare IPv6 literal in brackets so it is legal inside a URL authority.
+ * `127.0.0.1`, a hostname, and an already-bracketed literal pass through.
+ */
+function urlAuthorityHost(host: string): string {
+  if (host.startsWith('[')) return host;
+  return host.includes(':') ? `[${host}]` : host;
+}
+
+/**
+ * The ONE composer for an editor origin — every URL vgai PRINTS, OPENS,
+ * SELF-HEALS with, records in `.vgai/session.json`, or dials.
+ *
+ * **It never says `localhost`.** A bare-`localhost` URL is a different address
+ * from the one the server is listening on: on a dual-stack box `localhost`
+ * resolves `::1` first while the editor binds `127.0.0.1`, so the URL reaches
+ * whatever else happens to hold that port on IPv6. Measured 2026-08-07 — the
+ * tab bijection's self-heal opened an UNRELATED application in the owner's
+ * browser because it composed its reopen URL from `localhost` instead of the
+ * host the server had actually bound.
+ *
+ * `bindHost` is the host the server bound (`resolveBindHost`); callers that
+ * only know a port — the CLI and SDK clients dialing a local session — omit it
+ * and get the IPv4 loopback literal. A wildcard bind (`0.0.0.0` / `::`, which
+ * is what WSL gets) is not an address a browser can visit, so it degrades to
+ * that same literal: reachable from the same box, and reachable from Windows
+ * through WSL2's loopback forwarding.
+ */
+export function editorOrigin(port: number, bindHost?: string): string {
+  const host = (bindHost ?? '').trim();
+  const unusable = host === '' || host === '0.0.0.0' || host === '::' || host === '[::]';
+  return `http://${unusable ? '127.0.0.1' : urlAuthorityHost(host)}:${port}`;
+}

package/src/manifest/filename.ts

@@ -0,0 +1,49 @@
+// The project manifest's FILENAME. There is exactly ONE.
+//
+// The manifest is `vgai.project.json`. It used to be `vgai.game.json`, and for
+// a while both names were read — WO-9 #62 recorded that dual-read as
+// permanent, on the presumption of an EXTERNAL constituency of projects
+// already on disk. The owner reversed that on 2026-08-02 (the legacy-removal
+// doctrine, `docs/ARCHITECTURE-CORE.md` §Vocabulary): this is pre-release
+// software, no such constituency exists, and a second way to spell the
+// manifest is the defect — two accepted names meant both kept being written,
+// and copies of the "try both" probe grew in five modules that agreed with the
+// real resolver only by coincidence.
+//
+// So the old name is REMOVED, and removed means it REJECTS LOUDLY naming the
+// exact one-line fix — never silently ignored, never redirected. A directory
+// carrying only `vgai.game.json` is an error with a `git mv` in the message,
+// not a project that quietly fails to open.
+//
+// This module is the ONE place either literal is spelled out, and it is
+// dependency-free (no `node:fs`) so browser bundles can import it. The
+// filesystem side lives in `./locate` (`resolveManifestPath`, `hasManifest`,
+// `assertNoRemovedManifestFilename`).
+
+/** The manifest filename. Every reader reads it; every writer writes it. */
+export const MANIFEST_FILENAME = 'vgai.project.json';
+
+/** The removed filename. Read by nothing — its only job is the error message. */
+export const REMOVED_MANIFEST_FILENAME = 'vgai.game.json';
+
+/** True for the manifest filename (basename comparison). */
+export function isManifestFilename(name: string): boolean {
+  return name === MANIFEST_FILENAME;
+}
+
+/**
+ * The verbatim rejection an on-disk `vgai.game.json` earns — the one-line fix
+ * spelled out, per the removed-format contract. Shared by the Node
+ * (`./locate`) and browser (storage-backend) halves so a project author sees
+ * the same sentence wherever the stale name is found.
+ */
+export function removedManifestFilenameMessage(where: string): string {
+  return (
+    `${where}: found \`${REMOVED_MANIFEST_FILENAME}\` and no \`${MANIFEST_FILENAME}\`. ` +
+    `\`${REMOVED_MANIFEST_FILENAME}\` was REMOVED (WO-LR1; the legacy-removal doctrine, ` +
+    'docs/ARCHITECTURE-CORE.md §Vocabulary) — nothing reads it any more, and it is ' +
+    'deliberately NOT read as a fallback, because a second accepted name is the defect.\n' +
+    `Fix: rename it — \`git mv ${REMOVED_MANIFEST_FILENAME} ${MANIFEST_FILENAME}\`. ` +
+    'The contents are unchanged; only the filename moved.'
+  );
+}

package/src/manifest/index.ts

@@ -1,6 +1,12 @@
-// Game manifest (vgai.game.json) — schema + loader (T3.1 slice 1).
-// See docs/GAME-MANIFEST-DESIGN.md.
+// Game manifest (vgai.project.json) — schema + loader (T3.1 slice
+// 1)..
 
+export {
+  isManifestFilename,
+  MANIFEST_FILENAME,
+  REMOVED_MANIFEST_FILENAME,
+  removedManifestFilenameMessage,
+} from './filename';
 export type { ResolvedAdapter, ResolvedAdapterRoot, ResolvedGameManifest } from './load';
 export { CAPABILITY_CEILINGS, DEFAULT_SERVER_MODULE, loadGameManifest } from './load';
 export type {

package/src/manifest/load-file.ts

@@ -8,9 +8,20 @@
 
 import { readFileSync } from 'node:fs';
 import { loadGameManifest, type ResolvedGameManifest } from './load';
+import { resolveManifestPath } from './locate';
+
+// The dual-name filesystem lookup lives in `./locate` (Zod-free on purpose);
+// re-exported here so the common "load a project's manifest" import is one
+// module.
+export { hasManifest, manifestWritePath, resolveManifestPath } from './locate';
 
 /** Read + JSON.parse `path`, then resolve it via `loadGameManifest`. Node-only. */
 export function loadGameManifestFile(path: string): ResolvedGameManifest {
   const raw: unknown = JSON.parse(readFileSync(path, 'utf-8'));
   return loadGameManifest(raw);
 }
+
+/** {@link loadGameManifestFile} against `dir`'s `vgai.project.json`. */
+export function loadGameManifestDir(dir: string): ResolvedGameManifest {
+  return loadGameManifestFile(resolveManifestPath(dir));
+}