@vgai/engine 0.5.15 → 0.5.16

package/src/adapter/native-debug-module.ts

@@ -0,0 +1,307 @@
+/**
+ * The ordinary module surface a native game may expose to its own debugger.
+ *
+ * A root entry re-exports one `debug` object from the project's command module:
+ *
+ *   export { debug } from './commands';
+ *
+ * The command module imports no vgai API. Its functions are the application's
+ * own functions over its own stores; the native adapter merely projects that
+ * existing registry onto the session debug/input doors after the root mounts.
+ * Loading through the root entry is load-bearing: the functions close over the
+ * exact module graph the mounted application uses, never a separately evaluated
+ * copy of its stores.
+ */
+
+import {
+  DebugError,
+  type DebugRegistry,
+  type DebugVirtualInputTarget,
+  getDebugRegistry,
+} from '../runtime/debug-registry';
+import type { Game } from '../runtime/game';
+
+export const NATIVE_INPUT_VALUE_TYPES = [
+  'digital',
+  'scalar',
+  'vector2',
+  'pointerDelta',
+  'pointerPosition',
+] as const;
+export type NativeInputValueType = (typeof NATIVE_INPUT_VALUE_TYPES)[number];
+export type NativeInputValue = boolean | number | { readonly x: number; readonly y: number };
+
+export interface NativeDebugModule {
+  readonly commands?: Readonly<Record<string, (...args: unknown[]) => unknown>>;
+  readonly state?: Readonly<Record<string, () => unknown>>;
+  readonly input?: {
+    readonly actions: Readonly<Record<string, NativeInputValueType>>;
+    readonly set: (action: string, value: NativeInputValue) => void;
+    readonly clear: () => void;
+    /** Optional native-scheduler operation. The adapter never synthesizes one. */
+    readonly tap?: (action: string) => void;
+    /** Optional native-scheduler operation. The adapter never adds a host phase. */
+    readonly scheduleAtTick?: (tick: number, action: string, value: NativeInputValue) => void;
+  };
+}
+
+type NativeInputBinding = NonNullable<NativeDebugModule['input']>;
+
+export interface NativeDebugBinding {
+  readonly rootId: string;
+  readonly debug: NativeDebugModule;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function rejectUnknownKeys(value: Record<string, unknown>, allowed: readonly string[], at: string) {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length > 0) {
+    throw new Error(
+      `${at} has unknown ${unknown.length === 1 ? 'key' : 'keys'}: ${unknown.join(', ')}`,
+    );
+  }
+}
+
+function functionRecord(
+  value: unknown,
+  at: string,
+): Record<string, (...args: unknown[]) => unknown> {
+  if (!isRecord(value)) throw new Error(`${at} must be an object of named functions.`);
+  const out: Record<string, (...args: unknown[]) => unknown> = {};
+  for (const [name, candidate] of Object.entries(value)) {
+    if (!name) throw new Error(`${at} contains an empty name.`);
+    if (typeof candidate !== 'function') throw new Error(`${at}.${name} must be a function.`);
+    out[name] = candidate as (...args: unknown[]) => unknown;
+  }
+  return out;
+}
+
+function parseActions(value: unknown): Record<string, NativeInputValueType> {
+  if (!isRecord(value)) {
+    throw new Error('debug.input.actions must be an object mapping action names to value types.');
+  }
+  const actions: Record<string, NativeInputValueType> = {};
+  for (const [name, valueType] of Object.entries(value)) {
+    if (!name) throw new Error('debug.input.actions contains an empty action name.');
+    if (!NATIVE_INPUT_VALUE_TYPES.includes(valueType as NativeInputValueType)) {
+      throw new Error(
+        `debug.input.actions.${name} must be one of ${NATIVE_INPUT_VALUE_TYPES.join(', ')}.`,
+      );
+    }
+    actions[name] = valueType as NativeInputValueType;
+  }
+  return actions;
+}
+
+function parseInput(value: unknown): NativeInputBinding {
+  if (!isRecord(value)) throw new Error('debug.input must be an object.');
+  rejectUnknownKeys(value, ['actions', 'set', 'clear', 'tap', 'scheduleAtTick'], 'debug.input');
+  const set = value['set'];
+  const clear = value['clear'];
+  const tap = value['tap'];
+  const scheduleAtTick = value['scheduleAtTick'];
+  if (typeof set !== 'function') throw new Error('debug.input.set must be a function.');
+  if (typeof clear !== 'function') throw new Error('debug.input.clear must be a function.');
+  if (tap !== undefined && typeof tap !== 'function') {
+    throw new Error('debug.input.tap must be a function when provided.');
+  }
+  if (scheduleAtTick !== undefined && typeof scheduleAtTick !== 'function') {
+    throw new Error('debug.input.scheduleAtTick must be a function when provided.');
+  }
+  return {
+    actions: parseActions(value['actions']),
+    set: set as NativeInputBinding['set'],
+    clear: clear as NativeInputBinding['clear'],
+    ...(typeof tap === 'function' ? { tap: tap as NonNullable<NativeInputBinding['tap']> } : {}),
+    ...(typeof scheduleAtTick === 'function'
+      ? {
+          scheduleAtTick: scheduleAtTick as NonNullable<NativeInputBinding['scheduleAtTick']>,
+        }
+      : {}),
+  };
+}
+
+/** Read the single native `debug` export from an already-loaded root module. */
+export function nativeDebugBindingFromEntryModule(
+  rootId: string,
+  entryModule: unknown,
+): NativeDebugBinding | null {
+  if (!isRecord(entryModule) || entryModule['debug'] === undefined) return null;
+  if (!isRecord(entryModule['debug'])) {
+    throw new Error(`Root "${rootId}" exports \`debug\`, but it is not an object.`);
+  }
+  const raw = entryModule['debug'];
+  rejectUnknownKeys(raw, ['commands', 'state', 'input'], `Root "${rootId}" debug export`);
+
+  const commands =
+    raw['commands'] === undefined ? undefined : functionRecord(raw['commands'], 'debug.commands');
+  const state =
+    raw['state'] === undefined ? undefined : functionRecord(raw['state'], 'debug.state');
+  const input = raw['input'] === undefined ? undefined : parseInput(raw['input']);
+  if (!commands && !state && !input) {
+    throw new Error(`Root "${rootId}" exports an empty \`debug\` object.`);
+  }
+  return {
+    rootId,
+    debug: {
+      ...(commands ? { commands } : {}),
+      ...(state ? { state } : {}),
+      ...(input ? { input } : {}),
+    },
+  };
+}
+
+function valueMatches(type: NativeInputValueType, value: NativeInputValue): boolean {
+  if (type === 'digital') return typeof value === 'boolean';
+  if (type === 'scalar') return typeof value === 'number' && Number.isFinite(value);
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof value.x === 'number' &&
+    Number.isFinite(value.x) &&
+    typeof value.y === 'number' &&
+    Number.isFinite(value.y)
+  );
+}
+
+function installInput(
+  game: Game,
+  registry: DebugRegistry,
+  binding: NativeDebugBinding,
+  input: NativeInputBinding,
+): void {
+  const trace: Array<{ tick: number; action: string; value: NativeInputValue }> = [];
+  let recording = false;
+
+  const requireAction = (action: string, value: NativeInputValue): NativeInputValueType => {
+    const type = input.actions[action];
+    if (!type) {
+      throw new DebugError(
+        'INPUT_ACTION_NOT_FOUND',
+        `Native input has no action named "${action}".`,
+        {
+          registered: Object.keys(input.actions),
+        },
+      );
+    }
+    if (!valueMatches(type, value)) {
+      throw new DebugError(
+        'INPUT_ACTION_VALUE_TYPE',
+        `Native input action "${action}" expects ${type}, not ${typeof value}.`,
+        { action, expected: type },
+      );
+    }
+    return type;
+  };
+
+  const apply = (action: string, value: NativeInputValue, tick: number): void => {
+    requireAction(action, value);
+    input.set(action, value);
+    if (recording) trace.push({ tick, action, value });
+  };
+
+  const unsupportedSource = (method: string): never => {
+    throw new DebugError(
+      'NATIVE_INPUT_SOURCE_UNSUPPORTED',
+      `${method} addresses an engine test source, but this game exposes an app-owned action store. Drive it by action name instead.`,
+    );
+  };
+  const target: DebugVirtualInputTarget = {
+    setVirtualAction(action, value) {
+      apply(action, value, registry.getGameTick());
+      return { delivered: true };
+    },
+    tapVirtualAction(action) {
+      if (!input.tap) {
+        throw new DebugError(
+          'NATIVE_INPUT_TAP_UNSUPPORTED',
+          `Native input for root "${binding.rootId}" does not export tap(); use setVirtualAction through the app-owned store.`,
+        );
+      }
+      requireAction(action, true);
+      input.tap(action);
+      return { delivered: true };
+    },
+    clearVirtualActions() {
+      input.clear();
+    },
+    scheduleActionAtTick(tick, action, value) {
+      const currentTick = registry.getGameTick();
+      if (!Number.isInteger(tick) || tick < currentTick) {
+        throw new DebugError(
+          'TICK_ALREADY_PASSED',
+          `Cannot schedule native input for tick ${tick}; current tick is ${currentTick}.`,
+          { tick, currentTick },
+        );
+      }
+      requireAction(action, value);
+      if (!input.scheduleAtTick) {
+        throw new DebugError(
+          'NATIVE_INPUT_SCHEDULE_UNSUPPORTED',
+          `Native input for root "${binding.rootId}" does not export scheduleAtTick(); the adapter will not create a host scheduler for it.`,
+        );
+      }
+      input.scheduleAtTick(tick, action, value);
+    },
+    startInputRecording() {
+      trace.length = 0;
+      recording = true;
+    },
+    stopInputRecording() {
+      recording = false;
+    },
+    isInputRecording() {
+      return recording;
+    },
+    injectAxis() {
+      unsupportedSource('injectAxis');
+    },
+    injectVector2() {
+      unsupportedSource('injectVector2');
+    },
+    injectPointerDelta() {
+      unsupportedSource('injectPointerDelta');
+    },
+    injectPointerPosition() {
+      unsupportedSource('injectPointerPosition');
+    },
+  };
+
+  registry.setInputActionsSource(binding.rootId, () =>
+    Object.entries(input.actions).map(([name, valueType]) => ({ name, valueType })),
+  );
+  registry.setInputTraceSource(binding.rootId, () => ({
+    version: 1,
+    seed: null,
+    fixedDt: game.loop.fixedDt,
+    ticks: [...trace],
+  }));
+  registry.setVirtualInputTarget(binding.rootId, target);
+}
+
+/** Project native registries onto the existing session debugger after mount. */
+export function installNativeDebugBindings(
+  game: Game,
+  bindings: readonly NativeDebugBinding[],
+): void {
+  if (bindings.length === 0) return;
+  const registry = getDebugRegistry(game);
+  if (!registry)
+    throw new Error('Cannot install native debug bindings: mounted Game has no debug registry.');
+  for (const binding of bindings) {
+    if (!game.world(binding.rootId)) {
+      throw new Error(`Native debug binding names unmounted root "${binding.rootId}".`);
+    }
+    const root = registry.forRoot(binding.rootId);
+    for (const [name, read] of Object.entries(binding.debug.state ?? {})) {
+      root.registerStateProvider(name, read, { tier: 'assisted' });
+    }
+    for (const [name, command] of Object.entries(binding.debug.commands ?? {})) {
+      root.registerCommand(name, { locus: 'client' }, command);
+    }
+    if (binding.debug.input) installInput(game, registry, binding, binding.debug.input);
+  }
+}

