@aura3d/input 1.0.6

package/src/GamepadDevice.ts

@@ -0,0 +1,48 @@
+import type { ButtonState, GamepadSnapshot } from "./InputSnapshot";
+
+export interface GamepadButtonLike {
+  readonly pressed: boolean;
+  readonly value: number;
+}
+
+export interface GamepadLike {
+  readonly id: string;
+  readonly index: number;
+  readonly connected: boolean;
+  readonly axes: readonly number[];
+  readonly buttons: readonly GamepadButtonLike[];
+}
+
+export class GamepadDevice {
+  private previousButtons = new Map<string, readonly boolean[]>();
+
+  poll(gamepads: readonly (GamepadLike | null | undefined)[], deadZone = 0.1): readonly GamepadSnapshot[] {
+    const snapshots: GamepadSnapshot[] = [];
+
+    for (const gamepad of gamepads) {
+      if (!gamepad?.connected) {
+        continue;
+      }
+
+      const key = `${gamepad.index}:${gamepad.id}`;
+      const previous = this.previousButtons.get(key) ?? [];
+      const buttons: ButtonState[] = gamepad.buttons.map((button, index) => {
+        const down = button.pressed || button.value > 0.5;
+        const wasDown = previous[index] ?? false;
+        return Object.freeze({ down, pressed: down && !wasDown, released: !down && wasDown });
+      });
+
+      snapshots.push(
+        Object.freeze({
+          id: gamepad.id,
+          index: gamepad.index,
+          axes: Object.freeze(gamepad.axes.map((axis) => (Math.abs(axis) < deadZone ? 0 : axis))),
+          buttons: Object.freeze(buttons)
+        })
+      );
+      this.previousButtons.set(key, buttons.map((button) => button.down));
+    }
+
+    return snapshots;
+  }
+}

package/src/GamepadInput.ts

@@ -0,0 +1,2 @@
+export { GamepadDevice as GamepadInput } from "./GamepadDevice";
+export type { GamepadButtonLike, GamepadLike } from "./GamepadDevice";

package/src/GestureControls.ts

@@ -0,0 +1,2 @@
+export { GestureRecognizer as GestureControls } from "./GestureRecognizer";
+export type { Gesture } from "./GestureRecognizer";

package/src/GestureHapticsFixtures.ts

