cursedbelt 1.0.0 → 2.3.0

package/src/game/core/inputCollector.spec.ts

@@ -1,29 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-// Only the pure `deadzone` helper is unit-tested here (no DOM). The event-driven
-// `createInputCollector` is proven in the kitchen-sink demo (listener attach/detach,
-// arrow-key + touch movement) — see e2e/game.spec.ts.
-import { deadzone } from './inputCollector';
-
-describe('deadzone', () => {
-  test('zeroes input inside the threshold', () => {
-    expect(deadzone(0.1)).toBe(0); // default threshold 0.15
-    expect(deadzone(-0.05)).toBe(0);
-    expect(deadzone(0.15)).toBe(0); // exactly at the edge
-  });
-
-  test('rescales the remainder so output still reaches 1', () => {
-    expect(deadzone(1, 0.15)).toBeCloseTo(1, 5);
-    expect(deadzone(-1, 0.15)).toBeCloseTo(-1, 5);
-  });
-
-  test('maps a mid value past the threshold linearly', () => {
-    // (0.575 - 0.15) / (1 - 0.15) = 0.5
-    expect(deadzone(0.575, 0.15)).toBeCloseTo(0.5, 5);
-    expect(deadzone(-0.575, 0.15)).toBeCloseTo(-0.5, 5);
-  });
-
-  test('preserves sign', () => {
-    expect(deadzone(0.5)).toBeGreaterThan(0);
-    expect(deadzone(-0.5)).toBeLessThan(0);
-  });
-});

package/src/game/core/inputCollector.ts

