@diffenderfer-games/hub 0.0.0-stage → 2.0.0-next.1

package/src/doctor/checks.ts

@@ -0,0 +1,78 @@
+/**
+ * The checks `hub-doctor` runs on a game (plan §4.3.7). Each returns
+ * findings; an `error` finding fails the run (and the game's CI).
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { GamePackageJson, type HubVersion } from '@diffenderfer-games/hub-contract';
+import { clientSupport } from '../core/version/hub-version';
+import { isHubUnreachable, type HubUnreachable } from './hub-version-fetch';
+
+/** How serious a finding is: `error` fails the run, `warning` and `info` only report. */
+export type FindingLevel = 'error' | 'warning' | 'info';
+
+/** One thing the doctor found. */
+export interface Finding {
+  /** How serious it is. */
+  readonly level: FindingLevel;
+  /** Which check found it: `version`, `vendored` or `manifest`. */
+  readonly check: 'version' | 'vendored' | 'manifest';
+  /** What to tell the developer, with the fix. */
+  readonly message: string;
+}
+
+/** The fix for an old or unsupported client. */
+const UPDATE_FIX = 'run `npm update @diffenderfer-games/hub`';
+
+/**
+ * The installed client against the hub's `/_api/version`: outside
+ * `supported` is an error, `deprecated` a warning, `null` (a hub from before
+ * versioning) is only reported. An unreachable or slow hub is an error, so a
+ * game's CI notices (`--offline` skips the check).
+ */
+export function checkClientVersion(installedVersion: string, hubVersion: HubVersion | null | HubUnreachable): Finding[] {
+  if (isHubUnreachable(hubVersion)) {
+    return [{ level: 'error', check: 'version', message: `hub unreachable at ${hubVersion.unreachableUrl} (${hubVersion.reason}); check --hub, or pass --offline to skip the version check` }];
+  }
+  switch (clientSupport(hubVersion, installedVersion)) {
+    case 'unsupported':
+      return [{ level: 'error', check: 'version', message: `@diffenderfer-games/hub ${installedVersion} is not supported by the hub (supported: ${hubVersion?.supported ?? '?'}): ${UPDATE_FIX}` }];
+    case 'deprecated':
+      return [{ level: 'warning', check: 'version', message: `@diffenderfer-games/hub ${installedVersion} is deprecated (deprecated: ${hubVersion?.deprecated ?? '?'}): ${UPDATE_FIX}` }];
+    case 'unknown':
+      return [{ level: 'info', check: 'version', message: 'the hub predates versioning (no /_api/version); the client version was not checked' }];
+    case 'supported':
+      return [{ level: 'info', check: 'version', message: `@diffenderfer-games/hub ${installedVersion} is supported (hub ${hubVersion?.server ?? '?'})` }];
+  }
+}
+
+/** Leftovers of the v1 vendored client, relative to the game's folder. */
+const VENDORED_LEFTOVERS = [
+  'src/hub/hub.ts',
+  'src/hub/input.ts',
+  'client/src/hub/hub.ts',
+  'scripts/sync-hub.mjs',
+] as const;
+
+/** A stale vendored `src/hub/` copy or its sync script (the package replaces both). */
+export function checkVendoredCopies(gameDir: string): Finding[] {
+  return VENDORED_LEFTOVERS.filter((leftover) => existsSync(join(gameDir, leftover))).map((leftover) => ({
+    level: 'warning',
+    check: 'vendored',
+    message: `${leftover} is a vendored copy of the v1 client: import from '@diffenderfer-games/hub' instead and delete it`,
+  }));
+}
+
+/** The `package.json` `game.*` block against the contract's manifest schema. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the game's package.json, parsed by GamePackageJson next
+export function checkManifest(packageJson: unknown): Finding[] {
+  const parsed = GamePackageJson.safeParse(packageJson);
+  if (parsed.success) {
+    return [{ level: 'info', check: 'manifest', message: `the game.* block is valid (${parsed.data.game.type})` }];
+  }
+  return parsed.error.issues.map((issue) => ({
+    level: 'error',
+    check: 'manifest',
+    message: `${issue.path.length === 0 ? '(package.json)' : issue.path.join('.')}: ${issue.message}`,
+  }));
+}

package/src/doctor/cli.ts

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * `hub-doctor`: checks a game against the hub (plan §4.3.7). Run it in a
+ * game's folder, in CI and before pushing:
+ *
+ * ```sh
+ * npx hub-doctor [--dir <game folder>] [--hub <url>] [--timeout <ms>] [--offline] [--json]
+ * ```
+ *
+ * - the installed `@diffenderfer-games/hub` against the hub's
+ *   `/_api/version` (`--hub`, default `https://diffenderfer.games`): outside
+ *   `supported` fails, `deprecated` warns (`--offline` skips this check);
+ * - a stale vendored `src/hub/` copy or `scripts/sync-hub.mjs` warns;
+ * - the `package.json` `game.*` block must match the contract's schema.
+ *
+ * Exits 1 when any check fails.
+ */
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { HUB_CLIENT_VERSION } from '../core/version/client-version.gen';
+import { checkClientVersion, checkManifest, checkVendoredCopies, type Finding } from './checks';
+import { DEFAULT_HUB_TIMEOUT_MS, fetchHubVersion } from './hub-version-fetch';
+
+const DEFAULT_HUB_URL = 'https://diffenderfer.games';
+
+/** The command line, parsed. */
+interface DoctorOptions {
+  readonly gameDir: string;
+  readonly hubUrl: string;
+  /** How long to wait for the hub, ms (`--timeout`). */
+  readonly timeoutMs: number;
+  readonly isOffline: boolean;
+  readonly isJson: boolean;
+}
+
+function readOptions(): DoctorOptions {
+  const { values } = parseArgs({
+    options: {
+      dir: { type: 'string' },
+      hub: { type: 'string' },
+      timeout: { type: 'string' },
+      offline: { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+    },
+  });
+  const timeoutMs = values.timeout === undefined ? DEFAULT_HUB_TIMEOUT_MS : Number(values.timeout);
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    process.stderr.write('hub-doctor: --timeout must be a positive number of milliseconds\n');
+    process.exit(2);
+  }
+  return { gameDir: resolve(values.dir ?? '.'), hubUrl: values.hub ?? DEFAULT_HUB_URL, timeoutMs, isOffline: values.offline, isJson: values.json };
+}
+
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a JSON file from disk, parsed by the caller's schema
+function readJsonFile(path: string): unknown {
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: JSON.parse's result, parsed by the caller's schema
+  const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'));
+  return parsed;
+}
+
+/** The client version the game has installed (its `node_modules` copy), else this doctor's own. */
+function installedClientVersion(gameDir: string): string {
+  try {
+    const installed = readJsonFile(join(gameDir, 'node_modules', '@diffenderfer-games', 'hub', 'package.json'));
+    if (typeof installed === 'object' && installed !== null && 'version' in installed && typeof installed.version === 'string') {
+      return installed.version;
+    }
+  } catch {
+    // Not installed in the game: report this doctor's own version.
+  }
+  return HUB_CLIENT_VERSION;
+}
+
+async function runDoctor(options: DoctorOptions): Promise<Finding[]> {
+  const findings: Finding[] = [];
+  if (!options.isOffline) {
+    findings.push(...checkClientVersion(installedClientVersion(options.gameDir), await fetchHubVersion(options.hubUrl, options.timeoutMs)));
+  }
+  findings.push(...checkVendoredCopies(options.gameDir));
+  try {
+    findings.push(...checkManifest(readJsonFile(join(options.gameDir, 'package.json'))));
+  } catch (failure) {
+    findings.push({ level: 'error', check: 'manifest', message: `could not read package.json: ${failure instanceof Error ? failure.message : String(failure)}` });
+  }
+  return findings;
+}
+
+const options = readOptions();
+const findings = await runDoctor(options);
+if (options.isJson) {
+  process.stdout.write(`${JSON.stringify({ findings }, null, 2)}\n`);
+} else {
+  for (const finding of findings) {
+    process.stdout.write(`${finding.level.padEnd(7)} ${finding.check}: ${finding.message}\n`);
+  }
+}
+process.exitCode = findings.some((finding) => finding.level === 'error') ? 1 : 0;