@@ -0,0 +1,179 @@
+export type GestureHapticsGestureType = "tap" | "pan" | "pinch" | "swipe" | "rotate";
+export type GestureHapticsPatternName = "tap" | "impact" | "damage" | "success" | "engine";
+
+export interface GestureHapticsFixtureOptions {
+  readonly seed?: number;
+  readonly pointerDeltaX?: number;
+  readonly pointerDeltaY?: number;
+  readonly pinchStartDistance?: number;
+  readonly pinchEndDistance?: number;
+  readonly rotateDegrees?: number;
+  readonly gamepadConnected?: boolean;
+}
+
+export interface GestureHapticsFixture {
+  readonly source: "origin-master-input-gesture-rumble-adapted";
+  readonly gestures: readonly {
+    readonly type: GestureHapticsGestureType;
+    readonly state: "possible" | "began" | "changed" | "ended";
+    readonly touchCount: number;
+    readonly center: readonly [number, number];
+    readonly distance?: number;
+    readonly velocity?: readonly [number, number];
+    readonly scale?: number;
+    readonly rotationDegrees?: number;
+  }[];
+  readonly gestureSummary: {
+    readonly tapDetected: boolean;
+    readonly panDistance: number;
+    readonly pinchScale: number;
+    readonly swipeDirection: "left" | "right" | "up" | "down";
+    readonly rotateDegrees: number;
+  };
+  readonly haptics: {
+    readonly gamepadConnected: boolean;
+    readonly hapticsClaimed: false;
+    readonly patterns: readonly {
+      readonly name: GestureHapticsPatternName;
+      readonly steps: number;
+      readonly totalDurationMs: number;
+      readonly peakWeak: number;
+      readonly peakStrong: number;
+      readonly loop: boolean;
+    }[];
+    readonly queuedPatterns: number;
+    readonly totalDurationMs: number;
+    readonly intensityMultiplier: number;
+  };
+  readonly productionReadiness: {
+    readonly gestureTelemetry: true;
+    readonly swipeRotateTelemetry: true;
+    readonly hapticPatternTelemetry: true;
+    readonly hapticClaimBoundaryTelemetry: true;
+  };
+  readonly blockedClaims: readonly string[];
+  readonly claimBoundary: string;
+  readonly hash: string;
+}
+
+export function sampleGestureHapticsFixture(options: GestureHapticsFixtureOptions = {}): GestureHapticsFixture {
+  const seed = normalizeSeed(options.seed ?? 0x9e57);
+  const pointerDeltaX = finite(options.pointerDeltaX ?? 84, "pointerDeltaX");
+  const pointerDeltaY = finite(options.pointerDeltaY ?? 18, "pointerDeltaY");
+  const pinchStartDistance = positive(options.pinchStartDistance ?? 42, "pinchStartDistance");
+  const pinchEndDistance = positive(options.pinchEndDistance ?? 76, "pinchEndDistance");
+  const rotateDegrees = finite(options.rotateDegrees ?? 28, "rotateDegrees");
+  const panDistance = Number(Math.hypot(pointerDeltaX, pointerDeltaY).toFixed(3));
+  const pinchScale = Number((pinchEndDistance / pinchStartDistance).toFixed(3));
+  const swipeDirection = Math.abs(pointerDeltaX) >= Math.abs(pointerDeltaY)
+    ? pointerDeltaX >= 0 ? "right" : "left"
+    : pointerDeltaY >= 0 ? "down" : "up";
+  const patterns = [
+    hapticPattern("tap", [{ weak: 0.3, strong: 0.2, duration: 50 }], false),
+    hapticPattern("impact", [{ weak: 0.7, strong: 0.8, duration: 100 }], false),
+    hapticPattern("damage", [
+      { weak: 0.8, strong: 0.9, duration: 80 },
+      { weak: 0, strong: 0, duration: 40 },
+      { weak: 0.6, strong: 0.7, duration: 60 }
+    ], false),
+    hapticPattern("success", [
+      { weak: 0.3, strong: 0.3, duration: 80 },
+      { weak: 0, strong: 0, duration: 50 },
+      { weak: 0.4, strong: 0.4, duration: 100 }
+    ], false),
+    hapticPattern("engine", [
+      { weak: 0.3, strong: 0.2, duration: 50 },
+      { weak: 0.35, strong: 0.25, duration: 50 }
+    ], true)
+  ] as const;
+  const fixture: Omit<GestureHapticsFixture, "hash"> = {
+    source: "origin-master-input-gesture-rumble-adapted",
+    gestures: [
+      { type: "tap", state: "ended", touchCount: 1, center: [16, 22] },
+      { type: "pan", state: "changed", touchCount: 1, center: [42, 38], distance: panDistance, velocity: [pointerDeltaX, pointerDeltaY] },
+      { type: "pinch", state: "changed", touchCount: 2, center: [64, 64], distance: pinchEndDistance, scale: pinchScale },
+      { type: "swipe", state: "ended", touchCount: 1, center: [120, 64], distance: panDistance, velocity: [pointerDeltaX * 8, pointerDeltaY * 8] },
+      { type: "rotate", state: "changed", touchCount: 2, center: [64, 64], rotationDegrees: Number(rotateDegrees.toFixed(3)) }
+    ],
+    gestureSummary: {
+      tapDetected: true,
+      panDistance,
+      pinchScale,
+      swipeDirection,
+      rotateDegrees: Number(rotateDegrees.toFixed(3))
+    },
+    haptics: {
+      gamepadConnected: options.gamepadConnected ?? true,
+      hapticsClaimed: false,
+      patterns,
+      queuedPatterns: 3 + Math.floor(seededUnit(seed) * 2),
+      totalDurationMs: patterns.reduce((sum, pattern) => sum + pattern.totalDurationMs, 0),
+      intensityMultiplier: Number((0.65 + seededUnit(seed ^ 0x54c) * 0.25).toFixed(3))
+    },
+    productionReadiness: {
+      gestureTelemetry: true,
+      swipeRotateTelemetry: true,
+      hapticPatternTelemetry: true,
+      hapticClaimBoundaryTelemetry: true
+    },
+    blockedClaims: [
+      "native mobile gesture recognizer parity",
+      "gamepad haptic actuator delivery guarantee",
+      "platform vibration permission handling",
+      "Unity Input System haptics parity",
+      "Unreal Enhanced Input haptics parity"
+    ],
+    claimBoundary: "This fixture ports old swipe/rotate gesture and rumble-pattern concepts into deterministic local input telemetry. It does not vibrate hardware, guarantee platform haptic delivery, or claim Unity Input System or Unreal Enhanced Input parity."
+  };
+  return {
+    ...fixture,
+    hash: stableHash(JSON.stringify(fixture))
+  };
+}
+
+function hapticPattern(
+  name: GestureHapticsPatternName,
+  steps: readonly { readonly weak: number; readonly strong: number; readonly duration: number }[],
+  loop: boolean
+): GestureHapticsFixture["haptics"]["patterns"][number] {
+  return {
+    name,
+    steps: steps.length,
+    totalDurationMs: steps.reduce((sum, step) => sum + step.duration, 0),
+    peakWeak: Math.max(...steps.map((step) => step.weak)),
+    peakStrong: Math.max(...steps.map((step) => step.strong)),
+    loop
+  };
+}
+
+function normalizeSeed(seed: number): number {
+  if (!Number.isInteger(seed) || seed < 0) throw new Error("seed must be a non-negative integer.");
+  return seed >>> 0;
+}
+
+function finite(value: number, name: string): number {
+  if (!Number.isFinite(value)) throw new Error(`${name} must be finite.`);
+  return value;
+}
+
+function positive(value: number, name: string): number {
+  if (!Number.isFinite(value) || value <= 0) throw new Error(`${name} must be positive.`);
+  return value;
+}
+
+function seededUnit(seed: number): number {
+  let value = seed >>> 0;
+  value ^= value << 13;
+  value ^= value >>> 17;
+  value ^= value << 5;
+  return (value >>> 0) / 0xffffffff;
+}
+
+function stableHash(value: string): string {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}

