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

package/src/__tests__/canvas-input-owner.test-d.ts

@@ -0,0 +1,39 @@
+/// <reference types="node" />
+
+import { readFileSync } from 'node:fs';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { CanvasInputBoundary } from '../canvas-input-boundary.js';
+
+type CanvasInputOwner = ReturnType<CanvasInputBoundary['owner']>;
+type ExpectedCanvasInputOwner = 'editor' | 'game';
+
+const canvasInputBoundarySource = readFileSync(
+  new URL('../canvas-input-boundary.ts', import.meta.url),
+  'utf8',
+);
+
+describe('canvas input owner', () => {
+  it('keeps the public owner vocabulary exact and bilateral', () => {
+    expectTypeOf<CanvasInputOwner>().toEqualTypeOf<ExpectedCanvasInputOwner>();
+    expectTypeOf<ExpectedCanvasInputOwner>().toEqualTypeOf<CanvasInputOwner>();
+    expectTypeOf<CanvasInputBoundary['owner']>().toEqualTypeOf<() => ExpectedCanvasInputOwner>();
+
+    const acceptsOwner = (owner: CanvasInputOwner): CanvasInputOwner => owner;
+    acceptsOwner('editor');
+    acceptsOwner('game');
+    // @ts-expect-error Unknown roles remain outside the closed owner vocabulary.
+    acceptsOwner('preview');
+  });
+
+  it('derives both private consumer views from the public owner method', () => {
+    expect(canvasInputBoundarySource).toContain(
+      "type CanvasInputOwner = ReturnType<CanvasInputBoundary['owner']>;",
+    );
+    expect(canvasInputBoundarySource).toContain("let active: CanvasInputOwner = 'editor';");
+    expect(canvasInputBoundarySource).toContain(
+      'const routed = (consumer: CanvasInputOwner): InputBackend => ({',
+    );
+    expect(canvasInputBoundarySource).not.toContain("let active: 'editor' | 'game'");
+    expect(canvasInputBoundarySource).not.toContain("const routed = (consumer: 'editor' | 'game')");
+  });
+});

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

