MouseInput.defs.ts

MouseInput — definitions.

Holds the MouseInputComponent class and the shapes its data and events travel in. No System lives here, which is the point: another component can name MouseInput in a query, or type an event it listens for, without pulling MouseInput's behaviour into its own bundle. Import from here, not from MouseInput.ts.

MouseInput.defs.ts

import { Component } from '@babylonjsmarket/ecs';

export interface MouseInputInput {
  /** Ignore motion until the pointer is locked to the canvas. */
  requirePointerLock?: boolean;
  /** First click requests pointer lock instead of counting as a button press. */
  clickToLock?: boolean;
}

export const DEFAULT_MOUSE_INPUT_PARAMS: Required<MouseInputInput> = {
  requirePointerLock: true,
  clickToLock: true,
};

export class MouseInputComponent extends Component {
  requirePointerLock: boolean;
  clickToLock: boolean;

  constructor(data: MouseInputInput = {}) {
    super();
    const p = { ...DEFAULT_MOUSE_INPUT_PARAMS, ...data };
    this.requirePointerLock = p.requirePointerLock;
    this.clickToLock = p.clickToLock;
  }

  serialize(): MouseInputInput {
    return {
      requirePointerLock: this.requirePointerLock,
      clickToLock: this.clickToLock,
    };
  }
}

MouseInput.panel.tsx

MouseInput.panel.tsx — get the cursor back.

Two toggles, and they exist for one specific moment: you are debugging a game that captures the pointer, and to touch any other panel you first have to get the cursor out of the canvas. Both flags are read inside the DOM handlers on every event, so switching require lock off releases the game's claim on the mouse immediately — motion starts being delivered uncaptured and nothing has to be reloaded.

That is also why this panel is worth having at all despite being two switches. There is no sensitivity here to tune; the flight and look components own that. This is the escape hatch.

A scene may carry several MouseInput sources and the System treats them as an OR — any one of them demanding lock is enough — so the toggles write all of them. Setting one and leaving another would read as a switch that does nothing.

MouseInput.panel.tsx

import type { EventBus, World } from '@babylonjsmarket/ecs';
import {
  definePanel,
  PanelHostComponent,
  PanelHostSystem,
  type PanelHostInput,
  type PanelSpec,
} from '@babylonjsmarket/viz';
import { MouseInputComponent } from './MouseInput.defs';

const PANEL_ID = 'mouse-input-panel';

export class MouseInputPanelComponent extends PanelHostComponent {
  constructor(data: PanelHostInput = {}) {
    super({
      panelId: PANEL_ID,
      activationKey: data.activationKey ?? 'KeyM',
      position: data.position ?? 'top-right',
      visible: data.visible,
    });
  }
}

export class MouseInputPanelSystem extends PanelHostSystem<MouseInputPanelComponent> {
  constructor(eventBus: EventBus) {
    super(eventBus, MouseInputPanelComponent);
  }

  protected canBuild(world: World): boolean {
    return world.getEntitiesWithComponent(MouseInputComponent).length > 0;
  }

  protected buildSpec(world: World): PanelSpec {
    const sources = (): MouseInputComponent[] =>
      world
        .getEntitiesWithComponent(MouseInputComponent)
        .map((e) => e.get(MouseInputComponent))
        .filter((c): c is MouseInputComponent => c != null);
    const first = (): MouseInputComponent | null => sources()[0] ?? null;

    return definePanel({
      id: PANEL_ID,
      title: 'MouseInput · the cursor',
      titleColor: '#e599f7',
      position: 'top-right',
      sections: [
        {
          title: 'Pointer lock',
          controls: [
            {
              kind: 'toggle',
              label: 'require lock',
              bind: {
                get: () => first()?.requirePointerLock ?? false,
                set: (v: boolean) => sources().forEach((c) => (c.requirePointerLock = v)),
              },
              help: 'On, motion is dropped until the canvas has captured the pointer. Off is how you get the cursor back without reloading.',
            },
            {
              kind: 'toggle',
              label: 'click to lock',
              bind: {
                get: () => first()?.clickToLock ?? false,
                set: (v: boolean) => sources().forEach((c) => (c.clickToLock = v)),
              },
              help: 'On, the first click on the canvas is spent capturing the pointer rather than reaching the game.',
            },
            {
              kind: 'readout',
              label: 'pointer locked',
              bind: {
                get: () =>
                  typeof document !== 'undefined' && document.pointerLockElement ? 'yes' : 'no',
              },
              pollMs: 250,
            },
            {
              kind: 'readout',
              label: 'sources',
              bind: { get: () => sources().length },
            },
            {
              kind: 'note',
              text: 'Several sources are an OR: one of them demanding lock is enough for the System, so both toggles write all of them.',
            },
          ],
        },
      ],
    });
  }
}

