@driftengine/native-host 4.0.0

package/src/mouseEvents.ts

@@ -0,0 +1,328 @@
+/**
+ * The mouse, as a page hears it from Chrome: pointer 1, and every event a browser builds around it.
+ *
+ * **What Chrome sends, measured 2026-09-19 in Chrome 151 over the DevTools protocol**, on a page
+ * whose canvas filled it, is what this sends:
+ * - Coming in is `pointerover`, `pointerenter` at the document and then the canvas, the same three as
+ *   mouse events, and then the move. Going out is the reverse, the canvas before the document.
+ * - A press is `pointerdown` then `mousedown`, whose `detail` counts the clicks, and a release is
+ *   `pointerup`, `mouseup` and a `click`. The click is a `PointerEvent`, as are `contextmenu` and
+ *   `auxclick`, and a second click in time and place is followed by `dblclick`.
+ * - The right button opens its context menu on the press, as on Linux.
+ * - A second button pressed while one is held is a `pointermove` rather than a `pointerdown`. The
+ *   first button's release after that clicks nothing, with a `detail` of 0.
+ *
+ * **Pointer lock is the cursor hidden and put back in the middle of the window after every move**,
+ * the delta being how far it got. `@kmamal/sdl` 0.11 offers no relative mouse mode and reports only
+ * where the pointer is, so this is the one way to it; it carries the desktop's acceleration, which a
+ * browser's lock without `unadjustedMovement` does too.
+ *
+ * What it gives up: clicks count by Chromium's own figures, 500 ms between presses and 2 px either
+ * way of the first, where Chrome on a desktop that sets its own uses that; a wheel notch is 100
+ * pixels, a browser's figure varying by platform; and a drag out of the window stays over the canvas
+ * until its release, which is SDL's capture of a held button.
+ */
+
+import type { NativeCanvas } from './canvas.ts';
+import { sdlCursor } from './canvasStyle.ts';
+import type { HostPage } from './page.ts';
+import {
+  type ModifierInit,
+  type MouseInit,
+  MouseEvent,
+  PointerEvent,
+  WheelEvent,
+} from './uiEvents.ts';
+
+export interface SdlPointer {
+  readonly x: number;
+  readonly y: number;
+  readonly button?: number;
+  readonly dx?: number;
+  readonly dy?: number;
+  readonly flipped?: boolean;
+  /** SDL's mouse made from a finger, which the touch events already said. */
+  readonly touch?: boolean;
+}
+
+/** Where the window is on the screen and how large, and SDL's mouse, which the lock warps. */
+export interface MouseWindow {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+export interface EventMouse {
+  setPosition(x: number, y: number): void;
+  showCursor(show?: boolean): void;
+  capture(): void;
+  uncapture(): void;
+  /** One of SDL's system cursors, by name. */
+  setCursor?(cursor: string): void;
+}
+
+/** SDL counts buttons from 1: left, middle, right, back, forward. A browser counts from 0. */
+const BUTTON = [-1, 0, 1, 2, 3, 4];
+/** And `buttons` is a mask in which the right button comes before the middle. */
+const BUTTON_BIT = [0, 1, 4, 2, 8, 16];
+/** One notch of the wheel, in the pixels `deltaMode` 0 counts in. */
+const NOTCH_PX = 100;
+const CLICK_MS = 500;
+const CLICK_PX = 2;
+
+export class MouseModel {
+  private buttons = 0;
+  /** The button whose press a release would complete as a click, or −1. */
+  private pressed = -1;
+  private count = 0;
+  private lastPress = { at: Number.NEGATIVE_INFINITY, x: 0, y: 0, button: -1 };
+  private x = 0;
+  private y = 0;
+  private inside = false;
+  /** The pointer left while a button held it here, so it leaves once the last one is let go. */
+  private away = false;
+  private locked = false;
+  /** Whether the page hid the cursor, `cursor: none`, which a lock let go does not undo. */
+  private cursorHidden = false;
+
+  constructor(
+    private readonly window: MouseWindow,
+    private readonly mouse: EventMouse,
+    private readonly page: HostPage,
+    private readonly canvas: NativeCanvas,
+    private readonly modifiers: () => ModifierInit,
+    private readonly now: () => number,
+  ) {
+    page.setPointerLocker((lock) => this.lock(lock));
+    page.capture.add(1, () => this.buttons !== 0);
+  }
+
+  /** The cursor a page wrote to the canvas's style. */
+  cursor(css: string): void {
+    const cursor = sdlCursor(css);
+    const hidden = cursor === null;
+    if (hidden !== this.cursorHidden) {
+      this.cursorHidden = hidden;
+      if (!this.locked) this.mouse.showCursor(!hidden);
+    }
+    if (cursor !== null) this.mouse.setCursor?.(cursor);
+  }
+
+  get isLocked(): boolean {
+    return this.locked;
+  }
+
+  move(event: SdlPointer): void {
+    let dx = event.x - this.x;
+    let dy = event.y - this.y;
+    if (this.locked) {
+      /* The warp back lands as a move to where the pointer already is: nothing moved. */
+      if (dx === 0 && dy === 0) return;
+      const centre = this.middle();
+      this.mouse.setPosition(centre.x, centre.y);
+    } else {
+      this.x = event.x;
+      this.y = event.y;
+      if (!this.inside) {
+        this.enter();
+        dx = 0;
+        dy = 0;
+      }
+    }
+    this.both('move', this.init(dx, dy, -1, 0));
+  }
+
+  down(event: SdlPointer): void {
+    this.settle(event);
+    const button = BUTTON[event.button ?? 0] ?? -1;
+    const chord = this.buttons !== 0;
+    this.buttons |= BUTTON_BIT[event.button ?? 0] ?? 0;
+    const at = this.now();
+    const last = this.lastPress;
+    const again =
+      button === last.button &&
+      at - last.at <= CLICK_MS &&
+      Math.abs(this.x - last.x) <= CLICK_PX &&
+      Math.abs(this.y - last.y) <= CLICK_PX;
+    this.count = again ? this.count + 1 : 1;
+    this.lastPress = { at, x: this.x, y: this.y, button };
+    this.pressed = button;
+    /* A press is a person's gesture, noted before its events so their listeners may use it. */
+    this.page.userActivation.notify();
+    const init = this.init(0, 0, button, this.count);
+    this.pointer(chord ? 'pointermove' : 'pointerdown', init);
+    const mousedown = this.mouseEvent('mousedown', init);
+    if (!mousedown.defaultPrevented) this.canvas.focus();
+    /* On the press, where Chrome on Linux sends it. */
+    if (button === 2) this.pointer('contextmenu', { ...init, detail: 0 }, false);
+  }
+
+  up(event: SdlPointer): void {
+    this.settle(event);
+    const button = BUTTON[event.button ?? 0] ?? -1;
+    this.buttons &= ~(BUTTON_BIT[event.button ?? 0] ?? 0);
+    const clicked = this.pressed === button;
+    const init = this.init(0, 0, button, clicked ? this.count : 0);
+    this.pointer(this.buttons !== 0 ? 'pointermove' : 'pointerup', init);
+    this.mouseEvent('mouseup', init);
+    if (this.buttons === 0) this.page.capture.releaseImplicitly(1, { ...init, ...POINTER(0) });
+    if (clicked) {
+      this.pointer(button === 0 ? 'click' : 'auxclick', init, false);
+      if (button === 0 && this.count === 2) this.mouseEvent('dblclick', init);
+    }
+    this.pressed = -1;
+    const { width, height } = this.window;
+    const outside = this.x < 0 || this.y < 0 || this.x >= width || this.y >= height;
+    if (this.buttons === 0 && (this.away || outside)) this.leave();
+  }
+
+  wheel(event: SdlPointer): void {
+    this.settle(event);
+    const direction = event.flipped === true ? -1 : 1;
+    this.canvas.dispatchEvent(
+      new WheelEvent('wheel', {
+        ...this.init(0, 0, -1, 0),
+        bubbles: true,
+        cancelable: true,
+        deltaX: (event.dx ?? 0) * direction * NOTCH_PX,
+        deltaY: -(event.dy ?? 0) * direction * NOTCH_PX,
+        deltaMode: 0,
+      }),
+    );
+  }
+
+  /** SDL's word that the pointer is over the window again, which cancels a leave still waiting. */
+  hover(): void {
+    this.away = false;
+  }
+
+  /** SDL's word that the pointer left the window: out and leave, once no button holds it here. */
+  leave(): void {
+    if (!this.inside || this.locked) return;
+    if (this.buttons !== 0) {
+      this.away = true;
+      return;
+    }
+    this.away = false;
+    this.inside = false;
+    const init = this.init(0, 0, -1, 0);
+    this.pointer('pointerout', init);
+    this.boundary('pointerleave', init, [this.canvas, this.page.document]);
+    this.mouseEvent('mouseout', init);
+    this.boundary('mouseleave', init, [this.canvas, this.page.document]);
+  }
+
+  /** A press or the wheel where no move came first: the pointer is here, so it came in. */
+  private settle(event: SdlPointer): void {
+    if (this.locked) return;
+    this.x = event.x;
+    this.y = event.y;
+    if (!this.inside) this.enter();
+  }
+
+  private enter(): void {
+    this.inside = true;
+    const init = this.init(0, 0, -1, 0);
+    this.pointer('pointerover', init);
+    this.boundary('pointerenter', init, [this.page.document, this.canvas]);
+    this.mouseEvent('mouseover', init);
+    this.boundary('mouseenter', init, [this.page.document, this.canvas]);
+  }
+
+  /** An enter or a leave, which does not bubble: sent to each node it crosses, in turn. */
+  private boundary(type: string, init: MouseInit, nodes: readonly EventTarget[]): void {
+    const Kind = type.startsWith('pointer') ? PointerEvent : MouseEvent;
+    const extra = type.startsWith('pointer') ? POINTER(init.buttons ?? 0) : {};
+    for (const node of nodes) {
+      node.dispatchEvent(new Kind(type, { ...init, ...extra, bubbles: false, cancelable: false }));
+    }
+  }
+
+  private both(type: string, init: MouseInit): void {
+    this.pointer(`pointer${type}`, init);
+    this.mouseEvent(`mouse${type}`, init);
+  }
+
+  private pointer(type: string, init: MouseInit, primary = true): PointerEvent {
+    /* A change of capture is told just before the pointer's next pointer event. */
+    if (type.startsWith('pointer')) {
+      this.page.capture.process(1, { ...init, ...POINTER(init.buttons ?? 0), isPrimary: true });
+    }
+    const event = new PointerEvent(type, {
+      ...init,
+      ...POINTER(init.buttons ?? 0),
+      isPrimary: primary,
+      detail: type === 'click' || type === 'auxclick' ? (init.detail ?? 0) : 0,
+      bubbles: true,
+      cancelable: true,
+    });
+    this.canvas.dispatchEvent(event);
+    return event;
+  }
+
+  private mouseEvent(type: string, init: MouseInit): MouseEvent {
+    const event = new MouseEvent(type, { ...init, bubbles: true, cancelable: true });
+    this.canvas.dispatchEvent(event);
+    return event;
+  }
+
+  private init(movementX: number, movementY: number, button: number, detail: number): MouseInit {
+    return {
+      clientX: this.x,
+      clientY: this.y,
+      screenX: this.window.x + this.x,
+      screenY: this.window.y + this.y,
+      movementX,
+      movementY,
+      button,
+      buttons: this.buttons,
+      detail,
+      ...this.modifiers(),
+    };
+  }
+
+  private middle(): { x: number; y: number } {
+    return {
+      x: Math.round(this.window.x + this.window.width / 2),
+      y: Math.round(this.window.y + this.window.height / 2),
+    };
+  }
+
+  /*
+   * Hide the cursor and hold it, or let it go. SDL refuses to capture the mouse for a window without
+   * focus, and says so by throwing; that is a refused lock, with the cursor left as it was, and not
+   * an error to take the process down from inside a click.
+   */
+  private lock(lock: boolean): boolean {
+    const { mouse } = this;
+    if (!lock) {
+      this.locked = false;
+      /* A release always succeeds from the page's side, whatever SDL says about it. */
+      try {
+        mouse.showCursor(!this.cursorHidden);
+        mouse.uncapture();
+      } catch {
+        /* Nothing held to let go of. */
+      }
+      return true;
+    }
+    try {
+      mouse.showCursor(false);
+      mouse.capture();
+      const centre = this.middle();
+      mouse.setPosition(centre.x, centre.y);
+      this.x = centre.x - this.window.x;
+      this.y = centre.y - this.window.y;
+      this.locked = true;
+      return true;
+    } catch {
+      mouse.showCursor(true);
+      return false;
+    }
+  }
+}
+
+/** The mouse is pointer 1, always primary, one pixel across, and pressing at half pressure. */
+function POINTER(buttons: number) {
+  return { pointerId: 1, pointerType: 'mouse', pressure: buttons !== 0 ? 0.5 : 0 };
+}

package/src/page.ts

@@ -0,0 +1,337 @@
+/**
+ * The page a scene expects around its canvas, for a host that has none: `window`, `document`, and
+ * the animation frames a browser schedules.
+ *
+ * **What is here is what gets read**, listed from every listener and property the engine's packages
+ * and the published scenes reach: keys, pointers, the mouse, the wheel, focus, resizing and
+ * unloading on `window`; visibility, focus and pointer lock on `document`; `requestAnimationFrame`,
+ * which the engine's input polls from. The three are a tree (`domTree.ts`), so an event is
+ * captured and bubbles as it does in a browser, and each answers the `on…` attributes. Anything
+ * else a scene reaches for is a gap named when it is met — `createElement` refuses by name —
+ * rather than a DOM this pretends to be.
+ *
+ * **Focus is a browser's.** The window has it or not, as SDL says; within it the canvas is focused
+ * only once it is focusable, which a canvas is when it is given a `tabIndex`, and keys go to what
+ * is focused, or to the document when nothing is.
+ *
+ * **A `document` is what the engine's splash looks for**, and it mounts one unless the scene says
+ * `splash: false` or the page carries a shell's bridge (`__driftHost`). The published scenes all
+ * say so; a packaged game is given the bridge.
+ */
+
+import { UserActivation } from './activation.ts';
+import type { NativeCanvas } from './canvas.ts';
+import { type Handlers, HostNode } from './domTree.ts';
+import { installEventClasses } from './eventClasses.ts';
+import { PageFullscreen } from './fullscreen.ts';
+import { MediaQueries, type MediaQueryList } from './mediaQueries.ts';
+import { PointerCapture } from './pointerCapture.ts';
+import { FocusEvent } from './uiEvents.ts';
+
+/** Every input event a page can be told of, which each of the three nodes answers `on…` for. */
+export const INPUT_TYPES = [
+  ...['keydown', 'keypress', 'keyup', 'focus', 'blur', 'wheel', 'contextmenu'],
+  ...['click', 'dblclick', 'auxclick', 'mousedown', 'mouseup', 'mousemove'],
+  ...['mouseover', 'mouseout', 'mouseenter', 'mouseleave'],
+  ...['pointerdown', 'pointerup', 'pointermove', 'pointerover', 'pointerout'],
+  ...['pointerenter', 'pointerleave', 'pointercancel', 'gotpointercapture', 'lostpointercapture'],
+  ...['touchstart', 'touchmove', 'touchend', 'touchcancel', 'fullscreenchange', 'fullscreenerror'],
+] as const;
+
+type InputType = (typeof INPUT_TYPES)[number];
+const WINDOW_TYPES = ['resize', 'beforeunload', 'gamepadconnected', 'gamepaddisconnected'] as const;
+const DOCUMENT_TYPES = [
+  'visibilitychange',
+  'pointerlockchange',
+  'pointerlockerror',
+  'fullscreenchange',
+  'fullscreenerror',
+] as const;
+
+/* The attributes `HostNode.handles` defines below, declared for the checker. */
+export interface PageWindow extends Handlers<InputType | (typeof WINDOW_TYPES)[number]> {}
+export interface PageDocument extends Handlers<InputType | (typeof DOCUMENT_TYPES)[number]> {}
+
+export class PageWindow extends HostNode {
+  canvas: NativeCanvas | null = null;
+  /** Answered by the page, which knows what a query asks about (`mediaQueries.ts`). */
+  matchMedia: (query: string) => MediaQueryList = () => {
+    throw new Error('[driftengine] a window no page holds has no media to query');
+  };
+  get innerWidth(): number {
+    return this.canvas?.clientWidth ?? 0;
+  }
+  get innerHeight(): number {
+    return this.canvas?.clientHeight ?? 0;
+  }
+  get devicePixelRatio(): number {
+    return this.canvas?.pixelRatio ?? 1;
+  }
+  static {
+    HostNode.handles(PageWindow.prototype, [...INPUT_TYPES, ...WINDOW_TYPES]);
+  }
+}
+
+export class PageDocument extends HostNode {
+  visibilityState: DocumentVisibilityState = 'visible';
+  pointerLockElement: Element | null = null;
+  /** What is focused: the canvas, once it is focusable and asked, or nothing. */
+  activeElement: NativeCanvas | null = null;
+  /** Set by the page that owns this document, which is what holds the lock and the focus. */
+  release: (() => void) | null = null;
+  focused = true;
+  /** The page's fullscreen, which this document reports. */
+  fullscreenControl: PageFullscreen | null = null;
+  readonly fullscreenEnabled = true;
+
+  get fullscreenElement(): NativeCanvas | null {
+    return this.fullscreenControl?.element ?? null;
+  }
+
+  /** The legacy flag, still read. */
+  get fullscreen(): boolean {
+    return this.fullscreenElement !== null;
+  }
+
+  exitFullscreen(): Promise<void> {
+    return this.fullscreenControl?.exit() ?? Promise.resolve();
+  }
+
+  get hidden(): boolean {
+    return this.visibilityState !== 'visible';
+  }
+
+  hasFocus(): boolean {
+    return this.focused;
+  }
+
+  exitPointerLock(): void {
+    this.release?.();
+  }
+
+  createElement(tag: string): never {
+    throw new Error(`[driftengine] the native host has no DOM to make a <${tag}> in`);
+  }
+
+  static {
+    HostNode.handles(PageDocument.prototype, [...INPUT_TYPES, ...DOCUMENT_TYPES]);
+  }
+}
+
+export interface HostPageOptions {
+  /** The clock a gesture's five seconds are measured on, in milliseconds. */
+  readonly now?: () => number;
+}
+
+export class HostPage {
+  readonly window = new PageWindow();
+  readonly document = new PageDocument();
+  /** Whether a person has just done something (`activation.ts`), as `navigator.userActivation`. */
+  readonly userActivation: UserActivation;
+  readonly fullscreen: PageFullscreen;
+  /** Which pointers the page holds (`pointerCapture.ts`). */
+  readonly capture = new PointerCapture();
+  readonly media: MediaQueries;
+  /** Whether a finger has landed: the one proof of a touch screen SDL gives. */
+  private touched = false;
+  /* Two queues swapped each frame, so a frame allocates nothing and asks made during it wait. */
+  private asked = new Map<number, FrameRequestCallback>();
+  private due = new Map<number, FrameRequestCallback>();
+  private nextId = 1;
+  private readonly lockListeners: ((locked: boolean) => void)[] = [];
+  private locker: ((lock: boolean) => boolean) | null = null;
+
+  constructor(options: HostPageOptions = {}) {
+    this.userActivation = new UserActivation(options.now ?? (() => performance.now()));
+    this.fullscreen = new PageFullscreen(this.userActivation);
+    this.document.parentNode = this.window;
+    this.document.release = () => this.unlock();
+    this.document.fullscreenControl = this.fullscreen;
+    this.fullscreen.changed = () => this.media.changed();
+    this.media = new MediaQueries(() => ({
+      width: this.window.innerWidth,
+      height: this.window.innerHeight,
+      pixelRatio: this.window.devicePixelRatio,
+      fullscreen: this.document.fullscreenElement !== null,
+      touched: this.touched,
+    }));
+    this.window.matchMedia = (query) => this.media.match(query);
+  }
+
+  /** A finger landed, so this is a touch screen, whatever SDL listed. */
+  noteTouch(): void {
+    if (this.touched) return;
+    this.touched = true;
+    this.media.changed();
+  }
+
+  readonly requestAnimationFrame = (callback: FrameRequestCallback): number => {
+    const id = this.nextId;
+    this.nextId += 1;
+    this.asked.set(id, callback);
+    return id;
+  };
+
+  readonly cancelAnimationFrame = (id: number): void => {
+    this.asked.delete(id);
+    this.due.delete(id);
+  };
+
+  /** One frame: the callbacks asked for before it began, in the order they were asked. */
+  runFrame(now: number): void {
+    const due = this.asked;
+    this.asked = this.due;
+    this.due = due;
+    for (const [id, callback] of due) {
+      /* Looked up again, so a callback cancelled by an earlier one this frame does not run. */
+      if (!due.has(id)) continue;
+      due.delete(id);
+      callback(now);
+    }
+  }
+
+  /** Whether the window can be seen, as `document.visibilityState` reports it. */
+  setVisible(visible: boolean): void {
+    const state: DocumentVisibilityState = visible ? 'visible' : 'hidden';
+    if (this.document.visibilityState === state) return;
+    this.document.visibilityState = state;
+    this.document.dispatchEvent(new Event('visibilitychange'));
+  }
+
+  /**
+   * The window gaining or losing the focus: the focused canvas is told first, as the element a
+   * browser blurs, and then the window.
+   */
+  setFocused(focused: boolean): void {
+    if (this.document.focused === focused) return;
+    this.document.focused = focused;
+    const canvas = this.document.activeElement;
+    if (canvas !== null) focusEvents(canvas, focused);
+    this.window.dispatchEvent(new FocusEvent(focused ? 'focus' : 'blur'));
+  }
+
+  /** Where a key goes: the focused element, or the document when nothing is focused. */
+  keyTarget(): HostNode {
+    return this.document.activeElement ?? this.document;
+  }
+
+  /** Hold `canvas` in this page: its parent, its pointer lock and its focus are the page's. */
+  attach(canvas: NativeCanvas): void {
+    canvas.parentNode = this.document;
+    this.window.canvas = canvas;
+    canvas.lockPointer = () => {
+      if (!this.userActivation.isActive) {
+        this.document.dispatchEvent(new Event('pointerlockerror', { bubbles: true }));
+        return Promise.reject(
+          refusal('NotAllowedError', 'A user gesture is required to request Pointer Lock.'),
+        );
+      }
+      return this.lock(canvas as unknown as Element)
+        ? Promise.resolve()
+        : Promise.reject(
+            refusal('NotAllowedError', '[driftengine] the window could not hold the pointer'),
+          );
+    };
+    canvas.fullscreener = () => this.fullscreen.request(canvas);
+    canvas.capture = this.capture;
+    canvas.focuser = (focus) => {
+      const now = this.document.activeElement;
+      if (focus === (now === canvas)) return;
+      this.document.activeElement = focus ? canvas : null;
+      if (this.document.focused) focusEvents(canvas, focus);
+    };
+  }
+
+  /**
+   * The platform's half of the lock: hide the cursor and hold it, or let it go. Answers false when it
+   * cannot — a window without focus, as a hidden one is — and the lock is then refused, the way a
+   * browser refuses one: the promise rejects and `pointerlockerror` fires, and nothing is locked.
+   */
+  setPointerLocker(locker: (lock: boolean) => boolean): void {
+    this.locker = locker;
+  }
+
+  /** The platform's half of fullscreen: put the window in it or take it out, false when it cannot. */
+  setFullscreener(setter: (on: boolean) => boolean): void {
+    this.fullscreen.setter = setter;
+  }
+
+  /** Told when the lock is taken or released. */
+  onPointerLock(listener: (locked: boolean) => void): void {
+    this.lockListeners.push(listener);
+  }
+
+  unlock(): void {
+    if (this.document.pointerLockElement === null) return;
+    this.locker?.(false);
+    this.document.pointerLockElement = null;
+    this.changedLock(false);
+  }
+
+  /** Put the globals a page has on `scope`, and hand back what takes them off again. */
+  install(scope: Record<string, unknown> = globalThis as Record<string, unknown>): () => void {
+    const names = [
+      'window',
+      'document',
+      'requestAnimationFrame',
+      'cancelAnimationFrame',
+      'devicePixelRatio',
+      'matchMedia',
+    ] as const;
+    const held = names.map((name) => [name, Object.getOwnPropertyDescriptor(scope, name)] as const);
+    scope['window'] = this.window;
+    scope['document'] = this.document;
+    scope['requestAnimationFrame'] = this.requestAnimationFrame;
+    scope['cancelAnimationFrame'] = this.cancelAnimationFrame;
+    scope['matchMedia'] = this.window.matchMedia;
+    Object.defineProperty(scope, 'devicePixelRatio', {
+      get: () => this.window.devicePixelRatio,
+      configurable: true,
+    });
+    const classes = installEventClasses(scope);
+    /* Node has a `navigator` of its own, behind a getter, so it is added to rather than replaced. */
+    const navigator = scope['navigator'] as object | undefined;
+    if (navigator !== undefined) {
+      Object.defineProperty(navigator, 'userActivation', {
+        value: this.userActivation,
+        configurable: true,
+      });
+    }
+    return () => {
+      classes();
+      if (navigator !== undefined)
+        delete (navigator as { userActivation?: unknown }).userActivation;
+      for (const [name, descriptor] of held) {
+        if (descriptor === undefined) delete scope[name];
+        else Object.defineProperty(scope, name, descriptor);
+      }
+    };
+  }
+
+  private lock(element: Element): boolean {
+    if (this.document.pointerLockElement === element) return true;
+    if (this.locker !== null && !this.locker(true)) {
+      this.document.dispatchEvent(new Event('pointerlockerror', { bubbles: true }));
+      return false;
+    }
+    this.document.pointerLockElement = element;
+    this.changedLock(true);
+    return true;
+  }
+
+  private changedLock(locked: boolean): void {
+    this.document.dispatchEvent(new Event('pointerlockchange', { bubbles: true }));
+    for (const listener of this.lockListeners) listener(locked);
+  }
+}
+
+/** `focus` and `focusin`, or `blur` and `focusout`: the first stays on the element, the second bubbles. */
+function focusEvents(canvas: NativeCanvas, focused: boolean): void {
+  canvas.dispatchEvent(new FocusEvent(focused ? 'focus' : 'blur'));
+  canvas.dispatchEvent(new FocusEvent(focused ? 'focusin' : 'focusout', { bubbles: true }));
+}
+
+/** A `DOMException`-shaped refusal: a browser's error name, with its message. */
+function refusal(name: string, message: string): Error {
+  return Object.assign(new Error(message), { name });
+}