@typeonce/ritmo-browser 0.23.0 → 0.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/Keyboard.ts CHANGED
@@ -28,13 +28,29 @@
28
28
  * down after that, or after a window blur, is pressed again at its next
29
29
  * auto-repeat.
30
30
  *
31
- * Keys typed into a form field are left to the field: a key that goes down
32
- * in an `<input>` (any type), `<textarea>`, `<select>`, or contenteditable
33
- * element presses no action and is not `preventDefault`-ed, so a name field
34
- * on the same page as the game receives "wasd" and the player does not move.
35
- * Releases are always processed, so a key held before focus moved into a
36
- * field still releases its action. With `window` as the host this needs no
37
- * setup.
31
+ * Keys the page is using are left to the page: a key that goes down in a
32
+ * form field (`<input>` of any type, `<textarea>`, `<select>`,
33
+ * contenteditable), or while a modal dialog is open (a `<dialog>` opened
34
+ * with `showModal()`, or a shown `aria-modal="true"` element), wherever
35
+ * focus is, or that a listener nearer the target already handled with
36
+ * `preventDefault()` (a menu's arrows, a slider's keys), and Enter, Space,
37
+ * and Tab on a control the player reached
38
+ * by keyboard (Tab to a button, link, tab, or any focusable element: the
39
+ * browser shows it with `:focus-visible`) press no action and are not
40
+ * `preventDefault`-ed. So a name field receives "wasd" and the player does
41
+ * not move, Enter and Space press a focused button, and Escape closes a
42
+ * modal `<dialog>`. Every other key on that focused button is still the
43
+ * game's: movement and hotkeys keep working after the player tabbed to a
44
+ * control. A control the player clicked with the mouse keeps focus but none
45
+ * of the keys: the game keeps playing, and Space does not press it again,
46
+ * with no `tabIndex = -1` or `blur()` in the game. A focused `<canvas>`, or
47
+ * the element passed as the host, is the game, not page UI: when a menu the
48
+ * player used by keyboard closes back into play, focus the canvas
49
+ * (`canvas.tabIndex = -1`, then `canvas.focus()`), or Enter and Space stay
50
+ * with the button the menu handed focus back to. Releases are always
51
+ * processed, so a key held before focus moved still releases its action.
52
+ * With `window` as the host this needs no setup; see {@link KeyEvent} for
53
+ * the exact rule.
38
54
  *
39
55
  * @module Keyboard
40
56
  * @docGroup browser
@@ -100,18 +116,67 @@ export type { Direction }
100
116
 
