f39ca7c · 56d64ff
@@ -110,13 +110,27 @@
flashbang, if you bought them,
<kbd>E</kbd> plants or defuses, <kbd>B</kbd> opens the buy menu in the freeze
time, <kbd>1</kbd>/<kbd>2</kbd>/<kbd>3</kbd> switch guns, <kbd>Tab</kbd> shows
the scoreboard, <kbd>F</kbd> puts the stage on the whole screen and
<kbd>Esc</kbd> pauses. On a touch screen the left of the view is a thumb stick,
<kbd>Esc</kbd> or <kbd>P</kbd> pauses. On a touch screen the left of the view is a thumb stick,
the right looks around, and the buttons along the bottom do the rest — including
the one in the top corner, which is full screen and is how you get one on a
phone, where there is no keyboard and no pointer to lock. A browser that will not
put an element full screen — an iPhone will not — never shows that button rather
than showing one that does nothing.
Escape is the one key the browser reads before the page does, and on a Mac what
it means is *give the window back*: full screen drops with the whole animation,
mid-round. So the game asks for the key rather than obeying it. Where a browser
has the Keyboard Lock API — Chrome and Edge — `src/engine/escape.ts` holds
Escape while the stage has the screen, so a pause is a pause and the screen
stays; that browser leaves full screen when Escape is *held* down, which is the
platform's own way out. Safari and Firefox have no such API and take the screen
whatever the page asks, so the pause panel says so and **Resume** puts it back —
a click is a gesture, which is the only thing a browser will hand a screen to.
<kbd>P</kbd> pauses the same way and is a key no browser has a meaning of its
own for, so it never costs the screen on any of them. The same thing happens at
`/range`, where Escape gives the mouse back: it keeps the screen where it can,
and **Capture the mouse** takes back what a browser took.
The radar sits in the top corner: the level from above, north up and never
turning, with the rooms in grey, the two bombsites lettered A and B, your side
in your side's colour and a white wedge for where you are and which way you are
@@ -232,7 +246,10 @@
renderer, no atlas, no mesh and no sound ship in that bundle, and
  with noise bursts and tones), `loop` (a fixed step with a clamp on a long
  frame), `controls` (a bindings table in, held actions out), `fullscreen` (the stage on
  the whole screen: whether this browser will, whether it is right now, the way
  in and out, and a refusal swallowed rather than thrown), `overlay` (the
  in and out, and a refusal swallowed rather than thrown), `escape` (the Escape
  key asked for rather than obeyed: the Keyboard Lock API held while the stage
  has the screen, released when it loses it, and the press handed to the game
  whether or not the lock was granted), `overlay` (the
  2D over the scene: a scale and a pad off the canvas width, scaled fonts,
  panels, aligned and faded text, a crosshair, a bar, right-aligned columns and
  a `m:ss` clock, drawn onto the seventeen members of a 2D context it uses and
@@ -299,7 +316,9 @@
renderer, no atlas, no mesh and no sound ship in that bundle, and
  `Ctor`; from `loop` `createLoop`, `Frames`, `Loop` and `LoopOptions`; from
  `controls` `createControls`, `attachButtons` and the event and option types
  they are driven with; from `fullscreen` `createFullscreen` with `Fullscreen`,
  `FullscreenHost`, `FullscreenTarget` and `FullscreenOwner`; from `overlay` `overlay`, `Overlay` and the `Paint`
  `FullscreenHost`, `FullscreenTarget` and `FullscreenOwner`; from `escape`
  `createEscape` and `ESCAPE` with `Escape`, `EscapeHost`, `KeyboardLock` and the
  `Screen` it reads full screen off; from `overlay` `overlay`, `Overlay` and the `Paint`
  a 2D game draws onto; from `scene` the frame and its pool — `createScene`,
  `resetScene`, `nextInstance`, `pushLine`, `Scene`, `SceneCapacity`, `Camera`
  and `Instance`; from `effects` the ring of what just happened —
@@ -29,6 +29,10 @@
test("the bindings are the ones the keyboard has always had", () => {
  // the browser for the screen, and nothing about an `Input` changes for it.
  expect(CS_KEYS.KeyF).toBe("fullscreen");
  expect(intent(["fullscreen"])).toEqual(intent([]));
  // P is the page's in the same way: it pauses, which is what Escape means too,
  // and no browser has a meaning of its own for it to take the window back with.
  expect(CS_KEYS.KeyP).toBe("pause");
  expect(intent(["pause"])).toEqual(intent([]));
});
test("nothing held is nothing asked for", () => {
@@ -15,9 +15,13 @@
export const CS_KEYS: Record<string, string> = {
  Space: "jump", ControlLeft: "duck", KeyC: "duck", ShiftLeft: "walk",
  KeyR: "reload", KeyE: "use", KeyG: "grenade", KeyT: "flash", KeyB: "buy", Tab: "scoreboard",
  Digit1: "slot1", Digit2: "slot2", Digit3: "slot3",
  // Not a thing the world knows about: `main.ts` hears it on `onAction` and
  // asks the browser for the screen, which `readIntent` below never sees.
  // Neither of these is a thing the world knows about: `main.ts` hears them on
  // `onAction`, and `readIntent` below never sees either. F asks the browser for
  // the screen; P pauses, which is what Escape means too — and P is a key no
  // browser has its own meaning for, so it pauses without also handing the
  // window back, which is what Escape does on a Mac.
  KeyF: "fullscreen",
  KeyP: "pause",
};
/** Left fires, right scopes. */
@@ -52,7 +52,9 @@
function painted(stage: FakeStage): FakeStage {
}
/** A booted page, its atlas painted, and the match already started on it. */
function playing(options: { webgl?: boolean; coarse?: boolean } = {}): FakeStage {
function playing(
  options: { webgl?: boolean; coarse?: boolean; fullscreen?: boolean; keyboardLock?: boolean } = {},
): FakeStage {
  const stage = painted(start(fakeStage(options)));
  stage.by("play").fire("click");
  return stage;
@@ -257,6 +259,101 @@
test("losing the pointer pauses a running match, and does not while the buy pane
  expect(stage.by("pause").hidden).toBe(true);
});
test("Escape pauses and keeps the screen where the browser hands the key over", async () => {
  const stage = playing();
  stage.press("KeyF");
  stage.lock(true);
  const box = stage.by("stage");
  expect(stage.document.fullscreenElement).toBe(box);
  // The key was asked for on the way into full screen, and granted a microtask
  // later: from here on Escape is the page's and not the browser's.
  expect(stage.keyboard.locked).toEqual(["Escape"]);
  await Promise.resolve();
  stage.window.fire("keydown", { code: "Escape" });
  // Paused, the pointer let go — under the lock the browser does not do that for
  // us — and the screen still ours, which is the whole point of holding the key.
  expect(stage.by("pause").hidden).toBe(false);
  expect(stage.document.pointerLockElement).toBe(null);
  expect(stage.document.fullscreenElement).toBe(box);
  expect(stage.by("esc").textContent).toContain("kept the screen");
  expect(stage.by("resume").focused).toBe(1);
  // And Resume goes back into the match without asking for a screen it already
  // has: one pointer lock, no second `requestFullscreen`.
  stage.by("resume").fire("click");
  expect(stage.by("pause").hidden).toBe(true);
  expect(box.fullscreens).toBe(1);
  expect(stage.scene.locks).toBe(2);
});
test("a browser that keeps Escape for itself pauses just the same, and Resume puts the screen back", () => {
  // Safari on a Mac: no Keyboard Lock API, so Escape leaves full screen whatever
  // the page asks — the window drops out of it with the whole animation, which is
  // what this test is about.
  const stage = playing({ keyboardLock: false });
  stage.press("KeyF");
  stage.lock(true);
  const box = stage.by("stage");
  expect(box.fullscreens).toBe(1);
  expect(stage.keyboard.grabs).toBe(0);
  // Escape, as that browser delivers it: the screen is gone before the page hears
  // the key, and the pointer goes with it.
  stage.document.fullscreenElement = null;
  stage.document.fire("fullscreenchange");
  stage.lock(false);
  stage.window.fire("keydown", { code: "Escape" });
  expect(stage.by("pause").hidden).toBe(false);
  expect(stage.by("esc").textContent).toContain("Resume puts it back");
  // Resume is a gesture, which is the only thing a browser will give a screen
  // back to: the stage goes full screen again and the pointer with it.
  stage.by("resume").fire("click");
  expect(stage.document.fullscreenElement).toBe(box);
  expect(box.fullscreens).toBe(2);
  expect(stage.scene.locks).toBe(2);
  // A player who left full screen on purpose is not dragged back into it.
  stage.press("KeyF");
  expect(stage.document.fullscreenElement).toBe(null);
  stage.lock(false);
  expect(stage.by("pause").hidden).toBe(false);
  stage.by("resume").fire("click");
  expect(stage.document.fullscreenElement).toBe(null);
  expect(box.fullscreens).toBe(2);
});
test("P pauses too, and a key no browser wants costs no screen", () => {
  const stage = playing({ keyboardLock: false });
  stage.press("KeyF");
  stage.lock(true);
  stage.press("KeyP");
  expect(stage.by("pause").hidden).toBe(false);
  expect(stage.document.fullscreenElement).toBe(stage.by("stage"));
  expect(stage.document.pointerLockElement).toBe(null);
  // Nothing was taken, and the line in the panel says as much rather than
  // promising to put a screen back that never went anywhere.
  expect(stage.by("esc").textContent).toContain("Esc or P pauses");
});
test("Escape closes the buy menu before it is a pause", () => {
  const stage = playing();
  stage.lock(true);
  stage.press("KeyB");
  expect(stage.by("buy").hidden).toBe(false);
  stage.window.fire("keydown", { code: "Escape" });
  expect(stage.by("buy").hidden).toBe(true);
  expect(stage.by("pause").hidden).toBe(true);
  // The next one is the pause, now that there is nothing in front of it.
  stage.window.fire("keydown", { code: "Escape" });
  expect(stage.by("pause").hidden).toBe(false);
  // A pause is not a second pause: the key held down does not stack panels or
  // steal the focus again.
  stage.window.fire("keydown", { code: "Escape", repeat: true });
  expect(stage.by("resume").focused).toBe(1);
});
test("leaving the match puts the menu back and stops the frame", () => {
  const stage = playing();
  stage.step(FRAME);
@@ -25,9 +25,10 @@
import { createAudio, type Audio } from "./audio.ts";
import { CS_KEYS, CS_MOUSE, CS_TAP, readIntent } from "./binding.ts";
import { drawHud, type Paint } from "./hud.ts";
import {
  attachButtons, clamp, createControls, createFullscreen, createLoop, createRenderer, effectAt,
  attachButtons, clamp, createControls, createEscape, createFullscreen, createLoop, createRenderer,
  effectAt,
  painter,
  type Button, type Camera, type Listens, type Mesh,
  type Button, type Camera, type KeyboardLock, type Listens, type Mesh,
} from "../engine/index.ts";
import { generateLevel, seedFrom } from "./generate.ts";
import { DE_FORGE } from "./map.ts";
@@ -131,6 +132,12 @@
export type BuildRenderer = (atlas: Uint8Array) => Draws;
export type Host = {
  document: PageDocument;
  window: PageWindow;
  /**
   * `navigator.keyboard`, when this browser has one: the Keyboard Lock API, and
   * the only way to be handed Escape instead of the browser's meaning for it.
   * Absent in Safari and Firefox, where the key keeps that meaning.
   */
  keyboard?: KeyboardLock;
  storage: Store;
  fetch(url: string, init: { method: string; headers: Record<string, string>; body: string }): Promise<Reply>;
  /** A fresh match id. `crypto.randomUUID` is one; `src/result.ts` checks it. */
@@ -175,6 +182,9 @@
export function boot(host: Host): Frame {
  const onMap = by("onmap");
  const prep = by("prep");
  const play = by<Panel & { disabled: boolean }>("play");
  const resumeButton = by("resume");
  // The line in the pause panel that says what Escape just did on this browser.
  const escHint = by("esc");
  const build = host.createRenderer(sceneCanvas);
  if (build === null) {
@@ -193,8 +203,9 @@
export function boot(host: Host): Frame {
  // the "fullscreen" action below like every other key this game reads. Both
  // arrive inside a gesture, which is the only time a browser says yes. A
  // browser that will not do it at all leaves the button hidden rather than
  // showing one that does nothing, and the state is the browser's — Escape
  // leaves and `onChange` is how this page hears about it.
  // showing one that does nothing, and the state is the browser's — a browser
  // that takes the screen back says so with `onChange`, which is how this page
  // hears about it and, below, how it knows there is something to put back.
  const full = createFullscreen({ element: stageBox, document: doc });
  const paintFull = (on: boolean): void => {
    const label = on ? "Leave full screen" : "Full screen";
@@ -205,7 +216,33 @@
export function boot(host: Host): Frame {
  };
  full.onChange = paintFull;
  fullButton.hidden = !full.supported;
  fullButton.addEventListener("click", () => full.toggle());
  /**
   * What the player asked for, which is not the same as what the browser is
   * giving us. On a Mac, Escape hands the screen back whether or not the page
   * wanted to keep it — the window drops out of full screen with the whole
   * animation, mid-round — and there is no way to refuse that from a keydown.
   * So the wish is remembered here, and `restoreFull` puts the screen back from
   * inside the Resume click, which is a gesture a browser will honour.
   */
  let wantsFull = false;
  const askFull = (): void => {
    wantsFull = !full.on;
    full.toggle();
  };
  const restoreFull = (): void => {
    if (wantsFull && !full.on) full.enter();
  };
  fullButton.addEventListener("click", askFull);
  /**
   * Escape, asked for rather than obeyed. Where a browser has the Keyboard Lock
   * API — Chrome and Edge — the key is ours while the stage has the screen, so a
   * pause is a pause and the screen stays; where it has not, the key still
   * arrives and the pause is the same, and what the browser also took Resume
   * gives back. `P` is the same press for a player who would rather not find out
   * which browser they are on.
   */
  const escape = createEscape({ window: win, document: doc, keyboard: host.keyboard }, full);
  const loop = createLoop({ tick: TICK }, {
    requestAnimationFrame: (callback) => win.requestAnimationFrame(callback),
@@ -293,10 +330,44 @@
export function boot(host: Host): Frame {
    }
  }
  /**
   * Stop the match and say what the key just cost. The panel is shown, the
   * pointer is let go — under the keyboard lock the browser does not do that for
   * us, which is the point of holding the key — and Resume takes the focus, so
   * the way back is one press of Enter wherever the pointer is.
   *
   * The sentence is the honest one for the browser this is: the key kept the
   * screen, or it took it and Resume will put it back, or full screen was never
   * asked for and the key cost nothing.
   */
  function pauseMatch(): void {
    if (!running) return;
    show(pause, true);
    // Already gone when a lost lock is what paused us; the call is a no-op then,
    // and the one thing that has to happen when the key was ours instead.
    doc.exitPointerLock();
    escHint.textContent =
      escape.held
        ? "Paused. The game kept the screen: Esc never leaves full screen here."
        : wantsFull && !full.on
          ? "Paused. This browser also left full screen on Esc — Resume puts it back."
          : "Paused. Esc or P pauses, and Resume goes back.";
    resumeButton.focus();
  }
  /** What Escape and P both mean: close the buy menu if it is open, else pause. */
  function pauseKey(): void {
    if (!buyPanel.hidden) return openBuy(false);
    if (pause.hidden) pauseMatch();
  }
  escape.onPress = pauseKey;
  controls.onAction = (action, down) => {
    if (!down) return;
    if (action === "buy") return openBuy(buyPanel.hidden);
    if (action === "fullscreen") return full.toggle();
    if (action === "pause") return pauseKey();
    if (action === "fullscreen") return askFull();
    // Dead, the trigger is the only thing left to press: it walks the camera
    // along your side, and the aim button walks it back. The touch pad's fire
    // is the same action, so a phone gets it without a button of its own.
@@ -304,8 +375,11 @@
export function boot(host: Host): Frame {
    if (action === "fire") cycle(world, spectator, 1);
    else if (action === "scope") cycle(world, spectator, -1);
  };
  // The pointer went away and we are still in a match: however it went — Escape
  // on a browser that keeps the key, a window losing focus, a browser policy —
  // the match stops rather than playing on without a mouse.
  controls.onUnlock = () => {
    if (running && buyPanel.hidden) show(pause, true);
    if (running && buyPanel.hidden) pauseMatch();
  };
  // --- results, sent as the match goes rather than only at the end
@@ -371,8 +445,11 @@
export function boot(host: Host): Frame {
  }
  play.addEventListener("click", start);
  by("resume").addEventListener("click", () => {
  // Resume is the gesture that puts back whatever the pause cost: the screen
  // first, if a browser took it, and then the pointer.
  resumeButton.addEventListener("click", () => {
    show(pause, false);
    restoreFull();
    void sceneCanvas.requestPointerLock();
  });
  by("quit").addEventListener("click", () => {
@@ -382,9 +459,6 @@
export function boot(host: Host): Frame {
    show(menu, true);
    show(touchPanel, false);
  });
  win.addEventListener("keydown", (event: { code: string }) => {
    if (event.code === "Escape" && !buyPanel.hidden) openBuy(false);
  });
  const saved = host.storage.getItem("cs.name");
  if (saved !== null && nameField.value === "") nameField.value = saved;
@@ -510,6 +584,10 @@
export function gameMeshes(level: Level = DE_FORGE): Record<string, Mesh> {
const browser = (): Host => ({
  document,
  window,
  // The Keyboard Lock API, if this browser has one. It is read off `navigator`
  // rather than asked for: a browser without it has no such member, which is
  // exactly what `createEscape` takes as its answer.
  keyboard: (navigator as { keyboard?: KeyboardLock }).keyboard,
  storage: localStorage,
  fetch: (url, init) => fetch(url, init),
  randomUUID: () => crypto.randomUUID(),
@@ -28,7 +28,7 @@
 * and it no longer needs to: what the two shared is behind the door now.
 */
import { fakePage, type FakeCanvas, type FakeDocument, type FakeElement, type FakePaint, type FakeWindow } from "../engine/index.ts";
import { fakePage, type FakeCanvas, type FakeDocument, type FakeElement, type FakeKeyboard, type FakePaint, type FakeWindow } from "../engine/index.ts";
import type { Audio } from "./audio.ts";
import type { Mesh } from "../engine/index.ts";
import type { BuildRenderer, Draws, Host, Stage } from "./main.ts";
@@ -105,6 +105,8 @@
export type FakeStage = {
  host: Host;
  document: FakeDocument;
  window: FakeWindow;
  /** `navigator.keyboard`: who holds Escape, and how often the game asked. */
  keyboard: FakeKeyboard;
  scene: StageCanvas;
  hud: StageCanvas;
  by(id: string): FakeElement;
@@ -153,7 +155,7 @@
export type FakeStage = {
 * contract between the page and this file, so `src/server.test.ts` checks the
 * served page against this same list rather than a second copy of it.
 */
export const PAGE_IDS = ["stage", "scene", "hud", "menu", "pause", "buy", "touch", "stats", "name", "length", "side", "sens", "map", "onmap", "play", "prep", "resume", "quit", "fps", "full"];
export const PAGE_IDS = ["stage", "scene", "hud", "menu", "pause", "buy", "touch", "stats", "name", "length", "side", "sens", "map", "onmap", "play", "prep", "resume", "quit", "esc", "fps", "full"];
/** The ones the server renders with `hidden` on them: the page starts at the menu. */
const HIDDEN = ["pause", "buy", "touch", "full"];
@@ -172,11 +174,13 @@
const GLOBALS = ["document", "window", "localStorage", "fetch"];
/**
 * The whole page the shooter's entry expects, plus the host around it. Pass
 * `webgl: false` for a browser that cannot give the renderer a context,
 * `coarse: true` for a phone, and `fullscreen: false` for a browser that will
 * not put an element on the whole screen.
 * `coarse: true` for a phone, `fullscreen: false` for a browser that will not
 * put an element on the whole screen, and `keyboardLock: false` for one that
 * will not hand the page the Escape key — which is Safari, and the browser this
 * game's pause has to be honest on.
 */
export function fakeStage(
  options: { webgl?: boolean; coarse?: boolean; fullscreen?: boolean } = {},
  options: { webgl?: boolean; coarse?: boolean; fullscreen?: boolean; keyboardLock?: boolean } = {},
): FakeStage {
  const page = fakePage({
    ids: PAGE_IDS,
@@ -185,6 +189,7 @@
export function fakeStage(
    actions: PAGE_ACTIONS,
    coarse: options.coarse,
    fullscreen: options.fullscreen,
    keyboardLock: options.keyboardLock,
  });
  // Asked for with `paint` left on, so both canvases have their 2D recorder.
  const [scene, hud] = page.canvases as [StageCanvas, StageCanvas];
@@ -222,6 +227,7 @@
export function fakeStage(
    host: {
      document: page.document,
      window: page.window,
      keyboard: page.keyboard,
      storage: {
        getItem: (key) => store.get(key) ?? null,
        setItem: (key, value) => void store.set(key, value),
@@ -249,6 +255,7 @@
export function fakeStage(
    },
    document: page.document,
    window: page.window,
    keyboard: page.keyboard,
    scene,
    hud,
    buttons: page.buttons,
@@ -357,6 +357,35 @@
inside a click or a keydown, which is the only time a browser says yes. The
`:fullscreen` half is CSS: the element keeps whatever aspect ratio and maximum
height it had unless a rule says otherwise.
### escape
Escape is the one key the browser reads before your page does, and on a Mac what
it means is "give the window back": the screen drops out of full screen, which a
player in the middle of a round reads as their window being thrown away. There is
exactly one way to ask for the key rather than its meaning — the Keyboard Lock
API — and this is the three lines of it.
`createEscape` takes an `EscapeHost` — the window the keydown arrives on, the
document that announces full screen, and an optional `KeyboardLock`, which is
`navigator.keyboard` and is absent in Safari and Firefox — plus a `Screen`, which
is anything with a live `Screen.on`, so a `Fullscreen` is one. It hands back an
`Escape`: `Escape.supported`, false on a browser with no such API, so a page can
say what the key will do rather than guess; `Escape.held`, whether the key is
ours right now, which is the grant *and* still being full screen, read live
rather than remembered; the `Escape.onPress` callback, one call per press and
never for a repeat; and `Escape.detach`, which gives the key back. `ESCAPE` is
the code it is about, and the only one it ever asks for.
The lock follows the screen, because a browser only grants it in full screen and
drops it when full screen goes: it is asked for on the way in and released on the
way out, and a refusal — a rejected promise, or a browser that throws instead —
leaves `Escape.held` false and is not an error a game can act on. Under the lock
the browser stops acting on the key and leaves full screen only when it is *held*
down, so `Escape.onPress` is the whole of what the key means and your game decides
that: close a panel, pause the match, let the pointer go. What this does not do is
put anything back — a browser that took the screen took it inside its own gesture,
and only another gesture can ask again, which is your Resume button.
### overlay
The 2D a game draws over its scene. `overlay` takes the surface, the width and
@@ -499,8 +528,11 @@
What you bring is `PageOptions`, which is your game and not the engine's:
`PageOptions.canvases` says which of those are canvases (the first one is the
surface), `PageOptions.hidden` is the ones the server renders already hidden,
and `PageOptions.actions` is one `[data-action]` element per name.
`paint: false` is a browser whose canvas gives no 2D context, and `coarse: true`
is a phone. Then `FakePage.step(ms)` runs the oldest frame that was asked for,
`paint: false` is a browser whose canvas gives no 2D context, `coarse: true`
is a phone, `fullscreen: false` is a browser that will not put an element on the
whole screen, and `keyboardLock: false` is one with no Keyboard Lock API — which
takes both methods off `FakePage.keyboard`, the `FakeKeyboard` that records what
is locked, how often it was asked and whether it is refusing. Then `FakePage.step(ms)` runs the oldest frame that was asked for,
that many milliseconds after the last one — that is the whole clock, and there
is no timer anywhere in the file.
@@ -287,6 +287,10 @@
test("the example imports the door and nothing else, which is what it is for", (
 *   fullscreen — `Fullscreen`, `FullscreenHost`, `FullscreenOwner`,
 *   `FullscreenTarget`, `createFullscreen`.
 *
 *   escape — `ESCAPE`, `Escape`, `EscapeHost`, `KeyboardLock`, `Screen`,
 *   `createEscape`; and `FakeKeyboard`, which is the browser's half of it on the
 *   headless page.
 *
 *   effects — `Effects`, `createEffects`, `pushEffect`, `expireEffects`,
 *   `effectAt`, `resetEffects`.
 *
@@ -295,20 +299,21 @@
test("the example imports the door and nothing else, which is what it is for", (
 */
export const SURFACE = [
  "Activations", "Adam", "Body", "Box", "Builder", "Burst", "Button", "ButtonOptions",
  "CHECKPOINT_CHARS", "Camera", "Complaint", "Controls", "Ctor", "DEFAULT_HYPER", "Effects",
  "CHECKPOINT_CHARS", "Camera", "Complaint", "Controls", "Ctor", "DEFAULT_HYPER", "ESCAPE",
  "Effects", "Escape", "EscapeHost",
  "FakeCanvas",
  "FakeDocument", "FakeElement", "FakePage", "FakePaint", "FakeTarget", "FakeWindow", "Fold",
  "FakeDocument", "FakeElement", "FakeKeyboard", "FakePage", "FakePaint", "FakeTarget", "FakeWindow", "Fold",
  "Folded", "Frames", "Fullscreen", "FullscreenHost", "FullscreenOwner", "FullscreenTarget",
  "Grads", "Grid", "Hit", "Host", "Hull", "Hyper", "Instance", "KeyEventish",
  "Grads", "Grid", "Hit", "Host", "Hull", "Hyper", "Instance", "KeyEventish", "KeyboardLock",
  "Listens", "LockOwner", "Loop", "LoopOptions", "Mat4", "Mesh", "MouseEventish", "MoveTuning", "Options",
  "Overlay", "Packed", "PageOptions", "Paint", "Painter", "Pin", "Policy", "QUANTUM",
  "Renderer", "RendererAssets", "Rollout", "Scene", "SceneCapacity", "Shader", "Shape",
  "Renderer", "RendererAssets", "Rollout", "Scene", "SceneCapacity", "Screen", "Shader", "Shape",
  "SoundDevice", "Stick", "Surface", "Tone", "TouchEventish", "Touchish", "UpdateStats", "Vec3",
  "Wish", "accelerate", "add", "addBox", "airAccelerate", "angleDelta", "angleVectors",
  "applyGrads", "attachButtons", "attenuate",
  "backward", "builder", "cellAt", "clamp", "clearGrads", "colOf", "compare",
  "computeAdvantages", "copyPolicy", "createAdam", "createControls", "createEffects",
  "createFullscreen",
  "createEscape", "createFullscreen",
  "createLoop", "createPolicy", "createRenderer", "createRollout", "createScene",
  "createSoundDevice",
  "cross", "deg", "dist", "dist2d", "dot", "effectAt", "expireEffects", "eyeHeight", "fakePage",
@@ -0,0 +1,161 @@
/**
 * Escape, driven against the headless page next door: the key heard, the lock
 * asked for when the stage takes the screen and given back when it loses it, a
 * browser with no Keyboard Lock API, a browser that refuses, and the stale grant
 * that must not outlive the screen it was granted for. Nothing in here is a
 * browser — `fakePage`'s `keyboard` is the one that hands the key over, and its
 * document fires `fullscreenchange` the way a real one does.
 */
import { expect, test } from "bun:test";
import { createEscape, ESCAPE, type EscapeHost } from "./escape.ts";
import { createFullscreen } from "./fullscreen.ts";
import { fakePage } from "./page.ts";
/** A page with a stage on it, full screen around the stage, and Escape over both. */
function stage(options: { keyboardLock?: boolean } = {}) {
  const page = fakePage({ ids: ["stage"], keyboardLock: options.keyboardLock });
  const full = createFullscreen({ element: page.by("stage"), document: page.document });
  const presses: number[] = [];
  const escape = createEscape(
    { window: page.window, document: page.document, keyboard: page.keyboard },
    full,
  );
  escape.onPress = () => void presses.push(presses.length + 1);
  return { page, full, escape, presses };
}
test("the key is heard once per press, and its browser meaning is refused", () => {
  const { page, presses } = stage();
  let prevented = 0;
  page.window.fire("keydown", { code: ESCAPE, preventDefault: () => void (prevented += 1) });
  expect(presses.length).toBe(1);
  expect(prevented).toBe(1);
  // A key held down repeats. One press is one pause, not sixty.
  page.window.fire("keydown", { code: ESCAPE, repeat: true });
  expect(presses.length).toBe(1);
  // And nothing else on the keyboard is this module's business.
  page.window.fire("keydown", { code: "KeyW" });
  page.window.fire("keyup", { code: ESCAPE });
  expect(presses.length).toBe(1);
});
test("the lock follows the screen: asked for on the way in, given back on the way out", async () => {
  const { page, full, escape } = stage();
  expect(escape.supported).toBe(true);
  // Nothing is asked for by a page that is not full screen.
  expect(page.keyboard.grabs).toBe(0);
  expect(escape.held).toBe(false);
  full.enter();
  expect(page.keyboard.grabs).toBe(1);
  expect(page.keyboard.locked).toEqual([ESCAPE]);
  // The grant is a promise: it is ours on the microtask it resolves, not before.
  expect(escape.held).toBe(false);
  await Promise.resolve();
  expect(escape.held).toBe(true);
  full.exit();
  expect(page.keyboard.locked).toBe(null);
  expect(escape.held).toBe(false);
});
test("held is read from the screen, never remembered", async () => {
  const { page, full, escape } = stage();
  full.enter();
  await Promise.resolve();
  expect(escape.held).toBe(true);
  // Escape held down, which a browser answers by taking the screen back. The
  // event is all we get, and the key is the browser's again the moment it fires.
  page.document.fullscreenElement = null;
  page.document.fire("fullscreenchange");
  expect(escape.held).toBe(false);
  expect(page.keyboard.locked).toBe(null);
});
test("a grant that arrives after the screen is gone does not claim the key", async () => {
  const { page, full, escape } = stage();
  full.enter();
  // Out again before the lock's promise has had a chance to settle: the grant
  // belongs to a lock the browser has already dropped.
  full.exit();
  await Promise.resolve();
  await Promise.resolve();
  expect(escape.held).toBe(false);
  expect(page.keyboard.locked).toBe(null);
});
test("a browser with no Keyboard Lock API says so, and is not asked", () => {
  const { page, full, escape, presses } = stage({ keyboardLock: false });
  expect(escape.supported).toBe(false);
  full.enter();
  expect(page.keyboard.grabs).toBe(0);
  expect(escape.held).toBe(false);
  // The key still arrives; this is the browser where it also leaves full screen.
  page.window.fire("keydown", { code: ESCAPE });
  expect(presses.length).toBe(1);
});
test("a refusal is not a crash, whichever way the browser refuses", async () => {
  const { page, full, escape } = stage();
  page.keyboard.refuse = true;
  expect(() => full.enter()).not.toThrow();
  await Promise.resolve();
  await Promise.resolve();
  expect(escape.held).toBe(false);
  // And a browser that throws where it should have rejected.
  const thrower: EscapeHost = {
    window: page.window,
    document: page.document,
    keyboard: {
      lock: () => {
        throw new Error("not allowed");
      },
      unlock: () => {
        throw new Error("not allowed either");
      },
    },
  };
  const rude = createEscape(thrower, { on: true });
  expect(rude.held).toBe(false);
  expect(() => rude.detach()).not.toThrow();
});
test("a page booted already full screen holds the key from the start", async () => {
  const page = fakePage({ ids: ["stage"] });
  page.document.fullscreenElement = page.by("stage");
  const escape = createEscape(
    { window: page.window, document: page.document, keyboard: page.keyboard },
    { on: true },
  );
  await Promise.resolve();
  expect(escape.held).toBe(true);
  expect(page.keyboard.grabs).toBe(1);
});
test("detach leaves the page as it found it, key included", async () => {
  const { page, full, escape, presses } = stage();
  full.enter();
  await Promise.resolve();
  expect(page.window.listening.has("keydown")).toBe(true);
  expect(page.document.listening.has("fullscreenchange")).toBe(true);
  escape.detach();
  expect(page.keyboard.locked).toBe(null);
  expect(escape.held).toBe(false);
  expect(page.window.listening.has("keydown")).toBe(false);
  page.window.fire("keydown", { code: ESCAPE });
  expect(presses.length).toBe(0);
  // The full screen module is still the one listening for its own event.
  expect(page.document.listening.has("fullscreenchange")).toBe(true);
});
test("a browser with no keyboard at all is a browser, not an exception", () => {
  const page = fakePage({ ids: ["stage"] });
  const escape = createEscape({ window: page.window, document: page.document }, { on: true });
  expect(escape.supported).toBe(false);
  expect(escape.held).toBe(false);
  expect(() => page.window.fire("keydown", { code: ESCAPE })).not.toThrow();
});
@@ -0,0 +1,149 @@
/**
 * Escape: the one key a browser reads before the page does. Every game here
 * wants it to mean "pause", and on a Mac it means "give the window back" — the
 * screen drops out of full screen with the whole macOS animation, which is what
 * a player sees as their window being thrown away mid-round.
 *
 * There is exactly one way to ask for the key rather than the meaning, and this
 * module is the three lines of it: the Keyboard Lock API. `keyboard.lock(["Escape"])`
 * says "deliver that key to the page while it is full screen"; the browser then
 * only leaves full screen when Escape is *held*, which is the behaviour the
 * platform intends and the one a game wants. It is Chrome's and Edge's; Safari
 * and Firefox do not have it, so `supported` says so and a game that asks gets
 * the honest answer rather than a promise nobody kept.
 *
 * Three things this file takes seriously, all three of them a real browser:
 *
 *   - The API may be missing entirely — `navigator.keyboard` is undefined in
 *     Safari — so the whole host member is optional and a missing one is not an
 *     error, it is a browser where Escape keeps its own meaning.
 *   - The lock is only granted in full screen and is dropped when full screen
 *     goes. So it is asked for when the stage takes the screen and released when
 *     it gives it back, and `held` is read live — granted *and* still there —
 *     rather than remembered, the way `fullscreen.ts` reads `on`.
 *   - The key still arrives as a keydown whether the lock was granted or not.
 *     `onPress` is that event, once per press and never for a repeat, and it is
 *     the game's whole interface to the key: what Escape means — close the buy
 *     menu, pause the match, show the note — is the game's business, and this
 *     file has no opinion about it.
 *
 * What it does not do is put anything back. A browser that took the screen took
 * it inside its own gesture, and only another gesture can ask again: that is the
 * game's Resume button, and the game is the one that knows whether the player
 * wanted full screen in the first place.
 */
import type { Listens } from "./controls.ts";
/** The code of the key this module is about, and the only one it ever asks for. */
export const ESCAPE = "Escape";
/**
 * `navigator.keyboard`, as far as this file is concerned. Both methods are
 * optional because a browser has either both or neither, and `lock` hands back a
 * promise that rejects when the browser will not.
 */
export type KeyboardLock = {
  lock?(codes: readonly string[]): unknown;
  unlock?(): unknown;
};
/**
 * Where the key is heard, where full screen is announced, and the keyboard to
 * ask — `window`, `document` and `navigator.keyboard` in a browser, three plain
 * objects in a test.
 */
export type EscapeHost = {
  window: Listens;
  document: Listens;
  /** Absent on a browser with no Keyboard Lock API, which is most of them. */
  keyboard?: KeyboardLock;
};
/** Whether the stage is on the whole screen right now. A `Fullscreen` is one. */
export type Screen = { readonly on: boolean };
export type Escape = {
  /** Whether this browser can hand the key over at all. False is not a failure. */
  readonly supported: boolean;
  /** Whether it is ours right now: granted, and still full screen. Live. */
  readonly held: boolean;
  /** Escape went down. Once per press; a held key does not repeat into this. */
  onPress: () => void;
  detach(): void;
};
export function createEscape(host: EscapeHost, screen: Screen): Escape {
  const keyboard = host.keyboard;
  const supported = typeof keyboard?.lock === "function" && typeof keyboard?.unlock === "function";
  // Whether the last request was granted. `held` is this *and* the screen: the
  // browser drops the lock when full screen goes, so remembering only the
  // promise would be a claim that outlived the thing it was true about.
  let granted = false;
  // Which request is the current one. A promise that resolves after the screen
  // was handed back belongs to a lock that is already gone and may not claim the
  // key; without this, a fast Escape leaves `held` true forever.
  let asked = 0;
  const ask = (): void => {
    if (!supported) return;
    const mine = ++asked;
    if (!screen.on) {
      granted = false;
      try {
        keyboard?.unlock?.();
      } catch {
        // A browser that throws where it should not. The key is the browser's
        // again either way, which is exactly what we just asked for.
      }
      return;
    }
    try {
      // A promise nobody awaits still rejects loudly, and a refusal here is not
      // news: it is a browser saying the key stays its own.
      const asking = keyboard?.lock?.([ESCAPE]);
      // Only the current request may claim the key: a stale one says nothing at
      // all, rather than answering for the lock that replaced it.
      if (asking instanceof Promise) asking.then(() => void (mine === asked && (granted = true)), () => {});
      else granted = true;
    } catch {
      granted = false;
    }
  };
  const key = (event: { code: string; repeat?: boolean; preventDefault(): void }): void => {
    if (event.code !== ESCAPE || event.repeat === true) return;
    // The browser's own meaning for the key, refused where refusing is allowed:
    // under the lock this is the whole point, and without it it costs nothing.
    event.preventDefault();
    escape.onPress();
  };
  const escape: Escape = {
    supported,
    get held() {
      return granted && screen.on;
    },
    onPress: () => {},
    detach() {
      host.window.removeEventListener("keydown", key);
      host.document.removeEventListener("fullscreenchange", ask);
      asked += 1;
      granted = false;
      if (supported) {
        try {
          keyboard?.unlock?.();
        } catch {
          // Leaving the page as we found it is best effort by definition.
        }
      }
    },
  };
  host.window.addEventListener("keydown", key);
  host.document.addEventListener("fullscreenchange", ask);
  // A page that is already full screen when this is wired — a game booted into
  // one — is a page that should already hold the key.
  ask();
  return escape;
}
@@ -62,6 +62,13 @@
export type {
export { createFullscreen } from "./fullscreen.ts";
export type { Fullscreen, FullscreenHost, FullscreenOwner, FullscreenTarget } from "./fullscreen.ts";
/**
 * Escape, asked for rather than obeyed: the Keyboard Lock API around the one key
 * a browser reads before the page does, so full screen survives a pause.
 */
export { createEscape, ESCAPE } from "./escape.ts";
export type { Escape, EscapeHost, KeyboardLock, Screen } from "./escape.ts";
/** The 2D over the scene: panels, scaled text, a crosshair, a bar and a clock. */
export { overlay } from "./overlay.ts";
export type { Overlay, Paint } from "./overlay.ts";
@@ -97,7 +104,8 @@
export type { Renderer, RendererAssets } from "./renderer.ts";
 */
export { fakePage } from "./page.ts";
export type {
  FakeCanvas, FakeDocument, FakeElement, FakePage, FakePaint, FakeTarget, FakeWindow, PageOptions,
  FakeCanvas, FakeDocument, FakeElement, FakeKeyboard, FakePage, FakePaint, FakeTarget, FakeWindow,
  PageOptions,
} from "./page.ts";
/**
@@ -15,9 +15,10 @@
 * hidden, written, focused, set as an attribute and put full screen; a canvas's
 * 2D context writes down every call it was asked for, in order, with its
 * arguments; a target remembers what is listening on it and delivers an event
 * to exactly those handlers. The two pieces of state a browser owns rather than
 * a page — the pointer lock and the full screen element — live on the document
 * here too, and asking for either fires the event a page hears it from. It is honest
 * to exactly those handlers. The pieces of state a browser owns rather than a
 * page live here too — the pointer lock and the full screen element on the
 * document, and who holds Escape on `keyboard` beside it — and asking for any of
 * them fires the event a page hears it from. It is honest
 * about being a double: it has no timer, it touches no global, it throws for
 * nothing, and it knows what neither a renderer nor an `AudioContext` is —
 * `canvas.gl` is a slot a game fills with its own recorder, because what a
@@ -29,6 +30,7 @@
 * are each the game's half, built on this one.
 */
import type { KeyboardLock } from "./escape.ts";
import type { Paint } from "./overlay.ts";
/**
@@ -270,6 +272,21 @@
export type FakeDocument = FakeTarget & {
  exitFullscreen?(): Promise<void>;
};
/**
 * `navigator.keyboard`: the third thing on this page the browser owns rather
 * than the document. It records what is locked and how many times something
 * asked, and `refuse` is a browser saying no — which a real one does when the
 * page is not full screen.
 */
export type FakeKeyboard = KeyboardLock & {
  /** The codes held by the page right now, or null when the browser has them. */
  locked: readonly string[] | null;
  /** How many times something asked for a lock, granted or refused. */
  grabs: number;
  /** Refuse every lock from here on, the way a browser out of full screen does. */
  refuse: boolean;
};
/** What a game brings: its own ids, its own buttons, and the browser it is on. */
export type PageOptions = {
  /** Every id `getElementById` answers for. Anything else answers null. */
@@ -291,6 +308,12 @@
export type PageOptions = {
   * the document, which is what an iPhone looks like from the inside.
   */
  fullscreen?: boolean;
  /**
   * Whether this browser has the Keyboard Lock API. Default true: asking holds
   * the codes and the promise resolves. False takes both methods off
   * `keyboard`, which is what Safari and Firefox look like from the inside.
   */
  keyboardLock?: boolean;
};
export type FakePage = {
@@ -302,6 +325,8 @@
export type FakePage = {
  surface: FakeCanvas;
  window: FakeWindow;
  document: FakeDocument;
  /** `navigator.keyboard`: who holds Escape, and how often it was asked for. */
  keyboard: FakeKeyboard;
  /** The canvases, in the order `canvases` named them. */
  canvases: FakeCanvas[];
  /** The `[data-action]` elements, in the order `actions` named them. */
@@ -374,6 +399,29 @@
export function fakePage(options: PageOptions = {}): FakePage {
    }
  }
  // The browser's half of the Keyboard Lock API. A real one only grants it in
  // full screen and drops it when full screen goes; this one grants whatever it
  // is asked for until a test sets `refuse`, because which of those a game does
  // about is `escape.ts`'s business and not this file's.
  const keyboard: FakeKeyboard = {
    locked: null,
    grabs: 0,
    refuse: false,
    lock(codes): Promise<void> {
      keyboard.grabs += 1;
      if (keyboard.refuse) return Promise.reject(new Error("the page is not full screen"));
      keyboard.locked = [...codes];
      return Promise.resolve();
    },
    unlock(): void {
      keyboard.locked = null;
    },
  };
  if (options.keyboardLock === false) {
    delete keyboard.lock;
    delete keyboard.unlock;
  }
  const window: FakeWindow = {
    ...target(),
    devicePixelRatio: 1,
@@ -387,6 +435,7 @@
export function fakePage(options: PageOptions = {}): FakePage {
    surface: canvases[0] ?? canvasElement("", paint),
    window,
    document,
    keyboard,
    canvases,
    buttons,
    frames,
@@ -94,14 +94,25 @@
const menu = (visitor: Who): string => `
        mouse to aim and fire · <kbd>R</kbd> reload · <kbd>G</kbd> throw an HE · <kbd>T</kbd> throw a flashbang ·
        <kbd>E</kbd> plant or defuse · <kbd>B</kbd> buy ·
        <kbd>1</kbd><kbd>2</kbd><kbd>3</kbd> guns · <kbd>Tab</kbd> scores · <kbd>F</kbd> full screen ·
        <kbd>Esc</kbd> pause</p>
        <kbd>Esc</kbd> or <kbd>P</kbd> pause</p>
      <p class="hint">Full screen keeps the screen through a pause where a browser lets it:
        Chrome and Edge hand the game the <kbd>Esc</kbd> key, and hold it down to leave. Safari and
        Firefox leave full screen on <kbd>Esc</kbd> whatever the page asks, so Resume puts it back —
        or pause with <kbd>P</kbd>, which no browser has a meaning of its own for.</p>
      <p class="hint">Dead, you watch a teammate until the round ends: fire for the next player,
        aim for the one before.</p>
    `;
/**
 * The pause panel. Its line about Escape is rendered with the sentence that is
 * true before any key has been pressed, and `src/client/main.ts` replaces it on
 * every pause with the one that is true for the browser it turned out to be:
 * whether Escape kept the screen, or took it and Resume will put it back.
 */
const PAUSE = `
      <h2>Paused</h2>
      <div class="row"><button type="button" class="primary" id="resume">Resume</button><button type="button" id="quit">Leave match</button></div>
      <p class="hint" id="esc"><kbd>Esc</kbd> or <kbd>P</kbd> pauses, and Resume goes back.</p>
    `;
export function gamePage(db: Database, { who: visitor, ...options }: PageOptions): string {
@@ -33,7 +33,9 @@
const NOTE = `
      <p class="hint"><kbd>WASD</kbd> move · <kbd>Space</kbd> jump · <kbd>Ctrl</kbd> crouch ·
        <kbd>Shift</kbd> walk · <kbd>F</kbd> or the mouse fires · <kbd>R</kbd> reload ·
        <kbd>Enter</kbd> start · <kbd>T</kbd> the other drill · <kbd>G</kbd> full screen, which is
        G here because F is the trigger · <kbd>Esc</kbd> gives the mouse back. On a touch screen the left of the view is a stick, the right looks around, and the
        G here because F is the trigger · <kbd>Esc</kbd> gives the mouse back, and keeps the screen
        where a browser lets the page hold the key — Chrome and Edge do, and Safari and Firefox
        leave full screen with it, so Capture the mouse puts that back too. On a touch screen the left of the view is a stick, the right looks around, and the
        buttons do the rest.</p>
      <p class="hint">It makes its own noise, through the engine's sound device and the range's own
        recipes: a short dry crack, a clean tone for a hit, a knock as a plate stands up — quieter
@@ -59,6 +59,47 @@
test("G and the button put the lane on the whole screen, and a browser that will
  }
});
test("Escape gives the mouse back, and the screen a browser took comes back with Capture", () => {
  // Bun has no Keyboard Lock API, so this is the browser where Escape keeps its
  // own meaning — Safari on a Mac — and the way back is the one this page owns.
  const { p, undo } = booted();
  try {
    const stage = p.by("stage");
    p.window.fire("keydown", { code: "KeyG" });
    p.window.fire("keyup", { code: "KeyG" });
    p.by("look").fire("click");
    p.document.pointerLockElement = p.scene;
    p.document.fire("pointerlockchange");
    expect(p.document.fullscreenElement).toBe(stage);
    expect(p.by("note").hidden).toBe(true);
    // Escape: the page lets the pointer go itself, because under a lock the
    // browser would not have, and the note comes back with it.
    p.window.fire("keydown", { code: "Escape" });
    expect(p.document.pointerLockElement).toBe(null);
    p.document.fire("pointerlockchange");
    expect(p.by("note").hidden).toBe(false);
    // And that browser also took the screen. Capture is a gesture, so it is what
    // asks for it again — the lane comes back whole, not half.
    p.document.fullscreenElement = null;
    p.document.fire("fullscreenchange");
    p.by("look").fire("click");
    expect(p.document.fullscreenElement).toBe(stage);
    expect(stage.fullscreens).toBe(2);
    // A person who left full screen on purpose is not dragged back into it.
    p.window.fire("keydown", { code: "KeyG" });
    p.window.fire("keyup", { code: "KeyG" });
    expect(p.document.fullscreenElement).toBe(null);
    p.by("look").fire("click");
    expect(p.document.fullscreenElement).toBe(null);
    expect(stage.fullscreens).toBe(2);
  } finally {
    undo();
  }
});
test("a browser with no full screen keeps the button hidden rather than shipping a dead one", () => {
  const { p, undo } = booted({ fullscreen: false });
  try {
@@ -49,8 +49,8 @@
import {
  type DrillName, type Target,
} from "./targets.ts";
import {
  angleVectors, attachButtons, clamp, createControls, createFullscreen, createLoop, createRenderer,
  move,
  angleVectors, attachButtons, clamp, createControls, createEscape, createFullscreen, createLoop,
  createRenderer, move, type KeyboardLock,
} from "../engine/index.ts";
/** The range's own step: 50 Hz, deliberately not the shooter's 64. */
@@ -168,6 +168,10 @@
export function boot(): void {
  // either way the note gets out of the way and the touch look still works.
  $("look").addEventListener("click", () => {
    note.hidden = true;
    // The click is a gesture, so it is also the way back into a screen a browser
    // took: on a Mac, Escape hands the window back whether the page wanted it or
    // not, and `wantsFull` below is how this page remembers that it did.
    restoreFull();
    try {
      const asked: unknown = scene.requestPointerLock?.();
      if (asked instanceof Promise) asked.catch(() => {});
@@ -192,9 +196,36 @@
export function boot(): void {
    fullButton.textContent = on ? "\u2921" : "\u26F6";
  };
  fullButton.hidden = !full.supported;
  fullButton.addEventListener("click", () => full.toggle());
  /**
   * What a person asked for, which is not the same as what the browser is giving
   * us: Escape takes the screen back on a Mac and no code here gets a say. The
   * wish is remembered so the Capture button above — a click, and therefore a
   * gesture a browser will honour — can put it back.
   */
  let wantsFull = false;
  const askFull = (): void => {
    wantsFull = !full.on;
    full.toggle();
  };
  const restoreFull = (): void => {
    if (wantsFull && !full.on) full.enter();
  };
  fullButton.addEventListener("click", askFull);
  controls.onAction = (action, down) => {
    if (down && action === "fullscreen") full.toggle();
    if (down && action === "fullscreen") askFull();
  };
  // Escape, asked for rather than obeyed. Where a browser has the Keyboard Lock
  // API the key is this page's while the lane has the screen, so it gives the
  // mouse back — which is what it always meant here — and the screen stays.
  // Where it has not, the key still arrives, the mouse still comes back, and the
  // Capture button is what takes the screen again.
  const escape = createEscape(
    { window, document, keyboard: (navigator as { keyboard?: KeyboardLock }).keyboard },
    full,
  );
  escape.onPress = () => {
    if (controls.locked) document.exitPointerLock();
  };
  touch.hidden = !matchMedia("(pointer: coarse)").matches;
		@@ -110,13 +110,27 @@ flashbang, if you bought them,
110	110	<kbd>E</kbd> plants or defuses, <kbd>B</kbd> opens the buy menu in the freeze
111	111	time, <kbd>1</kbd>/<kbd>2</kbd>/<kbd>3</kbd> switch guns, <kbd>Tab</kbd> shows
112	112	the scoreboard, <kbd>F</kbd> puts the stage on the whole screen and
113		<kbd>Esc</kbd> pauses. On a touch screen the left of the view is a thumb stick,
	113	<kbd>Esc</kbd> or <kbd>P</kbd> pauses. On a touch screen the left of the view is a thumb stick,
114	114	the right looks around, and the buttons along the bottom do the rest — including
115	115	the one in the top corner, which is full screen and is how you get one on a
116	116	phone, where there is no keyboard and no pointer to lock. A browser that will not
117	117	put an element full screen — an iPhone will not — never shows that button rather
118	118	than showing one that does nothing.
119	119
	120	Escape is the one key the browser reads before the page does, and on a Mac what
	121	it means is give the window back: full screen drops with the whole animation,
	122	mid-round. So the game asks for the key rather than obeying it. Where a browser
	123	has the Keyboard Lock API — Chrome and Edge — `src/engine/escape.ts` holds
	124	Escape while the stage has the screen, so a pause is a pause and the screen
	125	stays; that browser leaves full screen when Escape is held down, which is the
	126	platform's own way out. Safari and Firefox have no such API and take the screen
	127	whatever the page asks, so the pause panel says so and Resume puts it back —
	128	a click is a gesture, which is the only thing a browser will hand a screen to.
	129	<kbd>P</kbd> pauses the same way and is a key no browser has a meaning of its
	130	own for, so it never costs the screen on any of them. The same thing happens at
	131	`/range`, where Escape gives the mouse back: it keeps the screen where it can,
	132	and Capture the mouse takes back what a browser took.
	133
120	134	The radar sits in the top corner: the level from above, north up and never
121	135	turning, with the rooms in grey, the two bombsites lettered A and B, your side
122	136	in your side's colour and a white wedge for where you are and which way you are
		@@ -232,7 +246,10 @@ renderer, no atlas, no mesh and no sound ship in that bundle, and
232	246	with noise bursts and tones), `loop` (a fixed step with a clamp on a long
233	247	frame), `controls` (a bindings table in, held actions out), `fullscreen` (the stage on
234	248	the whole screen: whether this browser will, whether it is right now, the way
235		in and out, and a refusal swallowed rather than thrown), `overlay` (the
	249	in and out, and a refusal swallowed rather than thrown), `escape` (the Escape
	250	key asked for rather than obeyed: the Keyboard Lock API held while the stage
	251	has the screen, released when it loses it, and the press handed to the game
	252	whether or not the lock was granted), `overlay` (the
236	253	2D over the scene: a scale and a pad off the canvas width, scaled fonts,
237	254	panels, aligned and faded text, a crosshair, a bar, right-aligned columns and
238	255	a `m:ss` clock, drawn onto the seventeen members of a 2D context it uses and
		@@ -299,7 +316,9 @@ renderer, no atlas, no mesh and no sound ship in that bundle, and
299	316	`Ctor`; from `loop` `createLoop`, `Frames`, `Loop` and `LoopOptions`; from
300	317	`controls` `createControls`, `attachButtons` and the event and option types
301	318	they are driven with; from `fullscreen` `createFullscreen` with `Fullscreen`,
302		`FullscreenHost`, `FullscreenTarget` and `FullscreenOwner`; from `overlay` `overlay`, `Overlay` and the `Paint`
	319	`FullscreenHost`, `FullscreenTarget` and `FullscreenOwner`; from `escape`
	320	`createEscape` and `ESCAPE` with `Escape`, `EscapeHost`, `KeyboardLock` and the
	321	`Screen` it reads full screen off; from `overlay` `overlay`, `Overlay` and the `Paint`
303	322	a 2D game draws onto; from `scene` the frame and its pool — `createScene`,
304	323	`resetScene`, `nextInstance`, `pushLine`, `Scene`, `SceneCapacity`, `Camera`
305	324	and `Instance`; from `effects` the ring of what just happened —
		@@ -29,6 +29,10 @@ test("the bindings are the ones the keyboard has always had", () => {
29	29	// the browser for the screen, and nothing about an `Input` changes for it.
30	30	expect(CS_KEYS.KeyF).toBe("fullscreen");
31	31	expect(intent(["fullscreen"])).toEqual(intent([]));
	32	// P is the page's in the same way: it pauses, which is what Escape means too,
	33	// and no browser has a meaning of its own for it to take the window back with.
	34	expect(CS_KEYS.KeyP).toBe("pause");
	35	expect(intent(["pause"])).toEqual(intent([]));
32	36	});
33	37
34	38	test("nothing held is nothing asked for", () => {
		@@ -15,9 +15,13 @@ export const CS_KEYS: Record<string, string> = {
15	15	Space: "jump", ControlLeft: "duck", KeyC: "duck", ShiftLeft: "walk",
16	16	KeyR: "reload", KeyE: "use", KeyG: "grenade", KeyT: "flash", KeyB: "buy", Tab: "scoreboard",
17	17	Digit1: "slot1", Digit2: "slot2", Digit3: "slot3",
18		// Not a thing the world knows about: `main.ts` hears it on `onAction` and
19		// asks the browser for the screen, which `readIntent` below never sees.
	18	// Neither of these is a thing the world knows about: `main.ts` hears them on
	19	// `onAction`, and `readIntent` below never sees either. F asks the browser for
	20	// the screen; P pauses, which is what Escape means too — and P is a key no
	21	// browser has its own meaning for, so it pauses without also handing the
	22	// window back, which is what Escape does on a Mac.
20	23	KeyF: "fullscreen",
	24	KeyP: "pause",
21	25	};
22	26
23	27	/** Left fires, right scopes. */
		@@ -52,7 +52,9 @@ function painted(stage: FakeStage): FakeStage {
52	52	}
53	53
54	54	/** A booted page, its atlas painted, and the match already started on it. */
55		function playing(options: { webgl?: boolean; coarse?: boolean } = {}): FakeStage {
	55	function playing(
	56	options: { webgl?: boolean; coarse?: boolean; fullscreen?: boolean; keyboardLock?: boolean } = {},
	57	): FakeStage {
56	58	const stage = painted(start(fakeStage(options)));
57	59	stage.by("play").fire("click");
58	60	return stage;
		@@ -257,6 +259,101 @@ test("losing the pointer pauses a running match, and does not while the buy pane
257	259	expect(stage.by("pause").hidden).toBe(true);
258	260	});
259	261
	262	test("Escape pauses and keeps the screen where the browser hands the key over", async () => {
	263	const stage = playing();
	264	stage.press("KeyF");
	265	stage.lock(true);
	266	const box = stage.by("stage");
	267	expect(stage.document.fullscreenElement).toBe(box);
	268	// The key was asked for on the way into full screen, and granted a microtask
	269	// later: from here on Escape is the page's and not the browser's.
	270	expect(stage.keyboard.locked).toEqual(["Escape"]);
	271	await Promise.resolve();
	272
	273	stage.window.fire("keydown", { code: "Escape" });
	274	// Paused, the pointer let go — under the lock the browser does not do that for
	275	// us — and the screen still ours, which is the whole point of holding the key.
	276	expect(stage.by("pause").hidden).toBe(false);
	277	expect(stage.document.pointerLockElement).toBe(null);
	278	expect(stage.document.fullscreenElement).toBe(box);
	279	expect(stage.by("esc").textContent).toContain("kept the screen");
	280	expect(stage.by("resume").focused).toBe(1);
	281
	282	// And Resume goes back into the match without asking for a screen it already
	283	// has: one pointer lock, no second `requestFullscreen`.
	284	stage.by("resume").fire("click");
	285	expect(stage.by("pause").hidden).toBe(true);
	286	expect(box.fullscreens).toBe(1);
	287	expect(stage.scene.locks).toBe(2);
	288	});
	289
	290	test("a browser that keeps Escape for itself pauses just the same, and Resume puts the screen back", () => {
	291	// Safari on a Mac: no Keyboard Lock API, so Escape leaves full screen whatever
	292	// the page asks — the window drops out of it with the whole animation, which is
	293	// what this test is about.
	294	const stage = playing({ keyboardLock: false });
	295	stage.press("KeyF");
	296	stage.lock(true);
	297	const box = stage.by("stage");
	298	expect(box.fullscreens).toBe(1);
	299	expect(stage.keyboard.grabs).toBe(0);
	300
	301	// Escape, as that browser delivers it: the screen is gone before the page hears
	302	// the key, and the pointer goes with it.
	303	stage.document.fullscreenElement = null;
	304	stage.document.fire("fullscreenchange");
	305	stage.lock(false);
	306	stage.window.fire("keydown", { code: "Escape" });
	307
	308	expect(stage.by("pause").hidden).toBe(false);
	309	expect(stage.by("esc").textContent).toContain("Resume puts it back");
	310	// Resume is a gesture, which is the only thing a browser will give a screen
	311	// back to: the stage goes full screen again and the pointer with it.
	312	stage.by("resume").fire("click");
	313	expect(stage.document.fullscreenElement).toBe(box);
	314	expect(box.fullscreens).toBe(2);
	315	expect(stage.scene.locks).toBe(2);
	316
	317	// A player who left full screen on purpose is not dragged back into it.
	318	stage.press("KeyF");
	319	expect(stage.document.fullscreenElement).toBe(null);
	320	stage.lock(false);
	321	expect(stage.by("pause").hidden).toBe(false);
	322	stage.by("resume").fire("click");
	323	expect(stage.document.fullscreenElement).toBe(null);
	324	expect(box.fullscreens).toBe(2);
	325	});
	326
	327	test("P pauses too, and a key no browser wants costs no screen", () => {
	328	const stage = playing({ keyboardLock: false });
	329	stage.press("KeyF");
	330	stage.lock(true);
	331	stage.press("KeyP");
	332	expect(stage.by("pause").hidden).toBe(false);
	333	expect(stage.document.fullscreenElement).toBe(stage.by("stage"));
	334	expect(stage.document.pointerLockElement).toBe(null);
	335	// Nothing was taken, and the line in the panel says as much rather than
	336	// promising to put a screen back that never went anywhere.
	337	expect(stage.by("esc").textContent).toContain("Esc or P pauses");
	338	});
	339
	340	test("Escape closes the buy menu before it is a pause", () => {
	341	const stage = playing();
	342	stage.lock(true);
	343	stage.press("KeyB");
	344	expect(stage.by("buy").hidden).toBe(false);
	345	stage.window.fire("keydown", { code: "Escape" });
	346	expect(stage.by("buy").hidden).toBe(true);
	347	expect(stage.by("pause").hidden).toBe(true);
	348	// The next one is the pause, now that there is nothing in front of it.
	349	stage.window.fire("keydown", { code: "Escape" });
	350	expect(stage.by("pause").hidden).toBe(false);
	351	// A pause is not a second pause: the key held down does not stack panels or
	352	// steal the focus again.
	353	stage.window.fire("keydown", { code: "Escape", repeat: true });
	354	expect(stage.by("resume").focused).toBe(1);
	355	});
	356
260	357	test("leaving the match puts the menu back and stops the frame", () => {
261	358	const stage = playing();
262	359	stage.step(FRAME);
		@@ -25,9 +25,10 @@ import { createAudio, type Audio } from "./audio.ts";
25	25	import { CS_KEYS, CS_MOUSE, CS_TAP, readIntent } from "./binding.ts";
26	26	import { drawHud, type Paint } from "./hud.ts";
27	27	import {
28		attachButtons, clamp, createControls, createFullscreen, createLoop, createRenderer, effectAt,
	28	attachButtons, clamp, createControls, createEscape, createFullscreen, createLoop, createRenderer,
	29	effectAt,
29	30	painter,
30		type Button, type Camera, type Listens, type Mesh,
	31	type Button, type Camera, type KeyboardLock, type Listens, type Mesh,
31	32	} from "../engine/index.ts";
32	33	import { generateLevel, seedFrom } from "./generate.ts";
33	34	import { DE_FORGE } from "./map.ts";
		@@ -131,6 +132,12 @@ export type BuildRenderer = (atlas: Uint8Array) => Draws;
131	132	export type Host = {
132	133	document: PageDocument;
133	134	window: PageWindow;
	135	/**
	136	* `navigator.keyboard`, when this browser has one: the Keyboard Lock API, and
	137	* the only way to be handed Escape instead of the browser's meaning for it.
	138	* Absent in Safari and Firefox, where the key keeps that meaning.
	139	*/
	140	keyboard?: KeyboardLock;
134	141	storage: Store;
135	142	fetch(url: string, init: { method: string; headers: Record<string, string>; body: string }): Promise<Reply>;
136	143	/** A fresh match id. `crypto.randomUUID` is one; `src/result.ts` checks it. */
		@@ -175,6 +182,9 @@ export function boot(host: Host): Frame {
175	182	const onMap = by("onmap");
176	183	const prep = by("prep");
177	184	const play = by<Panel & { disabled: boolean }>("play");
	185	const resumeButton = by("resume");
	186	// The line in the pause panel that says what Escape just did on this browser.
	187	const escHint = by("esc");
178	188
179	189	const build = host.createRenderer(sceneCanvas);
180	190	if (build === null) {
		@@ -193,8 +203,9 @@ export function boot(host: Host): Frame {
193	203	// the "fullscreen" action below like every other key this game reads. Both
194	204	// arrive inside a gesture, which is the only time a browser says yes. A
195	205	// browser that will not do it at all leaves the button hidden rather than
196		// showing one that does nothing, and the state is the browser's — Escape
197		// leaves and `onChange` is how this page hears about it.
	206	// showing one that does nothing, and the state is the browser's — a browser
	207	// that takes the screen back says so with `onChange`, which is how this page
	208	// hears about it and, below, how it knows there is something to put back.
198	209	const full = createFullscreen({ element: stageBox, document: doc });
199	210	const paintFull = (on: boolean): void => {
200	211	const label = on ? "Leave full screen" : "Full screen";
		@@ -205,7 +216,33 @@ export function boot(host: Host): Frame {
205	216	};
206	217	full.onChange = paintFull;
207	218	fullButton.hidden = !full.supported;
208		fullButton.addEventListener("click", () => full.toggle());
	219	/**
	220	* What the player asked for, which is not the same as what the browser is
	221	* giving us. On a Mac, Escape hands the screen back whether or not the page
	222	* wanted to keep it — the window drops out of full screen with the whole
	223	* animation, mid-round — and there is no way to refuse that from a keydown.
	224	* So the wish is remembered here, and `restoreFull` puts the screen back from
	225	* inside the Resume click, which is a gesture a browser will honour.
	226	*/
	227	let wantsFull = false;
	228	const askFull = (): void => {
	229	wantsFull = !full.on;
	230	full.toggle();
	231	};
	232	const restoreFull = (): void => {
	233	if (wantsFull && !full.on) full.enter();
	234	};
	235	fullButton.addEventListener("click", askFull);
	236
	237	/**
	238	* Escape, asked for rather than obeyed. Where a browser has the Keyboard Lock
	239	* API — Chrome and Edge — the key is ours while the stage has the screen, so a
	240	* pause is a pause and the screen stays; where it has not, the key still
	241	* arrives and the pause is the same, and what the browser also took Resume
	242	* gives back. `P` is the same press for a player who would rather not find out
	243	* which browser they are on.
	244	*/
	245	const escape = createEscape({ window: win, document: doc, keyboard: host.keyboard }, full);
209	246
210	247	const loop = createLoop({ tick: TICK }, {
211	248	requestAnimationFrame: (callback) => win.requestAnimationFrame(callback),
		@@ -293,10 +330,44 @@ export function boot(host: Host): Frame {
293	330	}
294	331	}
295	332
	333	/**
	334	* Stop the match and say what the key just cost. The panel is shown, the
	335	* pointer is let go — under the keyboard lock the browser does not do that for
	336	* us, which is the point of holding the key — and Resume takes the focus, so
	337	* the way back is one press of Enter wherever the pointer is.
	338	*
	339	* The sentence is the honest one for the browser this is: the key kept the
	340	* screen, or it took it and Resume will put it back, or full screen was never
	341	* asked for and the key cost nothing.
	342	*/
	343	function pauseMatch(): void {
	344	if (!running) return;
	345	show(pause, true);
	346	// Already gone when a lost lock is what paused us; the call is a no-op then,
	347	// and the one thing that has to happen when the key was ours instead.
	348	doc.exitPointerLock();
	349	escHint.textContent =
	350	escape.held
	351	? "Paused. The game kept the screen: Esc never leaves full screen here."
	352	: wantsFull && !full.on
	353	? "Paused. This browser also left full screen on Esc — Resume puts it back."
	354	: "Paused. Esc or P pauses, and Resume goes back.";
	355	resumeButton.focus();
	356	}
	357
	358	/** What Escape and P both mean: close the buy menu if it is open, else pause. */
	359	function pauseKey(): void {
	360	if (!buyPanel.hidden) return openBuy(false);
	361	if (pause.hidden) pauseMatch();
	362	}
	363
	364	escape.onPress = pauseKey;
	365
296	366	controls.onAction = (action, down) => {
297	367	if (!down) return;
298	368	if (action === "buy") return openBuy(buyPanel.hidden);
299		if (action === "fullscreen") return full.toggle();
	369	if (action === "pause") return pauseKey();
	370	if (action === "fullscreen") return askFull();
300	371	// Dead, the trigger is the only thing left to press: it walks the camera
301	372	// along your side, and the aim button walks it back. The touch pad's fire
302	373	// is the same action, so a phone gets it without a button of its own.
		@@ -304,8 +375,11 @@ export function boot(host: Host): Frame {
304	375	if (action === "fire") cycle(world, spectator, 1);
305	376	else if (action === "scope") cycle(world, spectator, -1);
306	377	};
	378	// The pointer went away and we are still in a match: however it went — Escape
	379	// on a browser that keeps the key, a window losing focus, a browser policy —
	380	// the match stops rather than playing on without a mouse.
307	381	controls.onUnlock = () => {
308		if (running && buyPanel.hidden) show(pause, true);
	382	if (running && buyPanel.hidden) pauseMatch();
309	383	};
310	384
311	385	// --- results, sent as the match goes rather than only at the end
		@@ -371,8 +445,11 @@ export function boot(host: Host): Frame {
371	445	}
372	446
373	447	play.addEventListener("click", start);
374		by("resume").addEventListener("click", () => {
	448	// Resume is the gesture that puts back whatever the pause cost: the screen
	449	// first, if a browser took it, and then the pointer.
	450	resumeButton.addEventListener("click", () => {
375	451	show(pause, false);
	452	restoreFull();
376	453	void sceneCanvas.requestPointerLock();
377	454	});
378	455	by("quit").addEventListener("click", () => {
		@@ -382,9 +459,6 @@ export function boot(host: Host): Frame {
382	459	show(menu, true);
383	460	show(touchPanel, false);
384	461	});
385		win.addEventListener("keydown", (event: { code: string }) => {
386		if (event.code === "Escape" && !buyPanel.hidden) openBuy(false);
387		});
388	462	const saved = host.storage.getItem("cs.name");
389	463	if (saved !== null && nameField.value === "") nameField.value = saved;
390	464
		@@ -510,6 +584,10 @@ export function gameMeshes(level: Level = DE_FORGE): Record<string, Mesh> {
510	584	const browser = (): Host => ({
511	585	document,
512	586	window,
	587	// The Keyboard Lock API, if this browser has one. It is read off `navigator`
	588	// rather than asked for: a browser without it has no such member, which is
	589	// exactly what `createEscape` takes as its answer.
	590	keyboard: (navigator as { keyboard?: KeyboardLock }).keyboard,
513	591	storage: localStorage,
514	592	fetch: (url, init) => fetch(url, init),
515	593	randomUUID: () => crypto.randomUUID(),
		@@ -28,7 +28,7 @@
28	28	* and it no longer needs to: what the two shared is behind the door now.
29	29	*/
30	30
31		import { fakePage, type FakeCanvas, type FakeDocument, type FakeElement, type FakePaint, type FakeWindow } from "../engine/index.ts";
	31	import { fakePage, type FakeCanvas, type FakeDocument, type FakeElement, type FakeKeyboard, type FakePaint, type FakeWindow } from "../engine/index.ts";
32	32	import type { Audio } from "./audio.ts";
33	33	import type { Mesh } from "../engine/index.ts";
34	34	import type { BuildRenderer, Draws, Host, Stage } from "./main.ts";
		@@ -105,6 +105,8 @@ export type FakeStage = {
105	105	host: Host;
106	106	document: FakeDocument;
107	107	window: FakeWindow;
	108	/** `navigator.keyboard`: who holds Escape, and how often the game asked. */
	109	keyboard: FakeKeyboard;
108	110	scene: StageCanvas;
109	111	hud: StageCanvas;
110	112	by(id: string): FakeElement;
		@@ -153,7 +155,7 @@ export type FakeStage = {
153	155	* contract between the page and this file, so `src/server.test.ts` checks the
154	156	* served page against this same list rather than a second copy of it.
155	157	*/
156		export const PAGE_IDS = ["stage", "scene", "hud", "menu", "pause", "buy", "touch", "stats", "name", "length", "side", "sens", "map", "onmap", "play", "prep", "resume", "quit", "fps", "full"];
	158	export const PAGE_IDS = ["stage", "scene", "hud", "menu", "pause", "buy", "touch", "stats", "name", "length", "side", "sens", "map", "onmap", "play", "prep", "resume", "quit", "esc", "fps", "full"];
157	159
158	160	/** The ones the server renders with `hidden` on them: the page starts at the menu. */
159	161	const HIDDEN = ["pause", "buy", "touch", "full"];
		@@ -172,11 +174,13 @@ const GLOBALS = ["document", "window", "localStorage", "fetch"];
172	174	/**
173	175	* The whole page the shooter's entry expects, plus the host around it. Pass
174	176	* `webgl: false` for a browser that cannot give the renderer a context,
175		* `coarse: true` for a phone, and `fullscreen: false` for a browser that will
176		* not put an element on the whole screen.
	177	* `coarse: true` for a phone, `fullscreen: false` for a browser that will not
	178	* put an element on the whole screen, and `keyboardLock: false` for one that
	179	* will not hand the page the Escape key — which is Safari, and the browser this
	180	* game's pause has to be honest on.
177	181	*/
178	182	export function fakeStage(
179		options: { webgl?: boolean; coarse?: boolean; fullscreen?: boolean } = {},
	183	options: { webgl?: boolean; coarse?: boolean; fullscreen?: boolean; keyboardLock?: boolean } = {},
180	184	): FakeStage {
181	185	const page = fakePage({
182	186	ids: PAGE_IDS,
		@@ -185,6 +189,7 @@ export function fakeStage(
185	189	actions: PAGE_ACTIONS,
186	190	coarse: options.coarse,
187	191	fullscreen: options.fullscreen,
	192	keyboardLock: options.keyboardLock,
188	193	});
189	194	// Asked for with `paint` left on, so both canvases have their 2D recorder.
190	195	const [scene, hud] = page.canvases as [StageCanvas, StageCanvas];
		@@ -222,6 +227,7 @@ export function fakeStage(
222	227	host: {
223	228	document: page.document,
224	229	window: page.window,
	230	keyboard: page.keyboard,
225	231	storage: {
226	232	getItem: (key) => store.get(key) ?? null,
227	233	setItem: (key, value) => void store.set(key, value),
		@@ -249,6 +255,7 @@ export function fakeStage(
249	255	},
250	256	document: page.document,
251	257	window: page.window,
	258	keyboard: page.keyboard,
252	259	scene,
253	260	hud,
254	261	buttons: page.buttons,
		@@ -357,6 +357,35 @@ inside a click or a keydown, which is the only time a browser says yes. The
357	357	`:fullscreen` half is CSS: the element keeps whatever aspect ratio and maximum
358	358	height it had unless a rule says otherwise.
359	359
	360	### escape
	361
	362	Escape is the one key the browser reads before your page does, and on a Mac what
	363	it means is "give the window back": the screen drops out of full screen, which a
	364	player in the middle of a round reads as their window being thrown away. There is
	365	exactly one way to ask for the key rather than its meaning — the Keyboard Lock
	366	API — and this is the three lines of it.
	367
	368	`createEscape` takes an `EscapeHost` — the window the keydown arrives on, the
	369	document that announces full screen, and an optional `KeyboardLock`, which is
	370	`navigator.keyboard` and is absent in Safari and Firefox — plus a `Screen`, which
	371	is anything with a live `Screen.on`, so a `Fullscreen` is one. It hands back an
	372	`Escape`: `Escape.supported`, false on a browser with no such API, so a page can
	373	say what the key will do rather than guess; `Escape.held`, whether the key is
	374	ours right now, which is the grant and still being full screen, read live
	375	rather than remembered; the `Escape.onPress` callback, one call per press and
	376	never for a repeat; and `Escape.detach`, which gives the key back. `ESCAPE` is
	377	the code it is about, and the only one it ever asks for.
	378
	379	The lock follows the screen, because a browser only grants it in full screen and
	380	drops it when full screen goes: it is asked for on the way in and released on the
	381	way out, and a refusal — a rejected promise, or a browser that throws instead —
	382	leaves `Escape.held` false and is not an error a game can act on. Under the lock
	383	the browser stops acting on the key and leaves full screen only when it is held
	384	down, so `Escape.onPress` is the whole of what the key means and your game decides
	385	that: close a panel, pause the match, let the pointer go. What this does not do is
	386	put anything back — a browser that took the screen took it inside its own gesture,
	387	and only another gesture can ask again, which is your Resume button.
	388
360	389	### overlay
361	390
362	391	The 2D a game draws over its scene. `overlay` takes the surface, the width and
		@@ -499,8 +528,11 @@ What you bring is `PageOptions`, which is your game and not the engine's:
499	528	`PageOptions.canvases` says which of those are canvases (the first one is the
500	529	surface), `PageOptions.hidden` is the ones the server renders already hidden,
501	530	and `PageOptions.actions` is one `[data-action]` element per name.
502		`paint: false` is a browser whose canvas gives no 2D context, and `coarse: true`
503		is a phone. Then `FakePage.step(ms)` runs the oldest frame that was asked for,
	531	`paint: false` is a browser whose canvas gives no 2D context, `coarse: true`
	532	is a phone, `fullscreen: false` is a browser that will not put an element on the
	533	whole screen, and `keyboardLock: false` is one with no Keyboard Lock API — which
	534	takes both methods off `FakePage.keyboard`, the `FakeKeyboard` that records what
	535	is locked, how often it was asked and whether it is refusing. Then `FakePage.step(ms)` runs the oldest frame that was asked for,
504	536	that many milliseconds after the last one — that is the whole clock, and there
505	537	is no timer anywhere in the file.
506	538
		@@ -287,6 +287,10 @@ test("the example imports the door and nothing else, which is what it is for", (
287	287	* fullscreen — `Fullscreen`, `FullscreenHost`, `FullscreenOwner`,
288	288	* `FullscreenTarget`, `createFullscreen`.
289	289	*
	290	* escape — `ESCAPE`, `Escape`, `EscapeHost`, `KeyboardLock`, `Screen`,
	291	* `createEscape`; and `FakeKeyboard`, which is the browser's half of it on the
	292	* headless page.
	293	*
290	294	* effects — `Effects`, `createEffects`, `pushEffect`, `expireEffects`,
291	295	* `effectAt`, `resetEffects`.
292	296	*
		@@ -295,20 +299,21 @@ test("the example imports the door and nothing else, which is what it is for", (
295	299	*/
296	300	export const SURFACE = [
297	301	"Activations", "Adam", "Body", "Box", "Builder", "Burst", "Button", "ButtonOptions",
298		"CHECKPOINT_CHARS", "Camera", "Complaint", "Controls", "Ctor", "DEFAULT_HYPER", "Effects",
	302	"CHECKPOINT_CHARS", "Camera", "Complaint", "Controls", "Ctor", "DEFAULT_HYPER", "ESCAPE",
	303	"Effects", "Escape", "EscapeHost",
299	304	"FakeCanvas",
300		"FakeDocument", "FakeElement", "FakePage", "FakePaint", "FakeTarget", "FakeWindow", "Fold",
	305	"FakeDocument", "FakeElement", "FakeKeyboard", "FakePage", "FakePaint", "FakeTarget", "FakeWindow", "Fold",
301	306	"Folded", "Frames", "Fullscreen", "FullscreenHost", "FullscreenOwner", "FullscreenTarget",
302		"Grads", "Grid", "Hit", "Host", "Hull", "Hyper", "Instance", "KeyEventish",
	307	"Grads", "Grid", "Hit", "Host", "Hull", "Hyper", "Instance", "KeyEventish", "KeyboardLock",
303	308	"Listens", "LockOwner", "Loop", "LoopOptions", "Mat4", "Mesh", "MouseEventish", "MoveTuning", "Options",
304	309	"Overlay", "Packed", "PageOptions", "Paint", "Painter", "Pin", "Policy", "QUANTUM",
305		"Renderer", "RendererAssets", "Rollout", "Scene", "SceneCapacity", "Shader", "Shape",
	310	"Renderer", "RendererAssets", "Rollout", "Scene", "SceneCapacity", "Screen", "Shader", "Shape",
306	311	"SoundDevice", "Stick", "Surface", "Tone", "TouchEventish", "Touchish", "UpdateStats", "Vec3",
307	312	"Wish", "accelerate", "add", "addBox", "airAccelerate", "angleDelta", "angleVectors",
308	313	"applyGrads", "attachButtons", "attenuate",
309	314	"backward", "builder", "cellAt", "clamp", "clearGrads", "colOf", "compare",
310	315	"computeAdvantages", "copyPolicy", "createAdam", "createControls", "createEffects",
311		"createFullscreen",
	316	"createEscape", "createFullscreen",
312	317	"createLoop", "createPolicy", "createRenderer", "createRollout", "createScene",
313	318	"createSoundDevice",
314	319	"cross", "deg", "dist", "dist2d", "dot", "effectAt", "expireEffects", "eyeHeight", "fakePage",
		@@ -0,0 +1,161 @@
	1	/**
	2	* Escape, driven against the headless page next door: the key heard, the lock
	3	* asked for when the stage takes the screen and given back when it loses it, a
	4	* browser with no Keyboard Lock API, a browser that refuses, and the stale grant
	5	* that must not outlive the screen it was granted for. Nothing in here is a
	6	* browser — `fakePage`'s `keyboard` is the one that hands the key over, and its
	7	* document fires `fullscreenchange` the way a real one does.
	8	*/
	9
	10	import { expect, test } from "bun:test";
	11	import { createEscape, ESCAPE, type EscapeHost } from "./escape.ts";
	12	import { createFullscreen } from "./fullscreen.ts";
	13	import { fakePage } from "./page.ts";
	14
	15	/** A page with a stage on it, full screen around the stage, and Escape over both. */
	16	function stage(options: { keyboardLock?: boolean } = {}) {
	17	const page = fakePage({ ids: ["stage"], keyboardLock: options.keyboardLock });
	18	const full = createFullscreen({ element: page.by("stage"), document: page.document });
	19	const presses: number[] = [];
	20	const escape = createEscape(
	21	{ window: page.window, document: page.document, keyboard: page.keyboard },
	22	full,
	23	);
	24	escape.onPress = () => void presses.push(presses.length + 1);
	25	return { page, full, escape, presses };
	26	}
	27
	28	test("the key is heard once per press, and its browser meaning is refused", () => {
	29	const { page, presses } = stage();
	30	let prevented = 0;
	31	page.window.fire("keydown", { code: ESCAPE, preventDefault: () => void (prevented += 1) });
	32	expect(presses.length).toBe(1);
	33	expect(prevented).toBe(1);
	34
	35	// A key held down repeats. One press is one pause, not sixty.
	36	page.window.fire("keydown", { code: ESCAPE, repeat: true });
	37	expect(presses.length).toBe(1);
	38	// And nothing else on the keyboard is this module's business.
	39	page.window.fire("keydown", { code: "KeyW" });
	40	page.window.fire("keyup", { code: ESCAPE });
	41	expect(presses.length).toBe(1);
	42	});
	43
	44	test("the lock follows the screen: asked for on the way in, given back on the way out", async () => {
	45	const { page, full, escape } = stage();
	46	expect(escape.supported).toBe(true);
	47	// Nothing is asked for by a page that is not full screen.
	48	expect(page.keyboard.grabs).toBe(0);
	49	expect(escape.held).toBe(false);
	50
	51	full.enter();
	52	expect(page.keyboard.grabs).toBe(1);
	53	expect(page.keyboard.locked).toEqual([ESCAPE]);
	54	// The grant is a promise: it is ours on the microtask it resolves, not before.
	55	expect(escape.held).toBe(false);
	56	await Promise.resolve();
	57	expect(escape.held).toBe(true);
	58
	59	full.exit();
	60	expect(page.keyboard.locked).toBe(null);
	61	expect(escape.held).toBe(false);
	62	});
	63
	64	test("held is read from the screen, never remembered", async () => {
	65	const { page, full, escape } = stage();
	66	full.enter();
	67	await Promise.resolve();
	68	expect(escape.held).toBe(true);
	69	// Escape held down, which a browser answers by taking the screen back. The
	70	// event is all we get, and the key is the browser's again the moment it fires.
	71	page.document.fullscreenElement = null;
	72	page.document.fire("fullscreenchange");
	73	expect(escape.held).toBe(false);
	74	expect(page.keyboard.locked).toBe(null);
	75	});
	76
	77	test("a grant that arrives after the screen is gone does not claim the key", async () => {
	78	const { page, full, escape } = stage();
	79	full.enter();
	80	// Out again before the lock's promise has had a chance to settle: the grant
	81	// belongs to a lock the browser has already dropped.
	82	full.exit();
	83	await Promise.resolve();
	84	await Promise.resolve();
	85	expect(escape.held).toBe(false);
	86	expect(page.keyboard.locked).toBe(null);
	87	});
	88
	89	test("a browser with no Keyboard Lock API says so, and is not asked", () => {
	90	const { page, full, escape, presses } = stage({ keyboardLock: false });
	91	expect(escape.supported).toBe(false);
	92	full.enter();
	93	expect(page.keyboard.grabs).toBe(0);
	94	expect(escape.held).toBe(false);
	95	// The key still arrives; this is the browser where it also leaves full screen.
	96	page.window.fire("keydown", { code: ESCAPE });
	97	expect(presses.length).toBe(1);
	98	});
	99
	100	test("a refusal is not a crash, whichever way the browser refuses", async () => {
	101	const { page, full, escape } = stage();
	102	page.keyboard.refuse = true;
	103	expect(() => full.enter()).not.toThrow();
	104	await Promise.resolve();
	105	await Promise.resolve();
	106	expect(escape.held).toBe(false);
	107
	108	// And a browser that throws where it should have rejected.
	109	const thrower: EscapeHost = {
	110	window: page.window,
	111	document: page.document,
	112	keyboard: {
	113	lock: () => {
	114	throw new Error("not allowed");
	115	},
	116	unlock: () => {
	117	throw new Error("not allowed either");
	118	},
	119	},
	120	};
	121	const rude = createEscape(thrower, { on: true });
	122	expect(rude.held).toBe(false);
	123	expect(() => rude.detach()).not.toThrow();
	124	});
	125
	126	test("a page booted already full screen holds the key from the start", async () => {
	127	const page = fakePage({ ids: ["stage"] });
	128	page.document.fullscreenElement = page.by("stage");
	129	const escape = createEscape(
	130	{ window: page.window, document: page.document, keyboard: page.keyboard },
	131	{ on: true },
	132	);
	133	await Promise.resolve();
	134	expect(escape.held).toBe(true);
	135	expect(page.keyboard.grabs).toBe(1);
	136	});
	137
	138	test("detach leaves the page as it found it, key included", async () => {
	139	const { page, full, escape, presses } = stage();
	140	full.enter();
	141	await Promise.resolve();
	142	expect(page.window.listening.has("keydown")).toBe(true);
	143	expect(page.document.listening.has("fullscreenchange")).toBe(true);
	144
	145	escape.detach();
	146	expect(page.keyboard.locked).toBe(null);
	147	expect(escape.held).toBe(false);
	148	expect(page.window.listening.has("keydown")).toBe(false);
	149	page.window.fire("keydown", { code: ESCAPE });
	150	expect(presses.length).toBe(0);
	151	// The full screen module is still the one listening for its own event.
	152	expect(page.document.listening.has("fullscreenchange")).toBe(true);
	153	});
	154
	155	test("a browser with no keyboard at all is a browser, not an exception", () => {
	156	const page = fakePage({ ids: ["stage"] });
	157	const escape = createEscape({ window: page.window, document: page.document }, { on: true });
	158	expect(escape.supported).toBe(false);
	159	expect(escape.held).toBe(false);
	160	expect(() => page.window.fire("keydown", { code: ESCAPE })).not.toThrow();
	161	});
		@@ -0,0 +1,149 @@
	1	/**
	2	* Escape: the one key a browser reads before the page does. Every game here
	3	* wants it to mean "pause", and on a Mac it means "give the window back" — the
	4	* screen drops out of full screen with the whole macOS animation, which is what
	5	* a player sees as their window being thrown away mid-round.
	6	*
	7	* There is exactly one way to ask for the key rather than the meaning, and this
	8	* module is the three lines of it: the Keyboard Lock API. `keyboard.lock(["Escape"])`
	9	* says "deliver that key to the page while it is full screen"; the browser then
	10	* only leaves full screen when Escape is held, which is the behaviour the
	11	* platform intends and the one a game wants. It is Chrome's and Edge's; Safari
	12	* and Firefox do not have it, so `supported` says so and a game that asks gets
	13	* the honest answer rather than a promise nobody kept.
	14	*
	15	* Three things this file takes seriously, all three of them a real browser:
	16	*
	17	* - The API may be missing entirely — `navigator.keyboard` is undefined in
	18	* Safari — so the whole host member is optional and a missing one is not an
	19	* error, it is a browser where Escape keeps its own meaning.
	20	* - The lock is only granted in full screen and is dropped when full screen
	21	* goes. So it is asked for when the stage takes the screen and released when
	22	* it gives it back, and `held` is read live — granted and still there —
	23	* rather than remembered, the way `fullscreen.ts` reads `on`.
	24	* - The key still arrives as a keydown whether the lock was granted or not.
	25	* `onPress` is that event, once per press and never for a repeat, and it is
	26	* the game's whole interface to the key: what Escape means — close the buy
	27	* menu, pause the match, show the note — is the game's business, and this
	28	* file has no opinion about it.
	29	*
	30	* What it does not do is put anything back. A browser that took the screen took
	31	* it inside its own gesture, and only another gesture can ask again: that is the
	32	* game's Resume button, and the game is the one that knows whether the player
	33	* wanted full screen in the first place.
	34	*/
	35
	36	import type { Listens } from "./controls.ts";
	37
	38	/** The code of the key this module is about, and the only one it ever asks for. */
	39	export const ESCAPE = "Escape";
	40
	41	/**
	42	* `navigator.keyboard`, as far as this file is concerned. Both methods are
	43	* optional because a browser has either both or neither, and `lock` hands back a
	44	* promise that rejects when the browser will not.
	45	*/
	46	export type KeyboardLock = {
	47	lock?(codes: readonly string[]): unknown;
	48	unlock?(): unknown;
	49	};
	50
	51	/**
	52	* Where the key is heard, where full screen is announced, and the keyboard to
	53	* ask — `window`, `document` and `navigator.keyboard` in a browser, three plain
	54	* objects in a test.
	55	*/
	56	export type EscapeHost = {
	57	window: Listens;
	58	document: Listens;
	59	/** Absent on a browser with no Keyboard Lock API, which is most of them. */
	60	keyboard?: KeyboardLock;
	61	};
	62
	63	/** Whether the stage is on the whole screen right now. A `Fullscreen` is one. */
	64	export type Screen = { readonly on: boolean };
	65
	66	export type Escape = {
	67	/** Whether this browser can hand the key over at all. False is not a failure. */
	68	readonly supported: boolean;
	69	/** Whether it is ours right now: granted, and still full screen. Live. */
	70	readonly held: boolean;
	71	/** Escape went down. Once per press; a held key does not repeat into this. */
	72	onPress: () => void;
	73	detach(): void;
	74	};
	75
	76	export function createEscape(host: EscapeHost, screen: Screen): Escape {
	77	const keyboard = host.keyboard;
	78	const supported = typeof keyboard?.lock === "function" && typeof keyboard?.unlock === "function";
	79	// Whether the last request was granted. `held` is this and the screen: the
	80	// browser drops the lock when full screen goes, so remembering only the
	81	// promise would be a claim that outlived the thing it was true about.
	82	let granted = false;
	83	// Which request is the current one. A promise that resolves after the screen
	84	// was handed back belongs to a lock that is already gone and may not claim the
	85	// key; without this, a fast Escape leaves `held` true forever.
	86	let asked = 0;
	87
	88	const ask = (): void => {
	89	if (!supported) return;
	90	const mine = ++asked;
	91	if (!screen.on) {
	92	granted = false;
	93	try {
	94	keyboard?.unlock?.();
	95	} catch {
	96	// A browser that throws where it should not. The key is the browser's
	97	// again either way, which is exactly what we just asked for.
	98	}
	99	return;
	100	}
	101	try {
	102	// A promise nobody awaits still rejects loudly, and a refusal here is not
	103	// news: it is a browser saying the key stays its own.
	104	const asking = keyboard?.lock?.([ESCAPE]);
	105	// Only the current request may claim the key: a stale one says nothing at
	106	// all, rather than answering for the lock that replaced it.
	107	if (asking instanceof Promise) asking.then(() => void (mine === asked && (granted = true)), () => {});
	108	else granted = true;
	109	} catch {
	110	granted = false;
	111	}
	112	};
	113
	114	const key = (event: { code: string; repeat?: boolean; preventDefault(): void }): void => {
	115	if (event.code !== ESCAPE \|\| event.repeat === true) return;
	116	// The browser's own meaning for the key, refused where refusing is allowed:
	117	// under the lock this is the whole point, and without it it costs nothing.
	118	event.preventDefault();
	119	escape.onPress();
	120	};
	121
	122	const escape: Escape = {
	123	supported,
	124	get held() {
	125	return granted && screen.on;
	126	},
	127	onPress: () => {},
	128	detach() {
	129	host.window.removeEventListener("keydown", key);
	130	host.document.removeEventListener("fullscreenchange", ask);
	131	asked += 1;
	132	granted = false;
	133	if (supported) {
	134	try {
	135	keyboard?.unlock?.();
	136	} catch {
	137	// Leaving the page as we found it is best effort by definition.
	138	}
	139	}
	140	},
	141	};
	142
	143	host.window.addEventListener("keydown", key);
	144	host.document.addEventListener("fullscreenchange", ask);
	145	// A page that is already full screen when this is wired — a game booted into
	146	// one — is a page that should already hold the key.
	147	ask();
	148	return escape;
	149	}