MouseInput.ts

MouseInput.ts — renderer-agnostic System bridging the DOM mouse onto the EventBus. The pointer half of the input contract KeyboardInput owns for keys.

On init it attaches window pointer listeners (guarded by a window check so it stays inert under SSR / node tests) and republishes each one as the canonical bus events — imported from inputEvents, never hardcoded:

DOM mousemove → emit MouseInputEvents.MOVE { dx, dy } DOM mousedown → emit MouseInputEvents.DOWN { button } DOM mouseup → emit MouseInputEvents.UP { button } DOM pointerlockchange → emit MouseInputEvents.LOCK_CHANGED { locked }

Motion is read from movementX/Y — a relative delta, the only thing that means anything once the cursor is locked and has no on-screen position. It is forwarded in RAW device pixels; consumers scale it (see PlayerFlightInput.mouseSensitivity).

Two details are load-bearing, both inherited from the reference game's input bridge:

While requirePointerLock is set, motion before capture is DROPPED rather than queued. Otherwise the mouse travel that a player uses to go click the canvas arrives as one enormous first delta and snaps the ship around. - Losing the lock (Esc, tab-away) synthesises an UP for every button still held. The DOM does not send mouseup once the pointer is gone, so without this the guns keep firing after the player has left.

The canvas comes from renderer.getRenderingCanvas() — the adapter's own accessor, so no engine type crosses the boundary and pointer lock still targets the surface being drawn into.

DOM listeners are non-event resources, so they're torn down in onShutdown. Not pauseable — an input source keeps bridging while paused so a pause menu still receives the mouse. Zero @babylonjs / three imports; constructor takes (eventBus) only.

MouseInput.ts

import { System } from '@babylonjsmarket/ecs';
import type { EventBus } from '@babylonjsmarket/ecs';
import { MouseInputComponent } from './MouseInput.defs';
import { MouseInputEvents } from '../../inputEvents';

export class MouseInputSystem extends System {
  protected query = { required: [MouseInputComponent] };

  private moveHandler: ((e: MouseEvent) => void) | null = null;
  private downHandler: ((e: MouseEvent) => void) | null = null;
  private upHandler: ((e: MouseEvent) => void) | null = null;
  private lockChangeHandler: (() => void) | null = null;

  /** Buttons currently held, so a lost pointer lock can release them. */
  private heldButtons = new Set<number>();
  private pointerLocked = false;

  constructor(eventBus: EventBus) {
    super(eventBus);
    // Input source: keep bridging the mouse even while the world is paused.
    this._pauseable = false;
  }

