Skip to content

An open modal owns the keys wherever focus is; playbook steps for DOM controls and menus - #232

Merged
SandroMaglione merged 1 commit into
mainfrom
browser/open-modal-owns-keys
Nov 16, 2026
Merged

SandroMaglione merged 1 commit into
mainfrom
browser/open-modal-owns-keys

Conversation

@SandroMaglione

Copy link
Copy Markdown
Member

What was wrong

In 0.24, Keyboard.actions left a key to the page only when closest(...) from the key's target found a dialog:modal or an [aria-modal="true"] element. When a redraw deleted the focused button inside an open modal, focus fell to <body>, and the game took the keys again.

Reproduced on the published @typeonce/ritmo-browser@0.24.0 in Chromium 141, with a <dialog> opened by showModal() and then document.activeElement.blur():

  • Z and Space pressed game actions behind the menu.
  • Escape pressed the game's pause action and was preventDefault-ed, so the dialog stayed open and fired no close. Without the keyboard, Escape with focus on <body> closes the dialog.

The same thing happens with a popover="manual" element that carries a static aria-modal="true". That is how one of the audited games builds its menu, and why it saw Escape arrive twice in one frame.

The rule

closest is still asked first. Then the key's document is asked: the target's ownerDocument, or the target itself when it has querySelector. A modal is open when the document holds:

  • a dialog:modal, or
  • an [aria-modal="true"] element whose checkVisibility({ visibilityProperty: true, opacityProperty: true }) returns true.

Details:

  • Closed menus left in the page: an aria-modal element that is hidden, display: none, visibility: hidden, a closed popover, or inside a closed dialog leaves the keys with the game. A closed menu often stays in the page with its attribute.
  • Fading out: an element at opacity: 0 also leaves the keys with the game. The menu is visually gone, and the JSDoc says so.
  • Plain test hosts: everything is read by shape, with no instanceof. Queries run in try/catch and nothing is cached. A target that cannot answer (no ownerDocument, no checkVisibility, a query that throws) keeps today's behaviour, so plain-object test hosts are unchanged.
  • Unbound keys: a key bound to no action is neither pressed nor prevented, so it now skips the check. This doesn't change behaviour; it keeps typing on the page free.
  • Keyboard.presses is unchanged: a settings dialog still hears the key to bind.

The KeyEvent JSDoc, the module header and the README state the rule. The changeset is marked breaking and carries the fix.

Browser evidence (Chromium 141, headless)

The page binds Z, Space and Escape. Each case presses Z, Space, then Escape. "prevented" is defaultPrevented as window saw each of the three keys.

build menu state Z, Space → game Escape → game prevented menu after Escape
0.24.0 <dialog> closed, focus on canvas jump, undo pause 1 1 1 closed
0.24.0 <dialog> open, focus inside – – 0 0 0 closed (1 close)
0.24.0 <dialog> open, focus on <body> jump, undo pause 1 1 1 still open
0.24.0 popover + aria-modal open, focus on <body> jump, undo pause 1 1 1 closed by the page's script
this PR <dialog> closed, focus on canvas jump, undo pause 1 1 1 closed
this PR <dialog> open, focus inside – – 0 0 0 closed (1 close)
this PR <dialog> open, focus on <body> – – 0 0 0 closed (1 close)
this PR popover + aria-modal closed, focus on canvas jump, undo pause 1 1 1 closed
this PR popover + aria-modal open, focus inside – – 0 0 0 closed by the page's script
this PR popover + aria-modal open, focus on <body> – see below 0 0 1 closed by the page's script

The last row. That page's own Escape listener (on document) hides the popover without preventing the key. It runs before window hears the key, so by then no modal is open and the game gets pause. With the listener calling preventDefault(), the game gets nothing. The JSDoc and the changeset tell such a script to prevent the key it handled. A native <dialog> doesn't have this problem: its close comes after dispatch.

aria-modal elements left in the page, with Space pressed and focus on <body>:

element game gets Space?
hidden attribute yes
display: none yes
visibility: hidden yes
opacity: 0 (fading out) yes
closed popover yes
inside a closed <dialog> yes
shown (control) no

Cost on auto-repeat

The check runs on every keydown of a bound key, repeats included. Each figure is the median of 5 runs of 20,000 synthetic keydowns dispatched from <body>:

page 0.24.0 this PR
500 nodes, 1 closed aria-modal 2.3 µs 11 µs
5,000 nodes, 0, 1 or 20 aria-modal (closed or shown) 2.2–2.4 µs 79–87 µs
5,000 nodes, unbound key 1.9 µs 1.7 µs

Each query walks the whole tree, about 6 ns per node. Auto-repeat sends about 30 keydowns a second, so even the 5,000-node case is under 3 ms per second, at most about 0.1 ms in one frame. A player can't feel that. Unbound keys cost nothing extra.

The playbook

ui-and-render.md gains steps 7 and 8. Step 6, the import-direction lint, keeps its number because ritmo-polish and POLISH.md cite it.

  • Step 7: build each DOM control once and update it in place; never rewrite a region that holds one. Give it a name a test can find.
  • Step 8: a menu that stops play is a modal. Native showModal() comes first; an aria-modal element must move focus in, keep it there, and make the page inert itself. The menu's own keys listen on it. cancel and close are intents, because the browser closes a dialog on a repeated Escape even when cancel is prevented. A splash or wipe over it is a popover="manual"; a layer the player presses is its own modal dialog.

The facts behind step 8 were checked in Chromium 141:

  • Repeated Escape: with cancel prevented, the third Escape closed the dialog anyway.
  • Popover over a modal: a popover="manual" shown over a modal dialog is drawn above it but is inert: focus() is refused and a click doesn't land.
  • Nested modal: a second modal dialog over the first takes focus and clicks.

The Check line is unchanged; the keyboard walk that will give it something to check comes in a follow-up.

Not covered

  • Shadow roots: a modal inside one is not seen. The key's target is then the shadow host, and the document query does not look inside. This was already true of closest; no audited game uses shadow DOM. Stated in the KeyEvent JSDoc.
  • Other browsers: Firefox and WebKit were not run (their Playwright builds are not installed here). dialog:modal and checkVisibility with both options are supported in current Firefox and Safari, but the evidence above is Chromium only.

Verified locally

  • pnpm run check (1,989 tests). The new modal tests fail against the 0.24 rule (5 of them) and pass with this one.
  • pnpm bench:check: no blocking regressions.
  • pnpm --dir website build

🤖 Generated with Claude Code

… 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 <body> 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 <noreply@anthropic.com>
@SandroMaglione

Copy link
Copy Markdown
Member Author

Checked in review, in Chromium, against this branch's Keyboard.ts:

  • The open question on Escape is settled for landkeep's setup. With a real dialog web-component library (a popover element with a static aria-modal="true"), the dialog open, and focus dropped to <body>: Z, Space, and Escape all stayed with the page, and the dialog reported one close request with reason escape-key. The result was the same whether the game let the library close the dialog or cancelled the close and applied it from its own state.
  • Step 8's claim about a repeated Escape holds on a second Chromium build. With cancel always prevented on a native <dialog>, the first two Escapes left it open and the third closed it.

No changes requested.

@SandroMaglione
SandroMaglione merged commit c800b34 into main Nov 16, 2026
5 checks passed
@SandroMaglione
SandroMaglione deleted the browser/open-modal-owns-keys branch November 16, 2026 05:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant