@botiverse/porthole 0.14.3 → 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.
- package/CHANGELOG.md +59 -0
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/locate.d.ts +1 -1
- package/dist/host/locate.js +2 -2
- package/dist/isolation/served.d.ts +17 -1
- package/dist/isolation/served.js +24 -1
- package/dist/isolation/types.d.ts +5 -0
- package/dist/isolation/types.js +5 -0
- package/dist/platform/focus-guard.d.ts +40 -0
- package/dist/platform/focus-guard.js +176 -32
- package/dist/platform/web.js +24 -9
- package/dist/server/files.js +7 -7
- package/dist/server/index.d.ts +1 -1
- package/dist/server/index.js +1 -1
- package/dist/server/nested.d.ts +13 -7
- package/dist/server/nested.js +31 -9
- package/dist/server/server.js +5 -2
- package/dist/shell/frame.d.ts +5 -2
- package/dist/shell/frame.js +41 -18
- package/docs/ADOPTING.md +32 -14
- package/docs/ARCHITECTURE.md +5 -1
- package/docs/DECISIONS.md +312 -2
- package/docs/DESIGN.md +8 -3
- package/docs/THREAT_MODEL.md +85 -30
- package/package.json +1 -1
- package/src/host/locate.ts +2 -2
- package/src/isolation/served.ts +29 -0
- package/src/isolation/types.ts +6 -0
- package/src/platform/focus-guard.ts +218 -34
- package/src/platform/web.ts +29 -12
- package/src/server/files.ts +5 -6
- package/src/server/index.ts +1 -0
- package/src/server/nested.ts +44 -12
- package/src/server/server.ts +5 -4
- package/src/shell/frame.ts +43 -18
package/dist/host/locate.d.ts
CHANGED
|
@@ -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>;
|
package/dist/host/locate.js
CHANGED
|
@@ -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
|
|
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 {};
|
package/dist/isolation/served.js
CHANGED
|
@@ -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. */
|
package/dist/isolation/types.js
CHANGED
|
@@ -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)
|
|
110
|
-
//
|
|
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) ||
|
|
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
|
|
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
|
-
|
|
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
|
|
233
|
-
waiting = { field, frame, guarded, since: at
|
|
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
|
-
|
|
250
|
-
|
|
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
|
-
|
|
257
|
-
|
|
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,
|
|
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
|
-
|
|
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
|
-
//
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
572
|
-
|
|
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
|
};
|