@botiverse/porthole 0.14.12 → 0.14.14
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 +46 -0
- package/dist/annotate/types.d.ts +10 -4
- package/dist/annotate/types.js +4 -1
- package/dist/annotate/validate.js +19 -4
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +2 -1
- package/dist/host/types.d.ts +9 -0
- package/dist/isolation/types.d.ts +6 -0
- package/dist/isolation/types.js +6 -0
- package/dist/platform/web.js +6 -1
- package/dist/react/frame.d.ts +4 -1
- package/dist/shell/annotate.d.ts +12 -1
- package/dist/shell/annotate.js +39 -5
- package/dist/shell/frame.d.ts +6 -1
- package/dist/shell/frame.js +45 -5
- package/docs/ADOPTING.md +53 -4
- package/docs/ARCHITECTURE.md +1 -0
- package/docs/DECISIONS.md +454 -4
- package/docs/DESIGN.md +21 -5
- package/docs/THREAT_MODEL.md +51 -8
- package/package.json +1 -1
- package/src/annotate/types.ts +10 -4
- package/src/annotate/validate.ts +23 -4
- package/src/host/create-host.ts +2 -1
- package/src/host/types.ts +9 -0
- package/src/isolation/types.ts +7 -0
- package/src/platform/web.ts +6 -0
- package/src/react/frame.tsx +4 -1
- package/src/shell/annotate.ts +40 -5
- package/src/shell/frame.ts +45 -5
package/dist/host/create-host.js
CHANGED
|
@@ -581,9 +581,10 @@ export function createHost(config, options = {}) {
|
|
|
581
581
|
focusMark(id) {
|
|
582
582
|
// Host → frame only, and kept for no later frame (P134). A mark that has gone, or has no
|
|
583
583
|
// marker, is nothing to ask for, and no fault: the host's card closed with the mark's.
|
|
584
|
+
// Stamped as it is sent: a frame judges by that how old the word is as it takes it (P137).
|
|
584
585
|
needsAnnotate("focusMark");
|
|
585
586
|
if (marks.some((mark) => mark.id === id && hasMarker(mark))) {
|
|
586
|
-
toFrame(ANNOTATE_METHODS.focusMark, { id });
|
|
587
|
+
toFrame(ANNOTATE_METHODS.focusMark, { id, at: Date.now() });
|
|
587
588
|
}
|
|
588
589
|
},
|
|
589
590
|
};
|
package/dist/host/types.d.ts
CHANGED
|
@@ -335,6 +335,15 @@ export interface AnnotationControls {
|
|
|
335
335
|
* Call it once the view is closed: from one of the page's text fields that still has focus, the
|
|
336
336
|
* move is the frame's own to the focus guard, undone and counted (P109). The page can take the
|
|
337
337
|
* focus back at once. Not kept for a frame that runs later.
|
|
338
|
+
*
|
|
339
|
+
* On a calm page it lands at once, from anywhere on the host's page. While the frame is finding
|
|
340
|
+
* its marks (a `show` just sent, the content just changed) it waits, and is then dropped unless
|
|
341
|
+
* the focus is in the frame by then (P135). One the frame takes more than 100 ms after you sent
|
|
342
|
+
* it (its page is busy) is held to the same test (P137), so a word that comes late takes no
|
|
343
|
+
* keyboard from a person who moved on. Nothing says it was dropped: if the frame isn't your page's
|
|
344
|
+
* `document.activeElement` soon after and the person hasn't moved on, call `focus()` and then
|
|
345
|
+
* `focusMark(id)` again. On a nested page only `focus()` reaches the page (P136): the frame's own
|
|
346
|
+
* `focus()` stops at its shell, and a second call that waits is dropped.
|
|
338
347
|
*/
|
|
339
348
|
focusMark(id: string): void;
|
|
340
349
|
}
|
|
@@ -103,6 +103,12 @@ export declare const SHELL_BEAT_METHOD = "porthole/shell/beat";
|
|
|
103
103
|
* that names the ask (`asked`). The host asks as it hears focus move into the frame.
|
|
104
104
|
*/
|
|
105
105
|
export declare const SHELL_LOOK_METHOD = "porthole/shell/look";
|
|
106
|
+
/**
|
|
107
|
+
* The host's word to a nested page's shell (P136) that it moved the focus into the frame: pass it on
|
|
108
|
+
* to the page, in this task, not in the focus event (where the shell's move doesn't take). Sent by
|
|
109
|
+
* `display.focus()` alone; a page has no way to say it.
|
|
110
|
+
*/
|
|
111
|
+
export declare const SHELL_FOCUS_METHOD = "porthole/shell/focus";
|
|
106
112
|
/** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
|
|
107
113
|
export declare const SHELL_METHOD_PREFIX = "porthole/shell/";
|
|
108
114
|
/** A page's word that it used storage, once per load (P111): never a key or a value. */
|
package/dist/isolation/types.js
CHANGED
|
@@ -11,6 +11,12 @@ export const SHELL_BEAT_METHOD = "porthole/shell/beat";
|
|
|
11
11
|
* that names the ask (`asked`). The host asks as it hears focus move into the frame.
|
|
12
12
|
*/
|
|
13
13
|
export const SHELL_LOOK_METHOD = "porthole/shell/look";
|
|
14
|
+
/**
|
|
15
|
+
* The host's word to a nested page's shell (P136) that it moved the focus into the frame: pass it on
|
|
16
|
+
* to the page, in this task, not in the focus event (where the shell's move doesn't take). Sent by
|
|
17
|
+
* `display.focus()` alone; a page has no way to say it.
|
|
18
|
+
*/
|
|
19
|
+
export const SHELL_FOCUS_METHOD = "porthole/shell/focus";
|
|
14
20
|
/** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
|
|
15
21
|
export const SHELL_METHOD_PREFIX = "porthole/shell/";
|
|
16
22
|
/** A page's word that it used storage, once per load (P111): never a key or a value. */
|
package/dist/platform/web.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { DOOR_SANDBOX_TOKENS } from "../compile/policy.js";
|
|
2
|
-
import { SHELL_BEAT_METHOD, SHELL_LOOK_METHOD, SHELL_METHOD_PREFIX, SHELL_STATE_METHOD, } from "../isolation/types.js";
|
|
2
|
+
import { SHELL_BEAT_METHOD, SHELL_FOCUS_METHOD, SHELL_LOOK_METHOD, SHELL_METHOD_PREFIX, SHELL_STATE_METHOD, } from "../isolation/types.js";
|
|
3
3
|
import { postMessageTransport } from "../transport/post-message.js";
|
|
4
4
|
import { focusGuard } from "./focus-guard.js";
|
|
5
5
|
/** A shell's own message (P111), by its namespace. */
|
|
@@ -169,6 +169,11 @@ export const webPlatform = {
|
|
|
169
169
|
},
|
|
170
170
|
focus() {
|
|
171
171
|
guard.focus(frame);
|
|
172
|
+
// A nested page (P136): the move stops at its shell on every engine, one way or another,
|
|
173
|
+
// and only the shell can pass it on. Only a move that landed: the shell asks no more of it.
|
|
174
|
+
if (nested && view.document.activeElement === frame) {
|
|
175
|
+
opened.send({ jsonrpc: "2.0", method: SHELL_FOCUS_METHOD });
|
|
176
|
+
}
|
|
172
177
|
},
|
|
173
178
|
onLoad(listener) {
|
|
174
179
|
loaded.add(listener);
|
package/dist/react/frame.d.ts
CHANGED
|
@@ -157,7 +157,10 @@ export interface PortholeFrameHandle {
|
|
|
157
157
|
/**
|
|
158
158
|
* Puts the keyboard back on a mark's marker in the frame (`annotations.focusMark(id)`, P134),
|
|
159
159
|
* once Escape closed your own view of that mark. Nothing happens for an id with no marker, or
|
|
160
|
-
* while no display runs. A config without `annotate`: `onHostError`, kind `"annotations"`.
|
|
160
|
+
* while no display runs. A config without `annotate`: `onHostError`, kind `"annotations"`. While
|
|
161
|
+
* the frame is finding its marks it waits, and is dropped unless the focus is in the frame by
|
|
162
|
+
* then (P135), and so is one a busy page takes late (P137): call it again after your own move of
|
|
163
|
+
* the focus into the frame.
|
|
161
164
|
*/
|
|
162
165
|
focusMark(id: string): void;
|
|
163
166
|
/**
|
package/dist/shell/annotate.d.ts
CHANGED
|
@@ -16,6 +16,16 @@ export declare const MARKER_HIT: string;
|
|
|
16
16
|
* `alt`) what follows the tag in the label. An element with neither has no words.
|
|
17
17
|
*/
|
|
18
18
|
export declare const MARKER_NAME: string;
|
|
19
|
+
/**
|
|
20
|
+
* Whether a host's `focusMark` is too old to land unasked (P137): `at` is the host's `Date.now()` as
|
|
21
|
+
* it sent the word, `now` the shell's, kept before content runs. Both read the one wall clock of
|
|
22
|
+
* this machine, the only clock two realms share (`performance.now()` counts from each one's own
|
|
23
|
+
* start). No number is an older host's word, which can't be known fresh. A word from ahead of the
|
|
24
|
+
* clock has the same bound behind it: two processes can read the clock a little apart, and past
|
|
25
|
+
* that the clock was set back, and the age says nothing. Comparisons only, nothing a page can
|
|
26
|
+
* patch, and a word that makes no number (`NaN`, `Infinity`) passes neither test.
|
|
27
|
+
*/
|
|
28
|
+
export declare const WORD_LATE: string;
|
|
19
29
|
/**
|
|
20
30
|
* The shell's annotation runtime (P053), spliced into the shell's runtime (`__ANNOTATE__`) when
|
|
21
31
|
* the config declares `annotate`, so it runs before any content does, with the DOM's own
|
|
@@ -39,7 +49,8 @@ export declare const MARKER_NAME: string;
|
|
|
39
49
|
* focus on it (P133), is reported (`activated`), and the content's own handlers never see it; a
|
|
40
50
|
* draft is drawn apart, a dashed line and a hollow bubble with no number, and has a marker with
|
|
41
51
|
* or without a count; the host's `focusMark` (P134) puts the focus on a marker that is there, and
|
|
42
|
-
* tells nothing back;
|
|
52
|
+
* tells nothing back; one that had to wait for the marks (P135), or that this document took late
|
|
53
|
+
* (P137), lands only if the focus is in this document by then;
|
|
43
54
|
* - following: while a mark has a marker, once a scroll, a resize or a change of the content
|
|
44
55
|
* settles, the marks that moved since the host was last told are reported, at most once a
|
|
45
56
|
* second, so the host's own UI beside a mark can follow;
|
package/dist/shell/annotate.js
CHANGED
|
@@ -54,6 +54,22 @@ export const MARKER_NAME = String.raw `(mark) => {
|
|
|
54
54
|
const what = mark.draft ? "Draft comment" : mark.count === 1 ? "1 comment" : mark.count > 1 ? mark.count + " comments" : "Comment";
|
|
55
55
|
return words === "" ? what : what + ' on "' + words + '"';
|
|
56
56
|
}`;
|
|
57
|
+
/**
|
|
58
|
+
* Whether a host's `focusMark` is too old to land unasked (P137): `at` is the host's `Date.now()` as
|
|
59
|
+
* it sent the word, `now` the shell's, kept before content runs. Both read the one wall clock of
|
|
60
|
+
* this machine, the only clock two realms share (`performance.now()` counts from each one's own
|
|
61
|
+
* start). No number is an older host's word, which can't be known fresh. A word from ahead of the
|
|
62
|
+
* clock has the same bound behind it: two processes can read the clock a little apart, and past
|
|
63
|
+
* that the clock was set back, and the age says nothing. Comparisons only, nothing a page can
|
|
64
|
+
* patch, and a word that makes no number (`NaN`, `Infinity`) passes neither test.
|
|
65
|
+
*/
|
|
66
|
+
export const WORD_LATE = String.raw `(at, now) => {
|
|
67
|
+
if (typeof at !== "number") {
|
|
68
|
+
return true;
|
|
69
|
+
}
|
|
70
|
+
const age = now - at;
|
|
71
|
+
return !(age > -100 && age < 100);
|
|
72
|
+
}`;
|
|
57
73
|
/**
|
|
58
74
|
* The shell's annotation runtime (P053), spliced into the shell's runtime (`__ANNOTATE__`) when
|
|
59
75
|
* the config declares `annotate`, so it runs before any content does, with the DOM's own
|
|
@@ -77,7 +93,8 @@ export const MARKER_NAME = String.raw `(mark) => {
|
|
|
77
93
|
* focus on it (P133), is reported (`activated`), and the content's own handlers never see it; a
|
|
78
94
|
* draft is drawn apart, a dashed line and a hollow bubble with no number, and has a marker with
|
|
79
95
|
* or without a count; the host's `focusMark` (P134) puts the focus on a marker that is there, and
|
|
80
|
-
* tells nothing back;
|
|
96
|
+
* tells nothing back; one that had to wait for the marks (P135), or that this document took late
|
|
97
|
+
* (P137), lands only if the focus is in this document by then;
|
|
81
98
|
* - following: while a mark has a marker, once a scroll, a resize or a change of the content
|
|
82
99
|
* settles, the marks that moved since the host was last told are reported, at most once a
|
|
83
100
|
* second, so the host's own UI beside a mark can follow;
|
|
@@ -120,6 +137,8 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
120
137
|
const selectionOf = Document.prototype.getSelection;
|
|
121
138
|
const removeAllRanges = Selection.prototype.removeAllRanges;
|
|
122
139
|
const focusElement = HTMLElement.prototype.focus;
|
|
140
|
+
const hasFocus = Document.prototype.hasFocus;
|
|
141
|
+
const wallClock = Date.now;
|
|
123
142
|
const elementRect = Element.prototype.getBoundingClientRect;
|
|
124
143
|
const rangeRect = Range.prototype.getBoundingClientRect;
|
|
125
144
|
const rangeRects = Range.prototype.getClientRects;
|
|
@@ -1072,6 +1091,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1072
1091
|
let waitingForContent = false;
|
|
1073
1092
|
let pendingFocus = null;
|
|
1074
1093
|
let pendingMarker = null;
|
|
1094
|
+
// Asked through the kept function: a page that says it has the focus gets no landing the
|
|
1095
|
+
// platform would refuse (P135).
|
|
1096
|
+
const focusIsHere = () => callOf(hasFocus, document, []) === true;
|
|
1097
|
+
const wordLate = ${WORD_LATE};
|
|
1075
1098
|
const settling = () => anchorTimer !== 0 || waitingForContent || marks.some((mark) => mark.state === null);
|
|
1076
1099
|
const scheduleAnchor = (all) => {
|
|
1077
1100
|
if (all) {
|
|
@@ -1113,7 +1136,12 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1113
1136
|
if (pendingMarker !== null) {
|
|
1114
1137
|
const id = pendingMarker;
|
|
1115
1138
|
pendingMarker = null;
|
|
1116
|
-
|
|
1139
|
+
// Parked, the host's word is old: the person may have moved on, and a marker's focus
|
|
1140
|
+
// takes the keyboard with no gesture. So it lands only if the focus is still in this
|
|
1141
|
+
// document. Otherwise it is dropped (P135).
|
|
1142
|
+
if (focusIsHere()) {
|
|
1143
|
+
focusMark(id, false);
|
|
1144
|
+
}
|
|
1117
1145
|
}
|
|
1118
1146
|
}, wait);
|
|
1119
1147
|
};
|
|
@@ -1223,8 +1251,11 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1223
1251
|
// markers yet, so it waits for them, as focus does; then a marker that isn't there, or has
|
|
1224
1252
|
// stepped aside for picking, is nothing to do. The kept function, so a page that patched
|
|
1225
1253
|
// focus isn't handed the marker from inside the closed root. The shell's focus listener
|
|
1226
|
-
// lights it and brings it into view; nothing is told.
|
|
1227
|
-
|
|
1254
|
+
// lights it and brings it into view; nothing is told. A fresh word reads no focus: after the
|
|
1255
|
+
// host's card closed the focus is on the host's body, so this document has none yet. One
|
|
1256
|
+
// parked is asked as it lands (P135), and one this document took late (P137: late, by when
|
|
1257
|
+
// the host sent it: a busy page doesn't park it) is asked here: its moment has passed.
|
|
1258
|
+
const focusMark = (id, late) => {
|
|
1228
1259
|
if (settling()) {
|
|
1229
1260
|
pendingMarker = id;
|
|
1230
1261
|
return;
|
|
@@ -1232,6 +1263,9 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1232
1263
|
if (mode.elements || !isShown(id)) {
|
|
1233
1264
|
return;
|
|
1234
1265
|
}
|
|
1266
|
+
if (late && !focusIsHere()) {
|
|
1267
|
+
return;
|
|
1268
|
+
}
|
|
1235
1269
|
for (let i = 0; i < markers.length; i += 1) {
|
|
1236
1270
|
if (markers[i].id === id) {
|
|
1237
1271
|
callOf(focusElement, markers[i].element, [{ preventScroll: true }]);
|
|
@@ -1675,7 +1709,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1675
1709
|
break;
|
|
1676
1710
|
}
|
|
1677
1711
|
case M.focusMark:
|
|
1678
|
-
focusMark(String(params.id));
|
|
1712
|
+
focusMark(String(params.id), wordLate(params.at, callOf(wallClock, undefined, [])));
|
|
1679
1713
|
break;
|
|
1680
1714
|
case M.clear:
|
|
1681
1715
|
track(null);
|
package/dist/shell/frame.d.ts
CHANGED
|
@@ -23,7 +23,12 @@
|
|
|
23
23
|
* - renews the page's sealed files' address before it ends, and gives the page the new one
|
|
24
24
|
* (`porthole/files-renewed`): the page's own loads aren't its origin's (an opaque origin's never
|
|
25
25
|
* are), so only the shell, on that origin, may renew it (P083);
|
|
26
|
-
* - passes its focus to the page
|
|
26
|
+
* - passes its focus to the page: at the focus event where that takes (Firefox, from the host's
|
|
27
|
+
* `<body>`), and on the host's word that it moved it there (`porthole/shell/focus`, P136), where
|
|
28
|
+
* it doesn't: a frame's move inside the focus event that made it the focused frame sets the
|
|
29
|
+
* shell's `activeElement` and goes no further (Chromium, WebKit), and from a focused element of
|
|
30
|
+
* the host's the window hears no focus event at all (Firefox). A later task's `frame.focus()`
|
|
31
|
+
* goes through on all of them, the frame blurred first as the failed one left it active.
|
|
27
32
|
*
|
|
28
33
|
* Plain ES2020, no imports and no build step, like the runtime. `__PLAN__` is its plan.
|
|
29
34
|
*/
|
package/dist/shell/frame.js
CHANGED
|
@@ -25,7 +25,12 @@ import { hostOriginProblem, onNestedLabel } from "../isolation/served.js";
|
|
|
25
25
|
* - renews the page's sealed files' address before it ends, and gives the page the new one
|
|
26
26
|
* (`porthole/files-renewed`): the page's own loads aren't its origin's (an opaque origin's never
|
|
27
27
|
* are), so only the shell, on that origin, may renew it (P083);
|
|
28
|
-
* - passes its focus to the page
|
|
28
|
+
* - passes its focus to the page: at the focus event where that takes (Firefox, from the host's
|
|
29
|
+
* `<body>`), and on the host's word that it moved it there (`porthole/shell/focus`, P136), where
|
|
30
|
+
* it doesn't: a frame's move inside the focus event that made it the focused frame sets the
|
|
31
|
+
* shell's `activeElement` and goes no further (Chromium, WebKit), and from a focused element of
|
|
32
|
+
* the host's the window hears no focus event at all (Firefox). A later task's `frame.focus()`
|
|
33
|
+
* goes through on all of them, the frame blurred first as the failed one left it active.
|
|
29
34
|
*
|
|
30
35
|
* Plain ES2020, no imports and no build step, like the runtime. `__PLAN__` is its plan.
|
|
31
36
|
*/
|
|
@@ -151,12 +156,39 @@ export const FRAME_SHELL_RUNTIME = String.raw `(() => {
|
|
|
151
156
|
};
|
|
152
157
|
requestAnimationFrame(tick);
|
|
153
158
|
setInterval(look, 50);
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
159
|
+
|
|
160
|
+
// Whether the focus is on the shell's own document, not through it on the page's (P136). Firefox
|
|
161
|
+
// tells a move from a focused element of the host's on the document alone. The host's word needs
|
|
162
|
+
// this: it never moves a focus that isn't here, and a page that has it hears no blur.
|
|
163
|
+
let holds = false;
|
|
164
|
+
// Until when a word that came ahead of the focus it speaks of holds (it crosses processes too).
|
|
165
|
+
let wordUntil = 0;
|
|
166
|
+
const handOn = () => {
|
|
167
|
+
if (holds && document.hasFocus()) {
|
|
168
|
+
frame.blur();
|
|
158
169
|
frame.focus();
|
|
159
170
|
}
|
|
171
|
+
};
|
|
172
|
+
const came = () => {
|
|
173
|
+
holds = true;
|
|
174
|
+
if (performance.now() < wordUntil) {
|
|
175
|
+
wordUntil = 0;
|
|
176
|
+
setTimeout(handOn, 0);
|
|
177
|
+
}
|
|
178
|
+
};
|
|
179
|
+
document.addEventListener("focus", came);
|
|
180
|
+
addEventListener("blur", () => {
|
|
181
|
+
holds = false;
|
|
182
|
+
look();
|
|
183
|
+
});
|
|
184
|
+
addEventListener("focus", (event) => {
|
|
185
|
+
if (event.target === window) {
|
|
186
|
+
came();
|
|
187
|
+
// Where a move can go on from inside this event (P136): Firefox, from the host's <body>.
|
|
188
|
+
if (document.activeElement !== frame) {
|
|
189
|
+
frame.focus();
|
|
190
|
+
}
|
|
191
|
+
}
|
|
160
192
|
look();
|
|
161
193
|
});
|
|
162
194
|
document.addEventListener("visibilitychange", look);
|
|
@@ -183,6 +215,14 @@ export const FRAME_SHELL_RUNTIME = String.raw `(() => {
|
|
|
183
215
|
if (data.method === PREFIX + "look" && typeof n === "number" && n >= 0 && Math.floor(n) === n) {
|
|
184
216
|
look(n);
|
|
185
217
|
}
|
|
218
|
+
// The host's own move into the frame, done (P136): on to the page.
|
|
219
|
+
if (data.method === PREFIX + "focus") {
|
|
220
|
+
if (holds) {
|
|
221
|
+
handOn();
|
|
222
|
+
} else {
|
|
223
|
+
wordUntil = performance.now() + 250;
|
|
224
|
+
}
|
|
225
|
+
}
|
|
186
226
|
return;
|
|
187
227
|
}
|
|
188
228
|
const child = frame.contentWindow;
|
package/docs/ADOPTING.md
CHANGED
|
@@ -420,9 +420,11 @@ composer.onClose(() => display.annotations.clearSelection());
|
|
|
420
420
|
their whole box (a composer's button, a card), a newer shell gives `selected`, each attached
|
|
421
421
|
result and `tracked` a `lastLineDocumentRect`: the last line with words on it, in the document's
|
|
422
422
|
coordinates (an element's whole box: it has no lines), unclamped as `documentRect` is. `selected`
|
|
423
|
-
carries the `scroll` it was read at too; an `anchored` report and `tracked` already do
|
|
424
|
-
|
|
425
|
-
|
|
423
|
+
carries the `scroll` it was read at too; an `anchored` report and `tracked` already do, and
|
|
424
|
+
`createHost` drops a report with a last line and no `scroll`, so where you have the line you have
|
|
425
|
+
the scroll (P137). A line's end in the frame's viewport is `x + width - scroll.x`, its bottom
|
|
426
|
+
`y + height - scroll.y`. Clip what you draw from it, as above, and keep `rect` where it is absent
|
|
427
|
+
(an older shell):
|
|
426
428
|
|
|
427
429
|
```js
|
|
428
430
|
display.on("annotation", (report) => {
|
|
@@ -453,13 +455,60 @@ composer.onClose(() => display.annotations.clearSelection());
|
|
|
453
455
|
can forge `activated` while the person really is there, which this doesn't stop. So moving the
|
|
454
456
|
keyboard into your view on it is your own step outside "takes no focus" above, and a page can
|
|
455
457
|
bring it about: gate whatever posts from that view (a Reply in a frame-opened card) yourself;
|
|
456
|
-
Porthole can't.
|
|
458
|
+
Porthole can't. That goes for keys too: with the focus in your view the person's next keys reach
|
|
459
|
+
your document, so the view's own key handlers and your page-wide shortcuts that write (an `r` that
|
|
460
|
+
resolves, Cmd+Enter that posts) need the same gate (P137). When the person's key closes your view
|
|
461
|
+
of that mark from inside it (Escape, or a
|
|
462
|
+
Tab past its first or last control), whether or not the keyboard got there through `activated`,
|
|
463
|
+
and only then, close it and call
|
|
457
464
|
`display.annotations.focusMark(id)` (React: `focusMark(id)` on the `ref`) to put the keyboard back
|
|
458
465
|
on the marker. It carries no content and reports nothing; an id with no marker, or a marker the
|
|
459
466
|
page has moved away, does nothing and throws nothing; the page can take the focus straight back.
|
|
460
467
|
Close the view first: from one of your text fields that still has focus, the focus guard takes
|
|
461
468
|
the move for the page's, undoes it and counts it (`focusTaken`). Keep your own list of marks as
|
|
462
469
|
the way that holds.
|
|
470
|
+
On a calm page that lands at once, from your `<body>`. While the frame is finding its marks (a
|
|
471
|
+
`show` just sent, which many hosts send as a card closes, or content that just changed) the word
|
|
472
|
+
waits, up to a second, and is then dropped unless the focus is in the frame by then. A word the
|
|
473
|
+
frame takes more than 100 ms after you sent it, because its page is busy, is held to the same
|
|
474
|
+
test. So a late word takes no keyboard from a person who moved on ([P135](DECISIONS.md),
|
|
475
|
+
[P137](DECISIONS.md)). As your card has just closed, the focus is on your `<body>`, so a word that
|
|
476
|
+
waited or came late is dropped, and nothing tells you: **call `focusMark` again after your own
|
|
477
|
+
move of the focus into the frame.** Call it as your close runs, not after other work: its age
|
|
478
|
+
starts when you call it, and where the browser runs the frame on your thread, what your task does
|
|
479
|
+
next counts too.
|
|
480
|
+
|
|
481
|
+
```js
|
|
482
|
+
closeCard();
|
|
483
|
+
display.annotations.focusMark(id);
|
|
484
|
+
setTimeout(() => {
|
|
485
|
+
// Not on the marker, and the person hasn't moved on: the frame was busy.
|
|
486
|
+
if (document.activeElement === document.body) {
|
|
487
|
+
display.focus();
|
|
488
|
+
display.annotations.focusMark(id);
|
|
489
|
+
}
|
|
490
|
+
}, 200);
|
|
491
|
+
```
|
|
492
|
+
|
|
493
|
+
Keep the check: on a button of yours, the person has moved on, and `display.focus()` would take the
|
|
494
|
+
keyboard from them. With React, whose `ref` has no `focus()`, call the frame's own `focus()` for
|
|
495
|
+
that step: it is only ever taken for the page's from a text field, and this one starts on `<body>`.
|
|
496
|
+
An id with no marker then leaves the focus in the frame, with the keys going to the page.
|
|
497
|
+
|
|
498
|
+
**Nested pages (P136).** `display.focus()` reaches a nested page on every engine, whether or not
|
|
499
|
+
it had the focus. Two ways don't:
|
|
500
|
+
- The frame's own `focus()`, which the React step above is: it stops at the page's shell (Chromium
|
|
501
|
+
and WebKit from anywhere, Firefox from a focused element of yours), so a `focusMark` that waits
|
|
502
|
+
is dropped even after it, and nothing tells you. On a calm page the second call doesn't wait and
|
|
503
|
+
lands. On a page that is changing, keep your own list of marks as the way back.
|
|
504
|
+
- `display.focus()` inside a key's own handler, on Firefox (measured on a nested page): it moves
|
|
505
|
+
nothing. Call it from a task, as the timer above does.
|
|
506
|
+
|
|
507
|
+
Without the second call, nothing changes on a calm page. On a busy one, a word that the frame
|
|
508
|
+
finishes with before your own move is lost where it used to land, so the person gets the frame and
|
|
509
|
+
not the marker. That is the cost of never pulling the keyboard into the page. Upgrade the host and
|
|
510
|
+
the content server together: a newer shell takes a word from an older `createHost`, which has no
|
|
511
|
+
stamp, as a late one (the second call still lands), and an older shell ignores the stamp.
|
|
463
512
|
- **Labels and quotes are the page's text**: shown only as text. Porthole takes out of a label what
|
|
464
513
|
the person can't see; a quote (`exact`) keeps it, to be found again. Hand either to a model only
|
|
465
514
|
as the page's words.
|
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -215,6 +215,7 @@ Host app Shell (its own origin) Page (opaque child)
|
|
|
215
215
|
│── the host's messages ──────►│── postMessage ───────────────►│
|
|
216
216
|
│◄── porthole/shell/state ─────│ its own activation, its focus │
|
|
217
217
|
│── porthole/shell/look ──────►│ look now (as a move is heard) │
|
|
218
|
+
│── porthole/shell/focus ─────►│ display.focus(): on to the ──►│ the page's window
|
|
218
219
|
```
|
|
219
220
|
|
|
220
221
|
### URL frame
|