@@ -0,0 +1,299 @@
+// composite-backend.test.ts -- merge-semantics contract for the
+// CompositeInputBackend decorator.
+//
+// WHY this backend exists: an AI (or a record/replay harness) needs to feed
+// synthetic input into the SAME `INPUT_BACKEND_KEY` world resource a human's
+// browser backend occupies -- WITHOUT evicting the human (PIE + human-as-final-
+// authority: a human can take over at any instant). Replacing the resource
+// would lock the human out; a decorator merges both sources so they coexist.
+//
+// The scan system calls `backend.sample()` exactly once per frame and RELIES on
+// its side effects (up-edge / movement / wheel accumulators drain on read).
+// So the composite must call `inner.sample()` exactly once and merge the
+// injected state field-by-field, honoring each field's lifecycle:
+//
+//   downKeys   held across frames         -> UNION(inner, injected.held)
+//   upKeys     lives exactly ONE frame    -> UNION, injected side drained here
+//   buttons    held tuple                 -> OR per slot
+//   movementX/Y, wheelDelta  accumulators -> SUM, injected side drained here
+//   focused    gates up-edge suppression  -> inner.focused || injectedActive
+//   pointerLocked                          -> inner (AI never fabricates a lock)
+//
+// yieldToHuman (default ON): a human-held key suppresses injected state only for
+// that SAME key in that frame, so the AI never fights the human for that key while
+// unrelated synthetic input can continue. This is the structural "human wins" gate.
+
+import { describe, expect, it } from 'vitest';
+// Import from the leaf modules, not the '../index' barrel: the barrel re-exports
+// frame-start-scan-system, which value-imports @forgeax/engine-ecs and would drag
+// an (unbuilt-dist) runtime dependency into this pure unit test. composite-backend
+// and input-snapshot have no engine-ecs dependency.
+import { makeCompositeBackend } from '../composite-backend';
+import type { InputBackend, InputBackendSample } from '../input-snapshot';
+
+/** Minimal programmable stand-in for the human/browser backend. */
+function fakeInner(init?: Partial<InputBackendSample>): InputBackend & {
+  set: (patch: Partial<InputBackendSample>) => void;
+  sampleCalls: () => number;
+} {
+  let calls = 0;
+  let state: InputBackendSample = {
+    downKeys: new Set<string>(),
+    upKeys: new Set<string>(),
+    buttons: [false, false, false],
+    movementX: 0,
+    movementY: 0,
+    wheelDelta: 0,
+    focused: true,
+    pointerLocked: false,
+    ...init,
+  };
+  return {
+    sample(): InputBackendSample {
+      calls++;
+      const out = { ...state, downKeys: new Set(state.downKeys), upKeys: new Set(state.upKeys) };
+      // Mirror the real backend: accumulators drain on read.
+      state = { ...state, upKeys: new Set(), movementX: 0, movementY: 0, wheelDelta: 0 };
+      return out;
+    },
+    detach() {},
+    set(patch) {
+      state = { ...state, ...patch };
+    },
+    sampleCalls: () => calls,
+  };
+}
+
+describe('CompositeInputBackend merge semantics', () => {
+  it('calls inner.sample() exactly once per composite.sample() (respects side effects)', () => {
+    const inner = fakeInner();
+    const c = makeCompositeBackend(inner);
+    c.sample();
+    c.sample();
+    expect(inner.sampleCalls()).toBe(2);
+  });
+
+  it('downKeys is the UNION of human-held and AI-injected keys', () => {
+    // yieldToHuman OFF so overlap coexists -- pure union semantics. (The default
+    // yield behavior is covered separately in the yieldToHuman describe block.)
+    const inner = fakeInner({ downKeys: new Set(['d']) });
+    const c = makeCompositeBackend(inner, { yieldToHuman: false });
+    c.press('w');
+    const s = c.sample();
+    expect(s.downKeys.has('w')).toBe(true); // AI
+    expect(s.downKeys.has('d')).toBe(true); // human
+  });
+
+  it('injected key stays held across frames until released', () => {
+    const inner = fakeInner();
+    const c = makeCompositeBackend(inner);
+    c.press('w');
+    expect(c.sample().downKeys.has('w')).toBe(true);
+    expect(c.sample().downKeys.has('w')).toBe(true); // still held next frame
+  });
+
+  it('release produces an up-edge that lives exactly ONE frame', () => {
+    const inner = fakeInner();
+    const c = makeCompositeBackend(inner);
+    c.press('w');
+    c.sample(); // held
+    c.release('w');
+    const s1 = c.sample();
+    expect(s1.upKeys.has('w')).toBe(true); // edge appears once
+    expect(s1.downKeys.has('w')).toBe(false); // no longer held
+    const s2 = c.sample();
+    expect(s2.upKeys.has('w')).toBe(false); // and is gone the next frame
+  });
+
+  it('merges human and AI up-edges in the same frame', () => {
+    const inner = fakeInner({ upKeys: new Set(['d']) });
+    const c = makeCompositeBackend(inner);
+    c.press('w');
+    c.sample();
+    c.release('w');
+    inner.set({ upKeys: new Set(['d']) });
+    const s = c.sample();
+    expect(s.upKeys.has('w')).toBe(true); // AI
+    expect(s.upKeys.has('d')).toBe(true); // human
+  });
+
+  it('buttons are OR-merged per slot (AI never clears a human button)', () => {
+    const inner = fakeInner({ buttons: [false, true, false] });
+    const c = makeCompositeBackend(inner);
+    c.setButton(0, true);
+    const s = c.sample();
+    expect(s.buttons).toEqual([true, true, false]);
+  });
+
+  it('movement + wheel accumulators are SUMMED and the injected side drains on read', () => {
+    const inner = fakeInner({ movementX: 3, movementY: -2, wheelDelta: 1 });
+    const c = makeCompositeBackend(inner);
+    c.addMovement(10, 20);
+    c.addWheel(2);
+    const s1 = c.sample();
+    expect(s1.movementX).toBe(13);
+    expect(s1.movementY).toBe(18);
+    expect(s1.wheelDelta).toBe(3);
+    // Injected accumulator must reset (inner already drains itself).
+    const s2 = c.sample();
+    expect(s2.movementX).toBe(0);
+    expect(s2.movementY).toBe(0);
+    expect(s2.wheelDelta).toBe(0);
+  });
+
+  it('focused is forced true while AI injection is active (so scan does not suppress AI up-edges)', () => {
+    const inner = fakeInner({ focused: false }); // headless / backgrounded tab
+    const c = makeCompositeBackend(inner);
+    c.press('w');
+    expect(c.sample().focused).toBe(true);
+  });
+
+  it('focused falls back to inner when there is no active injection', () => {
+    const inner = fakeInner({ focused: false });
+    const c = makeCompositeBackend(inner);
+    expect(c.sample().focused).toBe(false);
+    inner.set({ focused: true });
+    expect(c.sample().focused).toBe(true);
+  });
+
+  it('pointerLocked passes through from inner (AI cannot fabricate a lock)', () => {
+    const inner = fakeInner({ pointerLocked: true });
+    const c = makeCompositeBackend(inner);
+    c.press('w');
+    expect(c.sample().pointerLocked).toBe(true);
+  });
+
+  describe('yieldToHuman gate (human-as-final-authority) — PER-KEY', () => {
+    it('the human wins only the SAME key; unrelated AI keys coexist', () => {
+      const inner = fakeInner();
+      const c = makeCompositeBackend(inner); // yieldToHuman defaults ON
+      c.press('w');
+      expect(c.sample().downKeys.has('w')).toBe(true); // AI drives while human idle
+
+      // Human presses a DIFFERENT key (d): AI's w survives, human's d is added —
+      // they coexist. This is the key difference from a global-yield gate.
+      inner.set({ downKeys: new Set(['d']) });
+      const s = c.sample();
+      expect(s.downKeys.has('d')).toBe(true); // human's key
+      expect(s.downKeys.has('w')).toBe(true); // AI's DIFFERENT key still lives
+
+      inner.set({ downKeys: new Set() });
+      expect(c.sample().downKeys.has('w')).toBe(true); // AI still held
+    });
+
+    it('a human press on the SAME key the AI holds suppresses the AI copy (no double-count)', () => {
+      const inner = fakeInner();
+      const c = makeCompositeBackend(inner);
+      c.press('w');
+      // Human grabs the SAME key. downKeys still has 'w' exactly once (Set), but the
+      // AI copy is suppressed so releasing the AI key does not linger under the human.
+      inner.set({ downKeys: new Set(['w']) });
+      expect(c.sample().downKeys.has('w')).toBe(true); // present via the human
+
+      // Human lets go while AI still holds w -> AI resumes ownership of w.
+      inner.set({ downKeys: new Set() });
+      expect(c.sample().downKeys.has('w')).toBe(true);
+    });
+
+    it('suppresses an injected up-edge while the human still holds that same key', () => {
+      const inner = fakeInner();
+      const c = makeCompositeBackend(inner);
+      c.press('w');
+      c.sample();
+
+      // The human takes w, then the AI releases its now-yielded copy. The composite
+      // must not tell the scan system that w went up while the human still holds it.
+      inner.set({ downKeys: new Set(['w']) });
+      c.release('w');
+      const s = c.sample();
+      expect(s.downKeys.has('w')).toBe(true);
+      expect(s.upKeys.has('w')).toBe(false);
+
+      // The injected edge was drained with the sample, so releasing the human key
+      // later is represented only by the human backend's own edge.
+      inner.set({ downKeys: new Set(), upKeys: new Set(['w']) });
+      const afterHumanRelease = c.sample();
+      expect(afterHumanRelease.downKeys.has('w')).toBe(false);
+      expect(afterHumanRelease.upKeys.has('w')).toBe(true);
+    });
+
+    it('with yieldToHuman disabled, AI and human coexist even on the SAME key', () => {
+      const inner = fakeInner({ downKeys: new Set(['w']) });
+      const c = makeCompositeBackend(inner, { yieldToHuman: false });
+      c.press('w');
+      const s = c.sample();
+      expect(s.downKeys.has('w')).toBe(true); // union collapses to one anyway
+    });
+
+    it('setYieldToHuman toggles the SAME-key gate at runtime', () => {
+      const inner = fakeInner({ downKeys: new Set(['w']) }); // human holds w
+      const c = makeCompositeBackend(inner);
+      c.press('w'); // AI also holds w
+      // With yield on, the AI copy of w is suppressed; the human still supplies w,
+      // so to observe the gate we track a SECOND AI-only key and the up-edge behavior.
+      c.press('a'); // AI-only key (human not pressing it)
+      let s = c.sample();
+      expect(s.downKeys.has('a')).toBe(true); // AI-only key always lives
+      expect(s.downKeys.has('w')).toBe(true); // supplied by the human
+      // Disable yield: nothing changes for a union of held keys (w still one entry).
+      c.setYieldToHuman(false);
+      s = c.sample();
+      expect(s.downKeys.has('w')).toBe(true);
+      expect(s.downKeys.has('a')).toBe(true);
+    });
+  });
+
+  it('clearInjected drops all AI state (held keys become up-edges once)', () => {
+    const inner = fakeInner();
+    const c = makeCompositeBackend(inner);
+    c.press('w');
+    c.press('a');
+    c.sample();
+    c.clearInjected();
+    const s = c.sample();
+    expect(s.downKeys.has('w')).toBe(false);
+    expect(s.downKeys.has('a')).toBe(false);
+    expect(s.upKeys.has('w')).toBe(true); // clean release edge
+    expect(s.upKeys.has('a')).toBe(true);
+  });
+
+  it('forwards setPointerLockAllowed and detach to inner', () => {
+    let allowed: boolean | undefined;
+    let detached = false;
+    const inner: InputBackend = {
+      sample: () => ({
+        downKeys: new Set(),
+        upKeys: new Set(),
+        buttons: [false, false, false],
+        movementX: 0,
+        movementY: 0,
+        wheelDelta: 0,
+        focused: true,
+        pointerLocked: false,
+      }),
+      setPointerLockAllowed: (a) => {
+        allowed = a;
+      },
+      detach: () => {
+        detached = true;
+      },
+    };
+    const c = makeCompositeBackend(inner);
+    c.setPointerLockAllowed?.(false);
+    expect(allowed).toBe(false);
+    c.detach();
+    expect(detached).toBe(true);
+  });
+
+  it('preserves inner optional fields (pointerEvents/pointers) untouched', () => {
+    const inner = fakeInner();
+    inner.set({
+      pointerEvents: [
+        { pointerId: 1, phase: 'down', x: 5, y: 6, pressure: 1, pointerType: 'mouse' },
+      ],
+    });
+    const c = makeCompositeBackend(inner);
+    const s = c.sample();
+    expect(s.pointerEvents?.[0]?.phase).toBe('down');
+  });
+});

