@botiverse/porthole 0.14.3 → 0.14.5
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 +77 -0
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +2 -0
- package/dist/host/locate.d.ts +1 -1
- package/dist/host/locate.js +2 -2
- package/dist/host/outcome.d.ts +4 -0
- package/dist/host/outcome.js +43 -0
- package/dist/host/types.d.ts +12 -4
- 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/react/frame.d.ts +2 -1
- 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 +37 -14
- package/docs/ARCHITECTURE.md +5 -1
- package/docs/DECISIONS.md +404 -2
- package/docs/DESIGN.md +11 -4
- package/docs/THREAT_MODEL.md +116 -32
- package/package.json +1 -1
- package/src/host/create-host.ts +2 -0
- package/src/host/locate.ts +2 -2
- package/src/host/outcome.ts +49 -0
- package/src/host/types.ts +12 -4
- 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/react/frame.tsx +2 -1
- 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/create-host.js
CHANGED
|
@@ -514,6 +514,8 @@ export function createHost(config, options = {}) {
|
|
|
514
514
|
speaks,
|
|
515
515
|
timeoutMs: config.limits.loadTimeoutMs ?? DEFAULT_LOAD_TIMEOUT_MS,
|
|
516
516
|
onOutcome: (outcome) => emit("outcome", outcome),
|
|
517
|
+
// A frame status from the content (P124): never shown, the host's to hear.
|
|
518
|
+
refused: (message) => hostError(message, "frame-status"),
|
|
517
519
|
});
|
|
518
520
|
outcomeWatch = watch;
|
|
519
521
|
if (!speaks) {
|
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);
|
package/dist/host/outcome.d.ts
CHANGED
|
@@ -9,6 +9,8 @@ interface FrameStatus {
|
|
|
9
9
|
}
|
|
10
10
|
/** A frame-status message, or null for anything else. */
|
|
11
11
|
export declare function parseFrameStatus(data: unknown): FrameStatus | null;
|
|
12
|
+
/** What the host is told of a frame status it didn't take (P124). */
|
|
13
|
+
export declare const UNTRUSTED_FRAME_STATUS = "A frame status (porthole/notifications/frame-status) came from the frame's content, not from a page of Porthole's server: not taken (P124)";
|
|
12
14
|
export interface OutcomeWatch {
|
|
13
15
|
/** The frame finished its handshake. */
|
|
14
16
|
initialized(): void;
|
|
@@ -21,5 +23,7 @@ export declare function watchOutcome(options: {
|
|
|
21
23
|
readonly speaks: boolean;
|
|
22
24
|
readonly timeoutMs: number;
|
|
23
25
|
readonly onOutcome: (outcome: FrameOutcome) => void;
|
|
26
|
+
/** A frame status that wasn't taken, once a run (P124): the host's to hear, never shown. */
|
|
27
|
+
readonly refused?: (message: string) => void;
|
|
24
28
|
}): OutcomeWatch;
|
|
25
29
|
export {};
|
package/dist/host/outcome.js
CHANGED
|
@@ -12,6 +12,27 @@ import { FRAME_STATUS_METHOD } from "../isolation/types.js";
|
|
|
12
12
|
* - an app from a host's own gateway is loaded on its first load, unless its page says it is
|
|
13
13
|
* blocked (the gateway may send the same message);
|
|
14
14
|
* - nothing settled in `timeoutMs`: a timeout.
|
|
15
|
+
*
|
|
16
|
+
* Who may say how loading went (P124). A frame status is taken only from a document of Porthole's
|
|
17
|
+
* server, a host's gateway or the host's own pages, never from content: its words draw the host's
|
|
18
|
+
* fallback, in Porthole's wording, with a link. Nothing in a message tells who sent it (a page
|
|
19
|
+
* that shares the frame's window and origin can send the same bytes), so the host goes by what
|
|
20
|
+
* content can't change: where the frame's documents come from, and in what order they speak.
|
|
21
|
+
*
|
|
22
|
+
* - An opaque frame's only document is the host's own shell, with the content in it: no page of
|
|
23
|
+
* Porthole's server ever loads there, so its every frame status is the content's.
|
|
24
|
+
* - A frame that speaks (a served shell, a view through the sandbox proxy, a nested page's shell)
|
|
25
|
+
* says Porthole's own word first in every document that holds content, before any of the
|
|
26
|
+
* content's code runs: the shell's hello, the proxy's ready (a nested page's own runtime's hello
|
|
27
|
+
* reaches the host before anything its page says, through its shell). A status page says
|
|
28
|
+
* nothing but its frame status. So a frame status is taken only before anything else was heard
|
|
29
|
+
* from the frame in this run: from its first document, which then was a page of Porthole's.
|
|
30
|
+
* After that, it came from the content (or from a later document, which in a display without
|
|
31
|
+
* files starts the display again, whose first document then says how it went).
|
|
32
|
+
* - A url-mode app has no shell to speak first, and shares its origin with the entry page and the
|
|
33
|
+
* status pages: its frame status is taken as before, the app's word (THREAT_MODEL S6).
|
|
34
|
+
*
|
|
35
|
+
* A frame status not taken is dropped, and told once a run to the host (`refused`).
|
|
15
36
|
*/
|
|
16
37
|
/** How long after a load the frame's word may still arrive. */
|
|
17
38
|
const SETTLE_MS = 400;
|
|
@@ -58,12 +79,21 @@ export function parseFrameStatus(data) {
|
|
|
58
79
|
: {}),
|
|
59
80
|
};
|
|
60
81
|
}
|
|
82
|
+
/** Whether a message names the frame-status method, well formed or not. */
|
|
83
|
+
const namesFrameStatus = (data) => data !== null &&
|
|
84
|
+
typeof data === "object" &&
|
|
85
|
+
data.method === FRAME_STATUS_METHOD;
|
|
86
|
+
/** What the host is told of a frame status it didn't take (P124). */
|
|
87
|
+
export const UNTRUSTED_FRAME_STATUS = "A frame status (porthole/notifications/frame-status) came from the frame's content, not from a page of Porthole's server: not taken (P124)";
|
|
61
88
|
export function watchOutcome(options) {
|
|
62
89
|
const { surface, source, speaks } = options;
|
|
63
90
|
const reports = source.kind === "url" && source.reports === true;
|
|
64
91
|
// The first outcome; after a load, only a later block (a status page, access revoked) is told.
|
|
65
92
|
let decided = null;
|
|
66
93
|
let heard = false;
|
|
94
|
+
// Whether the frame said anything but a frame status in this run (P124).
|
|
95
|
+
let spoke = false;
|
|
96
|
+
let told = false;
|
|
67
97
|
let entering = false;
|
|
68
98
|
let loads = 0;
|
|
69
99
|
const timers = new Set();
|
|
@@ -96,8 +126,21 @@ export function watchOutcome(options) {
|
|
|
96
126
|
options.onOutcome(outcome);
|
|
97
127
|
}
|
|
98
128
|
};
|
|
129
|
+
// Whether a frame status may be the word of a page of Porthole's (P124, above).
|
|
130
|
+
const mayBePorthole = () => source.kind === "url" && (!speaks || !spoke);
|
|
99
131
|
const unlisten = surface.transport.listen((data) => {
|
|
100
132
|
heard = true;
|
|
133
|
+
if (!namesFrameStatus(data)) {
|
|
134
|
+
spoke = true;
|
|
135
|
+
return;
|
|
136
|
+
}
|
|
137
|
+
if (!mayBePorthole()) {
|
|
138
|
+
if (!told) {
|
|
139
|
+
told = true;
|
|
140
|
+
options.refused?.(UNTRUSTED_FRAME_STATUS);
|
|
141
|
+
}
|
|
142
|
+
return;
|
|
143
|
+
}
|
|
101
144
|
const status = parseFrameStatus(data);
|
|
102
145
|
if (status?.state === "entering") {
|
|
103
146
|
entering = true;
|
package/dist/host/types.d.ts
CHANGED
|
@@ -117,7 +117,13 @@ export type HostErrorKind =
|
|
|
117
117
|
/** A display couldn't be made (the React binding: a bad config, a missing handler). */
|
|
118
118
|
| "mount"
|
|
119
119
|
/** An annotation call was refused (an invalid mark, an unknown id). */
|
|
120
|
-
| "annotations"
|
|
120
|
+
| "annotations"
|
|
121
|
+
/**
|
|
122
|
+
* A frame status (`porthole/notifications/frame-status`) the host didn't take, since it came
|
|
123
|
+
* from the frame's content, not from a page of Porthole's server (P124): never shown, never an
|
|
124
|
+
* outcome. Told once a run.
|
|
125
|
+
*/
|
|
126
|
+
| "frame-status";
|
|
121
127
|
/** What a display reports, by event name. */
|
|
122
128
|
/** Why a display's frame showed nothing of its content (`FrameOutcome`). */
|
|
123
129
|
export type FrameBlock =
|
|
@@ -138,9 +144,11 @@ export type FrameBlock =
|
|
|
138
144
|
/**
|
|
139
145
|
* How a display's document went: it loaded (a shell or view finished its handshake; a url-mode
|
|
140
146
|
* app's document loaded), it was blocked (and why), or nothing settled in
|
|
141
|
-
* `limits.loadTimeoutMs`. Once per run, plus a later `blocked` if
|
|
142
|
-
* after it loaded (access revoked mid-session). A host shows its own fallback ("Open in
|
|
143
|
-
* tab") on anything but loaded.
|
|
147
|
+
* `limits.loadTimeoutMs`. Once per run, plus a later `blocked` if a url-mode app's frame shows a
|
|
148
|
+
* status page after it loaded (access revoked mid-session). A host shows its own fallback ("Open in
|
|
149
|
+
* a new tab") on anything but loaded. A `blocked` is the word of a page of Porthole's server (or a
|
|
150
|
+
* host's gateway, or its own pages), never of a frame's content, except a url-mode app's (P124):
|
|
151
|
+
* in a frame that speaks, only its run's first document says it; an opaque frame never does.
|
|
144
152
|
*/
|
|
145
153
|
export type FrameOutcome = {
|
|
146
154
|
readonly state: "loaded";
|
|
@@ -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;
|