101
117
  /**
102
118
  * The subset of `KeyboardEvent` the module reads. `code` (the physical key),
103
- * the modifiers, and `target` (the element the key was typed into) are
104
- * optional so simple test hosts can omit them; browsers always provide them.
105
- * `ctrlKey` and `metaKey` mark a browser shortcut, which {@link actions}
106
- * leaves to the browser, and `altKey` tells AltGr (Ctrl and Alt together)
107
- * from Ctrl.
119
+ * the modifiers, `defaultPrevented`, and `target` (the focused element the
120
+ * key went down in) are optional so simple test hosts can omit them;
121
+ * browsers always provide them. `ctrlKey` and `metaKey` mark a browser
122
+ * shortcut, which {@link actions} leaves to the browser, and `altKey` tells
123
+ * AltGr (Ctrl and Alt together) from Ctrl.
108
124
  *
109
- * A target is a form field, whose key presses {@link actions} and
110
- * {@link presses} leave to it, when its `tagName` is `INPUT` (any type,
111
- * checkboxes and buttons included), `TEXTAREA`, or `SELECT`, or its
112
- * `isContentEditable` is `true`. It is read by shape, not `instanceof`, so
113
- * it works across iframes, and a test host types into a field by passing
114
- * `{ tagName: "INPUT" }` or `{ isContentEditable: true }`.
125
+ * {@link actions} leaves a key to the page when any of these holds:
126
+ *
127
+ * - `defaultPrevented` is `true` because a listener nearer the target (a
128
+ * roving-focus group's arrows, a custom slider, a menu) handled it, not
129
+ * because another `Keyboard.actions` on the same host did;
130
+ * - the target is a form field: its `tagName` is `INPUT` (any type,
131
+ * checkboxes and buttons included), `TEXTAREA`, or `SELECT`, or its
132
+ * `isContentEditable` is `true`;
133
+ * - a modal dialog is open, wherever focus is: `closest` from the target
134
+ * finds a `dialog:modal` (opened with `showModal()`) or an
135
+ * `[aria-modal="true"]` element, or the target's document (its
136
+ * `ownerDocument`, or the target itself when it has `querySelector`) holds
137
+ * a `dialog:modal`, or an `[aria-modal="true"]` element that is shown:
138
+ * its `checkVisibility({ visibilityProperty: true, opacityProperty: true })`
139
+ * returns `true`. So a menu keeps its keys after a redraw deleted the
140
+ * focused button and dropped focus to `<body>`, and Escape still closes
141
+ * it. An `aria-modal` element still in the page but closed (`hidden`,
142
+ * `display: none`, `visibility: hidden`, a closed popover, inside a closed
143
+ * `<dialog>`) leaves the keys with the game, and so does one fading out
144
+ * at `opacity: 0`: the player no longer sees the menu. A script that
145
+ * hides an `aria-modal` menu on a key calls `preventDefault()` on it (the
146
+ * first rule): it runs before a `window` host hears the key, and the menu
147
+ * it hid no longer counts. Not seen: a modal inside a shadow root (the
148
+ * target is then the shadow host, and the document query does not look
149
+ * inside it). A modal in another document (an iframe) is modal only
150
+ * there and leaves this host's keys alone;
151
+ * - the key is Enter, Space, or Tab (the keys a browser itself acts on for
152
+ * a focused control: press it, move focus on) and the target took focus
153
+ * by keyboard: it matched `:focus-visible` when its `focusin` reached the
154
+ * host, and it is not a `<canvas>` or the host itself (the game's own
155
+ * surface). Any other key on that control is the game's, as a page
156
+ * shortcut still works with a button focused, unless the control handled
157
+ * it (the first rule).
158
+ *
159
+ * {@link presses} offers a key the game asked for, usually from inside a
160
+ * settings dialog, so it skips only a form field's keys and Enter, Space,
161
+ * and Tab on a control reached by keyboard: an open modal dialog and a key a
162
+ * widget handled do not hide a press from it.
163
+ *
164
+ * Focus is judged when it arrives because browsers disagree later: Chromium
165
+ * turns `:focus-visible` on for a clicked button at the first key the player
166
+ * presses, so a check at keydown would hand Space back to a "Mute" button
167
+ * clicked minutes earlier. A focus a script moves (`element.focus()`) counts
168
+ * as by keyboard after the player last used the keyboard in Chromium and
169
+ * Safari, never in Firefox; a dialog's own focus is covered by the modal
170
+ * rule in all three.
171
+ *
172
+ * The target is read by shape, not `instanceof`, so it works across
173
+ * iframes, and a test host types into a field by passing
174
+ * `{ tagName: "INPUT" }` or `{ isContentEditable: true }`, focuses a
175
+ * control by keyboard by sending `focusin` with a target whose
176
+ * `matches(":focus-visible")` returns `true`, and opens a modal by giving
177
+ * the target an `ownerDocument` whose `querySelector("dialog:modal")`
178
+ * returns an element. A target without those members leaves the key with
179
+ * the game.
115
180
  */