package/src/adapter/object3d-authoring-subject.ts

@@ -0,0 +1,50 @@
+/**
+ * Transient authoring identity for a native subject represented by an
+ * Object3D proxy.
+ *
+ * Some ecosystem-native objects are not Object3Ds themselves: Rapier bodies
+ * and joints are the first examples. A project library may already own a
+ * viewport proxy for one of those objects. This mark lets the ordinary
+ * Object3D authoring projection name and inspect that proxy without teaching
+ * the editor shell the library's nouns or creating a persisted sidecar.
+ *
+ * The mark is observation only. Its values are read from the native owner at
+ * the moment they are requested, and any authored change still belongs in the
+ * owning TS/TSX or ecosystem artifact.
+ */
+
+import type * as THREE from 'three';
+import { deleteUserData, getUserData, setUserData } from '../ecs/user-data';
+import type { PropertyDescriptor } from './authoring';
+
+export interface Object3DAuthoringSubjectField extends PropertyDescriptor {
+  /** Read the current value from the native subject. */
+  readonly value: () => unknown;
+}
+
+export interface Object3DAuthoringSubjectMark {
+  readonly label: string;
+  readonly kind: string;
+  readonly typeLabel?: string;
+  readonly fields?: () => readonly Object3DAuthoringSubjectField[];
+  /** Presentation-only selection feedback for proxies hidden by default. */
+  readonly selectionChanged?: (selected: boolean) => void;
+}
+
+export function object3DAuthoringSubjectOf(
+  object: THREE.Object3D | null | undefined,
+): Object3DAuthoringSubjectMark | null {
+  const mark = getUserData(object, 'authoringSubject');
+  return mark && typeof mark.label === 'string' && typeof mark.kind === 'string' ? mark : null;
+}
+
+export function setObject3DAuthoringSubject(
+  object: THREE.Object3D,
+  mark: Object3DAuthoringSubjectMark,
+): void {
+  setUserData(object, 'authoringSubject', mark);
+}
+
+export function clearObject3DAuthoringSubject(object: THREE.Object3D): void {
+  deleteUserData(object, 'authoringSubject');
+}