package/src/GestureRecognizer.ts

@@ -0,0 +1,43 @@
+import type { InputSnapshot, PointerTouch } from "./InputSnapshot";
+
+export type Gesture =
+  | { readonly type: "tap"; readonly x: number; readonly y: number }
+  | { readonly type: "pan"; readonly deltaX: number; readonly deltaY: number }
+  | { readonly type: "pinch"; readonly scale: number };
+
+export class GestureRecognizer {
+  private previousTouches: readonly PointerTouch[] = [];
+  private downFrames = 0;
+
+  update(snapshot: InputSnapshot): readonly Gesture[] {
+    const gestures: Gesture[] = [];
+    const touches = snapshot.pointer.touches;
+
+    if (snapshot.button(0).down) {
+      this.downFrames += 1;
+      if (snapshot.pointer.deltaX !== 0 || snapshot.pointer.deltaY !== 0) {
+        gestures.push({ type: "pan", deltaX: snapshot.pointer.deltaX, deltaY: snapshot.pointer.deltaY });
+      }
+    }
+
+    if (snapshot.button(0).released && this.downFrames <= 12) {
+      gestures.push({ type: "tap", x: snapshot.pointer.x, y: snapshot.pointer.y });
+    }
+
+    if (touches.length >= 2 && this.previousTouches.length >= 2) {
+      const previousDistance = distance(this.previousTouches[0]!, this.previousTouches[1]!);
+      const currentDistance = distance(touches[0]!, touches[1]!);
+      if (previousDistance > 0) gestures.push({ type: "pinch", scale: currentDistance / previousDistance });
+    }
+
+    if (!snapshot.button(0).down) {
+      this.downFrames = 0;
+    }
+    this.previousTouches = touches;
+    return gestures;
+  }
+}
+
+function distance(a: PointerTouch, b: PointerTouch): number {
+  return Math.hypot(a.x - b.x, a.y - b.y);
+}

