Repository navigation
An open modal owns the keys wherever focus is; playbook steps for DOM controls and menus - #232
Merged
Merged
Conversation
… 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>
Member
Author
|
Checked in review, in Chromium, against this branch's
No changes requested. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What was wrong
In 0.24,
Keyboard.actionsleft a key to the page only whenclosest(...)from the key's target found adialog:modalor 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.0in Chromium 141, with a<dialog>opened byshowModal()and thendocument.activeElement.blur():pauseaction and waspreventDefault-ed, so the dialog stayed open and fired noclose. Without the keyboard, Escape with focus on<body>closes the dialog.The same thing happens with a
popover="manual"element that carries a staticaria-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
closestis still asked first. Then the key's document is asked: the target'sownerDocument, or the target itself when it hasquerySelector. A modal is open when the document holds:dialog:modal, or[aria-modal="true"]element whosecheckVisibility({ visibilityProperty: true, opacityProperty: true })returnstrue.Details:
aria-modalelement that ishidden,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.opacity: 0also leaves the keys with the game. The menu is visually gone, and the JSDoc says so.instanceof. Queries run intry/catchand nothing is cached. A target that cannot answer (noownerDocument, nocheckVisibility, a query that throws) keeps today's behaviour, so plain-object test hosts are unchanged.Keyboard.pressesis unchanged: a settings dialog still hears the key to bind.The
KeyEventJSDoc, 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
defaultPreventedaswindowsaw each of the three keys.<dialog><dialog>close)<dialog><body>aria-modal<body><dialog><dialog>close)<dialog><body>close)aria-modalaria-modalaria-modal<body>The last row. That page's own Escape listener (on
document) hides the popover without preventing the key. It runs beforewindowhears the key, so by then no modal is open and the game getspause. With the listener callingpreventDefault(), 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-modalelements left in the page, with Space pressed and focus on<body>:hiddenattributedisplay: nonevisibility: hiddenopacity: 0(fading out)<dialog>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>:aria-modalaria-modal(closed or shown)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.mdgains steps 7 and 8. Step 6, the import-direction lint, keeps its number becauseritmo-polishandPOLISH.mdcite it.showModal()comes first; anaria-modalelement must move focus in, keep it there, and make the page inert itself. The menu's own keys listen on it.cancelandcloseare intents, because the browser closes a dialog on a repeated Escape even whencancelis prevented. A splash or wipe over it is apopover="manual"; a layer the player presses is its own modal dialog.The facts behind step 8 were checked in Chromium 141:
cancelprevented, the third Escape closed the dialog anyway.popover="manual"shown over a modal dialog is drawn above it but is inert:focus()is refused and a click doesn't land.The Check line is unchanged; the keyboard walk that will give it something to check comes in a follow-up.
Not covered
closest; no audited game uses shadow DOM. Stated in theKeyEventJSDoc.dialog:modalandcheckVisibilitywith 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