116
181
  export interface KeyEvent {
117
182
  readonly key: string
@@ -120,22 +185,172 @@ export interface KeyEvent {
120
185
  readonly ctrlKey?: boolean
121
186
  readonly metaKey?: boolean
122
187
  readonly altKey?: boolean
188
+ readonly defaultPrevented?: boolean
123
189
  readonly target?: object | null
124
190
  preventDefault(): void
125
191
  }
126
192
 
193
+ /**
194
+ * The subset of the `focusin` event the module reads: the element that took
195
+ * focus, read by shape like {@link KeyEvent}'s target.
196
+ */
197
+ export interface FocusInEvent {
198
+ readonly target?: object | null
199
+ }
200
+
127
201
  /** Every action that is not in use shares this state, so a snapshot of an idle keyboard allocates no states. */
128
202
  const idleState: ActionState = { held: false, pressed: false, released: false }
129
203
 
130
204
  const editableTags: ReadonlySet<string> = new Set(["INPUT", "TEXTAREA", "SELECT"])
131
205
 
206
+ /** The members of an element the module reads, all optional: a test host passes plain objects. */
207
+ interface TargetShape {
208
+ readonly tagName?: unknown
209
+ readonly isContentEditable?: unknown
210
+ readonly matches?: unknown
211
+ readonly closest?: unknown
212
+ }
213
+
132
214
  /** Whether a key event's target is a form field, by the rule on {@link KeyEvent}. */
133
- const isEditableTarget = (target: object | null | undefined): boolean => {
134
- if (target === null || target === undefined) return false
135
- const { tagName, isContentEditable } = target as { readonly tagName?: unknown; readonly isContentEditable?: unknown }
215
+ const isEditableTarget = (target: object): boolean => {
216
+ const { tagName, isContentEditable } = target as TargetShape
136
217
  return isContentEditable === true || (typeof tagName === "string" && editableTags.has(tagName.toUpperCase()))
137
218
  }
138
219
 
220
+ /** `target.matches(selector)`, false for a target without it or a selector the browser does not know. */
221
+ const matchesSelector = (target: object, selector: string): boolean => {
222
+ const { matches } = target as TargetShape
223
+ if (typeof matches !== "function") return false
224
+ try {
225
+ return (matches as (selector: string) => unknown).call(target, selector) === true
226
+ } catch {
227
+ return false
228
+ }
229
+ }
230
+
231
+ /** Whether `target.closest(selector)` finds an element, false where it cannot ask. */
232
+ const hasAncestor = (target: object, selector: string): boolean => {
233
+ const { closest } = target as TargetShape
234
+ if (typeof closest !== "function") return false
235
+ try {
236
+ const found: unknown = (closest as (selector: string) => unknown).call(target, selector)
237
+ return found !== null && found !== undefined
238
+ } catch {
239
+ return false
240
+ }
241
+ }
242
+
243
+ /** Whether the target is inside an open modal dialog. `:modal` is asked of dialogs only, since a fullscreen element can match it too. */
244
+ const isInsideModal = (target: object): boolean =>
245
+ hasAncestor(target, "[aria-modal=\"true\"]") || hasAncestor(target, "dialog:modal")
246
+
247
+ /** The members of a document the module reads. */
248
+ interface DocumentShape {
249
+ readonly ownerDocument?: unknown
250
+ readonly querySelector?: unknown
251
+ readonly querySelectorAll?: unknown
252
+ }
253
+
254
+ /** The document a key went down in: the target's `ownerDocument`, or the target itself when it is one (it can query). */
255
+ const documentOf = (target: object): object | null => {
256
+ const { ownerDocument, querySelector } = target as DocumentShape
257
+ if (typeof ownerDocument === "object" && ownerDocument !== null) return ownerDocument
258
+ return typeof querySelector === "function" ? target : null
259
+ }
260
+
261
+ /**
262
+ * Whether an `aria-modal` element is shown. A closed one often stays in the
263
+ * page with its attribute (`hidden`, a closed popover, `display: none`), and
264
+ * one fading out at `opacity: 0` is gone for the player. An element that
265
+ * cannot answer is not shown.
266
+ */
267
+ const isShown = (element: unknown): boolean => {
268
+ if (typeof element !== "object" || element === null) return false
269
+ const { checkVisibility } = element as { readonly checkVisibility?: unknown }
270
+ if (typeof checkVisibility !== "function") return false
271
+ return (checkVisibility as (options: object) => unknown).call(element, { visibilityProperty: true, opacityProperty: true }) === true
272
+ }
273
+
274
+ /** Whether the document holds an open modal dialog, wherever focus is in it. */
275
+ const hasOpenModal = (document: object): boolean => {
276
+ const { querySelector, querySelectorAll } = document as DocumentShape
277
+ try {
278
+ if (typeof querySelector === "function") {
279
+ const dialog: unknown = (querySelector as (selector: string) => unknown).call(document, "dialog:modal")
280
+ if (dialog !== null && dialog !== undefined) return true
281
+ }
282
+ if (typeof querySelectorAll !== "function") return false
283
+ const elements: unknown = (querySelectorAll as (selector: string) => unknown).call(document, "[aria-modal=\"true\"]")
284
+ if (typeof elements !== "object" || elements === null || typeof (elements as { readonly length?: unknown }).length !== "number") return false
285
+ const list = elements as ArrayLike<unknown>
286
+ for (let index = 0; index < list.length; index++) if (isShown(list[index])) return true
287
+ return false
288
+ } catch {
289
+ return false
290
+ }
291
+ }
292
+
293
+ /** Whether a modal dialog is open for a key with this target, by the rule on {@link KeyEvent}. */
294
+ const isModalOpen = (target: object): boolean => {
295
+ if (isInsideModal(target)) return true
296
+ const document = documentOf(target)
297
+ return document !== null && hasOpenModal(document)
298
+ }
299
+
300
+ /**
301
+ * The key events a `Keyboard.actions` device prevented: another device on
302
+ * the same host sees them as `defaultPrevented`, and they are still the game's.
303
+ */
304
+ const preventedByKeyboard = new WeakSet()
305
+
306
+ /** The keys a browser itself acts on for a focused control: Enter and Space press it, Tab moves focus on. */
307
+ const isControlKey = (event: KeyEvent): boolean => event.key === "Enter" || event.key === " " || event.key === "Tab"
308
+
309
+ /** Which keys belong to the page on one host, by the rule on {@link KeyEvent}. */
310
+ interface PageKeys {
311
+ /** Whether {@link actions} leaves this key to the page. */
312
+ readonly owns: (event: KeyEvent) => boolean
313
+ /** Whether {@link presses} leaves this key to the page: a form field's keys, and a keyboard-focused control's own. */
314
+ readonly ownsWhileCapturing: (event: KeyEvent) => boolean
315
+ readonly dispose: () => void
316
+ }
317
+
318
+ /**
319
+ * Tracks which element took focus by keyboard on `host`, and answers
320
+ * whether a key belongs to the page by the rule on {@link KeyEvent}.
321
+ */
322
+ const pageKeys = (host: KeyboardHost): PageKeys => {
323
+ // The element that last took focus while it matched `:focus-visible`, read
324
+ // at `focusin` because Chromium turns it on for a clicked control at the next key.
325
+ let keyboardFocused: object | null = null
326
+ const onFocusIn = (event: FocusInEvent): void => {
327
+ const target = event.target ?? null
328
+ keyboardFocused = target !== null && matchesSelector(target, ":focus-visible") ? target : null
329
+ }
330
+ host.addEventListener("focusin", onFocusIn)
331
+ const isGameSurface = (target: object): boolean => {
332
+ const { tagName } = target as TargetShape
333
+ return target === host || (typeof tagName === "string" && tagName.toUpperCase() === "CANVAS")
334
+ }
335
+ const isControlPress = (event: KeyEvent, target: object): boolean =>
336
+ target === keyboardFocused && isControlKey(event) && !isGameSurface(target)
337
+ return {
338
+ owns(event) {
339
+ if (event.defaultPrevented === true && !preventedByKeyboard.has(event)) return true
340
+ const target = event.target ?? null
341
+ if (target === null) return false
342
+ return isEditableTarget(target) || isControlPress(event, target) || isModalOpen(target)
343
+ },
344
+ ownsWhileCapturing(event) {
345
+ const target = event.target ?? null
346
+ return target !== null && (isEditableTarget(target) || isControlPress(event, target))
347
+ },
348
+ dispose() {
349
+ host.removeEventListener("focusin", onFocusIn)
350
+ }
351
+ }
352
+ }
353
+
139
354
  const modifierKeys: ReadonlySet<string> = new Set(["Shift", "Control", "Alt", "AltGraph", "Meta"])
140
355
  const modifierCodes: ReadonlySet<string> = new Set(["ShiftLeft", "ShiftRight", "ControlLeft", "ControlRight", "AltLeft", "AltRight", "MetaLeft", "MetaRight"])
141
356
 
@@ -150,12 +365,16 @@ const isShortcut = (event: KeyEvent): boolean =>
150
365
  const isMeta = (event: KeyEvent): boolean => event.key === "Meta" || event.code === "MetaLeft" || event.code === "MetaRight"
151
366
 
152
367
  /**
153
- * The event target the module listens on, usually `window`.
368
+ * The event target the module listens on, usually `window`. `focusin` tells
369
+ * which control the player reached by keyboard (see {@link KeyEvent}); a
370
+ * test host that never sends it has no such control.
154
371
  */
155
372
  export interface KeyboardHost {
156
373
  addEventListener(type: "keydown" | "keyup", listener: (event: KeyEvent) => void): void
374
+ addEventListener(type: "focusin", listener: (event: FocusInEvent) => void): void
157
375
  addEventListener(type: "blur", listener: () => void): void
158
376
  removeEventListener(type: "keydown" | "keyup", listener: (event: KeyEvent) => void): void
377
+ removeEventListener(type: "focusin", listener: (event: FocusInEvent) => void): void
159
378
  removeEventListener(type: "blur", listener: () => void): void
160
379
  }
161
380
 
@@ -300,7 +519,10 @@ export interface Actions<B extends Bindings> extends System.Consumes<"snapshot">
300
519
  export interface ActionsOptions {
301
520
  /**
302
521
  * Call `preventDefault()` for bound keys, so arrows and space do not scroll
303
- * the page. Defaults to `true`.
522
+ * the page and a button clicked with the mouse, which keeps focus, is not
523
+ * pressed again by Space or Enter. Defaults to `true`. With `false`, every
524
+ * key the game takes also does what the page does with it (Space presses
525
+ * that clicked button and scrolls); which keys the game takes does not change.
304
526
  */
305
527
  readonly preventDefault?: boolean
306
528
  }
@@ -373,11 +595,18 @@ const shortcutModifierTokens = [
373
595
 
374
596
  /**
375
597
  * Starts tracking bound keys on `host`, usually `window`, until `dispose()`.
376
- * When the window loses focus every held action is released. A key pressed
377
- * in a form field (see {@link KeyEvent}) is left to the field, and a browser
378
- * shortcut (a key pressed with Cmd or Ctrl, unless the bindings use Control
379
- * or Meta) to the browser: it presses no action and is not
380
- * `preventDefault`-ed. Each call is
598
+ * When the window loses focus every held action is released. A key the page
599
+ * is using (a form field, an open modal dialog, a key a widget already
600
+ * handled, Enter, Space, and Tab on a control reached by keyboard; see
601
+ * {@link KeyEvent}) is left to
602
+ * the page, and a browser shortcut (a key pressed with Cmd or Ctrl, unless
603
+ * the bindings use Control or Meta) to the browser: it presses no action and
604
+ * is not `preventDefault`-ed. Use it for every key the host reacts to,
605
+ * one-shot keys too (pause on Escape, mute on M: read their `pressed` edge
606
+ * in the snapshot), instead of a `keydown` listener on `window` that calls
607
+ * `preventDefault()` and so takes Enter and Space from a focused button.
608
+ * Binding Tab keeps a keyboard player from moving focus to the page's
609
+ * controls, so a page with controls leaves it unbound. Each call is
381
610
  * its own device: build one per source (one `Controls` merge, one player
382
611
  * of a pool). Use {@link scripted} for tests and headless runs, and
383
612
  * {@link presses} to capture an unbound key on a settings screen.
@@ -408,6 +637,7 @@ export const actions = <const B extends Bindings>(
408
637
  leavesShortcuts = !shortcutModifierTokens.some((token) => actionsByToken.has(token))
409
638
  }
410
639
  index()
640
+ const page = pageKeys(host)
411
641
 
412
642
  /**
413
643
  * Each held token and the actions it holds: those bound to it when it went
@@ -464,9 +694,12 @@ export const actions = <const B extends Bindings>(
464
694
  }
465
695
  tokens.push(codeToken(event.code))
466
696
  }
467
- // Typed into a form field, the key belongs to the field; a shortcut
468
- // belongs to the browser. Their releases are still processed by `onKeyUp`.
469
- if (isEditableTarget(event.target) || (leavesShortcuts && isShortcut(event))) return
697
+ // A key bound to no action presses nothing and is not prevented, so the
698
+ // page's rule (which may query the document) is not asked for it.
699
+ if (!tokens.some((token) => actionsByToken.has(token))) return
700
+ // A key the page is using belongs to the page; a shortcut belongs to the
701
+ // browser. Their releases are still processed by `onKeyUp`.
702
+ if (page.owns(event) || (leavesShortcuts && isShortcut(event))) return
470
703
  let handled = false
471
704
  for (const token of tokens) {
472
705
  const bound = actionsByToken.get(token)
@@ -483,11 +716,14 @@ export const actions = <const B extends Bindings>(
483
716
  heldTokens.set(token, new Set(bound))
484
717
  for (const name of bound) pressed.add(name)
485
718
  }
486
- if (handled && preventDefault) event.preventDefault()
719
+ if (handled && preventDefault) {
720
+ event.preventDefault()
721
+ preventedByKeyboard.add(event)
722
+ }
487
723
  }
488
724
 
489
- // Releases are processed wherever the key was released, form fields
490
- // included, so a key held before focus moved into a field still releases.
725
+ // Releases are processed wherever the key was released, form fields and
726
+ // focused controls included, so a key held before focus moved still releases.
491
727
  const onKeyUp = (event: KeyEvent): void => {
492
728
  const character = event.code === undefined ? keyToken(event.key) : keyTokenByCode.get(event.code) ?? keyToken(event.key)
493
729
  if (event.code === undefined || !codesByToken.has(character)) release(character)
@@ -556,6 +792,7 @@ export const actions = <const B extends Bindings>(
556
792
  host.removeEventListener("keydown", onKeyDown)
557
793
  host.removeEventListener("keyup", onKeyUp)
558
794
  host.removeEventListener("blur", onBlur)
795
+ page.dispose()
559
796
  }
560
797
  }
561
798
  return live
@@ -573,7 +810,7 @@ export interface KeyPress {
573
810
  export interface Presses extends System.Consumes<"snapshot"> {
574
811
  /** The keys that went down since the previous snapshot, in order, without auto-repeats. */
575
812
  snapshot(): ReadonlyArray<KeyPress>
576
- /** Removes the event listener. */
813
+ /** Removes the event listeners. */
577
814
  dispose(): void
578
815
  }
579
816
 
@@ -581,9 +818,14 @@ export interface Presses extends System.Consumes<"snapshot"> {
581
818
  * Starts collecting every key press on `host`, whatever the bindings, for a
582
819
  * settings screen that waits for the key to bind. Use {@link actions} for
583
820
  * gameplay. It never calls `preventDefault()`, and skips keys pressed in a
584
- * form field (see {@link KeyEvent}) and browser shortcuts (a key pressed with
585
- * Cmd or Ctrl), so Ctrl+R on the settings screen binds nothing; Control and
586
- * Meta pressed alone are offered.
821
+ * form field, Enter, Space, and Tab on a control reached by keyboard (see
822
+ * {@link KeyEvent}), and browser shortcuts (a key pressed with Cmd or Ctrl),
823
+ * so Ctrl+R on the settings screen binds nothing; Control and Meta pressed
824
+ * alone are offered. Unlike {@link actions} it still offers a key pressed
825
+ * inside an open modal dialog or one a widget handled, since the screen that
826
+ * waits for a key is usually a dialog. For "press any key" on a title or a
827
+ * cutscene, it is the host's listener: it leaves Enter on a button reached
828
+ * by keyboard to the button.
587
829
  *
588
830
  * @example
589
831
  * ```ts
@@ -601,8 +843,9 @@ export interface Presses extends System.Consumes<"snapshot"> {
601
843
  */
602
844
  export const presses = (host: KeyboardHost): Presses => {
603
845
  let pending: Array<KeyPress> = []
846
+ const page = pageKeys(host)
604
847
  const onKeyDown = (event: KeyEvent): void => {
605
- if (event.repeat || isEditableTarget(event.target) || isShortcut(event)) return
848
+ if (event.repeat || page.ownsWhileCapturing(event) || isShortcut(event)) return
606
849
  pending.push({ key: event.key, code: event.code ?? null })
607
850
  }
608
851
  host.addEventListener("keydown", onKeyDown)
@@ -614,6 +857,7 @@ export const presses = (host: KeyboardHost): Presses => {
614
857
  },
615
858
  dispose() {
616
859
  host.removeEventListener("keydown", onKeyDown)
860
+ page.dispose()
617
861
  }
618
862
  }
619
863
  }
package/src/Touch.ts CHANGED
@@ -43,6 +43,12 @@
43
43
  * press opens is cancelled while a tracked finger is down. `dispose()`
44
44
  * restores the styles.
45
45
  *
46
+ * While attached, the target also carries a function that returns the
47
+ * layout at its current size, under `Symbol.for("@typeonce/ritmo-browser/Touch.layout")`:
48
+ * `ritmo-devtools layout` reads it to check the buttons the canvas does not
49
+ * show to the page (too small to tap, under the notch, under a panel).
50
+ * `dispose()` removes it.
51
+ *
46
52
  * @module Touch
47
53
  * @docGroup browser
48
54
  *
@@ -77,6 +83,9 @@ import { anyUsed } from "./internal/used.ts"
77
83
  import type { ActionState } from "./internal/state.ts"
78
84
  import type { Vector } from "./internal/vectors.ts"
79
85
 
86
+ /** Where `ritmo-devtools layout` reads the layout of an attached target (see the module header). */
87
+ const layoutKey = Symbol.for("@typeonce/ritmo-browser/Touch.layout")
88
+
80
89
  /** A position in CSS pixels relative to the element's top-left corner. */
81
90
  export interface Position {
82
91
  readonly x: number
@@ -551,6 +560,7 @@ export const actions = <const B extends string, const V extends string = never,
551
560
  const style = target.style
552
561
  const previousStyles = style === undefined ? [] : noBrowserGestures.map((property) => [property, style.getPropertyValue(property)] as const)
553
562
  for (const property of noBrowserGestures) style?.setProperty(property, "none")
563
+ Reflect.set(target, layoutKey, () => layout(sizeOf()))
554
564
  target.addEventListener("pointerdown", onDown)
555
565
  target.addEventListener("pointermove", onMove)
556
566
  target.addEventListener("pointerup", onUp)
@@ -610,6 +620,7 @@ export const actions = <const B extends string, const V extends string = never,
610
620
  blurHost.removeEventListener("blur", onBlur)
611
621
  // An empty value removes the property, so a style the element did not have is not left behind.
612
622
  for (const [property, value] of previousStyles) style?.setProperty(property, value)
623
+ Reflect.deleteProperty(target, layoutKey)
613
624
  }
614
625
  }
615
626
  }