@botiverse/porthole 0.15.3 → 0.16.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.
Files changed (107) hide show
  1. package/CHANGELOG.md +58 -0
  2. package/dist/bridge/bridge.d.ts +1 -8
  3. package/dist/bridge/bridge.js +0 -7
  4. package/dist/check/page-source.js +1 -1
  5. package/dist/check/page.js +1 -1
  6. package/dist/compile/policy.d.ts +0 -7
  7. package/dist/compile/policy.js +1 -10
  8. package/dist/config/capabilities.d.ts +8 -14
  9. package/dist/config/capabilities.js +4 -5
  10. package/dist/config/schema.d.ts +2 -13
  11. package/dist/config/validate.js +0 -24
  12. package/dist/conformance/behavior.js +26 -37
  13. package/dist/conformance/clipboard.js +47 -1
  14. package/dist/conformance/harness-source.js +1 -1
  15. package/dist/displays/displays.js +1 -3
  16. package/dist/guide/limits.js +1 -1
  17. package/dist/guide/runtime.js +1 -1
  18. package/dist/host/create-host.d.ts +1 -1
  19. package/dist/host/create-host.js +6 -51
  20. package/dist/host/door.d.ts +1 -1
  21. package/dist/host/locate.d.ts +1 -1
  22. package/dist/host/locate.js +2 -2
  23. package/dist/host/outcome.d.ts +5 -12
  24. package/dist/host/outcome.js +8 -16
  25. package/dist/host/types.d.ts +6 -22
  26. package/dist/index.d.ts +2 -4
  27. package/dist/index.js +2 -4
  28. package/dist/isolation/served.d.ts +4 -14
  29. package/dist/isolation/served.js +7 -28
  30. package/dist/isolation/types.d.ts +2 -25
  31. package/dist/isolation/types.js +0 -23
  32. package/dist/platform/focus-field.d.ts +11 -0
  33. package/dist/platform/focus-field.js +18 -0
  34. package/dist/platform/types.d.ts +6 -22
  35. package/dist/platform/web.js +8 -106
  36. package/dist/presets/presets.d.ts +0 -2
  37. package/dist/presets/presets.js +0 -1
  38. package/dist/react/frame.d.ts +0 -8
  39. package/dist/react/frame.js +0 -4
  40. package/dist/runtime/contract.d.ts +2 -2
  41. package/dist/runtime/contract.js +2 -2
  42. package/dist/runtime/types.generated.js +6 -6
  43. package/dist/server/files.js +7 -23
  44. package/dist/server/host.d.ts +1 -1
  45. package/dist/server/index.d.ts +1 -1
  46. package/dist/server/index.js +4 -6
  47. package/dist/server/naming.js +1 -1
  48. package/dist/server/server.js +28 -166
  49. package/dist/server/types.d.ts +7 -7
  50. package/dist/shell/plan.d.ts +0 -5
  51. package/dist/shell/plan.js +2 -4
  52. package/dist/shell/runtime.js +1 -268
  53. package/docs/ADOPTING.md +42 -138
  54. package/docs/ARCHITECTURE.md +0 -33
  55. package/docs/DECISIONS.md +115 -10
  56. package/docs/DESIGN.md +27 -64
  57. package/docs/THREAT_MODEL.md +128 -255
  58. package/package.json +1 -1
  59. package/src/bridge/bridge.ts +1 -17
  60. package/src/check/page.ts +1 -1
  61. package/src/compile/policy.ts +1 -11
  62. package/src/config/capabilities.ts +8 -14
  63. package/src/config/schema.ts +2 -13
  64. package/src/config/validate.ts +0 -28
  65. package/src/conformance/behavior.ts +50 -52
  66. package/src/conformance/clipboard.ts +56 -1
  67. package/src/displays/displays.ts +1 -3
  68. package/src/guide/limits.ts +1 -1
  69. package/src/guide/runtime.ts +1 -1
  70. package/src/host/create-host.ts +6 -52
  71. package/src/host/door.ts +1 -1
  72. package/src/host/locate.ts +2 -2
  73. package/src/host/outcome.ts +8 -21
  74. package/src/host/types.ts +6 -20
  75. package/src/index.ts +2 -4
  76. package/src/isolation/served.ts +6 -34
  77. package/src/isolation/types.ts +2 -31
  78. package/src/platform/focus-field.ts +18 -0
  79. package/src/platform/types.ts +6 -21
  80. package/src/platform/web.ts +8 -129
  81. package/src/presets/presets.ts +0 -3
  82. package/src/react/frame.tsx +0 -10
  83. package/src/runtime/contract.ts +4 -4
  84. package/src/runtime/types.generated.ts +6 -6
  85. package/src/server/files.ts +4 -19
  86. package/src/server/host.ts +1 -1
  87. package/src/server/index.ts +4 -16
  88. package/src/server/naming.ts +1 -1
  89. package/src/server/server.ts +29 -189
  90. package/src/server/types.ts +7 -7
  91. package/src/shell/plan.ts +2 -9
  92. package/src/shell/runtime.ts +1 -268
  93. package/types/runtime/v1/artifact.d.ts +2 -3
  94. package/types/runtime/v1/assets.d.ts +1 -1
  95. package/types/runtime/v1/chat.d.ts +2 -2
  96. package/types/runtime/v1/comments.d.ts +1 -1
  97. package/types/runtime/v1/downloads.d.ts +2 -2
  98. package/types/runtime/v1/links.d.ts +2 -2
  99. package/dist/platform/focus-guard.d.ts +0 -288
  100. package/dist/platform/focus-guard.js +0 -838
  101. package/dist/server/nested.d.ts +0 -66
  102. package/dist/server/nested.js +0 -121
  103. package/dist/shell/frame.d.ts +0 -28
  104. package/dist/shell/frame.js +0 -407
  105. package/src/platform/focus-guard.ts +0 -1114
  106. package/src/server/nested.ts +0 -157
  107. package/src/shell/frame.ts +0 -444
@@ -1,1114 +0,0 @@
1
- /**
2
- * The focus guard (P109): a display's frame can move the keyboard into itself whenever it likes
3
- * (`element.focus()` in its own realm; on Chromium and WebKit with no gesture at all), and what the
4
- * person goes on typing into the host's composer or chat box then goes to the page. Porthole can't
5
- * stop the call, which runs in the content's realm, but the host's page can undo it: when focus
6
- * leaves one of its text fields for a display's frame and the person didn't move it there, focus
7
- * goes back once the engine has finished moving it, the guard watches that it stays back, and the
8
- * display hears `focusTaken`; a display whose frame keeps doing it is stopped (`createHost`).
9
- *
10
- * What the host's page can see of a move into a frame, measured on Chromium, WebKit and Firefox
11
- * (P109): Chromium and WebKit blur the host's window as it happens, and a press on the frame (a
12
- * click, a tap, held or not) leaves the frame element `:active` then; a Tab is the host's own
13
- * keydown just before. Firefox doesn't blur the window and shows no `:active` (a focusout on the
14
- * field was seen in one review's runs, not in another's): its `document.activeElement` changes,
15
- * which the guard reads at each animation frame while a frame is guarded, and the pointer over the
16
- * frame (`:hover`, `pointerover`) is all it can tell of a press. A page that takes focus back on
17
- * its own blur (which a take-back fires) leaves Firefox's focus on nothing (`<body>`) or in the
18
- * frame again (the review of the guard, GK-1): the guard keeps watching after each take-back and
19
- * counts one that didn't hold. Every engine keeps a gesture's transient activation for 5 s
20
- * (measured: 5.04 to 5.10 s).
21
- *
22
- * A nested page's shell (P111) says when its activation turned on, which a press in the page does,
23
- * and so does a key the person typed into it: one meant for the host's composer, after the page took
24
- * the keyboard and before the guard took it back (the audit of P111's guard, NG-1). Neither the
25
- * shell nor the host's page can tell the two apart from the activation (the shell gets no event as
26
- * focus comes into its child, measured), so (P120): in a fight over a text field the shell's word
27
- * isn't asked; a wait on a move from a text field doesn't end with the frame holding focus unjudged;
28
- * and where the host's page sees the pointer over its frames, an activation while it isn't over the
29
- * frame and the person was typing is no press.
30
- */
31
-
32
- /** How long the person's Tab counts as moving focus (the move follows its keydown at once). */
33
- export const TAB_MS = 1_000;
34
-
35
- /**
36
- * How long transient activation lasts after a gesture (measured: 5 s on all three engines): a
37
- * host page with activation and no gesture of its own for longer had one in a frame.
38
- */
39
- export const ACTIVATION_SPAN_MS = 5_000;
40
-
41
- /** The person is typing: a key on the host's page within this long. */
42
- export const TYPING_MS = 1_000;
43
-
44
- /**
45
- * No press of the person's lands on a frame this soon after a key they typed on the host's page
46
- * (P122): a hand on the keys doesn't reach the pointer and press that fast (the Keystroke-Level
47
- * Model gives 400 ms to the hand's move from the keys to the mouse alone; Card, Moran and Newell,
48
- * 1980). A move into a nested page's frame, or its shell's activation turning on, within this long
49
- * is the person's next key landing in the page, which turns its activation on as a press does.
50
- * Where neither the host's page nor the shell sees the pointer (full Chromium), it holds a page that
51
- * takes the keyboard while the person types even when their key outruns the shell's answer.
52
- */
53
- export const KEY_PRESS_MS = 250;
54
-
55
- /**
56
- * After a take-back, the guard keeps watching (each animation frame) until focus has stayed in the
57
- * text field this long: a page that takes it again at once (on its own blur, which the take-back
58
- * fires) is caught as it does, on Firefox too (P109, after the review of the guard: GK-1).
59
- */
60
- export const HELD_MS = 300;
61
-
62
- /** A take-back that hasn't put focus back in the field after this long failed: counted, and tried again. */
63
- export const GIVE_BACK_MS = 50;
64
-
65
- /**
66
- * A frame that holds focus isn't the person's for this long after they press the host's page: the
67
- * press gives the page activation before focus leaves the frame (on Firefox, a move between
68
- * processes), and a call the frame sends in between would borrow it.
69
- */
70
- export const HOST_PRESS_MS = 1_000;
71
-
72
- /**
73
- * When a display is stopped for taking the keyboard (P109): focus given back can't stop its frame
74
- * calling `focus()` again (nothing the host sets on the frame does, `inert` included: measured),
75
- * and each try leaves it the keys typed until focus is back. So three undone moves within 10 s
76
- * that came while the person typed on the page or that kept focus from going back (a take-back that
77
- * failed: the keys then go to the frame, and the page sees no typing to count), or five at all
78
- * within 2 s, stop it. A person's own move never fails a take-back.
79
- */
80
- export const TAKES = {
81
- typing: { most: 3, withinMs: 10_000 },
82
- any: { most: 5, withinMs: 2_000 },
83
- } as const;
84
-
85
- /**
86
- * A nested page's shell (P111) says its own activation turned on: a press or key of the person's
87
- * in that page (activation goes up to ancestors, never down, so nothing on the host's page turns
88
- * it on). A move of focus into the frame within this long of it, with no press or key on the
89
- * host's page since, is the person's; so is a `comments.open` the page sends within it.
90
- */
91
- export const SHELL_GESTURE_MS = 1_000;
92
-
93
- /**
94
- * How long a move into a nested page's frame waits for its shell's word before it is taken for
95
- * the page's: the shell says what it saw at its next animation frame, after the host's page
96
- * already heard the move. A shell that says nothing in time (gone, stalled) has its frame's move
97
- * taken back, as any page's.
98
- */
99
- export const SHELL_WAIT_MS = 500;
100
-
101
- /**
102
- * A shell's word that came this long before the host's page heard the move is about that move
103
- * (the shell's frame can come first); one from before then is about an earlier one.
104
- */
105
- export const SHELL_EARLY_MS = 150;
106
-
107
- /**
108
- * A shell that went this long without a look, or without a word to the host (its heartbeat is every
109
- * 50 ms), was stalled (P111, after its review): where the page shares the shell's thread (WebKit,
110
- * Firefox), a page that holds it from its own click handler pushes the moment the shell sees its
111
- * activation turn on past the person's next keys on the host's page. An activation it saw then is
112
- * uncertain: it is no one's gesture until it lapses.
113
- */
114
- export const SHELL_STALL_MS = 100;
115
-
116
- /**
117
- * A press a nested page's runtime told its shell (P148) within this long after the shell was seen
118
- * to have stalled is no one's. The shell notes a press when it hears it, and a page that holds the
119
- * thread it shares with its shell makes that late, by as long as it likes: when the page lets go,
120
- * what waited behind it runs at once, the shell's own look among it, which may come first and say
121
- * the stall, the press following a moment later as if it were new.
122
- */
123
- export const SHELL_AFTER_STALL_MS = 500;
124
-
125
- /** What a nested page's shell last said (P111), on the host's clock. */
126
- export interface ShellWord {
127
- /** Whether its engine tells activation at all (`navigator.userActivation`). */
128
- readonly supported: boolean;
129
- /** When its activation last turned on; -Infinity if it hasn't, or is off. */
130
- readonly activatedAt: number;
131
- /** Whether it last said the page's focus is in it, and when it last said focus came in. */
132
- readonly focused: boolean;
133
- readonly focusedAt: number;
134
- /** Its activation turned on while it was stalled: uncertain until it goes off (`SHELL_STALL_MS`). */
135
- readonly uncertain?: boolean;
136
- /**
137
- * Its activation turned on within `TYPING_MS` of the person's typing on the host's page, the
138
- * pointer not come over the frame since (`pressPossible`, judged as it turned on): where the
139
- * host's page sees the pointer, their key landing in the page, no press (P120).
140
- */
141
- readonly keyed?: boolean;
142
- /**
143
- * When it last heard a real press from its page's runtime (P148); -Infinity, or absent, if it
144
- * heard none, or the one it heard is uncertain (judged as an activation that turned on is).
145
- */
146
- readonly pressedAt?: number;
147
- /** How many presses it said it had heard, the last time it spoke: more is a new one. */
148
- readonly presses?: number;
149
- /** `keyed`, for the press at `pressedAt`: judged as the shell told it. */
150
- readonly pressKeyed?: boolean;
151
- }
152
-
153
- /** One move of the keyboard the guard undid. */
154
- export interface FocusTake {
155
- /** The person pressed a key on the host's page within the last second. */
156
- readonly typing: boolean;
157
- /**
158
- * Focus didn't stay back in the field: the frame kept it, took it again within `HELD_MS`, or it
159
- * landed nowhere.
160
- */
161
- readonly failed: boolean;
162
- }
163
-
164
- /** What the host's page knew when focus left one of its text fields for a display's frame. */
165
- export interface FocusMove {
166
- readonly now: number;
167
- /** The engine told the host's page as it happened (its window blurred): Chromium, WebKit. */
168
- readonly seen: boolean;
169
- /** The frame element is `:active`: a press on it, pointer or touch (Chromium, WebKit). */
170
- readonly pressed: boolean;
171
- /** The pointer is over the frame element (`:hover`). */
172
- readonly over: boolean;
173
- /** When the pointer last came over the frame element (`pointerover`); -Infinity if never. */
174
- readonly overSince: number;
175
- /** The person's last key on the host's page, and when. */
176
- readonly lastKey: { readonly key: string; readonly at: number } | null;
177
- /** When the person last typed on the host's page (a key other than Tab and the modifiers). */
178
- readonly typedAt: number;
179
- /** When the text field focus left got it. */
180
- readonly focusedAt: number;
181
- /** When the host's page last saw a gesture of its own (a key, a press, a click, typed text). */
182
- readonly gestureAt: number;
183
- /** Whether the host's page has transient activation now; undefined where it can't tell. */
184
- readonly activation: boolean | undefined;
185
- /** The host moved focus into the frame itself (`DisplayHandle.focus()`), just now. */
186
- readonly hostMoved: boolean;
187
- /**
188
- * A nested page's frame (P111): what its shell said, and when the host's page last had a
189
- * trusted press or key of its own. Absent for any other frame.
190
- */
191
- readonly shell?: {
192
- readonly word: ShellWord;
193
- readonly hostInputAt: number;
194
- /** The host's page sees the pointer over its frames on this engine (`pressPossible`, P120). */
195
- readonly pointerShown?: boolean;
196
- };
197
- }
198
-
199
- /**
200
- * Whether the person moved focus into the frame themselves:
201
- * - the host did (`DisplayHandle.focus()`);
202
- * - by the keyboard: their last key on the host's page was Tab (or Shift+Tab), just now;
203
- * - by a press on the frame: where the engine tells the move as it happens (Chromium, WebKit),
204
- * the frame element is `:active`; where it doesn't (Firefox), the pointer is over the frame and
205
- * came over it after the text field got focus and after the person last typed in the host's page
206
- * (a page can't move the pointer; a composer that opened beside the frame while the pointer
207
- * rested over it, and a person typing with it there, keep their keys);
208
- * - by a gesture the host's own events don't explain: the host's page has transient activation,
209
- * and for longer than activation lasts it saw no gesture of its own and the text field has had
210
- * focus, so the person pressed or activated something in a frame since (an assistive
211
- * technology's activation, which moves no pointer and sends the host no key, is one). The
212
- * gesture that opened a composer (a selection in the frame, `selected`) is older than the
213
- * composer's focus, and doesn't count.
214
- * Anything else is the page's: focus goes back.
215
- */
216
- export function personMoved(move: FocusMove): boolean {
217
- if (move.hostMoved) {
218
- return true;
219
- }
220
- if (move.lastKey !== null && move.lastKey.key === "Tab" && move.now - move.lastKey.at <= TAB_MS) {
221
- return true;
222
- }
223
- // A nested page (P111): its shell's activation turned on within the last second, and the host's
224
- // page had no press or key of its own since (the person went back to it), where it may have been
225
- // a press (P120) and not within `KEY_PRESS_MS` of the person's last key (P122); or, where the
226
- // engine tells it, a press on the frame. Nothing else: no pointer over it, no host-wide
227
- // activation.
228
- if (move.shell !== undefined && move.shell.word.supported) {
229
- return (
230
- (move.seen && move.pressed) ||
231
- (move.now - move.typedAt >= KEY_PRESS_MS &&
232
- shellSaw(
233
- move.shell.word,
234
- move.shell.hostInputAt,
235
- move.now,
236
- move.shell.pointerShown === true,
237
- ))
238
- );
239
- }
240
- if (
241
- move.seen ? move.pressed : move.over && move.overSince > Math.max(move.typedAt, move.focusedAt)
242
- ) {
243
- return true;
244
- }
245
- return (
246
- move.activation === true &&
247
- move.now - Math.max(move.gestureAt, move.focusedAt) > ACTIVATION_SPAN_MS
248
- );
249
- }
250
-
251
- /**
252
- * Whether a nested page's shell saw the person's gesture just now (P111): its activation turned on
253
- * within `SHELL_GESTURE_MS`, after the host's page's last trusted press or key.
254
- */
255
- export function shellGesture(word: ShellWord, hostInputAt: number, now: number): boolean {
256
- return (
257
- word.supported &&
258
- now - word.activatedAt <= SHELL_GESTURE_MS &&
259
- now >= word.activatedAt &&
260
- hostInputAt < word.activatedAt
261
- );
262
- }
263
-
264
- /**
265
- * Whether a nested page's runtime told its shell a real press just now (P148): the shell heard it
266
- * within `SHELL_GESTURE_MS`, after the host's page's last trusted press or key. What the shell's
267
- * activation can't say: a press while it is already on (within 5 s of the last gesture).
268
- */
269
- export function shellPress(word: ShellWord, hostInputAt: number, now: number): boolean {
270
- const pressedAt = word.pressedAt ?? -Infinity;
271
- return (
272
- word.supported &&
273
- now - pressedAt <= SHELL_GESTURE_MS &&
274
- now >= pressedAt &&
275
- hostInputAt < pressedAt
276
- );
277
- }
278
-
279
- /**
280
- * Whether a nested page's shell saw the person's gesture just now, either way: its activation
281
- * turned on (`shellGesture`, P111), or its page's runtime told it a press (`shellPress`, P148);
282
- * each only where a press could have made it (P120: `shown`, the host's page sees the pointer over
283
- * its frames, and the word is `keyed`, the person's key landing in the page).
284
- */
285
- export function shellSaw(
286
- word: ShellWord,
287
- hostInputAt: number,
288
- now: number,
289
- shown: boolean,
290
- ): boolean {
291
- return (
292
- (shellGesture(word, hostInputAt, now) && !(shown && word.keyed === true)) ||
293
- (shellPress(word, hostInputAt, now) && !(shown && word.pressKeyed === true))
294
- );
295
- }
296
-
297
- /**
298
- * Whether the person could have pressed the frame just before `at` (P120): a nested page's shell
299
- * says its activation turned on, which a key typed into the page does as well as a press. Where the
300
- * host's page sees the pointer over its frames (`shown`: Firefox; Chromium and WebKit where the frame
301
- * is in their process, not full Chromium), a press needs the pointer over the frame, come over it
302
- * since the person last typed on the host's page; within `TYPING_MS` of that typing, an activation
303
- * with the pointer elsewhere is their keys landing in the page. Anywhere else it may be a press.
304
- */
305
- export function pressPossible(
306
- shown: boolean,
307
- over: boolean,
308
- overSince: number,
309
- typedAt: number,
310
- at: number,
311
- ): boolean {
312
- return !shown || at - typedAt > TYPING_MS || (over && overSince > typedAt);
313
- }
314
-
315
- /** Keys that type nothing on their own: they don't count as typing (a gesture still). */
316
- const MODIFIERS = new Set(["Shift", "Control", "Alt", "Meta", "AltGraph", "CapsLock", "Fn"]);
317
-
318
- /** The `<input>` types that take typed text (an unknown type is `text`). */
319
- const TEXT_INPUTS = new Set(["text", "search", "url", "tel", "email", "password", "number"]);
320
-
321
- /** Whether `element` takes the person's typed text: a text field, a text area, an editable region. */
322
- export function takesText(element: Element | null): element is HTMLElement {
323
- if (element === null) {
324
- return false;
325
- }
326
- switch (element.localName) {
327
- case "textarea":
328
- return true;
329
- case "input":
330
- return TEXT_INPUTS.has((element as HTMLInputElement).type);
331
- default:
332
- return (element as Partial<HTMLElement>).isContentEditable ?? false;
333
- }
334
- }
335
-
336
- /** The element that has focus, inside open shadow roots too. */
337
- function deepActive(document: Document): Element | null {
338
- let active = document.activeElement;
339
- for (
340
- let inner = active?.shadowRoot?.activeElement;
341
- inner !== null && inner !== undefined;
342
- inner = active?.shadowRoot?.activeElement
343
- ) {
344
- active = inner;
345
- }
346
- return active;
347
- }
348
-
349
- /** One page's guard, shared by every display's frame on it. */
350
- export interface FocusGuard {
351
- /**
352
- * Guards `frame`: `taken` hears each move into it that was undone. `nested`: it holds a nested
353
- * page's shell (P111), whose word (`shell`) decides the moves into it.
354
- */
355
- add(
356
- frame: HTMLIFrameElement,
357
- taken: (take: FocusTake) => void,
358
- options?: {
359
- readonly nested?: boolean;
360
- /** Asks a nested page's shell to look now (P120); it answers with a report naming `n`. */
361
- readonly ask?: (n: number) => void;
362
- },
363
- ): () => void;
364
- /** What a nested page's shell said (P111): its activation, its focus. */
365
- shell(
366
- frame: HTMLIFrameElement,
367
- said: {
368
- readonly supported: boolean;
369
- readonly ago: number | null;
370
- readonly focused: boolean;
371
- /** How long the shell went without a look before this one (its own clock). */
372
- readonly gap: number;
373
- /** The ask this report answers (P120), if it answers one. */
374
- readonly asked?: number;
375
- /**
376
- * Its page's runtime's real presses (P148): how long ago the shell heard the last (null:
377
- * none since the frame's last load), and how many it has heard. Absent from an older shell.
378
- */
379
- readonly pressed?: number | null;
380
- readonly presses?: number;
381
- },
382
- ): void;
383
- /** A nested page's shell's heartbeat (P111): it is looking. */
384
- beat(frame: HTMLIFrameElement): void;
385
- /** Whether a nested page's shell saw the person's gesture just now (`shellGesture`). */
386
- gesture(frame: HTMLIFrameElement): boolean;
387
- /** The host moves focus into `frame` itself. */
388
- focus(frame: HTMLIFrameElement): void;
389
- /**
390
- * Whether the page's focus is in `frame` now, the person's own (once any move into it was
391
- * judged; on an engine that tells the host's page nothing, here and then).
392
- */
393
- focused(frame: HTMLIFrameElement): boolean;
394
- /** The host moves focus into one of its text fields: see `focusField`. */
395
- field(field: HTMLElement): void;
396
- }
397
-
398
- interface Guarded {
399
- readonly taken: Set<(take: FocusTake) => void>;
400
- overSince: number;
401
- /** A nested page's shell's word (P111); null for any other frame. */
402
- word: ShellWord | null;
403
- /** When the host last heard the shell (a report or a heartbeat). */
404
- heardAt: number;
405
- /** When the shell was last seen to have stalled (`SHELL_STALL_MS`); -Infinity if never. */
406
- stalledAt: number;
407
- /** Asks the shell to look now (P120), the last ask's number, and whether it was answered. */
408
- readonly ask: ((n: number) => void) | undefined;
409
- asked: number;
410
- answered: boolean;
411
- }
412
-
413
- const guards = new WeakMap<Window, FocusGuard>();
414
-
415
- /** The guard for `view`'s page, made on first use. */
416
- export function focusGuard(view: Window): FocusGuard {
417
- const existing = guards.get(view);
418
- if (existing !== undefined) {
419
- return existing;
420
- }
421
- const document = view.document;
422
- const frames = new Map<HTMLIFrameElement, Guarded>();
423
- const now = () => view.performance.now();
424
- let known: Element | null = deepActive(document);
425
- let focusedAt = now();
426
- let lastKey: { key: string; at: number } | null = null;
427
- let typedAt = -Infinity;
428
- /** When the person typed on the host's page, the last two seconds of it (P122). */
429
- const typings: number[] = [];
430
- const typed = (at: number) => {
431
- typedAt = at;
432
- typings.push(at);
433
- while (typings.length > 0 && at - (typings[0] as number) > 2 * TYPING_MS) {
434
- typings.shift();
435
- }
436
- };
437
- /** The person's last typing on the host's page at or before `at` (-Infinity: none known). */
438
- const typedBefore = (at: number): number => {
439
- for (let index = typings.length - 1; index >= 0; index -= 1) {
440
- const each = typings[index] as number;
441
- if (each <= at) {
442
- return each;
443
- }
444
- }
445
- return -Infinity;
446
- };
447
- let gestureAt = -Infinity;
448
- let pressAt = -Infinity;
449
- /** The host's page's last trusted press or key (P111: a nested page's gesture must be later). */
450
- let inputAt = -Infinity;
451
- /**
452
- * A move into a nested page's frame waiting for its shell's word (P111): from a text field
453
- * (`field`: taken back unless the shell says the person's), or from anything else (null: only
454
- * whether the frame is the person's for a gesture gate).
455
- */
456
- let waiting: {
457
- readonly field: HTMLElement | null;
458
- readonly frame: HTMLIFrameElement;
459
- readonly guarded: Guarded;
460
- readonly since: number;
461
- } | null = null;
462
- /**
463
- * Whether the host's page sees the pointer over its frames (P120): learned once the pointer comes
464
- * over one (`pointerover` on its element: Firefox, and Chromium and WebKit where frames are in their
465
- * process), or a move from a text field into one doesn't blur the window (Firefox, which shows
466
- * the pointer over a frame, measured). Full Chromium shows neither, and never learns it.
467
- */
468
- let pointerShown = false;
469
- /** When focus last went into a guarded frame, and whether the person moved it there. */
470
- let enteredAt = -Infinity;
471
- let earned = false;
472
- /** The text field the person last pressed, when, and what had focus as they pressed it. */
473
- let pressed: {
474
- readonly field: HTMLElement;
475
- readonly at: number;
476
- readonly from: Element | null;
477
- } | null = null;
478
- let hostMove: { frame: HTMLIFrameElement; at: number } | null = null;
479
- let polling = 0;
480
- /**
481
- * A take-back in progress: the field focus goes back to, the frame it came from, when focus was
482
- * last given back, and since when it has stayed in the field. Ends once it has stayed `HELD_MS`,
483
- * the person moves focus somewhere of their own, or the field or frame is gone. A `fight` undoes
484
- * the page's own move (a take-back, `focusField`, or the person leaving a frame that took focus
485
- * itself), not the person leaving a frame they moved into (P120).
486
- */
487
- let contest: {
488
- readonly field: HTMLElement;
489
- readonly frame: HTMLIFrameElement;
490
- readonly guarded: Guarded;
491
- readonly fight: boolean;
492
- gaveAt: number;
493
- heldSince: number | null;
494
- } | null = null;
495
-
496
- const activation = (): boolean | undefined => {
497
- try {
498
- const state = (view.navigator as Navigator & { userActivation?: { isActive: boolean } })
499
- .userActivation;
500
- return state === undefined ? undefined : state.isActive;
501
- } catch {
502
- return undefined;
503
- }
504
- };
505
-
506
- /**
507
- * What the person's move would need, read now: see `personMoved`. Into a nested page's frame
508
- * whose shell hasn't spoken of this move yet, `wait` (P111). In a fight over a text field
509
- * (`fight`, P120), a nested page's frame is judged as any frame is, its shell's word not asked:
510
- * an activation it says turned on then is the person's keys landing in it far more often than a
511
- * press (a press back into the page within `HELD_MS` of focus landing in the field).
512
- */
513
- const judge = (
514
- frame: HTMLIFrameElement,
515
- guarded: Guarded,
516
- seen: boolean,
517
- at: number,
518
- fight = false,
519
- ): boolean | "wait" => {
520
- const word = fight ? null : guarded.word;
521
- const over = frame.matches(":hover");
522
- const moved = personMoved({
523
- now: at,
524
- seen,
525
- pressed: frame.matches(":active"),
526
- over,
527
- overSince: guarded.overSince,
528
- lastKey,
529
- typedAt,
530
- focusedAt,
531
- gestureAt,
532
- activation: activation(),
533
- hostMoved: hostMove !== null && hostMove.frame === frame && at - hostMove.at <= TAB_MS,
534
- ...(word === null ? {} : { shell: { word, hostInputAt: inputAt, pointerShown } }),
535
- });
536
- hostMove = null;
537
- // The shell tells a move at its next frame, the host's page hears it first: until the shell
538
- // said focus came in (around now), its activation may be on its way; unless no press could
539
- // have made the move (P120), which nothing the shell says changes.
540
- if (
541
- !moved &&
542
- word !== null &&
543
- word.supported &&
544
- word.focusedAt < at - SHELL_EARLY_MS &&
545
- at - typedAt >= KEY_PRESS_MS &&
546
- pressPossible(pointerShown, over, guarded.overSince, typedAt, at)
547
- ) {
548
- return "wait";
549
- }
550
- return moved;
551
- };
552
-
553
- /** Waits for a nested page's shell's word on a move (P111): decided by `settle`. */
554
- const wait = (
555
- field: HTMLElement | null,
556
- frame: HTMLIFrameElement,
557
- guarded: Guarded,
558
- at: number,
559
- ) => {
560
- waiting = { field, frame, guarded, since: at };
561
- // The shell looks at its next frame, and a key the person types into the page before then
562
- // turns its activation on as a press does: asked to look now, it says what it saw as the move
563
- // was heard (P120).
564
- guarded.asked += 1;
565
- guarded.answered = false;
566
- guarded.ask?.(guarded.asked);
567
- known = frame;
568
- enteredAt = at;
569
- earned = false;
570
- schedule();
571
- };
572
-
573
- /**
574
- * A waiting move, once its shell spoke or the wait is over: the person's (the frame keeps
575
- * focus), or the page's (from a text field, taken back). A move elsewhere since ends it.
576
- */
577
- const settle = (at: number) => {
578
- const held = waiting;
579
- if (held === null) {
580
- return;
581
- }
582
- const { field, frame, guarded } = held;
583
- const active = deepActive(document);
584
- if (active !== frame || !frames.has(frame)) {
585
- waiting = null;
586
- // Moved on since to nothing, or back to the field, with no press of the person's on the
587
- // host's page: still the page's move from that field (P120, after the audit of P111's guard:
588
- // NG-1, where the frame took it again at once and was then let be), watched as a take-back
589
- // is, focus on nothing given back and counted.
590
- if (
591
- field !== null &&
592
- field.isConnected &&
593
- pressAt <= held.since &&
594
- (active === null || active === document.body || active === field)
595
- ) {
596
- known = field;
597
- contest = { field, frame, guarded, fight: true, gaveAt: held.since, heldSince: null };
598
- schedule();
599
- return;
600
- }
601
- // Anywhere else: from the frame, as the next look judges it.
602
- known = frame;
603
- return;
604
- }
605
- const word = guarded.word;
606
- // The shell's activation, where a press could have made it: within a second of the person's
607
- // typing on the host's page with the pointer elsewhere, it is their keys landing in the page
608
- // (P120). Read as of the move.
609
- const theirs = word !== null && shellSaw(word, inputAt, at, pointerShown);
610
- // It said focus came in around the move, or answered the ask the move made with focus in it.
611
- const spoke =
612
- word !== null &&
613
- (word.focusedAt >= held.since - SHELL_EARLY_MS || (guarded.answered && word.focused));
614
- if (theirs) {
615
- waiting = null;
616
- known = frame;
617
- earned = true;
618
- return;
619
- }
620
- if (!spoke && at - held.since < SHELL_WAIT_MS) {
621
- return;
622
- }
623
- waiting = null;
624
- if (field !== null && field.isConnected) {
625
- takeBack(field, frame, guarded, at, false);
626
- }
627
- };
628
-
629
- /**
630
- * Focus goes back to `field` once the engine has finished the move: given back inside its blur
631
- * it stays with the frame on Chromium and WebKit, and Firefox takes it back only from a frame
632
- * that was blurred first (measured). Unless the person has since put focus somewhere of their own.
633
- */
634
- const giveBack = (field: HTMLElement, frame: HTMLIFrameElement) => {
635
- view.setTimeout(() => {
636
- const current = deepActive(document);
637
- if (
638
- field.isConnected &&
639
- (current === frame || current === null || current === document.body)
640
- ) {
641
- frame.blur();
642
- field.focus({ preventScroll: true });
643
- }
644
- }, 0);
645
- };
646
-
647
- /** A move the guard undoes: focus goes back, the display hears it, and the guard keeps watching. */
648
- const takeBack = (
649
- field: HTMLElement,
650
- frame: HTMLIFrameElement,
651
- guarded: Guarded,
652
- at: number,
653
- failed: boolean,
654
- ) => {
655
- // Until it is back, the field counts as the page's focus, so a move that didn't take is seen.
656
- known = field;
657
- focusedAt = at;
658
- contest = { field, frame, guarded, fight: true, gaveAt: at, heldSince: null };
659
- giveBack(field, frame);
660
- schedule();
661
- const take: FocusTake = { typing: at - typedAt <= TYPING_MS, failed };
662
- for (const taken of guarded.taken) {
663
- taken(take);
664
- }
665
- };
666
-
667
- /**
668
- * While a take-back is in progress: whether focus stayed in the field, or the frame has it again
669
- * (or it landed on nothing), which is the page's doing unless the person moved it there.
670
- */
671
- const watch = (seen: boolean, active: Element | null, at: number): boolean => {
672
- const watched = contest;
673
- if (watched === null) {
674
- return false;
675
- }
676
- const { field, frame, guarded } = watched;
677
- if (!field.isConnected || pressAt > watched.gaveAt) {
678
- // Gone, or the person pressed the page since: theirs to place focus now.
679
- contest = null;
680
- return false;
681
- }
682
- if (!frames.has(frame)) {
683
- // The frame was removed mid-fight (its display stopped): Firefox may leave focus on nothing
684
- // once the focused frame goes. Back into the field, for a moment after.
685
- if ((active === null || active === document.body) && at - watched.gaveAt <= HELD_MS) {
686
- field.focus({ preventScroll: true });
687
- return true;
688
- }
689
- contest = null;
690
- return false;
691
- }
692
- if (active === field) {
693
- watched.heldSince ??= at;
694
- if (at - watched.heldSince >= HELD_MS) {
695
- contest = null;
696
- }
697
- known = field;
698
- return true;
699
- }
700
- const lost = active === frame || active === null || active === document.body;
701
- if (!lost) {
702
- // Somewhere else of the person's (another field, a button, another frame): judged as any.
703
- contest = null;
704
- return false;
705
- }
706
- if (active === frame) {
707
- // The frame has it again. In a fight, the person's only by a Tab, the host's own move, or a
708
- // press the engine shows: a nested page's too, its shell's word not asked (P120, after the
709
- // audit of P111's guard, NG-1, where waiting for it let the frame keep the keyboard).
710
- const verdict = judge(frame, guarded, seen, at, watched.fight);
711
- if (verdict === true) {
712
- contest = null;
713
- known = frame;
714
- enteredAt = at;
715
- earned = true;
716
- return true;
717
- }
718
- if (verdict === "wait") {
719
- // The person left a nested page they had moved into, and focus went back in (P111): its
720
- // shell decides, as it would at first.
721
- if (watched.heldSince !== null || at - watched.gaveAt >= GIVE_BACK_MS) {
722
- contest = null;
723
- wait(field, frame, guarded, at);
724
- }
725
- return true;
726
- }
727
- }
728
- // Taken again once it was back (within `HELD_MS`), or not back yet after `GIVE_BACK_MS`: a
729
- // take-back that failed, given again and counted.
730
- if (watched.heldSince !== null || at - watched.gaveAt >= GIVE_BACK_MS) {
731
- takeBack(field, frame, guarded, at, true);
732
- }
733
- return true;
734
- };
735
-
736
- /** Judges a change of focus since the last look: `seen` when the engine told it (a blur). */
737
- const look = (seen: boolean) => {
738
- const active = deepActive(document);
739
- const at = now();
740
- if (waiting !== null) {
741
- settle(at);
742
- return;
743
- }
744
- if (watch(seen, active, at)) {
745
- return;
746
- }
747
- const was = known;
748
- // The person pressed a text field and focus is on nothing: on Firefox, a page that takes focus
749
- // as they press, or takes it back on its blur with a gesture of theirs, leaves it there
750
- // (measured, on a slow machine too), and their keys are lost. Into the field, once: as a
751
- // take-back the page failed if a frame had focus as they pressed, else simply.
752
- const press = pressed;
753
- if (
754
- press !== null &&
755
- (active === null || active === document.body) &&
756
- at - press.at <= HELD_MS &&
757
- press.field.isConnected
758
- ) {
759
- pressed = null;
760
- const from = press.from ?? was;
761
- const blamed = from === null ? undefined : frames.get(from as HTMLIFrameElement);
762
- if (blamed === undefined) {
763
- known = active;
764
- press.field.focus({ preventScroll: true });
765
- } else {
766
- takeBack(press.field, from as HTMLIFrameElement, blamed, at, true);
767
- }
768
- return;
769
- }
770
- known = active;
771
- if (active === was || active === null) {
772
- return;
773
- }
774
- const entered = frames.get(active as HTMLIFrameElement);
775
- if (entered !== undefined) {
776
- // From a text field it is judged below; from anything else it is let be, but only the
777
- // person's own move makes the frame theirs for a gesture gate (`focused`).
778
- enteredAt = at;
779
- const verdict = takesText(was) || judge(active as HTMLIFrameElement, entered, seen, at);
780
- if (verdict === "wait") {
781
- // A nested page's (P111): theirs once its shell says so; nothing to take back.
782
- wait(null, active as HTMLIFrameElement, entered, at);
783
- return;
784
- }
785
- earned = verdict;
786
- }
787
- // Into a text field from a display's frame (the person pressed the composer while the frame
788
- // had focus): watched as a take-back is, since a page that takes focus back on its own blur
789
- // leaves it on nothing on Firefox (measured), where the keys are lost to the page's doing.
790
- const left = was === null ? undefined : frames.get(was as HTMLIFrameElement);
791
- if (left !== undefined && takesText(active)) {
792
- contest = {
793
- field: active,
794
- frame: was as HTMLIFrameElement,
795
- guarded: left,
796
- fight: !earned,
797
- gaveAt: at,
798
- heldSince: at,
799
- };
800
- return;
801
- }
802
- const guarded = frames.get(active as HTMLIFrameElement);
803
- if (guarded === undefined || !takesText(was) || !was.isConnected) {
804
- return;
805
- }
806
- const frame = active as HTMLIFrameElement;
807
- if (!seen) {
808
- // A move out of a text field the window didn't blur for: Firefox, which shows the host's
809
- // page the pointer over a frame (P120).
810
- pointerShown = true;
811
- }
812
- const verdict = judge(frame, guarded, seen, at);
813
- if (verdict === true) {
814
- return;
815
- }
816
- if (verdict === "wait") {
817
- wait(was, frame, guarded, at);
818
- return;
819
- }
820
- takeBack(was, frame, guarded, at, false);
821
- };
822
-
823
- /**
824
- * Firefox moves focus into a frame without a word to the host's page: while a frame is guarded,
825
- * look at each animation frame (one read of the focused element), so the guard knows where focus
826
- * is when it next leaves a text field, or comes into one from a frame.
827
- */
828
- const poll = () => {
829
- polling = 0;
830
- look(false);
831
- schedule();
832
- };
833
- const schedule = () => {
834
- if (polling === 0 && (frames.size > 0 || contest !== null || waiting !== null)) {
835
- polling = view.requestAnimationFrame(poll);
836
- }
837
- };
838
-
839
- const gesture = () => {
840
- gestureAt = now();
841
- };
842
- const press = (event: Event) => {
843
- pressAt = now();
844
- if (event.isTrusted) {
845
- inputAt = pressAt;
846
- }
847
- gestureAt = pressAt;
848
- const target = event.composedPath()[0];
849
- pressed =
850
- target instanceof Element && takesText(target)
851
- ? { field: target, at: pressAt, from: deepActive(document) }
852
- : null;
853
- };
854
- view.addEventListener(
855
- "keydown",
856
- (event) => {
857
- const at = now();
858
- gestureAt = at;
859
- lastKey = { key: event.key, at };
860
- if (event.isTrusted) {
861
- inputAt = at;
862
- }
863
- if (event.key !== "Tab" && !MODIFIERS.has(event.key)) {
864
- typed(at);
865
- }
866
- },
867
- true,
868
- );
869
- // A click too (an assistive technology's click on the host's own UI dispatches no press), and
870
- // text that comes without a key (dictation, a paste, an input method): typing all the same.
871
- for (const type of ["pointerup", "touchend", "click"]) {
872
- view.addEventListener(type, gesture, true);
873
- }
874
- for (const type of ["pointerdown", "mousedown"]) {
875
- view.addEventListener(type, press, true);
876
- }
877
- view.addEventListener(
878
- "input",
879
- () => {
880
- typed(now());
881
- gestureAt = typedAt;
882
- },
883
- true,
884
- );
885
- // Focus moving within the page: what had it, for the next move out of a text field.
886
- document.addEventListener(
887
- "focusin",
888
- () => {
889
- focusedAt = now();
890
- look(false);
891
- schedule();
892
- },
893
- true,
894
- );
895
- // Chromium and WebKit blur the window as focus goes into a frame. Firefox may send the field a
896
- // focusout first (seen in one review's runs, not in another's): looked at once it's over.
897
- view.addEventListener("blur", (event) => {
898
- if (event.target === view) {
899
- look(true);
900
- }
901
- });
902
- document.addEventListener(
903
- "focusout",
904
- () => {
905
- view.setTimeout(() => look(false), 0);
906
- },
907
- true,
908
- );
909
-
910
- const guard: FocusGuard = {
911
- add(frame, taken, options) {
912
- let guarded = frames.get(frame);
913
- if (guarded === undefined) {
914
- const entry: Guarded = {
915
- taken: new Set(),
916
- overSince: -Infinity,
917
- heardAt: -Infinity,
918
- stalledAt: -Infinity,
919
- ask: options?.nested === true ? options.ask : undefined,
920
- asked: 0,
921
- answered: false,
922
- word:
923
- options?.nested === true
924
- ? { supported: true, activatedAt: -Infinity, focused: false, focusedAt: -Infinity }
925
- : null,
926
- };
927
- frame.addEventListener("pointerover", () => {
928
- entry.overSince = now();
929
- pointerShown = true;
930
- });
931
- frames.set(frame, entry);
932
- guarded = entry;
933
- }
934
- guarded.taken.add(taken);
935
- schedule();
936
- const own = guarded;
937
- return () => {
938
- own.taken.delete(taken);
939
- if (own.taken.size === 0) {
940
- frames.delete(frame);
941
- }
942
- };
943
- },
944
- shell(frame, said) {
945
- const guarded = frames.get(frame);
946
- const before = guarded?.word ?? null;
947
- if (guarded === undefined || before === null) {
948
- return;
949
- }
950
- const at = now();
951
- // Off to on after a stall, the shell's or the host's (no word for longer than its beat
952
- // allows): uncertain, and so until it goes off (P111, after its review). So is one that
953
- // turned on while the guard fights this frame for a text field (P120): the person's keys,
954
- // meant for the field, landing in the page.
955
- // So is one that turned on within `KEY_PRESS_MS` of a key the person typed on the host's page
956
- // before it (P122): that key's successor, landing in the page.
957
- const turnedOn = said.ago !== null && before.activatedAt === -Infinity && !before.uncertain;
958
- const stalled = said.gap > SHELL_STALL_MS || at - guarded.heardAt > SHELL_STALL_MS;
959
- if (stalled) {
960
- guarded.stalledAt = at;
961
- }
962
- const fought = contest !== null && contest.fight && contest.frame === frame;
963
- // The typing before it, never after: a key the person typed on the host's page after they
964
- // pressed the page, before the shell's word came, says nothing of that press (P122, after
965
- // CI). The shell saw it turn on at its look, so it turned on at most a look's gap before:
966
- // only a key before then counts.
967
- const turnedAt =
968
- said.ago === null ? -Infinity : at - said.ago - Math.min(said.gap, SHELL_STALL_MS);
969
- const typing = typedBefore(turnedAt);
970
- const soon = said.ago !== null && turnedAt - typing < KEY_PRESS_MS;
971
- const uncertain =
972
- said.ago !== null &&
973
- (before.uncertain === true || (turnedOn && (stalled || fought || soon)));
974
- guarded.heardAt = at;
975
- if (said.asked !== undefined && said.asked === guarded.asked) {
976
- guarded.answered = true;
977
- }
978
- // Whether a press could have turned it on, judged as it did (P120, after its review): the
979
- // person's typing then, and the pointer then, not when a move is later judged.
980
- const activatedAt = said.ago === null || uncertain ? -Infinity : at - said.ago;
981
- const keyed =
982
- activatedAt === -Infinity
983
- ? false
984
- : turnedOn
985
- ? !pressPossible(true, frame.matches(":hover"), guarded.overSince, typing, turnedAt)
986
- : before.keyed === true;
987
- // A press its page's runtime told it (P148), new when it has heard more than it had: judged
988
- // as an activation that turned on is. Heard in or just after a stall
989
- // (`SHELL_AFTER_STALL_MS`), in a fight for a text field, or within `KEY_PRESS_MS` of a key
990
- // the person typed on the host's page before it, it is no one's (a press says nothing of
991
- // when it was until the shell hears it, and Enter or Space on a button the page put the
992
- // focus on is the person's key landing in the page); and whether a press could have made
993
- // it is judged now, as the shell tells it (P120).
994
- const pressNew = typeof said.presses === "number" && said.presses !== (before.presses ?? 0);
995
- const pressHeardAt =
996
- typeof said.pressed === "number"
997
- ? at - said.pressed - Math.min(said.gap, SHELL_STALL_MS)
998
- : -Infinity;
999
- const pressTyping = typedBefore(pressHeardAt);
1000
- const pressedAt =
1001
- typeof said.pressed !== "number"
1002
- ? -Infinity
1003
- : !pressNew
1004
- ? (before.pressedAt ?? -Infinity)
1005
- : at - guarded.stalledAt <= SHELL_AFTER_STALL_MS ||
1006
- fought ||
1007
- pressHeardAt - pressTyping < KEY_PRESS_MS
1008
- ? -Infinity
1009
- : at - said.pressed;
1010
- const pressKeyed =
1011
- pressedAt === -Infinity
1012
- ? false
1013
- : pressNew
1014
- ? !pressPossible(
1015
- true,
1016
- frame.matches(":hover"),
1017
- guarded.overSince,
1018
- pressTyping,
1019
- pressHeardAt,
1020
- )
1021
- : before.pressKeyed === true;
1022
- guarded.word = {
1023
- supported: said.supported,
1024
- activatedAt,
1025
- focused: said.focused,
1026
- focusedAt: said.focused && !before.focused ? at : before.focusedAt,
1027
- ...(uncertain ? { uncertain: true } : {}),
1028
- ...(keyed ? { keyed: true } : {}),
1029
- ...(said.presses === undefined ? {} : { pressedAt, presses: said.presses }),
1030
- ...(pressKeyed ? { pressKeyed: true } : {}),
1031
- };
1032
- if (waiting?.frame === frame) {
1033
- settle(at);
1034
- } else if (
1035
- pressNew &&
1036
- known === frame &&
1037
- document.activeElement === frame &&
1038
- contest === null &&
1039
- shellPress(guarded.word, inputAt, at) &&
1040
- !(pointerShown && pressKeyed)
1041
- ) {
1042
- // Focus is in the frame already and the person pressed in its page: theirs from here on,
1043
- // as a move into it they made is (the shell's word on the move may have come before the
1044
- // press's did).
1045
- earned = true;
1046
- }
1047
- },
1048
- beat(frame) {
1049
- const guarded = frames.get(frame);
1050
- if (guarded !== undefined && guarded.word !== null) {
1051
- const at = now();
1052
- // The first word after a silence may be a heartbeat: the stall is the same.
1053
- if (at - guarded.heardAt > SHELL_STALL_MS) {
1054
- guarded.stalledAt = at;
1055
- }
1056
- guarded.heardAt = at;
1057
- }
1058
- },
1059
- gesture(frame) {
1060
- const guarded = frames.get(frame);
1061
- const word = guarded?.word ?? null;
1062
- const at = now();
1063
- // Where a press could have made it (P120): a key the person typed into the page, meant for
1064
- // the host's composer, turns the shell's activation on too.
1065
- return guarded !== undefined && word !== null && shellSaw(word, inputAt, at, pointerShown);
1066
- },
1067
- focus(frame) {
1068
- hostMove = { frame, at: now() };
1069
- frame.focus();
1070
- look(true);
1071
- },
1072
- focused(frame) {
1073
- look(false);
1074
- // A press on the host's page since focus went into the frame, just now: the activation is
1075
- // that press's, and focus is about to leave (a call that lands in between doesn't count).
1076
- const pressedHost = pressAt > enteredAt && now() - pressAt < HOST_PRESS_MS;
1077
- return known === frame && document.activeElement === frame && earned && !pressedHost;
1078
- },
1079
- field(field) {
1080
- const holder = deepActive(document);
1081
- const guarded = holder === null ? undefined : frames.get(holder as HTMLIFrameElement);
1082
- if (guarded === undefined) {
1083
- field.focus({ preventScroll: true });
1084
- return;
1085
- }
1086
- // Watched as a take-back: a frame that keeps focus fails it, and is counted.
1087
- const frame = holder as HTMLIFrameElement;
1088
- frame.blur();
1089
- field.focus({ preventScroll: true });
1090
- known = field;
1091
- focusedAt = now();
1092
- contest = { field, frame, guarded, fight: true, gaveAt: focusedAt, heldSince: null };
1093
- schedule();
1094
- },
1095
- };
1096
- guards.set(view, guard);
1097
- return guard;
1098
- }
1099
-
1100
- /**
1101
- * Moves focus into one of the host page's text fields (a composer that opens beside a display,
1102
- * P109): `field.focus()` for a host to call instead. Firefox doesn't move focus from a frame that
1103
- * holds it with a gesture of the person's and takes it back on its own blur (measured: the keys
1104
- * then go to the frame); this blurs the frame first, and the focus guard watches that focus lands,
1105
- * counting a frame that keeps it toward stopping its display. Elsewhere it is `field.focus()`.
1106
- */
1107
- export function focusField(field: HTMLElement): void {
1108
- const view = field.ownerDocument.defaultView;
1109
- if (view === null) {
1110
- field.focus({ preventScroll: true });
1111
- return;
1112
- }
1113
- focusGuard(view).field(field);
1114
- }