@vgai/engine 0.5.13 → 0.5.14

package/src/behavior/xstate-inspection.ts

@@ -0,0 +1,51 @@
+import type * as THREE from 'three';
+import type { AnyStateMachine } from 'xstate';
+import { deleteUserData, getUserData, setUserData } from '../ecs/user-data';
+
+/** Minimal structural actor surface needed by the live behavior debugger. */
+export interface InspectableXStateActor {
+  readonly getSnapshot: () => {
+    readonly value: unknown;
+    readonly context: unknown;
+    readonly machine?: AnyStateMachine;
+  };
+  readonly subscribe: (next: (snapshot: { readonly value: unknown }) => void) => {
+    unsubscribe: () => void;
+  };
+  readonly logic?: AnyStateMachine;
+}
+
+export interface XStateBehaviorInspection {
+  readonly actor: InspectableXStateActor;
+  readonly machine: AnyStateMachine;
+}
+
+let version = 0;
+const listeners = new Set<() => void>();
+
+function notify(): void {
+  version++;
+  for (const listener of listeners) listener();
+}
+
+export function subscribeXStateBehaviorInspections(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function xstateBehaviorInspectionsVersion(): number {
+  return version;
+}
+
+export function attachXStateBehaviorInspection(
+  owner: THREE.Object3D,
+  inspection: XStateBehaviorInspection,
+): () => void {
+  setUserData(owner, '_xstateBehavior', inspection);
+  notify();
+  return () => {
+    if (getUserData(owner, '_xstateBehavior') !== inspection) return;
+    deleteUserData(owner, '_xstateBehavior');
+    notify();
+  };
+}

package/src/core/game-loop.ts

@@ -1,6 +1,12 @@
 import { clampTimeScale, paceFrame, TIME_SCALE_RANGE } from './frame-pacing';
 import type { GameLoopConfig, GameLoopLiveness } from './types';
 
+/** A visible rAF chain that has produced no callback for this long is not
+ * honestly "running" merely because its callback remains armed. One second
+ * is far beyond an ordinary dropped frame and short enough for status to
+ * report browser starvation while it is still actionable. */
+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
@@ -56,19 +62,24 @@ export function createGameLoop(config: GameLoopConfig) {
   // Idle throttle (T2.1): a hidden tab stops the loop outright; becoming
   // visible again restarts it with the accumulator clock resynced to "now" —
   // deliberately no catch-up burst for the wall-clock time spent hidden.
-  let hiddenPaused = false;
+  let visibilityPaused = false;
   let visibilityListenerAttached = false;
 
-  function handleVisibilityChange() {
+  /** Reconcile the gate against the CURRENT document bit, not merely the
+   * last event. Browsers can miss/coalesce visibilitychange around window
+   * occlusion and reloads; reading liveness is itself a recovery opportunity,
+   * so a stale event can never leave this flag permanently wedged. */
+  function reconcileVisibilityGate() {
+    if (externalDrive || !visibilityListenerAttached) return;
     if (typeof document === 'undefined') return;
     if (document.hidden) {
       if (running) {
         running = false;
         cancelAnimationFrame(rafId);
-        hiddenPaused = true;
+        visibilityPaused = true;
       }
-    } else if (hiddenPaused) {
-      hiddenPaused = false;
+    } else if (visibilityPaused) {
+      visibilityPaused = false;
       running = true;
       lastTime = performance.now();
       accumulator = 0;
@@ -76,6 +87,10 @@ export function createGameLoop(config: GameLoopConfig) {
     }
   }
 
+  function handleVisibilityChange() {
+    reconcileVisibilityGate();
+  }
+
   function frame(currentTime: number) {
     if (!running) return;
     rafId = requestAnimationFrame(frame);
@@ -107,13 +122,13 @@ export function createGameLoop(config: GameLoopConfig) {
     start() {
       if (running) return;
       running = true;
-      // A direct start() call can land while the loop is auto-hidden-paused
-      // (`hiddenPaused` true, `running` false, no rAF pending). Without this
+      // A direct start() call can land while the loop is auto-loop-starved
+      // (`visibilityPaused` true, `running` false, no rAF pending). Without this
       // reset, a later visibilitychange-to-visible would see stale
-      // `hiddenPaused === true` and spawn a SECOND rAF chain on top of the
+      // `visibilityPaused === true` and spawn a SECOND rAF chain on top of the
       // one this call is about to start (doubled update()/render() overhead
       // until the next stop() — no sim-speed effect, but wasted work).
-      hiddenPaused = false;
+      visibilityPaused = false;
       lastTime = performance.now();
       accumulator = 0;
 
@@ -137,7 +152,7 @@ export function createGameLoop(config: GameLoopConfig) {
       }
       if (typeof document !== 'undefined' && document.hidden) {
         running = false;
-        hiddenPaused = true;
+        visibilityPaused = true;
         return;
       }
 
@@ -146,7 +161,7 @@ export function createGameLoop(config: GameLoopConfig) {
 
     stop() {
       running = false;
-      hiddenPaused = false;
+      visibilityPaused = false;
       cancelAnimationFrame(rafId);
 
       if (visibilityListenerAttached && typeof document !== 'undefined') {
@@ -156,22 +171,29 @@ export function createGameLoop(config: GameLoopConfig) {
     },
 
     get isRunning() {
+      reconcileVisibilityGate();
       return running;
     },
 
     /**
      * Truthful liveness (issue #175 — see `GameLoopLiveness`'s doc comment
      * in `core/types.ts` for the full contract). Unlike `isRunning` above,
-     * this DISTINGUISHES a hidden-tab pause from an actually-stopped loop:
-     * `hiddenPaused` is only ever set by `handleVisibilityChange` (T2.1's
-     * idle throttle) and cleared by `start()`/`stop()`/visibility-restore,
-     * so it can never be true at the same time `running` is true. An
+     * this distinguishes a starved rAF loop from an actually-stopped loop.
+     * `visibilityPaused` records the deliberate `document.hidden` gate, and
+     * every read first reconciles that flag against the CURRENT document bit
+     * so a missed visibilitychange cannot wedge it. A visible, armed chain
+     * also reports starvation when no real frame callback has arrived within
+     * {@link LOOP_STARVATION_MS}; "armed" alone is not evidence of progress. An
      * `externalDrive` loop never installs the visibility listener at all
-     * (see `start()` above), so `hiddenPaused` stays permanently `false` for
+     * (see `start()` above), so `visibilityPaused` stays permanently `false` for
      * it — it only ever reports `'running'` or `'stopped'`.
      */
     get liveness(): GameLoopLiveness {
-      if (hiddenPaused) return 'hidden-paused';
+      reconcileVisibilityGate();
+      if (visibilityPaused) return 'loop-starved';
+      if (running && !externalDrive && performance.now() - lastTime > LOOP_STARVATION_MS) {
+        return 'loop-starved';
+      }
       return running ? 'running' : 'stopped';
     },
 

package/src/core/types.ts

@@ -110,18 +110,17 @@ export interface GameLoopConfig {
  * debug-registry.ts`) can name the union without importing `game-loop.ts`
  * as a value.
  *
- * - `'running'` — the rAF chain is armed and `config.update` is being
- *   driven by real frames (or, for an `externalDrive` loop, `start()` has
- *   been called — see that mode's own liveness note below).
- * - `'hidden-paused'` — the T2.1 idle throttle stopped the loop because
- *   `document.hidden` is true; this is deliberate and reversible (resumes
- *   automatically on visibility), but ZERO ticks are advancing right now.
+ * - `'running'` — a real rAF callback arrived recently (or, for an
+ *   `externalDrive` loop, `start()` has been called — see that mode's own
+ *   liveness note below).
+ * - `'loop-starved'` — the host loop has made no recent rAF progress: either
+ *   the T2.1 visibility gate deliberately parked it, or an armed visible-page
+ *   callback has not arrived within the starvation threshold. This reports
+ *   the LOOP measurement, never a conclusion about where the browser tab is.
  * - `'stopped'` — `stop()` was called, or `start()` was never called.
  *
- * `isRunning` collapses `'hidden-paused'` and `'stopped'` into the same
- * `false` — exactly the ambiguity that let a hidden-paused game report as
- * healthy ("playing") through every consumer that only read `isRunning`/
- * store-level play state. Read `liveness` wherever "is this game actually
- * advancing" matters.
+ * `isRunning` says whether the rAF chain is armed; it can therefore remain
+ * `true` while a visible browser starves callbacks. Read `liveness` wherever
+ * "is this host loop actually advancing" matters.
  */
-export type GameLoopLiveness = 'running' | 'hidden-paused' | 'stopped';
+export type GameLoopLiveness = 'running' | 'loop-starved' | 'stopped';

package/src/data/data-asset.ts

@@ -94,7 +94,7 @@ export function defineData<S extends z.ZodType>(
         parsed = parseDataJson(schema, next, sourcePath);
       } catch (err) {
         // Keep the last good value alive — see the JSDoc on DataHandle.hotSwap.
-        // biome-ignore lint/suspicious/noConsole: deliberate, greppable — a rejected live-tune edit must be loud without crashing the running game (mirrors achieved-tier.ts's direct console use)
+        // biome-ignore lint/suspicious/noConsole: deliberate, greppable — a rejected live-tune edit must be loud without crashing the running game
         console.error(`[data] hot edit rejected, keeping previous values.\n${String(err)}`);
         return;
       }

package/src/dev/instruments.ts

@@ -50,6 +50,7 @@
  */
 
 import { z } from 'zod';
+import { nodeKeyedPhysics } from '../adapter/system-adapter';
 import { clampTimeScale, TIME_SCALE_RANGE } from '../core/frame-pacing';
 import type { Game } from '../runtime/game';
 
@@ -175,7 +176,10 @@ export function createDevInstruments(game: Game): DevInstrumentSet {
   // below, which is also the only thing that calls the adapter.
   let collidersDrawn = false;
   const colliderDraw = () => {
-    const adapter = game.systemAdapters.physics;
+    // Node-id keyed only — `setDebugDrawEnabled` draws THREE wireframes into
+    // the world, which a canvas mount's display-keyed carrier has no analogue
+    // for and does not declare.
+    const adapter = nodeKeyedPhysics(game.systemAdapters.physics);
     return adapter?.setDebugDrawEnabled ? adapter : null;
   };
 

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

@@ -18,6 +18,12 @@
  * `annotation: null` (counted as unattributed) — never a fabricated guess. The
  * wrappers are all restored when the capture resolves, rejects, times out, or
  * the adapter is disposed.
+ *
+ * That attribution is a THREE capability, not a property of frame capture: a
+ * surface whose renderer has no per-draw annotation seam omits `scene` entirely
+ * (the Pixi ingest lane does — `editor/src/ingest/ingest-render-debug.ts`), and
+ * every draw is then recorded unattributed. The capture itself is GL-level and
+ * unchanged either way; only the names beside the draws go away.
  */
 
 import type * as THREE from 'three';
@@ -44,8 +50,19 @@ export function frameCaptureContextFor(
 export interface RenderDebugAdapterDeps {
   /** The armed-on-demand frame capture over the mount's real context. */
   capture: WebGLFrameCapture;
-  /** The live scene root traversed to attribute draws. */
-  scene: THREE.Object3D;
+  /**
+   * The live three scene root traversed to attribute draws to the objects that
+   * issue them.
+   *
+   * OMITTED on a surface whose renderer publishes no per-draw annotation seam —
+   * the Pixi lane, where display objects have no `onBeforeRender` and the
+   * batcher merges many display objects into one draw, so there is no object to
+   * name for a given draw at all. Then every draw is recorded with
+   * `annotation: null` and lands in `totals.unattributed`: the honest "this
+   * seam cannot say who drew this", never a guess derived from the scene's
+   * shape.
+   */
+  scene?: THREE.Object3D;
   /** Memory snapshot supplier (renderer.info-backed). When omitted, the
    *  adapter's `memorySnapshot` is absent (honest capability degradation). */
   memory?: () => RenderMemorySnapshot;
@@ -127,6 +144,9 @@ export function createRenderDebugAdapter(deps: RenderDebugAdapterDeps): RenderDe
 
   function wrapOnBeforeRender(): (() => void)[] {
     const restores: (() => void)[] = [];
+    // No scene ⇒ no annotation seam on this surface (see `scene` above): wrap
+    // nothing, restore nothing, and let every draw record `annotation: null`.
+    if (!scene) return restores;
     scene.traverse((object) => {
       if (!isRenderable(object)) return;
       const original = object.onBeforeRender;

package/src/ecs/user-data.ts

@@ -46,8 +46,10 @@
  *                           mixer; see xstate-animation-binding.ts).
  * - `_availableClips`     — string[] of clip names discovered on the GLTF
  *                           (inspector dropdown; same names as `_animClips`' keys).
- * - `_xstateAnimation`    — live native XState/Three binding exposed for
- *                           play-mode inspection; removed when binding disposes.
+ * - `_animationRuntime`   — format-neutral live native mixer/action inspection.
+ * - `_xstateBehavior`     — optional live XState behavior actor inspection.
+ * - `_xstateAnimation`    — compatibility handle for the optional XState→Three
+ *                           bridge; animation UI never discovers through it.
  *
  * Disposal contract:
  * - `__sharedGeometry`    — `true` when a mesh's geometry is shared/cached and MUST
@@ -118,7 +120,9 @@ import type { ParticleSystem } from 'three.quarks';
 import type { ConstraintMark } from '../adapter/constraint';
 import type { RapierEditableBody } from '../adapter/rapier-physics-adapter';
 import type { ReflectionProbeMark } from '../adapter/reflection-probe';
+import type { AnimationRuntimeInspection } from '../animation/runtime-inspection';
 import type { XStateAnimationBinding } from '../animation/xstate-animation-binding';
+import type { XStateBehaviorInspection } from '../behavior/xstate-inspection';
 
 /** The kinds of editor helper objects tagged via `editorHelperType`. */
 export type EditorHelperType =
@@ -165,6 +169,8 @@ export interface UserDataSchema {
   _animMixer: THREE.AnimationMixer;
   _animClips: Map<string, THREE.AnimationClip>;
   _availableClips: string[];
+  _animationRuntime: AnimationRuntimeInspection;
+  _xstateBehavior: XStateBehaviorInspection;
   _xstateAnimation: XStateAnimationBinding;
   __sharedGeometry: boolean;
   __shadeOrig: THREE.Material | THREE.Material[];
@@ -222,6 +228,8 @@ export const UserDataKeys = {
   _animMixer: '_animMixer',
   _animClips: '_animClips',
   _availableClips: '_availableClips',
+  _animationRuntime: '_animationRuntime',
+  _xstateBehavior: '_xstateBehavior',
   _xstateAnimation: '_xstateAnimation',
   __sharedGeometry: '__sharedGeometry',
   __shadeOrig: '__shadeOrig',

package/src/input/binding-identity.ts

@@ -0,0 +1,37 @@
+import type { InputBinding } from './input-types';
+
+/**
+ * Whether two bindings name the same physical input.
+ *
+ * This is the native identity rule used by both runtime rebinding and the
+ * editor's `.inputmap.json` document. Deadzones do not change identity, while
+ * opposite directions on one gamepad axis remain independent controls.
+ */
+export function inputBindingsCollide(a: InputBinding, b: InputBinding): boolean {
+  if (a.type !== b.type) return false;
+  switch (a.type) {
+    case 'key':
+      return a.code === (b as typeof a).code;
+    case 'mouse_button':
+      return a.button === (b as typeof a).button;
+    case 'mouse_move':
+      return true;
+    case 'gamepad_button':
+      return a.button === (b as typeof a).button;
+    case 'gamepad_axis': {
+      const other = b as typeof a;
+      return a.axis === other.axis && a.direction === other.direction;
+    }
+    case 'gamepad_axis_pair': {
+      const other = b as typeof a;
+      return a.xAxis === other.xAxis && a.yAxis === other.yAxis;
+    }
+    case 'touch_button':
+    case 'touch_stick':
+    case 'test_axis':
+    case 'test_vector2':
+    case 'test_pointer_delta':
+    case 'test_pointer_position':
+      return a.sourceId === (b as typeof a).sourceId;
+  }
+}

package/src/input/input-manager.ts

@@ -1,5 +1,6 @@
 import { AssetParseError } from '../asset-parse-error';
 import { resolveUrl } from '../loader';
+import { inputBindingsCollide } from './binding-identity';
 import type {
   ActionValueOf,
   ActionValueSource,
@@ -235,7 +236,7 @@ const INPUT_TRACE_CAP = 2000;
  *     map this class serializes is a valid document for B2 to read back.
  *   - Conflicts: `findConflicts(proposed, excludeActionName?)` scans every
  *     OTHER registered action's bindings for one that's structurally
- *     equivalent to `proposed` (see the private `bindingsCollide` — same
+ *     equivalent to `proposed` (see `inputBindingsCollide` — same
  *     physical input identity: same key code, same mouse button, the same
  *     gamepad button/axis/axis-pair, the same touch `sourceId`, etc.) and
  *     returns the (possibly empty) list as plain `BindingConflict` data —
@@ -261,15 +262,28 @@ const INPUT_TRACE_CAP = 2000;
  *
  *   - `getLastActiveDevice()` returns the `PromptDevice` family of whichever
  *     input arrived most recently — keyboard on `keydown`, mouse on
- *     `mousedown`/a real `mousemove`, gamepad on a button press or a stick
- *     pushed meaningfully off-center (checked in `poll()`), touch on
- *     `setTouchButton(_, true)` or `setTouchStick` pushed meaningfully
- *     off-center. `null` before any input has arrived.
+ *     `mousedown`/a real `mousemove`, gamepad on a button press or an axis
+ *     past ITS OWN DECLARED DEADZONE (checked in `poll()`), touch on
+ *     `setTouchButton(_, true)` or a `setTouchStick` past the deadzone that
+ *     stick's binding declares. `null` before any input has arrived. The
+ *     off-rest threshold is always the game's declaration, never a constant
+ *     this class picked — see `declaredDeadzone`.
  *   - `getPrompt(actionName)` (device omitted) resolves against it directly,
  *     falling back to `'keyboard'` before any input has arrived — a HUD can
  *     call it every frame with no extra bookkeeping and the label switches on
  *     its own.
  */
+/**
+ * The documented deadzone defaults, one home each. Both are stated in
+ * `input/schema.ts`'s own `.describe()` text — spelled here so every reader
+ * (the value getters AND the active-device tracker) uses the SAME number, which
+ * is the drift the tracker's old hardcoded 0.3 was.
+ */
+const GAMEPAD_AXIS_DEFAULT_DEADZONE = 0.15;
+/** `touch_stick`'s documented default: none. A virtual stick reports a value
+ *  only because a finger is on it, so it has no at-rest jitter floor to clear. */
+const TOUCH_STICK_DEFAULT_DEADZONE = 0;
+
 export class InputManager {
   private actions = new Map<string, InputBinding[]>();
   // F1 — each registered/loaded action's declared value shape (defaults to
@@ -344,20 +358,44 @@ export class InputManager {
   // the player switches controllers, without the caller having to guess or
   // track this itself. Updated at the same points raw input arrives: keydown
   // (`'keyboard'`), mousedown/mousemove (`'mouse'`), a gamepad button press or
-  // a stick pushed meaningfully past rest (`'gamepad'`, both detected in
+  // an axis past its declared deadzone (`'gamepad'`, both detected in
   // `poll()` — a raw resting stick reports small non-zero noise on some
-  // pads, so this deliberately checks a coarse magnitude, not "any non-zero
-  // axis"), and a touch button press / stick pushed past rest
+  // pads, so this checks the threshold the GAME declared for that axis, not
+  // "any non-zero axis"), and a touch button press / stick pushed past rest
   // (`'touch'` — `setTouchButton`/`setTouchStick`). `null` until the very
   // first input of any kind arrives. See `getLastActiveDevice`/`getPrompt`.
   private lastActiveDevice: PromptDevice | null = null;
-  /** Coarse "is this stick meaningfully off-center" check shared by the
-   *  gamepad and touch-stick active-device heuristics above — deliberately a
-   *  higher bar than a binding's own (often much smaller) configured
-   *  deadzone, since this is "did the player just grab this control", not
-   *  "does this binding's value count as non-zero". */
-  private static isStickActive(v: Vector2): boolean {
-    return Math.hypot(v.x, v.y) > 0.3;
+  /**
+   * "Is this control off its rest position" for the active-device tracker,
+   * answered from what the GAME DECLARED rather than from a threshold this
+   * class invented.
+   *
+   * It used to be `Math.hypot(v.x, v.y) > 0.3` — a constant nobody could see or
+   * change, sitting on top of a deadzone the game had already stated. A game
+   * that declares a 0.5 deadzone on its move stick considers everything under
+   * 0.5 to be rest; reporting "the player switched to gamepad" at 0.31 makes a
+   * HUD's prompt flip to a control the game itself is ignoring. Zero inference
+   * (ARCHITECTURE-CORE §The editor protocol) says the fix is to read the
+   * declaration, and it is already here in `this.actions`.
+   *
+   * SMALLEST wins when several bindings name one source: the first magnitude at
+   * which ANY of the game's own bindings treats the control as live is the
+   * moment the player has grabbed it.
+   */
+  private declaredDeadzone(
+    matches: (binding: InputBinding) => number | undefined,
+    documentedDefault: number,
+  ): number {
+    let smallest: number | undefined;
+    for (const bindings of this.actions.values()) {
+      for (const binding of bindings) {
+        const declared = matches(binding);
+        if (declared !== undefined && (smallest === undefined || declared < smallest)) {
+          smallest = declared;
+        }
+      }
+    }
+    return smallest ?? documentedDefault;
   }
   // Task 1.4 — action-level virtual input
   // for a synthetic player, promoted from hollowstone's `VirtualInput`. Held
@@ -859,15 +897,30 @@ export class InputManager {
     // above. isPressed/isJustPressed/isJustReleased apply a binding's own
     // threshold to these raw values (current vs. `gamepadAxesPrev`) on read.
     const currentAxes = new Map<string, number>();
+    // F4 — the deadzone THIS GAME declares on each axis, resolved once per poll
+    // (see `declaredDeadzone`): an axis reading past the game's own rest
+    // threshold is unambiguous real gamepad input; anything under it is the
+    // resting noise every pad emits, and the game is already ignoring it.
+    const axisDeadzone = new Map<number, number>();
     for (let i = 0; i < this.gamepads.length; i++) {
       const gp = this.gamepads[i];
       if (!gp) continue;
       for (let a = 0; a < gp.axes.length; a++) {
         const value = gp.axes[a] ?? 0;
         currentAxes.set(`${i}:${a}`, value);
-        // F4 — a stick pushed meaningfully off-center is also unambiguous
-        // real gamepad input (see `isStickActive`'s doc comment).
-        if (Math.abs(value) > 0.3) this.lastActiveDevice = 'gamepad';
+        let deadzone = axisDeadzone.get(a);
+        if (deadzone === undefined) {
+          deadzone = this.declaredDeadzone(
+            (binding) =>
+              (binding.type === 'gamepad_axis' && binding.axis === a) ||
+              (binding.type === 'gamepad_axis_pair' && (binding.xAxis === a || binding.yAxis === a))
+                ? (binding.deadzone ?? GAMEPAD_AXIS_DEFAULT_DEADZONE)
+                : undefined,
+            GAMEPAD_AXIS_DEFAULT_DEADZONE,
+          );
+          axisDeadzone.set(a, deadzone);
+        }
+        if (Math.abs(value) > deadzone) this.lastActiveDevice = 'gamepad';
       }
     }
     this.gamepadAxesCurrent = currentAxes;
@@ -1011,7 +1064,7 @@ export class InputManager {
           }
           break;
         case 'gamepad_axis': {
-          const dz = binding.deadzone ?? 0.15;
+          const dz = binding.deadzone ?? GAMEPAD_AXIS_DEFAULT_DEADZONE;
           for (const gp of this.gamepads) {
             if (!gp) continue;
             const val = gp.axes[binding.axis] ?? 0;
@@ -1056,7 +1109,7 @@ export class InputManager {
           // Edge-tracked via raw axis snapshots (poll()): true only on the
           // first frame the thresholded (direction+deadzone) boolean flips
           // from off→on (across any connected gamepad).
-          const dz = binding.deadzone ?? 0.15;
+          const dz = binding.deadzone ?? GAMEPAD_AXIS_DEFAULT_DEADZONE;
           for (let i = 0; i < this.gamepads.length; i++) {
             const key = `${i}:${binding.axis}`;
             const now = this.gamepadAxesCurrent.get(key) ?? 0;
@@ -1102,7 +1155,7 @@ export class InputManager {
         case 'gamepad_axis': {
           // The mirror of isJustPressed: true only on the first frame the
           // thresholded boolean flips from on→off.
-          const dz = binding.deadzone ?? 0.15;
+          const dz = binding.deadzone ?? GAMEPAD_AXIS_DEFAULT_DEADZONE;
           for (let i = 0; i < this.gamepads.length; i++) {
             const key = `${i}:${binding.axis}`;
             const now = this.gamepadAxesCurrent.get(key) ?? 0;
@@ -1155,7 +1208,7 @@ export class InputManager {
           }
           break;
         case 'gamepad_axis': {
-          const dz = binding.deadzone ?? 0.15;
+          const dz = binding.deadzone ?? GAMEPAD_AXIS_DEFAULT_DEADZONE;
           for (let i = 0; i < this.gamepads.length; i++) {
             const gp = this.gamepads[i];
             if (!gp) continue;
@@ -1240,7 +1293,7 @@ export class InputManager {
     if (!bindings) return out;
     for (const binding of bindings) {
       if (binding.type === 'gamepad_axis') {
-        const dz = binding.deadzone ?? 0.15;
+        const dz = binding.deadzone ?? GAMEPAD_AXIS_DEFAULT_DEADZONE;
         for (let i = 0; i < this.gamepads.length; i++) {
           const gp = this.gamepads[i];
           if (!gp) continue;
@@ -1292,7 +1345,7 @@ export class InputManager {
   private contributeGamepadAxisPair(
     binding: Extract<InputBinding, { type: 'gamepad_axis_pair' }>,
   ): { value: Vector2; source: ActionValueSource }[] {
-    const dz = binding.deadzone ?? 0.15;
+    const dz = binding.deadzone ?? GAMEPAD_AXIS_DEFAULT_DEADZONE;
     const out: { value: Vector2; source: ActionValueSource }[] = [];
     for (let i = 0; i < this.gamepads.length; i++) {
       const gp = this.gamepads[i];
@@ -1350,7 +1403,10 @@ export class InputManager {
         case 'touch_stick': {
           const raw = this.touchStickValues.get(binding.sourceId) ?? { x: 0, y: 0 };
           out.push({
-            value: InputManager.rescaleVector2(raw, binding.deadzone ?? 0),
+            value: InputManager.rescaleVector2(
+              raw,
+              binding.deadzone ?? TOUCH_STICK_DEFAULT_DEADZONE,
+            ),
             source: { bindingType: 'touch_stick', sourceId: binding.sourceId },
           });
           break;
@@ -1715,46 +1771,6 @@ export class InputManager {
     for (const actionName of this.defaultBindings.keys()) this.resetBindings(actionName);
   }
 
-  /**
-   * Whether `a` and `b` are the SAME physical input (F3's structural-conflict
-   * identity check — see `findConflicts`). Deliberately narrower than deep
-   * equality: `deadzone` never participates (two bindings on the same key
-   * with different deadzones are still the same physical control), and a
-   * `gamepad_axis`'s `direction` DOES participate — opposite directions of one
-   * physical axis (e.g. "accelerate" on positive, "brake" on negative) are a
-   * legitimate, non-conflicting pair, not a collision.
-   */
-  private static bindingsCollide(a: InputBinding, b: InputBinding): boolean {
-    if (a.type !== b.type) return false;
-    switch (a.type) {
-      case 'key':
-        return a.code === (b as typeof a).code;
-      case 'mouse_button':
-        return a.button === (b as typeof a).button;
-      case 'mouse_move':
-        return true; // there is only one physical mouse-move source
-      case 'gamepad_button':
-        return a.button === (b as typeof a).button;
-      case 'gamepad_axis': {
-        const other = b as typeof a;
-        return a.axis === other.axis && a.direction === other.direction;
-      }
-      case 'gamepad_axis_pair': {
-        const other = b as typeof a;
-        return a.xAxis === other.xAxis && a.yAxis === other.yAxis;
-      }
-      case 'touch_button':
-      case 'touch_stick':
-      case 'test_axis':
-      case 'test_vector2':
-      case 'test_pointer_delta':
-      case 'test_pointer_position':
-        return a.sourceId === (b as typeof a).sourceId;
-      default:
-        return false;
-    }
-  }
-
   /**
    * Every EXISTING binding, on every OTHER registered action, that is
    * structurally the same physical input as `proposed` (F3 AC "conflicts are
@@ -1769,7 +1785,7 @@ export class InputManager {
     for (const [actionName, bindings] of this.actions) {
       if (actionName === excludeActionName) continue;
       bindings.forEach((binding, bindingIndex) => {
-        if (InputManager.bindingsCollide(proposed, binding)) {
+        if (inputBindingsCollide(proposed, binding)) {
           conflicts.push({ actionName, bindingIndex, binding: structuredClone(binding) });
         }
       });
@@ -1995,8 +2011,17 @@ export class InputManager {
    */
   setTouchStick(sourceId: string, value: Vector2): void {
     this.touchStickValues.set(sourceId, value);
-    // F4 — mirrors the gamepad-axis heuristic in poll() (see `isStickActive`).
-    if (InputManager.isStickActive(value)) this.lastActiveDevice = 'touch';
+    // F4 — same rule as poll()'s gamepad axes (see `declaredDeadzone`): the
+    // deadzone the game declared on THIS virtual stick decides whether the knob
+    // has left rest, not a number this class picked.
+    const deadzone = this.declaredDeadzone(
+      (binding) =>
+        binding.type === 'touch_stick' && binding.sourceId === sourceId
+          ? (binding.deadzone ?? TOUCH_STICK_DEFAULT_DEADZONE)
+          : undefined,
+      TOUCH_STICK_DEFAULT_DEADZONE,
+    );
+    if (Math.hypot(value.x, value.y) > deadzone) this.lastActiveDevice = 'touch';
   }
 
   /** Clear a virtual stick's value (e.g. simulating the touch point lifting —