  protected onInitialize(): void {
    this.moveHandler = (e: MouseEvent) => {
      if (this.requiresLock() && !this.pointerLocked) return;
      // Not captured? Then only the canvas steers. Without this the ship banks
      // while the player is dragging a debug slider, because a window-level
      // mousemove does not care what is under the cursor.
      if (!this.pointerLocked && !this.isOverCanvas(e)) return;
      const dx = e.movementX ?? 0;
      const dy = e.movementY ?? 0;
      // A still mouse fires no-op moves on some platforms; don't wake listeners.
      if (dx === 0 && dy === 0) return;
      this.eventBus.emit(MouseInputEvents.MOVE, { dx, dy });
    };

    this.downHandler = (e: MouseEvent) => {
      // Clicks that land on UI are not the game's to take.
      //
      // These listeners are on `window`, so every mousedown in the document
      // arrives here — including one on a debug panel, a button, or a link. The
      // capture request used to fire for all of them, so clicking any overlay
      // swallowed the cursor and the player had to press Esc to get it back to
      // the very control they were trying to use. Pointer capture is a canvas
      // gesture; anything else is somebody else's click.
      if (!this.isOverCanvas(e)) return;
      // First click buys the pointer, it doesn't pull the trigger.
      if (this.clicksToLock() && !this.pointerLocked) {
        this.requestPointerLock();
        return;
      }
      this.heldButtons.add(e.button);
      this.eventBus.emit(MouseInputEvents.DOWN, { button: e.button });
    };

    this.upHandler = (e: MouseEvent) => {
      this.heldButtons.delete(e.button);
      this.eventBus.emit(MouseInputEvents.UP, { button: e.button });
    };

    this.lockChangeHandler = () => {
      this.pointerLocked = this.isCanvasLocked();
      if (!this.pointerLocked) this.releaseHeldButtons();
      this.eventBus.emit(MouseInputEvents.LOCK_CHANGED, { locked: this.pointerLocked });
    };

    if (typeof window !== 'undefined') {
      window.addEventListener('mousemove', this.moveHandler);
      window.addEventListener('mousedown', this.downHandler);
      window.addEventListener('mouseup', this.upHandler);
    }
    if (typeof document !== 'undefined') {
      document.addEventListener('pointerlockchange', this.lockChangeHandler);
    }

    // Adopt the lock that already exists rather than assuming there isn't one.
    // A round reset rebuilds the game around the SAME canvas, so the pointer is
    // very often still captured — and since no pointerlockchange fires for a lock
    // that never changed, starting at `false` would silently drop every mouse
    // delta until the player pressed Esc and clicked again.
    this.pointerLocked = this.isCanvasLocked();
  }

  protected onShutdown(): void {
    if (typeof window !== 'undefined') {
      if (this.moveHandler) window.removeEventListener('mousemove', this.moveHandler);
      if (this.downHandler) window.removeEventListener('mousedown', this.downHandler);
      if (this.upHandler) window.removeEventListener('mouseup', this.upHandler);
    }
    if (typeof document !== 'undefined' && this.lockChangeHandler) {
      document.removeEventListener('pointerlockchange', this.lockChangeHandler);
    }
    this.moveHandler = null;
    this.downHandler = null;
    this.upHandler = null;
    this.lockChangeHandler = null;
    this.heldButtons.clear();
    this.pointerLocked = false;
  }

  protected onUpdate(_dt: number): void {
    // DOM-driven: every event is emitted from a handler attached in
    // onInitialize, so there is no per-frame work.
  }

  /** True if any matched MouseInput source demands pointer lock before motion. */
  private requiresLock(): boolean {
    for (const entity of this.entities) {
      if (entity.get(MouseInputComponent)!.requirePointerLock) return true;
    }
    return false;
  }

  /** True if any matched MouseInput source spends the first click on capture. */
  private clicksToLock(): boolean {
    for (const entity of this.entities) {
      if (entity.get(MouseInputComponent)!.clickToLock) return true;
    }
    return false;
  }

  private getCanvas(): HTMLCanvasElement | null {
    return this.world?.renderer?.getRenderingCanvas() ?? null;
  }

  /**
   * True when a pointer event happened on the game canvas rather than on UI
   * drawn over it. Missing canvas (headless, pre-init) counts as NOT over it, so
   * a test never accidentally captures.
   */
  private isOverCanvas(e: MouseEvent): boolean {
    const canvas = this.getCanvas();
    if (!canvas) return false;
    const target = e.target as Node | null;
    return target === canvas || (target !== null && canvas.contains(target));
  }