package/src/__tests__/controller-platform-owner.test-d.ts

@@ -0,0 +1,46 @@
+/// <reference types="node" />
+
+import { readFileSync } from 'node:fs';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { ControllerPlatform } from '../controller-db.js';
+import { platformFromUserAgent } from '../controller-db.js';
+
+type ExpectedControllerPlatform = 'Windows' | 'Mac OS X' | 'Linux' | 'Android' | 'iOS';
+
+const controllerDbSource = readFileSync(new URL('../controller-db.ts', import.meta.url), 'utf8');
+
+describe('controller platform owner', () => {
+  it('keeps the exact public membership and producer declaration', () => {
+    expectTypeOf<ControllerPlatform>().toEqualTypeOf<ExpectedControllerPlatform>();
+    expectTypeOf<ExpectedControllerPlatform>().toEqualTypeOf<ControllerPlatform>();
+    expectTypeOf(platformFromUserAgent).toEqualTypeOf<
+      (ua: string) => ControllerPlatform | undefined
+    >();
+
+    const acceptsPlatform = (platform: ControllerPlatform): ControllerPlatform => platform;
+    acceptsPlatform('Windows');
+    acceptsPlatform('Mac OS X');
+    acceptsPlatform('Linux');
+    acceptsPlatform('Android');
+    acceptsPlatform('iOS');
+    // @ts-expect-error unknown platform labels remain outside the closed union.
+    acceptsPlatform('platform-not-real');
+  });
+
+  it('derives the public union and user-agent output from one private tuple', () => {
+    expect(controllerDbSource).toContain(
+      "const CONTROLLER_PLATFORMS = ['Windows', 'Mac OS X', 'Linux', 'Android', 'iOS'] as const;",
+    );
+    expect(controllerDbSource).toContain(
+      'export type ControllerPlatform = (typeof CONTROLLER_PLATFORMS)[number];',
+    );
+    expect(controllerDbSource).toContain('return CONTROLLER_PLATFORMS[4];');
+    expect(controllerDbSource).toContain('return CONTROLLER_PLATFORMS[3];');
+    expect(controllerDbSource).toContain('return CONTROLLER_PLATFORMS[0];');
+    expect(controllerDbSource).toContain('return CONTROLLER_PLATFORMS[1];');
+    expect(controllerDbSource).toContain('return CONTROLLER_PLATFORMS[2];');
+    expect(controllerDbSource).not.toContain(
+      "export type ControllerPlatform = 'Windows' | 'Mac OS X' | 'Linux' | 'Android' | 'iOS';",
+    );
+  });
+});

