@forgeax/engine-input 0.1.20 → 0.1.21

package/src/browser-backend.ts

@@ -176,7 +176,11 @@ export function attachBrowserInputBackend(
   const upEdges = new Set<string>();
   const heldCodes = new Set<string>();
   const upCodeEdges = new Set<string>();
+  const pressedKeys = new Set<string>();
+  const pressedCodes = new Set<string>();
   const buttons: [boolean, boolean, boolean] = [false, false, false];
+  const pressedButtons: [boolean, boolean, boolean] = [false, false, false];
+  const releasedButtons: [boolean, boolean, boolean] = [false, false, false];
   let mvx = 0;
   let mvy = 0;
   let wheelAccum = 0;
@@ -195,6 +199,15 @@ export function attachBrowserInputBackend(
   // gameGate is a command-set boolean (setPointerLockAllowed), default true.
   let gameGate = true;
 
+  function emitLockError(path: 'w3c' | 'provider', cause: unknown): void {
+    try {
+      options.onLockError?.({ path, cause });
+    } catch {
+      // Lock diagnostics are observational; a throwing host callback must not
+      // create a second unhandled rejection from the browser Promise path.
+    }
+  }
+
   // w8 (D-1/D-3): release the provider lock idempotently. Calls the injected
   // exitLock (routing any throw to onLockError as { path: 'provider' }) and
   // clears providerLocked unconditionally. Shared by every provider-release
@@ -205,7 +218,7 @@ export function attachBrowserInputBackend(
       try {
         options.lockProvider.exitLock();
       } catch (err: unknown) {
-        if (options.onLockError) options.onLockError({ path: 'provider', cause: err });
+        emitLockError('provider', err);
       }
     }
     providerLocked = false;
@@ -348,11 +361,11 @@ export function attachBrowserInputBackend(
       clear();
       return;
     }
+    if (!heldKeys.has(ev.key)) pressedKeys.add(ev.key);
     heldKeys.add(ev.key);
-    upEdges.delete(ev.key);
     if (ev.code) {
+      if (!heldCodes.has(ev.code)) pressedCodes.add(ev.code);
       heldCodes.add(ev.code);
-      upCodeEdges.delete(ev.code);
     }
     // w8 (D-1): ESC releases provider lock (W3C path handles ESC via browser
     // pointerlockchange). Only acts when providerLocked is true.
@@ -379,6 +392,7 @@ export function attachBrowserInputBackend(
     // Only mouse-type pointers affect the mouse button cluster (D-3).
     if (ev.pointerType === 'mouse') {
       if (ev.button === 0 || ev.button === 1 || ev.button === 2) {
+        if (!buttons[ev.button]) pressedButtons[ev.button] = true;
         buttons[ev.button] = true;
       }
     }
@@ -453,6 +467,7 @@ export function attachBrowserInputBackend(
     if (isUiEvent(ev)) return;
     if (ev.pointerType === 'mouse') {
       if (ev.button === 0 || ev.button === 1 || ev.button === 2) {
+        if (buttons[ev.button]) releasedButtons[ev.button] = true;
         buttons[ev.button] = false;
       }
     }
@@ -547,6 +562,14 @@ export function attachBrowserInputBackend(
     // sole consumer as it did before ownership routing existed.
     upEdges.clear();
     upCodeEdges.clear();
+    pressedKeys.clear();
+    pressedCodes.clear();
+    pressedButtons[0] = false;
+    pressedButtons[1] = false;
+    pressedButtons[2] = false;
+    releasedButtons[0] = false;
+    releasedButtons[1] = false;
+    releasedButtons[2] = false;
     heldKeys.clear();
     heldCodes.clear();
     buttons[0] = false;
@@ -623,6 +646,11 @@ export function attachBrowserInputBackend(
   }
   safeAdd(doc, 'pointerlockchange', onPointerLockChange as EventListener);
 
+  function onPointerLockError(event: Event): void {
+    emitLockError('w3c', event);
+  }
+  safeAdd(doc, 'pointerlockerror', onPointerLockError as EventListener);
+
   // PointerLock entry must be triggered by user activation (W3C requires
   // a click / keydown handler to call `requestPointerLock()`). The MVP
   // wires a click listener on the canvas as the activation surface;
@@ -645,9 +673,6 @@ export function attachBrowserInputBackend(
     // the cursor outside the play-game quadrant) skip the lock entirely. Default
     // is always-allow, so the standalone game runtime is unchanged.
     if (options.pointerLockAllowed && !options.pointerLockAllowed()) return;
-    // Pointer Lock requires window focus; skip silently when unfocused.
-    if (typeof doc.hasFocus === 'function' && !doc.hasFocus()) return;
-
     // D-2 / D-7: lockProvider path takes priority over W3C.
     if (options.lockProvider) {
       providerLocked = true; // D-7 optimistic placement
@@ -656,17 +681,13 @@ export function attachBrowserInputBackend(
         if (result && typeof (result as Promise<void>).catch === 'function') {
           (result as Promise<void>).catch((cause: unknown) => {
             providerLocked = false;
-            if (options.onLockError) {
-              options.onLockError({ path: 'provider', cause });
-            }
+            emitLockError('provider', cause);
           });
         }
       } catch (cause: unknown) {
         // Synchronous throw from requestLock.
         providerLocked = false;
-        if (options.onLockError) {
-          options.onLockError({ path: 'provider', cause });
-        }
+        emitLockError('provider', cause);
       }
       return;
     }
@@ -674,13 +695,15 @@ export function attachBrowserInputBackend(
     // W3C path: standard requestPointerLock.
     const fn = canvas.requestPointerLock;
     if (typeof fn !== 'function') return;
-    const r = fn.call(canvas) as unknown;
-    if (r && typeof (r as Promise<void>).catch === 'function') {
-      (r as Promise<void>).catch((cause: unknown) => {
-        if (options.onLockError) {
-          options.onLockError({ path: 'w3c', cause });
-        }
-      });
+    try {
+      const r = fn.call(canvas) as unknown;
+      if (r && typeof (r as Promise<void>).catch === 'function') {
+        (r as Promise<void>).catch((cause: unknown) => {
+          emitLockError('w3c', cause);
+        });
+      }
+    } catch (cause: unknown) {
+      emitLockError('w3c', cause);
     }
   }
   safeAdd(canvas, 'click', onCanvasClick as EventListener);
@@ -787,7 +810,19 @@ export function attachBrowserInputBackend(
       upKeys: new Set(upEdges),
       downCodes: new Set(heldCodes),
       upCodes: new Set(upCodeEdges),
+      pressedKeys: new Set(pressedKeys),
+      pressedCodes: new Set(pressedCodes),
       buttons: [buttons[0], buttons[1], buttons[2]] as readonly [boolean, boolean, boolean],
+      pressedButtons: [pressedButtons[0], pressedButtons[1], pressedButtons[2]] as readonly [
+        boolean,
+        boolean,
+        boolean,
+      ],
+      releasedButtons: [releasedButtons[0], releasedButtons[1], releasedButtons[2]] as readonly [
+        boolean,
+        boolean,
+        boolean,
+      ],
       movementX: mvx,
       movementY: mvy,
       ...(mouseX !== undefined && mouseY !== undefined ? { mouseX, mouseY } : {}),
@@ -806,6 +841,14 @@ export function attachBrowserInputBackend(
     // Reset per-frame accumulators (movement delta + key edges + wheel notches + phase queue).
     upEdges.clear();
     upCodeEdges.clear();
+    pressedKeys.clear();
+    pressedCodes.clear();
+    pressedButtons[0] = false;
+    pressedButtons[1] = false;
+    pressedButtons[2] = false;
+    releasedButtons[0] = false;
+    releasedButtons[1] = false;
+    releasedButtons[2] = false;
     mvx = 0;
     mvy = 0;
     wheelAccum = 0;
@@ -831,8 +874,10 @@ export function attachBrowserInputBackend(
   function clear(): void {
     heldKeys.clear();
     upEdges.clear();
+    pressedKeys.clear();
     heldCodes.clear();
     upCodeEdges.clear();
+    pressedCodes.clear();
     pointerMap.clear();
     phaseQueue.length = 0;
     prevGamepadFrame.clear();
@@ -841,6 +886,12 @@ export function attachBrowserInputBackend(
     buttons[0] = false;
     buttons[1] = false;
     buttons[2] = false;
+    pressedButtons[0] = false;
+    pressedButtons[1] = false;
+    pressedButtons[2] = false;
+    releasedButtons[0] = false;
+    releasedButtons[1] = false;
+    releasedButtons[2] = false;
     mvx = 0;
     mvy = 0;
     wheelAccum = 0;
@@ -866,6 +917,7 @@ export function attachBrowserInputBackend(
     safeRemove(canvas, 'wheel', onWheel as EventListener);
     safeRemove(doc, 'visibilitychange', onVisibilityChange as EventListener);
     safeRemove(doc, 'pointerlockchange', onPointerLockChange as EventListener);
+    safeRemove(doc, 'pointerlockerror', onPointerLockError as EventListener);
     safeRemove(canvas, 'click', onCanvasClick as EventListener);
     clear();
     // D-5: restore original touch-action value.

package/src/composite-backend.ts

@@ -59,7 +59,10 @@ export interface CompositeInputBackend extends InputBackend {
   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. */
+  /**
+   * Drop all injected state and pending frame edges; currently-held keys/buttons
+   * emit one clean release edge so a previously observed hold is closed.
+   */
   clearInjected(): void;
   /** Toggle the yield-to-human gate at runtime. */
   setYieldToHuman(yield_: boolean): void;
@@ -76,12 +79,22 @@ export function makeCompositeBackend(
   const buttons: [boolean, boolean, boolean] = [false, false, false];
   // Injected per-frame accumulators (drained on each sample()).
   const upEdges = new Set<string>();
+  const pressedKeys = new Set<string>();
+  const pressedButtons: [boolean, boolean, boolean] = [false, false, false];
+  const releasedButtons: [boolean, boolean, boolean] = [false, false, false];
   let mvx = 0;
   let mvy = 0;
   let wheel = 0;
 
   function injectionActive(): boolean {
-    return heldKeys.size > 0 || upEdges.size > 0 || buttons.some((b) => b);
+    return (
+      heldKeys.size > 0 ||
+      upEdges.size > 0 ||
+      pressedKeys.size > 0 ||
+      buttons.some((b) => b) ||
+      pressedButtons.some((b) => b) ||
+      releasedButtons.some((b) => b)
+    );
   }
 
   function sample(): InputBackendSample {
@@ -111,12 +124,38 @@ export function makeCompositeBackend(
       mergedUp.add(k);
     }
 
+    const mergedPressed =
+      base.pressedKeys === undefined && pressedKeys.size === 0
+        ? undefined
+        : new Set([...(base.pressedKeys ?? []), ...pressedKeys]);
+    if (yieldToHuman && base.downKeys.size > 0 && mergedPressed !== undefined) {
+      for (const key of pressedKeys) {
+        if (base.downKeys.has(key)) mergedPressed.delete(key);
+      }
+    }
+
     // 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],
     ];
+    const mergedPressedButtons =
+      base.pressedButtons === undefined && !pressedButtons.some(Boolean)
+        ? undefined
+        : ([
+            (base.pressedButtons?.[0] ?? false) || pressedButtons[0],
+            (base.pressedButtons?.[1] ?? false) || pressedButtons[1],
+            (base.pressedButtons?.[2] ?? false) || pressedButtons[2],
+          ] as const);
+    const mergedReleasedButtons =
+      base.releasedButtons === undefined && !releasedButtons.some(Boolean)
+        ? undefined
+        : ([
+            (base.releasedButtons?.[0] ?? false) || releasedButtons[0],
+            (base.releasedButtons?.[1] ?? false) || releasedButtons[1],
+            (base.releasedButtons?.[2] ?? false) || releasedButtons[2],
+          ] as const);
 
     // focused: keep true while WE are injecting, so the scan system does not
     // treat a headless/backgrounded tab (inner.focused === false) as a reason
@@ -127,7 +166,11 @@ export function makeCompositeBackend(
       ...base, // carry inner optional fields (pointers/gamepads/gestures/...) untouched
       downKeys,
       upKeys: mergedUp,
+      ...(mergedPressed === undefined ? {} : { pressedKeys: mergedPressed }),
+      ...(base.pressedCodes === undefined ? {} : { pressedCodes: base.pressedCodes }),
       buttons: mergedButtons,
+      ...(mergedPressedButtons === undefined ? {} : { pressedButtons: mergedPressedButtons }),
+      ...(mergedReleasedButtons === undefined ? {} : { releasedButtons: mergedReleasedButtons }),
       movementX: base.movementX + mvx,
       movementY: base.movementY + mvy,
       wheelDelta: base.wheelDelta + wheel,
@@ -137,6 +180,13 @@ export function makeCompositeBackend(
 
     // Drain injected per-frame accumulators (mirrors inner's own drain).
     upEdges.clear();
+    pressedKeys.clear();
+    pressedButtons[0] = false;
+    pressedButtons[1] = false;
+    pressedButtons[2] = false;
+    releasedButtons[0] = false;
+    releasedButtons[1] = false;
+    releasedButtons[2] = false;
     mvx = 0;
     mvy = 0;
     wheel = 0;
@@ -158,13 +208,15 @@ export function makeCompositeBackend(
     detach: () => inner.detach(),
 
     press(key) {
+      if (!heldKeys.has(key)) pressedKeys.add(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) {
+      if (down && !buttons[slot]) pressedButtons[slot] = true;
+      if (!down && buttons[slot]) releasedButtons[slot] = true;
       buttons[slot] = down;
     },
     addMovement(dx, dy) {
@@ -175,8 +227,23 @@ export function makeCompositeBackend(
       wheel += notches;
     },
     clearInjected() {
+      // Clearing is a lease boundary: discard every pending frame edge first,
+      // then emit only the releases required to close state that was held
+      // across the boundary. This prevents a press/release queued before a
+      // revoke from becoming a ghost edge for the next consumer.
+      upEdges.clear();
+      pressedKeys.clear();
       for (const k of heldKeys) upEdges.add(k); // clean release edge for each
       heldKeys.clear();
+      pressedButtons[0] = false;
+      pressedButtons[1] = false;
+      pressedButtons[2] = false;
+      releasedButtons[0] = false;
+      releasedButtons[1] = false;
+      releasedButtons[2] = false;
+      if (buttons[0]) releasedButtons[0] = true;
+      if (buttons[1]) releasedButtons[1] = true;
+      if (buttons[2]) releasedButtons[2] = true;
       buttons[0] = buttons[1] = buttons[2] = false;
       mvx = 0;
       mvy = 0;

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

@@ -50,8 +50,8 @@ export const INPUT_BACKEND_KEY = 'InputBackend' as const;
  * 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);
+ *      `backend.sample()` once to atomically drain the per-frame accumulators
+ *      (movement delta plus key/code/button press and release edge sets);
  *   2. derives a fresh `InputSnapshot` via `snapshotFromSample`;
  *   3. writes it under `INPUT_SNAPSHOT_RESOURCE_KEY` via
  *      `world.insertResource` -- idempotent overwrite, charter P4

package/src/input-snapshot.ts

@@ -349,12 +349,14 @@ export interface InputSnapshot {
 export interface InputBackend {
   /**
    * Produce one frame's worth of input data and reset the per-frame
-   * accumulators (movement delta + up-edge set). Held-key state and
-   * held-button state survive across calls.
+   * accumulators (movement delta + edge sets). Held-key state and
+   * held-button state survive across calls. Browser producers latch edge
+   * transitions when events arrive, so a down+up sequence between two scans
+   * remains observable instead of being lost to the held-state projection.
    *
    * Contract notes:
    * - `downKeys` is the held-key set as of the call (held across frames)
-   * - `upKeys` is the up-edge set since the previous sample (cleared
+   * - `upKeys` is the release-edge set since the previous sample (cleared
    *   after the call so the edge appears in exactly one frame)
    * - `buttons` is the held-button slot tuple `[b0, b1, b2]`
    * - `movementX` / `movementY` are the accumulated PointerLock delta
@@ -392,7 +394,15 @@ export interface InputBackendSample {
   readonly downCodes?: ReadonlySet<string>;
   /** One-frame physical code release edges, when the producer has them. */
   readonly upCodes?: ReadonlySet<string>;
+  /** Logical key press edges latched since the previous frame-start scan. */
+  readonly pressedKeys?: ReadonlySet<string>;
+  /** Physical code press edges latched since the previous frame-start scan. */
+  readonly pressedCodes?: ReadonlySet<string>;
   readonly buttons: readonly [boolean, boolean, boolean];
+  /** Mouse button press edges latched since the previous frame-start scan. */
+  readonly pressedButtons?: readonly [boolean, boolean, boolean];
+  /** Mouse button release edges latched since the previous frame-start scan. */
+  readonly releasedButtons?: readonly [boolean, boolean, boolean];
   readonly movementX: number;
   readonly movementY: number;
   /** Latest canvas-pixel mouse position; absent for non-pointer backends. */
@@ -530,35 +540,45 @@ export function snapshotFromSample(
   // a derived view of the producer's state at one instant.
   const heldKeys = new Set<string>(sample.downKeys);
   const upEdges = new Set<string>(sample.upKeys);
-  const justPressedKeys = new Set<string>();
-  for (const key of heldKeys) {
-    if (previousSnapshot === undefined || !previousSnapshot.keyboard.down(key)) {
-      justPressedKeys.add(key);
-    }
-  }
+  const justPressedKeys =
+    sample.pressedKeys === undefined
+      ? new Set<string>(
+          [...heldKeys].filter(
+            (key) => previousSnapshot === undefined || !previousSnapshot.keyboard.down(key),
+          ),
+        )
+      : new Set<string>(sample.pressedKeys);
   const heldCodes = new Set<string>(sample.downCodes ?? []);
   const upCodeEdges = new Set<string>(sample.upCodes ?? []);
-  const justPressedCodes = new Set<string>();
-  for (const code of heldCodes) {
-    if (previousSnapshot === undefined || !previousSnapshot.keyboard.downCode(code)) {
-      justPressedCodes.add(code);
-    }
-  }
+  const justPressedCodes =
+    sample.pressedCodes === undefined
+      ? new Set<string>(
+          [...heldCodes].filter(
+            (code) => previousSnapshot === undefined || !previousSnapshot.keyboard.downCode(code),
+          ),
+        )
+      : new Set<string>(sample.pressedCodes);
   const buttons: readonly [boolean, boolean, boolean] = [
     sample.buttons[0],
     sample.buttons[1],
     sample.buttons[2],
   ];
-  const justPressedButtons: readonly [boolean, boolean, boolean] = [
-    buttons[0] && (previousSnapshot === undefined || !previousSnapshot.mouse.button(0)),
-    buttons[1] && (previousSnapshot === undefined || !previousSnapshot.mouse.button(1)),
-    buttons[2] && (previousSnapshot === undefined || !previousSnapshot.mouse.button(2)),
-  ];
-  const justReleasedButtons: readonly [boolean, boolean, boolean] = [
-    sample.focusReset !== true && previousSnapshot?.mouse.button(0) === true && !buttons[0],
-    sample.focusReset !== true && previousSnapshot?.mouse.button(1) === true && !buttons[1],
-    sample.focusReset !== true && previousSnapshot?.mouse.button(2) === true && !buttons[2],
-  ];
+  const justPressedButtons: readonly [boolean, boolean, boolean] =
+    sample.pressedButtons === undefined
+      ? [
+          buttons[0] && (previousSnapshot === undefined || !previousSnapshot.mouse.button(0)),
+          buttons[1] && (previousSnapshot === undefined || !previousSnapshot.mouse.button(1)),
+          buttons[2] && (previousSnapshot === undefined || !previousSnapshot.mouse.button(2)),
+        ]
+      : [sample.pressedButtons[0], sample.pressedButtons[1], sample.pressedButtons[2]];
+  const justReleasedButtons: readonly [boolean, boolean, boolean] =
+    sample.releasedButtons === undefined
+      ? [
+          sample.focusReset !== true && previousSnapshot?.mouse.button(0) === true && !buttons[0],
+          sample.focusReset !== true && previousSnapshot?.mouse.button(1) === true && !buttons[1],
+          sample.focusReset !== true && previousSnapshot?.mouse.button(2) === true && !buttons[2],
+        ]
+      : [sample.releasedButtons[0], sample.releasedButtons[1], sample.releasedButtons[2]];
   const movementDelta = Object.freeze({ x: sample.movementX, y: sample.movementY });
   const mousePosition =
     sample.mouseX === undefined || sample.mouseY === undefined