  /** True if the DOM currently has the pointer locked to our own canvas. */
  private isCanvasLocked(): boolean {
    if (typeof document === 'undefined') return false;
    const canvas = this.getCanvas();
    return canvas !== null && document.pointerLockElement === canvas;
  }

  private requestPointerLock(): void {
    this.getCanvas()?.requestPointerLock?.();
  }

  /**
   * Tell listeners every held button came up. Called when the pointer lock is
   * lost, because the DOM will not send those mouseups itself.
   */
  private releaseHeldButtons(): void {
    for (const button of this.heldButtons) {
      this.eventBus.emit(MouseInputEvents.UP, { button });
    }
    this.heldButtons.clear();
  }
}

export {
  MouseInputComponent,
  DEFAULT_MOUSE_INPUT_PARAMS,
  type MouseInputInput,
} from './MouseInput.defs';

MouseInput.contract.test.ts

11 ✓

ArcadeECS contract: MouseInput

Component() with no args constructs and applies defaults
Component merges sample input on top of defaults
Component.serialize() round-trips into a constructor input
System constructor signature is exactly (eventBus)
System declares a non-empty query.required
world.addSystem + initialize + update runs clean with no entity
adding the Component attaches the entity to the System
world.update(dt) does not throw with the entity attached
Adapter handles: create/dispose balance across entity lifecycle
EventBus has no lingering listeners after world.destroy()
Declared event names follow the "{domain}.{action}" convention

Last run 2026-09-09

MouseInput.contract.test.ts

// @vitest-environment jsdom
import { runMechanicContract } from '@babylonjsmarket/ecs/testing';
import { MouseInputComponent, MouseInputSystem } from './MouseInput';

// jsdom: MouseInputSystem attaches window/document pointer listeners in
// onInitialize, which the contract battery runs.
runMechanicContract({
  name: 'MouseInput',
  componentClass: MouseInputComponent,
  // A standalone input source, exactly like KeyboardInput: it only needs its own
  // marker component to match, and it emits its `mouse.*` events from DOM
  // handlers rather than during onUpdate — so no companions and no declared
  // events here. The emitted names are covered by MouseInput.test.ts, which can
  // dispatch real pointer events; the contract's output check only watches
  // update ticks and would always see zero.
  systemClass: MouseInputSystem,
  sampleInput: { requirePointerLock: false },
});

MouseInput.defs.test.ts

4 ✓

MouseInputComponent

demands pointer lock by default
spends the first click on capture by default
accepts both knobs turned off
serialize() round-trips into an equivalent component

Last run 2026-09-09

MouseInput.defs.test.ts

import { describe, expect, it } from 'vitest';
import { MouseInputComponent, DEFAULT_MOUSE_INPUT_PARAMS } from './MouseInput.defs';

describe('MouseInputComponent', () => {
  it('demands pointer lock by default', () => {
    expect(DEFAULT_MOUSE_INPUT_PARAMS.requirePointerLock).toBe(true);
    expect(new MouseInputComponent().requirePointerLock).toBe(true);
  });

  it('spends the first click on capture by default', () => {
    expect(DEFAULT_MOUSE_INPUT_PARAMS.clickToLock).toBe(true);
    expect(new MouseInputComponent().clickToLock).toBe(true);
  });

  it('accepts both knobs turned off', () => {
    const c = new MouseInputComponent({ requirePointerLock: false, clickToLock: false });
    expect(c.requirePointerLock).toBe(false);
    expect(c.clickToLock).toBe(false);
  });

  it('serialize() round-trips into an equivalent component', () => {
    const c = new MouseInputComponent({ requirePointerLock: false, clickToLock: true });
    const copy = new MouseInputComponent(c.serialize());
    expect(copy.serialize()).toEqual({ requirePointerLock: false, clickToLock: true });
  });
});

MouseInput.panel.test.tsx

6 ✓

MouseInputPanel