package/src/adapter/root-adapter.ts

@@ -1,26 +1,10 @@
 /**
  * RootAdapter — the host ⇄ runtime contract. A ROOT is *anything that mounts*.
  *
- * This is the interface the HOST depends on. It replaces the old
- * `{ setup, components }` shape: the host no longer knows about `GameSetupFn`
- * — that is the internal of ONE implementer
- * (`SetupThreeRootAdapter`). First-party content and an unmodified external game
- * are peer implementers of THIS interface; the host has no branch on which.
- *
- * It was `GameAdapter` until WO-9 #60, and the rename is an ONTOLOGY fix, not
- * taste. Under D20 a *game* is the manifest's whole `roots` array — that is
- * what `runtime/game.ts`'s `Game` is. Every implementer of THIS interface
- * adapts exactly ONE root. So `Game` and `GameAdapter` sat at different levels
- * of the ontology while sharing a name-stem, which reads as though one were
- * the adapter for the other. The surrounding vocabulary had already moved:
- * `MountedRootBase`, `MountedRoot`, `MountedRootFor`, `RootStateObserver`,
- * `SurfaceAdapterFor`, `RootInstance`, `mountManifestRoots` — and, decisively,
- * the resolver that PRODUCES these (`resolveRootAdapter`, `RootAdapterSchema`,
- * `resolveThreeRootAdapter`) already said root. The interface was the last
- * holdout, out of step with its own resolver.
- *
- * The `K = 'three'` default below is KEPT deliberately (see the note on the
- * interface).
+ * This is the interface the host depends on. `GameSetupFn` is private to one
+ * implementer (`SetupThreeRootAdapter`); first-party content and unmodified
+ * external games are peer root adapters. A game is the manifest's complete
+ * roots array, while each adapter owns exactly one root.
  */
 
 import type { Container } from 'pixi.js';
