@forgeax/engine-input 0.1.31 → 0.1.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-input",
-  "version": "0.1.31",
+  "version": "0.1.32",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -31,8 +31,8 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-ecs": "0.1.31",
-    "@forgeax/engine-plugin": "0.1.31"
+    "@forgeax/engine-ecs": "0.1.32",
+    "@forgeax/engine-plugin": "0.1.32"
   },
   "forgeax": {
     "metrics": {

package/src/__tests__/composite-backend.test.ts

@@ -92,6 +92,24 @@ describe('CompositeInputBackend merge semantics', () => {
     expect(c.sample().downKeys.has('w')).toBe(true); // still held next frame
   });
 
+  it('accepts logical keys and physical codes for both keyboard projections', () => {
+    const inner = fakeInner();
+    const c = makeCompositeBackend(inner);
+    c.press('w');
+    let sample = c.sample();
+    expect(sample.downKeys.has('w')).toBe(true);
+    expect(sample.downCodes?.has('KeyW')).toBe(true);
+    c.release('w');
+    sample = c.sample();
+    expect(sample.upKeys.has('w')).toBe(true);
+    expect(sample.upCodes?.has('KeyW')).toBe(true);
+
+    c.press('KeyW');
+    sample = c.sample();
+    expect(sample.downKeys.has('w')).toBe(true);
+    expect(sample.downCodes?.has('KeyW')).toBe(true);
+  });
+
   it('release produces an up-edge that lives exactly ONE frame', () => {
     const inner = fakeInner();
     const c = makeCompositeBackend(inner);
@@ -275,6 +293,43 @@ describe('CompositeInputBackend merge semantics', () => {
     expect(sample.releasedButtons).toBeUndefined();
   });
 
+  it('revokeInjectedLease fences late injections until a new lease opens', () => {
+    const inner = fakeInner();
+    const c = makeCompositeBackend(inner);
+    c.press('w');
+    expect(c.sample().downCodes?.has('KeyW')).toBe(true);
+    c.revokeInjectedLease();
+    c.press('a');
+    expect(c.sample().downKeys.has('a')).toBe(false);
+    c.beginInjectedLease();
+    c.press('a');
+    expect(c.sample().downCodes?.has('KeyA')).toBe(true);
+  });
+
+  it('keeps an old execution lease read-only after a later lease opens', () => {
+    const inner = fakeInner();
+    const c = makeCompositeBackend(inner);
+    const oldLease = c.createInjectedLease();
+    oldLease.press('KeyW');
+    expect(c.sample().downCodes?.has('KeyW')).toBe(true);
+
+    const currentLease = c.createInjectedLease();
+    oldLease.revokeInjectedLease();
+    oldLease.press('KeyA');
+    oldLease.setButton(0, true);
+    oldLease.addMovement(10, 20);
+    oldLease.addWheel(3);
+    expect(c.sample().downKeys.has('a')).toBe(false);
+    expect(c.sample().buttons[0]).toBe(false);
+    expect(c.sample().movementX).toBe(0);
+    expect(c.sample().wheelDelta).toBe(0);
+
+    currentLease.press('KeyD');
+    const sample = c.sample();
+    expect(sample.downKeys.has('d')).toBe(true);
+    expect(sample.downKeys.has('a')).toBe(false);
+  });
+
   it('forwards setPointerLockAllowed and detach to inner', () => {
     let allowed: boolean | undefined;
     let detached = false;

package/src/composite-backend.ts

@@ -64,22 +64,113 @@ export interface CompositeInputBackend extends InputBackend {
    * emit one clean release edge so a previously observed hold is closed.
    */
   clearInjected(): void;
+  /** Open a fresh synthetic-input lease after a previous revoke boundary. */
+  beginInjectedLease(): void;
+  /** Revoke the current lease and fence later injections until reopened. */
+  revokeInjectedLease(): void;
+  /**
+   * Create the one execution-scoped injection view. Creating a lease
+   * invalidates every previously-created view; an invalid view remains a
+   * no-op even after a later lease is opened.
+   */
+  createInjectedLease(): CompositeInputLease;
   /** Toggle the yield-to-human gate at runtime. */
   setYieldToHuman(yield_: boolean): void;
 }
 
+/**
+ * Synthetic input exposed to one eval/execution. It deliberately has no
+ * `beginInjectedLease` method: a script can release its own lease, but it
+ * cannot reopen an old reference after the host has moved to another job.
+ */
+export interface CompositeInputLease extends InputBackend {
+  press(key: string): void;
+  release(key: string): void;
+  setButton(slot: 0 | 1 | 2, down: boolean): void;
+  addMovement(dx: number, dy: number): void;
+  addWheel(notches: number): void;
+  clearInjected(): void;
+  revokeInjectedLease(): void;
+}
+
+// The public injection surface accepts either the logical KeyboardEvent.key
+// (`w`, ` `, `ArrowUp`) or the physical KeyboardEvent.code (`KeyW`, `Space`).
+// Keep both projections populated so code-first control drives games that read
+// either keyboard.down(...) or keyboard.downCode(...).
+const CODE_TO_KEY: Readonly<Record<string, string>> = {
+  Space: ' ',
+  ShiftLeft: 'Shift',
+  ShiftRight: 'Shift',
+  ControlLeft: 'Control',
+  ControlRight: 'Control',
+  AltLeft: 'Alt',
+  AltRight: 'Alt',
+  MetaLeft: 'Meta',
+  MetaRight: 'Meta',
+  BracketLeft: '[',
+  BracketRight: ']',
+  Backslash: '\\',
+  Semicolon: ';',
+  Quote: "'",
+  Comma: ',',
+  Period: '.',
+  Slash: '/',
+  Minus: '-',
+  Equal: '=',
+  Backquote: '`',
+};
+
+function keyForCode(code: string): string | undefined {
+  if (CODE_TO_KEY[code] !== undefined) return CODE_TO_KEY[code];
+  if (/^Key[A-Z]$/.test(code)) return code.slice(3).toLowerCase();
+  if (/^Digit[0-9]$/.test(code)) return code.slice(5);
+  if (/^Numpad[0-9]$/.test(code)) return code.slice(6);
+  if (/^F(?:[1-9]|1[0-2])$/.test(code)) return code;
+  if (/^Arrow(?:Up|Down|Left|Right)$/.test(code)) return code;
+  if (/^(?:Escape|Enter|Tab|Backspace|Delete|Home|End|PageUp|PageDown|Insert)$/.test(code))
+    return code;
+  return undefined;
+}
+
+function codeForKey(key: string): string | undefined {
+  if (/^[a-zA-Z]$/.test(key)) return `Key${key.toUpperCase()}`;
+  if (/^[0-9]$/.test(key)) return `Digit${key}`;
+  if (key === ' ') return 'Space';
+  if (
+    /^(?:Arrow(?:Up|Down|Left|Right)|Escape|Enter|Tab|Backspace|Delete|Home|End|PageUp|PageDown|Insert)$/.test(
+      key,
+    )
+  )
+    return key;
+  if (/^F(?:[1-9]|1[0-2])$/.test(key)) return key;
+  const entry = Object.entries(CODE_TO_KEY).find(([, value]) => value === key);
+  return entry?.[0];
+}
+
+function normalizeKey(value: string): { readonly key: string; readonly code: string | undefined } {
+  const logical = keyForCode(value);
+  return logical === undefined
+    ? { key: value, code: codeForKey(value) }
+    : { key: logical, code: value };
+}
+
 export function makeCompositeBackend(
   inner: InputBackend,
   options?: CompositeBackendOptions,
 ): CompositeInputBackend {
   let yieldToHuman = options?.yieldToHuman ?? true;
+  let leaseRevoked = false;
+  let leaseGeneration = 0;
 
   // Injected held-state (survives across frames).
   const heldKeys = new Set<string>();
+  const heldCodes = new Set<string>();
   const buttons: [boolean, boolean, boolean] = [false, false, false];
   // Injected per-frame accumulators (drained on each sample()).
   const upEdges = new Set<string>();
+  const upCodeEdges = new Set<string>();
   const pressedKeys = new Set<string>();
+  const pressedCodes = new Set<string>();
   const pressedButtons: [boolean, boolean, boolean] = [false, false, false];
   const releasedButtons: [boolean, boolean, boolean] = [false, false, false];
   let mvx = 0;
@@ -89,8 +180,11 @@ export function makeCompositeBackend(
   function injectionActive(): boolean {
     return (
       heldKeys.size > 0 ||
+      heldCodes.size > 0 ||
       upEdges.size > 0 ||
+      upCodeEdges.size > 0 ||
       pressedKeys.size > 0 ||
+      pressedCodes.size > 0 ||
       buttons.some((b) => b) ||
       pressedButtons.some((b) => b) ||
       releasedButtons.some((b) => b)
@@ -111,26 +205,79 @@ export function makeCompositeBackend(
     // 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);
+    const downCodes =
+      base.downCodes === undefined && heldCodes.size === 0
+        ? undefined
+        : new Set(base.downCodes ?? []);
     for (const k of heldKeys) {
-      if (yieldToHuman && base.downKeys.has(k)) continue; // human owns this exact key
+      const code = codeForKey(k);
+      if (
+        yieldToHuman &&
+        (base.downKeys.has(k) || (code !== undefined && base.downCodes?.has(code) === true))
+      )
+        continue; // human owns this exact key
       downKeys.add(k);
     }
+    for (const code of heldCodes) {
+      const key = keyForCode(code);
+      if (
+        yieldToHuman &&
+        (base.downCodes?.has(code) === true || (key !== undefined && base.downKeys.has(key)))
+      )
+        continue;
+      downCodes?.add(code);
+    }
 
     // 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;
+      const code = codeForKey(k);
+      if (
+        yieldToHuman &&
+        (base.downKeys.has(k) || (code !== undefined && base.downCodes?.has(code) === true))
+      )
+        continue;
       mergedUp.add(k);
     }
+    const mergedUpCodes =
+      base.upCodes === undefined && upCodeEdges.size === 0
+        ? undefined
+        : new Set(base.upCodes ?? []);
+    for (const code of upCodeEdges) {
+      const key = keyForCode(code);
+      if (
+        yieldToHuman &&
+        (base.downCodes?.has(code) === true || (key !== undefined && base.downKeys.has(key)))
+      )
+        continue;
+      mergedUpCodes?.add(code);
+    }
 
     const mergedPressed =
       base.pressedKeys === undefined && pressedKeys.size === 0
         ? undefined
         : new Set([...(base.pressedKeys ?? []), ...pressedKeys]);
-    if (yieldToHuman && base.downKeys.size > 0 && mergedPressed !== undefined) {
+    if (
+      yieldToHuman &&
+      (base.downKeys.size > 0 || (base.downCodes?.size ?? 0) > 0) &&
+      mergedPressed !== undefined
+    ) {
       for (const key of pressedKeys) {
-        if (base.downKeys.has(key)) mergedPressed.delete(key);
+        const code = codeForKey(key);
+        if (base.downKeys.has(key) || (code !== undefined && base.downCodes?.has(code) === true))
+          mergedPressed.delete(key);
+      }
+    }
+    const mergedPressedCodes =
+      base.pressedCodes === undefined && pressedCodes.size === 0
+        ? undefined
+        : new Set(base.pressedCodes ?? []);
+    if (yieldToHuman && mergedPressedCodes !== undefined) {
+      for (const code of pressedCodes) {
+        const key = keyForCode(code);
+        if (base.downCodes?.has(code) === true || (key !== undefined && base.downKeys.has(key)))
+          mergedPressedCodes.delete(code);
       }
     }
 
@@ -166,8 +313,10 @@ export function makeCompositeBackend(
       ...base, // carry inner optional fields (pointers/gamepads/gestures/...) untouched
       downKeys,
       upKeys: mergedUp,
+      ...(downCodes === undefined ? {} : { downCodes }),
+      ...(mergedUpCodes === undefined ? {} : { upCodes: mergedUpCodes }),
       ...(mergedPressed === undefined ? {} : { pressedKeys: mergedPressed }),
-      ...(base.pressedCodes === undefined ? {} : { pressedCodes: base.pressedCodes }),
+      ...(mergedPressedCodes === undefined ? {} : { pressedCodes: mergedPressedCodes }),
       buttons: mergedButtons,
       ...(mergedPressedButtons === undefined ? {} : { pressedButtons: mergedPressedButtons }),
       ...(mergedReleasedButtons === undefined ? {} : { releasedButtons: mergedReleasedButtons }),
@@ -180,7 +329,9 @@ export function makeCompositeBackend(
 
     // Drain injected per-frame accumulators (mirrors inner's own drain).
     upEdges.clear();
+    upCodeEdges.clear();
     pressedKeys.clear();
+    pressedCodes.clear();
     pressedButtons[0] = false;
     pressedButtons[1] = false;
     pressedButtons[2] = false;
@@ -201,54 +352,146 @@ export function makeCompositeBackend(
     ? { setPointerLockAllowed: (allowed: boolean) => inner.setPointerLockAllowed?.(allowed) }
     : {};
 
+  const clearInjected = (): void => {
+    // 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();
+    upCodeEdges.clear();
+    pressedKeys.clear();
+    pressedCodes.clear();
+    for (const k of heldKeys) upEdges.add(k);
+    for (const code of heldCodes) upCodeEdges.add(code);
+    heldKeys.clear();
+    heldCodes.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;
+    wheel = 0;
+  };
+
+  const beginInjectedLease = (): void => {
+    // A new boundary must invalidate old references. Merely flipping a global
+    // boolean would let an async script keep writing after a later job opens.
+    leaseGeneration += 1;
+    leaseRevoked = false;
+    clearInjected();
+  };
+  const revokeInjectedLease = (): void => {
+    leaseGeneration += 1;
+    leaseRevoked = true;
+    clearInjected();
+  };
+
+  const createInjectedLease = (): CompositeInputLease => {
+    beginInjectedLease();
+    const generation = leaseGeneration;
+    const active = (): boolean => !leaseRevoked && generation === leaseGeneration;
+    return {
+      sample,
+      detach: () => {},
+      press(key) {
+        if (!active()) return;
+        const normalized = normalizeKey(key);
+        if (!heldKeys.has(normalized.key)) pressedKeys.add(normalized.key);
+        heldKeys.add(normalized.key);
+        if (normalized.code !== undefined) {
+          if (!heldCodes.has(normalized.code)) pressedCodes.add(normalized.code);
+          heldCodes.add(normalized.code);
+        }
+      },
+      release(key) {
+        if (!active()) return;
+        const normalized = normalizeKey(key);
+        if (heldKeys.delete(normalized.key)) upEdges.add(normalized.key);
+        if (normalized.code !== undefined && heldCodes.delete(normalized.code))
+          upCodeEdges.add(normalized.code);
+      },
+      setButton(slot, down) {
+        if (!active()) return;
+        if (down && !buttons[slot]) pressedButtons[slot] = true;
+        if (!down && buttons[slot]) releasedButtons[slot] = true;
+        buttons[slot] = down;
+      },
+      addMovement(dx, dy) {
+        if (!active()) return;
+        mvx += dx;
+        mvy += dy;
+      },
+      addWheel(notches) {
+        if (!active()) return;
+        wheel += notches;
+      },
+      clearInjected() {
+        if (active()) clearInjected();
+      },
+      revokeInjectedLease() {
+        if (active()) revokeInjectedLease();
+      },
+    };
+  };
+
   return {
     sample,
     ...lockGate,
-    // Teardown belongs to the human backend -- forward it.
-    detach: () => inner.detach(),
+    // Teardown belongs to the human backend -- revoke the synthetic lease
+    // first, then forward the physical listener teardown.  `clear()` is also
+    // exposed so an owner can revoke input without detaching the browser.
+    clear: () => {
+      clearInjected();
+      inner.clear?.();
+    },
+    detach: () => {
+      clearInjected();
+      inner.detach();
+    },
 
     press(key) {
-      if (!heldKeys.has(key)) pressedKeys.add(key);
-      heldKeys.add(key);
+      if (leaseRevoked) return;
+      const normalized = normalizeKey(key);
+      if (!heldKeys.has(normalized.key)) pressedKeys.add(normalized.key);
+      heldKeys.add(normalized.key);
+      if (normalized.code !== undefined) {
+        if (!heldCodes.has(normalized.code)) pressedCodes.add(normalized.code);
+        heldCodes.add(normalized.code);
+      }
     },
     release(key) {
-      if (heldKeys.delete(key)) upEdges.add(key); // held -> emit one up-edge
+      if (leaseRevoked) return;
+      const normalized = normalizeKey(key);
+      if (heldKeys.delete(normalized.key)) upEdges.add(normalized.key); // held -> emit one up-edge
+      if (normalized.code !== undefined && heldCodes.delete(normalized.code))
+        upCodeEdges.add(normalized.code);
     },
     setButton(slot, down) {
+      if (leaseRevoked) return;
       if (down && !buttons[slot]) pressedButtons[slot] = true;
       if (!down && buttons[slot]) releasedButtons[slot] = true;
       buttons[slot] = down;
     },
     addMovement(dx, dy) {
+      if (leaseRevoked) return;
       mvx += dx;
       mvy += dy;
     },
     addWheel(notches) {
+      if (leaseRevoked) return;
       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;
-      wheel = 0;
-    },
+    clearInjected,
+    beginInjectedLease,
+    revokeInjectedLease,
+    createInjectedLease,
     setYieldToHuman(yield_) {
       yieldToHuman = yield_;
     },

package/src/index.ts

@@ -48,6 +48,7 @@ export {
 export {
   type CompositeBackendOptions,
   type CompositeInputBackend,
+  type CompositeInputLease,
   makeCompositeBackend,
 } from './composite-backend';
 export {