@forgeax/engine-input 0.0.0-dev.8d955ade1c79

package/src/canvas-input-boundary.ts

@@ -0,0 +1,81 @@
+// @forgeax/engine-input -- exclusive host-owned canvas input boundary.
+//
+// A physical canvas has one DOM acquisition backend. Hosts with two worlds (for
+// example editor + transient Play) route that one producer through these two
+// InputBackend views. This is exclusive ownership, deliberately separate from
+// synthetic/replay input composition.
+
+import {
+  createEmptyInputBackendSample,
+  type InputBackend,
+  type InputBackendSample,
+} from './input-snapshot';
+import { isUiOwnedEvent } from './ui-ownership';
+
+export interface CanvasInputBoundary {
+  readonly editor: InputBackend;
+  readonly game: InputBackend;
+  owner(): 'editor' | 'game';
+  grantGame(): void;
+  revokeGame(): void;
+  /** Clear the active consumer when an event originated in the host UI. */
+  handleUiEvent(event: Event, host: Node): boolean;
+  detach(): void;
+}
+
+type CanvasInputOwner = ReturnType<CanvasInputBoundary['owner']>;
+
+export function createCanvasInputBoundary(source: InputBackend): CanvasInputBoundary {
+  let active: CanvasInputOwner = 'editor';
+  let gamePointerLockAllowed = false;
+  source.setPointerLockAllowed?.(false);
+
+  const empty = (): InputBackendSample => createEmptyInputBackendSample();
+
+  const clear = (): void => {
+    source.clear?.();
+    source.setPointerLockAllowed?.(false);
+  };
+
+  const routed = (consumer: CanvasInputOwner): InputBackend => ({
+    sample: () => (consumer === active ? source.sample() : empty()),
+    setPointerLockAllowed: (allowed) => {
+      if (consumer === 'game') {
+        gamePointerLockAllowed = allowed;
+        source.setPointerLockAllowed?.(active === 'game' && allowed);
+      } else {
+        source.setPointerLockAllowed?.(false);
+      }
+    },
+    clear: () => {
+      if (consumer === active) clear();
+    },
+    detach: () => source.detach(),
+  });
+
+  const grantGame = (): void => {
+    if (active === 'game') return;
+    clear();
+    active = 'game';
+    source.setPointerLockAllowed?.(gamePointerLockAllowed);
+  };
+
+  const revokeGame = (): void => {
+    clear();
+    active = 'editor';
+  };
+
+  return {
+    editor: routed('editor'),
+    game: routed('game'),
+    owner: () => active,
+    grantGame,
+    revokeGame,
+    handleUiEvent: (event, host) => {
+      if (!isUiOwnedEvent(event, host)) return false;
+      clear();
+      return true;
+    },
+    detach: () => source.detach(),
+  };
+}

package/src/composite-backend.ts

