@vgai/engine 0.5.5 → 0.5.6

package/dist/input/schema.js

@@ -0,0 +1,228 @@
+// T4.6 — the `.inputmap.json` schema.
+//
+// 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).
+// No runtime dependency beyond `zod`, matching the `scene/schema/` and
+// `manifest/schema.ts` precedent.
+//
+// T4.1 history (now closed by F2): `mouse_move` and `gamepad_axis_pair` were
+// authored-but-unhandled binding kinds — REJECTED at parse via a `.superRefine`
+// that threw naming the field, mirroring the `scene/schema/ui.ts` dead-field
+// mechanism. F2 (spec §12 "Complete Device Backends") un-rejects both: real
+// `InputManager` readers now exist for them (`collectPointerDeltaContributions`/
+// `collectVector2Contributions` — `mouse_move` feeds pointerDelta/vector2 from
+// the existing mouseDelta accumulator; `gamepad_axis_pair` feeds vector2 from
+// the coupled `xAxis`/`yAxis` gamepad reading). F2 also adds two new LIVE
+// binding kinds, `touch_button`/`touch_stick` (the touch/virtual-control
+// backend — see `InputManager.setTouchButton`/`setTouchStick`).
+//
+// F1 (spec §12 "Define Typed Action Values") adds:
+//  - `InputAction.valueType` — an action now DECLARES its value shape
+//    (`digital`/`scalar`/`vector2`/`pointerDelta`/`pointerPosition`),
+//    defaulted to `digital` so every pre-F1 action stays valid unchanged.
+//  - four new, LIVE (not dead-rejected) binding kinds — `test_axis`,
+//    `test_vector2`, `test_pointer_delta`, `test_pointer_position` — the
+//    "injected test input" backend F2's acceptance criteria names as a
+//    peer of keyboard/mouse/gamepad/touch. They read back a caller-injected
+//    raw value (InputManager.injectAxis/injectVector2/injectPointerDelta/
+//    injectPointerPosition) through the SAME deadzone/normalize/combine path
+//    real device bindings use.
+import { z } from 'zod';
+const KeyBindingSchema = z.object({
+    type: z.literal('key').describe('Binding kind: a keyboard key (KeyboardEvent.code)'),
+    code: z.string().describe('KeyboardEvent.code value, e.g. "KeyW", "Space", "ArrowUp"'),
+});
+const MouseButtonBindingSchema = z.object({
+    type: z.literal('mouse_button').describe('Binding kind: a mouse button'),
+    button: z.number().describe('MouseEvent.button index (0 = left, 1 = middle, 2 = right)'),
+});
+const MouseMoveBindingSchema = z.object({
+    type: z
+        .literal('mouse_move')
+        .describe('Binding kind: raw mouse movement (F2, spec §12 "Complete Device Backends"). Feeds a ' +
+        "'pointerDelta'-valueType action with the raw accumulated mouse delta (no deadzone), and " +
+        "can also feed a 'vector2'-valueType action (the same delta, radial-deadzoned + unit-" +
+        'circle-clamped via `deadzone`).'),
+    deadzone: z
+        .number()
+        .optional()
+        .describe("Radial deadzone magnitude applied only when this binding feeds a 'vector2'-valueType " +
+        "action (default 0 — no deadzone; ignored for 'pointerDelta' reads, which are never " +
+        'deadzoned).'),
+});
+const GamepadButtonBindingSchema = z.object({
+    type: z.literal('gamepad_button').describe('Binding kind: a gamepad face/shoulder button'),
+    button: z.number().describe('Standard Gamepad API button index'),
+});
+const GamepadAxisBindingSchema = z.object({
+    type: z.literal('gamepad_axis').describe('Binding kind: a single thresholded gamepad axis'),
+    axis: z.number().describe('Standard Gamepad API axis index'),
+    direction: z
+        .enum(['positive', 'negative'])
+        .describe('Which side of the deadzone counts as "pressed"'),
+    deadzone: z.number().optional().describe('Deadzone magnitude (default 0.15 if omitted)'),
+});
+const GamepadAxisPairBindingSchema = z.object({
+    type: z
+        .literal('gamepad_axis_pair')
+        .describe('Binding kind: a coupled (x, y) gamepad axis pair, e.g. a stick used as a 2D vector ' +
+        '(look/aim/movement) (F2, spec §12 "Complete Device Backends"). Feeds a ' +
+        "'vector2'-valueType action: (xAxis, yAxis) read together, radial-deadzoned + unit-" +
+        'circle-clamped the same way a real analog stick is.'),
+    xAxis: z.number().describe('Standard Gamepad API axis index for the X component'),
+    yAxis: z.number().describe('Standard Gamepad API axis index for the Y component'),
+    deadzone: z.number().optional().describe('Deadzone magnitude (default 0.15 if omitted)'),
+});
+// ---------------------------------------------------------------------------
+// F1 (spec §12) — injected test input bindings. LIVE (real runtime readers in
+// InputManager's getScalar/getVector2/getPointerDelta/getPointerPosition),
+// unlike the two dead stubs above. Foreshadows F2's "injected test input"
+// backend: real device kinds F2 adds later feed the same typed-value
+// aggregation path these exercise today.
+// ---------------------------------------------------------------------------
+const TestAxisBindingSchema = z.object({
+    type: z
+        .literal('test_axis')
+        .describe("Binding kind: an injected synthetic scalar value for a 'scalar'-valueType action " +
+        '(InputManager.injectAxis/getScalar) — the "injected test input" backend named in F2, ' +
+        "built in F1 as the typed scalar value model's testable source."),
+    sourceId: z
+        .string()
+        .describe('Names the injected test source this binding reads (InputManager.injectAxis).'),
+    deadzone: z
+        .number()
+        .optional()
+        .describe('1D deadzone magnitude applied to the injected raw value before combine (default 0 — no ' +
+        'deadzone). Values below it read as 0; values at/above it rescale from 0 (at the ' +
+        'deadzone edge) to ±1 (at |raw| = 1), sign preserved.'),
+});
+const TestVector2BindingSchema = z.object({
+    type: z
+        .literal('test_vector2')
+        .describe("Binding kind: an injected synthetic {x,y} value for a 'vector2'-valueType action " +
+        '(InputManager.injectVector2/getVector2) — the "injected test input" backend named in ' +
+        "F2, built in F1 as the typed Vector2 value model's testable source."),
+    sourceId: z
+        .string()
+        .describe('Names the injected test source this binding reads (InputManager.injectVector2).'),
+    deadzone: z
+        .number()
+        .optional()
+        .describe('Radial deadzone magnitude applied to the injected raw {x,y} before combine (default 0 ' +
+        '— no deadzone). Vectors whose magnitude is below it read as {0,0}; at/above it, ' +
+        'direction is preserved and magnitude rescales the same way the scalar deadzone does, ' +
+        'then the result is clamped to the unit circle (magnitude <= 1).'),
+});
+const TestPointerDeltaBindingSchema = z.object({
+    type: z
+        .literal('test_pointer_delta')
+        .describe("Binding kind: an injected synthetic per-frame {x,y} delta for a 'pointerDelta'-" +
+        'valueType action (InputManager.injectPointerDelta/getPointerDelta) — the "injected ' +
+        'test input" backend named in F2. No deadzone (deltas are not deadzoned).'),
+    sourceId: z
+        .string()
+        .describe('Names the injected test source this binding reads (InputManager.injectPointerDelta).'),
+});
+const TestPointerPositionBindingSchema = z.object({
+    type: z
+        .literal('test_pointer_position')
+        .describe("Binding kind: an injected synthetic absolute {x,y} position for a 'pointerPosition'-" +
+        'valueType action (InputManager.injectPointerPosition/getPointerPosition) — the ' +
+        '"injected test input" backend named in F2.'),
+    sourceId: z
+        .string()
+        .describe('Names the injected test source this binding reads (InputManager.injectPointerPosition).'),
+});
+// ---------------------------------------------------------------------------
+// F2 (spec §12 "Complete Device Backends") — touch/virtual-control bindings.
+// LIVE (real runtime readers in InputManager's isPressed/isJustPressed/
+// isJustReleased/getDigitalSource and getVector2), driven by
+// InputManager.setTouchButton/setTouchStick — the headless-testable
+// injectable entry points a real on-screen touch-control UI's own
+// touchstart/touchmove/touchend handlers would call (that DOM wiring is a
+// thin adapter at the edge, out of scope here — see input-manager.ts).
+// ---------------------------------------------------------------------------
+const TouchButtonBindingSchema = z.object({
+    type: z
+        .literal('touch_button')
+        .describe("Binding kind: a virtual on-screen button for a 'digital' action " +
+        '(InputManager.setTouchButton/isPressed) — edge-tracked (isJustPressed/isJustReleased) ' +
+        'the same way a real mouse/keyboard button is.'),
+    sourceId: z
+        .string()
+        .describe('Names the virtual control zone this binding reads (InputManager.setTouchButton) — a ' +
+        'touch-UI-chosen id, not a real device index.'),
+});
+const TouchStickBindingSchema = z.object({
+    type: z
+        .literal('touch_stick')
+        .describe("Binding kind: a virtual on-screen analog stick for a 'vector2' action " +
+        '(InputManager.setTouchStick/getVector2) — radial-deadzoned + unit-circle-clamped the ' +
+        'same way a real gamepad stick is.'),
+    sourceId: z
+        .string()
+        .describe('Names the virtual control zone this binding reads (InputManager.setTouchStick) — a ' +
+        'touch-UI-chosen id, not a real device index.'),
+    deadzone: z
+        .number()
+        .optional()
+        .describe('Radial deadzone magnitude applied to the raw {x,y} before combine (default 0 — no ' +
+        'deadzone).'),
+});
+/** A single input binding. Every kind listed here is LIVE — F2 (spec §12) closed the last two
+ *  dead stubs (`mouse_move`/`gamepad_axis_pair`) by giving both real `InputManager` readers. */
+export const InputBindingSchema = z.discriminatedUnion('type', [
+    KeyBindingSchema,
+    MouseButtonBindingSchema,
+    MouseMoveBindingSchema,
+    GamepadButtonBindingSchema,
+    GamepadAxisBindingSchema,
+    GamepadAxisPairBindingSchema,
+    TestAxisBindingSchema,
+    TestVector2BindingSchema,
+    TestPointerDeltaBindingSchema,
+    TestPointerPositionBindingSchema,
+    TouchButtonBindingSchema,
+    TouchStickBindingSchema,
+]);
+/** An action has a name (the record key) and one or more bindings. */
+export const InputActionSchema = z.object({
+    valueType: z
+        .enum(['digital', 'scalar', 'vector2', 'pointerDelta', 'pointerPosition'])
+        .default('digital')
+        .describe("This action's declared value shape (F1, spec §12). 'digital' (boolean, with " +
+        'pressed/justPressed/justReleased edges) is the default when omitted, matching every ' +
+        "action authored before F1. 'scalar' is a single deadzone-rescaled float axis. " +
+        "'vector2' is a radial-deadzoned, unit-circle-normalized {x,y}. 'pointerDelta' is a " +
+        "per-frame {x,y} movement delta, summed across sources. 'pointerPosition' is an " +
+        'absolute {x,y}, last-write-wins across sources. InputManager enforces this at read ' +
+        'time: reading an action through the wrong typed getter (e.g. getScalar on a ' +
+        "'digital' action) throws."),
+    bindings: z
+        .array(InputBindingSchema)
+        .describe('Bindings that all trigger/feed this action. Digital actions combine via OR (any one ' +
+        'binding satisfied is enough). Scalar actions combine via max-magnitude across ' +
+        'contributing bindings (ties keep the first-listed binding). Vector2 actions combine ' +
+        'by summing contributing {x,y} values then clamping to the unit circle. PointerDelta ' +
+        'actions sum contributing deltas. PointerPosition actions use the most-recently-' +
+        'written contributing source (last-write-wins).'),
+});
+/**
+ * The `.inputmap.json` file format (`InputManager.loadMap`).
+ *
+ * `version` is RESERVED (no range-check reader exists yet for this format —
+ * same convention `2d.version`/`Scene2DSchema` used before T2.3 gave the 3D
+ * scene version axis a real reader; see `schema-consumption-map.ts`).
+ */
+export const InputMapFileSchema = z.object({
+    version: z.number().describe('Input map file format version (RESERVED — no range check yet)'),
+    actions: z
+        .record(z.string(), InputActionSchema)
+        .describe('Named actions, each with a list of bindings (InputManager.loadMap)'),
+});