package/src/__tests__/input-snapshot.test-d.ts

@@ -0,0 +1,78 @@
+// input-snapshot.test-d.ts -- compile-time assertions for AC-07.
+//
+// Anchors:
+// - mouse.button(i) accepts the literal union 0 | 1 | 2 (W3C MouseEvent.button:
+//   0=primary, 1=auxiliary, 2=secondary; plan-strategy section 2.10 D-5).
+// - mouse.button(3) is a TS error (literal-narrowing rejects out-of-range).
+// - keyboard.down/justPressed/up plus physical-code readers return boolean
+//   (not unknown / not Result).
+//
+// charter awareness:
+// - F2 minimal surface: keyboard read points are locked at compile time
+// - P3 explicit failure: invalid button index is a compile-time error,
+//   not a silent runtime fallback (no string parsing, no number coercion)
+
+import { describe, expectTypeOf, it } from 'vitest';
+import { createInputSnapshot, type InputSnapshot } from '../index';
+
+describe('InputSnapshot type surface (AC-07)', () => {
+  it('keyboard.down accepts string and returns boolean', () => {
+    const snap: InputSnapshot = createInputSnapshot();
+    expectTypeOf(snap.keyboard.down).parameter(0).toEqualTypeOf<string>();
+    expectTypeOf(snap.keyboard.down('w')).toEqualTypeOf<boolean>();
+  });
+
+  it('keyboard.up accepts string and returns boolean', () => {
+    const snap: InputSnapshot = createInputSnapshot();
+    expectTypeOf(snap.keyboard.up).parameter(0).toEqualTypeOf<string>();
+    expectTypeOf(snap.keyboard.up('w')).toEqualTypeOf<boolean>();
+  });
+
+  it('keyboard.justPressed accepts string and returns boolean', () => {
+    const snap: InputSnapshot = createInputSnapshot();
+    expectTypeOf(snap.keyboard.justPressed).parameter(0).toEqualTypeOf<string>();
+    expectTypeOf(snap.keyboard.justPressed('w')).toEqualTypeOf<boolean>();
+  });
+
+  it('keyboard code readers accept string and return boolean', () => {
+    const snap: InputSnapshot = createInputSnapshot();
+    expectTypeOf(snap.keyboard.downCode).parameter(0).toEqualTypeOf<string>();
+    expectTypeOf(snap.keyboard.justPressedCode).parameter(0).toEqualTypeOf<string>();
+    expectTypeOf(snap.keyboard.upCode).parameter(0).toEqualTypeOf<string>();
+    expectTypeOf(snap.keyboard.downCode('KeyA')).toEqualTypeOf<boolean>();
+  });
+
+  it('mouse.movementDelta has shape { x: number; y: number }', () => {
+    const snap: InputSnapshot = createInputSnapshot();
+    expectTypeOf(snap.mouse.movementDelta).toEqualTypeOf<{
+      readonly x: number;
+      readonly y: number;
+    }>();
+  });
+
+  it('mouse.position has shape { x: number; y: number }', () => {
+    const snap: InputSnapshot = createInputSnapshot();
+    expectTypeOf(snap.mouse.position).toEqualTypeOf<
+      { readonly x: number; readonly y: number } | undefined
+    >();
+  });
+
+  it('mouse.pointerLocked returns boolean (required, alongside movementDelta)', () => {
+    const snap: InputSnapshot = createInputSnapshot();
+    expectTypeOf(snap.mouse.pointerLocked).toEqualTypeOf<boolean>();
+  });
+
+  it('mouse button edge readers accept the literal union and return boolean', () => {
+    const snap: InputSnapshot = createInputSnapshot();
+    expectTypeOf(snap.mouse.justPressed(0)).toEqualTypeOf<boolean>();
+    expectTypeOf(snap.mouse.justReleased(0)).toEqualTypeOf<boolean>();
+  });
+
+  it('mouse.button(3) is a TS compile error (literal-narrowing rejects out-of-range)', () => {
+    const snap: InputSnapshot = createInputSnapshot();
+    // @ts-expect-error -- 3 is not assignable to 0 | 1 | 2 (charter P3 explicit failure)
+    snap.mouse.button(3);
+    // @ts-expect-error -- arbitrary number is not assignable either
+    snap.mouse.button(42 as number);
+  });
+});