package/src/doctor/hub-version-fetch.ts

@@ -0,0 +1,43 @@
+/**
+ * Reading the hub's `GET /_api/version` for `hub-doctor`, with a timeout so a
+ * hung or unreachable hub fails a game's CI quickly instead of stalling it.
+ */
+import { HubVersion } from '@diffenderfer-games/hub-contract';
+
+/** How long the doctor waits for the hub by default, ms. */
+export const DEFAULT_HUB_TIMEOUT_MS = 10_000;
+
+/** The hub could not be asked: down, slow, or answering with an error. */
+export interface HubUnreachable {
+  /** The URL that was asked. */
+  readonly unreachableUrl: string;
+  /** Why, for the message (`timed out after 10000 ms`, `HTTP 502`, a network error). */
+  readonly reason: string;
+}
+
+/** Whether a version lookup failed. */
+export function isHubUnreachable(lookup: HubVersion | null | HubUnreachable): lookup is HubUnreachable {
+  return lookup !== null && 'unreachableUrl' in lookup;
+}
+
+/**
+ * The hub's version: `null` for a hub from before versioning (404), a
+ * {@link HubUnreachable} when it can't be read within `timeoutMs`.
+ */
+export async function fetchHubVersion(hubUrl: string, timeoutMs: number = DEFAULT_HUB_TIMEOUT_MS): Promise<HubVersion | null | HubUnreachable> {
+  const url = new URL('/_api/version', hubUrl).toString();
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    if (response.status === 404) {
+      return null;
+    }
+    if (!response.ok) {
+      return { unreachableUrl: url, reason: `HTTP ${String(response.status)}` };
+    }
+    return HubVersion.parse(await response.json());
+  } catch (failure) {
+    const isTimeout = failure instanceof Error && (failure.name === 'TimeoutError' || failure.name === 'AbortError');
+    const reason = isTimeout ? `timed out after ${String(timeoutMs)} ms` : failure instanceof Error ? failure.message : String(failure);
+    return { unreachableUrl: url, reason };
+  }
+}