package/dist/loader.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Shared asset loading infrastructure.
+ *
+ * Provides a single LoadingManager (for Three.js loaders) and resolveUrl()
+ * (for raw fetch calls) so that all engine asset requests go through one
+ * configurable URL prefix. Call setAssetPrefix() once at runtime startup.
+ *
+ * Three.js loaders constructed with `loadingManager` automatically rewrite
+ * URLs via setURLModifier(). For raw fetch() calls, wrap the URL with
+ * resolveUrl() to apply the same prefix.
+ */
+import * as THREE from 'three';
+import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
+/** Shared Three.js LoadingManager — all engine loaders should use this. */
+export declare const loadingManager: THREE.LoadingManager;
+/** Pre-configured TextureLoader using the shared manager. */
+export declare const textureLoader: THREE.TextureLoader;
+/**
+ * Shared DRACOLoader for decoding DRACO-compressed GLTF/GLB meshes.
+ *
+ * The decoder wasm/js is vendored under
+ * packages/editor/template/public/jsm/libs/draco/gltf/ and served at the
+ * absolute runtime path '/jsm/libs/draco/gltf/' (DRACOLoader appends
+ * draco_wasm_wrapper.js / draco_decoder.wasm to this path). This is an
+ * absolute path, so it deliberately does NOT go through the asset prefix —
+ * the decoder is engine infrastructure, not a scene asset.
+ */
+export declare const dracoLoader: DRACOLoader;
+/**
+ * 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 declare const ktx2Loader: KTX2Loader;
+/**
+ * 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 declare function detectKtx2Support(renderer: THREE.WebGLRenderer): void;
+/** Pre-configured GLTFLoader using the shared manager, with DRACO decoding wired in. */
+export declare const gltfLoader: GLTFLoader;
+/**
+ * Set the URL prefix prepended to relative asset paths.
+ * Called once by createGameRuntime(). Defaults to '/'.
+ */
+export declare function setAssetPrefix(prefix: string): void;
+/**
+ * Resolve a relative asset URL using the current prefix.
+ * Use this for raw fetch() calls — Three.js loaders using
+ * `loadingManager` handle this automatically.
+ */
+export declare function resolveUrl(url: string): string;
+//# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAgBhE,2EAA2E;AAC3E,eAAO,MAAM,cAAc,sBAA6B,CAAC;AAGzD,6DAA6D;AAC7D,eAAO,MAAM,aAAa,qBAA0C,CAAC;AAErE;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,aAAkC,CAAC;AAG3D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU,YAAiC,CAAC;AAKzD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,KAAK,CAAC,aAAa,GAAG,IAAI,CAkBrE;AAED,wFAAwF;AACxF,eAAO,MAAM,UAAU,YAAiC,CAAC;AAUzD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C"}

