@forgeax/engine-input 0.1.2

package/src/__tests__/browser-backend-lock-error.test.ts

@@ -0,0 +1,425 @@
+// browser-backend-lock-error.test.ts -- M1 w4: onLockError unit tests.
+//
+// Covers: W3C rejection → onLockError (no longer silently swallowed),
+// provider reject → onLockError + providerLocked rollback.
+//
+// charter awareness:
+//   P3 explicit failure -- lock failures must produce structured signals,
+//     never silently swallowed (constraint 7).
+//   F1 single-entry indexability -- all error tests in one file.
+
+import { describe, expect, it, vi } from 'vitest';
+import { attachBrowserInputBackend } from '../browser-backend';
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('browser-backend-lock-error.test.ts (w4)', () => {
+  describe('W3C requestPointerLock rejection → onLockError', () => {
+    it('W3C rejection calls onLockError with { path: "w3c", cause }', () => {
+      const listeners = new Map<string, Map<string, Set<EventListener>>>();
+      const makeTarget = (label: string) => ({
+        addEventListener(kind: string, handler: EventListener): void {
+          let perTarget = listeners.get(label);
+          if (!perTarget) {
+            perTarget = new Map();
+            listeners.set(label, perTarget);
+          }
+          let set = perTarget.get(kind);
+          if (!set) {
+            set = new Set();
+            perTarget.set(kind, set);
+          }
+          set.add(handler);
+        },
+        removeEventListener(kind: string, handler: EventListener): void {
+          listeners.get(label)?.get(kind)?.delete(handler);
+        },
+      });
+
+      const pointerLockEl: Element | null = null;
+      const rejectionError = new Error('WrongDocumentError');
+      const lockErrorCalls: Array<{ path: string; cause: unknown }> = [];
+
+      const canvas = {
+        ...makeTarget('canvas'),
+        requestPointerLock(): Promise<void> {
+          return Promise.reject(rejectionError);
+        },
+        getBoundingClientRect: () => ({ left: 0, top: 0, width: 800, height: 600 }) as DOMRect,
+        width: 800,
+        height: 600,
+        style: { touchAction: '' },
+        setPointerCapture: () => {},
+      } as unknown as HTMLCanvasElement;
+
+      const doc = {
+        ...makeTarget('document'),
+        hasFocus() {
+          return true;
+        },
+        visibilityState: 'visible',
+        get pointerLockElement() {
+          return pointerLockEl;
+        },
+        exitPointerLock() {},
+      } as unknown as Document;
+
+      const win = makeTarget('window') as unknown as Window;
+
+      attachBrowserInputBackend(canvas, {
+        document: doc,
+        window: win,
+        onLockError: (detail) => {
+          lockErrorCalls.push(detail);
+        },
+      });
+
+      // Click triggers requestPointerLock which rejects.
+      const clickH = listeners.get('canvas')?.get('click');
+      if (clickH) {
+        const ev = new Event('click');
+        for (const h of clickH) h(ev as Event);
+      }
+
+      // Wait for microtask to resolve promise rejection.
+      return vi.waitFor(
+        () => {
+          expect(lockErrorCalls.length).toBe(1);
+          expect(lockErrorCalls[0]?.path).toBe('w3c');
+          expect(lockErrorCalls[0]?.cause).toBe(rejectionError);
+        },
+        { timeout: 200 },
+      );
+    });
+
+    it('W3C rejection without onLockError provided does NOT throw (backend is resilient)', () => {
+      const listeners = new Map<string, Map<string, Set<EventListener>>>();
+      const makeTarget = (label: string) => ({
+        addEventListener(kind: string, handler: EventListener): void {
+          let perTarget = listeners.get(label);
+          if (!perTarget) {
+            perTarget = new Map();
+            listeners.set(label, perTarget);
+          }
+          let set = perTarget.get(kind);
+          if (!set) {
+            set = new Set();
+            perTarget.set(kind, set);
+          }
+          set.add(handler);
+        },
+        removeEventListener(kind: string, handler: EventListener): void {
+          listeners.get(label)?.get(kind)?.delete(handler);
+        },
+      });
+
+      const pointerLockEl: Element | null = null;
+
+      const canvas = {
+        ...makeTarget('canvas'),
+        requestPointerLock(): Promise<void> {
+          return Promise.reject(new Error('SecurityError'));
+        },
+        getBoundingClientRect: () => ({ left: 0, top: 0, width: 800, height: 600 }) as DOMRect,
+        width: 800,
+        height: 600,
+        style: { touchAction: '' },
+        setPointerCapture: () => {},
+      } as unknown as HTMLCanvasElement;
+
+      const doc = {
+        ...makeTarget('document'),
+        hasFocus() {
+          return true;
+        },
+        visibilityState: 'visible',
+        get pointerLockElement() {
+          return pointerLockEl;
+        },
+        exitPointerLock() {},
+      } as unknown as Document;
+
+      const win = makeTarget('window') as unknown as Window;
+
+      attachBrowserInputBackend(canvas, {
+        document: doc,
+        window: win,
+        // No onLockError provided -- should not throw.
+      });
+
+      // Click triggers rejection.
+      const clickH = listeners.get('canvas')?.get('click');
+      if (clickH) {
+        const ev = new Event('click');
+        for (const h of clickH) h(ev as Event);
+      }
+
+      // The promise rejection should be caught, not unhandled.
+      // We verify by waiting a microtask — no throw should occur.
+      return vi.waitFor(
+        () => {
+          // If we got here without an unhandled rejection, the test passes.
+          expect(true).toBe(true);
+        },
+        { timeout: 200 },
+      );
+    });
+  });
+
+  describe('provider requestLock reject → onLockError + rollback', () => {
+    it('provider requestLock reject calls onLockError with { path: "provider", cause }', async () => {
+      const listeners = new Map<string, Map<string, Set<EventListener>>>();
+      const makeTarget = (label: string) => ({
+        addEventListener(kind: string, handler: EventListener): void {
+          let perTarget = listeners.get(label);
+          if (!perTarget) {
+            perTarget = new Map();
+            listeners.set(label, perTarget);
+          }
+          let set = perTarget.get(kind);
+          if (!set) {
+            set = new Set();
+            perTarget.set(kind, set);
+          }
+          set.add(handler);
+        },
+        removeEventListener(kind: string, handler: EventListener): void {
+          listeners.get(label)?.get(kind)?.delete(handler);
+        },
+      });
+
+      const pointerLockEl: Element | null = null;
+      const providerError = new Error('Tauri invoke failed');
+      const lockErrorCalls: Array<{ path: string; cause: unknown }> = [];
+
+      const canvas = {
+        ...makeTarget('canvas'),
+        requestPointerLock() {},
+        getBoundingClientRect: () => ({ left: 0, top: 0, width: 800, height: 600 }) as DOMRect,
+        width: 800,
+        height: 600,
+        style: { touchAction: '' },
+        setPointerCapture: () => {},
+      } as unknown as HTMLCanvasElement;
+
+      const doc = {
+        ...makeTarget('document'),
+        hasFocus() {
+          return true;
+        },
+        visibilityState: 'visible',
+        get pointerLockElement() {
+          return pointerLockEl;
+        },
+        exitPointerLock() {},
+      } as unknown as Document;
+
+      const win = makeTarget('window') as unknown as Window;
+
+      const handle = attachBrowserInputBackend(canvas, {
+        document: doc,
+        window: win,
+        lockProvider: {
+          requestLock(): Promise<void> {
+            return Promise.reject(providerError);
+          },
+          exitLock() {},
+        },
+        onLockError: (detail) => {
+          lockErrorCalls.push(detail);
+        },
+      });
+      const backend = handle.backend;
+
+      // Click triggers provider requestLock which rejects.
+      const clickH = listeners.get('canvas')?.get('click');
+      if (clickH) {
+        const ev = new Event('click');
+        for (const h of clickH) h(ev as Event);
+      }
+
+      await vi.waitFor(
+        () => {
+          expect(lockErrorCalls.length).toBe(1);
+          expect(lockErrorCalls[0]?.path).toBe('provider');
+          expect(lockErrorCalls[0]?.cause).toBe(providerError);
+        },
+        { timeout: 200 },
+      );
+
+      // providerLocked should be rolled back.
+      const s = backend.sample();
+      expect(s.pointerLocked).toBe(false);
+    });
+
+    it('provider requestLock throw calls onLockError and rolls back providerLocked', async () => {
+      const listeners = new Map<string, Map<string, Set<EventListener>>>();
+      const makeTarget = (label: string) => ({
+        addEventListener(kind: string, handler: EventListener): void {
+          let perTarget = listeners.get(label);
+          if (!perTarget) {
+            perTarget = new Map();
+            listeners.set(label, perTarget);
+          }
+          let set = perTarget.get(kind);
+          if (!set) {
+            set = new Set();
+            perTarget.set(kind, set);
+          }
+          set.add(handler);
+        },
+        removeEventListener(kind: string, handler: EventListener): void {
+          listeners.get(label)?.get(kind)?.delete(handler);
+        },
+      });
+
+      const pointerLockEl: Element | null = null;
+      const syncError = new Error('postMessage failed');
+      const lockErrorCalls: Array<{ path: string; cause: unknown }> = [];
+
+      const canvas = {
+        ...makeTarget('canvas'),
+        requestPointerLock() {},
+        getBoundingClientRect: () => ({ left: 0, top: 0, width: 800, height: 600 }) as DOMRect,
+        width: 800,
+        height: 600,
+        style: { touchAction: '' },
+        setPointerCapture: () => {},
+      } as unknown as HTMLCanvasElement;
+
+      const doc = {
+        ...makeTarget('document'),
+        hasFocus() {
+          return true;
+        },
+        visibilityState: 'visible',
+        get pointerLockElement() {
+          return pointerLockEl;
+        },
+        exitPointerLock() {},
+      } as unknown as Document;
+
+      const win = makeTarget('window') as unknown as Window;
+
+      const handle = attachBrowserInputBackend(canvas, {
+        document: doc,
+        window: win,
+        lockProvider: {
+          requestLock(): void {
+            throw syncError;
+          },
+          exitLock() {},
+        },
+        onLockError: (detail) => {
+          lockErrorCalls.push(detail);
+        },
+      });
+      const backend = handle.backend;
+
+      // Click triggers provider requestLock which throws synchronously.
+      const clickH = listeners.get('canvas')?.get('click');
+      if (clickH) {
+        const ev = new Event('click');
+        for (const h of clickH) h(ev as Event);
+      }
+
+      expect(lockErrorCalls.length).toBe(1);
+      expect(lockErrorCalls[0]?.path).toBe('provider');
+      expect(lockErrorCalls[0]?.cause).toBe(syncError);
+
+      // providerLocked should be rolled back.
+      const s = backend.sample();
+      expect(s.pointerLocked).toBe(false);
+    });
+
+    it('provider exitLock throw calls onLockError (does not affect lock cleanup)', async () => {
+      const listeners = new Map<string, Map<string, Set<EventListener>>>();
+      const makeTarget = (label: string) => ({
+        addEventListener(kind: string, handler: EventListener): void {
+          let perTarget = listeners.get(label);
+          if (!perTarget) {
+            perTarget = new Map();
+            listeners.set(label, perTarget);
+          }
+          let set = perTarget.get(kind);
+          if (!set) {
+            set = new Set();
+            perTarget.set(kind, set);
+          }
+          set.add(handler);
+        },
+        removeEventListener(kind: string, handler: EventListener): void {
+          listeners.get(label)?.get(kind)?.delete(handler);
+        },
+      });
+
+      const pointerLockEl: Element | null = null;
+      const exitError = new Error('exitLock failed');
+      const lockErrorCalls: Array<{ path: string; cause: unknown }> = [];
+
+      const canvas = {
+        ...makeTarget('canvas'),
+        requestPointerLock() {},
+        getBoundingClientRect: () => ({ left: 0, top: 0, width: 800, height: 600 }) as DOMRect,
+        width: 800,
+        height: 600,
+        style: { touchAction: '' },
+        setPointerCapture: () => {},
+      } as unknown as HTMLCanvasElement;
+
+      const doc = {
+        ...makeTarget('document'),
+        hasFocus() {
+          return true;
+        },
+        visibilityState: 'visible',
+        get pointerLockElement() {
+          return pointerLockEl;
+        },
+        exitPointerLock() {},
+      } as unknown as Document;
+
+      const win = makeTarget('window') as unknown as Window;
+
+      const handle = attachBrowserInputBackend(canvas, {
+        document: doc,
+        window: win,
+        lockProvider: {
+          requestLock() {},
+          exitLock(): void {
+            throw exitError;
+          },
+        },
+        onLockError: (detail) => {
+          lockErrorCalls.push(detail);
+        },
+      });
+      const backend = handle.backend;
+
+      // Lock via provider path.
+      const clickH = listeners.get('canvas')?.get('click');
+      if (clickH) {
+        const ev = new Event('click');
+        for (const h of clickH) h(ev as Event);
+      }
+      expect(backend.sample().pointerLocked).toBe(true);
+
+      // ESC triggers exitLock which throws.
+      const keyH = listeners.get('window')?.get('keydown');
+      if (keyH) {
+        const ev = { key: 'Escape' } as KeyboardEvent;
+        for (const h of keyH) h(ev as Event);
+      }
+
+      expect(lockErrorCalls.length).toBe(1);
+      expect(lockErrorCalls[0]?.path).toBe('provider');
+      expect(lockErrorCalls[0]?.cause).toBe(exitError);
+
+      // providerLocked should still be cleared despite exitLock throw.
+      const s = backend.sample();
+      expect(s.pointerLocked).toBe(false);
+    });
+  });
+});