@@ -1,245 +0,0 @@
-import type { DisposeRegistry } from './DisposeRegistry';
-
-export interface PointerSnapshot {
-  /** Canvas-relative X in CSS pixels. */
-  x: number;
-  /** Canvas-relative Y in CSS pixels. */
-  y: number;
-  /** Bitmask of currently-pressed buttons (`PointerEvent.buttons`). */
-  buttons: number;
-  /** The originating `PointerEvent.pointerId`. */
-  id: number;
-  /** `'mouse' | 'pen' | 'touch'`. */
-  type: string;
-}
-
-export interface GamepadSnapshot {
-  index: number;
-  /** Axes with the deadzone already applied. Even indices = X, odd = Y, by convention. */
-  axes: number[];
-  /** Per-button analog value in `[0, 1]`. */
-  buttons: number[];
-  /** Per-button pressed flag. */
-  pressed: boolean[];
-}
-
-export interface InputSnapshot {
-  /** The primary (most-recently-active) pointer. */
-  pointer: { x: number; y: number; buttons: number };
-  /** `KeyboardEvent.code` → held. Cleared on window blur to avoid stuck keys. */
-  keys: Record<string, boolean>;
-  /** One entry per active touch contact, canvas-relative. */
-  touch: { x: number; y: number }[];
-  /** The first connected gamepad with deadzone-corrected axes, or `null`. */
-  gamepad: GamepadSnapshot | null;
-}
-
-export interface InputCollectorOptions {
-  /**
-   * Where keyboard listeners attach. Defaults to `window` so the game receives keys
-   * without the canvas needing focus. Pass the canvas to scope keys to focus instead.
-   */
-  keyboardTarget?: Window | HTMLElement;
-  /** Gamepad axis deadzone (default `0.15`). */
-  gamepadDeadzone?: number;
-  /**
-   * Set `canvas.style.touchAction = 'none'` so dragging on a touch device doesn't
-   * scroll/zoom the page (default `true`). Restored on dispose.
-   */
-  preventTouchScroll?: boolean;
-}
-
-export interface InputCollector {
-  /** A point-in-time copy of all input state — call once per frame. */
-  snapshot: () => InputSnapshot;
-  /** Subscribe to pointer-down events (mouse/pen/touch unified). */
-  onPointerDown: (fn: (e: PointerSnapshot) => void) => void;
-  /** Subscribe to pointer-up events. */
-  onPointerUp: (fn: (e: PointerSnapshot) => void) => void;
-  /** Subscribe to a specific `KeyboardEvent.code`; `down` is `true` on press, `false` on release. */
-  onKey: (code: string, fn: (down: boolean) => void) => void;
-}
-
-/**
- * Applies a radial deadzone to a normalized axis value in `[-1, 1]` and rescales the
- * remainder so output still spans the full range past the threshold (no sudden jump
- * at the deadzone edge). Use for gamepad sticks / analog inputs.
- */
-export function deadzone(value: number, threshold = 0.15): number {
-  const magnitude = Math.abs(value);
-  if (magnitude <= threshold) return 0;
-  const sign = value < 0 ? -1 : 1;
-  return sign * ((magnitude - threshold) / (1 - threshold));
-}
-
-/**
- * Collects raw input state from pointer, keyboard, touch, and gamepad into a single
- * snapshot-able object. Pointer events unify mouse/pen/touch; touch contacts are also
- * surfaced individually in `snapshot().touch`. All listeners attach via the supplied
- * {@link DisposeRegistry}, so they're torn down automatically on engine dispose.
- *
- * Per-game `computeIntent(snapshot)` (mapping raw input → a game-specific action enum)
- * stays in the game — this layer only handles the common collection + deadzone.
- *
- * Browser-only: reads `document`/`window`/`navigator`. Never call from a server file.
- */
-export function createInputCollector(
-  canvas: HTMLCanvasElement,
-  registry: DisposeRegistry,
-  opts: InputCollectorOptions = {},
-): InputCollector {
-  const {
-    keyboardTarget = typeof window !== 'undefined' ? window : canvas,
-    gamepadDeadzone = 0.15,
-    preventTouchScroll = true,
-  } = opts;
-
-  const keys: Record<string, boolean> = {};
-  const activePointers = new Map<number, PointerSnapshot>();
-  let primary: PointerSnapshot = { x: 0, y: 0, buttons: 0, id: -1, type: 'mouse' };
-  let gamepadIndex: number | null = null;
-
-  const pointerDownHandlers: Array<(e: PointerSnapshot) => void> = [];
-  const pointerUpHandlers: Array<(e: PointerSnapshot) => void> = [];
-  const keyHandlers = new Map<string, Array<(down: boolean) => void>>();
-
-  function toLocal(e: PointerEvent): PointerSnapshot {
-    const rect = canvas.getBoundingClientRect();
-    return {
-      x: e.clientX - rect.left,
-      y: e.clientY - rect.top,
-      buttons: e.buttons,
-      id: e.pointerId,
-      type: e.pointerType,
-    };
-  }
-
-  // --- Pointer (unifies mouse, pen, touch) ---
-  const onPointerMove = (e: PointerEvent) => {
-    const p = toLocal(e);
-    if (activePointers.has(p.id) || p.type !== 'touch') primary = p;
-    if (activePointers.has(p.id)) activePointers.set(p.id, p);
-  };
-  const onPointerDown = (e: PointerEvent) => {
-    const p = toLocal(e);
-    activePointers.set(p.id, p);
-    primary = p;
-    for (const fn of pointerDownHandlers) fn(p);
-  };
-  const onPointerUp = (e: PointerEvent) => {
-    const p = toLocal(e);
-    activePointers.delete(p.id);
-    primary = { ...p, buttons: 0 };
-    for (const fn of pointerUpHandlers) fn(p);
-  };
-  const onPointerCancel = (e: PointerEvent) => {
-    activePointers.delete(e.pointerId);
-  };
-
-  addCanvasListener('pointermove', onPointerMove);
-  addCanvasListener('pointerdown', onPointerDown);
-  addCanvasListener('pointerup', onPointerUp);
-  addCanvasListener('pointercancel', onPointerCancel);
-
-  if (preventTouchScroll) {
-    const prev = canvas.style.touchAction;
-    canvas.style.touchAction = 'none';
-    registry.add(() => {
-      canvas.style.touchAction = prev;
-    });
-  }
-
-  // --- Keyboard (window by default; cleared on blur) ---
-  const onKeyDown = (e: KeyboardEvent) => {
-    if (keys[e.code]) return; // ignore auto-repeat
-    keys[e.code] = true;
-    const handlers = keyHandlers.get(e.code);
-    if (handlers) for (const fn of handlers) fn(true);
-  };
-  const onKeyUp = (e: KeyboardEvent) => {
-    if (!keys[e.code]) return;
-    keys[e.code] = false;
-    const handlers = keyHandlers.get(e.code);
-    if (handlers) for (const fn of handlers) fn(false);
-  };
-  const onBlur = () => {
-    for (const code of Object.keys(keys)) {
-      if (keys[code]) {
-        keys[code] = false;
-        const handlers = keyHandlers.get(code);
-        if (handlers) for (const fn of handlers) fn(false);
-      }
-    }
-  };
-  addTargetListener(keyboardTarget, 'keydown', onKeyDown as EventListener);
-  addTargetListener(keyboardTarget, 'keyup', onKeyUp as EventListener);
-  if (typeof window !== 'undefined') addTargetListener(window, 'blur', onBlur);
-
-  // --- Gamepad (connection is evented; state is polled in snapshot) ---
-  if (typeof window !== 'undefined') {
-    const onConnect = (e: Event) => {
-      gamepadIndex = (e as GamepadEvent).gamepad.index;
-    };
-    const onDisconnect = (e: Event) => {
-      if ((e as GamepadEvent).gamepad.index === gamepadIndex) gamepadIndex = null;
-    };
-    addTargetListener(window, 'gamepadconnected', onConnect);
-    addTargetListener(window, 'gamepaddisconnected', onDisconnect);
-  }
-
-  function readGamepad(): GamepadSnapshot | null {
-    if (typeof navigator === 'undefined' || !navigator.getGamepads) return null;
-    const pads = navigator.getGamepads();
-    const pad = gamepadIndex !== null ? pads[gamepadIndex] : pads.find((p) => p != null);
-    if (!pad) return null;
-    return {
-      index: pad.index,
-      axes: pad.axes.map((a) => deadzone(a, gamepadDeadzone)),
-      buttons: pad.buttons.map((b) => b.value),
-      pressed: pad.buttons.map((b) => b.pressed),
-    };
-  }
-
-  return {
-    snapshot() {
-      const touch: { x: number; y: number }[] = [];
-      for (const p of activePointers.values()) {
-        if (p.type === 'touch') touch.push({ x: p.x, y: p.y });
-      }
-      return {
-        pointer: { x: primary.x, y: primary.y, buttons: primary.buttons },
-        keys: { ...keys },
-        touch,
-        gamepad: readGamepad(),
-      };
-    },
-    onPointerDown(fn) {
-      pointerDownHandlers.push(fn);
-    },
-    onPointerUp(fn) {
-      pointerUpHandlers.push(fn);
-    },
-    onKey(code, fn) {
-      const handlers = keyHandlers.get(code);
-      if (handlers) handlers.push(fn);
-      else keyHandlers.set(code, [fn]);
-    },
-  };
-
-  function addCanvasListener<K extends keyof HTMLElementEventMap>(
-    type: K,
-    handler: (e: HTMLElementEventMap[K]) => void,
-  ): void {
-    canvas.addEventListener(type, handler as EventListener);
-    registry.add(() => canvas.removeEventListener(type, handler as EventListener));
-  }
-
-  function addTargetListener(
-    target: Window | HTMLElement,
-    type: string,
-    handler: EventListener,
-  ): void {
-    target.addEventListener(type, handler);
-    registry.add(() => target.removeEventListener(type, handler));
-  }
-}