package/src/__tests__/input-snapshot.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  createEmptyInputBackendSample,
+  type InputBackendSample,
+  snapshotFromSample,
+} from '../input-snapshot';
+
+function sample(
+  downKeys: string[],
+  upKeys: string[] = [],
+  downCodes: string[] = [],
+  upCodes: string[] = [],
+): InputBackendSample {
+  return {
+    downKeys: new Set(downKeys),
+    upKeys: new Set(upKeys),
+    downCodes: new Set(downCodes),
+    upCodes: new Set(upCodes),
+    buttons: [false, false, false],
+    movementX: 0,
+    movementY: 0,
+    wheelDelta: 0,
+    focused: true,
+    pointerLocked: false,
+  };
+}
+
+describe('keyboard snapshot edges', () => {
+  it('derives justPressed from the previous frozen snapshot', () => {
+    const first = snapshotFromSample(sample(['a']));
+    const held = snapshotFromSample(sample(['a']), undefined, undefined, first);
+    const released = snapshotFromSample(sample([], ['a']), undefined, undefined, held);
+
+    expect(first.keyboard.down('a')).toBe(true);
+    expect(first.keyboard.justPressed('a')).toBe(true);
+    expect(held.keyboard.justPressed('a')).toBe(false);
+    expect(released.keyboard.down('a')).toBe(false);
+    expect(released.keyboard.up('a')).toBe(true);
+  });
+
+  it('keeps code-like and logical key strings as independent read points', () => {
+    const snap = snapshotFromSample(sample(['?'], [], ['KeyA']));
+
+    expect(snap.keyboard.down('?')).toBe(true);
+    expect(snap.keyboard.justPressed('?')).toBe(true);
+    expect(snap.keyboard.downCode('KeyA')).toBe(true);
+    expect(snap.keyboard.justPressedCode('KeyA')).toBe(true);
+  });
+});
+
+describe('empty backend sample ownership', () => {
+  it('keeps the neutral sample owner out of the public root', async () => {
+    const root = (await import('../index')) as Record<string, unknown>;
+    const empty = createEmptyInputBackendSample();
+
+    expect(root).not.toHaveProperty('createEmptyInputBackendSample');
+    expect(empty.downKeys.size).toBe(0);
+    expect(empty.upKeys.size).toBe(0);
+    expect(empty.buttons).toEqual([false, false, false]);
+    expect(empty.movementX).toBe(0);
+    expect(empty.movementY).toBe(0);
+    expect(empty.wheelDelta).toBe(0);
+    expect(empty.focused).toBe(true);
+    expect(empty.pointerLocked).toBe(false);
+  });
+});
+
+describe('mouse snapshot edges', () => {
+  it('derives primary-button held, press, and release edges from snapshots', () => {
+    const first = snapshotFromSample({
+      ...sample([]),
+      buttons: [true, false, false],
+    });
+    const held = snapshotFromSample(
+      { ...sample([]), buttons: [true, false, false] },
+      undefined,
+      undefined,
+      first,
+    );
+    const released = snapshotFromSample(
+      { ...sample([]), buttons: [false, false, false] },
+      undefined,
+      undefined,
+      held,
+    );
+
+    expect(first.mouse.button(0)).toBe(true);
+    expect(first.mouse.justPressed(0)).toBe(true);
+    expect(first.mouse.justReleased(0)).toBe(false);
+    expect(held.mouse.justPressed(0)).toBe(false);
+    expect(held.mouse.justReleased(0)).toBe(false);
+    expect(released.mouse.button(0)).toBe(false);
+    expect(released.mouse.justReleased(0)).toBe(true);
+  });
+});