package/dist/loader.js

@@ -0,0 +1,114 @@
+/**
+ * Shared asset loading infrastructure.
+ *
+ * Provides a single LoadingManager (for Three.js loaders) and resolveUrl()
+ * (for raw fetch calls) so that all engine asset requests go through one
+ * configurable URL prefix. Call setAssetPrefix() once at runtime startup.
+ *
+ * Three.js loaders constructed with `loadingManager` automatically rewrite
+ * URLs via setURLModifier(). For raw fetch() calls, wrap the URL with
+ * resolveUrl() to apply the same prefix.
+ */
+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 = '/';
+function rewriteUrl(url) {
+    if (url.startsWith('/') ||
+        url.startsWith('http') ||
+        url.startsWith('data:') ||
+        url.startsWith('blob:')) {
+        return url;
+    }
+    return _prefix + url;
+}
+/** Shared Three.js LoadingManager — all engine loaders should use this. */
+export const loadingManager = new THREE.LoadingManager();
+loadingManager.setURLModifier(rewriteUrl);
+/** Pre-configured TextureLoader using the shared manager. */
+export const textureLoader = new THREE.TextureLoader(loadingManager);
+/**
+ * Shared DRACOLoader for decoding DRACO-compressed GLTF/GLB meshes.
+ *
+ * The decoder wasm/js is vendored under
+ * packages/editor/template/public/jsm/libs/draco/gltf/ and served at the
+ * absolute runtime path '/jsm/libs/draco/gltf/' (DRACOLoader appends
+ * draco_wasm_wrapper.js / draco_decoder.wasm to this path). This is an
+ * absolute path, so it deliberately does NOT go through the asset prefix —
+ * the decoder is engine infrastructure, not a scene asset.
+ */
+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) {
+    if (ktx2SupportDetected)
+        return;
+    const probe = renderer;
+    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) —
+// throws at load time in every runtime and the editor viewport. Symmetric
+// with the DRACO wiring above (CB2): the ONE shared loader owns codec setup.
+gltfLoader.setMeshoptDecoder(MeshoptDecoder);
+/**
+ * Set the URL prefix prepended to relative asset paths.
+ * Called once by createGameRuntime(). Defaults to '/'.
+ */
+export function setAssetPrefix(prefix) {
+    _prefix = prefix.endsWith('/') ? prefix : prefix ? `${prefix}/` : '/';
+}
+/**
+ * Resolve a relative asset URL using the current prefix.
+ * Use this for raw fetch() calls — Three.js loaders using
+ * `loadingManager` handle this automatically.
+ */
+export function resolveUrl(url) {
+    return rewriteUrl(url);
+}

