@vgai/engine 0.2.0

package/src/runtime/input-router.ts

@@ -0,0 +1,213 @@
+/**
+ * The delegating input router (COMPOSITION-DESIGN.md D5 §2a) —
+ * `createGameRuntime`'s worlds path (T6.1 slice 1,
+ * docs/MULTI-WORLD-DESIGN.md §1.C) uses this to route pointer input across
+ * N stacked world canvases with exactly ONE root listener.
+ *
+ * Split into two layers so the decision logic is unit-testable with plain
+ * fake worlds — no real DOM/canvas needed:
+ *
+ *  - `stackOrder` / `resolveClaimingWorld`: pure functions over
+ *    `{id, zOrder, hitTest?}` — "who claims this point".
+ *  - `applyPointerEventsStacking` / `createInputRouter`: the DOM wiring —
+ *    sets `pointer-events` CSS per D5 §2a and forwards a claimed event to
+ *    the claiming world's own canvas.
+ *
+ * Per-event fall-through (D5 §2b — the sanctioned mechanism for an
+ * authoring surface's own interior drag affordances, e.g. the world2d
+ * editor's gizmos) is explicitly NOT this file's job (MULTI-WORLD-DESIGN.md
+ * task 4) — it stays inside whatever authoring surface needs it.
+ */
+
+/** The pure decision inputs — no DOM. */
+export interface ClaimEntry {
+  readonly id: string;
+  readonly zOrder: number;
+  /**
+   * Optional claim predicate over a point RELATIVE TO THE CONTAINER. Absent
+   * means: "this world claims only if it is the bottom (lowest zOrder)
+   * world" — D5 §2a's stated default ("transparent upper worlds do not
+   * claim, the bottom world claims everything").
+   */
+  readonly hitTest?: ((x: number, y: number) => boolean) | undefined;
+}
+
+/** The DOM-wiring inputs — one real canvas per world. */
+export interface RouterWorldEntry extends ClaimEntry {
+  readonly canvas: HTMLCanvasElement;
+}
+
+/**
+ * Bottom-to-top paint order: ascending `zOrder`, ties -> original array
+ * order — the SAME rule `manifest/load.ts`'s `loadGameManifest` sorts
+ * worlds by, so a world's DOM stacking position always matches its
+ * manifest-resolved zOrder. The last element is the topmost (visually on
+ * top / highest z-index).
+ */
+export function stackOrder<T extends ClaimEntry>(entries: readonly T[]): T[] {
+  return entries
+    .map((entry, index) => ({ entry, index }))
+    .sort((a, b) => a.entry.zOrder - b.entry.zOrder || a.index - b.index)
+    .map(({ entry }) => entry);
+}
+
+/**
+ * Resolve which world's id claims a container-relative point `(x, y)` — D5
+ * §2a: walk top-down (topmost first); the first world whose `hitTest`
+ * returns true wins ("topmost-claim wins"). A world with no `hitTest` never
+ * claims UNLESS it is the bottom-most world, which claims unconditionally
+ * (or via its own `hitTest`, if it declares one) — "no-claim falls to
+ * bottom". Returns `null` only when `entries` is empty.
+ */
+export function resolveClaimingWorld(
+  entries: readonly ClaimEntry[],
+  x: number,
+  y: number,
+): string | null {
+  if (entries.length === 0) return null;
+  const order = stackOrder(entries); // bottom -> top
+  for (let i = order.length - 1; i >= 1; i--) {
+    const entry = order[i]!;
+    if (entry.hitTest?.(x, y)) return entry.id;
+  }
+  // No upper world claimed (or there is only one world) -> the bottom world
+  // claims — honoring its own hitTest if it declares one (rare: the bottom
+  // world usually claims everything unconditionally per D5 §2a's default).
+  return order[0]!.id;
+}
+
+/**
+ * Sets `canvas.style.pointerEvents` per D5 §1/§2a: the bottom (lowest
+ * zOrder) world's canvas is `'auto'` (real user input DOM-hit-tests it by
+ * default); every canvas above it is `'none'` (real user input never
+ * DOM-hit-tests it — the router's JS-level `hitTest` is what still lets it
+ * claim a point via `createInputRouter`'s forwarding).
+ */
+export function applyPointerEventsStacking(entries: readonly RouterWorldEntry[]): void {
+  const order = stackOrder(entries);
+  order.forEach((entry, i) => {
+    entry.canvas.style.pointerEvents = i === 0 ? 'auto' : 'none';
+  });
+}
+
+const ROUTED_EVENT_TYPES = ['pointerdown', 'pointerup', 'pointermove', 'click', 'wheel'] as const;
+
+/** Common pointer/mouse/wheel event fields this router knows how to carry
+ *  over when forwarding a claimed event to a different canvas (see
+ *  `forwardEvent` below) — not an exhaustive Event surface, just the fields
+ *  games/libraries actually read for hit-testing and input state. */
+function pickEventInit(original: Event): Record<string, unknown> {
+  const src = original as unknown as Record<string, unknown>;
+  const keys = [
+    'clientX',
+    'clientY',
+    'screenX',
+    'screenY',
+    'offsetX',
+    'offsetY',
+    'button',
+    'buttons',
+    'ctrlKey',
+    'altKey',
+    'shiftKey',
+    'metaKey',
+    'pointerId',
+    'pointerType',
+    'pressure',
+    'isPrimary',
+    'deltaX',
+    'deltaY',
+    'deltaZ',
+    'deltaMode',
+  ];
+  const init: Record<string, unknown> = { bubbles: false, cancelable: true, composed: true };
+  for (const key of keys) if (key in src) init[key] = src[key];
+  return init;
+}
+
+/**
+ * Forward `original` onto `canvas` as a NEW, non-bubbling event of the same
+ * event-type family — so a canvas with `pointer-events:none` (never a
+ * native DOM hit-test target) still receives the interaction its own event
+ * pipeline (Pixi's `EventSystem`, a raycast-driven three controller, …)
+ * listens for on ITS canvas. `bubbles:false` is deliberate: it stops the
+ * clone from re-triggering the container's own capture listener (an
+ * infinite loop) — re-dispatching the SAME event object is not an option
+ * either (the DOM forbids re-dispatching an event still being dispatched).
+ *
+ * Best-effort: environments with no `PointerEvent`/`MouseEvent`/
+ * `WheelEvent` global (Node unit tests) skip forwarding silently — those
+ * tests exercise the pure claim-resolution logic above instead, which needs
+ * no real `Event` objects at all.
+ */
+function forwardEvent(canvas: HTMLCanvasElement, original: Event): void {
+  const g = globalThis as unknown as {
+    PointerEvent?: new (type: string, init?: unknown) => Event;
+    MouseEvent?: new (type: string, init?: unknown) => Event;
+    WheelEvent?: new (type: string, init?: unknown) => Event;
+  };
+  const Ctor =
+    original.type === 'wheel'
+      ? g.WheelEvent
+      : original.type.startsWith('pointer')
+        ? g.PointerEvent
+        : (g.MouseEvent ?? g.PointerEvent);
+  if (!Ctor || typeof canvas.dispatchEvent !== 'function') return;
+  try {
+    canvas.dispatchEvent(new Ctor(original.type, pickEventInit(original)));
+  } catch {
+    // Best-effort forwarding — a construction failure here must never break
+    // the (already-delivered) original event's own handling.
+  }
+}
+
+export interface InputRouterHandle {
+  /** Resolve which world claims a container-relative point right now — the
+   *  pure decision, exposed for callers/tests that don't want to simulate a
+   *  real DOM event. */
+  resolveClaim(x: number, y: number): string | null;
+  /** Detach the container listener(s). Idempotent. */
+  dispose(): void;
+}
+
+/**
+ * Wire the delegating router onto `container` for `entries` (D5 §2a): apply
+ * the pointer-events stacking, then attach ONE capture-phase listener per
+ * routed event type that resolves the claiming world and forwards the event
+ * to ITS canvas when that world isn't already the natural DOM target (the
+ * bottom world, whose canvas is the only one with `pointer-events:auto`).
+ */
+export function createInputRouter(
+  container: HTMLElement,
+  entries: readonly RouterWorldEntry[],
+): InputRouterHandle {
+  applyPointerEventsStacking(entries);
+  const byId = new Map(entries.map((e) => [e.id, e] as const));
+  const bottomId = stackOrder(entries)[0]?.id;
+
+  const handler = (evt: Event) => {
+    const rect = container.getBoundingClientRect?.() ?? { left: 0, top: 0 };
+    const clientX = (evt as unknown as { clientX?: number }).clientX ?? 0;
+    const clientY = (evt as unknown as { clientY?: number }).clientY ?? 0;
+    const x = clientX - rect.left;
+    const y = clientY - rect.top;
+    const claimant = resolveClaimingWorld(entries, x, y);
+    if (claimant && claimant !== bottomId) {
+      const entry = byId.get(claimant);
+      if (entry) forwardEvent(entry.canvas, evt);
+    }
+  };
+
+  for (const type of ROUTED_EVENT_TYPES) {
+    container.addEventListener?.(type, handler, true);
+  }
+
+  return {
+    resolveClaim: (x, y) => resolveClaimingWorld(entries, x, y),
+    dispose() {
+      for (const type of ROUTED_EVENT_TYPES) {
+        container.removeEventListener?.(type, handler, true);
+      }
+    },
+  };
+}