will not build a panel for a world with no mouse input
releasing the lock writes EVERY source, since the System ORs them
click-to-lock writes every source too
reads live values rather than a snapshot
reports whether the pointer is captured right now
counts the sources

Last run 2026-09-09

MouseInput.panel.test.tsx

// @vitest-environment jsdom
import { describe, it, expect, beforeEach } from 'vitest';
import { EventBus, World, MockRendererAdapter } from '@babylonjsmarket/ecs';
import { MouseInputComponent } from './MouseInput.defs';
import { MouseInputPanelComponent, MouseInputPanelSystem } from './MouseInput.panel';

/**
 * The System treats several MouseInput sources as an OR — one of them demanding
 * lock is enough — so a toggle that wrote only the first would be a switch you
 * could flip with nothing happening.
 */
describe('MouseInputPanel', () => {
  let eventBus: EventBus;
  let world: World;
  let system: MouseInputPanelSystem;
  let a: MouseInputComponent;
  let b: MouseInputComponent;

  function control(label: string): {
    bind?: { get(): boolean | number | string; set(v: boolean): void };
  } {
    const spec = (system as unknown as {
      buildSpec(w: World): { sections: Array<{ controls: Array<Record<string, unknown>> }> };
    }).buildSpec(world);
    for (const s of spec.sections) {
      for (const c of s.controls) if (c.label === label) return c as never;
    }
    throw new Error(`no control "${label}"`);
  }

  beforeEach(() => {
    eventBus = new EventBus();
    world = new World({ eventBus, renderer: new MockRendererAdapter() });
    system = new MouseInputPanelSystem(eventBus);
    world.addSystem(system);
    a = new MouseInputComponent({ requirePointerLock: true, clickToLock: true });
    b = new MouseInputComponent({ requirePointerLock: true, clickToLock: false });
    world.createEntity().add(a);
    world.createEntity().add(b);
    world.createEntity().add(new MouseInputPanelComponent());
    world.initialize();
  });

  it('will not build a panel for a world with no mouse input', () => {
    const bare = new World({ eventBus: new EventBus(), renderer: new MockRendererAdapter() });
    expect((system as unknown as { canBuild(w: World): boolean }).canBuild(bare)).toBe(false);
  });

  it('releasing the lock writes EVERY source, since the System ORs them', () => {
    control('require lock').bind!.set(false);
    expect(a.requirePointerLock).toBe(false);
    expect(b.requirePointerLock).toBe(false);
  });

  it('click-to-lock writes every source too', () => {
    control('click to lock').bind!.set(true);
    expect(a.clickToLock).toBe(true);
    expect(b.clickToLock).toBe(true);
  });

  it('reads live values rather than a snapshot', () => {
    a.requirePointerLock = false;
    expect(control('require lock').bind!.get()).toBe(false);
  });

  it('reports whether the pointer is captured right now', () => {
    expect(control('pointer locked').bind!.get()).toBe('no');
  });

  it('counts the sources', () => {
    expect(control('sources').bind!.get()).toBe(2);
  });
});

MouseInput.test.ts

24 ✓

MouseInputSystem

re-exports the component for the registry
is not pauseable — the mouse still reaches a pause menu
does no per-frame work
drops motion until the pointer is locked
forwards raw device pixels, unscaled
ignores a no-op move
reports motion straight away when pointer lock is not required
spends the first click on capture instead of the trigger
reports button presses once the pointer is held
passes the button index through
clicks straight through when clickToLock is off
announces the lock being taken and released
is not locked when some other element holds the pointer
releases held buttons when the lock is lost
does not re-release a button that already came up
stops listening after shutdown
adopts a pointer lock that was already held at startup
does not adopt a lock held by some other element at startup
survives having no canvas to lock

MouseInputSystem › clicks that are not the game's to take

does not capture the pointer when the click lands on UI
still captures when the click lands on the canvas
does not report a button press from a click on UI
does not steer from a mouse drag across UI while unlocked
steers from anywhere once the pointer is genuinely captured

Last run 2026-09-09

MouseInput.test.ts

