@vgai/engine 0.5.22 → 0.5.24

package/src/input/input-manager.ts

@@ -184,10 +184,16 @@ const INPUT_TRACE_CAP = 2000;
  *     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.
+ *     are the injectable entry points an on-screen touch UI calls, and they
+ *     are the UPPER half of the touch story. The LOWER half — the DOM
+ *     pointer stream itself, as dense finger indices mapped into the game's
+ *     own design space and gated on `isInputActive()` — is
+ *     `input/host-pointer.ts` (`createHostPointer`), beside this file; a
+ *     control drains its `takeTouches()` and calls the setters above.
+ *     What is deliberately still NOT here is the control layer in between:
+ *     which rect owns which finger, and how a knob's offset becomes a stick
+ *     vector, is the shape of the UI drawing the control, so it belongs to
+ *     that UI and there is no first-party one to generalize from yet.
  *   - 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
@@ -428,7 +434,7 @@ export class InputManager {
   // 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 (`setup-three-root-adapter.ts`) instead passes the
+  // per-world wiring (`world3d-react/r3f-root-factory.tsx`) 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
@@ -461,7 +467,7 @@ export class InputManager {
    *  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`
-   *  (`setup-three-root-adapter.ts`, the same seed spot as
+   *  (`world3d-react/r3f-root-factory.tsx`, 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). */
@@ -787,8 +793,8 @@ export class InputManager {
     }
   }
 
-  /** The names of all registered actions (r3f `world-context` enumerates these
-   *  for its input-binding projection). */
+  /** The names of all registered actions (the `game.input.actions` debug seam
+   *  enumerates these — `runtime/game-input-seams.ts`). */
   actionNames(): string[] {
     return [...this.actions.keys()];
   }
@@ -797,7 +803,7 @@ export class InputManager {
    * 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 (`setup-three-root-adapter.ts` does,
+   * live, shared `Game` tick counter here (`world3d-react/r3f-root-factory.tsx` 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
@@ -1691,6 +1697,22 @@ export class InputManager {
     return this.focused;
   }
 
+  /**
+   * The gate every REAL-DEVICE listener here passes: {@link isEnabled} AND
+   * {@link isFocused}. Public because the DOM edge this class deliberately
+   * does not own — `host-pointer.ts`, the pointer stream behind the touch
+   * backends — must pass the SAME gate, and a caller writing
+   * `isEnabled() && isFocused()` out for itself is how a looser one drifts in
+   * (a pointer adapter that checked only `isEnabled` kept updating position
+   * for a blurred tab). Read it; do not recompose it.
+   *
+   * Machine input (`setVirtualAction` and the tick-scheduled actuations) is
+   * deliberately NOT this gate — see `machineInputActive`.
+   */
+  isInputActive(): boolean {
+    return this.inputActive;
+  }
+
   /** Whether the pointer is currently locked to {@link requestPointerLock}'s
    *  element (F2, spec §12 "pointer lock") — tracked via the real
    *  `pointerlockchange` event. */
@@ -2167,12 +2189,11 @@ export class InputManager {
   }
 
   // ==========================================================================
-  // Task 1.4 — action-level virtual input for a synthetic player. Promoted from
-  // hollowstone's proven `VirtualInput` (`bot/virtual-input.ts`): a bot drives
+  // Action-level virtual input for a synthetic player: 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
+  // collectVector2Contributions above). The gates are split: 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
@@ -2380,7 +2401,7 @@ export class InputManager {
    *  `'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
-   *  (`setup-three-root-adapter.ts`), the same seed spot as
+   *  (`world3d-react/r3f-root-factory.tsx`), the same seed spot as
    *  `setVirtualInputTarget`/`setInputActionsSource` — never called directly
    *  by gameplay code. */
   setDebugEmit(fn: ((event: string, detail?: unknown) => void) | null): void {

package/src/input/input-types.ts

@@ -128,7 +128,7 @@ export interface InputMapFile {
 // types. See input-manager.ts's class doc comment for the full design note;
 // these are the plain data shapes shared between `InputManager`'s rebinding
 // API, the framework-free `RebindController` (rebind-controller.ts), and any
-// UI (e.g. the template's `RebindPanel.tsx`) that surfaces them.
+// UI that surfaces them.
 // =============================================================================
 
 /**

package/src/input/rebind-controller.ts

@@ -1,11 +1,9 @@
-// F3 (spec §12 "Add Rebinding and Prompts") — a framework-free rebinding
-// STATE MACHINE over an `InputManager`. Deliberately has no dependency on
-// React (or any UI library): "listen for the next input, surface a conflict,
-// let the caller decide" is the same flow whether the caller is the
-// template's `RebindPanel.tsx` (ordinary React, see that file) or any other
-// UI/CLI. Keeping the logic here means it's unit-testable with no DOM/JSX at
-// all, and the React component becomes a thin, mechanically-verifiable
-// wrapper (see the template component's own doc comment).
+// A framework-free rebinding STATE MACHINE over an `InputManager`.
+// Deliberately has no dependency on React (or any UI library): "listen for the
+// next input, surface a conflict, let the caller decide" is the same flow
+// whether the caller is a React panel or a CLI. Keeping the logic here makes
+// it unit-testable with no DOM/JSX at all, and leaves any UI a thin,
+// mechanically-verifiable wrapper.
 //
 // Flow: `listen(actionName)` -> caller captures the next raw input event
 // itself (a keydown, a gamepad poll, a touch tap — capture is inherently

package/src/input/schema.ts

@@ -37,62 +37,74 @@
 import { z } from 'zod';
 import type { InputAction, InputBinding, InputMapFile } from './input-types';
 
-const KeyBindingSchema = z.object({
-  type: z.literal('key').describe('Binding kind: a keyboard key (KeyboardEvent.code)'),
-  code: z.string().describe('KeyboardEvent.code value, e.g. "KeyW", "Space", "ArrowUp"'),
-});
+const KeyBindingSchema = z
+  .object({
+    type: z.literal('key').describe('Binding kind: a keyboard key (KeyboardEvent.code)'),
+    code: z.string().describe('KeyboardEvent.code value, e.g. "KeyW", "Space", "ArrowUp"'),
+  })
+  .strict();
 
-const MouseButtonBindingSchema = z.object({
-  type: z.literal('mouse_button').describe('Binding kind: a mouse button'),
-  button: z.number().describe('MouseEvent.button index (0 = left, 1 = middle, 2 = right)'),
-});
+const MouseButtonBindingSchema = z
+  .object({
+    type: z.literal('mouse_button').describe('Binding kind: a mouse button'),
+    button: z.number().describe('MouseEvent.button index (0 = left, 1 = middle, 2 = right)'),
+  })
+  .strict();
 
-const MouseMoveBindingSchema = z.object({
-  type: z
-    .literal('mouse_move')
-    .describe(
-      'Binding kind: raw mouse movement (F2, spec §12 "Complete Device Backends"). Feeds a ' +
-        "'pointerDelta'-valueType action with the raw accumulated mouse delta (no deadzone), and " +
-        "can also feed a 'vector2'-valueType action (the same delta, radial-deadzoned + unit-" +
-        'circle-clamped via `deadzone`).',
-    ),
-  deadzone: z
-    .number()
-    .optional()
-    .describe(
-      "Radial deadzone magnitude applied only when this binding feeds a 'vector2'-valueType " +
-        "action (default 0 — no deadzone; ignored for 'pointerDelta' reads, which are never " +
-        'deadzoned).',
-    ),
-});
+const MouseMoveBindingSchema = z
+  .object({
+    type: z
+      .literal('mouse_move')
+      .describe(
+        'Binding kind: raw mouse movement (F2, spec §12 "Complete Device Backends"). Feeds a ' +
+          "'pointerDelta'-valueType action with the raw accumulated mouse delta (no deadzone), and " +
+          "can also feed a 'vector2'-valueType action (the same delta, radial-deadzoned + unit-" +
+          'circle-clamped via `deadzone`).',
+      ),
+    deadzone: z
+      .number()
+      .optional()
+      .describe(
+        "Radial deadzone magnitude applied only when this binding feeds a 'vector2'-valueType " +
+          "action (default 0 — no deadzone; ignored for 'pointerDelta' reads, which are never " +
+          'deadzoned).',
+      ),
+  })
+  .strict();
 
-const GamepadButtonBindingSchema = z.object({
-  type: z.literal('gamepad_button').describe('Binding kind: a gamepad face/shoulder button'),
-  button: z.number().describe('Standard Gamepad API button index'),
-});
+const GamepadButtonBindingSchema = z
+  .object({
+    type: z.literal('gamepad_button').describe('Binding kind: a gamepad face/shoulder button'),
+    button: z.number().describe('Standard Gamepad API button index'),
+  })
+  .strict();
 
-const GamepadAxisBindingSchema = z.object({
-  type: z.literal('gamepad_axis').describe('Binding kind: a single thresholded gamepad axis'),
-  axis: z.number().describe('Standard Gamepad API axis index'),
-  direction: z
-    .enum(['positive', 'negative'])
-    .describe('Which side of the deadzone counts as "pressed"'),
-  deadzone: z.number().optional().describe('Deadzone magnitude (default 0.15 if omitted)'),
-});
+const GamepadAxisBindingSchema = z
+  .object({
+    type: z.literal('gamepad_axis').describe('Binding kind: a single thresholded gamepad axis'),
+    axis: z.number().describe('Standard Gamepad API axis index'),
+    direction: z
+      .enum(['positive', 'negative'])
+      .describe('Which side of the deadzone counts as "pressed"'),
+    deadzone: z.number().optional().describe('Deadzone magnitude (default 0.15 if omitted)'),
+  })
+  .strict();
 
-const GamepadAxisPairBindingSchema = z.object({
-  type: z
-    .literal('gamepad_axis_pair')
-    .describe(
-      'Binding kind: a coupled (x, y) gamepad axis pair, e.g. a stick used as a 2D vector ' +
-        '(look/aim/movement) (F2, spec §12 "Complete Device Backends"). Feeds a ' +
-        "'vector2'-valueType action: (xAxis, yAxis) read together, radial-deadzoned + unit-" +
-        'circle-clamped the same way a real analog stick is.',
-    ),
-  xAxis: z.number().describe('Standard Gamepad API axis index for the X component'),
-  yAxis: z.number().describe('Standard Gamepad API axis index for the Y component'),
-  deadzone: z.number().optional().describe('Deadzone magnitude (default 0.15 if omitted)'),
-});
+const GamepadAxisPairBindingSchema = z
+  .object({
+    type: z
+      .literal('gamepad_axis_pair')
+      .describe(
+        'Binding kind: a coupled (x, y) gamepad axis pair, e.g. a stick used as a 2D vector ' +
+          '(look/aim/movement) (F2, spec §12 "Complete Device Backends"). Feeds a ' +
+          "'vector2'-valueType action: (xAxis, yAxis) read together, radial-deadzoned + unit-" +
+          'circle-clamped the same way a real analog stick is.',
+      ),
+    xAxis: z.number().describe('Standard Gamepad API axis index for the X component'),
+    yAxis: z.number().describe('Standard Gamepad API axis index for the Y component'),
+    deadzone: z.number().optional().describe('Deadzone magnitude (default 0.15 if omitted)'),
+  })
+  .strict();
 
 // ---------------------------------------------------------------------------
 // F1 (spec §12) — injected test input bindings. LIVE (real runtime readers in
@@ -102,78 +114,86 @@ const GamepadAxisPairBindingSchema = z.object({
 // aggregation path these exercise today.
 // ---------------------------------------------------------------------------
 
-const TestAxisBindingSchema = z.object({
-  type: z
-    .literal('test_axis')
-    .describe(
-      "Binding kind: an injected synthetic scalar value for a 'scalar'-valueType action " +
-        '(InputManager.injectAxis/getScalar) — the "injected test input" backend named in F2, ' +
-        "built in F1 as the typed scalar value model's testable source.",
-    ),
-  sourceId: z
-    .string()
-    .describe('Names the injected test source this binding reads (InputManager.injectAxis).'),
-  deadzone: z
-    .number()
-    .optional()
-    .describe(
-      '1D deadzone magnitude applied to the injected raw value before combine (default 0 — no ' +
-        'deadzone). Values below it read as 0; values at/above it rescale from 0 (at the ' +
-        'deadzone edge) to ±1 (at |raw| = 1), sign preserved.',
-    ),
-});
+const TestAxisBindingSchema = z
+  .object({
+    type: z
+      .literal('test_axis')
+      .describe(
+        "Binding kind: an injected synthetic scalar value for a 'scalar'-valueType action " +
+          '(InputManager.injectAxis/getScalar) — the "injected test input" backend named in F2, ' +
+          "built in F1 as the typed scalar value model's testable source.",
+      ),
+    sourceId: z
+      .string()
+      .describe('Names the injected test source this binding reads (InputManager.injectAxis).'),
+    deadzone: z
+      .number()
+      .optional()
+      .describe(
+        '1D deadzone magnitude applied to the injected raw value before combine (default 0 — no ' +
+          'deadzone). Values below it read as 0; values at/above it rescale from 0 (at the ' +
+          'deadzone edge) to ±1 (at |raw| = 1), sign preserved.',
+      ),
+  })
+  .strict();
 
-const TestVector2BindingSchema = z.object({
-  type: z
-    .literal('test_vector2')
-    .describe(
-      "Binding kind: an injected synthetic {x,y} value for a 'vector2'-valueType action " +
-        '(InputManager.injectVector2/getVector2) — the "injected test input" backend named in ' +
-        "F2, built in F1 as the typed Vector2 value model's testable source.",
-    ),
-  sourceId: z
-    .string()
-    .describe('Names the injected test source this binding reads (InputManager.injectVector2).'),
-  deadzone: z
-    .number()
-    .optional()
-    .describe(
-      'Radial deadzone magnitude applied to the injected raw {x,y} before combine (default 0 ' +
-        '— no deadzone). Vectors whose magnitude is below it read as {0,0}; at/above it, ' +
-        'direction is preserved and magnitude rescales the same way the scalar deadzone does, ' +
-        'then the result is clamped to the unit circle (magnitude <= 1).',
-    ),
-});
+const TestVector2BindingSchema = z
+  .object({
+    type: z
+      .literal('test_vector2')
+      .describe(
+        "Binding kind: an injected synthetic {x,y} value for a 'vector2'-valueType action " +
+          '(InputManager.injectVector2/getVector2) — the "injected test input" backend named in ' +
+          "F2, built in F1 as the typed Vector2 value model's testable source.",
+      ),
+    sourceId: z
+      .string()
+      .describe('Names the injected test source this binding reads (InputManager.injectVector2).'),
+    deadzone: z
+      .number()
+      .optional()
+      .describe(
+        'Radial deadzone magnitude applied to the injected raw {x,y} before combine (default 0 ' +
+          '— no deadzone). Vectors whose magnitude is below it read as {0,0}; at/above it, ' +
+          'direction is preserved and magnitude rescales the same way the scalar deadzone does, ' +
+          'then the result is clamped to the unit circle (magnitude <= 1).',
+      ),
+  })
+  .strict();
 
-const TestPointerDeltaBindingSchema = z.object({
-  type: z
-    .literal('test_pointer_delta')
-    .describe(
-      "Binding kind: an injected synthetic per-frame {x,y} delta for a 'pointerDelta'-" +
-        'valueType action (InputManager.injectPointerDelta/getPointerDelta) — the "injected ' +
-        'test input" backend named in F2. No deadzone (deltas are not deadzoned).',
-    ),
-  sourceId: z
-    .string()
-    .describe(
-      'Names the injected test source this binding reads (InputManager.injectPointerDelta).',
-    ),
-});
+const TestPointerDeltaBindingSchema = z
+  .object({
+    type: z
+      .literal('test_pointer_delta')
+      .describe(
+        "Binding kind: an injected synthetic per-frame {x,y} delta for a 'pointerDelta'-" +
+          'valueType action (InputManager.injectPointerDelta/getPointerDelta) — the "injected ' +
+          'test input" backend named in F2. No deadzone (deltas are not deadzoned).',
+      ),
+    sourceId: z
+      .string()
+      .describe(
+        'Names the injected test source this binding reads (InputManager.injectPointerDelta).',
+      ),
+  })
+  .strict();
 
-const TestPointerPositionBindingSchema = z.object({
-  type: z
-    .literal('test_pointer_position')
-    .describe(
-      "Binding kind: an injected synthetic absolute {x,y} position for a 'pointerPosition'-" +
-        'valueType action (InputManager.injectPointerPosition/getPointerPosition) — the ' +
-        '"injected test input" backend named in F2.',
-    ),
-  sourceId: z
-    .string()
-    .describe(
-      'Names the injected test source this binding reads (InputManager.injectPointerPosition).',
-    ),
-});
+const TestPointerPositionBindingSchema = z
+  .object({
+    type: z
+      .literal('test_pointer_position')
+      .describe(
+        "Binding kind: an injected synthetic absolute {x,y} position for a 'pointerPosition'-" +
+          'valueType action (InputManager.injectPointerPosition/getPointerPosition) — the ' +
+          '"injected test input" backend named in F2.',
+      ),
+    sourceId: z
+      .string()
+      .describe(
+        'Names the injected test source this binding reads (InputManager.injectPointerPosition).',
+      ),
+  })
+  .strict();
 
 // ---------------------------------------------------------------------------
 // F2 (spec §12 "Complete Device Backends") — touch/virtual-control bindings.
@@ -185,44 +205,48 @@ const TestPointerPositionBindingSchema = z.object({
 // thin adapter at the edge, out of scope here — see input-manager.ts).
 // ---------------------------------------------------------------------------
 
-const TouchButtonBindingSchema = z.object({
-  type: z
-    .literal('touch_button')
-    .describe(
-      "Binding kind: a virtual on-screen button for a 'digital' action " +
-        '(InputManager.setTouchButton/isPressed) — edge-tracked (isJustPressed/isJustReleased) ' +
-        'the same way a real mouse/keyboard button is.',
-    ),
-  sourceId: z
-    .string()
-    .describe(
-      'Names the virtual control zone this binding reads (InputManager.setTouchButton) — a ' +
-        'touch-UI-chosen id, not a real device index.',
-    ),
-});
+const TouchButtonBindingSchema = z
+  .object({
+    type: z
+      .literal('touch_button')
+      .describe(
+        "Binding kind: a virtual on-screen button for a 'digital' action " +
+          '(InputManager.setTouchButton/isPressed) — edge-tracked (isJustPressed/isJustReleased) ' +
+          'the same way a real mouse/keyboard button is.',
+      ),
+    sourceId: z
+      .string()
+      .describe(
+        'Names the virtual control zone this binding reads (InputManager.setTouchButton) — a ' +
+          'touch-UI-chosen id, not a real device index.',
+      ),
+  })
+  .strict();
 
-const TouchStickBindingSchema = z.object({
-  type: z
-    .literal('touch_stick')
-    .describe(
-      "Binding kind: a virtual on-screen analog stick for a 'vector2' action " +
-        '(InputManager.setTouchStick/getVector2) — radial-deadzoned + unit-circle-clamped the ' +
-        'same way a real gamepad stick is.',
-    ),
-  sourceId: z
-    .string()
-    .describe(
-      'Names the virtual control zone this binding reads (InputManager.setTouchStick) — a ' +
-        'touch-UI-chosen id, not a real device index.',
-    ),
-  deadzone: z
-    .number()
-    .optional()
-    .describe(
-      'Radial deadzone magnitude applied to the raw {x,y} before combine (default 0 — no ' +
-        'deadzone).',
-    ),
-});
+const TouchStickBindingSchema = z
+  .object({
+    type: z
+      .literal('touch_stick')
+      .describe(
+        "Binding kind: a virtual on-screen analog stick for a 'vector2' action " +
+          '(InputManager.setTouchStick/getVector2) — radial-deadzoned + unit-circle-clamped the ' +
+          'same way a real gamepad stick is.',
+      ),
+    sourceId: z
+      .string()
+      .describe(
+        'Names the virtual control zone this binding reads (InputManager.setTouchStick) — a ' +
+          'touch-UI-chosen id, not a real device index.',
+      ),
+    deadzone: z
+      .number()
+      .optional()
+      .describe(
+        'Radial deadzone magnitude applied to the raw {x,y} before combine (default 0 — no ' +
+          'deadzone).',
+      ),
+  })
+  .strict();
 
 /** A single input binding. Every kind listed here is LIVE — F2 (spec §12) closed the last two
  *  dead stubs (`mouse_move`/`gamepad_axis_pair`) by giving both real `InputManager` readers. */
@@ -242,31 +266,33 @@ export const InputBindingSchema: z.ZodType<InputBinding> = z.discriminatedUnion(
 ]) as z.ZodType<InputBinding>;
 
 /** An action has a name (the record key) and one or more bindings. */
-export const InputActionSchema: z.ZodType<InputAction> = z.object({
-  valueType: z
-    .enum(['digital', 'scalar', 'vector2', 'pointerDelta', 'pointerPosition'])
-    .default('digital')
-    .describe(
-      "This action's declared value shape (F1, spec §12). 'digital' (boolean, with " +
-        'pressed/justPressed/justReleased edges) is the default when omitted, matching every ' +
-        "action authored before F1. 'scalar' is a single deadzone-rescaled float axis. " +
-        "'vector2' is a radial-deadzoned, unit-circle-normalized {x,y}. 'pointerDelta' is a " +
-        "per-frame {x,y} movement delta, summed across sources. 'pointerPosition' is an " +
-        'absolute {x,y}, last-write-wins across sources. InputManager enforces this at read ' +
-        'time: reading an action through the wrong typed getter (e.g. getScalar on a ' +
-        "'digital' action) throws.",
-    ),
-  bindings: z
-    .array(InputBindingSchema)
-    .describe(
-      'Bindings that all trigger/feed this action. Digital actions combine via OR (any one ' +
-        'binding satisfied is enough). Scalar actions combine via max-magnitude across ' +
-        'contributing bindings (ties keep the first-listed binding). Vector2 actions combine ' +
-        'by summing contributing {x,y} values then clamping to the unit circle. PointerDelta ' +
-        'actions sum contributing deltas. PointerPosition actions use the most-recently-' +
-        'written contributing source (last-write-wins).',
-    ),
-});
+export const InputActionSchema: z.ZodType<InputAction> = z
+  .object({
+    valueType: z
+      .enum(['digital', 'scalar', 'vector2', 'pointerDelta', 'pointerPosition'])
+      .default('digital')
+      .describe(
+        "This action's declared value shape (F1, spec §12). 'digital' (boolean, with " +
+          'pressed/justPressed/justReleased edges) is the default when omitted, matching every ' +
+          "action authored before F1. 'scalar' is a single deadzone-rescaled float axis. " +
+          "'vector2' is a radial-deadzoned, unit-circle-normalized {x,y}. 'pointerDelta' is a " +
+          "per-frame {x,y} movement delta, summed across sources. 'pointerPosition' is an " +
+          'absolute {x,y}, last-write-wins across sources. InputManager enforces this at read ' +
+          'time: reading an action through the wrong typed getter (e.g. getScalar on a ' +
+          "'digital' action) throws.",
+      ),
+    bindings: z
+      .array(InputBindingSchema)
+      .describe(
+        'Bindings that all trigger/feed this action. Digital actions combine via OR (any one ' +
+          'binding satisfied is enough). Scalar actions combine via max-magnitude across ' +
+          'contributing bindings (ties keep the first-listed binding). Vector2 actions combine ' +
+          'by summing contributing {x,y} values then clamping to the unit circle. PointerDelta ' +
+          'actions sum contributing deltas. PointerPosition actions use the most-recently-' +
+          'written contributing source (last-write-wins).',
+      ),
+  })
+  .strict();
 
 /**
  * The `.inputmap.json` file format (`InputManager.loadMap`).
@@ -275,9 +301,11 @@ export const InputActionSchema: z.ZodType<InputAction> = z.object({
  * same convention `2d.version`/`Scene2DSchema` used before T2.3 gave the 3D
  * scene version axis a real reader; see `schema-consumption-map.ts`).
  */
-export const InputMapFileSchema: z.ZodType<InputMapFile> = z.object({
-  version: z.number().describe('Input map file format version (RESERVED — no range check yet)'),
-  actions: z
-    .record(z.string(), InputActionSchema)
-    .describe('Named actions, each with a list of bindings (InputManager.loadMap)'),
-}) as z.ZodType<InputMapFile>;
+export const InputMapFileSchema: z.ZodType<InputMapFile> = z
+  .object({
+    version: z.number().describe('Input map file format version (RESERVED — no range check yet)'),
+    actions: z
+      .record(z.string(), InputActionSchema)
+      .describe('Named actions, each with a list of bindings (InputManager.loadMap)'),
+  })
+  .strict() as z.ZodType<InputMapFile>;