@vgai/engine 0.5.13 → 0.5.14

package/dist/core/game-loop.js

@@ -1,4 +1,9 @@
 import { clampTimeScale, paceFrame, TIME_SCALE_RANGE } from './frame-pacing';
+/** 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
@@ -52,26 +57,35 @@ export function createGameLoop(config) {
     // 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;
             rafId = requestAnimationFrame(frame);
         }
     }
+    function handleVisibilityChange() {
+        reconcileVisibilityGate();
+    }
     function frame(currentTime) {
         if (!running)
             return;
@@ -101,13 +115,13 @@ export function createGameLoop(config) {
             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;
             // External-drive mode (I2): never arm rAF and never install the
@@ -130,14 +144,14 @@ export function createGameLoop(config) {
             }
             if (typeof document !== 'undefined' && document.hidden) {
                 running = false;
-                hiddenPaused = true;
+                visibilityPaused = true;
                 return;
             }
             rafId = requestAnimationFrame(frame);
         },
         stop() {
             running = false;
-            hiddenPaused = false;
+            visibilityPaused = false;
             cancelAnimationFrame(rafId);
             if (visibilityListenerAttached && typeof document !== 'undefined') {
                 document.removeEventListener('visibilitychange', handleVisibilityChange);
@@ -145,22 +159,29 @@ export function createGameLoop(config) {
             }
         },
         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() {
-            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';
         },
         set timeScale(value) {

package/dist/core/types.d.ts

@@ -93,19 +93,18 @@ 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';
 //# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;;;;;;CASd,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAE7E,+BAA+B;AAC/B,eAAO,MAAM,WAAW,EAAE,eAAe,EASxC,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,QAAQ,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;AAE5C,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACvE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACtE;AAED,yDAAyD;AACzD,MAAM,WAAW,SAAS;IACxB,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,KAAK,EAAE,eAAe,CAAC;IACvB,4EAA4E;IAC5E,IAAI,CAAC,IAAI,IAAI,CAAC;IACd,uBAAuB;IACvB,MAAM,EAAE,QAAQ,CAAC;IACjB,8DAA8D;IAC9D,OAAO,CAAC,IAAI,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;OAUG;IACH,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACpD;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;;;;;;CASd,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAE7E,+BAA+B;AAC/B,eAAO,MAAM,WAAW,EAAE,eAAe,EASxC,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,QAAQ,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;AAE5C,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACvE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACtE;AAED,yDAAyD;AACzD,MAAM,WAAW,SAAS;IACxB,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,KAAK,EAAE,eAAe,CAAC;IACvB,4EAA4E;IAC5E,IAAI,CAAC,IAAI,IAAI,CAAC;IACd,uBAAuB;IACvB,MAAM,EAAE,QAAQ,CAAC;IACjB,8DAA8D;IAC9D,OAAO,CAAC,IAAI,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;OAUG;IACH,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACpD;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,cAAc,GAAG,SAAS,CAAC"}

package/dist/data/data-asset.js

@@ -57,7 +57,7 @@ export function defineData(schema, initial, 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/dist/dev/instruments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instruments.d.ts","sourceRoot":"","sources":["../../src/dev/instruments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;sCAEsC;AACtC,MAAM,MAAM,oBAAoB;AAC9B,oBAAoB;AAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE;AAC9B,0CAA0C;GACxC;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACtD,6EAA6E;GAC3E;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AACH,sEAAsE;GACpE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9B;;;kBAGkB;AAClB,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC;IAC1B,GAAG,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC;CAC1C;AAED,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACjD,0EAA0E;IAC1E,IAAI,IAAI,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/C,4DAA4D;IAC5D,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC;;mCAEmC;AACnC,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,mEAAmE;AACnE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,gBAAgB,CAehF;AAcD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,GAAG,gBAAgB,CAwIjE"}
+{"version":3,"file":"instruments.d.ts","sourceRoot":"","sources":["../../src/dev/instruments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;sCAEsC;AACtC,MAAM,MAAM,oBAAoB;AAC9B,oBAAoB;AAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE;AAC9B,0CAA0C;GACxC;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACtD,6EAA6E;GAC3E;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AACH,sEAAsE;GACpE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9B;;;kBAGkB;AAClB,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC;IAC1B,GAAG,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC;CAC1C;AAED,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACjD,0EAA0E;IAC1E,IAAI,IAAI,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/C,4DAA4D;IAC5D,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC;;mCAEmC;AACnC,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,mEAAmE;AACnE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,gBAAgB,CAehF;AAcD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,GAAG,gBAAgB,CA2IjE"}

package/dist/dev/instruments.js

@@ -49,6 +49,7 @@
  * collider instruments only drive state that `Game` already owns.
  */
 import { z } from 'zod';