import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { EventBus, World, MockRendererAdapter } from '@babylonjsmarket/ecs';
import { MouseInputComponent, MouseInputSystem } from './MouseInput';
import { MouseInputEvents } from '../../inputEvents';

/**
 * Dispatch a mouse event on `window` the way the DOM really does — with a
 * `target`. The System listens on `window` (so it sees events anywhere) but acts
 * only on the ones whose target is the canvas, so the target is load-bearing to
 * every test here, not incidental detail.
 */
function fire(e: MouseEvent, target: EventTarget | null): void {
  if (target) Object.defineProperty(e, 'target', { value: target, configurable: true });
  window.dispatchEvent(e);
}

/** A mousemove carrying a relative delta, the way a locked pointer reports. */
function mousemove(dx: number, dy: number, target: EventTarget | null = theCanvas): void {
  const e = new MouseEvent('mousemove');
  // movementX/Y are read-only accessors on the prototype; jsdom doesn't
  // synthesise them from the constructor, so define them on the instance.
  Object.defineProperty(e, 'movementX', { value: dx });
  Object.defineProperty(e, 'movementY', { value: dy });
  fire(e, target);
}

const mousedown = (button = 0, target: EventTarget | null = theCanvas) =>
  fire(new MouseEvent('mousedown', { button }), target);
const mouseup = (button = 0, target: EventTarget | null = theCanvas) =>
  fire(new MouseEvent('mouseup', { button }), target);

/** The canvas the current test's System is bound to (set in beforeEach). */
let theCanvas: HTMLCanvasElement | null = null;

/** Point document.pointerLockElement at `el` and fire the change event. */
function setPointerLock(el: Element | null): void {
  Object.defineProperty(document, 'pointerLockElement', {
    value: el,
    configurable: true,
  });
  document.dispatchEvent(new Event('pointerlockchange'));
}