package/src/doctor/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "types": [
+      "node"
+    ]
+  },
+  "include": [
+    "."
+  ],
+  "exclude": []
+}

package/src/globals.ts

@@ -0,0 +1,115 @@
+/**
+ * Page-wide singletons across client versions (plan §4.4). One page often
+ * runs two client builds: the game's bundled copy and the host's injected
+ * `/_hub/hub.js`. The input system, daily challenges and the realtime API
+ * must exist once per page, so each is registered here with the version that
+ * created it and a small `api` number that changes only when the
+ * cross-bundle shape does.
+ *
+ * - Same `api`: the first creator wins and everyone shares it.
+ * - Different `api`: the caller decides who owns the page (see
+ *   {@link claimSingleton}'s `onMismatch`); the mismatch is logged once with the fix.
+ * - The v1 names (`window.__HUB_INPUT__`, `__HUB_DAILY__`, `__HUB_RT__`) stay as
+ *   aliases while vendored v1 copies are still around.
+ */
+
+/** A page-wide singleton's name. */
+export type SingletonName = 'input' | 'daily' | 'rt';
+
+/** One registered singleton. */
+export interface SingletonRecord {
+  /** The client version that created it. */
+  readonly version: string;
+  /** Its cross-bundle shape number. */
+  readonly api: number;
+  /** The instance itself; another bundle's object, so callers check it before use. */
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: the instance may come from another bundle on the page
+  readonly instance: unknown;
+}
+
+/** The registry on `window.__DG__`. */
+export type DgGlobals = { [K in SingletonName]?: SingletonRecord };
+
+/** The version recorded for a singleton adopted from a v1 (vendored) client, which predates the registry. */
+export const V1_CLIENT_VERSION = 'v1';
+
+/** The v1 window names, kept as aliases. */
+export const LEGACY_GLOBAL_NAMES = { input: '__HUB_INPUT__', daily: '__HUB_DAILY__', rt: '__HUB_RT__' } as const satisfies Record<SingletonName, string>;
+
+declare global {
+  interface Window {
+    __DG__?: DgGlobals;
+    // eslint-disable-next-line no-restricted-syntax -- trust boundary: set by any bundle on the page, including v1 copies
+    __HUB_INPUT__?: unknown;
+    // eslint-disable-next-line no-restricted-syntax -- trust boundary: set by any bundle on the page, including v1 copies
+    __HUB_DAILY__?: unknown;
+    // eslint-disable-next-line no-restricted-syntax -- trust boundary: set by any bundle on the page, including v1 copies
+    __HUB_RT__?: unknown;
+  }
+}
+
+/** How to claim a singleton. */
+export interface SingletonClaim<T> {
+  readonly name: SingletonName;
+  /** This bundle's client version. */
+  readonly version: string;
+  /** This bundle's shape number for the singleton. */
+  readonly api: number;
+  /** Make the instance when nobody has yet. */
+  readonly create: () => T;
+  /** Whether a registered instance is usable as `T` (it may come from another bundle). */
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: checks another bundle's object
+  readonly isInstance: (candidate: unknown) => candidate is T;
+  /**
+   * The registered one has a different `api`: return `true` to replace it
+   * with this bundle's instance, `false` to keep it (then `create` makes a
+   * private instance for this bundle only). Default: keep it.
+   */
+  readonly onMismatch?: (registered: SingletonRecord) => boolean;
+}
+
+const warnedMismatches = new Set<SingletonName>();
+
+/** The page registry, created on first use (`undefined` outside a browser). */
+function registryOf(page: Window | undefined): DgGlobals | undefined {
+  if (page === undefined) {
+    return undefined;
+  }
+  page.__DG__ ??= {};
+  return page.__DG__;
+}
+
+/** Register (or join) a page-wide singleton and return the instance this bundle should use. */
+export function claimSingleton<T>(claim: SingletonClaim<T>): T {
+  const page = typeof window === 'undefined' ? undefined : window;
+  const registry = registryOf(page);
+  if (page === undefined || registry === undefined) {
+    return claim.create();
+  }
+  const registered = registry[claim.name];
+  if (registered !== undefined && claim.isInstance(registered.instance)) {
+    if (registered.api === claim.api) {
+      return registered.instance;
+    }
+    if (!warnedMismatches.has(claim.name)) {
+      warnedMismatches.add(claim.name);
+      // eslint-disable-next-line no-console -- the plan's one-time warning to the game developer, with the fix
+      console.warn(`[hub] two clients on this page disagree on "${claim.name}" (v${registered.version} api ${String(registered.api)}, v${claim.version} api ${String(claim.api)}). Fix: npm update @diffenderfer-games/hub`);
+    }
+    if (claim.onMismatch?.(registered) !== true) {
+      return claim.create();
+    }
+  } else {
+    const legacy = page[LEGACY_GLOBAL_NAMES[claim.name]];
+    if (registered === undefined && claim.isInstance(legacy)) {
+      // A v1 vendored copy got there first: share it, as v1 bundles did, and
+      // record it so later bundles (and diagnostics) see which client owns it.
+      registry[claim.name] = { version: V1_CLIENT_VERSION, api: claim.api, instance: legacy };
+      return legacy;
+    }
+  }
+  const instance = claim.create();
+  registry[claim.name] = { version: claim.version, api: claim.api, instance };
+  page[LEGACY_GLOBAL_NAMES[claim.name]] = instance;
+  return instance;
+}