@@ -0,0 +1,189 @@
+// @forgeax/engine-input -- CompositeInputBackend (synthetic-input decorator).
+//
+// PROBLEM. The scan system reads ONE `InputBackend` from `INPUT_BACKEND_KEY`
+// each frame. An AI / record-replay harness needs to feed synthetic input into
+// that same slot WITHOUT evicting the human's browser backend -- because a human
+// may take over at any instant (PIE two-world model + charter §8 human-as-final-
+// authority). Overwriting the resource locks the human out; wrapping it does not.
+//
+// SOLUTION. `makeCompositeBackend(inner)` returns an `InputBackend` that HOLDS
+// the human backend as `inner` and layers a programmatic injection surface
+// (`press` / `release` / `setButton` / `addMovement` / `addWheel`) on top. The
+// scan system stays variant-agnostic: it still calls `sample()` on one backend
+// (Depend-on-Abstractions -- the consumer never learns a composite exists).
+//
+// SIDE-EFFECT CONTRACT. `inner.sample()` DRAINS its per-frame accumulators
+// (up-edges, movement delta, wheel notches) on read, so the composite calls it
+// EXACTLY ONCE per `sample()` and drains its OWN injected accumulators in the
+// same pass. Field-by-field merge honoring each field's lifecycle:
+//
+//   downKeys   held across frames    -> UNION(inner, injected.held)
+//   upKeys     lives one frame        -> UNION; injected up-edge set drained here
+//   buttons    held tuple             -> OR per slot
+//   movementX/Y, wheelDelta            -> SUM; injected side reset to 0 here
+//   focused    gates up-edge suppress -> inner.focused || injectionActive
+//   pointerLocked                      -> inner (AI must not fabricate a lock)
+//   optional (pointers/gamepads/...)   -> pass through from inner untouched
+//
+// YIELD-TO-HUMAN (default on). A human-held key on `inner` suppresses only the
+// injected state for that SAME key in that frame. Other AI keys continue, so a
+// human can take a key without silencing unrelated synthetic input. This is the
+// structural realization of "human wins" without a global takeover policy.
+
+import type { InputBackend, InputBackendSample } from './input-snapshot';
+
+/** Options controlling the composite merge policy. */
+export interface CompositeBackendOptions {
+  /**
+   * When `true` (default), a key held on the inner (human) backend suppresses
+   * injected state only for that same key in that frame. Set `false` for
+   * record/replay or AI-solo scenarios where both sources should coexist even
+   * on key overlap.
+   */
+  readonly yieldToHuman?: boolean;
+}
+
+/**
+ * A composite backend: an `InputBackend` (drop-in for `INPUT_BACKEND_KEY`) plus
+ * a programmatic injection surface. All injection is additive over the wrapped
+ * human backend.
+ */
+export interface CompositeInputBackend extends InputBackend {
+  /** Hold `key` down (mirrors a keydown). Idempotent. */
+  press(key: string): void;
+  /** Release `key` (mirrors a keyup); emits a one-frame up-edge on next sample. */
+  release(key: string): void;
+  /** Set an injected mouse-button slot (0/1/2) held-state. */
+  setButton(slot: 0 | 1 | 2, down: boolean): void;
+  /** Accumulate injected pointer-lock movement delta (drained on next sample). */
+  addMovement(dx: number, dy: number): void;
+  /** Accumulate injected wheel notches (drained on next sample). */
+  addWheel(notches: number): void;
+  /** Drop all injected state; currently-held keys emit a clean up-edge once. */
+  clearInjected(): void;
+  /** Toggle the yield-to-human gate at runtime. */
+  setYieldToHuman(yield_: boolean): void;
+}
+
+export function makeCompositeBackend(
+  inner: InputBackend,
+  options?: CompositeBackendOptions,
+): CompositeInputBackend {
+  let yieldToHuman = options?.yieldToHuman ?? true;
+
+  // Injected held-state (survives across frames).
+  const heldKeys = new Set<string>();
+  const buttons: [boolean, boolean, boolean] = [false, false, false];
+  // Injected per-frame accumulators (drained on each sample()).
+  const upEdges = new Set<string>();
+  let mvx = 0;
+  let mvy = 0;
+  let wheel = 0;
+
+  function injectionActive(): boolean {
+    return heldKeys.size > 0 || upEdges.size > 0 || buttons.some((b) => b);
+  }
+
+  function sample(): InputBackendSample {
+    // Call inner EXACTLY once -- it drains its own accumulators here.
+    const base = inner.sample();
+
+    // yield-to-human is PER-KEY: an injected key is suppressed only when the human
+    // is holding the SAME key this frame. This is the minimal realization of
+    // charter §8 (the human always wins a key they touch) WITHOUT the collateral of
+    // a global gate — a human strafing D does not silence an AI holding W, so the
+    // two genuinely coexist (that is the whole point of a composite; a caller who
+    // wants "human takes over everything" can clearInjected() at the policy layer).
+    // downKeys: union of human-held and injected-held, minus injected keys the human
+    // is also pressing. A yielded injected release is likewise a no-op: emitting its
+    // up-edge would incorrectly release the human-held key in the scan system.
+    const downKeys = new Set(base.downKeys);
+    for (const k of heldKeys) {
+      if (yieldToHuman && base.downKeys.has(k)) continue; // human owns this exact key
+      downKeys.add(k);
+    }
+
+    // upKeys: union of human up-edges and injected up-edges (one-frame life), except
+    // injected edges for keys that the human still owns under the per-key yield gate.
+    const mergedUp = new Set(base.upKeys);
+    for (const k of upEdges) {
+      if (yieldToHuman && base.downKeys.has(k)) continue;
+      mergedUp.add(k);
+    }
+
+    // buttons: OR per slot.
+    const mergedButtons: readonly [boolean, boolean, boolean] = [
+      base.buttons[0] || buttons[0],
+      base.buttons[1] || buttons[1],
+      base.buttons[2] || buttons[2],
+    ];
+
+    // focused: keep true while WE are injecting, so the scan system does not
+    // treat a headless/backgrounded tab (inner.focused === false) as a reason
+    // to suppress our up-edges. Otherwise mirror inner.
+    const focused = base.focused || injectionActive();
+
+    const out: InputBackendSample = {
+      ...base, // carry inner optional fields (pointers/gamepads/gestures/...) untouched
+      downKeys,
+      upKeys: mergedUp,
+      buttons: mergedButtons,
+      movementX: base.movementX + mvx,
+      movementY: base.movementY + mvy,
+      wheelDelta: base.wheelDelta + wheel,
+      focused,
+      pointerLocked: base.pointerLocked, // AI never fabricates a lock
+    };
+
+    // Drain injected per-frame accumulators (mirrors inner's own drain).
+    upEdges.clear();
+    mvx = 0;
+    mvy = 0;
+    wheel = 0;
+
+    return out;
+  }
+
+  // Only surface setPointerLockAllowed when the inner backend supports it, so
+  // the optional method is truly absent (not `undefined`) under
+  // exactOptionalPropertyTypes -- and forwards to the human backend when present.
+  const lockGate: Pick<InputBackend, 'setPointerLockAllowed'> = inner.setPointerLockAllowed
+    ? { setPointerLockAllowed: (allowed: boolean) => inner.setPointerLockAllowed?.(allowed) }
+    : {};
+
+  return {
+    sample,
+    ...lockGate,
+    // Teardown belongs to the human backend -- forward it.
+    detach: () => inner.detach(),
+
+    press(key) {
+      heldKeys.add(key);
+      upEdges.delete(key); // re-press cancels a pending release edge
+    },
+    release(key) {
+      if (heldKeys.delete(key)) upEdges.add(key); // held -> emit one up-edge
+    },
+    setButton(slot, down) {
+      buttons[slot] = down;
+    },
+    addMovement(dx, dy) {
+      mvx += dx;
+      mvy += dy;
+    },
+    addWheel(notches) {
+      wheel += notches;
+    },
+    clearInjected() {
+      for (const k of heldKeys) upEdges.add(k); // clean release edge for each
+      heldKeys.clear();
+      buttons[0] = buttons[1] = buttons[2] = false;
+      mvx = 0;
+      mvy = 0;
+      wheel = 0;
+    },
+    setYieldToHuman(yield_) {
+      yieldToHuman = yield_;
+    },
+  };
+}