describe('MouseInputSystem', () => {
  let eventBus: EventBus;
  let world: World;
  let system: MouseInputSystem;
  let renderer: MockRendererAdapter;
  let canvas: HTMLCanvasElement;
  let seen: Array<{ type: string; data: unknown }>;

  beforeEach(async () => {
    canvas = document.createElement('canvas');
    document.body.appendChild(canvas);
    theCanvas = canvas;
    renderer = new MockRendererAdapter();
    await renderer.init(canvas);

    eventBus = new EventBus();
    world = new World({ eventBus, renderer });
    system = new MouseInputSystem(eventBus);
    world.addSystem(system);
    world.createEntity().add(new MouseInputComponent());
    world.initialize();

    seen = [];
    for (const type of Object.values(MouseInputEvents)) {
      eventBus.on(type, (data: unknown) => seen.push({ type, data }));
    }
  });

  afterEach(() => {
    world.shutdown();
    canvas.remove();
    setPointerLock(null);
  });

  const moves = () => seen.filter((e) => e.type === MouseInputEvents.MOVE).map((e) => e.data);
  const ups = () => seen.filter((e) => e.type === MouseInputEvents.UP).map((e) => e.data);
  const downs = () => seen.filter((e) => e.type === MouseInputEvents.DOWN).map((e) => e.data);

  it('re-exports the component for the registry', () => {
    expect(typeof MouseInputComponent).toBe('function');
    expect(new MouseInputComponent()).toBeInstanceOf(MouseInputComponent);
  });

  it('is not pauseable — the mouse still reaches a pause menu', () => {
    expect(system.pauseable).toBe(false);
  });

  it('does no per-frame work', () => {
    expect(() => world.update(1 / 60)).not.toThrow();
    expect(seen).toHaveLength(0);
  });

  // The whole reason requirePointerLock defaults on: the travel a player spends
  // reaching for the canvas must not arrive as one enormous first delta.
  it('drops motion until the pointer is locked', () => {
    mousemove(50, 50);
    expect(moves()).toHaveLength(0);

    setPointerLock(canvas);
    mousemove(50, 50);
    expect(moves()).toEqual([{ dx: 50, dy: 50 }]);
  });

  it('forwards raw device pixels, unscaled', () => {
    setPointerLock(canvas);
    mousemove(-13, 7);
    expect(moves()).toEqual([{ dx: -13, dy: 7 }]);
  });

  it('ignores a no-op move', () => {
    setPointerLock(canvas);
    mousemove(0, 0);
    expect(moves()).toHaveLength(0);
  });

  it('reports motion straight away when pointer lock is not required', async () => {
    world.shutdown();
    const bus = new EventBus();
    const w = new World({ eventBus: bus, renderer });
    w.addSystem(new MouseInputSystem(bus));
    w.createEntity().add(new MouseInputComponent({ requirePointerLock: false }));
    w.initialize();

    const got: unknown[] = [];
    bus.on(MouseInputEvents.MOVE, (d: unknown) => got.push(d));
    mousemove(4, 5);

    expect(got).toEqual([{ dx: 4, dy: 5 }]);
    w.shutdown();
  });

  it('spends the first click on capture instead of the trigger', () => {
    const request = vi.fn();
    canvas.requestPointerLock = request;

    mousedown(0);

    expect(request).toHaveBeenCalledTimes(1);
    expect(downs()).toHaveLength(0);
  });

  it('reports button presses once the pointer is held', () => {
    setPointerLock(canvas);

    mousedown(0);
    expect(downs()).toEqual([{ button: 0 }]);

    mouseup(0);
    expect(ups()).toEqual([{ button: 0 }]);
  });

  it('passes the button index through', () => {
    setPointerLock(canvas);
    mousedown(2);
    expect(downs()).toEqual([{ button: 2 }]);
  });

  it('clicks straight through when clickToLock is off', async () => {
    world.shutdown();
    const bus = new EventBus();
    const w = new World({ eventBus: bus, renderer });
    w.addSystem(new MouseInputSystem(bus));
    w.createEntity().add(new MouseInputComponent({ clickToLock: false }));
    w.initialize();

    const got: unknown[] = [];
    bus.on(MouseInputEvents.DOWN, (d: unknown) => got.push(d));
    mousedown(0);

    expect(got).toEqual([{ button: 0 }]);
    w.shutdown();
  });

  it('announces the lock being taken and released', () => {
    setPointerLock(canvas);
    setPointerLock(null);

    expect(seen.filter((e) => e.type === MouseInputEvents.LOCK_CHANGED).map((e) => e.data)).toEqual([
      { locked: true },
      { locked: false },
    ]);
  });

  it('is not locked when some other element holds the pointer', () => {
    const other = document.createElement('div');
    setPointerLock(other);

    expect(seen.filter((e) => e.type === MouseInputEvents.LOCK_CHANGED).map((e) => e.data)).toEqual([
      { locked: false },
    ]);
  });

  // The DOM sends no mouseup once the pointer is gone, so without this the guns
  // keep firing after the player has hit Esc.
  it('releases held buttons when the lock is lost', () => {
    setPointerLock(canvas);
    mousedown(0);
    mousedown(2);
    seen.length = 0;

    setPointerLock(null);

    expect(ups()).toEqual([{ button: 0 }, { button: 2 }]);
  });

  it('does not re-release a button that already came up', () => {
    setPointerLock(canvas);
    mousedown(0);
    mouseup(0);
    seen.length = 0;

    setPointerLock(null);

    expect(ups()).toHaveLength(0);
  });

  it('stops listening after shutdown', () => {
    setPointerLock(canvas);
    world.shutdown();
    seen.length = 0;

    mousemove(20, 20);
    mousedown(0);

    expect(seen).toHaveLength(0);
  });

  // A round reset rebuilds the game around the same canvas, so the pointer is
  // usually still captured — and no pointerlockchange fires for a lock that never
  // changed. Starting at `false` would drop every delta until the player pressed
  // Esc and clicked again.
  it('adopts a pointer lock that was already held at startup', () => {
    setPointerLock(canvas);
    world.shutdown();

    const bus = new EventBus();
    const w = new World({ eventBus: bus, renderer });
    w.addSystem(new MouseInputSystem(bus));
    w.createEntity().add(new MouseInputComponent());
    w.initialize();

    const got: unknown[] = [];
    bus.on(MouseInputEvents.MOVE, (d: unknown) => got.push(d));
    mousemove(9, 9);

    expect(got).toEqual([{ dx: 9, dy: 9 }]);
    w.shutdown();
  });

  it('does not adopt a lock held by some other element at startup', () => {
    setPointerLock(document.createElement('div'));
    world.shutdown();

    const bus = new EventBus();
    const w = new World({ eventBus: bus, renderer });
    w.addSystem(new MouseInputSystem(bus));
    w.createEntity().add(new MouseInputComponent());
    w.initialize();

    const got: unknown[] = [];
    bus.on(MouseInputEvents.MOVE, (d: unknown) => got.push(d));
    mousemove(9, 9);

    expect(got).toHaveLength(0);
    w.shutdown();
  });

  it('survives having no canvas to lock', () => {
    const bus = new EventBus();
    const w = new World({ eventBus: bus }); // no renderer at all
    w.addSystem(new MouseInputSystem(bus));
    w.createEntity().add(new MouseInputComponent());
    w.initialize();

    expect(() => mousedown(0)).not.toThrow();
    w.shutdown();
  });

  describe('clicks that are not the game\'s to take', () => {
    /** A debug panel drawn over the canvas, like the viz overlay. */
    function overlay(): HTMLElement {
      const el = document.createElement('div');
      document.body.appendChild(el);
      return el;
    }

    it('does not capture the pointer when the click lands on UI', () => {
      // The reported bug. These listeners are on `window`, so a mousedown on a
      // debug panel arrives here too; it used to request pointer lock, which
      // swallowed the cursor the player was trying to use the panel WITH, and
      // only Esc gave it back.
      const el = overlay();
      const req = vi.fn();
      canvas.requestPointerLock = req as never;
      mousedown(0, el);
      expect(req).not.toHaveBeenCalled();
      el.remove();
    });

    it('still captures when the click lands on the canvas', () => {
      const req = vi.fn();
      canvas.requestPointerLock = req as never;
      mousedown(0, canvas);
      expect(req).toHaveBeenCalledTimes(1);
    });

    it('does not report a button press from a click on UI', () => {
      const el = overlay();
      setPointerLock(canvas);
      seen.length = 0;
      mousedown(0, el);
      expect(seen.filter((s) => s.type === MouseInputEvents.DOWN)).toEqual([]);
      el.remove();
    });

    it('does not steer from a mouse drag across UI while unlocked', () => {
      // Dragging a debug slider must not bank the ship.
      const el = overlay();
      world.shutdown();
      world = new World({ eventBus, renderer });
      system = new MouseInputSystem(eventBus);
      world.addSystem(system);
      world.createEntity().add(new MouseInputComponent({ requirePointerLock: false }));
      world.initialize();
      seen.length = 0;

      mousemove(9, 9, el);
      expect(seen.filter((s) => s.type === MouseInputEvents.MOVE)).toEqual([]);

      mousemove(4, 5, canvas);
      expect(seen.filter((s) => s.type === MouseInputEvents.MOVE))
        .toEqual([{ type: MouseInputEvents.MOVE, data: { dx: 4, dy: 5 } }]);
      el.remove();
    });

    it('steers from anywhere once the pointer is genuinely captured', () => {
      // A locked pointer has no on-screen position, so target-gating motion then
      // would throw away every delta the capture exists to deliver.
      setPointerLock(canvas);
      seen.length = 0;
      mousemove(3, 2, document.body);
      expect(seen.filter((s) => s.type === MouseInputEvents.MOVE))
        .toEqual([{ type: MouseInputEvents.MOVE, data: { dx: 3, dy: 2 } }]);
    });
  });
});