@botiverse/porthole 0.14.2 → 0.14.4

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.
@@ -3,6 +3,6 @@ import type { FrameSource, InstanceLocator, InstanceRef } from "../isolation/typ
3
3
  /**
4
4
  * Where a served frame (domain or external isolation) loads from: the host's locator answers, and
5
5
  * `checkFrameLocation` checks the answer (one of the config's content origins, never the host's
6
- * own site) before any frame is made.
6
+ * own site; a nested page's on a shell's own label, P121) before any frame is made.
7
7
  */
8
8
  export declare function locateServed(locator: InstanceLocator, instance: InstanceRef, config: PortholeConfig, hostOrigin: string, signal?: AbortSignal): Promise<FrameSource>;
@@ -3,11 +3,11 @@ import { parseViewer } from "../runtime/levels.js";
3
3
  /**
4
4
  * Where a served frame (domain or external isolation) loads from: the host's locator answers, and
5
5
  * `checkFrameLocation` checks the answer (one of the config's content origins, never the host's
6
- * own site) before any frame is made.
6
+ * own site; a nested page's on a shell's own label, P121) before any frame is made.
7
7
  */
8
8
  export async function locateServed(locator, instance, config, hostOrigin, signal) {
9
9
  const location = await locator.locate(instance, signal);
10
- checkFrameLocation(location, config.contentOrigins, hostOrigin);
10
+ checkFrameLocation(location, config.contentOrigins, hostOrigin, config.nested === true);
11
11
  // The host's access, as its backend answered (P087): a viewer that doesn't parse is the host's
12
12
  // error, never no viewer (after the review: a mount's own would take its place).
13
13
  const viewer = location.viewer === undefined ? null : parseViewer(location.viewer);
@@ -6,6 +6,20 @@ interface ParsedOrigin {
6
6
  }
7
7
  /** `scheme://host[:port]`, lowercase, nothing else; null for anything that isn't exactly that. */
8
8
  export declare function parseOrigin(origin: string): ParsedOrigin | null;
9
+ /**
10
+ * The start of every label Porthole serves for itself on a content domain (P114): no host's naming
11
+ * may make one (`content.name` is refused one, and `prefixedName` won't take the prefix).
12
+ */
13
+ export declare const PORTHOLE_LABEL_PREFIX = "porthole-";
14
+ /** Whether a label is a nested page's shell's own (P114, `nestedLabelOf`'s form). */
15
+ export declare const isNestedLabel: (label: string) => boolean;
16
+ /**
17
+ * Whether `origin` is on a nested page's shell's own label (P114): its host's first label is one.
18
+ * The shell runs nowhere else (P121): the host's mount, the shell itself and `/server`'s helpers
19
+ * each refuse any other origin, so a content Worker of a host's own can't put it beside other
20
+ * content by mistake.
21
+ */
22
+ export declare function onNestedLabel(origin: string): boolean;
9
23
  /** Whether `origin` is an exact origin (`https://host[:port]`, lowercase, no path). */
10
24
  export declare function isExactOrigin(origin: unknown): origin is string;
11
25
  export declare function isHostOrigin(origin: unknown): origin is string;
@@ -31,5 +45,7 @@ export declare function originMatchesSource(origin: string, source: string): boo
31
45
  * names, and it is not of the host's own site (a same-site frame with `allow-same-origin` could
32
46
  * reach cookies and storage the host shares with its site).
33
47
  */
34
- export declare function checkFrameLocation(location: FrameLocation, contentOrigins: readonly string[], hostOrigin: string): void;
48
+ export declare function checkFrameLocation(location: FrameLocation, contentOrigins: readonly string[], hostOrigin: string,
49
+ /** The config nests its pages (P111): the location must be on a shell's own label (P121). */
50
+ nested?: boolean): void;
35
51
  export {};
@@ -15,6 +15,24 @@ export function parseOrigin(origin) {
15
15
  const [, scheme = "", host = "", port] = match;
16
16
  return { scheme, host, port: port ?? DEFAULT_PORTS[scheme] ?? "" };
17
17
  }