package/src/game/core/resizeCanvas.ts

@@ -1,31 +0,0 @@
-/**
- * Resize a canvas's backing-store resolution to match its CSS display size times the
- * device pixel ratio, so rendering is crisp on HiDPI screens without stretching.
- *
- * Call this at the top of the render loop. It only writes `canvas.width/height` when
- * they actually changed (writing them is destructive — it clears the canvas and resets
- * the 2D context state), and returns whether a resize happened so the game can update
- * its viewport/projection only when needed.
- *
- * This is deliberately NOT inside `useGameEngine`: backing-store sizing is game-specific
- * (a WebGL game also calls `gl.viewport`, a 2D game may re-scale the context), so the
- * hook stays renderer-agnostic and the game owns its resize policy.
- *
- * @param canvas - The target canvas.
- * @param dpr - Device pixel ratio (defaults to `window.devicePixelRatio`, min 1).
- * @returns `true` if the backing store was resized this call.
- */
-export function resizeCanvasToDisplaySize(
-  canvas: HTMLCanvasElement,
-  dpr: number = typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1,
-): boolean {
-  const ratio = dpr > 0 ? dpr : 1;
-  const width = Math.max(1, Math.round(canvas.clientWidth * ratio));
-  const height = Math.max(1, Math.round(canvas.clientHeight * ratio));
-  if (canvas.width !== width || canvas.height !== height) {
-    canvas.width = width;
-    canvas.height = height;
-    return true;
-  }
-  return false;
-}

package/src/game/react/index.ts

@@ -1,10 +0,0 @@
-// cursedbelt/game/react — the browser-only React host hook. Reads `document`/`window`;
-// never import this subpath from a Bun server file. The engine-agnostic core (no React,
-// Bun-safe) lives in `cursedbelt/game`.
-
-export type {
-  GameFactory,
-  GameHandle,
-  UseGameEngineResult,
-} from './useGameEngine';
-export { useGameEngine } from './useGameEngine';

