@vgai/engine 0.5.22 → 0.5.24

package/src/audio/bus-mixer.ts

@@ -0,0 +1,161 @@
+/**
+ * A named-bus mixer over Web Audio: buses created on demand, routed into each
+ * other by name, and set in DECIBELS.
+ *
+ * Every mixer a game reaches for is this shape — Unity's `AudioMixerGroup`,
+ * Godot's bus layout, FMOD's VCAs, and the `music`/`sfx`/`voice` trio
+ * `setup/setup-audio.ts` hands a first-party three world. What they share is
+ * not the protocol (that part is genuinely per-ecosystem and stays with the
+ * lane that speaks it) but the machinery underneath: a `GainNode` per bus, a
+ * name → node map, a parent to route into, and the one conversion below. This
+ * file owns exactly that, and nothing that names an ecosystem.
+ *
+ * ## dB is not a gain, and the mistake is silent
+ *
+ * `GainNode.gain` is a LINEAR amplitude multiplier; every mixer's authored
+ * volume is logarithmic dB, where 0 dB is unity and −80 dB is silence. Writing
+ * the dB number straight onto `gain.value` gives you a gain of −80 (a phase
+ * inversion at 80x) where the author asked for silence, and it does not throw,
+ * warn, or look wrong in a debugger — it is just loud. {@link dbToLinear} is
+ * the one conversion, `10^(dB/20)`, which is both Godot's `db_to_linear`
+ * (`core/math/math_funcs.h`: `exp(db * 0.11512925464970228…)`, the same
+ * function written in base e) and Unity's mixer volume curve.
+ *
+ * It deliberately does NOT clamp. A mixer's RANGE is protocol — Unity's
+ * exposed parameters saturate at its slider's ends, Godot's `volume_db` does
+ * not — so the lane that knows the range applies it before calling here, and
+ * this file cannot silently mute or silently boost anyone's authored value.
+ *
+ * ## Create-on-demand, and why it is the contract rather than a convenience
+ *
+ * {@link AudioBusMixer.bus} MINTS a bus the first time it is named and returns
+ * the SAME node forever after. The identity is the contract, not the minting:
+ * a source connects to a bus long before anything sets that bus's volume, and
+ * a parent is usually named by its child before anyone asks for it directly
+ * (`bus('music', 'master')` builds `master` too, and the later `bus('master')`
+ * must be that same node). A `bus()` that minted per call would hand the
+ * volume control a SECOND node — the sources would keep feeding the first one,
+ * every later write would land on a node nothing plays through, and nothing
+ * would throw or look wrong. So the map is authoritative, and the only way a
+ * name stops resolving to its node is {@link AudioBusMixer.remove} or
+ * {@link AudioBusMixer.disconnect}.
+ *
+ * A re-ask that names a DIFFERENT parent throws by name. Routing is decided at
+ * creation (the node is already connected by then), so honouring the second
+ * parent would mean silently re-routing live audio and ignoring it would mean
+ * silently keeping the first — a loud error is the only reading that is not a
+ * lie.
+ *
+ * ## RESOURCE OWNERSHIP
+ *
+ * No module-scoped state: {@link createAudioBusMixer} is a factory and the
+ * OWNER of an instance is whoever called it (a `setupAudio` graph, one
+ * translated port's mixer store). What an instance ALLOCATES is one `GainNode`
+ * per named bus, and disconnecting those is the whole of its teardown
+ * obligation — {@link AudioBusMixer.disconnect}, called once by that same
+ * owner. The `context` and the `destination` node are NOT its own: they are
+ * passed in, shared with everything else hanging off the same graph, and this
+ * file never creates, closes, suspends or disconnects either one.
+ */
+
+/**
+ * The graph an {@link AudioBusMixer} hangs off, as the two members it touches.
+ *
+ * Narrow on purpose: `createGain` is all it needs from the context, so a real
+ * `AudioContext`, an `OfflineAudioContext` and a headless stand-in are all
+ * acceptable without a cast.
+ */
+export interface AudioBusMixerOptions {
+  readonly context: { createGain(): GainNode };
+  /** The node every parentless bus feeds. Usually a master gain or the context's destination. */
+  readonly destination: AudioNode;
+}
+
+export interface AudioBusMixer {
+  /**
+   * The bus named `name`, created on the first ask and connected to `parent`
+   * (itself created on demand) or to the destination.
+   *
+   * The returned node is the real `GainNode` — set `gain.value`, schedule
+   * automation on `gain`, connect sources to it. Nothing here stands between a
+   * caller and Web Audio's own API.
+   */
+  bus(name: string, parent?: string): GainNode;
+  /** The bus named `name` if it EXISTS, else null. Never mints one. */
+  find(name: string): GainNode | null;
+  /** Set this bus's gain from decibels, creating it if absent. Clamp before calling — see the header. */
+  setDb(name: string, db: number, parent?: string): void;
+  /**
+   * Disconnect one bus and forget its name, so a later {@link bus} mints a
+   * fresh node. Buses that named it as their parent are NOT re-routed — they
+   * keep feeding the removed node, which now reaches nothing.
+   */
+  remove(name: string): void;
+  /** Disconnect every bus and forget them all. The owner's ONE teardown. */
+  disconnect(): void;
+}
+
+/** dB → linear amplitude: `10^(dB/20)`. 0 dB is 1, −6 dB is ~0.5, −80 dB is ~0.0001. Never clamps. */
+export function dbToLinear(db: number): number {
+  return 10 ** (db / 20);
+}
+
+interface BusRecord {
+  readonly node: GainNode;
+  readonly parent: string | undefined;
+}
+
+function safeDisconnect(node: GainNode): void {
+  try {
+    node.disconnect();
+  } catch {
+    // already disconnected
+  }
+}
+
+/** Create one named-bus mixer. See the header for what owns the instance and what it allocates. */
+export function createAudioBusMixer(options: AudioBusMixerOptions): AudioBusMixer {
+  const { context, destination } = options;
+  const buses = new Map<string, BusRecord>();
+
+  function bus(name: string, parent?: string): GainNode {
+    const existing = buses.get(name);
+    if (existing !== undefined) {
+      if (parent !== undefined && parent !== existing.parent) {
+        throw new Error(
+          `audio bus ${JSON.stringify(name)} already routes into ` +
+            `${existing.parent === undefined ? 'the destination' : JSON.stringify(existing.parent)}` +
+            `; it cannot also route into ${JSON.stringify(parent)}. Routing is decided when a bus ` +
+            'is created (see packages/engine/src/audio/bus-mixer.ts).',
+        );
+      }
+      return existing.node;
+    }
+    // The parent is resolved (and minted, recursively) before this bus is
+    // seated, so a conflicting-parent throw upstream leaves nothing half-built.
+    const into = parent === undefined ? destination : bus(parent);
+    const node = context.createGain();
+    node.gain.value = 1;
+    node.connect(into);
+    buses.set(name, { node, parent });
+    return node;
+  }
+
+  return {
+    bus,
+    find: (name) => buses.get(name)?.node ?? null,
+    setDb: (name, db, parent) => {
+      bus(name, parent).gain.value = dbToLinear(db);
+    },
+    remove: (name) => {
+      const record = buses.get(name);
+      if (record === undefined) return;
+      buses.delete(name);
+      safeDisconnect(record.node);
+    },
+    disconnect: () => {
+      for (const record of buses.values()) safeDisconnect(record.node);
+      buses.clear();
+    },
+  };
+}