package/src/index.ts

@@ -0,0 +1,50 @@
+/**
+ * `@diffenderfer-games/hub`: the hub client for games on diffenderfer.games.
+ *
+ * ```ts
+ * import { hub } from '@diffenderfer-games/hub';
+ *
+ * const { user } = await hub.me();
+ * await hub.putSave('auto', { level: 7, gold: 120 });
+ * await hub.submitScore('highscore', 9001, { title: 'High Score' });
+ * ```
+ *
+ * In a hosted game the slug and API base are detected from the page; use
+ * {@link createHub} for others. Every call rejects with a {@link HubError}
+ * when it fails, except the fire-and-forget analytics (`recordPlay`,
+ * `heartbeat`, `event`). When the hub can't be reached, reads come from an
+ * offline cache and writes are queued until it is back.
+ *
+ * The page-wide namespaces hang off `hub` as lazy getters (`hub.input`,
+ * `hub.daily`, `hub.social`, `hub.mp`, `hub.rooms`, `hub.race`), and each has
+ * its own entry (`@diffenderfer-games/hub/input`, ...) for games that want
+ * only that part.
+ *
+ * @packageDocumentation
+ */
+export { createHub, Hub, hub } from './core/hub';
+export {
+  ContentRejectedError,
+  HubError,
+  OfflineError,
+  UNSUPPORTED_BY_HUB,
+  type HubErrorCode,
+  type HubErrorDetails,
+} from './core/errors';
+export type { SyncConflict, SyncResult } from './core/connection';
+export type { AuthResponse, ProfileUpdate, StatResult } from './core/hub-progress';
+export type { GrantBundle, TradeBundle, TradeId, TradeListOptions, TradeNoteOptions } from './core/hub-economy';
+export type { HubMenuControl } from './core/menu-control';
+export type { QueueOp, QueueOpInput, QueuedScoreOptions, ProfilePatch } from './core/offline/queue';
+export type { BufferedEvent } from './core/offline/events';
+export type { EndpointFields, EndpointName, EndpointReply } from './core/rest/endpoint-types';
+export { CLIENT_VERSION_HEADER } from './core/rest/rest-client';
+export type { ClientSupport } from './core/version/hub-version';
+export { HUB_CLIENT_VERSION } from './core/version/client-version.gen';
+export type * from './core/types';
+export * from './daily';
+export * from './input';
+export type * from './social';
+export type * from './mp';
+export type * from './race';
+export type * from './rooms';