package/src/__tests__/swipe-direction-owner.test-d.ts

@@ -0,0 +1,45 @@
+/// <reference types="node" />
+
+import { readFileSync } from 'node:fs';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { SwipeDirection } from '../gesture-recognizer.js';
+
+type ExpectedSwipeDirection = 'left' | 'right' | 'up' | 'down';
+
+const gestureRecognizerSource = readFileSync(
+  new URL('../gesture-recognizer.ts', import.meta.url),
+  'utf8',
+);
+
+describe('swipe direction owner', () => {
+  it('keeps the exact public membership and producer declaration', () => {
+    expectTypeOf<SwipeDirection>().toEqualTypeOf<ExpectedSwipeDirection>();
+    expectTypeOf<ExpectedSwipeDirection>().toEqualTypeOf<SwipeDirection>();
+
+    const acceptsDirection = (direction: SwipeDirection): SwipeDirection => direction;
+    acceptsDirection('left');
+    acceptsDirection('right');
+    acceptsDirection('up');
+    acceptsDirection('down');
+    // @ts-expect-error unknown direction labels remain outside the closed union.
+    acceptsDirection('direction-not-real');
+  });
+
+  it('derives the public union and dominant-axis output from one private tuple', () => {
+    expect(gestureRecognizerSource).toContain(
+      "const SWIPE_DIRECTIONS = ['left', 'right', 'up', 'down'] as const;",
+    );
+    expect(gestureRecognizerSource).toContain(
+      'export type SwipeDirection = (typeof SWIPE_DIRECTIONS)[number];',
+    );
+    expect(gestureRecognizerSource).toContain(
+      'if (Math.abs(dx) >= Math.abs(dy)) return dx >= 0 ? SWIPE_DIRECTIONS[1] : SWIPE_DIRECTIONS[0];',
+    );
+    expect(gestureRecognizerSource).toContain(
+      'return dy >= 0 ? SWIPE_DIRECTIONS[3] : SWIPE_DIRECTIONS[2];',
+    );
+    expect(gestureRecognizerSource).not.toContain(
+      "export type SwipeDirection = 'left' | 'right' | 'up' | 'down';",
+    );
+  });
+});