package/src/core/frame-pacing.ts

@@ -1,6 +1,6 @@
 /**
  * Frame pacing — the accumulator/alpha arithmetic of the fixed-timestep loop,
- * extracted PURE (WO-P13, `docs/WORK.md` §2 P13).
+ * extracted PURE.
  *
  * `core/game-loop.ts` owns the browser side (rAF, `visibilitychange`,
  * `performance.now`); this module owns the arithmetic, so the interesting
@@ -108,7 +108,7 @@ export function paceFrame(
   const maxAccumulator = fixedDt * maxSubSteps;
 
   // Clamp large frame gaps (a slow frame, a debugger pause) BEFORE scaling by
-  // timeScale — unchanged from the pre-WO-P13 loop.
+  // timeScale.
   const displayDt = Math.min(rawDt, maxAccumulator) * timeScale;
   let next = accumulator + displayDt;
   // Spiral-of-death guard: bound the accumulator regardless of timeScale or

package/src/core/game-loop.ts

@@ -9,9 +9,7 @@ const LOOP_STARVATION_MS = 1_000;
 
 /**
  * Fixed-timestep game loop with accumulator pattern — SIM at a fixed rate,
- * PRESENTATION at the display's rate (WO-P13, `docs/WORK.md` §2 P13, which
- * flipped the former D1 "render is fixed-rate too" decision this comment used
- * to state).
+ * PRESENTATION at the display's rate.
  *
  * Per real (rAF) frame:
  *

package/src/core/seeded-random.ts

@@ -42,7 +42,7 @@ export const GAMEPLAY_STREAM = 'gameplay';
 export const DEFAULT_SEEDED_RANDOM_SEED = 0x9e3779b9;
 
 /**
- * The `ctx.random` surface (`GameContext.random`, `runtime/types.ts`).
+ * A game-scoped random surface.
  * Callable (draws from the `'gameplay'` stream), plus:
  * - `stream(name)` — an independent named generator, `[0, 1)` floats, same
  *   call signature as `Math.random`/the bare `SeededRandom` call itself.

package/src/core/sim-clock.ts

@@ -93,10 +93,9 @@
  * controller cancels everything a `setup()` scheduled:
  *
  * ```ts
- * export async function setup(ctx: GameContext): Promise<GameCleanup> {
- *   const ac = new AbortController();
- *   ctx.clock.after(3, () => spawnWave(), { signal: ac.signal });
- *   return { dispose: () => ac.abort() }; // cancels timers AND listeners
+ * const ac = new AbortController();
+ * clock.after(3, () => spawnWave(), { signal: ac.signal });
+ * // on dispose: ac.abort() — cancels timers AND listeners
  * }
  * ```
  *
@@ -170,7 +169,7 @@ export interface SimClock {
 /**
  * The runtime-facing half — NOT for game code. Split off the public
  * {@link SimClock} the same way `runtime/game.ts` splits `GameInternal` off
- * `Game`: `GameContext.clock` is typed as `SimClock`, so game code cannot
+ * `Game`: game code only ever sees the public `SimClock`, so it cannot
  * reach `flush`/`dispose`.
  */
 export interface SimClockInternal extends SimClock {
@@ -394,7 +393,7 @@ export function registerSimClock(owner: object, clock: SimClockInternal): void {
  *  Returns the INTERNAL view because this registry is engine-only — but a
  *  caller that RESOLVES a clock here is not its owner and must not call
  *  `dispose()` on it (module header, ownership). Game code never reaches it at
- *  all: `GameContext.clock` is typed as the public {@link SimClock}, which has
+ *  all: it only ever sees the public {@link SimClock}, which has
  *  neither `flush` nor `dispose`, the same way `Game` hides `GameInternal`. */
 export function getSimClock(owner: object): SimClockInternal | null {
   return clockByOwner.get(owner) ?? null;

package/src/core/types.ts

@@ -72,9 +72,7 @@ export interface GameLoopConfig {
    */
   update: (dt: number) => void;
   /**
-   * Called EXACTLY ONCE per real (rAF) frame — the PRESENTATION half
-   * (WO-P13, `docs/WORK.md` §2 P13; this is the callback whose absence the
-   * former D1 decision recorded).
+   * Called EXACTLY ONCE per real (rAF) frame — the PRESENTATION half.
    *
    * - `alpha` — `accumulator / fixedDt` after this frame's substeps were
    *   consumed, in `[0, 1]`: how far presentation sits past the last

package/src/defaults.ts

@@ -1,20 +1,12 @@
 /**
  * Single source of truth for default values the engine's factories read.
  *
- * WO-8 deleted SEVEN groups — `transform`, `entity`, `audio`, `shadow`,
- * `animation`, `fog`, `environment` — because every one of their readers was a
- * `.vscn.json` consumer (`entity-factory.ts`, `scene-loader.ts`,
- * `scene-sync.ts`, `scene-serializer.ts`, the per-section inspectors) and
- * `defaults-source-scan.test.ts` reported them with ZERO `DEFAULTS.<group>`
- * readers anywhere in engine/editor src or tests. That guard offers two remedies
- * — wire the group to the factory that reads it, or delete it if truly unused —
- * and there is no surviving factory to wire these to: `transform` restated
- * THREE's own Object3D constructor values, `entity.locked`/ `pivot` were
- * descriptor-only fields, and `fog`/`environment.envMapIntensity`/ `shadow` were
- * the `.vscn` `environment` block that `render-env.ts` explicitly did NOT carry
- * forward. Keeping them would have been exactly the dead documentation T1.13
- * created this guard to prevent.
- *
+ * A group belongs here only while a FACTORY reads it. A default with no
+ * reader is dead documentation: it looks authoritative, nothing consults it,
+ * and it drifts from the value the code actually uses. Restating a library's
+ * own constructor values (THREE's `Object3D` transform, say) is the same
+ * mistake in a different shape — the library is already the source of truth.
+ * So when a factory goes, its group goes with it.
  */
 export const DEFAULTS = {
   material: {

package/src/dev/register-render-vitals.ts

@@ -8,10 +8,7 @@
  *
  * Engine-owned and first-party, seeded by BOTH three-root mount paths — a game
  * writes nothing to get these, and there is no capability to install:
- *  - `adapter/setup-three-root-adapter.ts` (the classic imperative
- *    `setup(ctx)` world), at the same spot it seeds
- *    `systemAdapters.renderDebug`;
- *  - `world3d-react/r3f-adapter.tsx` (a TSX/R3F world — the shape EVERY
+ *  - `world3d-react/r3f-root-factory.tsx` (a TSX/R3F world — the shape EVERY
  *    scaffolded project's three root has), right after fiber's first commit
  *    resolves the scene.
  * Both is the whole point and not redundancy: they are two independent mounts

package/src/dev/render-debug-adapter.ts

@@ -3,11 +3,10 @@
  * the WebGL2 frame capture (`webgl-frame-capture.ts`), a live three.js scene,
  * and the render adapter's per-frame render pass.
  *
- * Split OUT of `setup-three-root-adapter.ts` so the capture/attribution/restore
+ * Split OUT of `world3d-react/r3f-root-factory.tsx` so the capture/attribution/restore
  * flow is unit-testable in a headless Node test with a mock GL context and a
  * plain scene — a real non-headless GPU mount (EffectComposer + WebGLRenderer)
- * cannot run under vitest here, the same reason the adapter suite drives
- * `setup(ctx)` only through hotReload on a data scene. `mount()` owns the
+ * cannot run under vitest here. `mount()` owns the
  * DECISION to construct this (only under a real WebGL2 context, never
  * headless — see `frameCaptureContextFor`); this module owns the BEHAVIOR.
  *

package/src/dev/render-vitals.ts

@@ -43,8 +43,8 @@
  * OWNER: the caller of {@link createRenderVitals}, which allocates one state
  * object and one `profiler.subscribe` registration. SHARER: none — the state
  * is private to that call. TEARDOWN: the returned `dispose()`, the ONE path
- * that ends the subscription (`setup-three-root-adapter.ts` calls it from
- * `disposeGame`).
+ * that ends the subscription (`world3d-react/r3f-root-factory.tsx` calls it
+ * from the mounted root's own `dispose()`).
  */
 
 import type { PerformanceFrame, PerformanceProfiler } from './performance-profiler';
@@ -52,7 +52,7 @@ import type { PerformanceFrame, PerformanceProfiler } from './performance-profil
 /**
  * The profiler phase name the three adapter brackets its CPU render
  * submission with — spelled HERE and nowhere else, so the producer
- * (`setup-three-root-adapter.ts`) and the consumer ({@link foldProfilerFrame})
+ * (`world3d-react/r3f-root-factory.tsx`) and the consumer ({@link foldProfilerFrame})
  * cannot drift apart. Dotted, so it reads as a decomposition of the enclosing
  * `render` phase rather than a ninth peer of `SystemPhase`.
  */

package/src/dev/webgl-frame-capture.ts

@@ -4,7 +4,7 @@
  * WHY FIRST-PARTY, NOT spectorjs (recorded per the "use libraries directly, no
  * wrappers" rule): the capture seam we need is the WebGL2 context this engine
  * ALREADY owns end-to-end (`renderer.getContext()` in
- * `setup-three-root-adapter.ts`). spectorjs is absent from node_modules, and its
+ * `world3d-react/r3f-root-factory.tsx`). spectorjs is absent from node_modules, and its
  * actual value is a bundled inspector UI we would discard — adopting it imports
  * ~2MB of library to keep ~10% of it, and it wraps the context with its own
  * global patching model rather than the instance-shadow-and-restore discipline

package/src/index.ts

@@ -10,21 +10,19 @@
  * remain the primary way to reach engine internals — reach for a subpath
  * first. This barrel exists only so the package's bare-name entry point is
  * HONEST (resolves to something real and useful) instead of dangling; it
- * covers just the handful of symbols a game/consumer needs to author a
- * first-party `setup()` and mount it, plus the scene/manifest file
+ * covers just the handful of symbols a consumer needs to mount a game
+ * from its manifest, plus the manifest file
  * entry points. Keep it small when extending it — prefer a new subpath
  * export over growing this file into a firehose.
  *
  * 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`
  *   - surface vocabulary: `AdapterSurface`
  *   - manifest-driven mount: `mountManifestRoots` + its option/result types
  *   - game manifest (vgai.project.json) entry point: `loadGameManifest`
  */
 
 export type { AdapterSurface } from './adapter/adapter-surface';
-export { fromSetup } from './adapter/setup-three-root-adapter';
 export { AssetParseError } from './asset-parse-error';
 export type {
   AdapterRoot,
@@ -42,4 +40,3 @@ export type {
   MountManifestOptions,
 } from './runtime/mount-manifest';
 export { mountManifestRoots } from './runtime/mount-manifest';
-export type { GameCleanup, GameContext, GameSetupFn } from './runtime/types';

package/src/input/host-pointer.ts

@@ -0,0 +1,230 @@
+/**
+ * The host POINTER stream, in the game's own coordinate space — the DOM edge
+ * `InputManager`'s touch backends (`setTouchButton` / `setTouchStick`) and any
+ * pointer-position read need, and which the manager itself deliberately does
+ * not own.
+ *
+ * `InputManager` listens on `window` for keyboard, mouse and focus, in CLIENT
+ * pixels, because an action map is surface-agnostic. A pointer is not: a tap is
+ * only meaningful relative to the surface it landed on, and a game's own
+ * coordinate space is usually NOT that surface's CSS pixels — a fixed design
+ * resolution presented by uniformly scaling and letterboxing is the common
+ * case, and a hit-test against a UI rect authored in design pixels has to
+ * happen in one space with the pointer. That mapping needs a surface and a
+ * design size the manager has no way to know, so it lives here, beside it.
+ *
+ * What this owns, and nothing more:
+ *
+ * - **Position** — the last pointer position over the surface, mapped into the
+ *   design space. `setPosition` is the headless door (a harness or a game
+ *   command driving the game with no DOM), the same shape as
+ *   `InputManager.addMouseDelta`: inject through the accumulator the reader
+ *   already reads, never a synthetic `pointermove`.
+ * - **Touches** — a per-frame queue of {@link HostPointerTouch} records with
+ *   DENSE finger indices, drained by the game's own frame. `pointerId` is the
+ *   browser's opaque, monotonically growing handle; a touch API that reports
+ *   "finger 0 and finger 1" wants the lowest free slot, reused the moment a
+ *   finger lifts, which is what {@link HostPointerTouch.index} is.
+ * - **Cursor** — the CSS cursor applied to the surface, because the surface is
+ *   resolved here and nowhere else.
+ *
+ * **Gating.** Every listener returns early unless
+ * `InputManager.isInputActive()` — the SAME predicate the manager's own
+ * `keydown`/`mousemove` listeners pass, so play-mode isolation and window
+ * blur suppress pointer position and touches exactly as they suppress a key.
+ * The predicate is read from the manager rather than recomposed here
+ * (`isEnabled() && isFocused()` written out a second time is how a looser gate
+ * drifts in: a blurred or typing tab kept updating a pointer position under
+ * exactly that duplication). Text-entry focus is deliberately NOT part of it,
+ * matching `onMouseMove` rather than `onKeyDown` — moving a finger is not
+ * typing.
+ *
+ * **Ownership.** Owns its four pointer listeners on the resolved owner, the
+ * touch queue and the finger-index table. Shares the `InputManager`, which is
+ * the game's and is never mutated here — this reports; what a control DOES
+ * with a finger (which rect owns it, whether that becomes a `setTouchButton`)
+ * belongs to the UI that draws the control. Teardown is {@link
+ * HostPointer.dispose}, and only that: `InputManager.dispose` does not reach
+ * these listeners.
+ *
+ * Headless (no `window`): construction succeeds and binds nothing. Position is
+ * whatever {@link HostPointer.setPosition} last wrote, and the touch queue
+ * stays empty.
+ */
+
+import type { InputManager } from './input-manager';
+import type { Vector2 } from './input-types';
+
+/**
+ * Cap on the undrained touch queue. A game that drains every frame cannot
+ * reach it — this is the bound for one that never drains at all (a project
+ * that reads no touches, on a device that has them), so the queue is a RING:
+ * the newest records win and the oldest are dropped.
+ */
+const TOUCH_QUEUE_MAX = 256;
+
+/** One finger edge the host pointer stream produced. */
+export interface HostPointerTouch {
+  /**
+   * `'start'` when the finger went down on the surface, `'move'` while it
+   * drags, `'end'` when it lifted or the browser cancelled it. A cancel is an
+   * end: the finger is gone either way, and a control that treats them
+   * differently is holding a button nothing will ever release.
+   */
+  readonly phase: 'start' | 'move' | 'end';
+  /**
+   * DENSE finger index — the lowest slot free when this finger went down, and
+   * free again the moment it lifts. NOT the browser's `pointerId`, which never
+   * reuses a value and is therefore useless as "which finger is this".
+   */
+  readonly index: number;
+  /** Position in the design space (see {@link HostPointerOptions.designSize}). */
+  readonly position: Vector2;
+}
+
+/** What {@link createHostPointer} needs. */
+export interface HostPointerOptions {
+  /** The game's own manager — read for its gate, never written. */
+  readonly input: InputManager;
+  /**
+   * The render surface pointer positions are relative to.
+   *
+   * A GETTER rather than an element because a renderer usually mints its
+   * canvas after the game's services exist. Absent (or returning `null`) falls
+   * back to the event's own target element, and listening falls back to
+   * `window` — which is what makes a finger that starts on the canvas and
+   * drags over a DOM overlay keep reporting.
+   */
+  readonly surface?: (() => HTMLElement | null) | undefined;
+  /**
+   * The game's own logical resolution, if it has one. Surface CSS pixels are
+   * mapped into it, so a pointer and a UI rect authored at this size share one
+   * space regardless of how the host scaled and letterboxed the surface.
+   *
+   * Absent: positions are reported in the surface's own CSS pixels, and the
+   * position before any event is `{x: 0, y: 0}`. Present: the position before
+   * any event is the CENTRE of the design space — a pointer that has never
+   * moved is better described as the middle of the view than as a corner it
+   * was never at.
+   */
+  readonly designSize?: Vector2 | undefined;
+}
+
+/** The host pointer stream bound to one surface. One per mounted game. */
+export interface HostPointer {
+  /** The last pointer position, in the design space. */
+  getPosition(): Vector2;
+  /** Headless / harness door onto {@link getPosition}'s value. */
+  setPosition(position: Vector2): void;
+  /**
+   * Drain the touch records queued since the last call. Returns them in
+   * arrival order and empties the queue, so a frame that drains sees each
+   * finger edge exactly once.
+   */
+  takeTouches(): readonly HostPointerTouch[];
+  /**
+   * Set the CSS `cursor` applied to the surface. Applied on the next pointer
+   * move over it, which is also when the surface is known.
+   */
+  setCursor(cursor: string): void;
+  /** Remove the listeners this owns. */
+  dispose(): void;
+}
+
+export function createHostPointer(options: HostPointerOptions): HostPointer {
+  const { input, surface: surfaceOf, designSize } = options;
+  let position: Vector2 = designSize
+    ? { x: designSize.x / 2, y: designSize.y / 2 }
+    : { x: 0, y: 0 };
+  let cursor = 'default';
+
+  const touches: HostPointerTouch[] = [];
+  /** Browser `pointerId` -> dense finger index, for fingers currently down. */
+  const fingerOfPointer = new Map<number, number>();
+  const freeFinger = (): number => {
+    const taken = new Set(fingerOfPointer.values());
+    let index = 0;
+    while (taken.has(index)) index += 1;
+    return index;
+  };
+  const queue = (touch: HostPointerTouch): void => {
+    touches.push(touch);
+    if (touches.length > TOUCH_QUEUE_MAX) touches.shift();
+  };
+
+  const queueTouch = (event: PointerEvent, point: Vector2): void => {
+    if (event.type === 'pointerdown') {
+      const index = freeFinger();
+      fingerOfPointer.set(event.pointerId, index);
+      queue({ phase: 'start', index, position: point });
+      return;
+    }
+    // A move or a release from a pointer that never went down on this surface
+    // is not one of our fingers.
+    const index = fingerOfPointer.get(event.pointerId);
+    if (index === undefined) return;
+    if (event.type === 'pointerup' || event.type === 'pointercancel') {
+      fingerOfPointer.delete(event.pointerId);
+      queue({ phase: 'end', index, position: point });
+      return;
+    }
+    queue({ phase: 'move', index, position: point });
+  };
+
+  /** A client-space event as a point in the design space, via the surface rect
+   *  the host actually presented it at. */
+  const toDesignSpace = (event: PointerEvent, rect: DOMRect): Vector2 => {
+    const x = event.clientX - rect.left;
+    const y = event.clientY - rect.top;
+    if (!designSize) return { x, y };
+    return { x: (x * designSize.x) / rect.width, y: (y * designSize.y) / rect.height };
+  };
+
+  const onPointer = (event: PointerEvent): void => {
+    // The manager's own gate, read from the manager. See this module's header
+    // for why it is not recomposed here.
+    if (!input.isInputActive()) return;
+    const surface = surfaceOf?.() ?? (event.target instanceof HTMLElement ? event.target : null);
+    if (surface === null) return;
+    const rect = surface.getBoundingClientRect();
+    if (rect.width <= 0 || rect.height <= 0) return;
+    const point = toDesignSpace(event, rect);
+
+    if (event.type === 'pointermove') {
+      // Every pointer type moves the position — a stylus and a dragging finger
+      // are as much "where the pointer is" as a mouse. Only the TOUCH queue is
+      // touch-only.
+      position = point;
+      surface.style.cursor = cursor;
+    }
+    // A mouse or a pen is not a finger. A control that answered them here would
+    // steal the clicks of a player who cannot see it.
+    if (event.pointerType === 'touch') queueTouch(event, point);
+  };
+
+  const KINDS = ['pointerdown', 'pointermove', 'pointerup', 'pointercancel'] as const;
+  const owner: EventTarget | null =
+    typeof window === 'undefined' ? null : (surfaceOf?.() ?? window);
+  if (owner !== null) {
+    for (const kind of KINDS) owner.addEventListener(kind, onPointer as EventListener);
+  }
+
+  return {
+    getPosition(): Vector2 {
+      return position;
+    },
+    setPosition(next): void {
+      position = { x: next.x, y: next.y };
+    },
+    takeTouches(): readonly HostPointerTouch[] {
+      return touches.splice(0, touches.length);
+    },
+    setCursor(next): void {
+      cursor = next;
+    },
+    dispose(): void {
+      if (owner === null) return;
+      for (const kind of KINDS) owner.removeEventListener(kind, onPointer as EventListener);
+    },
+  };
+}