package/src/input/device-state.ts

@@ -0,0 +1,146 @@
+/**
+ * The raw state of every input device, updated by DOM events and sampled once
+ * per frame: held keys and mouse buttons, the pointer, movement and wheel
+ * accumulators, one-frame pulses, on-screen sticks and buttons, and gamepads.
+ */
+import { AXIS_DEADZONE, readGamepads } from './gamepad';
+
+/** An on-screen stick's output, -1..1 per axis. */
+export interface StickOutput {
+  outX: number;
+  outY: number;
+}
+
+/** A 2D accumulator. */
+interface Delta {
+  dx: number;
+  dy: number;
+}
+
+/** Keys that scroll the page; cancelled during play (not while typing). */
+const SCROLL_KEYS = new Set([' ', 'arrowup', 'arrowdown', 'arrowleft', 'arrowright']);
+
+/** Input types that don't take text (buttons, checkboxes, sliders…). */
+const NON_TEXT_INPUT_TYPES = new Set(['button', 'submit', 'reset', 'checkbox', 'radio', 'range', 'color', 'file', 'image']);
+
+/** Whether typing in `target` owns Space and the arrow keys. */
+export function isTypingTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) {
+    return false;
+  }
+  if (target.isContentEditable || target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement) {
+    return true;
+  }
+  return target instanceof HTMLInputElement && !NON_TEXT_INPUT_TYPES.has(target.type);
+}
+
+/** What the device state reports back to the input system. */
+export interface DeviceStateEvents {
+  /** The mouse moved or clicked: it is the active pointer. */
+  onMouseActivity(): void;
+  /** A gamepad connected (`true`) or disconnected (`false`). */
+  onGamepadConnection(isConnected: boolean): void;
+  /** Whether keydown should cancel scrolling keys (a game defined its inputs). */
+  shouldCancelScrollKeys(): boolean;
+}
+
+/** Raw device state for one page. */
+export class DeviceState {
+  readonly heldKeys = new Set<string>();
+  readonly heldMouseButtons = new Set<number>();
+  readonly pressedVirtualButtons = new Set<string>();
+  readonly sticks = new Map<string, StickOutput>();
+  pointerX = 0;
+  pointerY = 0;
+  readonly movement: Delta = { dx: 0, dy: 0 };
+  readonly wheel: Delta = { dx: 0, dy: 0 };
+  gamepads: Gamepad[] = [];
+  frame = 0;
+  private readonly pulseFrames = new Map<string, number>();
+
+  /** Fire a one-frame pulse (`tap`, `mouse:dbl`). */
+  pulse(name: string): void {
+    this.pulseFrames.set(name, this.frame);
+  }
+
+  /** Whether a pulse fired this frame or the last. */
+  isPulseActive(name: string): boolean {
+    const firedAt = this.pulseFrames.get(name);
+    return firedAt === this.frame || firedAt === this.frame - 1;
+  }
+
+  /** Poll the gamepads. Returns whether any are connected and whether any moved. */
+  pollGamepads(): { isConnected: boolean; hasActivity: boolean } {
+    this.gamepads = readGamepads();
+    const hasActivity = this.gamepads.some((pad) => pad.buttons.some((button) => button.pressed || button.value > 0.5)
+      || pad.axes.some((axis) => Math.abs(axis) > AXIS_DEADZONE));
+    return { isConnected: this.gamepads.length > 0, hasActivity };
+  }
+
+  /** End-of-frame decay of the relative accumulators. */
+  decay(): void {
+    this.movement.dx = 0;
+    this.movement.dy = 0;
+    this.wheel.dx *= 0.6;
+    this.wheel.dy *= 0.6;
+  }
+
+  /** Release everything held (focus loss, hidden tab), so nothing sticks. */
+  releaseAll(): void {
+    this.heldKeys.clear();
+    this.heldMouseButtons.clear();
+    this.pressedVirtualButtons.clear();
+    for (const stick of this.sticks.values()) {
+      stick.outX = 0;
+      stick.outY = 0;
+    }
+  }
+
+  /** Wire the DOM listeners that feed this state. */
+  listen(events: DeviceStateEvents): void {
+    if (typeof window === 'undefined') {
+      return;
+    }
+    window.addEventListener('keydown', (event) => {
+      const key = event.key.toLowerCase();
+      this.heldKeys.add(key);
+      if (events.shouldCancelScrollKeys() && SCROLL_KEYS.has(key) && !isTypingTarget(event.target)) {
+        event.preventDefault();
+      }
+    });
+    window.addEventListener('keyup', (event) => this.heldKeys.delete(event.key.toLowerCase()));
+    window.addEventListener('mousemove', (event) => {
+      this.movement.dx += event.movementX;
+      this.movement.dy += event.movementY;
+      this.pointerX = event.clientX;
+      this.pointerY = event.clientY;
+      events.onMouseActivity();
+    });
+    window.addEventListener('mousedown', (event) => {
+      this.heldMouseButtons.add(event.button);
+      events.onMouseActivity();
+    });
+    window.addEventListener('mouseup', (event) => this.heldMouseButtons.delete(event.button));
+    window.addEventListener('dblclick', () => {
+      this.pulse('mouse:dbl');
+    });
+    window.addEventListener('wheel', (event) => {
+      this.wheel.dx += Math.sign(event.deltaX);
+      this.wheel.dy += Math.sign(event.deltaY);
+    }, { passive: true });
+    window.addEventListener('blur', () => {
+      this.releaseAll();
+    });
+    document.addEventListener('visibilitychange', () => {
+      if (document.hidden) {
+        this.releaseAll();
+      }
+    });
+    window.addEventListener('gamepadconnected', () => {
+      events.onGamepadConnection(true);
+    });
+    window.addEventListener('gamepaddisconnected', () => {
+      events.onGamepadConnection(false);
+    });
+  }
+}

