From cd6bb2ea376e0a067366bf9cb14ad72cbd92aa11 Mon Sep 17 00:00:00 2001 From: SandroMaglione Date: Mon, 16 Nov 2026 18:12:45 +1300 Subject: [PATCH] An open modal owns the keys wherever focus is; playbook steps for DOM controls and menus Keyboard.actions left a key to the page only when closest() from its target found a modal. When a redraw deleted the focused button inside an open dialog, focus fell to and the game took the keys again: Z and Space pressed game actions behind the menu, and Escape pressed the game's action and was prevented, so the dialog stayed open. After closest(), the rule now asks the key's document (the target's ownerDocument, or the target when it can query): a dialog:modal, or an [aria-modal="true"] element whose checkVisibility({ visibilityProperty, opacityProperty }) is true. A closed aria-modal element left in the page, or one fading out at opacity 0, leaves the keys with the game. A target that cannot answer keeps today's behaviour. Keys bound to no action skip the check. Keyboard.presses is unchanged. The ritmo skill's UI playbook gains steps 7 and 8: build DOM controls once and never rewrite a region holding one, with a name a test can find; a menu that stops play is a modal, its cancel and close are intents, a splash or wipe over it is a manual popover, and a layer the player presses is its own modal dialog. Co-Authored-By: Claude Opus 5.5 --- .changeset/open-modal-owns-keys.md | 28 ++++ .changeset/ui-playbook-dom-controls.md | 5 + packages/browser/README.md | 2 +- packages/browser/src/Keyboard.ts | 95 +++++++++-- packages/browser/test/Keyboard.test.ts | 148 ++++++++++++++++++ .../skills/ritmo/playbooks/ui-and-render.md | 2 + 6 files changed, 269 insertions(+), 11 deletions(-) create mode 100644 .changeset/open-modal-owns-keys.md create mode 100644 .changeset/ui-playbook-dom-controls.md diff --git a/.changeset/open-modal-owns-keys.md b/.changeset/open-modal-owns-keys.md new file mode 100644 index 00000000..e4e6c3e3 --- /dev/null +++ b/.changeset/open-modal-owns-keys.md @@ -0,0 +1,28 @@ +--- +"@typeonce/ritmo-browser": minor +--- + +**Breaking (a fix to 0.24's modal rule): `Keyboard.actions` leaves every key to the page while a modal dialog is open, wherever focus is.** In 0.24 a key was the page's only when its target was inside the modal. When a redraw deleted the focused button inside an open ``, focus fell to `` and the game took the keys again: Z and Space pressed game actions behind the menu, and Escape pressed the game's action and was `preventDefault`-ed, so the dialog did not close. + +A modal is now open when the key's document holds a `` opened with `showModal()`, or an `aria-modal="true"` element that is shown (`checkVisibility({ visibilityProperty: true, opacityProperty: true })`). An `aria-modal` element still in the page but closed (`hidden`, `display: none`, `visibility: hidden`, a closed popover, inside a closed ``) leaves the keys with the game, and so does one fading out at `opacity: 0`. `Keyboard.presses` is unchanged. + +What a game may need to change: + +- An `aria-modal="true"` element left shown during play now takes every key. Hide it when its menu closes, or remove the attribute: + + ```ts + menu.hidden = true // or menu.hidePopover(), or menu.removeAttribute("aria-modal") + ``` + +- A script that hides an `aria-modal` menu on Escape runs before a `window` host hears the key, so the game still gets that Escape. Prevent the key it handled: + + ```ts + document.addEventListener("keydown", (event) => { + if (event.key === "Escape" && menu.matches(":popover-open")) { + event.preventDefault() + menu.hidePopover() + } + }) + ``` + +- A game that merged a dialog's Escape with the game's Escape action (both arrived in one frame with focus on ``) now gets only the dialog's. diff --git a/.changeset/ui-playbook-dom-controls.md b/.changeset/ui-playbook-dom-controls.md new file mode 100644 index 00000000..1d79f53b --- /dev/null +++ b/.changeset/ui-playbook-dom-controls.md @@ -0,0 +1,5 @@ +--- +"@typeonce/ritmo": patch +--- + +The `ritmo` skill's UI playbook (`ui-and-render.md`) gains two steps for DOM controls and menus: build each control once and update it in place, never rewriting a region that holds one, and give it a name a test can find; a menu that stops play is a modal (`showModal()` on a ``, or an `aria-modal` element that moves focus in, keeps it there, and makes the page behind inert itself), whose `cancel` and `close` are intents, with a `popover="manual"` for a splash or wipe over it and a modal dialog of its own for a layer the player presses. diff --git a/packages/browser/README.md b/packages/browser/README.md index 1019e5ac..6d6d2bb7 100644 --- a/packages/browser/README.md +++ b/packages/browser/README.md @@ -4,7 +4,7 @@ Browser integrations for ritmo: - `BrowserTickSource`: animation frames as a tick source for the core fixed-step loop. - `BrowserVisibility`: the Page Visibility API as the `Visibility` of a networked session's `hidden` option, so a hidden tab tells the other peers instead of going silent (see [Hidden tabs](https://github.com/typeonce-dev/ritmo/blob/main/packages/netcode/README.md#hidden-tabs)). -- Devices, each built with `X.actions(...)` from its host and bindings (a layout for `Touch`) and reporting a snapshot of `actions`, `vectors`, and `used`: `Keyboard` (keys by character or physical key; a key pressed with Ctrl or Cmd is left to the browser as a shortcut unless the game binds Control or Meta, and a key the page is using is left to the page: one in a form field, inside an open modal dialog, or already handled by a widget, and Enter, Space, and Tab on a control reached by keyboard, whose other keys stay with the game, while a button clicked with the mouse keeps none), `Gamepad` (standard-mapping button names, sticks, and triggers; a pad without the standard mapping is read by its buttons only, and says so in `standard`), `Pointer` (mouse and pen buttons, chords included, position, wheel, pointer lock), and `Touch` (on-screen controls with named floating sticks, one per vector, and drag-to-aim buttons; a control the game hides is `null` in the layout and lets go of its finger). Keyboard, gamepad, and pointer bindings are rebindable at runtime for a controls settings screen (validate saved ones with `parseRebinding`); every device has scripted timelines for tests, and keyboard, gamepad, and pointer also record them for replays. +- Devices, each built with `X.actions(...)` from its host and bindings (a layout for `Touch`) and reporting a snapshot of `actions`, `vectors`, and `used`: `Keyboard` (keys by character or physical key; a key pressed with Ctrl or Cmd is left to the browser as a shortcut unless the game binds Control or Meta, and a key the page is using is left to the page: one in a form field, any key while a modal dialog is open, or one already handled by a widget, and Enter, Space, and Tab on a control reached by keyboard, whose other keys stay with the game, while a button clicked with the mouse keeps none), `Gamepad` (standard-mapping button names, sticks, and triggers; a pad without the standard mapping is read by its buttons only, and says so in `standard`), `Pointer` (mouse and pen buttons, chords included, position, wheel, pointer lock), and `Touch` (on-screen controls with named floating sticks, one per vector, and drag-to-aim buttons; a control the game hides is `null` in the layout and lets go of its finger). Keyboard, gamepad, and pointer bindings are rebindable at runtime for a controls settings screen (validate saved ones with `parseRebinding`); every device has scripted timelines for tests, and keyboard, gamepad, and pointer also record them for replays. - `Controls`: the game's actions declared once, as buttons and vectors (movement with length at most 1, from keys, d-pad, stick, or touch stick), and the devices merged into one input source; devices used together (keyboard and mouse) are grouped as one. It also holds the types every device shares: `Controls.ActionState` (a button's `held` / `pressed` / `released`) and `Controls.Vector`. `Controls.players` and `Gamepad.pads`: local multiplayer, where players join a slot by pressing a button on any pooled device, every pad on its own. - `InputCapture`: the system that drains an input source once per update into a resource. Systems read that resource; a system that calls `snapshot()` itself declares the source with `Game.System.consumeService`. Declare the source service as `InputCapture.SourceOf` (the device's, merge's, or pool's `snapshot()` only), so one descriptor is provided by the live devices in the page, scripted ones in tests, and the recorded or fuzzed input of [`@typeonce/ritmo-devtools`](https://github.com/typeonce-dev/ritmo/blob/main/packages/devtools/README.md) (`Replay`, `Fuzz`); the page keeps the device to rebind and dispose it. diff --git a/packages/browser/src/Keyboard.ts b/packages/browser/src/Keyboard.ts index 79b45369..3c1f62cb 100644 --- a/packages/browser/src/Keyboard.ts +++ b/packages/browser/src/Keyboard.ts @@ -30,10 +30,11 @@ * * Keys the page is using are left to the page: a key that goes down in a * form field (`` of any type, `