package/src/InputActionBindingFixtures.ts

@@ -0,0 +1,121 @@
+import { InputSnapshot } from "./InputSnapshot";
+
+export type InputValueProcessor =
+  | { readonly type: "deadzone"; readonly threshold: number }
+  | { readonly type: "scale"; readonly factor: number }
+  | { readonly type: "invert" }
+  | { readonly type: "clamp"; readonly min: number; readonly max: number }
+  | { readonly type: "exponential"; readonly exponent: number };
+
+export interface InputActionBindingFixture {
+  readonly source: "origin-master-input-action-binding-adapted";
+  readonly evidence: {
+    readonly oldCodebasePort: true;
+    readonly actionBindings: true;
+    readonly processors: true;
+    readonly holdTapDoubleTap: true;
+    readonly compositeAxis: true;
+    readonly modifierChord: true;
+  };
+  readonly actionCount: number;
+  readonly bindingCount: number;
+  readonly processorCount: number;
+  readonly processedAxis: number;
+  readonly deadzoneFilteredAxis: number;
+  readonly compositeX: number;
+  readonly compositeY: number;
+  readonly compositeMagnitude: number;
+  readonly holdTriggered: boolean;
+  readonly holdDurationSeconds: number;
+  readonly tapTriggered: boolean;
+  readonly doubleTapTriggered: boolean;
+  readonly modifierChordPressed: boolean;
+  readonly claimBoundary: string;
+}
+
+export function processInputValue(value: number, processors: readonly InputValueProcessor[], deltaSeconds = 1 / 60): number {
+  let result = finite(value, 0);
+  for (const processor of processors) {
+    if (processor.type === "deadzone") {
+      result = Math.abs(result) < Math.max(0, processor.threshold) ? 0 : result;
+    } else if (processor.type === "scale") {
+      result *= finite(processor.factor, 1);
+    } else if (processor.type === "invert") {
+      result *= -1;
+    } else if (processor.type === "clamp") {
+      result = clamp(result, processor.min, processor.max);
+    } else {
+      const sign = Math.sign(result);
+      result = sign * Math.pow(Math.abs(result), Math.max(0.01, finite(processor.exponent, 1))) * Math.max(0.001, deltaSeconds / (1 / 60));
+    }
+  }
+  return Number(result.toFixed(4));
+}
+
+export function sampleInputActionBindingFixture(): InputActionBindingFixture {
+  const activeSnapshot = new InputSnapshot({
+    keys: new Set(["ControlLeft", "KeyW", "KeyD"]),
+    previousKeys: new Set(["ControlLeft", "KeyW"]),
+    gamepads: [{
+      id: "fixture-pad",
+      index: 0,
+      axes: [0.42, -0.74],
+      buttons: [{ down: true, pressed: true, released: false }]
+    }]
+  });
+  const processedAxis = processInputValue(activeSnapshot.gamepads[0]?.axes[0] ?? 0, [
+    { type: "deadzone", threshold: 0.2 },
+    { type: "scale", factor: 1.8 },
+    { type: "clamp", min: -1, max: 1 }
+  ]);
+  const deadzoneFilteredAxis = processInputValue(0.08, [{ type: "deadzone", threshold: 0.2 }]);
+  const compositeX = (activeSnapshot.key("KeyD").down ? 1 : 0) - (activeSnapshot.key("KeyA").down ? 1 : 0);
+  const compositeY = (activeSnapshot.key("KeyW").down ? 1 : 0) - (activeSnapshot.key("KeyS").down ? 1 : 0);
+  const holdDurationSeconds = Number((5 * 0.12).toFixed(2));
+  const tapTriggered = evaluateTap(1.2, 1.34, 0.2);
+  const doubleTapTriggered = evaluateDoubleTap([1.2, 1.34], 0.25);
+  const modifierChordPressed = activeSnapshot.key("ControlLeft").down && activeSnapshot.key("KeyD").pressed;
+
+  return {
+    source: "origin-master-input-action-binding-adapted",
+    evidence: {
+      oldCodebasePort: true,
+      actionBindings: true,
+      processors: true,
+      holdTapDoubleTap: true,
+      compositeAxis: true,
+      modifierChord: true
+    },
+    actionCount: 4,
+    bindingCount: 8,
+    processorCount: 3,
+    processedAxis,
+    deadzoneFilteredAxis,
+    compositeX,
+    compositeY,
+    compositeMagnitude: Number(Math.hypot(compositeX, compositeY).toFixed(4)),
+    holdTriggered: holdDurationSeconds >= 0.5,
+    holdDurationSeconds,
+    tapTriggered,
+    doubleTapTriggered,
+    modifierChordPressed,
+    claimBoundary: "Bounded deterministic current-input evidence for old InputAction/InputBinding processors and interactions; this does not claim full input action asset, rebinding UI, or Unity Input System parity."
+  };
+}
+
+function evaluateTap(pressedAtSeconds: number, releasedAtSeconds: number, tapSpeedSeconds: number): boolean {
+  return releasedAtSeconds >= pressedAtSeconds && releasedAtSeconds - pressedAtSeconds <= tapSpeedSeconds;
+}
+
+function evaluateDoubleTap(pressTimesSeconds: readonly number[], maxIntervalSeconds: number): boolean {
+  return pressTimesSeconds.length >= 2 && (pressTimesSeconds.at(-1) ?? 0) - (pressTimesSeconds.at(-2) ?? 0) <= maxIntervalSeconds;
+}
+
+function finite(value: unknown, fallback: number): number {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : fallback;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}

