@vgai/engine 0.3.0 → 0.4.0-canary.20260715.0

package/src/input/input-manager.ts

@@ -38,6 +38,70 @@ function isTextEntryFocused(): boolean {
   );
 }
 
+/**
+ * Thrown by `InputManager.setVirtualAction`/`tapVirtualAction` (Task 1.4,
+ * ACCEPTANCE-DRIVER-BUILD-PLAN.md / SYNTHETIC-PLAYER-SPEC.md §3.2) for an
+ * action name that was never `registerAction`/`loadMap`-ed. Carries a
+ * machine-readable `code` and `data.registered` (every declared action name)
+ * rather than requiring a caller to parse the message.
+ */
+export class InputActionError extends Error {
+  readonly code = 'INPUT_ACTION_NOT_FOUND' as const;
+  readonly data: { registered: string[] };
+
+  constructor(action: string, method: string, registered: string[]) {
+    super(
+      `InputManager.${method}: unknown action "${action}". Registered actions: ` +
+        (registered.length ? registered.join(', ') : '(none)'),
+    );
+    this.name = 'InputActionError';
+    this.data = { registered };
+  }
+}
+
+/**
+ * Thrown by `InputManager.scheduleActionAtTick` (D15/T-D15.5,
+ * docs/D15-DETERMINISM-DESIGN.md §2.c) when the named `tick` has already
+ * elapsed — scheduling only ever applies to the CURRENT or a future tick,
+ * never one already serviced by `poll()`. Carries `data.currentTick` — the
+ * NEXT tick `poll()` will service (not the tick that just elapsed) — so a
+ * caller can retry by scheduling for `data.currentTick` or later.
+ */
+export class InputTickError extends Error {
+  readonly code = 'TICK_ALREADY_PASSED' as const;
+  readonly data: { currentTick: number };
+
+  constructor(tick: number, currentTick: number) {
+    super(
+      `InputManager.scheduleActionAtTick: tick ${tick} has already passed (next tick to be ` +
+        `serviced: ${currentTick}) — scheduling only applies to the current or a future tick`,
+    );
+    this.name = 'InputTickError';
+    this.data = { currentTick };
+  }
+}
+
+/** Shallow equality for a resolved action value (boolean/number/Vector2) —
+ *  D15/T-D15.5's recording tap uses this to emit DELTAS only (the trace
+ *  format's "deltas only" line), never a full snapshot every tick. `prev`
+ *  is `undefined` for an action never recorded before (always "changed"). */
+function actionValuesEqual(
+  prev: boolean | number | { x: number; y: number } | undefined,
+  next: boolean | number | { x: number; y: number },
+): boolean {
+  if (prev === undefined) return false;
+  if (typeof prev !== typeof next) return false;
+  if (typeof prev === 'object' && typeof next === 'object') {
+    return prev.x === next.x && prev.y === next.y;
+  }
+  return prev === next;
+}
+
+/** Cap on {@link InputManager}'s post-gate input-trace ring (D15/T-D15.5) —
+ *  mirrors `debug-registry.ts`'s own `RING_CAP` precedent for the debug event
+ *  ring: bounds memory for a recording session a caller forgot to stop. */
+const INPUT_TRACE_CAP = 2000;
+
 /**
  * Maps raw keyboard/mouse/gamepad events → named actions.
  *
@@ -296,6 +360,85 @@ export class InputManager {
   private static isStickActive(v: Vector2): boolean {
     return Math.hypot(v.x, v.y) > 0.3;
   }
+  // Task 1.4 (ACCEPTANCE-DRIVER-BUILD-PLAN.md) — action-level virtual input
+  // for a synthetic player, promoted from hollowstone's `VirtualInput`. Held
+  // digitals OR into isPressed alongside binding contributions (like
+  // touchButtonsDown above); tap queues, then is promoted to "active" for
+  // exactly one poll()/endFrame() bracket (see poll()/endFrame() below,
+  // mirroring hollowstone's queued/beginFrame contract); scalar/vector2 are
+  // level values feeding the same max-magnitude/sum combine every real
+  // binding uses (collectScalarContributions/collectVector2Contributions).
+  private virtualDigitalHeld = new Set<string>();
+  private virtualDigitalTapQueued = new Set<string>();
+  private virtualDigitalTapActive = new Set<string>();
+  /** pulse-runner friction #4 — the release-edge mirror of
+   *  `virtualDigitalTapActive`: a direct `setVirtualAction(action, false)` (or
+   *  `clearVirtualActions()`) on an action that WAS held writes here so
+   *  `isJustReleased` fires exactly once, mirroring real `onKeyUp`'s
+   *  immediate `keysJustUp` write (no queue/promotion needed — unlike the
+   *  press edge, nothing in `poll()` reassigns this set out from under a
+   *  write that lands before `poll()` runs). Cleared every `endFrame()`,
+   *  same bracket as every other just-* edge set. */
+  private virtualDigitalJustReleased = new Set<string>();
+  private virtualScalarValues = new Map<string, number>();
+  private virtualVector2Values = new Map<string, Vector2>();
+  // D15/T-D15.5 (docs/D15-DETERMINISM-DESIGN.md §2.c) — tick-indexed input
+  // scheduling + post-gate recording.
+  //
+  // `currentTick` is a FALLBACK, self-incrementing counter, used only when a
+  // caller never tells `poll()` which tick it's servicing (every existing
+  // bare/headless caller — tests, a mount with no `Game` shell behind it —
+  // keeps this exact pre-existing behavior, zero regression). The REAL
+  // per-world wiring (`vgai-scene-game-adapter.ts`) instead passes the
+  // shared `Game`-level tick counter into every `poll(tick)` call — this is
+  // deliberate: an InputManager-local counter drifts from the actual game
+  // tick for a paused/frozen world (its `poll()` isn't called every game
+  // tick, so a local increment-per-call counter undercounts) — see the
+  // `lastServicedTick` gap-handling below, which structurally can't drift
+  // because it's driven by whatever tick value the CALLER (ultimately the
+  // shared `Game` tick) actually supplies.
+  private currentTick = 0;
+  /** The last tick value `poll()` actually serviced, or `-1` before the
+   *  first call. Used to detect a GAP (this world's input phase didn't run
+   *  for one or more intervening ticks — e.g. frozen/paused while other
+   *  roots kept advancing the shared game tick) so any schedule entries
+   *  inside that gap can be dropped (with an observable event) instead of
+   *  silently rotting in {@link scheduledActions} forever. */
+  private lastServicedTick = -1;
+  /** Pending `scheduleActionAtTick` actuations, grouped by their exact target
+   *  tick. Applied (and removed) at the START of that tick's `poll()` — see
+   *  `applyScheduledActionsForTick`. A tick whose input phase is skipped
+   *  entirely (this world paused/frozen, or a gap between two serviced
+   *  ticks) never reaches it — its scheduled entries are dropped, each
+   *  emitting one `'input.schedule.dropped'` debug event (`{tick, action}`)
+   *  via {@link setDebugEmit}'s sink if one is wired — NOT retried on a
+   *  later tick (mirrors `clearVirtualActions`-on-gate-close: no stuck
+   *  actuation ever silently fires late). */
+  private scheduledActions = new Map<
+    number,
+    { action: string; value: boolean | number | { x: number; y: number } }[]
+  >();
+  /** Optional sink for the `'input.schedule.dropped'` debug event (`{tick,
+   *  action}`) emitted whenever a scheduled entry is discarded because its
+   *  target tick's input phase never ran. Wired by whoever constructs this
+   *  `InputManager` with access to a `DebugRegistry`
+   *  (`vgai-scene-game-adapter.ts`, the same seed spot as
+   *  `setVirtualInputTarget`/`setInputActionsSource`) — `null` (the
+   *  default) for a bare/headless `InputManager`, in which case a drop
+   *  stays silent (matching pre-D15/T-D15.5 behavior). */
+  private debugEmit: ((event: string, detail?: unknown) => void) | null = null;
+  /** D15/T-D15.5 recording toggle — see {@link startInputRecording}. */
+  private inputRecording = false;
+  /** The post-gate action-delta trace (§2.c's format sketch) — capped so an
+   *  accidentally-long recording session can't grow this unboundedly. */
+  private inputTrace: {
+    tick: number;
+    actions: Record<string, boolean | number | { x: number; y: number }>;
+  }[] = [];
+  /** Last value recorded per action, so `recordPostGateTick` only ever
+   *  appends a DELTA (the format sketch's "deltas only" line), not a full
+   *  snapshot every tick. Cleared on `startInputRecording()`. */
+  private lastTraceSnapshot = new Map<string, boolean | number | { x: number; y: number }>();
   private disposed = false;
   /**
    * When false, all raw input is ignored and held/transient state is cleared.
@@ -320,6 +463,17 @@ export class InputManager {
   private get inputActive(): boolean {
     return this.enabled && this.focused;
   }
+  /** #144 — the gate MACHINE input passes (virtual actions and
+   *  tick-scheduled actuations): the editor's explicit `enabled` flag ONLY.
+   *  Window focus deliberately does not participate: a synthetic player
+   *  drives the shared editor tab precisely while the human's focus is
+   *  elsewhere (their terminal, another window) — the first live in-editor
+   *  probe run froze mid-suite the moment the owner started typing to their
+   *  agent, which is the bug this gate split fixes. Real-device input keeps
+   *  the stricter `inputActive` (enabled AND focused) gate above. */
+  private get machineInputActive(): boolean {
+    return this.enabled;
+  }
   /** F2 — real pointer-lock state (`document.pointerLockElement`), tracked via
    *  `pointerlockchange` (see the constructor). */
   private pointerLocked = false;