package/dist/manifest/editor-port.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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 declare const DEFAULT_EDITOR_PORT = 20173;
+/**
+ * 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 declare function editorHmrPort(editorPort: number): number;
+/**
+ * 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 declare function editorOrigin(port: number, bindHost?: string): string;
+//# sourceMappingURL=editor-port.d.ts.map

package/dist/manifest/editor-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor-port.d.ts","sourceRoot":"","sources":["../../src/manifest/editor-port.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAExD;AAWD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAIpE"}

package/dist/manifest/editor-port.js

@@ -0,0 +1,67 @@
+/**
+ * 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) {
+    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) {
+    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, bindHost) {
+    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/dist/manifest/filename.d.ts

@@ -0,0 +1,14 @@
+/** The manifest filename. Every reader reads it; every writer writes it. */
+export declare const MANIFEST_FILENAME = "vgai.project.json";
+/** The removed filename. Read by nothing — its only job is the error message. */
+export declare const REMOVED_MANIFEST_FILENAME = "vgai.game.json";
+/** True for the manifest filename (basename comparison). */
+export declare function isManifestFilename(name: string): boolean;
+/**
+ * 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 declare function removedManifestFilenameMessage(where: string): string;
+//# sourceMappingURL=filename.d.ts.map

package/dist/manifest/filename.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filename.d.ts","sourceRoot":"","sources":["../../src/manifest/filename.ts"],"names":[],"mappings":"AAsBA,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AAErD,iFAAiF;AACjF,eAAO,MAAM,yBAAyB,mBAAmB,CAAC;AAE1D,4DAA4D;AAC5D,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASpE"}

package/dist/manifest/filename.js

@@ -0,0 +1,43 @@
+// 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) {
+    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) {
+    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/dist/manifest/index.d.ts

@@ -0,0 +1,6 @@
+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 { AdapterRoot, GameManifest, IngestStrategy, RootAdapter, Tier, } from './schema';
+export { AdapterRootSchema, GameManifestSchema, IngestStrategySchema, RootAdapterSchema, TierSchema, } from './schema';
+//# sourceMappingURL=index.d.ts.map

package/dist/manifest/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/manifest/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,yBAAyB,EACzB,8BAA8B,GAC/B,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AACzF,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AACtF,YAAY,EACV,WAAW,EACX,YAAY,EACZ,cAAc,EACd,WAAW,EACX,IAAI,GACL,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,UAAU,GACX,MAAM,UAAU,CAAC"}

package/dist/manifest/index.js

@@ -0,0 +1,9 @@
+// Game manifest (vgai.project.json) — schema + loader (T3.1 slice
+// 1)..
+export { isManifestFilename, MANIFEST_FILENAME, REMOVED_MANIFEST_FILENAME, removedManifestFilenameMessage, } from './filename';
+export { CAPABILITY_CEILINGS, DEFAULT_SERVER_MODULE, loadGameManifest } from './load';
+export { AdapterRootSchema, GameManifestSchema, IngestStrategySchema, RootAdapterSchema, TierSchema, } from './schema';
+// `loadGameManifestFile` (Node-only, reads `path` via `node:fs`) is
+// deliberately NOT re-exported here — this barrel must stay import-safe for
+// browser bundles. Import it directly from `@engine/manifest/load-file` in
+// Node-only contexts (CLI, tests).

package/dist/manifest/load-file.d.ts

@@ -0,0 +1,7 @@
+import { type ResolvedGameManifest } from './load';
+export { hasManifest, manifestWritePath, resolveManifestPath } from './locate';
+/** Read + JSON.parse `path`, then resolve it via `loadGameManifest`. Node-only. */
+export declare function loadGameManifestFile(path: string): ResolvedGameManifest;
+/** {@link loadGameManifestFile} against `dir`'s `vgai.project.json`. */
+export declare function loadGameManifestDir(dir: string): ResolvedGameManifest;
+//# sourceMappingURL=load-file.d.ts.map

package/dist/manifest/load-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-file.d.ts","sourceRoot":"","sources":["../../src/manifest/load-file.ts"],"names":[],"mappings":"AASA,OAAO,EAAoB,KAAK,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAMrE,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAE/E,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,CAGvE;AAED,wEAAwE;AACxE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CAErE"}