package/src/controller-db-data.ts

@@ -0,0 +1,25 @@
+// controller-db-data.ts -- the 554KB vendored SDL_GameControllerDB, inlined
+// at build time via esbuild's text loader (tsup.config.ts loader['.txt']).
+//
+// This module is a SEPARATE sub-export (`@forgeax/engine-input/controller-db-data`)
+// so the vendored 554KB text NEVER enters the main-entry bundle. The
+// browser backend dynamic-imports it only on first sight of a non-standard
+// gamepad (D-2 lazy-load; C-5 the DB size must not sit in the default path).
+//
+// The `?raw`-free plain import returns the inlined string because tsup is
+// configured with loader: { '.txt': 'text' }. In a vitest/vite context the
+// default `.txt` import is a URL, so consumers under test inject their own
+// DB text instead of importing this module (D-13 loadControllerDb override).
+
+// @ts-expect-error -- esbuild text loader inlines the .txt file as a string
+// module; there is no ambient type declaration for `*.txt` imports and one
+// is not warranted for a single build-time asset.
+import bundledControllerDb from '../vendor/gamecontrollerdb.txt';
+
+/** The vendored gamecontrollerdb.txt contents, inlined at build time. */
+export const BUNDLED_CONTROLLER_DB: string = bundledControllerDb as string;
+
+/** Default loader used by the backend when no override is supplied (D-13). */
+export function loadBundledControllerDb(): Promise<string> {
+  return Promise.resolve(BUNDLED_CONTROLLER_DB);
+}