package/src/game/react/useGameEngine.ts

@@ -1,125 +0,0 @@
-import { type DependencyList, type RefObject, useEffect, useRef, useState } from 'react';
-import { DisposeRegistry } from '../core/DisposeRegistry';
-
-/**
- * The handle a {@link GameFactory} returns. The host hook owns its lifecycle:
- * `dispose` runs on true unmount; `pause`/`resume` run on tab hide/show.
- */
-export interface GameHandle {
-  /** Tear down the engine. Called exactly once, on true unmount. */
-  dispose(): void;
-  /** Optional: called when the tab is hidden (Page Visibility). Cancel your rAF here. */
-  pause?(): void;
-  /** Optional: called when the tab becomes visible again. Restart your rAF here. */
-  resume?(): void;
-}
-
-/**
- * Creates the engine for a freshly-mounted canvas. Receives a {@link DisposeRegistry}
- * for RAII cleanup — register every listener / rAF id / resource you allocate.
- *
- * MUST be referentially stable: define it at module level or wrap it in `useCallback`.
- * (It's read through a ref, so an unstable identity won't restart the engine — but a
- * stale closure could capture old props. Prefer reading live values through refs.)
- *
- * @returns the handle, or a promise of it (async setup — e.g. loading WASM — is fine).
- */
-export type GameFactory<THandle extends GameHandle> = (
-  canvas: HTMLCanvasElement,
-  registry: DisposeRegistry,
-) => THandle | Promise<THandle>;
-
-export interface UseGameEngineResult<THandle extends GameHandle> {
-  /** Attach to your `<canvas ref={canvasRef} />`. */
-  canvasRef: RefObject<HTMLCanvasElement | null>;
-  /**
-   * The live handle, available after mount (`null` during SSR/init). This is a ref
-   * value, NOT reactive — gate UI that needs it on {@link UseGameEngineResult.isReady}.
-   */
-  handle: THandle | null;
-  /** `true` once the factory has resolved and the engine is running. */
-  isReady: boolean;
-}
-
-/**
- * Stable game-engine host hook — the architectural fix for the "game froze, can't
- * click out" bug.
- *
- * The bug: a game's lifecycle `useEffect` listed a context-derived value (typically
- * `authRequest` / `saveNow` from `AuthContext`) in its dep array. When that value's
- * identity churned on an unrelated re-render, React tore down and re-ran the effect —
- * disposing the *live* engine mid-session. A guarded setup (`if (engine) return`) then
- * refused to recreate it, leaving a dead canvas with no way out.
- *
- * The fix, by construction: the `factory` is held in a ref and is **never** an effect
- * dependency. The engine starts once on mount and is disposed once on true unmount.
- * AuthContext can re-render as much as it likes — the engine lifecycle is fully
- * decoupled from React's render cycle. Only the explicit `deps` (true restart triggers
- * like a room id or game mode) re-create the engine.
- *
- * Notes:
- * - **Canvas sizing / DPR is game-specific** and intentionally NOT handled here. Call
- *   `resizeCanvasToDisplaySize(canvas)` (from `cursedbelt/game`) in your render loop.
- * - **Page Visibility**: the hook calls `handle.pause?()` on hide and `handle.resume?()`
- *   on show. Cancel your rAF in `pause` and restart it in `resume`; pair with
- *   `createFixedTimestep`'s `maxCatchup` guard so the post-resume delta can't spiral.
- *
- * @param factory Stable engine constructor (module-level or `useCallback`).
- * @param deps    True restart triggers (keep small + stable). Default `[]` = mount-once.
- */
-export function useGameEngine<THandle extends GameHandle>(
-  factory: GameFactory<THandle>,
-  deps: DependencyList = [],
-): UseGameEngineResult<THandle> {
-  const canvasRef = useRef<HTMLCanvasElement | null>(null);
-  const factoryRef = useRef(factory); // ← intentionally never an effect dependency
-  const handleRef = useRef<THandle | null>(null);
-  const [isReady, setIsReady] = useState(false);
-
-  // Keep the factory ref fresh on every render WITHOUT re-running the engine effect.
-  // (Same pattern as a `useEvent` / event-handler ref.)
-  useEffect(() => {
-    factoryRef.current = factory;
-  });
-
-  // NOTE (the freeze fix): `factory` is intentionally NOT a dependency of this effect —
-  // it is read through the stable `factoryRef`, so AuthContext churn (or any re-render)
-  // can never tear down and restart the live engine. Only `deps` (true restart triggers
-  // like a room id) re-create it. The exhaustive-deps lint has nothing to flag precisely
-  // because `factory` is never referenced directly here.
-  useEffect(() => {
-    const canvas = canvasRef.current;
-    if (!canvas) return;
-
-    const registry = new DisposeRegistry();
-    let active = true;
-
-    Promise.resolve(factoryRef.current(canvas, registry)).then((handle) => {
-      if (!active) {
-        // Unmounted before the (possibly async) factory resolved — dispose immediately.
-        handle.dispose();
-        return;
-      }
-      handleRef.current = handle;
-      setIsReady(true);
-
-      const onVisibility = () => {
-        if (document.hidden) handle.pause?.();
-        else handle.resume?.();
-      };
-      document.addEventListener('visibilitychange', onVisibility);
-      registry.add(() => document.removeEventListener('visibilitychange', onVisibility));
-    });
-
-    return () => {
-      active = false;
-      registry.disposeAll();
-      handleRef.current?.dispose();
-      handleRef.current = null;
-      setIsReady(false);
-    };
-    // biome-ignore lint/correctness/useExhaustiveDependencies: `deps` is this hook's own pass-through dependency-list parameter (same shape as useEffect's own deps arg), inherently caller-supplied rather than an inline literal; `factory` is intentionally excluded per the freeze-fix note above.
-  }, deps);
-
-  return { canvasRef, handle: handleRef.current, isReady };
-}