+import { nodeKeyedPhysics } from '../adapter/system-adapter';
 import { clampTimeScale, TIME_SCALE_RANGE } from '../core/frame-pacing';
 /**
  * How many display frames the frame-time reading keeps. ~1 second at 60 Hz —
@@ -103,7 +104,10 @@ export function createDevInstruments(game) {
     // 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;
     };
     const instruments = [

package/dist/dev/render-debug-adapter.d.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';
 import type { RenderDebugAdapter } from '../adapter/system-adapter';
@@ -31,8 +37,19 @@ export declare function frameCaptureContextFor(headless: boolean, rendererContex
 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;

package/dist/dev/render-debug-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-debug-adapter.d.ts","sourceRoot":"","sources":["../../src/dev/render-debug-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,KAAK,EAAgC,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE7F;;;2DAG2D;AAC3D,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,OAAO,EACjB,eAAe,EAAE,OAAO,GACvB,sBAAsB,GAAG,IAAI,CAO/B;AAED,MAAM,WAAW,sBAAsB;IACrC,uEAAuE;IACvE,OAAO,EAAE,iBAAiB,CAAC;IAC3B,wDAAwD;IACxD,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC;IACtB;gFAC4E;IAC5E,MAAM,CAAC,EAAE,MAAM,oBAAoB,CAAC;IACpC;yDACqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;0BACsB;IACtB,YAAY,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACvD,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,+DAA+D;IAC/D,YAAY,IAAI,IAAI,CAAC;IACrB,6EAA6E;IAC7E,WAAW,IAAI,IAAI,CAAC;IACpB,6EAA6E;IAC7E,OAAO,IAAI,IAAI,CAAC;CACjB;AAkDD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,sBAAsB,GAAG,iBAAiB,CAgFxF"}
+{"version":3,"file":"render-debug-adapter.d.ts","sourceRoot":"","sources":["../../src/dev/render-debug-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,KAAK,EAAgC,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE7F;;;2DAG2D;AAC3D,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,OAAO,EACjB,eAAe,EAAE,OAAO,GACvB,sBAAsB,GAAG,IAAI,CAO/B;AAED,MAAM,WAAW,sBAAsB;IACrC,uEAAuE;IACvE,OAAO,EAAE,iBAAiB,CAAC;IAC3B;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC;IACvB;gFAC4E;IAC5E,MAAM,CAAC,EAAE,MAAM,oBAAoB,CAAC;IACpC;yDACqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;0BACsB;IACtB,YAAY,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACvD,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,+DAA+D;IAC/D,YAAY,IAAI,IAAI,CAAC;IACrB,6EAA6E;IAC7E,WAAW,IAAI,IAAI,CAAC;IACpB,6EAA6E;IAC7E,OAAO,IAAI,IAAI,CAAC;CACjB;AAkDD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,sBAAsB,GAAG,iBAAiB,CAmFxF"}

package/dist/dev/render-debug-adapter.js

@@ -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.
  */
 /** Decide whether a mount can host frame capture — a real WebGL2 context with
  *  the draw entry points, never a headless/stub renderer. Exported so the
@@ -73,6 +79,10 @@ export function createRenderDebugAdapter(deps) {
     let pending = null;
     function wrapOnBeforeRender() {
         const restores = [];
+        // 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;

package/dist/ecs/user-data.d.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
@@ -117,7 +119,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 = 'lights' | 'cameras' | 'audio' | 'colliders' | 'joints' | 'lod' | 'splines' | 'particles' | 'particle-shape' | 'pivot' | 'navmesh' | 'constraints' | 'reflection-probes' | 'skeletons';
 /**
@@ -142,6 +146,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[];
@@ -201,6 +207,8 @@ export declare const UserDataKeys: {
     readonly _animMixer: "_animMixer";
     readonly _animClips: "_animClips";
     readonly _availableClips: "_availableClips";
+    readonly _animationRuntime: "_animationRuntime";
+    readonly _xstateBehavior: "_xstateBehavior";
     readonly _xstateAnimation: "_xstateAnimation";
     readonly __sharedGeometry: "__sharedGeometry";
     readonly __shadeOrig: "__shadeOrig";

package/dist/ecs/user-data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user-data.d.ts","sourceRoot":"","sources":["../../src/ecs/user-data.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"user-data.d.ts","sourceRoot":"","sources":["../../src/ecs/user-data.ts"],"names":[],"mappings":"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"}

package/dist/ecs/user-data.js

@@ -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
@@ -132,6 +134,8 @@ export const UserDataKeys = {
     _animMixer: '_animMixer',
     _animClips: '_animClips',
     _availableClips: '_availableClips',
+    _animationRuntime: '_animationRuntime',
+    _xstateBehavior: '_xstateBehavior',
     _xstateAnimation: '_xstateAnimation',
     __sharedGeometry: '__sharedGeometry',
     __shadeOrig: '__shadeOrig',

package/dist/input/binding-identity.d.ts

@@ -0,0 +1,10 @@
+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 declare function inputBindingsCollide(a: InputBinding, b: InputBinding): boolean;
+//# sourceMappingURL=binding-identity.d.ts.map

package/dist/input/binding-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding-identity.d.ts","sourceRoot":"","sources":["../../src/input/binding-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,OAAO,CA2B9E"}

package/dist/input/binding-identity.js

@@ -0,0 +1,36 @@
+/**
+ * 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, b) {
+    if (a.type !== b.type)
+        return false;
+    switch (a.type) {
+        case 'key':
+            return a.code === b.code;
+        case 'mouse_button':
+            return a.button === b.button;
+        case 'mouse_move':
+            return true;
+        case 'gamepad_button':
+            return a.button === b.button;
+        case 'gamepad_axis': {
+            const other = b;
+            return a.axis === other.axis && a.direction === other.direction;
+        }
+        case 'gamepad_axis_pair': {
+            const other = b;
+            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.sourceId;
+    }
+}

package/dist/input/input-manager.d.ts

@@ -27,175 +27,6 @@ export declare class InputTickError extends Error {
     };
     constructor(tick: number, currentTick: number);
 }
-/**
- * Maps raw keyboard/mouse/gamepad events → named actions.
- *
- * Usage:
- *   const input = new InputManager();
- *   await input.loadMap('inputmaps/default.inputmap.json');
- *   // In game loop:
- *   input.poll();  // call at start of frame
- *   if (input.isPressed('jump')) { ... }
- *   if (input.isJustPressed('attack')) { ... }
- *   input.endFrame();  // call at end of frame
- *
- * F1 (spec §12 "Define Typed Action Values") — typed action values:
- *
- * Every action DECLARES a value shape (`InputAction.valueType`, defaulted to
- * `'digital'` — see `input-types.ts`'s `ActionValueType`). Each shape has its
- * own typed getter, none of which return `any`:
- *
- *   - `'digital'`         — `isPressed`/`isJustPressed`/`isJustReleased` -> `boolean`
- *   - `'scalar'`           — `getScalar` -> `number`
- *   - `'vector2'`          — `getVector2` -> `Vector2` ({x,y})
- *   - `'pointerDelta'`     — `getPointerDelta` -> `Vector2`
- *   - `'pointerPosition'`  — `getPointerPosition` -> `Vector2`
- *
- * Reading an action through the WRONG getter (e.g. `getScalar` on a
- * `'digital'` action) throws — that's the type-safety enforcement point,
- * since actions are declared in data (JSON), not TS types, so there's no
- * compiler backstop otherwise. `readAction(name, expectedType)` is a generic
- * entry point over the same getters, typed via `ActionValueOf<T>`.
- *
- * Each typed getter has a `*Source` sibling (e.g. `getScalarSource`) that
- * returns `ActionValueSource | null` — which binding (and, for gamepad
- * bindings, which connected gamepad, or for injected test bindings, which
- * named source) produced the current value. That's the "device/source
- * metadata" AC.
- *
- * Deadzone + normalization:
- *   - scalar: below `deadzone` magnitude -> 0; at/above it, rescaled from 0
- *     (at the deadzone edge) to ±1 (at |raw| = 1), sign preserved
- *     (`rescaleScalar`).
- *   - vector2: below `deadzone` magnitude -> {0,0}; at/above it, direction is
- *     preserved and magnitude is rescaled the same way, then the result is
- *     clamped to the unit circle — magnitude never exceeds 1 even for a raw
- *     diagonal input like {1,1} (`rescaleVector2`).
- *
- * Simultaneous-binding combine rules (documented here, spec §12 F1
- * "simultaneous bindings combine predictably"):
- *   - digital: OR — any one satisfied binding makes the action pressed
- *     (pre-existing behavior, unchanged).
- *   - scalar: max-magnitude across contributing bindings' (deadzone-applied)
- *     values, sign preserved; ties keep the first-listed binding
- *     (deterministic given binding array order).
- *   - vector2: sum contributing (deadzone-applied) {x,y} values component-
- *     wise, then clamp the sum to the unit circle (never renormalized UP —
- *     only ever scaled down if the sum exceeds magnitude 1).
- *   - pointerDelta: sum contributing deltas (matches the existing
- *     mouseDeltaX/Y + lookStick accumulation precedent below).
- *   - pointerPosition: last-write-wins — the contributing source most
- *     recently updated (by injection call order) wins; position isn't
- *     additive so summing would be meaningless.
- *
- * Synthetic input injection (test hook, also the shape of F2's "injected
- * test input" backend): `injectAxis`/`injectVector2`/`injectPointerDelta`/
- * `injectPointerPosition` push a raw value into a named source, read back by
- * binding an action to `{ type: 'test_axis' | 'test_vector2' |
- * 'test_pointer_delta' | 'test_pointer_position', sourceId }` — the exact
- * same aggregation path (deadzone/normalize/combine) real device bindings
- * use.
- *
- * F2 (spec §12 "Complete Device Backends") completes the real-device side of
- * that same typed-value path:
- *
- *   - `mouse_move` — un-rejected (schema.ts). Feeds `getPointerDelta` (raw
- *     accumulated `mouseDeltaX/Y`, no deadzone) and `getVector2` (the same
- *     delta, deadzone-rescaled + unit-circle-clamped).
- *   - `gamepad_axis_pair` — un-rejected (schema.ts). Feeds `getVector2` with
- *     the coupled `(xAxis, yAxis)` reading, deadzone-rescaled like a real
- *     stick (default deadzone 0.15, matching `gamepad_axis`).
- *   - `touch_button`/`touch_stick` — new binding kinds for touch/virtual
- *     controls. `setTouchButton(sourceId, pressed)` feeds a digital action
- *     (edge-tracked like `mouse_button`); `setTouchStick(sourceId, value)`
- *     feeds a vector2 action (deadzone-rescaled like a gamepad stick). These
- *     are the injectable entry points a real on-screen touch UI's own
- *     touchstart/touchmove/touchend handlers would call — that DOM wiring is
- *     a thin adapter at the edge (browser-verified separately, e.g. F4/e2e);
- *     the mapping logic here is unit-tested headlessly with no DOM.
- *   - Focus gating — `blur`/`focus` on `window` (guarded, real DOM only) now
- *     drop input the same way `setEnabled(false)` does (flushing held
- *     key/mouse/touch-button state) without touching the `enabled` flag the
- *     editor drives — see `focused`/`inputActive` below. This is what stops
- *     a stuck key/button when the user alt-tabs away mid-press.
- *   - Pointer lock — `pointerlockchange` on `document` (guarded) tracks
- *     `isPointerLocked()`; losing lock flushes mouse-button state (a click
- *     held at the moment lock exits must not stick).
- *   - Gamepad device identity — `getGamepadInfo(index)` exposes `{index, id,
- *     mapping, connected}`; `ActionValueSource.gamepadId` (in addition to the
- *     pre-existing `gamepadIndex`) is populated for every
- *     gamepad_button/gamepad_axis/gamepad_axis_pair source.
- *   - Disconnection/reconnection needs no new tracking: `poll()` already
- *     re-reads `navigator.getGamepads()` every frame and every read (digital
- *     edges, scalar/vector2 contributions) already skips a `null` gamepad
- *     entry, so a disconnected gamepad's bound actions go neutral (and a
- *     previously-held button correctly fires `isJustReleased`) with no
- *     special-cased code — see the state-transition tests.
- *
- * F3 (spec §12 "Add Rebinding and Prompts") completes the input system with
- * rebinding, structural conflict detection, and device-prompt resolution:
- *
- *   - Listing/mutating: `getBindings`/`setBindings`/`addBinding`/
- *     `removeBinding`/`replaceBinding` — the same `this.actions` map F1/F2
- *     already read, now with a public read + mutation surface (there was
- *     previously none — every existing call site either loaded a map once or
- *     read through the typed getters).
- *   - Reset-to-defaults: `registerAction`/`loadMap`/`loadMapObject` snapshot
- *     each action's bindings into `defaultBindings` (a deep clone) at
- *     registration/load time; `resetBindings`/`resetAllBindings` restore from
- *     that snapshot. Later rebinding calls do NOT touch the snapshot, so
- *     "reset" always means "back to what was authored/loaded", not "back to
- *     the last reset".
- *   - Persist: `toInputMapFile()` serializes the live action set back into
- *     the exact `.inputmap.json` shape (`InputMapFile`) `loadMap` reads;
- *     `loadMapObject(data)` is `loadMap`'s synchronous, no-`fetch` sibling —
- *     both funnel through the same `InputMapFileSchema`-validated
- *     `applyParsedMap`. This is the round-trip seam: serialize, write/hand to
- *     something else, reload, and rebound actions survive. It complements —
- *     doesn't replace — the SDK's `project.inputMap.read/validate/update`
- *     operations (B2, `packages/vgai-sdk/src/project/input-map-operations.ts`):
- *     those are FILE-level (a CLI/agent editing the `.inputmap.json` on disk,
- *     no running game involved); this is RUNTIME-level (a live game rebinding
- *     while playing). Both validate through the identical
- *     `InputMapFileSchema`, so a file B2 wrote loads here unchanged, and a
- *     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
- *     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 —
- *     never throws. A rebinding UI calls this BEFORE calling
- *     `addBinding`/`replaceBinding`/`setBindings` and decides what to do with
- *     a non-empty result (block, warn, let the user steal the binding by
- *     removing it from the other action first).
- *   - Prompts: `getPrompt(actionName, device?, gamepadIndex?)` resolves a
- *     `BindingPrompt` (display label + icon name) for whichever of the
- *     action's bindings belongs to the requested `PromptDevice` family
- *     (keyboard/mouse/gamepad/touch — `bindingDeviceFamily` in
- *     `prompt-labels.ts`), using `getGamepadInfo` to prefer the standard
- *     mapping's canonical glyph names (`'A'`, `'LB'`, ...) for gamepad
- *     buttons and falling back to a raw index label (or a "disconnected"
- *     label) when the pad isn't in standard mapping or isn't connected.
- *     `device` is optional (F4 below) — omit it to resolve against
- *     `getLastActiveDevice()` instead.
- *
- * F4 (spec §12 "Schema and Examples") closes F3's one open gap — a
- * current-ACTIVE-device tracker, so a prompt UI can switch its displayed
- * label as the player switches controllers instead of the caller having to
- * track that itself:
- *
- *   - `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.
- *   - `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.
- */
 export declare class InputManager {
     private actions;
     private actionValueTypes;
@@ -228,12 +59,24 @@ export declare class InputManager {
     private touchButtonsJustUp;
     private touchStickValues;
     private lastActiveDevice;
-    /** 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;
+    /**
+     * "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;
     private virtualDigitalHeld;
     private virtualDigitalTapQueued;
     private virtualDigitalTapActive;
@@ -693,16 +536,6 @@ export declare class InputManager {
     /** Reset every action that has a snapshot back to its registered/loaded
      *  defaults. Convenience batch form of `resetBindings`. */
     resetAllBindings(): void;
-    /**
-     * 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;
     /**
      * Every EXISTING binding, on every OTHER registered action, that is
      * structurally the same physical input as `proposed` (F3 AC "conflicts are