package/src/input/edges.ts

@@ -0,0 +1,55 @@
+/**
+ * Edge detection for polled buttons: a plain rising edge, and a rising edge
+ * that repeats while held (menu navigation: a first step, a pause, then steady
+ * steps).
+ */
+
+/** Delay before a held direction starts repeating. */
+const FIRST_REPEAT_DELAY_MS = 320;
+/** Interval between repeats while held. */
+const REPEAT_INTERVAL_MS = 130;
+
+/** A monotonic clock in ms. */
+export function nowMs(): number {
+  return typeof performance === 'undefined' ? Date.now() : performance.now();
+}
+
+/** Rising edges of named polled buttons. */
+export class RisingEdges {
+  private readonly wasPressed = new Map<string, boolean>();
+
+  /** Whether `key` went from released to pressed since the last call for it. */
+  rose(key: string, isPressed: boolean): boolean {
+    const wasPressedBefore = this.wasPressed.get(key) === true;
+    this.wasPressed.set(key, isPressed);
+    return isPressed && !wasPressedBefore;
+  }
+}
+
+/** Rising edges that repeat while held. */
+export class RepeatingEdges {
+  private readonly timers = new Map<string, { isHeld: boolean; nextAt: number }>();
+
+  /** Whether `key` fires now: on the press, then after a delay, then steadily while held. */
+  fires(key: string, isPressed: boolean, at: number = nowMs()): boolean {
+    let timer = this.timers.get(key);
+    if (timer === undefined) {
+      timer = { isHeld: false, nextAt: 0 };
+      this.timers.set(key, timer);
+    }
+    if (!isPressed) {
+      timer.isHeld = false;
+      return false;
+    }
+    if (!timer.isHeld) {
+      timer.isHeld = true;
+      timer.nextAt = at + FIRST_REPEAT_DELAY_MS;
+      return true;
+    }
+    if (at >= timer.nextAt) {
+      timer.nextAt = at + REPEAT_INTERVAL_MS;
+      return true;
+    }
+    return false;
+  }
+}