@@ -62,12 +46,9 @@ export interface RootStateObserver {
 }
 
 /**
- * Everything a mounted world provides EXCEPT its render surface: THREE.Scene/
- * THREE.Camera typing is replaced with kind-tagged world surfaces. Split out
- * of the old flat
- * `MountedThreeRoot` so a non-threejs world can carry its own kind-appropriate
- * surface field (a pixi `stage`, a react `container`) instead of being
- * force-fit through THREE `scene`/`camera` fields it doesn't have.
+ * Everything a mounted world provides except its render surface. Tagged
+ * mounted-root variants carry their native surface fields: a Three scene and
+ * camera, a Pixi stage, or a DOM container.
  */
 export interface MountedRootBase {
   /**
@@ -103,11 +84,8 @@ export interface MountedRootBase {
   readonly observe?: RootStateObserver;
 }
 
-/** A live, mounted three world. The host obtains `scene`/`camera` to
- *  render+author. Until WO-9 task #9 this type also had a `MountedGame` alias,
- *  which every pre-T7.5 threejs call site named; the alias is deleted, because
- *  what it aliased is one three ROOT and a game is the manifest's whole set of
- *  roots (D20). */
+/** A live, mounted Three world. The host obtains `scene`/`camera` to render
+ * and author it. */
 export interface MountedThreeRoot extends MountedRootBase {
   readonly kind: 'three';
   /** The live scene + camera the editor inspects/renders for authoring. */
@@ -151,8 +129,7 @@ export interface MountedReactRoot extends MountedRootBase {
   readonly container: HTMLElement;
 }
 
-/** Every kind of live, mounted world (T7.5) — the union `RootInstance.mounted`
- *  is typed against now, replacing the THREE-only `MountedThreeRoot`. */
+/** Every kind of live, mounted world. */
 export type MountedRoot = MountedThreeRoot | MountedPixiRoot | MountedReactRoot;
 
 /** Map a {@link AdapterSurface} to its mounted-world shape (mirrors `NodeOf`/
@@ -167,30 +144,22 @@ export type MountedRootFor<K extends AdapterSurface> = K extends 'three'
       : never;
 
 /**
- * The interface every game implements to run on the host. Generic over
- * {@link AdapterSurface} (T7.5) so a non-threejs implementer's `mount` returns
- * its OWN kind-tagged surface instead of being cast through the three shape —
- * defaults to `'three'` so every pre-T7.5 implementer/call site
- * (`RootAdapter`, unparameterized) keeps compiling unchanged.
+ * The interface every root implements to run on the host. Generic over
+ * {@link AdapterSurface} so `mount` receives and returns its native surface
+ * types. Bare `RootAdapter` denotes the first-party Three surface.
  *
- * `K` parameterizes BOTH halves of `mount` (P-8): until then only the RETURN
- * type was kind-tagged, while the PARAMETER was always the three-shaped
- * `ThreeHostContext` — so a `RootAdapter<'canvas'>` was, by its own type, handed a
- * `THREE.WebGLRenderer` it cannot use, and the production Pixi/React adapters
- * could not be `RootAdapter`s at all (they were separate structural types over
- * `CanvasHostContext`/`DomHostContext`, and `RootAdapter<'canvas'>` existed only in
- * tests). With `HostContextFor<K>` the surface tag picks the context type, and
- * those production adapters are now genuine `RootAdapter<K>` subtypes —
+ * `K` parameterizes both halves of `mount`: `HostContextFor<K>` selects the
+ * host context and `MountedRootFor<K>` selects the mounted result. Production
+ * adapters are genuine `RootAdapter<K>` subtypes —
  * `Pixi2DRootAdapter extends RootAdapter<'canvas'>`, `ReactRootAdapter extends
  * RootAdapter<'dom'>` (`runtime/create-runtime.ts`).
  */
 /**
- * On the `= 'three'` default (WO-9 #60 considered removing it, and did not):
- * this default is type-level only: an author who writes bare `RootAdapter` for
+ * The `= 'three'` default is type-level only: an author who writes bare
+ * `RootAdapter` for
  * a pixi root gets a compile error on `mount`'s return type, because
  * `MountedRootFor<'three'>` demands `scene`/`camera` a `MountedPixiRoot` has
- * not got. Wrong-by-default is caught by tsc, so removing this default would
- * be churn across ~125 bare call sites for no defect it could catch.
+ * not got.
  */
 export interface RootAdapter<K extends AdapterSurface = 'three'> {
   /** Stable id (telemetry/registry/conformance). */
@@ -203,17 +172,13 @@ export interface RootAdapter<K extends AdapterSurface = 'three'> {
 /**
  * One surface tag paired with an adapter typed FOR that surface (WO-34).
  *
- * Why this exists: a resolver that turns a manifest root into a mountable
+ * A resolver that turns a manifest root into a mountable
  * adapter handles every surface in one function, so its return type has to
  * span all three. Returning the bare union `RootAdapter<'three'> |
  * RootAdapter<'canvas'> | RootAdapter<'dom'>` does NOT work — a union of
  * function types INTERSECTS its parameters, so `.mount(host)` becomes
  * uncallable with any single host value (no one object is simultaneously a
- * `ThreeHostContext`, a `CanvasHostContext` and a `DomHostContext`). The historical
- * workaround was to declare the whole channel `RootAdapter<'three'>` and
- * re-assert the real kind at each call site with `as unknown as` — kind
- * ERASURE: the surface tag the manifest already knew was thrown away and
- * guessed back.
+ * `ThreeHostContext`, a `CanvasHostContext` and a `DomHostContext`).
  *
  * Carrying the tag ALONGSIDE the adapter fixes that structurally: this is a
  * discriminated union on `surface`, so `switch (resolved.surface)` narrows

package/src/adapter/root-seam-contract.ts

@@ -0,0 +1,56 @@
+/** Exhaustive proof requirements for substrate mount/lifecycle seams. */
+
+import type { AdapterSurface } from './adapter-surface';
+import type {
+  MountedPixiRoot,
+  MountedReactRoot,
+  MountedRootBase,
+  MountedThreeRoot,
+  RootAdapter,
+  RootStateObserver,
+} from './root-adapter';
+import { defineSeamShape } from './seam-evidence';
+
+export const ROOT_ADAPTER_SHAPE = defineSeamShape<RootAdapter<AdapterSurface>>()({
+  id: { optional: false, kind: 'value', required: 'shape' },
+  mount: { optional: false, kind: 'function', required: 'effect' },
+});
+
+export const MOUNTED_ROOT_BASE_SHAPE = defineSeamShape<MountedRootBase>()({
+  drivesOwnLoop: { optional: false, kind: 'value', required: 'shape' },
+  update: { optional: true, kind: 'function', required: 'effect' },
+  fixedUpdate: { optional: true, kind: 'function', required: 'effect' },
+  setPaused: { optional: true, kind: 'function', required: 'effect' },
+  step: { optional: true, kind: 'function', required: 'effect' },
+  resize: { optional: true, kind: 'function', required: 'effect' },
+  dispose: { optional: false, kind: 'function', required: 'effect' },
+  authoring: { optional: true, kind: 'value', required: 'operation' },
+  systems: { optional: true, kind: 'value', required: 'operation' },
+  observe: { optional: true, kind: 'value', required: 'effect' },
+});
+
+export const ROOT_STATE_OBSERVER_SHAPE = defineSeamShape<RootStateObserver>()({
+  subscribe: { optional: false, kind: 'function', required: 'effect' },
+  snapshot: { optional: false, kind: 'function', required: 'operation' },
+});
+
+type ThreeSurface = Omit<MountedThreeRoot, keyof MountedRootBase>;
+type CanvasSurface = Omit<MountedPixiRoot, keyof MountedRootBase>;
+type DomSurface = Omit<MountedReactRoot, keyof MountedRootBase>;
+
+export const MOUNTED_THREE_SURFACE_SHAPE = defineSeamShape<ThreeSurface>()({
+  kind: { optional: false, kind: 'value', required: 'shape' },
+  scene: { optional: false, kind: 'value', required: 'effect' },
+  camera: { optional: false, kind: 'value', required: 'effect' },
+  rendererConfig: { optional: true, kind: 'value', required: 'shape' },
+});
+
+export const MOUNTED_CANVAS_SURFACE_SHAPE = defineSeamShape<CanvasSurface>()({
+  kind: { optional: false, kind: 'value', required: 'shape' },
+  stage: { optional: false, kind: 'value', required: 'effect' },
+});
+
+export const MOUNTED_DOM_SURFACE_SHAPE = defineSeamShape<DomSurface>()({
+  kind: { optional: false, kind: 'value', required: 'shape' },
+  container: { optional: false, kind: 'value', required: 'effect' },
+});