18
+ /**
19
+ * The start of every label Porthole serves for itself on a content domain (P114): no host's naming
20
+ * may make one (`content.name` is refused one, and `prefixedName` won't take the prefix).
21
+ */
22
+ export const PORTHOLE_LABEL_PREFIX = "porthole-";
23
+ const NESTED_LABEL = /^porthole-[a-z2-7]{24}$/u;
24
+ /** Whether a label is a nested page's shell's own (P114, `nestedLabelOf`'s form). */
25
+ export const isNestedLabel = (label) => NESTED_LABEL.test(label);
26
+ /**
27
+ * Whether `origin` is on a nested page's shell's own label (P114): its host's first label is one.
28
+ * The shell runs nowhere else (P121): the host's mount, the shell itself and `/server`'s helpers
29
+ * each refuse any other origin, so a content Worker of a host's own can't put it beside other
30
+ * content by mistake.
31
+ */
32
+ export function onNestedLabel(origin) {
33
+ const parsed = parseOrigin(origin);
34
+ return parsed !== null && isNestedLabel(parsed.host.split(".")[0] ?? "");
35
+ }
18
36
  /** Whether `origin` is an exact origin (`https://host[:port]`, lowercase, no path). */
19
37
  export function isExactOrigin(origin) {
20
38
  return typeof origin === "string" && parseOrigin(origin) !== null;
@@ -95,7 +113,9 @@ export function originMatchesSource(origin, source) {
95
113
  * names, and it is not of the host's own site (a same-site frame with `allow-same-origin` could
96
114
  * reach cookies and storage the host shares with its site).
97
115
  */
98
- export function checkFrameLocation(location, contentOrigins, hostOrigin) {
116
+ export function checkFrameLocation(location, contentOrigins, hostOrigin,
117
+ /** The config nests its pages (P111): the location must be on a shell's own label (P121). */
118
+ nested = false) {
99
119
  const origin = parseOrigin(location.origin);
100
120
  let url;
101
121
  try {
@@ -112,6 +132,9 @@ export function checkFrameLocation(location, contentOrigins, hostOrigin) {
112
132
  if (!contentOrigins.some((source) => originMatchesSource(location.origin, source))) {
113
133
  throw new TypeError(`The located origin ${location.origin} is not one of the config's content origins`);
114
134
  }
135
+ if (nested && !onNestedLabel(location.origin)) {
136
+ throw new TypeError(`The located origin ${location.origin} isn't a nested page's own: its shell is served on a label of its own alone (${PORTHOLE_LABEL_PREFIX}<24 base32>, nestedLabelOf(label), P114), never beside other content`);
137
+ }
115
138
  const host = parseOrigin(hostOrigin);
116
139
  if (host !== null && maybeSameSite(origin.host, host.host)) {
117
140
  throw new TypeError(`The located origin ${location.origin} may be the same site as the host (${hostOrigin}): content must be served from a registrable domain the host uses for nothing else`);
@@ -83,6 +83,11 @@ export declare const FRAME_STATUS_METHOD = "porthole/notifications/frame-status"
83
83
  export declare const SHELL_STATE_METHOD = "porthole/shell/state";
84
84
  /** A nested page's shell's heartbeat, every 50 ms while it runs (P111, after its review). */
85
85
  export declare const SHELL_BEAT_METHOD = "porthole/shell/beat";
86
+ /**
87
+ * The host's ask to a nested page's shell (P120): look now, and say what it saw in a state report
88
+ * that names the ask (`asked`). The host asks as it hears focus move into the frame.
89
+ */
90
+ export declare const SHELL_LOOK_METHOD = "porthole/shell/look";
86
91
  /** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
87
92
  export declare const SHELL_METHOD_PREFIX = "porthole/shell/";
88
93
  /** A page's word that it used storage, once per load (P111): never a key or a value. */
@@ -4,6 +4,11 @@ export const FRAME_STATUS_METHOD = "porthole/notifications/frame-status";
4
4
  export const SHELL_STATE_METHOD = "porthole/shell/state";
5
5
  /** A nested page's shell's heartbeat, every 50 ms while it runs (P111, after its review). */
6
6
  export const SHELL_BEAT_METHOD = "porthole/shell/beat";
7
+ /**
8
+ * The host's ask to a nested page's shell (P120): look now, and say what it saw in a state report
9
+ * that names the ask (`asked`). The host asks as it hears focus move into the frame.
10
+ */
11
+ export const SHELL_LOOK_METHOD = "porthole/shell/look";
7
12
  /** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
8
13
  export const SHELL_METHOD_PREFIX = "porthole/shell/";
9
14
  /** A page's word that it used storage, once per load (P111): never a key or a value. */
@@ -18,6 +18,15 @@
18
18
  * frame again (the review of the guard, GK-1): the guard keeps watching after each take-back and
19
19
  * counts one that didn't hold. Every engine keeps a gesture's transient activation for 5 s
20
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.
21
30
  */
22
31
  /** How long the person's Tab counts as moving focus (the move follows its keydown at once). */
23
32
  export declare const TAB_MS = 1000;
@@ -28,6 +37,16 @@ export declare const TAB_MS = 1000;
28
37
  export declare const ACTIVATION_SPAN_MS = 5000;
29
38
  /** The person is typing: a key on the host's page within this long. */
30
39
  export declare const TYPING_MS = 1000;
40
+ /**
41
+ * No press of the person's lands on a frame this soon after a key they typed on the host's page
42
+ * (P122): a hand on the keys doesn't reach the pointer and press that fast (the Keystroke-Level
43
+ * Model gives 400 ms to the hand's move from the keys to the mouse alone; Card, Moran and Newell,
44
+ * 1980). A move into a nested page's frame, or its shell's activation turning on, within this long
45
+ * is the person's next key landing in the page, which turns its activation on as a press does.
46
+ * Where neither the host's page nor the shell sees the pointer (full Chromium), it holds a page that
47
+ * takes the keyboard while the person types even when their key outruns the shell's answer.
48
+ */
49
+ export declare const KEY_PRESS_MS = 250;
31
50
  /**
32
51
  * After a take-back, the guard keeps watching (each animation frame) until focus has stayed in the
33
52
  * text field this long: a page that takes it again at once (on its own blur, which the take-back
@@ -98,6 +117,12 @@ export interface ShellWord {
98
117
  readonly focusedAt: number;
99
118
  /** Its activation turned on while it was stalled: uncertain until it goes off (`SHELL_STALL_MS`). */
100
119
  readonly uncertain?: boolean;
120
+ /**
121
+ * Its activation turned on within `TYPING_MS` of the person's typing on the host's page, the
122
+ * pointer not come over the frame since (`pressPossible`, judged as it turned on): where the
123
+ * host's page sees the pointer, their key landing in the page, no press (P120).
124
+ */
125
+ readonly keyed?: boolean;
101
126
  }
102
127
  /** One move of the keyboard the guard undid. */
103
128
  export interface FocusTake {
@@ -142,6 +167,8 @@ export interface FocusMove {
142
167
  readonly shell?: {
143
168
  readonly word: ShellWord;
144
169
  readonly hostInputAt: number;
170
+ /** The host's page sees the pointer over its frames on this engine (`pressPossible`, P120). */
171
+ readonly pointerShown?: boolean;
145
172
  };
146
173
  }
147
174
  /**
@@ -167,6 +194,15 @@ export declare function personMoved(move: FocusMove): boolean;
167
194
  * within `SHELL_GESTURE_MS`, after the host's page's last trusted press or key.
168
195
  */
169
196
  export declare function shellGesture(word: ShellWord, hostInputAt: number, now: number): boolean;
197
+ /**
198
+ * Whether the person could have pressed the frame just before `at` (P120): a nested page's shell
199
+ * says its activation turned on, which a key typed into the page does as well as a press. Where the
200
+ * host's page sees the pointer over its frames (`shown`: Firefox; Chromium and WebKit where the frame
201
+ * is in their process, not full Chromium), a press needs the pointer over the frame, come over it
202
+ * since the person last typed on the host's page; within `TYPING_MS` of that typing, an activation
203
+ * with the pointer elsewhere is their keys landing in the page. Anywhere else it may be a press.
204
+ */
205
+ export declare function pressPossible(shown: boolean, over: boolean, overSince: number, typedAt: number, at: number): boolean;
170
206
  /** Whether `element` takes the person's typed text: a text field, a text area, an editable region. */
171
207
  export declare function takesText(element: Element | null): element is HTMLElement;
172
208
  /** One page's guard, shared by every display's frame on it. */
@@ -177,6 +213,8 @@ export interface FocusGuard {
177
213
  */
178
214
  add(frame: HTMLIFrameElement, taken: (take: FocusTake) => void, options?: {
179
215
  readonly nested?: boolean;
216
+ /** Asks a nested page's shell to look now (P120); it answers with a report naming `n`. */
217
+ readonly ask?: (n: number) => void;
180
218
  }): () => void;
181
219
  /** What a nested page's shell said (P111): its activation, its focus. */
182
220
  shell(frame: HTMLIFrameElement, said: {
@@ -185,6 +223,8 @@ export interface FocusGuard {
185
223
  readonly focused: boolean;
186
224
  /** How long the shell went without a look before this one (its own clock). */
187
225
  readonly gap: number;
226
+ /** The ask this report answers (P120), if it answers one. */
227
+ readonly asked?: number;
188
228
  }): void;
189
229
  /** A nested page's shell's heartbeat (P111): it is looking. */
190
230
  beat(frame: HTMLIFrameElement): void;
@@ -18,6 +18,15 @@
18
18
  * frame again (the review of the guard, GK-1): the guard keeps watching after each take-back and
19
19
  * counts one that didn't hold. Every engine keeps a gesture's transient activation for 5 s
20
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.
21
30
  */
22
31
  /** How long the person's Tab counts as moving focus (the move follows its keydown at once). */
23
32
  export const TAB_MS = 1_000;
@@ -28,6 +37,16 @@ export const TAB_MS = 1_000;
28
37
  export const ACTIVATION_SPAN_MS = 5_000;
29
38
  /** The person is typing: a key on the host's page within this long. */
30
39
  export const TYPING_MS = 1_000;
40
+ /**
41
+ * No press of the person's lands on a frame this soon after a key they typed on the host's page
42
+ * (P122): a hand on the keys doesn't reach the pointer and press that fast (the Keystroke-Level
43
+ * Model gives 400 ms to the hand's move from the keys to the mouse alone; Card, Moran and Newell,
44
+ * 1980). A move into a nested page's frame, or its shell's activation turning on, within this long
45
+ * is the person's next key landing in the page, which turns its activation on as a press does.
46
+ * Where neither the host's page nor the shell sees the pointer (full Chromium), it holds a page that
47
+ * takes the keyboard while the person types even when their key outruns the shell's answer.
48
+ */
49
+ export const KEY_PRESS_MS = 250;
31
50
  /**
32
51
  * After a take-back, the guard keeps watching (each animation frame) until focus has stayed in the
33
52
  * text field this long: a page that takes it again at once (on its own blur, which the take-back
@@ -106,10 +125,15 @@ export function personMoved(move) {
106
125
  return true;
107
126
  }
108
127
  // A nested page (P111): its shell's activation turned on within the last second, and the host's
109
- // page had no press or key of its own since (the person went back to it); or, where the engine
110
- // tells it, a press on the frame. Nothing else: no pointer over it, no host-wide activation.
128
+ // page had no press or key of its own since (the person went back to it), where it may have been
129
+ // a press (P120) and not within `KEY_PRESS_MS` of the person's last key (P122); or, where the
130
+ // engine tells it, a press on the frame. Nothing else: no pointer over it, no host-wide
131
+ // activation.
111
132
  if (move.shell !== undefined && move.shell.word.supported) {
112
- return ((move.seen && move.pressed) || shellGesture(move.shell.word, move.shell.hostInputAt, move.now));
133
+ return ((move.seen && move.pressed) ||
134
+ (move.now - move.typedAt >= KEY_PRESS_MS &&
135
+ shellGesture(move.shell.word, move.shell.hostInputAt, move.now) &&
136
+ !(move.shell.pointerShown === true && move.shell.word.keyed === true)));
113
137
  }
114
138
  if (move.seen ? move.pressed : move.over && move.overSince > Math.max(move.typedAt, move.focusedAt)) {
115
139
  return true;
@@ -127,6 +151,17 @@ export function shellGesture(word, hostInputAt, now) {
127
151
  now >= word.activatedAt &&
128
152
  hostInputAt < word.activatedAt);
129
153
  }
154
+ /**
155
+ * Whether the person could have pressed the frame just before `at` (P120): a nested page's shell
156
+ * says its activation turned on, which a key typed into the page does as well as a press. Where the
157
+ * host's page sees the pointer over its frames (`shown`: Firefox; Chromium and WebKit where the frame
158
+ * is in their process, not full Chromium), a press needs the pointer over the frame, come over it
159
+ * since the person last typed on the host's page; within `TYPING_MS` of that typing, an activation
160
+ * with the pointer elsewhere is their keys landing in the page. Anywhere else it may be a press.
161
+ */
162
+ export function pressPossible(shown, over, overSince, typedAt, at) {
163
+ return !shown || at - typedAt > TYPING_MS || (over && overSince > typedAt);
164
+ }
130
165
  /** Keys that type nothing on their own: they don't count as typing (a gesture still). */
131
166
  const MODIFIERS = new Set(["Shift", "Control", "Alt", "Meta", "AltGraph", "CapsLock", "Fn"]);
132
167
  /** The `<input>` types that take typed text (an unknown type is `text`). */
@@ -167,6 +202,25 @@ export function focusGuard(view) {
167
202
  let focusedAt = now();
168
203
  let lastKey = null;
169
204
  let typedAt = -Infinity;
205
+ /** When the person typed on the host's page, the last two seconds of it (P122). */
206
+ const typings = [];
207
+ const typed = (at) => {
208
+ typedAt = at;
209
+ typings.push(at);
210
+ while (typings.length > 0 && at - typings[0] > 2 * TYPING_MS) {
211
+ typings.shift();
212
+ }
213
+ };
214
+ /** The person's last typing on the host's page at or before `at` (-Infinity: none known). */
215
+ const typedBefore = (at) => {
216
+ for (let index = typings.length - 1; index >= 0; index -= 1) {
217
+ const each = typings[index];
218
+ if (each <= at) {
219
+ return each;
220
+ }
221
+ }
222
+ return -Infinity;
223
+ };
170
224
  let gestureAt = -Infinity;
171
225
  let pressAt = -Infinity;
172
226
  /** The host's page's last trusted press or key (P111: a nested page's gesture must be later). */
@@ -177,6 +231,13 @@ export function focusGuard(view) {
177
231
  * whether the frame is the person's for a gesture gate).
178
232
  */
179
233
  let waiting = null;
234
+ /**
235
+ * Whether the host's page sees the pointer over its frames (P120): learned once the pointer comes
236
+ * over one (`pointerover` on its element: Firefox, and Chromium and WebKit where frames are in their
237
+ * process), or a move from a text field into one doesn't blur the window (Firefox, which shows
238
+ * the pointer over a frame, measured). Full Chromium shows neither, and never learns it.
239
+ */
240
+ let pointerShown = false;
180
241
  /** When focus last went into a guarded frame, and whether the person moved it there. */
181
242
  let enteredAt = -Infinity;
182
243
  let earned = false;
@@ -187,7 +248,9 @@ export function focusGuard(view) {
187
248
  /**
188
249
  * A take-back in progress: the field focus goes back to, the frame it came from, when focus was
189
250
  * last given back, and since when it has stayed in the field. Ends once it has stayed `HELD_MS`,
190
- * the person moves focus somewhere of their own, or the field or frame is gone.
251
+ * the person moves focus somewhere of their own, or the field or frame is gone. A `fight` undoes
252
+ * the page's own move (a take-back, `focusField`, or the person leaving a frame that took focus
253
+ * itself), not the person leaving a frame they moved into (P120).
191
254
  */
192
255
  let contest = null;
193
256
  const activation = () => {
@@ -202,15 +265,19 @@ export function focusGuard(view) {
202
265
  };
203
266
  /**
204
267
  * What the person's move would need, read now: see `personMoved`. Into a nested page's frame
205
- * whose shell hasn't spoken of this move yet, `wait` (P111).
268
+ * whose shell hasn't spoken of this move yet, `wait` (P111). In a fight over a text field
269
+ * (`fight`, P120), a nested page's frame is judged as any frame is, its shell's word not asked:
270
+ * an activation it says turned on then is the person's keys landing in it far more often than a
271
+ * press (a press back into the page within `HELD_MS` of focus landing in the field).
206
272
  */
207
- const judge = (frame, guarded, seen, at) => {
208
- const word = guarded.word;
273
+ const judge = (frame, guarded, seen, at, fight = false) => {
274
+ const word = fight ? null : guarded.word;
275
+ const over = frame.matches(":hover");
209
276
  const moved = personMoved({
210
277
  now: at,
211
278
  seen,
212
279
  pressed: frame.matches(":active"),
213
- over: frame.matches(":hover"),
280
+ over,
214
281
  overSince: guarded.overSince,
215
282
  lastKey,
216
283
  typedAt,
@@ -218,19 +285,31 @@ export function focusGuard(view) {
218
285
  gestureAt,
219
286
  activation: activation(),
220
287
  hostMoved: hostMove !== null && hostMove.frame === frame && at - hostMove.at <= TAB_MS,
221
- ...(word === null ? {} : { shell: { word, hostInputAt: inputAt } }),
288
+ ...(word === null ? {} : { shell: { word, hostInputAt: inputAt, pointerShown } }),
222
289
  });
223
290
  hostMove = null;
224
291
  // The shell tells a move at its next frame, the host's page hears it first: until the shell
225
- // said focus came in (around now), its activation may be on its way.
226
- if (!moved && word !== null && word.supported && word.focusedAt < at - SHELL_EARLY_MS) {
292
+ // said focus came in (around now), its activation may be on its way; unless no press could
293
+ // have made the move (P120), which nothing the shell says changes.
294
+ if (!moved &&
295
+ word !== null &&
296
+ word.supported &&
297
+ word.focusedAt < at - SHELL_EARLY_MS &&
298
+ at - typedAt >= KEY_PRESS_MS &&
299
+ pressPossible(pointerShown, over, guarded.overSince, typedAt, at)) {
227
300
  return "wait";
228
301
  }
229
302
  return moved;
230
303
  };
231
304
  /** Waits for a nested page's shell's word on a move (P111): decided by `settle`. */
232
- const wait = (field, frame, guarded, at, failed) => {
233
- waiting = { field, frame, guarded, since: at, failed };
305
+ const wait = (field, frame, guarded, at) => {
306
+ waiting = { field, frame, guarded, since: at };
307
+ // The shell looks at its next frame, and a key the person types into the page before then
308
+ // turns its activation on as a press does: asked to look now, it says what it saw as the move
309
+ // was heard (P120).
310
+ guarded.asked += 1;
311
+ guarded.answered = false;
312
+ guarded.ask?.(guarded.asked);
234
313
  known = frame;
235
314
  enteredAt = at;
236
315
  earned = false;
@@ -246,15 +325,34 @@ export function focusGuard(view) {
246
325
  return;
247
326
  }
248
327
  const { field, frame, guarded } = held;
249
- if (deepActive(document) !== frame || !frames.has(frame)) {
250
- // Moved on since: from the frame, as the next look judges it.
328
+ const active = deepActive(document);
329
+ if (active !== frame || !frames.has(frame)) {
251
330
  waiting = null;
331
+ // Moved on since to nothing, or back to the field, with no press of the person's on the
332
+ // host's page: still the page's move from that field (P120, after the audit of P111's guard:
333
+ // NG-1, where the frame took it again at once and was then let be), watched as a take-back
334
+ // is, focus on nothing given back and counted.
335
+ if (field !== null &&
336
+ field.isConnected &&
337
+ pressAt <= held.since &&
338
+ (active === null || active === document.body || active === field)) {
339
+ known = field;
340
+ contest = { field, frame, guarded, fight: true, gaveAt: held.since, heldSince: null };
341
+ schedule();
342
+ return;
343
+ }
344
+ // Anywhere else: from the frame, as the next look judges it.
252
345
  known = frame;
253
346
  return;
254
347
  }
255
348
  const word = guarded.word;
256
- const theirs = word !== null && shellGesture(word, inputAt, at);
257
- const spoke = word !== null && word.focusedAt >= held.since - SHELL_EARLY_MS;
349
+ // The shell's activation, where a press could have made it: within a second of the person's
350
+ // typing on the host's page with the pointer elsewhere, it is their keys landing in the page
351
+ // (P120). Read as of the move.
352
+ const theirs = word !== null && shellGesture(word, inputAt, at) && !(pointerShown && word.keyed === true);
353
+ // It said focus came in around the move, or answered the ask the move made with focus in it.
354
+ const spoke = word !== null &&
355
+ (word.focusedAt >= held.since - SHELL_EARLY_MS || (guarded.answered && word.focused));
258
356
  if (theirs) {
259
357
  waiting = null;
260
358
  known = frame;
@@ -266,7 +364,7 @@ export function focusGuard(view) {
266
364
  }
267
365
  waiting = null;
268
366
  if (field !== null && field.isConnected) {
269
- takeBack(field, frame, guarded, at, held.failed);
367
+ takeBack(field, frame, guarded, at, false);
270
368
  }
271
369
  };
272
370
  /**
@@ -289,7 +387,7 @@ export function focusGuard(view) {
289
387
  // Until it is back, the field counts as the page's focus, so a move that didn't take is seen.
290
388
  known = field;
291
389
  focusedAt = at;
292
- contest = { field, frame, guarded, gaveAt: at, heldSince: null };
390
+ contest = { field, frame, guarded, fight: true, gaveAt: at, heldSince: null };
293
391
  giveBack(field, frame);
294
392
  schedule();
295
393
  const take = { typing: at - typedAt <= TYPING_MS, failed };
@@ -337,7 +435,10 @@ export function focusGuard(view) {
337
435
  return false;
338
436
  }
339
437
  if (active === frame) {
340
- const verdict = judge(frame, guarded, seen, at);
438
+ // The frame has it again. In a fight, the person's only by a Tab, the host's own move, or a
439
+ // press the engine shows: a nested page's too, its shell's word not asked (P120, after the
440
+ // audit of P111's guard, NG-1, where waiting for it let the frame keep the keyboard).
441
+ const verdict = judge(frame, guarded, seen, at, watched.fight);
341
442
  if (verdict === true) {
342
443
  contest = null;
343
444
  known = frame;
@@ -346,10 +447,11 @@ export function focusGuard(view) {
346
447
  return true;
347
448
  }
348
449
  if (verdict === "wait") {
349
- // A nested page's frame took it again (P111): its shell decides, as it would at first.
450
+ // The person left a nested page they had moved into, and focus went back in (P111): its
451
+ // shell decides, as it would at first.
350
452
  if (watched.heldSince !== null || at - watched.gaveAt >= GIVE_BACK_MS) {
351
453
  contest = null;
352
- wait(field, frame, guarded, at, true);
454
+ wait(field, frame, guarded, at);
353
455
  }
354
456
  return true;
355
457
  }
@@ -406,7 +508,7 @@ export function focusGuard(view) {
406
508
  const verdict = takesText(was) || judge(active, entered, seen, at);
407
509
  if (verdict === "wait") {
408
510
  // A nested page's (P111): theirs once its shell says so; nothing to take back.
409
- wait(null, active, entered, at, false);
511
+ wait(null, active, entered, at);
410
512
  return;
411
513
  }
412
514
  earned = verdict;
@@ -420,6 +522,7 @@ export function focusGuard(view) {
420
522
  field: active,
421
523
  frame: was,
422
524
  guarded: left,
525
+ fight: !earned,
423
526
  gaveAt: at,
424
527
  heldSince: at,
425
528
  };
@@ -430,12 +533,17 @@ export function focusGuard(view) {
430
533
  return;
431
534
  }
432
535
  const frame = active;
536
+ if (!seen) {
537
+ // A move out of a text field the window didn't blur for: Firefox, which shows the host's
538
+ // page the pointer over a frame (P120).
539
+ pointerShown = true;
540
+ }
433
541
  const verdict = judge(frame, guarded, seen, at);
434
542
  if (verdict === true) {
435
543
  return;
436
544
  }
437
545
  if (verdict === "wait") {
438
- wait(was, frame, guarded, at, false);
546
+ wait(was, frame, guarded, at);
439
547
  return;
440
548
  }
441
549
  takeBack(was, frame, guarded, at, false);
@@ -478,7 +586,7 @@ export function focusGuard(view) {
478
586
  inputAt = at;
479
587
  }
480
588
  if (event.key !== "Tab" && !MODIFIERS.has(event.key)) {
481
- typedAt = at;
589
+ typed(at);
482
590
  }
483
591
  }, true);
484
592
  // A click too (an assistive technology's click on the host's own UI dispatches no press), and
@@ -490,7 +598,7 @@ export function focusGuard(view) {
490
598
  view.addEventListener(type, press, true);
491
599
  }
492
600
  view.addEventListener("input", () => {
493
- typedAt = now();
601
+ typed(now());
494
602
  gestureAt = typedAt;
495
603
  }, true);
496
604
  // Focus moving within the page: what had it, for the next move out of a text field.
@@ -517,12 +625,16 @@ export function focusGuard(view) {
517
625
  taken: new Set(),
518
626
  overSince: -Infinity,
519
627
  heardAt: -Infinity,
628
+ ask: options?.nested === true ? options.ask : undefined,
629
+ asked: 0,
630
+ answered: false,
520
631
  word: options?.nested === true
521
632
  ? { supported: true, activatedAt: -Infinity, focused: false, focusedAt: -Infinity }
522
633
  : null,
523
634
  };
524
635
  frame.addEventListener("pointerover", () => {
525
636
  entry.overSince = now();
637
+ pointerShown = true;
526
638
  });
527
639
  frames.set(frame, entry);
528
640
  guarded = entry;
@@ -545,17 +657,42 @@ export function focusGuard(view) {
545
657
  }
546
658
  const at = now();
547
659
  // Off to on after a stall, the shell's or the host's (no word for longer than its beat
548
- // allows): uncertain, and so until it goes off (P111, after its review).
660
+ // allows): uncertain, and so until it goes off (P111, after its review). So is one that
661
+ // turned on while the guard fights this frame for a text field (P120): the person's keys,
662
+ // meant for the field, landing in the page.
663
+ // So is one that turned on within `KEY_PRESS_MS` of a key the person typed on the host's page
664
+ // before it (P122): that key's successor, landing in the page.
549
665
  const turnedOn = said.ago !== null && before.activatedAt === -Infinity && !before.uncertain;
550
666
  const stalled = said.gap > SHELL_STALL_MS || at - guarded.heardAt > SHELL_STALL_MS;
551
- const uncertain = said.ago !== null && (before.uncertain === true || (turnedOn && stalled));
667
+ const fought = contest !== null && contest.fight && contest.frame === frame;
668
+ // The typing before it, never after: a key the person typed on the host's page after they
669
+ // pressed the page, before the shell's word came, says nothing of that press (P122, after
670
+ // CI). The shell saw it turn on at its look, so it turned on at most a look's gap before:
671
+ // only a key before then counts.
672
+ const turnedAt = said.ago === null ? -Infinity : at - said.ago - Math.min(said.gap, SHELL_STALL_MS);
673
+ const typing = typedBefore(turnedAt);
674
+ const soon = said.ago !== null && turnedAt - typing < KEY_PRESS_MS;
675
+ const uncertain = said.ago !== null &&
676
+ (before.uncertain === true || (turnedOn && (stalled || fought || soon)));
552
677
  guarded.heardAt = at;
678
+ if (said.asked !== undefined && said.asked === guarded.asked) {
679
+ guarded.answered = true;
680
+ }
681
+ // Whether a press could have turned it on, judged as it did (P120, after its review): the
682
+ // person's typing then, and the pointer then, not when a move is later judged.
683
+ const activatedAt = said.ago === null || uncertain ? -Infinity : at - said.ago;
684
+ const keyed = activatedAt === -Infinity
685
+ ? false
686
+ : turnedOn
687
+ ? !pressPossible(true, frame.matches(":hover"), guarded.overSince, typing, turnedAt)
688
+ : before.keyed === true;
553
689
  guarded.word = {
554
690
  supported: said.supported,
555
- activatedAt: said.ago === null || uncertain ? -Infinity : at - said.ago,
691
+ activatedAt,
556
692
  focused: said.focused,
557
693
  focusedAt: said.focused && !before.focused ? at : before.focusedAt,
558
694
  ...(uncertain ? { uncertain: true } : {}),
695
+ ...(keyed ? { keyed: true } : {}),
559
696
  };
560
697
  if (waiting?.frame === frame) {
561
698
  settle(at);
@@ -568,8 +705,15 @@ export function focusGuard(view) {
568
705
  }
569
706
  },
570
707
  gesture(frame) {
571
- const word = frames.get(frame)?.word ?? null;
572
- return word !== null && shellGesture(word, inputAt, now());
708
+ const guarded = frames.get(frame);
709
+ const word = guarded?.word ?? null;
710
+ const at = now();
711
+ // Where a press could have made it (P120): a key the person typed into the page, meant for
712
+ // the host's composer, turns the shell's activation on too.
713
+ return (guarded !== undefined &&
714
+ word !== null &&
715
+ shellGesture(word, inputAt, at) &&
716
+ !(pointerShown && word.keyed === true));
573
717
  },
574
718
  focus(frame) {
575
719
  hostMove = { frame, at: now() };
@@ -596,7 +740,7 @@ export function focusGuard(view) {
596
740
  field.focus({ preventScroll: true });
597
741
  known = field;
598
742
  focusedAt = now();
599
- contest = { field, frame, guarded, gaveAt: focusedAt, heldSince: null };
743
+ contest = { field, frame, guarded, fight: true, gaveAt: focusedAt, heldSince: null };
600
744
  schedule();
601
745
  },
602
746
  };