package/src/react/canvas/CanvasNavHUD.spec.tsx

@@ -1,62 +0,0 @@
-import { afterEach, describe, expect, test } from 'bun:test';
-import { cleanup, fireEvent, render } from '@testing-library/react';
-import { CanvasNavHUD } from './CanvasNavHUD';
-
-afterEach(cleanup);
-
-const WORLD = { x: 0, y: 0, width: 1000, height: 500 };
-
-describe('CanvasNavHUD — DESIGN.md §7 names three controls', () => {
-  test('fit, centre-on-focus and the radar are all present', () => {
-    const { getByLabelText } = render(
-      <CanvasNavHUD
-        onFit={() => {}}
-        onCenterFocus={() => {}}
-        focusLabel='Ada Lovelace'
-        world={WORLD}
-        viewport={{ x: 100, y: 50, width: 200, height: 100 }}
-      />,
-    );
-    expect(getByLabelText('Fit to canvas')).toBeTruthy();
-    // The hint names WHAT it centres on, not "centre".
-    expect(getByLabelText('Centre on Ada Lovelace')).toBeTruthy();
-    expect(getByLabelText('Radar')).toBeTruthy();
-  });
-
-  test('the radar draws the viewport rectangle in world coordinates', () => {
-    const { container } = render(
-      <CanvasNavHUD
-        onFit={() => {}}
-        world={WORLD}
-        viewport={{ x: 500, y: 250, width: 250, height: 125 }}
-      />,
-    );
-    const rect = container.querySelector('[data-cb-hud-viewport]');
-    // 132×88 radar; half-way across the world is half-way across the radar.
-    expect(rect?.getAttribute('x')).toBe('66');
-    expect(rect?.getAttribute('y')).toBe('44');
-    expect(rect?.getAttribute('width')).toBe('33');
-  });
-
-  test('a canvas with no focus node simply omits that control', () => {
-    const { queryByLabelText } = render(<CanvasNavHUD onFit={() => {}} world={WORLD} />);
-    expect(queryByLabelText(/Centre on/)).toBeNull();
-  });
-
-  test('the zoom cluster clamps to its range and reports a percentage', () => {
-    const seen: number[] = [];
-    const { getByLabelText, getByText } = render(
-      <CanvasNavHUD onFit={() => {}} zoom={0.1} zoomRange={[0.1, 4]} onZoomChange={(z) => seen.push(z)} />,
-    );
-    expect(getByText('10%')).toBeTruthy();
-    // At the floor, zooming out further is not offered rather than silently ignored.
-    expect(getByLabelText('Zoom out').hasAttribute('disabled')).toBe(true);
-    fireEvent.click(getByLabelText('Zoom in'));
-    expect(seen).toEqual([0.125]);
-  });
-
-  test('without world bounds there is no radar to draw', () => {
-    const { queryByLabelText } = render(<CanvasNavHUD onFit={() => {}} />);
-    expect(queryByLabelText('Radar')).toBeNull();
-  });
-});