package/src/__tests__/browser-backend-lock-gate.test.ts

@@ -0,0 +1,283 @@
+// browser-backend-lock-gate.test.ts -- M1 w2: gate synthesis unit tests.
+//
+// Covers: gameGate x hostPredicate four-quadrant matrix,
+// setPointerLockAllowed(false) immediate release on both paths.
+//
+// charter awareness:
+//   F1 single-entry indexability -- all gate tests in one file
+//   P3 explicit failure -- each assertion produces a clear diagnostic
+
+import { describe, expect, it } from 'vitest';
+import { attachBrowserInputBackend } from '../browser-backend';
+
+// ---------------------------------------------------------------------------
+// Helper: build fake env with shared document listeners.
+// ---------------------------------------------------------------------------
+
+function buildEnvForClickTest(opts?: {
+  hostPredicate?: (() => boolean) | undefined;
+  lockProvider?: { requestLock: () => void; exitLock: () => void } | undefined;
+}): {
+  backend: ReturnType<typeof attachBrowserInputBackend>['backend'];
+  fireClick(): void;
+  requestPointerLockCalls: { count: number };
+  requestLockCalls: { count: number };
+  exitLockCalls: { count: number };
+  exitPointerLockCalls: { count: number };
+  setPointerLockElement(el: Element | null): void;
+  canvas: HTMLCanvasElement;
+} {
+  const listeners = new Map<string, Map<string, Set<EventListener>>>();
+  const makeTarget = (label: string) => ({
+    addEventListener(kind: string, handler: EventListener): void {
+      let perTarget = listeners.get(label);
+      if (!perTarget) {
+        perTarget = new Map();
+        listeners.set(label, perTarget);
+      }
+      let set = perTarget.get(kind);
+      if (!set) {
+        set = new Set();
+        perTarget.set(kind, set);
+      }
+      set.add(handler);
+    },
+    removeEventListener(kind: string, handler: EventListener): void {
+      listeners.get(label)?.get(kind)?.delete(handler);
+    },
+  });
+
+  let pointerLockEl: Element | null = null;
+  const requestPointerLockCalls = { count: 0 };
+  const exitPointerLockCalls = { count: 0 };
+  const requestLockCalls = { count: 0 };
+  const exitLockCalls = { count: 0 };
+
+  const canvas = {
+    ...makeTarget('canvas'),
+    requestPointerLock() {
+      requestPointerLockCalls.count += 1;
+    },
+    getBoundingClientRect: () => ({ left: 0, top: 0, width: 800, height: 600 }) as DOMRect,
+    width: 800,
+    height: 600,
+    style: { touchAction: '' },
+    setPointerCapture: () => {},
+  } as unknown as HTMLCanvasElement;
+
+  const doc = {
+    ...makeTarget('document'),
+    hasFocus() {
+      return true;
+    },
+    visibilityState: 'visible',
+    get pointerLockElement() {
+      return pointerLockEl;
+    },
+    exitPointerLock() {
+      exitPointerLockCalls.count += 1;
+      pointerLockEl = null;
+      const hs = listeners.get('document')?.get('pointerlockchange');
+      if (hs) {
+        const ev = new Event('pointerlockchange');
+        for (const h of hs) h(ev as Event);
+      }
+    },
+  } as unknown as Document & { exitPointerLock(): void };
+
+  const win = makeTarget('window') as unknown as Window;
+
+  // Build options with exactOptionalPropertyTypes-safe handling.
+  const backendOpts: Record<string, unknown> = {
+    document: doc,
+    window: win,
+  };
+  if (opts?.hostPredicate !== undefined) {
+    backendOpts.pointerLockAllowed = opts.hostPredicate;
+  }
+  if (opts?.lockProvider !== undefined) {
+    backendOpts.lockProvider = opts.lockProvider;
+  }
+
+  const handle = attachBrowserInputBackend(
+    canvas,
+    backendOpts as Parameters<typeof attachBrowserInputBackend>[1],
+  );
+
+  return {
+    backend: handle.backend,
+    canvas,
+    fireClick() {
+      const handlers = listeners.get('canvas')?.get('click');
+      if (handlers) {
+        const ev = new Event('click');
+        for (const h of handlers) h(ev as Event);
+      }
+    },
+    requestPointerLockCalls,
+    exitPointerLockCalls,
+    requestLockCalls,
+    exitLockCalls,
+    setPointerLockElement(el) {
+      pointerLockEl = el;
+      const hs = listeners.get('document')?.get('pointerlockchange');
+      if (hs) {
+        const ev = new Event('pointerlockchange');
+        for (const h of hs) h(ev as Event);
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('browser-backend-lock-gate.test.ts (w2)', () => {
+  describe('gate four-quadrant matrix', () => {
+    it('gameGate=true (default), hostPredicate=true -> lock requested (W3C path)', () => {
+      const env = buildEnvForClickTest({
+        hostPredicate: () => true,
+      });
+      env.fireClick();
+      expect(env.requestPointerLockCalls.count).toBe(1);
+      expect(env.backend.sample().pointerLocked).toBe(false); // pointerlockchange not fired yet
+    });
+
+    it('gameGate=true (default), hostPredicate=false -> no lock', () => {
+      const env = buildEnvForClickTest({
+        hostPredicate: () => false,
+      });
+      env.fireClick();
+      expect(env.requestPointerLockCalls.count).toBe(0);
+      expect(env.backend.sample().pointerLocked).toBe(false);
+    });
+
+    it('gameGate=false (setPointerLockAllowed(false)), hostPredicate=true -> no lock', () => {
+      const env = buildEnvForClickTest({
+        hostPredicate: () => true,
+      });
+      env.backend.setPointerLockAllowed?.(false);
+      env.fireClick();
+      expect(env.requestPointerLockCalls.count).toBe(0);
+      expect(env.backend.sample().pointerLocked).toBe(false);
+    });
+
+    it('gameGate=false, hostPredicate=false -> no lock', () => {
+      const env = buildEnvForClickTest({
+        hostPredicate: () => false,
+      });
+      env.backend.setPointerLockAllowed?.(false);
+      env.fireClick();
+      expect(env.requestPointerLockCalls.count).toBe(0);
+      expect(env.backend.sample().pointerLocked).toBe(false);
+    });
+
+    it('gameGate reverts to true after setPointerLockAllowed(true)', () => {
+      const env = buildEnvForClickTest({
+        hostPredicate: () => true,
+      });
+      env.backend.setPointerLockAllowed?.(false);
+      env.fireClick();
+      expect(env.requestPointerLockCalls.count).toBe(0);
+
+      env.backend.setPointerLockAllowed?.(true);
+      env.fireClick();
+      expect(env.requestPointerLockCalls.count).toBe(1);
+    });
+  });
+
+  describe('gate with lockProvider path', () => {
+    it('gate passes + lockProvider present -> requestLock called, not W3C', () => {
+      const requestLockCalls = { count: 0 };
+      const env = buildEnvForClickTest({
+        hostPredicate: () => true,
+        lockProvider: {
+          requestLock() {
+            requestLockCalls.count += 1;
+          },
+          exitLock() {},
+        },
+      });
+      env.fireClick();
+      expect(requestLockCalls.count).toBe(1);
+      expect(env.requestPointerLockCalls.count).toBe(0);
+      expect(env.backend.sample().pointerLocked).toBe(true); // D-7 optimistic
+    });
+
+    it('gate blocked + lockProvider present -> neither requestLock nor W3C called', () => {
+      const requestLockCalls = { count: 0 };
+      const env = buildEnvForClickTest({
+        hostPredicate: () => false,
+        lockProvider: {
+          requestLock() {
+            requestLockCalls.count += 1;
+          },
+          exitLock() {},
+        },
+      });
+      env.fireClick();
+      expect(requestLockCalls.count).toBe(0);
+      expect(env.requestPointerLockCalls.count).toBe(0);
+      expect(env.backend.sample().pointerLocked).toBe(false);
+    });
+  });
+
+  describe('setPointerLockAllowed(false) immediate release', () => {
+    it('W3C path: setPointerLockAllowed(false) while locked -> exitPointerLock called', () => {
+      const env = buildEnvForClickTest({
+        hostPredicate: () => true,
+      });
+      // Lock via W3C path: click + pointerlockchange simulation.
+      env.fireClick();
+      env.setPointerLockElement(env.canvas);
+      expect(env.backend.sample().pointerLocked).toBe(true);
+
+      // Now release.
+      env.backend.setPointerLockAllowed?.(false);
+      expect(env.exitPointerLockCalls.count).toBe(1);
+      expect(env.backend.sample().pointerLocked).toBe(false);
+    });
+
+    it('provider path: setPointerLockAllowed(false) while locked -> exitLock called', () => {
+      const exitLockCalls = { count: 0 };
+      const env = buildEnvForClickTest({
+        hostPredicate: () => true,
+        lockProvider: {
+          requestLock() {},
+          exitLock() {
+            exitLockCalls.count += 1;
+          },
+        },
+      });
+      env.fireClick();
+      expect(env.backend.sample().pointerLocked).toBe(true);
+
+      env.backend.setPointerLockAllowed?.(false);
+      expect(exitLockCalls.count).toBe(1);
+      expect(env.backend.sample().pointerLocked).toBe(false);
+    });
+
+    it('setPointerLockAllowed(false) when not locked -> no-op', () => {
+      const env = buildEnvForClickTest();
+      env.backend.setPointerLockAllowed?.(false);
+      expect(env.exitPointerLockCalls.count).toBe(0);
+    });
+  });
+
+  describe('hostPredicate is evaluated live per click', () => {
+    it('predicate toggle mid-session switches gate behavior', () => {
+      let gateAllowed = false;
+      const env = buildEnvForClickTest({
+        hostPredicate: () => gateAllowed,
+      });
+
+      env.fireClick();
+      expect(env.requestPointerLockCalls.count).toBe(0);
+
+      gateAllowed = true;
+      env.fireClick();
+      expect(env.requestPointerLockCalls.count).toBe(1);
+    });
+  });
+});