package/src/runtime/mount-game.ts

@@ -0,0 +1,269 @@
+// E4 — the S-D composer (docs/unified-world-editor/27-visual-react-editing.md
+// §7 E4; design lineage docs/unified-world-editor/26-unified-editor-spec.md
+// §5 Stage S-D). Builds ON `mount-manifest.ts`'s `mountManifestWorlds` (never
+// duplicates its per-kind dispatch/validation) to add the one thing that
+// module deliberately does NOT have: a KIND REGISTRY, so a project doesn't
+// have to hand-build an `entries` map inline in its own `main.ts` every time
+// — it registers a `WorldKindFactory` per kind it uses (once, at module load)
+// and then mounts with a single `mountGameFromManifest(manifest, host)` call.
+//
+// Engine-core react/pixi-free discipline (mirrors `mount-manifest.ts`'s own
+// header comment, and the HARD INVARIANT this file was built under): this
+// registry is pure mechanism — it holds whatever `WorldKindFactory` functions
+// callers register, but it registers NONE itself. In particular there is no
+// built-in 'pixijs'/'react' registration here (that would require this file
+// to value-import `pixi.js`/`react`/`react-dom`, exactly what `mount-manifest
+// .ts` forbids); a project that has a pixijs or react world MUST register a
+// factory for that kind itself — see `defaultThreeKindFactory` below for why
+// even the 'threejs' convenience export is a plain function the CALLER
+// registers, not something this module wires up automatically.
+
+import type { GameAdapter } from '../adapter/game-adapter';
+import type { ResolvedWorldEntry } from '../manifest/load';
+import type { ComponentRegistry } from '../scene/component-registry';
+import type { GameSession } from './create-runtime';
+import { type MountEntry, mountManifestWorlds, resolveManifest } from './mount-manifest';
+import type { GameSetupFn } from './types';
+
+// ---------------------------------------------------------------------------
+// The host contract (design/26 §5 D1's `ManifestHost`)
+// ---------------------------------------------------------------------------
+
+/**
+ * What a caller of `mountGameFromManifest` provides. Deliberately minimal —
+ * this file never fetches/reads the manifest itself (same rule
+ * `mount-manifest.ts` follows: the caller already has a parsed manifest or a
+ * raw JSON value in hand).
+ */
+export interface ManifestHost {
+  /** The host creates one absolutely-positioned surface per world inside
+   *  this element — see `WorldsRuntimeConfig.container`. */
+  readonly container: HTMLElement;
+  /**
+   * Resolve a manifest-declared `entry` (a project-relative module path,
+   * e.g. `"src/scripts/main.ts"`) to the ALREADY-IMPORTED module namespace a
+   * registered {@link WorldKindFactory} needs to build a `MountEntry` from.
+   *
+   * Deliberately NOT "import this arbitrary string path" — a static bundler
+   * (Vite/rollup building a `dist/`) cannot resolve a runtime-computed import
+   * specifier, so the recommended shape is a small caller-owned lookup table
+   * of STATIC imports keyed by the manifest's own `entry` strings (see
+   * `packages/editor/template/src/main.ts` for the worked pattern) rather
+   * than a literal `import(path)`. Optional — a manifest whose every world
+   * either declares no `entry` or is fully satisfied by an explicit
+   * `opts.entries` needs none at all.
+   */
+  loadEntryModule?(path: string): Promise<unknown>;
+  /** Resolve asset/scene URLs relative to the project — forwarded to a
+   *  registered {@link WorldKindFactory} via {@link WorldKindFactoryContext},
+   *  never called by this module itself (a factory only needs it for a
+   *  non-default resolution scheme, e.g. a hosted-editor iframe). */
+  resolveUrl?(path: string): string;
+  readonly width?: number | undefined;
+  readonly height?: number | undefined;
+  /** Forwarded to `createGameRuntime` — Node/headless test harnesses only,
+   *  never a real host. See `WorldsRuntimeConfig.headless`. */
+  readonly headless?: boolean | undefined;
+}
+
+/** What a registered {@link WorldKindFactory} is handed for one world. */
+export interface WorldKindFactoryContext {
+  readonly host: ManifestHost;
+  /**
+   * The result of `host.loadEntryModule(world.entry)`, if the world declares
+   * an `entry` AND the host supports loading it — `undefined` for a
+   * scene-only world, or when the host has no `loadEntryModule`.
+   */
+  readonly entryModule?: unknown;
+}
+
+/**
+ * A caller-registered per-kind mount strategy: given the world's resolved
+ * manifest entry and the loaded entry module (if any), produce the
+ * `MountEntry` `mountManifestWorlds` needs to mount it (exactly what a
+ * project used to hand-build inline as its own `entries[id]` — see
+ * `examples/tri-world/src/main.ts`'s pre-E4 shape). May be async (loading an
+ * asset, fetching a scene file, etc.).
+ */
+export type WorldKindFactory = (
+  world: ResolvedWorldEntry,
+  ctx: WorldKindFactoryContext,
+) => MountEntry | Promise<MountEntry>;
+
+// ---------------------------------------------------------------------------
+// The registry
+// ---------------------------------------------------------------------------
+
+const registry = new Map<string, WorldKindFactory>();
+
+/**
+ * Register a `WorldKindFactory` for a manifest world `kind` (`'threejs'` /
+ * `'pixijs'` / `'react'`, or any future kind the manifest schema grows).
+ * Call once, at module load — mirrors `registerSceneUIRenderer()`'s existing
+ * "call before mounting" convention (`packages/editor/template/src/main.ts`).
+ *
+ * Throws on double-registration of the SAME kind: an accidental duplicate
+ * (two side-effect imports of the same registration module, or a copy-paste)
+ * is far more likely than an intentional runtime swap — a caller that really
+ * wants to replace a registration must `unregisterWorldKind` first, making
+ * the intent explicit.
+ */
+export function registerWorldKind(kind: string, factory: WorldKindFactory): void {
+  if (registry.has(kind)) {
+    throw new Error(
+      `registerWorldKind: a factory is already registered for kind "${kind}" — ` +
+        'call unregisterWorldKind(kind) first if you intend to replace it (an accidental ' +
+        'double-registration, e.g. two side-effect imports of the same registration module, ' +
+        'is far more common than an intentional swap).',
+    );
+  }
+  registry.set(kind, factory);
+}
+
+/** Remove a kind's registration (e.g. before re-registering a replacement). */
+export function unregisterWorldKind(kind: string): void {
+  registry.delete(kind);
+}
+
+/** Whether a factory is currently registered for `kind`. */
+export function isWorldKindRegistered(kind: string): boolean {
+  return registry.has(kind);
+}
+
+/**
+ * Test-only escape hatch: clears every registration. Registrations are
+ * meant to be one-time, process-lifetime — production code should never
+ * call this; it exists so unit tests can start each case from a clean
+ * registry without cross-test leakage.
+ */
+export function __clearWorldKindRegistryForTests(): void {
+  registry.clear();
+}
+
+// ---------------------------------------------------------------------------
+// `defaultThreeKindFactory` — an OPT-IN convenience, never auto-registered
+// ---------------------------------------------------------------------------
+
+/** The entry-module export shape every first-party entry module follows
+ *  (`packages/editor/template/src/scripts/main.ts`, every `examples/*`
+ *  project's `src/index.ts` — see CLAUDE.md's "Adding an example project"). */
+interface ThreeEntryModuleExports {
+  readonly adapter?: GameAdapter;
+  readonly setup?: GameSetupFn;
+  readonly componentRegistry?: ComponentRegistry;
+}
+
+/**
+ * A ready-to-register {@link WorldKindFactory} for `kind: 'threejs'` worlds
+ * that follow the first-party entry-module convention (`export const
+ * adapter` and/or `export async function setup`) or are plain scene files
+ * with an optional named `componentRegistry` export. Threejs is safe to
+ * ship as an exported convenience (unlike pixijs/react) because `three`/
+ * `VgaiSceneGameAdapter` are already unconditional engine dependencies —
+ * see `mount-manifest.ts`'s header comment. Still never auto-registered:
+ * the registry itself stays zero-policy (see this file's header comment) —
+ * a caller opts in with `registerWorldKind('threejs', defaultThreeKindFactory)`.
+ *
+ * Resolution mirrors `mount-manifest.ts`'s own `resolveThreeAdapter` branch
+ * order: an entry module's `adapter` export wins outright; else its `setup`
+ * export (wrapping via `fromSetup` happens inside `mountManifestWorlds`
+ * itself — this factory just returns the `MountEntry` shape); else (no
+ * `entry` at all) a scene-driven world, forwarding `componentRegistry` if
+ * the entry module supplied one.
+ */
+export const defaultThreeKindFactory: WorldKindFactory = (world, ctx) => {
+  const mod = ctx.entryModule as ThreeEntryModuleExports | undefined;
+  if (mod?.adapter) return { kind: 'threejs', adapter: mod.adapter };
+  if (mod?.setup) return { kind: 'threejs', setup: mod.setup };
+  if (world.entry !== undefined) {
+    throw new Error(
+      `defaultThreeKindFactory: entry module "${world.entry}" for world "${world.id}" exports ` +
+        'neither `adapter` nor `setup` — every first-party entry module exports at least one ' +
+        '(see packages/editor/template/src/scripts/main.ts).',
+    );
+  }
+  return { kind: 'threejs', componentRegistry: mod?.componentRegistry };
+};
+
+// ---------------------------------------------------------------------------
+// The composer
+// ---------------------------------------------------------------------------
+
+export interface MountGameOptions {
+  /** Explicit per-world entries, same shape `mountManifestWorlds` accepts —
+   *  ALWAYS wins over a registered kind factory for that world id (backward
+   *  compat: a caller mid-migration, or one that just prefers building one
+   *  entry by hand, never has to touch the registry at all). */
+  readonly entries?: Readonly<Record<string, MountEntry>> | undefined;
+}
+
+/** True for the one shape `mountManifestWorlds` can ALREADY mount with zero
+ *  `entries[id]` at all (a plain `default`-adapter, scene-driven, no-`entry`
+ *  threejs world — `resolveThreeAdapter`'s own scene branch, which needs
+ *  nothing beyond the manifest itself). Every other shape (pixijs, react, an
+ *  entry-declaring or module/ingest-adapter threejs world) needs SOMETHING
+ *  in `entries[id]` to succeed. */
+function worldIsSelfSufficient(world: ResolvedWorldEntry): boolean {
+  return world.kind === 'threejs' && world.adapter.type === 'default' && world.entry === undefined;
+}
+
+/**
+ * Mount every world declared by a `vgai.game.json` manifest onto `host
+ * .container`, resolving each world's kind through the `registerWorldKind`
+ * registry — falling back to an explicit `opts.entries[id]` where supplied,
+ * exactly like `mountManifestWorlds` (so a caller can migrate one world at a
+ * time, or never touch the registry if it prefers hand-building entries).
+ *
+ * This is the "one call" scaffold/example projects mount through (E4
+ * acceptance): register whatever kinds you need once, then
+ * `await mountGameFromManifest(manifest, host)` — see
+ * `packages/editor/template/src/main.ts` for the worked single-world
+ * example and `examples/tri-world/src/main.ts` for a multi-kind one.
+ *
+ * Degrades loudly (`docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md` D-Z2, carried
+ * into E4): a world whose kind has no registered factory AND no explicit
+ * entry, and which cannot self-mount from the manifest alone, throws a named
+ * `Error` identifying the world id + kind and BOTH ways to fix it
+ * (`registerWorldKind` or `opts.entries`) — never a silent skip.
+ */
+export async function mountGameFromManifest(
+  manifestInput: unknown,
+  host: ManifestHost,
+  opts: MountGameOptions = {},
+): Promise<GameSession> {
+  const manifest = resolveManifest(manifestInput);
+  const entries: Record<string, MountEntry> = { ...opts.entries };
+
+  for (const world of manifest.worlds) {
+    if (entries[world.id] !== undefined) continue; // explicit entry always wins
+
+    const factory = registry.get(world.kind);
+    if (factory) {
+      const entryModule =
+        world.entry !== undefined && host.loadEntryModule
+          ? await host.loadEntryModule(world.entry)
+          : undefined;
+      entries[world.id] = await factory(world, { host, entryModule });
+      continue;
+    }
+
+    if (worldIsSelfSufficient(world)) continue; // mountManifestWorlds needs nothing further
+
+    throw new Error(
+      `mountGameFromManifest: world "${world.id}" (kind "${world.kind}") has no registered ` +
+        `world-kind factory and no explicit entries["${world.id}"] — call ` +
+        `registerWorldKind("${world.kind}", factory) before mounting (see ` +
+        '`defaultThreeKindFactory` for a worked threejs example), or pass ' +
+        `opts.entries["${world.id}"] directly (see mount-manifest.ts's \`MountEntry\`).`,
+    );
+  }
+
+  return mountManifestWorlds({
+    manifest,
+    container: host.container,
+    entries,
+    width: host.width,
+    height: host.height,
+    headless: host.headless,
+  });
+}