@@ -380,12 +534,15 @@ export class InputManager {
     this.mouseDeltaY += e.movementY;
   };
 
-  /** F2 — real window blur: drop focus and flush held state, mirroring
-   *  `setEnabled(false)`'s flush (see `flushHeldState`), without touching the
-   *  editor-driven `enabled` flag. */
+  /** F2 — real window blur: drop focus and flush held REAL-device state
+   *  (the browser stops delivering keyup/mouseup while blurred, so a key
+   *  held at alt-tab time would stick). #144: virtual-action state is
+   *  deliberately NOT flushed here — a bot's held action survives the human
+   *  looking away (see `machineInputActive`); only `setEnabled(false)`
+   *  clears it. */
   private onWindowBlur = () => {
     this.focused = false;
-    this.flushHeldState();
+    this.flushRealHeldState();
   };
 
   /** F2 — real window focus regain. No flush needed (there's nothing held to
@@ -395,14 +552,15 @@ export class InputManager {
     this.focused = true;
   };
 
-  /** Clear all held/transient keyboard/mouse/touch-button state — shared by
-   *  `setEnabled(false)` and real blur (`onWindowBlur`), so a key/button
-   *  physically held when input is suspended doesn't linger. Level values
-   *  (gamepad axes, touch sticks, injected test axes) are deliberately NOT
-   *  flushed here — they are gated at READ time instead (see `inputActive`
-   *  checks in `poll()`/the `collect*Contributions` methods), matching the
-   *  pre-existing gamepad-axis convention. */
-  private flushHeldState(): void {
+  /** Clear held/transient REAL-device state (keyboard/mouse/touch-button) —
+   *  shared by `setEnabled(false)` (via `flushHeldState`) and real blur
+   *  (`onWindowBlur`), so a key/button physically held when input is
+   *  suspended doesn't linger. Level values (gamepad axes, touch sticks,
+   *  injected test axes) are deliberately NOT flushed here — they are gated
+   *  at READ time instead (see `inputActive` checks in `poll()`/the
+   *  `collect*Contributions` methods), matching the pre-existing
+   *  gamepad-axis convention. */
+  private flushRealHeldState(): void {
     this.keysDown.clear();
     this.keysJustDown.clear();
     this.keysJustUp.clear();
@@ -416,6 +574,45 @@ export class InputManager {
     this.touchButtonsJustUp.clear();
   }
 
+  /** The full flush `setEnabled(false)` performs: real-device state AND
+   *  virtual-action state. Task 1.4's rule ("a bot's held action must not
+   *  survive input being suspended") now applies only to the editor's
+   *  explicit gate — #144 moved real window blur onto `flushRealHeldState`
+   *  alone, so machine input survives the human's focus leaving the tab.
+   *  No release edge is manufactured here (`manufactureReleaseEdge: false`,
+   *  the default) — this is a SUSPEND, not a deliberate release, and mirrors
+   *  `flushRealHeldState`'s own silence (a key physically held at
+   *  suspend/blur time is wiped with no `keysJustUp`, "flush held state,
+   *  don't corrupt history", see `poll()`'s doc comment). */
+  private flushHeldState(): void {
+    this.flushRealHeldState();
+    this.clearVirtualActionState();
+  }
+
+  /** Shared by the public `clearVirtualActions()` and `flushHeldState()`
+   *  above — clears every virtual-action store (held digitals, queued/active
+   *  taps, scalar/vector2 values, the release-edge set itself).
+   *
+   *  `manufactureReleaseEdge` (default `false`): when `true` — only
+   *  `clearVirtualActions()`'s own deliberate "let go" passes this — every
+   *  currently-held digital in `virtualDigitalHeld` first gets an
+   *  `isJustReleased` edge written to `virtualDigitalJustReleased`, mirroring
+   *  a real key-up (`onKeyUp` → `keysJustUp`). `flushHeldState()` (the
+   *  editor-gate suspend path) deliberately passes `false` — see its own doc
+   *  comment for why a suspend must stay silent. */
+  private clearVirtualActionState(options?: { manufactureReleaseEdge: boolean }): void {
+    if (options?.manufactureReleaseEdge) {
+      for (const action of this.virtualDigitalHeld) {
+        this.virtualDigitalJustReleased.add(action);
+      }
+    }
+    this.virtualDigitalHeld.clear();
+    this.virtualDigitalTapQueued.clear();
+    this.virtualDigitalTapActive.clear();
+    this.virtualScalarValues.clear();
+    this.virtualVector2Values.clear();
+  }
+
   constructor() {
     window.addEventListener('keydown', this.onKeyDown);
     window.addEventListener('keyup', this.onKeyUp);
@@ -529,10 +726,56 @@ export class InputManager {
     return [...this.actions.keys()];
   }
 
-  /** Poll gamepads and virtual look stick (call at start of frame) */
-  poll() {
-    if (!this.inputActive) {
-      // Input suspended (editor-gated play mode, OR — F2 — real window blur).
+  /**
+   * Poll gamepads and virtual look stick (call at start of frame).
+   *
+   * `tick` (D15/T-D15.3/.5) — the GAME tick this call services. Pass the
+   * live, shared `Game` tick counter here (`vgai-scene-game-adapter.ts` does,
+   * via `DebugRegistry.getGameTick()`) so `scheduleActionAtTick`'s numbering
+   * never drifts from the actual game tick — the bug an earlier revision of
+   * this feature had: an InputManager-LOCAL counter, incremented once per
+   * `poll()` call, undercounts for a paused/frozen world (its `poll()` isn't
+   * called every game tick while frozen), so a schedule set against "tick
+   * 500" could fire at the wrong wall-tick once the world resumed. Omit it
+   * (every existing bare/headless caller does) to fall back to the
+   * self-incrementing `currentTick` counter — unchanged pre-D15 behavior.
+   */
+  poll(tick?: number) {
+    const servicedTick = tick !== undefined ? tick : this.currentTick;
+    // D15/T-D15.5 — a GAP: one or more ticks strictly between the last tick
+    // this InputManager serviced and this one never ran its input phase at
+    // all (this world was paused/frozen and skipped straight from tick A to
+    // a later tick B > A+1 once stepped/resumed again — the frozen-world
+    // scenario objection above). Any entries scheduled for a tick inside
+    // that gap can never be honored — drop them (each emitting one
+    // `'input.schedule.dropped'` event) rather than leaving them to rot in
+    // `scheduledActions` forever. Guarded on `size > 0` so the overwhelmingly
+    // common case (nothing ever scheduled) costs nothing, even across a
+    // very large gap.
+    if (this.scheduledActions.size > 0) {
+      // Iterate the (tiny) schedule map, never the gap's tick RANGE — a
+      // world resuming after a very long freeze (or one mounting late into
+      // a game already millions of ticks in) must not pay O(gap) here.
+      // Sorted so drop events still arrive in tick order.
+      const gapped = [...this.scheduledActions.keys()]
+        .filter((t) => t > this.lastServicedTick && t < servicedTick)
+        .sort((a, b) => a - b);
+      for (const t of gapped) {
+        const skipped = this.scheduledActions.get(t)!;
+        this.scheduledActions.delete(t);
+        for (const entry of skipped) {
+          this.debugEmit?.('input.schedule.dropped', { tick: t, action: entry.action });
+        }
+      }
+    }
+    this.lastServicedTick = servicedTick;
+    this.currentTick = servicedTick + 1;
+    if (!this.enabled) {
+      // Input suspended by the editor's explicit gate (play stopped /
+      // game-tab-inactive). #144: this branch no longer covers real window
+      // blur — an enabled-but-blurred tick falls through so MACHINE input
+      // (virtual actions, scheduled actuations) keeps flowing while the
+      // human's focus is elsewhere; real devices are gated further down.
       // Unlike keyboard/mouse, gamepad state isn't DOM-event-driven —
       // `isPressed`/`isJustPressed`/`isJustReleased` read `this.gamepads`
       // (and the edge-tracked sets) directly, not a live poll of `navigator`.
@@ -544,9 +787,49 @@ export class InputManager {
       // resume diffing against genuinely-last-observed hardware state once
       // re-enabled, so there's no phantom edge on re-enable (mirrors the
       // "flush held state, don't corrupt history" intent of setEnabled below).
+      // D15/T-D15.5: a tick serviced while gated drops its OWN scheduled
+      // entries too (never applied, never retried later) — same honesty line
+      // `setVirtualAction`'s own gate already draws — each emitting the same
+      // `'input.schedule.dropped'` event the gap-handling above does.
+      const gatedDrop = this.scheduledActions.get(servicedTick);
+      if (gatedDrop) {
+        this.scheduledActions.delete(servicedTick);
+        for (const entry of gatedDrop) {
+          this.debugEmit?.('input.schedule.dropped', { tick: servicedTick, action: entry.action });
+        }
+      }
       this.gamepads = [];
       return;
     }
+    // Task 1.4 — promote queued tapVirtualAction() calls to this frame's
+    // "active" just-pressed set (hollowstone's queued/beginFrame contract,
+    // ported onto this engine's existing fixed-step poll()/endFrame()
+    // bracket instead of a bespoke beginFrame() — poll() already runs at the
+    // start of the fixed step). Cleared in endFrame() below.
+    this.virtualDigitalTapActive = this.virtualDigitalTapQueued;
+    this.virtualDigitalTapQueued = new Set();
+    // D15/T-D15.5 — apply any actuation scheduled for exactly this tick
+    // (spec §2.c: "applied at the START of the target tick's input phase",
+    // before any gameplay phase reads input — this still runs before every
+    // OTHER phase this tick, `input` being the first system phase). Placed
+    // AFTER the tap-queue promotion immediately above (not before) so a
+    // scheduled digital `true` can add itself to `virtualDigitalTapActive`
+    // (see `applyScheduledActionsForTick`) without that promotion's
+    // reassignment wiping it out.
+    this.applyScheduledActionsForTick(servicedTick);
+
+    if (!this.focused) {
+      // #144 — enabled but blurred: everything ABOVE this line is machine
+      // input (tap promotion, scheduled actuations) and stays live; real
+      // devices below gate exactly as the old combined branch did (no
+      // gamepads presented, edge sets frozen at their last real values).
+      // The post-gate trace still records — "what the sim actually
+      // consumed" includes machine input delivered while blurred.
+      this.gamepads = [];
+      this.recordPostGateTick(servicedTick);
+      return;
+    }
+
     this.gamepads = navigator.getGamepads ? [...navigator.getGamepads()] : [];
 
     // Gamepad button edge detection: diff this frame's pressed set against the
@@ -593,6 +876,102 @@ export class InputManager {
       this.mouseDeltaX += this.lookStickX * scale;
       this.mouseDeltaY += this.lookStickY * scale;
     }
+    // D15/T-D15.5 — tap the POST-GATE resolved values for this tick LAST
+    // (every binding/virtual/scheduled contribution above has already been
+    // folded in): "what the sim actually consumed", the honesty line the
+    // design doc draws for record-now/replay-in-SP5 (§2.c).
+    this.recordPostGateTick(servicedTick);
+  }
+
+  /**
+   * D15/T-D15.5 — apply every actuation `scheduleActionAtTick` queued for
+   * exactly `tick`, then forget them (a tick is serviced at most once).
+   *
+   * Digital `true` gets SPECIAL handling (the objection-1 fix): it promotes
+   * the action into this tick's `virtualDigitalTapActive` set directly — the
+   * same one-tick "active" pulse `tapVirtualAction` uses — so `isJustPressed`
+   * reads true for EXACTLY this tick (false on the next, per `endFrame()`'s
+   * clear) while `isPressed` keeps reading true afterward (still held) until
+   * a later scheduled/explicit `false` releases it. This direct write is
+   * safe here (unlike `applyVirtualActionValue`'s equivalent direct-path
+   * case — see its doc comment) specifically because this method only ever
+   * runs from inside `poll()`, AFTER `poll()`'s own tap-queue-promotion
+   * reassignment of `virtualDigitalTapActive` has already happened for this
+   * tick (see `poll()`'s own comment on why it's placed after) — so there's
+   * no risk of this write being silently wiped by that reassignment.
+   *
+   * pulse-runner friction #4: a prior revision of this comment
+   * used to say `setVirtualAction`'s plain write "never produces a
+   * just-pressed edge at all" and that the edge fix landed ONLY here, for
+   * this scheduled path — true at the time, and exactly the gap a blind
+   * dogfood run (pulse-runner) hit through the direct `setVirtualAction`/
+   * `holdFor` path. `applyVirtualActionValue` now manufactures the same kind
+   * of edge for THAT path too (queued instead of written directly, for the
+   * timing reason above) — this is no longer the only path that does.
+   *
+   * A digital `false` here simply releases the hold — no edge is
+   * manufactured for it at a SCHEDULED tick (no caller needs a virtual
+   * `isJustReleased` fired at an exact future tick today); the direct
+   * `setVirtualAction(action, false)`/`clearVirtualActions()` paths DO
+   * manufacture one now (see `applyVirtualActionValue`/
+   * `clearVirtualActionState`). Scalar/vector2 values apply directly,
+   * unchanged.
+   */
+  private applyScheduledActionsForTick(tick: number): void {
+    const pending = this.scheduledActions.get(tick);
+    if (!pending) return;
+    this.scheduledActions.delete(tick);
+    for (const entry of pending) {
+      if (typeof entry.value === 'boolean') {
+        if (entry.value) {
+          this.virtualDigitalHeld.add(entry.action);
+          this.virtualDigitalTapActive.add(entry.action);
+        } else {
+          this.virtualDigitalHeld.delete(entry.action);
+        }
+      } else {
+        this.applyVirtualActionValue(entry.action, entry.value);
+      }
+    }
+  }
+
+  /** D15/T-D15.5 — append this tick's action-value DELTA to the recording
+   *  ring, iff a recording is active. Reads every declared digital/scalar/
+   *  vector2 action through the exact same typed getters gameplay code would
+   *  (`readAction`), so the trace reflects what a component reading these
+   *  actions THIS tick actually sees post-gate — never a raw/ungated value.
+   *  `pointerDelta`/`pointerPosition` actions are skipped (a different,
+   *  frame-accumulated shape, and not part of the virtual-action/schedule
+   *  surface this trace exists to prove).
+   *
+   *  Two replay-affecting caveats a future SP5 consumer must know:
+   *  1. A gated stretch never calls this at all (`poll()`'s gated branch
+   *     returns before reaching it) — no entries are recorded for ticks
+   *     input was suspended. Any change only OBSERVABLE once re-enabled (a
+   *     delta against `lastTraceSnapshot`) lands as a delta AT the re-enable
+   *     tick, not at whatever tick it actually happened.
+   *  2. This ring is capped (`INPUT_TRACE_CAP`) and evicts via `shift()` once
+   *     it fills — dropping the OLDEST entry. Because entries are DELTAS,
+   *     evicting the earliest entries drops the base state later deltas were
+   *     relative to — this ring is not safe to replay from its start once it
+   *     has ever been capped. */
+  private recordPostGateTick(tick: number): void {
+    if (!this.inputRecording) return;
+    const deltas: Record<string, boolean | number | { x: number; y: number }> = {};
+    let changed = false;
+    for (const name of this.actionNames()) {
+      const type = this.getActionValueType(name);
+      if (type !== 'digital' && type !== 'scalar' && type !== 'vector2') continue;
+      const value = this.readAction(name, type);
+      const prev = this.lastTraceSnapshot.get(name);
+      if (actionValuesEqual(prev, value)) continue;
+      deltas[name] = value;
+      this.lastTraceSnapshot.set(name, value);
+      changed = true;
+    }
+    if (!changed) return;
+    this.inputTrace.push({ tick, actions: deltas });
+    if (this.inputTrace.length > INPUT_TRACE_CAP) this.inputTrace.shift();
   }
 
   /** Has a `gamepad_axis` binding's raw value crossed its direction+deadzone
@@ -608,6 +987,11 @@ export class InputManager {
   /** Is an action currently held down? */
   isPressed(actionName: string): boolean {
     this.assertValueType(actionName, 'digital', 'isPressed');
+    // Task 1.4 — a held virtual action, or a tap promoted to this frame's
+    // "active" set, ORs into isPressed alongside binding contributions.
+    if (this.virtualDigitalHeld.has(actionName) || this.virtualDigitalTapActive.has(actionName)) {
+      return true;
+    }
     const bindings = this.actions.get(actionName);
     if (!bindings) return false;
 
@@ -644,6 +1028,10 @@ export class InputManager {
   /** Was an action pressed this frame (not held from previous)? */
   isJustPressed(actionName: string): boolean {
     this.assertValueType(actionName, 'digital', 'isJustPressed');
+    // Task 1.4 — a tapVirtualAction() queued on a prior frame reads
+    // just-pressed for exactly the one poll()/endFrame() bracket it was
+    // promoted into (see poll()/endFrame() below).
+    if (this.virtualDigitalTapActive.has(actionName)) return true;
     const bindings = this.actions.get(actionName);
     if (!bindings) return false;
 
@@ -688,6 +1076,11 @@ export class InputManager {
   /** Was an action released this frame (held last frame, up now)? */
   isJustReleased(actionName: string): boolean {
     this.assertValueType(actionName, 'digital', 'isJustReleased');
+    // pulse-runner friction #4 — mirrors isJustPressed's virtual check above:
+    // a direct setVirtualAction(action, false) or clearVirtualActions() on a
+    // held action manufactures exactly one just-released edge here, matching
+    // a real key-up's keysJustUp.
+    if (this.virtualDigitalJustReleased.has(actionName)) return true;
     const bindings = this.actions.get(actionName);
     if (!bindings) return false;
 
@@ -732,6 +1125,14 @@ export class InputManager {
    *  iteration order. */
   getDigitalSource(actionName: string): ActionValueSource | null {
     this.assertValueType(actionName, 'digital', 'getDigitalSource');
+    // #144 — mirror isPressed's own pre-gate virtual check: a machine-held
+    // action reports its source even while the window is blurred.
+    if (
+      this.machineInputActive &&
+      (this.virtualDigitalHeld.has(actionName) || this.virtualDigitalTapActive.has(actionName))
+    ) {
+      return { bindingType: 'virtual' };
+    }
     if (!this.inputActive) return null;
     const bindings = this.actions.get(actionName);
     if (!bindings) return null;
@@ -823,10 +1224,18 @@ export class InputManager {
   private collectScalarContributions(
     actionName: string,
   ): { value: number; source: ActionValueSource }[] {
-    if (!this.inputActive) return [];
-    const bindings = this.actions.get(actionName);
-    if (!bindings) return [];
     const out: { value: number; source: ActionValueSource }[] = [];
+    // Task 1.4 — a virtual scalar value joins the same max-magnitude combine
+    // real bindings do (computeScalar below). #144: it passes the MACHINE
+    // gate (enabled only), so a bot's held value reads through while the
+    // window is blurred; real bindings below keep the full focus gate.
+    const virtual = this.virtualScalarValues.get(actionName);
+    if (virtual !== undefined && this.machineInputActive) {
+      out.push({ value: virtual, source: { bindingType: 'virtual' } });
+    }
+    if (!this.inputActive) return out;
+    const bindings = this.actions.get(actionName);
+    if (!bindings) return out;
     for (const binding of bindings) {
       if (binding.type === 'gamepad_axis') {
         const dz = binding.deadzone ?? 0.15;
@@ -904,10 +1313,17 @@ export class InputManager {
   private collectVector2Contributions(
     actionName: string,
   ): { value: Vector2; source: ActionValueSource }[] {
-    if (!this.inputActive) return [];
-    const bindings = this.actions.get(actionName);
-    if (!bindings) return [];
     const out: { value: Vector2; source: ActionValueSource }[] = [];
+    // Task 1.4 — a virtual vector2 value joins the same sum-then-clamp
+    // combine real bindings do (computeVector2 below). #144: machine gate
+    // only, same as the scalar collector above.
+    const virtual = this.virtualVector2Values.get(actionName);
+    if (virtual !== undefined && this.machineInputActive) {
+      out.push({ value: virtual, source: { bindingType: 'virtual' } });
+    }
+    if (!this.inputActive) return out;
+    const bindings = this.actions.get(actionName);
+    if (!bindings) return out;
     for (const binding of bindings) {
       switch (binding.type) {
         case 'test_vector2': {
@@ -1511,6 +1927,14 @@ export class InputManager {
     // F2 — touch-button edges, same shape as the mouse-button edges above.
     this.touchButtonsJustDown.clear();
     this.touchButtonsJustUp.clear();
+    // Task 1.4 — a promoted tap is just-pressed for exactly one poll()/
+    // endFrame() bracket.
+    this.virtualDigitalTapActive.clear();
+    // Mirrors the line above for the release edge a direct
+    // `setVirtualAction(action, false)`/`clearVirtualActions()` manufactures
+    // (see `virtualDigitalJustReleased`'s doc comment) — just-released for
+    // exactly one poll()/endFrame() bracket too.
+    this.virtualDigitalJustReleased.clear();
   }
 
   /** Inject synthetic key state from touch controls */
@@ -1579,6 +2003,261 @@ export class InputManager {
     this.touchStickValues.delete(sourceId);
   }
 
+  // ==========================================================================
+  // Task 1.4 (ACCEPTANCE-DRIVER-BUILD-PLAN.md / SYNTHETIC-PLAYER-SPEC.md §3.2)
+  // — action-level virtual input for a synthetic player. Promoted from
+  // hollowstone's proven `VirtualInput` (`bot/virtual-input.ts`): a bot drives
+  // NAMED ACTIONS (not raw devices), and its contributions join action
+  // resolution at exactly the same points binding contributions do (see
+  // isPressed/isJustPressed and collectScalarContributions/
+  // collectVector2Contributions above). #144 split the gates: virtual input
+  // passes `machineInputActive` (the editor's `enabled` flag only), while
+  // human input keeps the full `inputActive` (enabled AND focused) gate — a
+  // synthetic player must keep playing the shared editor tab while the
+  // human's focus is elsewhere. Unlike every typed getter above (which
+  // treats an unknown action as inert), these THROW on an unknown name — a
+  // synthetic-player caller needs a loud signal that the action it's driving
+  // doesn't exist, not a silently-ignored actuation.
+  // ==========================================================================
+
+  /** Existence check shared by `setVirtualAction`/`tapVirtualAction` — throws
+   *  `InputActionError` (`code: 'INPUT_ACTION_NOT_FOUND'`, `data.registered`
+   *  = every declared action name) for a name that was never
+   *  `registerAction`/`loadMap`-ed. */
+  private assertActionExists(actionName: string, method: string): void {
+    if (!this.actionValueTypes.has(actionName)) {
+      throw new InputActionError(actionName, method, this.actionNames());
+    }
+  }
+
+  /** Which declared `ActionValueType` a `setVirtualAction` value shape
+   *  corresponds to — the type-safety check mirrors every typed getter's
+   *  `assertValueType` (F1). `pointerDelta`/`pointerPosition` actions aren't
+   *  drivable through `setVirtualAction` (no boolean/number/Vector2 call
+   *  shape maps to them) — use `injectPointerDelta`/`injectPointerPosition`. */
+  private static virtualValueCategory(
+    value: boolean | number | { x: number; y: number },
+  ): ActionValueType {
+    if (typeof value === 'boolean') return 'digital';
+    if (typeof value === 'number') return 'scalar';
+    return 'vector2';
+  }
+
+  /**
+   * Set a virtual value for `action`, OR'd/summed into the same action reads
+   * humans drive (see the section doc comment above). A `boolean` holds a
+   * digital action pressed until set `false`/cleared; a `number` or `{x,y}`
+   * is a level value combined via the action's own scalar max-magnitude /
+   * vector2 sum-then-clamp rule.
+   *
+   * A digital `false`→`true` transition manufactures a genuine `isJustPressed`
+   * edge, exactly one real key-down does (pulse-runner friction #4 —
+   * previously this write-half only ever held the action pressed with NO
+   * edge at all; every edge-triggered ability driven through this direct
+   * path was unprovable). Re-setting `true` while already held (auto-repeat)
+   * does NOT re-fire it — see {@link applyVirtualActionValue}. The mirror
+   * `true`→`false` transition manufactures an `isJustReleased` edge the same
+   * way a real key-up does.
+   *
+   * Throws `InputActionError` for an unregistered `action`, and the same
+   * valueType-mismatch error every typed getter throws (`assertValueType`)
+   * when `value`'s shape doesn't match the action's declared `valueType`.
+   *
+   * Gated (`setEnabled(false)` — play stopped or editor-gated; #144: window
+   * focus no longer gates machine input): writes NOTHING — matching
+   * `setTouchButton`'s write-gate precedent above — and returns
+   * `{delivered: false, reason}` rather than a silent no-op, so a probe/bot
+   * never mistakes a swallowed actuation for a delivered one.
+   */
+  setVirtualAction(
+    action: string,
+    value: boolean | number | { x: number; y: number },
+  ): { delivered: boolean; reason?: string } {
+    this.assertActionExists(action, 'setVirtualAction');
+    const expected = InputManager.virtualValueCategory(value);
+    this.assertValueType(action, expected, 'setVirtualAction');
+    if (!this.machineInputActive) {
+      return { delivered: false, reason: 'input-gated (input disabled by the editor)' };
+    }
+    this.applyVirtualActionValue(action, value);
+    return { delivered: true };
+  }
+
+  /**
+   * The write half of {@link setVirtualAction} — extracted so D15/T-D15.5's
+   * `scheduleActionAtTick` can apply a non-boolean (scalar/vector2) queued
+   * actuation through the exact same code path (no gate check here: the two
+   * callers gate differently — `setVirtualAction` above checks
+   * `inputActive` before calling this; `applyScheduledActionsForTick` is
+   * only ever reached from inside `poll()` AFTER its own gate check has
+   * already returned early on a gated tick). `applyScheduledActionsForTick`
+   * still handles digital `true` itself rather than calling here (its
+   * one-tick edge must land EXACTLY at the scheduled tick — see its own doc
+   * comment) — this method's digital branch is `setVirtualAction`'s direct
+   * path, called at an arbitrary point relative to the poll()/endFrame()
+   * bracket.
+   *
+   * pulse-runner friction #4 — the digital branch used to be a bare held-flag
+   * write with no manufactured edge at all (the comment that used to sit
+   * here read: "A digital value is handled by `applyScheduledActionsForTick`
+   * itself (it needs the extra just-pressed edge a plain held-value write
+   * doesn't produce)" — i.e. the edge fix shipped ONLY for the scheduled
+   * path, never for this one, which is exactly the gap a blind dogfood run
+   * hit: `setVirtualAction('jump', true)` held the action down but
+   * `isJustPressed('jump')` never fired). Fixed here by reusing
+   * `tapVirtualAction`'s exact one-tick-pulse queue mechanism for this
+   * DIRECT case, specifically because this method's caller can land at any
+   * point relative to `poll()`: writing `virtualDigitalTapActive` directly
+   * here (as the scheduled path safely does, from inside `poll()` itself)
+   * would risk being silently wiped by `poll()`'s own unconditional
+   * `virtualDigitalTapActive = virtualDigitalTapQueued` reassignment,
+   * depending on timing. Queueing side-steps that hazard by construction —
+   * the same reason `tapVirtualAction` queues instead of writing directly. A
+   * redundant `true` while already held (`virtualDigitalHeld` already has
+   * `action`) does not queue again, matching a real key's auto-repeat never
+   * re-firing `isJustPressed`. The `false` branch mirrors real `onKeyUp`
+   * instead (immediate write, no queue needed — nothing in `poll()`
+   * reassigns `virtualDigitalJustReleased`), and only fires when the action
+   * was actually held (no released→released re-fire).
+   */
+  private applyVirtualActionValue(
+    action: string,
+    value: boolean | number | { x: number; y: number },
+  ): void {
+    switch (InputManager.virtualValueCategory(value)) {
+      case 'digital':
+        if (value as boolean) {
+          if (!this.virtualDigitalHeld.has(action)) this.virtualDigitalTapQueued.add(action);
+          this.virtualDigitalHeld.add(action);
+        } else {
+          if (this.virtualDigitalHeld.has(action)) this.virtualDigitalJustReleased.add(action);
+          this.virtualDigitalHeld.delete(action);
+        }
+        break;
+      case 'scalar':
+        this.virtualScalarValues.set(action, value as number);
+        break;
+      default:
+        this.virtualVector2Values.set(action, value as { x: number; y: number });
+        break;
+    }
+  }
+
+  /**
+   * One-frame press of a `'digital'` action (Task 1.4): queues `action` so it
+   * reads `isJustPressed`/`isPressed` true for EXACTLY the next `poll()`'s
+   * frame — promoted to the "active" set at the top of `poll()`, cleared in
+   * `endFrame()` alongside every other just-pressed edge set (see both
+   * above). Hollowstone's `queued`/`beginFrame` tap contract, ported onto
+   * this engine's existing fixed-step `poll()`/`endFrame()` bracket instead
+   * of a bespoke `beginFrame()` hook.
+   *
+   * Throws the same errors as {@link setVirtualAction} (unknown action;
+   * non-digital valueType). A gated tap does NOT queue — it must not fire on
+   * a later frame once input becomes active again — and returns
+   * `{delivered: false, reason}`.
+   */
+  tapVirtualAction(action: string): { delivered: boolean; reason?: string } {
+    this.assertActionExists(action, 'tapVirtualAction');
+    this.assertValueType(action, 'digital', 'tapVirtualAction');
+    if (!this.machineInputActive) {
+      return { delivered: false, reason: 'input-gated (input disabled by the editor)' };
+    }
+    this.virtualDigitalTapQueued.add(action);
+    return { delivered: true };
+  }
+
+  /** Clear all virtual-action state — held digitals, queued/active taps, and
+   *  scalar/vector2 values. `flushHeldState()` (the same flush
+   *  `setEnabled(false)`/real blur apply to held keys/mouse/touch buttons)
+   *  shares the underlying wipe, so a bot's held action never survives input
+   *  being suspended — but only THIS public entry point (a deliberate "let
+   *  go", the mirror of `setVirtualAction(action, false)` below) manufactures
+   *  an `isJustReleased` edge for whatever was held; the suspend path stays
+   *  silent (see `flushHeldState`'s own doc comment). */
+  clearVirtualActions(): void {
+    this.clearVirtualActionState({ manufactureReleaseEdge: true });
+  }
+
+  /**
+   * D15/T-D15.5 (`docs/D15-DETERMINISM-DESIGN.md` §2.c) — schedule a virtual
+   * actuation for exactly `tick`: applied at the START of that tick's
+   * `poll()` (composing with `runTicks` — a schedule for tick 500 fires
+   * exactly once the sim has been driven through tick 500, regardless of
+   * burst size). A digital `true` produces a genuine `isJustPressed` edge
+   * exactly at the target tick (not merely a held value — see
+   * `applyScheduledActionsForTick`).
+   *
+   * Throws `InputActionError` for an unregistered `action` and the same
+   * valueType-mismatch error every typed getter throws (`assertValueType`) —
+   * both checked EAGERLY, at schedule time, not deferred to the target tick.
+   * Throws `InputTickError` (`code: 'TICK_ALREADY_PASSED'`) when `tick` is
+   * strictly less than the tick `poll()` will service NEXT — scheduling only
+   * ever reaches the current or a future tick. A tick whose input phase
+   * never runs (this world paused/frozen at that point, or a multi-tick gap
+   * — see `poll()`) drops its scheduled entries rather than replaying them
+   * late — each drop emits one `'input.schedule.dropped'` debug event
+   * (`{tick, action}`) via {@link setDebugEmit}'s sink, if one is wired.
+   */
+  scheduleActionAtTick(
+    tick: number,
+    action: string,
+    value: boolean | number | { x: number; y: number },
+  ): void {
+    this.assertActionExists(action, 'scheduleActionAtTick');
+    const expected = InputManager.virtualValueCategory(value);
+    this.assertValueType(action, expected, 'scheduleActionAtTick');
+    if (tick < this.currentTick) {
+      throw new InputTickError(tick, this.currentTick);
+    }
+    const pending = this.scheduledActions.get(tick);
+    if (pending) pending.push({ action, value });
+    else this.scheduledActions.set(tick, [{ action, value }]);
+  }
+
+  /** Wire (or clear, via `null`) the sink `poll()` calls with
+   *  `'input.schedule.dropped'` (`{tick, action}`) whenever it discards a
+   *  scheduled entry for a tick whose input phase never ran. Called once by
+   *  whoever constructs this `InputManager` with a `DebugRegistry` behind it
+   *  (`vgai-scene-game-adapter.ts`), the same seed spot as
+   *  `setVirtualInputTarget`/`setInputActionsSource` — never called directly
+   *  by gameplay code. */
+  setDebugEmit(fn: ((event: string, detail?: unknown) => void) | null): void {
+    this.debugEmit = fn;
+  }
+
+  /** D15/T-D15.5 — start (or restart) recording the post-gate action-delta
+   *  trace: clears any prior trace/snapshot, so a fresh recording session
+   *  never carries over stale deltas from an earlier one. */
+  startInputRecording(): void {
+    this.inputRecording = true;
+    this.inputTrace = [];
+    this.lastTraceSnapshot.clear();
+  }
+
+  /** D15/T-D15.5 — stop recording (the trace accumulated so far stays
+   *  readable via {@link getInputTrace} until the next `startInputRecording`
+   *  clears it). Idempotent. */
+  stopInputRecording(): void {
+    this.inputRecording = false;
+  }
+
+  /** D15/T-D15.5 — whether a recording is currently active. */
+  isInputRecording(): boolean {
+    return this.inputRecording;
+  }
+
+  /** D15/T-D15.5 — the recorded trace so far (a defensive copy), versioned
+   *  per the design doc's format sketch (§2.c). SP5 (out of scope here) is
+   *  the eventual consumer that replays this; this module only ever
+   *  RECORDS. */
+  getInputTrace(): {
+    version: 1;
+    ticks: { tick: number; actions: Record<string, boolean | number | { x: number; y: number }> }[];
+  } {
+    return { version: 1, ticks: this.inputTrace.slice() };
+  }
+
   /** Request pointer lock for FPS-style mouse control */
   requestPointerLock(element: HTMLElement) {
     // Idempotent: never stack duplicate click listeners. Rewire if the element