package/src/__tests__/ui-input-matrix.test.ts

@@ -0,0 +1,31 @@
+// @vitest-environment jsdom
+
+import { describe, expect, it } from 'vitest';
+
+import { isUiOwnedEvent } from '../ui-ownership';
+
+describe('UI input ownership matrix', () => {
+  it.each(['input', 'select', 'range', 'checkbox', 'contenteditable'])('%s is UI-owned', (kind) => {
+    const root = document.createElement('div');
+    const element =
+      kind === 'contenteditable'
+        ? document.createElement('div')
+        : kind === 'select'
+          ? document.createElement('select')
+          : document.createElement('input');
+    if (kind === 'contenteditable') element.contentEditable = 'true';
+    if (kind === 'range' || kind === 'checkbox') element.setAttribute('type', kind);
+    root.append(element);
+    const event = new KeyboardEvent('keydown', { bubbles: true, composed: true, key: 'a' });
+    element.dispatchEvent(event);
+    expect(isUiOwnedEvent(event, root)).toBe(true);
+  });
+
+  it('leaves a canvas gameplay event outside the UI root', () => {
+    const root = document.createElement('div');
+    const canvas = document.createElement('canvas');
+    const event = new KeyboardEvent('keydown', { bubbles: true, key: 'a' });
+    canvas.dispatchEvent(event);
+    expect(isUiOwnedEvent(event, root)).toBe(false);
+  });
+});

package/src/__tests__/ui-ownership-edge.test.ts

@@ -0,0 +1,33 @@
+// @vitest-environment jsdom
+
+import { describe, expect, it } from 'vitest';
+
+import { resolveUiOwnership } from '../ui-ownership';
+
+describe('UI ownership fallback paths', () => {
+  it('reports target fallback when composedPath is unavailable', () => {
+    const root = document.createElement('div');
+    const child = document.createElement('input');
+    root.append(child);
+    const event = new Event('keydown');
+    Object.defineProperty(event, 'target', { configurable: true, value: child });
+    Object.defineProperty(event, 'composedPath', { configurable: true, value: undefined });
+
+    expect(resolveUiOwnership(event, root)).toEqual({
+      owned: true,
+      source: 'target-fallback',
+    });
+  });
+
+  it('returns an explicit unknown result for targetless events', () => {
+    const root = document.createElement('div');
+    const event = new Event('keydown');
+    Object.defineProperty(event, 'target', { configurable: true, value: null });
+    Object.defineProperty(event, 'composedPath', { configurable: true, value: undefined });
+
+    expect(resolveUiOwnership(event, root)).toEqual({
+      owned: false,
+      source: 'target-fallback',
+    });
+  });
+});