package/src/controller-db.ts

@@ -0,0 +1,218 @@
+// controller-db.ts -- pure SDL_GameControllerDB parsing + GUID derivation.
+//
+// This module holds ONLY pure functions (no DOM, no ECS, no vendored data
+// import). The 554KB gamecontrollerdb.txt lives in the separate
+// `./controller-db-data` sub-export so it never enters the main-entry
+// bundle; the backend dynamic-imports both this module and the data module
+// on first sight of a non-standard gamepad (D-2 lazy-load).
+//
+// SDL GUID reference: KB source
+// .forgeax-harness/knowledge-base/sources/2026-07-07-sdl-guid-browser-gamepad-id-mapping.md
+//
+// D-13 strategy 2: build a match GUID from VID/PID with bus=USB(0x03),
+// CRC=0, version=0, driver signature/data=0. This matches the vast
+// majority of gamecontrollerdb.txt native entries directly.
+
+/** A single mapping token target: physical button / axis / hat index. */
+export type MappingToken =
+  | { readonly kind: 'button'; readonly index: number }
+  | { readonly kind: 'axis'; readonly index: number; readonly half?: '+' | '-' }
+  | { readonly kind: 'hat'; readonly index: number; readonly mask: number };
+
+/**
+ * Parsed mapping tokens for one controller entry, keyed by the SDL logical
+ * name (`a`, `b`, `leftx`, `dpup`, `lefttrigger`, ...). Values are the
+ * physical source (button `bN`, axis `aN`, hat `hN.M`).
+ */
+export type MappingTokens = Readonly<Record<string, MappingToken>>;
+
+/** One controller-DB row: its platform section + parsed mapping tokens. */
+export interface ControllerDbEntry {
+  readonly platform: string | undefined;
+  readonly tokens: MappingTokens;
+}
+
+/**
+ * Parsed controller DB: SDL GUID (32-char hex) -> one entry per platform
+ * section. The same GUID can appear in multiple platform sections, so the
+ * value is an array.
+ */
+export type ControllerDb = Readonly<Record<string, readonly ControllerDbEntry[]>>;
+
+/** Recognised web platform section labels (D-13). */
+const CONTROLLER_PLATFORMS = ['Windows', 'Mac OS X', 'Linux', 'Android', 'iOS'] as const;
+export type ControllerPlatform = (typeof CONTROLLER_PLATFORMS)[number];
+
+/** Parse one `key:source` mapping token into a MappingToken. */
+function parseMappingToken(source: string): MappingToken | undefined {
+  // Half-axis prefix: +aN / -aN.
+  let half: '+' | '-' | undefined;
+  let body = source;
+  if (body.startsWith('+') || body.startsWith('-')) {
+    half = body[0] as '+' | '-';
+    body = body.slice(1);
+  }
+  const prefix = body[0];
+  if (prefix === 'b') {
+    const index = Number.parseInt(body.slice(1), 10);
+    return Number.isNaN(index) ? undefined : { kind: 'button', index };
+  }
+  if (prefix === 'a') {
+    const index = Number.parseInt(body.slice(1), 10);
+    if (Number.isNaN(index)) return undefined;
+    return half ? { kind: 'axis', index, half } : { kind: 'axis', index };
+  }
+  if (prefix === 'h') {
+    // hN.M -- hat N, direction mask M.
+    const dot = body.indexOf('.');
+    if (dot < 0) return undefined;
+    const index = Number.parseInt(body.slice(1, dot), 10);
+    const mask = Number.parseInt(body.slice(dot + 1), 10);
+    return Number.isNaN(index) || Number.isNaN(mask) ? undefined : { kind: 'hat', index, mask };
+  }
+  return undefined;
+}
+
+/**
+ * Parse a gamecontrollerdb.txt string into a ControllerDb map. Comment
+ * (`#`) and blank lines are skipped. Each data line is
+ * `GUID,Name,token:source,...,platform:PLATFORM,`.
+ */
+export function parseControllerDb(txt: string): ControllerDb {
+  const db: Record<string, ControllerDbEntry[]> = {};
+  for (const rawLine of txt.split('\n')) {
+    const line = rawLine.trim();
+    if (line.length === 0 || line.startsWith('#')) continue;
+    const fields = line.split(',');
+    const guid = fields[0];
+    if (!guid || guid.length !== 32) continue;
+    let platform: string | undefined;
+    const tokens: Record<string, MappingToken> = {};
+    // fields[1] is the human-readable name; mapping tokens start at index 2.
+    for (let i = 2; i < fields.length; i++) {
+      const field = fields[i];
+      if (!field) continue;
+      const colon = field.indexOf(':');
+      if (colon < 0) continue;
+      const key = field.slice(0, colon);
+      const source = field.slice(colon + 1);
+      if (key === 'platform') {
+        platform = source;
+        continue;
+      }
+      // crc / sdk / hint fields are not physical mappings; skip non b/a/h.
+      const token = parseMappingToken(source);
+      if (token) tokens[key] = token;
+    }
+    const entry: ControllerDbEntry = { platform, tokens };
+    const bucket = db[guid];
+    if (bucket) {
+      bucket.push(entry);
+    } else {
+      db[guid] = [entry];
+    }
+  }
+  return db;
+}
+
+/** Format a 16-bit value as a 4-char little-endian hex pair. */
+function le16Hex(value: number): string {
+  const lo = value & 0xff;
+  const hi = (value >> 8) & 0xff;
+  return lo.toString(16).padStart(2, '0') + hi.toString(16).padStart(2, '0');
+}
+
+/**
+ * Build a 32-char SDL GUID hex from a VID/PID pair (D-13 strategy 2):
+ * bus (default USB 0x03) + CRC=0 + VID + fill + PID + fill + version=0 +
+ * driver sig/data=0. Each 16-bit field is little-endian within the string.
+ *
+ * Example: buildGuidFromVidPid(0x045e, 0x028e) ->
+ * '030000005e0400008e02000000000000' (Xbox 360).
+ */
+export function buildGuidFromVidPid(vid: number, pid: number, bus = 0x03): string {
+  return (
+    le16Hex(bus) + // bytes 0-1: bus type
+    '0000' + // bytes 2-3: CRC = 0
+    le16Hex(vid) + // bytes 4-5: VID (LE)
+    '0000' + // bytes 6-7: fill
+    le16Hex(pid) + // bytes 8-9: PID (LE)
+    '0000' + // bytes 10-11: fill
+    '0000' + // bytes 12-13: version = 0
+    '0000' // bytes 14-15: driver signature + data = 0
+  );
+}
+
+const CHROME_VENDOR_RE = /Vendor:\s*([0-9a-f]{1,4})/i;
+const CHROME_PRODUCT_RE = /Product:\s*([0-9a-f]{1,4})/i;
+
+/**
+ * Extract an SDL GUID from a browser `Gamepad.id` string. Handles the
+ * Chrome/Edge (`Vendor: XXXX Product: YYYY`) and Firefox (`VID-PID-Name`,
+ * leading-zero tolerant) formats. Returns undefined when VID/PID cannot be
+ * extracted (Safari name-only strings, XInput devices) so the caller keeps
+ * the Feat1 empty-signal (graceful degradation, R-3).
+ */
+export function extractGuidFromGamepadId(id: string): string | undefined {
+  // XInput devices expose no VID/PID in either Chrome or Firefox.
+  if (id.toLowerCase().includes('xinput')) return undefined;
+
+  // Chrome / Edge: "... (STANDARD GAMEPAD Vendor: 054c Product: 09cc)".
+  const vendorMatch = id.match(CHROME_VENDOR_RE);
+  const productMatch = id.match(CHROME_PRODUCT_RE);
+  if (vendorMatch?.[1] && productMatch?.[1]) {
+    const vid = Number.parseInt(vendorMatch[1], 16);
+    const pid = Number.parseInt(productMatch[1], 16);
+    if (!Number.isNaN(vid) && !Number.isNaN(pid)) return buildGuidFromVidPid(vid, pid);
+  }
+
+  // Firefox: "046d-c216-Logitech Dual Action" (VID-PID-Name). The first two
+  // dash segments must be pure hex; a name-only Safari string fails this.
+  const parts = id.split('-');
+  if (parts.length >= 3 && parts[0] && parts[1]) {
+    const vidHex = parts[0];
+    const pidHex = parts[1];
+    if (/^[0-9a-f]{1,4}$/i.test(vidHex) && /^[0-9a-f]{1,4}$/i.test(pidHex)) {
+      const vid = Number.parseInt(vidHex, 16);
+      const pid = Number.parseInt(pidHex, 16);
+      if (!Number.isNaN(vid) && !Number.isNaN(pid)) return buildGuidFromVidPid(vid, pid);
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Map a `navigator.userAgent` string to a gamecontrollerdb.txt platform
+ * section label (D-13). Returns undefined when the UA is unrecognised, in
+ * which case the caller falls back to any-platform entry selection.
+ */
+export function platformFromUserAgent(ua: string): ControllerPlatform | undefined {
+  // Order matters: iOS + Android both contain substrings that overlap with
+  // the desktop checks, so test the mobile/specific cases first.
+  if (/iPhone|iPad|iPod/.test(ua)) return CONTROLLER_PLATFORMS[4];
+  if (/Android/.test(ua)) return CONTROLLER_PLATFORMS[3];
+  if (/Windows/.test(ua)) return CONTROLLER_PLATFORMS[0];
+  if (/Mac OS X|Macintosh/.test(ua)) return CONTROLLER_PLATFORMS[1];
+  if (/Linux/.test(ua)) return CONTROLLER_PLATFORMS[2];
+  return undefined;
+}
+
+/**
+ * Select the best mapping entry for a GUID: prefer the entry whose platform
+ * section matches `platform`, else fall back to the first available entry
+ * (any platform). Returns undefined when the GUID is absent from the DB.
+ */
+export function selectBestMappingEntry(
+  db: ControllerDb,
+  guid: string,
+  platform: string | undefined,
+): ControllerDbEntry | undefined {
+  const entries = db[guid];
+  if (!entries || entries.length === 0) return undefined;
+  if (platform) {
+    const match = entries.find((e) => e.platform === platform);
+    if (match) return match;
+  }
+  return entries[0];
+}

package/src/frame-start-scan-system.ts

@@ -0,0 +1,93 @@
+// frame-start-scan-system.ts -- bridges an `InputBackend` producer into
+// the `InputSnapshot` Resource consumed by user systems (charter P5).
+//
+// Plan-strategy section 2.10 D-5 locks the system to a frame-start position
+// in the schedule: user systems declare `after: ['input-frame-start-scan']`
+// to read the snapshot. The system itself holds zero queries; it only
+// pulls one sample from the backend and writes the Resource.
+//
+// The backend is supplied via the `InputBackend` World resource rather than a
+// captured closure. Resource reads remain explicit in the system body.
+
+import { defineSystem, defineSystemSet, type SystemHandle } from '@forgeax/engine-ecs';
+import {
+  type ActionConfig,
+  type ActionState,
+  deriveActionStates,
+  INPUT_MAP_KEY,
+} from './action-state';
+import {
+  INPUT_SNAPSHOT_RESOURCE_KEY,
+  type InputBackend,
+  type InputSnapshot,
+  readActionStatesForEdgeDiff,
+  snapshotFromSample,
+} from './input-snapshot';
+
+/**
+ * Stable system name (locked by `frame-start-scan-system.test.ts`). User
+ * systems reference it through `after: [FRAME_START_SCAN_SYSTEM_NAME]`
+ * to ensure they observe the freshly written snapshot.
+ */
+export const FRAME_START_SCAN_SYSTEM_NAME = 'input-frame-start-scan';
+export const InputSet = defineSystemSet({ name: 'input' });
+
+/**
+ * Resource key under which the {@link InputBackend} producer is inserted
+ * (M2 — full resource-ification, D-2 / D-7). The frame-start scan system
+ * declares it in `resources`; the fn body reads it back via
+ * `world.getResource(INPUT_BACKEND_KEY)`.
+ *
+ * Aligns with the `INPUT_SNAPSHOT_RESOURCE_KEY` naming. Consumers import the
+ * constant rather than the bare string so a typo degrades to an import error
+ * (charter P3).
+ */
+export const INPUT_BACKEND_KEY = 'InputBackend' as const;
+
+/**
+ * The frame-start scan system token (M2 — full resource-ification, D-4).
+ *
+ * Module-level `defineSystem` with the real fn body — no factory, no closure.
+ * Each `world.update()` tick:
+ *   1. reads the {@link InputBackend} from `INPUT_BACKEND_KEY` and calls
+ *      `backend.sample()` to drain the per-frame accumulator (movement delta +
+ *      up-edge set);
+ *   2. derives a fresh `InputSnapshot` via `snapshotFromSample`;
+ *   3. writes it under `INPUT_SNAPSHOT_RESOURCE_KEY` via
+ *      `world.insertResource` -- idempotent overwrite, charter P4
+ *      consistent abstraction (consumers always read the same Resource key
+ *      regardless of which backend produced the sample).
+ *
+ * Labelled `'input'` (spec §6.2 label-anchor map).
+ */
+export const InputFrameStartScan: SystemHandle<readonly []> = defineSystem({
+  name: FRAME_START_SCAN_SYSTEM_NAME,
+  queries: [],
+  fn: (world) => {
+    const backend = world.getResource<InputBackend>(INPUT_BACKEND_KEY);
+    const sample = backend.sample();
+
+    // Action mapping: derive states from InputMap Resource + prev snapshot edges.
+    // D-6: edge baseline reuses existing prev InputSnapshot Resource (Derive,
+    // Don't Duplicate — zero new cross-frame state carrier).
+    let actionStates: ReturnType<typeof deriveActionStates> | undefined;
+    let inputMap: readonly ActionConfig[] | undefined;
+    if (world.hasResource(INPUT_MAP_KEY)) {
+      inputMap = world.getResource<readonly ActionConfig[]>(INPUT_MAP_KEY);
+      // Read prev snapshot's internal action states for edge diff.
+      // First frame: no prev snapshot → justPressed = pressed (same as Feat1 gamepad).
+      let prevActionStates: readonly ActionState[] | undefined;
+      if (world.hasResource(INPUT_SNAPSHOT_RESOURCE_KEY)) {
+        const prevSnap = world.getResource<InputSnapshot>(INPUT_SNAPSHOT_RESOURCE_KEY);
+        prevActionStates = readActionStatesForEdgeDiff(prevSnap);
+      }
+      actionStates = deriveActionStates(sample, inputMap, prevActionStates);
+    }
+
+    const previousSnapshot = world.hasResource(INPUT_SNAPSHOT_RESOURCE_KEY)
+      ? world.getResource<InputSnapshot>(INPUT_SNAPSHOT_RESOURCE_KEY)
+      : undefined;
+    const snapshot = snapshotFromSample(sample, actionStates, inputMap, previousSnapshot);
+    world.insertResource(INPUT_SNAPSHOT_RESOURCE_KEY, snapshot);
+  },
+});