package/src/input/gamepad.ts

@@ -0,0 +1,61 @@
+/**
+ * Reading standard gamepads: button indices, the stick deadzone and the
+ * directions a pad is pointing.
+ */
+
+/** Standard-gamepad button indices. */
+export const PAD_BUTTON = {
+  A: 0, B: 1, X: 2, Y: 3, LB: 4, RB: 5, LT: 6, RT: 7, SELECT: 8, START: 9, UP: 12, DOWN: 13, LEFT: 14, RIGHT: 15,
+} as const;
+
+/** Stick deflection below this is ignored. */
+export const AXIS_DEADZONE = 0.35;
+
+/** A screen direction. */
+export type Direction = 'up' | 'down' | 'left' | 'right';
+
+/** Which directions are held. */
+export type HeldDirections = Record<Direction, boolean>;
+
+/** The connected gamepads (the browser's list has holes). */
+export function readGamepads(): Gamepad[] {
+  if (typeof navigator === 'undefined' || typeof navigator.getGamepads !== 'function') {
+    return [];
+  }
+  return navigator.getGamepads().filter((pad): pad is Gamepad => pad !== null);
+}
+
+/** Whether `pad` holds button `index`. */
+export function isPadButtonPressed(pad: Gamepad, index: number): boolean {
+  return pad.buttons[index]?.pressed === true;
+}
+
+/** Whether any pad holds button `index`. */
+export function isAnyPadButtonPressed(pads: readonly Gamepad[], index: number): boolean {
+  return pads.some((pad) => isPadButtonPressed(pad, index));
+}
+
+/** The directions one pad points (left stick past `deadzone`, or the d-pad). */
+export function padDirections(pad: Gamepad, deadzone: number): HeldDirections {
+  const horizontal = pad.axes[0] ?? 0;
+  const vertical = pad.axes[1] ?? 0;
+  return {
+    up: vertical < -deadzone || isPadButtonPressed(pad, PAD_BUTTON.UP),
+    down: vertical > deadzone || isPadButtonPressed(pad, PAD_BUTTON.DOWN),
+    left: horizontal < -deadzone || isPadButtonPressed(pad, PAD_BUTTON.LEFT),
+    right: horizontal > deadzone || isPadButtonPressed(pad, PAD_BUTTON.RIGHT),
+  };
+}
+
+/** The directions any pad points. */
+export function anyPadDirections(pads: readonly Gamepad[], deadzone: number): HeldDirections {
+  const held: HeldDirections = { up: false, down: false, left: false, right: false };
+  for (const pad of pads) {
+    const directions = padDirections(pad, deadzone);
+    held.up ||= directions.up;
+    held.down ||= directions.down;
+    held.left ||= directions.left;
+    held.right ||= directions.right;
+  }
+  return held;
+}