package/src/InputReplay.ts

@@ -0,0 +1,275 @@
+export type InputReplayEventType =
+  | "key"
+  | "pointer-button"
+  | "pointer-move"
+  | "pointer-wheel"
+  | "gamepad-axis"
+  | "gamepad-button"
+  | "action"
+  | "frame";
+
+export interface InputReplayEvent {
+  readonly type: InputReplayEventType;
+  readonly timestampMs: number;
+  readonly frame: number;
+  readonly code?: string;
+  readonly down?: boolean;
+  readonly button?: number;
+  readonly x?: number;
+  readonly y?: number;
+  readonly deltaX?: number;
+  readonly deltaY?: number;
+  readonly gamepadIndex?: number;
+  readonly controlIndex?: number;
+  readonly action?: string;
+  readonly context?: string;
+  readonly value?: number;
+  readonly vector?: readonly [number, number];
+  readonly deltaTimeMs?: number;
+}
+
+export interface InputRecordingMetadata {
+  readonly version: "1.0.0";
+  readonly source: "origin-master-input-recorder-playback-adapted";
+  readonly startTimeMs: number;
+  readonly endTimeMs: number;
+  readonly durationMs: number;
+  readonly frameCount: number;
+  readonly eventCount: number;
+  readonly evidence: {
+    readonly oldCodebasePort: true;
+    readonly recording: boolean;
+    readonly playback: boolean;
+    readonly seek: boolean;
+    readonly looping: boolean;
+  };
+}
+
+export interface InputRecording {
+  readonly metadata: InputRecordingMetadata;
+  readonly events: readonly InputReplayEvent[];
+}
+
+export interface InputPlaybackOptions {
+  readonly speed?: number;
+  readonly loop?: boolean;
+}
+
+export interface InputPlaybackSnapshot {
+  readonly state: "stopped" | "playing" | "paused";
+  readonly currentTimeMs: number;
+  readonly emittedEvents: number;
+  readonly loopCount: number;
+  readonly recordingEventCount: number;
+  readonly evidence: InputRecordingMetadata["evidence"];
+}
+
+export class InputRecorder {
+  private readonly events: InputReplayEvent[] = [];
+  private readonly maxEvents: number;
+  private recording = false;
+  private startTimeMs = 0;
+  private lastTimestampMs = 0;
+  private frame = 0;
+
+  constructor(options: { readonly maxEvents?: number } = {}) {
+    this.maxEvents = options.maxEvents ?? 4096;
+  }
+
+  start(startTimeMs = 0): void {
+    this.events.length = 0;
+    this.recording = true;
+    this.startTimeMs = finite(startTimeMs, 0);
+    this.lastTimestampMs = this.startTimeMs;
+    this.frame = 0;
+  }
+
+  stop(endTimeMs = this.lastTimestampMs): InputRecording {
+    this.recording = false;
+    this.lastTimestampMs = Math.max(this.startTimeMs, finite(endTimeMs, this.lastTimestampMs));
+    return this.recordingSnapshot();
+  }
+
+  recordFrame(deltaTimeMs: number, timestampMs = this.lastTimestampMs + deltaTimeMs): void {
+    this.push({
+      type: "frame",
+      timestampMs: finite(timestampMs, this.lastTimestampMs),
+      frame: this.frame,
+      deltaTimeMs: Math.max(0, finite(deltaTimeMs, 0))
+    });
+    this.frame += 1;
+  }
+
+  recordKey(code: string, down: boolean, timestampMs = this.lastTimestampMs): void {
+    this.push({ type: "key", timestampMs: finite(timestampMs, this.lastTimestampMs), frame: this.frame, code, down });
+  }
+
+  recordPointerButton(button: number, down: boolean, x: number, y: number, timestampMs = this.lastTimestampMs): void {
+    this.push({ type: "pointer-button", timestampMs: finite(timestampMs, this.lastTimestampMs), frame: this.frame, button, down, x, y });
+  }
+
+  recordPointerMove(x: number, y: number, deltaX: number, deltaY: number, timestampMs = this.lastTimestampMs): void {
+    this.push({ type: "pointer-move", timestampMs: finite(timestampMs, this.lastTimestampMs), frame: this.frame, x, y, deltaX, deltaY });
+  }
+
+  recordPointerWheel(deltaX: number, deltaY: number, timestampMs = this.lastTimestampMs): void {
+    this.push({ type: "pointer-wheel", timestampMs: finite(timestampMs, this.lastTimestampMs), frame: this.frame, deltaX, deltaY });
+  }
+
+  recordGamepadAxis(gamepadIndex: number, controlIndex: number, value: number, timestampMs = this.lastTimestampMs): void {
+    this.push({ type: "gamepad-axis", timestampMs: finite(timestampMs, this.lastTimestampMs), frame: this.frame, gamepadIndex, controlIndex, value });
+  }
+
+  recordGamepadButton(gamepadIndex: number, controlIndex: number, down: boolean, value: number, timestampMs = this.lastTimestampMs): void {
+    this.push({ type: "gamepad-button", timestampMs: finite(timestampMs, this.lastTimestampMs), frame: this.frame, gamepadIndex, controlIndex, down, value });
+  }
+
+  recordAction(context: string, action: string, value: number, vector?: readonly [number, number], timestampMs = this.lastTimestampMs): void {
+    this.push({ type: "action", timestampMs: finite(timestampMs, this.lastTimestampMs), frame: this.frame, context, action, value, vector });
+  }
+
+  recordingSnapshot(): InputRecording {
+    const endTimeMs = Math.max(this.lastTimestampMs, this.events.at(-1)?.timestampMs ?? this.startTimeMs);
+    return Object.freeze({
+      metadata: Object.freeze({
+        version: "1.0.0" as const,
+        source: "origin-master-input-recorder-playback-adapted" as const,
+        startTimeMs: this.startTimeMs,
+        endTimeMs,
+        durationMs: Math.max(0, endTimeMs - this.startTimeMs),
+        frameCount: this.frame,
+        eventCount: this.events.length,
+        evidence: replayEvidence()
+      }),
+      events: Object.freeze([...this.events])
+    });
+  }
+
+  toJSON(): string {
+    return JSON.stringify(this.recordingSnapshot());
+  }
+
+  private push(event: InputReplayEvent): void {
+    if (!this.recording) throw new Error("InputRecorder must be started before recording events.");
+    if (this.events.length >= this.maxEvents) throw new Error(`InputRecorder exceeded maxEvents=${this.maxEvents}.`);
+    this.lastTimestampMs = Math.max(this.lastTimestampMs, event.timestampMs);
+    this.events.push(Object.freeze({ ...event, timestampMs: this.lastTimestampMs }));
+  }
+}
+
+export class InputPlayback {
+  private recording: InputRecording | undefined;
+  private state: InputPlaybackSnapshot["state"] = "stopped";
+  private currentTimeMs = 0;
+  private eventIndex = 0;
+  private emittedEvents = 0;
+  private loopCount = 0;
+  private speed: number;
+  private loop: boolean;
+
+  constructor(options: InputPlaybackOptions = {}) {
+    this.speed = Math.max(0.01, finite(options.speed, 1));
+    this.loop = options.loop ?? false;
+  }
+
+  load(recording: InputRecording): void {
+    this.recording = normalizeRecording(recording);
+    this.stop();
+  }
+
+  play(): void {
+    if (!this.recording) throw new Error("InputPlayback requires a recording before play().");
+    this.state = "playing";
+  }
+
+  pause(): void {
+    if (this.state === "playing") this.state = "paused";
+  }
+
+  stop(): void {
+    this.state = "stopped";
+    this.currentTimeMs = 0;
+    this.eventIndex = 0;
+  }
+
+  seek(timeMs: number): void {
+    const recording = this.requireRecording();
+    this.currentTimeMs = clamp(finite(timeMs, 0), 0, recording.metadata.durationMs);
+    this.eventIndex = recording.events.findIndex((event) => event.timestampMs >= recording.metadata.startTimeMs + this.currentTimeMs);
+    if (this.eventIndex < 0) this.eventIndex = recording.events.length;
+  }
+
+  update(deltaTimeMs: number): readonly InputReplayEvent[] {
+    if (this.state !== "playing") return [];
+    const recording = this.requireRecording();
+    this.currentTimeMs += Math.max(0, finite(deltaTimeMs, 0)) * this.speed;
+    const absoluteTime = recording.metadata.startTimeMs + this.currentTimeMs;
+    const emitted: InputReplayEvent[] = [];
+    while (this.eventIndex < recording.events.length && (recording.events[this.eventIndex]?.timestampMs ?? Infinity) <= absoluteTime) {
+      emitted.push(recording.events[this.eventIndex]!);
+      this.eventIndex += 1;
+    }
+    if (this.currentTimeMs >= recording.metadata.durationMs) {
+      if (this.loop && recording.metadata.durationMs > 0) {
+        this.loopCount += 1;
+        this.currentTimeMs %= recording.metadata.durationMs;
+        this.eventIndex = 0;
+      } else {
+        this.state = "stopped";
+        this.currentTimeMs = recording.metadata.durationMs;
+      }
+    }
+    this.emittedEvents += emitted.length;
+    return Object.freeze(emitted);
+  }
+
+  snapshot(): InputPlaybackSnapshot {
+    return Object.freeze({
+      state: this.state,
+      currentTimeMs: Number(this.currentTimeMs.toFixed(3)),
+      emittedEvents: this.emittedEvents,
+      loopCount: this.loopCount,
+      recordingEventCount: this.recording?.metadata.eventCount ?? 0,
+      evidence: replayEvidence()
+    });
+  }
+
+  private requireRecording(): InputRecording {
+    if (!this.recording) throw new Error("InputPlayback has no loaded recording.");
+    return this.recording;
+  }
+}
+
+export function parseInputRecording(json: string): InputRecording {
+  return normalizeRecording(JSON.parse(json) as InputRecording);
+}
+
+function normalizeRecording(recording: InputRecording): InputRecording {
+  const events = [...recording.events].sort((left, right) => left.timestampMs - right.timestampMs || left.frame - right.frame);
+  return Object.freeze({
+    metadata: Object.freeze({
+      ...recording.metadata,
+      evidence: replayEvidence()
+    }),
+    events: Object.freeze(events.map((event) => Object.freeze({ ...event })))
+  });
+}
+
+function replayEvidence(): InputRecordingMetadata["evidence"] {
+  return {
+    oldCodebasePort: true,
+    recording: true,
+    playback: true,
+    seek: true,
+    looping: true
+  };
+}
+
+function finite(value: unknown, fallback: number): number {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : fallback;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}