@botiverse/porthole 0.14.11 → 0.14.13
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 +28 -0
- package/dist/annotate/types.d.ts +7 -2
- package/dist/annotate/types.js +5 -0
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +8 -0
- package/dist/host/types.d.ts +19 -0
- package/dist/react/frame.d.ts +8 -0
- package/dist/react/frame.js +6 -0
- package/dist/react/view.js +1 -0
- package/dist/shell/annotate.d.ts +14 -3
- package/dist/shell/annotate.js +70 -10
- package/docs/ADOPTING.md +58 -4
- package/docs/DECISIONS.md +236 -1
- package/docs/DESIGN.md +17 -8
- package/docs/THREAT_MODEL.md +59 -5
- package/package.json +1 -1
- package/src/annotate/types.ts +7 -2
- package/src/host/create-host.ts +8 -0
- package/src/host/types.ts +19 -0
- package/src/react/frame.tsx +14 -0
- package/src/react/view.tsx +1 -0
- package/src/shell/annotate.ts +71 -10
package/dist/host/create-host.js
CHANGED
|
@@ -578,6 +578,14 @@ export function createHost(config, options = {}) {
|
|
|
578
578
|
needsAnnotate("clearSelection");
|
|
579
579
|
toFrame(ANNOTATE_METHODS.clearSelection, {});
|
|
580
580
|
},
|
|
581
|
+
focusMark(id) {
|
|
582
|
+
// Host → frame only, and kept for no later frame (P134). A mark that has gone, or has no
|
|
583
|
+
// marker, is nothing to ask for, and no fault: the host's card closed with the mark's.
|
|
584
|
+
needsAnnotate("focusMark");
|
|
585
|
+
if (marks.some((mark) => mark.id === id && hasMarker(mark))) {
|
|
586
|
+
toFrame(ANNOTATE_METHODS.focusMark, { id });
|
|
587
|
+
}
|
|
588
|
+
},
|
|
581
589
|
};
|
|
582
590
|
const hostContext = () => {
|
|
583
591
|
const width = container.getBoundingClientRect().width;
|
package/dist/host/types.d.ts
CHANGED
|
@@ -326,6 +326,25 @@ export interface AnnotationControls {
|
|
|
326
326
|
* a frame that runs later (it has no selection to clear).
|
|
327
327
|
*/
|
|
328
328
|
clearSelection(): void;
|
|
329
|
+
/**
|
|
330
|
+
* Puts the keyboard back on a mark's marker in the frame (P134): for after Escape closed the
|
|
331
|
+
* host's own view of that mark, and for nothing else. No content goes with it, and no report
|
|
332
|
+
* comes of it. Nothing happens, and nothing throws, for an id no mark with a marker is shown
|
|
333
|
+
* under, or if the frame has no such marker now (its words are gone, elements are being picked):
|
|
334
|
+
* the display's own `focus()` isn't used, so the frame takes no focus for a marker it hasn't got.
|
|
335
|
+
* Call it once the view is closed: from one of the page's text fields that still has focus, the
|
|
336
|
+
* move is the frame's own to the focus guard, undone and counted (P109). The page can take the
|
|
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), so a word that comes late takes no keyboard from a
|
|
342
|
+
* person who moved on. Nothing says it was dropped: if the frame isn't your page's
|
|
343
|
+
* `document.activeElement` soon after and the person hasn't moved on, call `focus()` and then
|
|
344
|
+
* `focusMark(id)` again. Known gap: on a nested page that had the focus, `focus()` doesn't bring
|
|
345
|
+
* it back into the page, so a second call that waits is dropped too (ADOPTING).
|
|
346
|
+
*/
|
|
347
|
+
focusMark(id: string): void;
|
|
329
348
|
}
|
|
330
349
|
export interface DisplayControls {
|
|
331
350
|
readonly displayId: string;
|
package/dist/react/frame.d.ts
CHANGED
|
@@ -154,6 +154,14 @@ export interface PortholeFrameHandle {
|
|
|
154
154
|
* `"annotations"` (the core's call throws; this never does).
|
|
155
155
|
*/
|
|
156
156
|
clearSelection(): void;
|
|
157
|
+
/**
|
|
158
|
+
* Puts the keyboard back on a mark's marker in the frame (`annotations.focusMark(id)`, P134),
|
|
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"`. While
|
|
161
|
+
* the frame is finding its marks it waits, and is dropped unless the focus is in the frame by
|
|
162
|
+
* then (P135): call it again after your own move of the focus into the frame.
|
|
163
|
+
*/
|
|
164
|
+
focusMark(id: string): void;
|
|
157
165
|
/**
|
|
158
166
|
* Finds `query` in the frame and highlights it (`find.query`, P131): where the matches stand,
|
|
159
167
|
* or `"unsupported"` (a config without `find`, an older shell, no answer in time, a later
|
package/dist/react/frame.js
CHANGED
|
@@ -349,6 +349,12 @@ export function PortholeFrame(props) {
|
|
|
349
349
|
attempt(() => now.annotations.clearSelection(), own.current);
|
|
350
350
|
}
|
|
351
351
|
},
|
|
352
|
+
focusMark(id) {
|
|
353
|
+
const now = display.current;
|
|
354
|
+
if (now !== null) {
|
|
355
|
+
attempt(() => now.annotations.focusMark(id), own.current);
|
|
356
|
+
}
|
|
357
|
+
},
|
|
352
358
|
find(query, options) {
|
|
353
359
|
try {
|
|
354
360
|
checkFindQuery(query, options);
|
package/dist/react/view.js
CHANGED
|
@@ -129,6 +129,7 @@ function InstanceView(props) {
|
|
|
129
129
|
const shown = useRef(null);
|
|
130
130
|
useImperativeHandle(ref, () => ({
|
|
131
131
|
clearSelection: () => shown.current?.clearSelection(),
|
|
132
|
+
focusMark: (id) => shown.current?.focusMark(id),
|
|
132
133
|
find: (query, options) => shown.current?.find(query, options) ?? Promise.resolve("unsupported"),
|
|
133
134
|
clearFind: () => shown.current?.clearFind(),
|
|
134
135
|
}), []);
|
package/dist/shell/annotate.d.ts
CHANGED
|
@@ -7,14 +7,23 @@
|
|
|
7
7
|
* centre is nearest the point. No built-in is called (content may have patched them).
|
|
8
8
|
*/
|
|
9
9
|
export declare const MARKER_HIT: string;
|
|
10
|
+
/**
|
|
11
|
+
* What a marker is called (P133, P134), to whoever can't see it, spliced into the runtime: what it
|
|
12
|
+
* is, and the words it is on, in quotes. In English, whatever the page's language: the shell has no
|
|
13
|
+
* words of the host's. `anchor.label` stays as the host stores it (it is the host's to show): an
|
|
14
|
+
* element's starts with its tag (`describe`, "p#intro.lead Words"), so an element's words are its
|
|
15
|
+
* quote, cut where the label's are and marked so, or for one with no text of its own (an image's
|
|
16
|
+
* `alt`) what follows the tag in the label. An element with neither has no words.
|
|
17
|
+
*/
|
|
18
|
+
export declare const MARKER_NAME: string;
|
|
10
19
|
/**
|
|
11
20
|
* The shell's annotation runtime (P053), spliced into the shell's runtime (`__ANNOTATE__`) when
|
|
12
21
|
* the config declares `annotate`, so it runs before any content does, with the DOM's own
|
|
13
22
|
* functions as they were. Plain ES2020 like the rest of the shell; no template literals (it sits
|
|
14
23
|
* in one).
|
|
15
24
|
*
|
|
16
|
-
* The host drives it (`porthole/annotate.start|stop|show|focus|clear|track|clearSelection`)
|
|
17
|
-
* reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked`):
|
|
25
|
+
* The host drives it (`porthole/annotate.start|stop|show|focus|clear|track|clearSelection|focusMark`)
|
|
26
|
+
* and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked`):
|
|
18
27
|
* - picking an element: the element under the pointer (or finger) is outlined with its name; a
|
|
19
28
|
* click or tap picks it, and the content's own handlers never see that click (unless the content
|
|
20
29
|
* patched the DOM's built-ins, P105); Escape cancels (while selecting text too, P112);
|
|
@@ -29,7 +38,9 @@ export declare const MARKER_HIT: string;
|
|
|
29
38
|
* in the line's gutter), an element's on its corner; a click on it, or Enter or Space with the
|
|
30
39
|
* focus on it (P133), is reported (`activated`), and the content's own handlers never see it; a
|
|
31
40
|
* draft is drawn apart, a dashed line and a hollow bubble with no number, and has a marker with
|
|
32
|
-
* or without a count;
|
|
41
|
+
* or without a count; the host's `focusMark` (P134) puts the focus on a marker that is there, and
|
|
42
|
+
* tells nothing back; one that had to wait for the marks lands only if the focus is still in this
|
|
43
|
+
* document (P135);
|
|
33
44
|
* - following: while a mark has a marker, once a scroll, a resize or a change of the content
|
|
34
45
|
* settles, the marks that moved since the host was last told are reported, at most once a
|
|
35
46
|
* second, so the host's own UI beside a mark can follow;
|
package/dist/shell/annotate.js
CHANGED
|
@@ -32,14 +32,36 @@ export const MARKER_HIT = String.raw `(count, boxAt, x, y, touch) => {
|
|
|
32
32
|
}
|
|
33
33
|
return best;
|
|
34
34
|
}`;
|
|
35
|
+
/**
|
|
36
|
+
* What a marker is called (P133, P134), to whoever can't see it, spliced into the runtime: what it
|
|
37
|
+
* is, and the words it is on, in quotes. In English, whatever the page's language: the shell has no
|
|
38
|
+
* words of the host's. `anchor.label` stays as the host stores it (it is the host's to show): an
|
|
39
|
+
* element's starts with its tag (`describe`, "p#intro.lead Words"), so an element's words are its
|
|
40
|
+
* quote, cut where the label's are and marked so, or for one with no text of its own (an image's
|
|
41
|
+
* `alt`) what follows the tag in the label. An element with neither has no words.
|
|
42
|
+
*/
|
|
43
|
+
export const MARKER_NAME = String.raw `(mark) => {
|
|
44
|
+
const squash = (text) => String(text).replace(/\s+/g, " ").trim();
|
|
45
|
+
const anchor = mark.anchor;
|
|
46
|
+
const label = typeof anchor.label === "string" ? squash(anchor.label).slice(0, 120) : "";
|
|
47
|
+
let words = label;
|
|
48
|
+
if (anchor.kind === "element") {
|
|
49
|
+
const quote = anchor.selectors.filter((each) => each && each.type === "TextQuoteSelector")[0];
|
|
50
|
+
const said = quote && typeof quote.exact === "string" ? squash(quote.exact.slice(0, 300)) : "";
|
|
51
|
+
const space = label.indexOf(" ");
|
|
52
|
+
words = said.length > 40 ? said.slice(0, 40).trim() + "\u2026" : said !== "" ? said : space === -1 ? "" : label.slice(space + 1);
|
|
53
|
+
}
|
|
54
|
+
const what = mark.draft ? "Draft comment" : mark.count === 1 ? "1 comment" : mark.count > 1 ? mark.count + " comments" : "Comment";
|
|
55
|
+
return words === "" ? what : what + ' on "' + words + '"';
|
|
56
|
+
}`;
|
|
35
57
|
/**
|
|
36
58
|
* The shell's annotation runtime (P053), spliced into the shell's runtime (`__ANNOTATE__`) when
|
|
37
59
|
* the config declares `annotate`, so it runs before any content does, with the DOM's own
|
|
38
60
|
* functions as they were. Plain ES2020 like the rest of the shell; no template literals (it sits
|
|
39
61
|
* in one).
|
|
40
62
|
*
|
|
41
|
-
* The host drives it (`porthole/annotate.start|stop|show|focus|clear|track|clearSelection`)
|
|
42
|
-
* reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked`):
|
|
63
|
+
* The host drives it (`porthole/annotate.start|stop|show|focus|clear|track|clearSelection|focusMark`)
|
|
64
|
+
* and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked`):
|
|
43
65
|
* - picking an element: the element under the pointer (or finger) is outlined with its name; a
|
|
44
66
|
* click or tap picks it, and the content's own handlers never see that click (unless the content
|
|
45
67
|
* patched the DOM's built-ins, P105); Escape cancels (while selecting text too, P112);
|
|
@@ -54,7 +76,9 @@ export const MARKER_HIT = String.raw `(count, boxAt, x, y, touch) => {
|
|
|
54
76
|
* in the line's gutter), an element's on its corner; a click on it, or Enter or Space with the
|
|
55
77
|
* focus on it (P133), is reported (`activated`), and the content's own handlers never see it; a
|
|
56
78
|
* draft is drawn apart, a dashed line and a hollow bubble with no number, and has a marker with
|
|
57
|
-
* or without a count;
|
|
79
|
+
* or without a count; the host's `focusMark` (P134) puts the focus on a marker that is there, and
|
|
80
|
+
* tells nothing back; one that had to wait for the marks lands only if the focus is still in this
|
|
81
|
+
* document (P135);
|
|
58
82
|
* - following: while a mark has a marker, once a scroll, a resize or a change of the content
|
|
59
83
|
* settles, the marks that moved since the host was last told are reported, at most once a
|
|
60
84
|
* second, so the host's own UI beside a mark can follow;
|
|
@@ -85,6 +109,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
85
109
|
track: "porthole/annotate.track",
|
|
86
110
|
tracked: "porthole/annotate.tracked",
|
|
87
111
|
clearSelection: "porthole/annotate.clearSelection",
|
|
112
|
+
focusMark: "porthole/annotate.focusMark",
|
|
88
113
|
};
|
|
89
114
|
// The DOM's own functions, taken before content runs.
|
|
90
115
|
const elementFromPoint = Document.prototype.elementFromPoint;
|
|
@@ -95,6 +120,8 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
95
120
|
const createElementNS = Document.prototype.createElementNS;
|
|
96
121
|
const selectionOf = Document.prototype.getSelection;
|
|
97
122
|
const removeAllRanges = Selection.prototype.removeAllRanges;
|
|
123
|
+
const focusElement = HTMLElement.prototype.focus;
|
|
124
|
+
const hasFocus = Document.prototype.hasFocus;
|
|
98
125
|
const elementRect = Element.prototype.getBoundingClientRect;
|
|
99
126
|
const rangeRect = Range.prototype.getBoundingClientRect;
|
|
100
127
|
const rangeRects = Range.prototype.getClientRects;
|
|
@@ -399,13 +426,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
399
426
|
const markerWidth = (label) => Math.max(MARKER_HEIGHT, 23 + (label === "" ? 0 : 3 + label.length * 7));
|
|
400
427
|
// Compact (P105): the number alone, or the glyph alone for none, with less padding.
|
|
401
428
|
const compactWidth = (label) => (label === "" ? 21 : Math.max(MARKER_HEIGHT, 10 + label.length * 7));
|
|
402
|
-
|
|
403
|
-
// on. In English, whatever the page's language: the shell has no words of the host's.
|
|
404
|
-
const nameOf = (mark) => {
|
|
405
|
-
const words = typeof mark.anchor.label === "string" ? squash(mark.anchor.label).slice(0, LIMIT.label) : "";
|
|
406
|
-
const what = mark.draft ? "Draft comment" : mark.count === 1 ? "1 comment" : mark.count > 1 ? mark.count + " comments" : "Comment";
|
|
407
|
-
return words === "" ? what : what + " on " + words;
|
|
408
|
-
};
|
|
429
|
+
const nameOf = ${MARKER_NAME};
|
|
409
430
|
// A rect's last line with words on it: its last box with a width, else any with a size.
|
|
410
431
|
const lastBox = (rects) => {
|
|
411
432
|
let any = null;
|
|
@@ -1052,6 +1073,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1052
1073
|
// mark), nor before a run of changes settles; a focus asked for meanwhile waits for it.
|
|
1053
1074
|
let waitingForContent = false;
|
|
1054
1075
|
let pendingFocus = null;
|
|
1076
|
+
let pendingMarker = null;
|
|
1055
1077
|
const settling = () => anchorTimer !== 0 || waitingForContent || marks.some((mark) => mark.state === null);
|
|
1056
1078
|
const scheduleAnchor = (all) => {
|
|
1057
1079
|
if (all) {
|
|
@@ -1090,6 +1112,17 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1090
1112
|
pendingFocus = null;
|
|
1091
1113
|
focus(id);
|
|
1092
1114
|
}
|
|
1115
|
+
if (pendingMarker !== null) {
|
|
1116
|
+
const id = pendingMarker;
|
|
1117
|
+
pendingMarker = null;
|
|
1118
|
+
// Parked, the host's word is old: the person may have moved on, and a marker's focus
|
|
1119
|
+
// takes the keyboard with no gesture. So it lands only if the focus is still in this
|
|
1120
|
+
// document, asked through the kept function: a page that says it has the focus gets
|
|
1121
|
+
// no landing the platform would refuse. Otherwise it is dropped (P135).
|
|
1122
|
+
if (callOf(hasFocus, document, []) === true) {
|
|
1123
|
+
focusMark(id);
|
|
1124
|
+
}
|
|
1125
|
+
}
|
|
1093
1126
|
}, wait);
|
|
1094
1127
|
};
|
|
1095
1128
|
new MutationObserver((records) => {
|
|
@@ -1194,6 +1227,29 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1194
1227
|
report([{ mark, result: resultOf(mark, null, scroll) }], scroll);
|
|
1195
1228
|
};
|
|
1196
1229
|
|
|
1230
|
+
// The focus on a mark's marker, at the host's word (P134). Marks a show just replaced have no
|
|
1231
|
+
// markers yet, so it waits for them, as focus does; then a marker that isn't there, or has
|
|
1232
|
+
// stepped aside for picking, is nothing to do. The kept function, so a page that patched
|
|
1233
|
+
// focus isn't handed the marker from inside the closed root. The shell's focus listener
|
|
1234
|
+
// lights it and brings it into view; nothing is told. A call that isn't parked reads no
|
|
1235
|
+
// focus: it is the host's word just now, and after its card closed the focus is on the
|
|
1236
|
+
// host's body, so this document has none yet. Only the landing of a parked one asks (P135).
|
|
1237
|
+
const focusMark = (id) => {
|
|
1238
|
+
if (settling()) {
|
|
1239
|
+
pendingMarker = id;
|
|
1240
|
+
return;
|
|
1241
|
+
}
|
|
1242
|
+
if (mode.elements || !isShown(id)) {
|
|
1243
|
+
return;
|
|
1244
|
+
}
|
|
1245
|
+
for (let i = 0; i < markers.length; i += 1) {
|
|
1246
|
+
if (markers[i].id === id) {
|
|
1247
|
+
callOf(focusElement, markers[i].element, [{ preventScroll: true }]);
|
|
1248
|
+
return;
|
|
1249
|
+
}
|
|
1250
|
+
}
|
|
1251
|
+
};
|
|
1252
|
+
|
|
1197
1253
|
// A marker's click (P104). The layer takes no pointer but on its markers, so a press whose
|
|
1198
1254
|
// target is the layer is on a marker: the content's handlers never see it (this listener
|
|
1199
1255
|
// runs before any of theirs), nor does what lies under it, and a click is reported. A press
|
|
@@ -1628,9 +1684,13 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1628
1684
|
}
|
|
1629
1685
|
break;
|
|
1630
1686
|
}
|
|
1687
|
+
case M.focusMark:
|
|
1688
|
+
focusMark(String(params.id));
|
|
1689
|
+
break;
|
|
1631
1690
|
case M.clear:
|
|
1632
1691
|
track(null);
|
|
1633
1692
|
pendingFocus = null;
|
|
1693
|
+
pendingMarker = null;
|
|
1634
1694
|
marks = [];
|
|
1635
1695
|
active = null;
|
|
1636
1696
|
hot = null;
|
package/docs/ADOPTING.md
CHANGED
|
@@ -337,7 +337,8 @@ composer.onClose(() => display.annotations.clearSelection());
|
|
|
337
337
|
for 500 ms after it appears or moves (no
|
|
338
338
|
`pointerdown`, `pointerup`, `click` or key: menu triggers act on a press, and menu items click
|
|
339
339
|
themselves on a release), ignores a press that began before that, opens beside the frame rather
|
|
340
|
-
than over `rect` where the layout allows, takes no focus
|
|
340
|
+
than over `rect` where the layout allows, takes no focus (unless it meets the conditions of
|
|
341
|
+
THREAT_MODEL §6's exceptions), and has nothing one click away that
|
|
341
342
|
posts, submits, resolves, deletes or discards. Making it `inert` while it arms does all of the
|
|
342
343
|
first:
|
|
343
344
|
|
|
@@ -434,14 +435,66 @@ composer.onClose(() => display.annotations.clearSelection());
|
|
|
434
435
|
});
|
|
435
436
|
```
|
|
436
437
|
- **The keyboard** (P133): each marker is a button in the frame's Tab order, after the page's own
|
|
437
|
-
stops, in reading order, named for what it is (
|
|
438
|
-
anchor's
|
|
438
|
+
stops, in reading order, named for what it is (`3 comments on "the words"`, from the `count` and
|
|
439
|
+
the anchor's words, without an element's tag, P134; in English, whatever your UI's language). The
|
|
440
|
+
`label` you store keeps its tag. Enter or Space on it is `activated`,
|
|
439
441
|
through the same path and the same gesture check as a click: nothing to handle apart. It is the
|
|
440
442
|
page's focus order, which a page can steal from or hide a marker from, and it is one more
|
|
441
443
|
`activated` the content can time: keep your own list of marks as the way a keyboard can rely on,
|
|
442
444
|
with `annotations.focus(id)` to bring one into view, and leave your view's guard as it is (it
|
|
443
445
|
takes no key for 500 ms either, and takes no focus: Enter again on the marker is one more
|
|
444
446
|
`activated`).
|
|
447
|
+
- **Key or pointer, and back to the marker** (P134). `activated` doesn't say what made it. Read
|
|
448
|
+
your own page as it arrives, in the listener: `document.activeElement === container.querySelector("iframe")`
|
|
449
|
+
(a shadow root of yours: its `activeElement`). True means the focus is in the frame, as it is
|
|
450
|
+
for a key on a marker; a pointer's press on a marker moves no focus, so a click from outside
|
|
451
|
+
reads false. The page can't change that reading, but it is a hint, not a proof: a click after the
|
|
452
|
+
person was already in the frame reads true, the page can put the focus in its frame itself, and it
|
|
453
|
+
can forge `activated` while the person really is there, which this doesn't stop. So moving the
|
|
454
|
+
keyboard into your view on it is your own step outside "takes no focus" above, and a page can
|
|
455
|
+
bring it about: gate whatever posts from that view (a Reply in a frame-opened card) yourself;
|
|
456
|
+
Porthole can't. When the person's key closes your view of that mark from inside it (Escape, or a
|
|
457
|
+
Tab past its first or last control), whether or not the keyboard got there through `activated`,
|
|
458
|
+
and only then, close it and call
|
|
459
|
+
`display.annotations.focusMark(id)` (React: `focusMark(id)` on the `ref`) to put the keyboard back
|
|
460
|
+
on the marker. It carries no content and reports nothing; an id with no marker, or a marker the
|
|
461
|
+
page has moved away, does nothing and throws nothing; the page can take the focus straight back.
|
|
462
|
+
Close the view first: from one of your text fields that still has focus, the focus guard takes
|
|
463
|
+
the move for the page's, undoes it and counts it (`focusTaken`). Keep your own list of marks as
|
|
464
|
+
the way that holds.
|
|
465
|
+
On a calm page that lands at once, from your `<body>`. While the frame is finding its marks (a
|
|
466
|
+
`show` just sent, which many hosts send as a card closes, or content that just changed) the word
|
|
467
|
+
waits, up to a second, and is then dropped unless the focus is in the frame by then, so it takes no
|
|
468
|
+
keyboard from a person who moved on ([P135](DECISIONS.md)). As your card has just closed, the focus
|
|
469
|
+
is on your `<body>`, so a word that waited is dropped, and nothing tells you: **call `focusMark`
|
|
470
|
+
again after your own move of the focus into the frame.**
|
|
471
|
+
|
|
472
|
+
```js
|
|
473
|
+
closeCard();
|
|
474
|
+
display.annotations.focusMark(id);
|
|
475
|
+
setTimeout(() => {
|
|
476
|
+
// Not on the marker, and the person hasn't moved on: the frame was busy.
|
|
477
|
+
if (document.activeElement === document.body) {
|
|
478
|
+
display.focus();
|
|
479
|
+
display.annotations.focusMark(id);
|
|
480
|
+
}
|
|
481
|
+
}, 200);
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
Keep the check: on a button of yours, the person has moved on, and `display.focus()` would take the
|
|
485
|
+
keyboard from them. With React, whose `ref` has no `focus()`, call the frame's own `focus()` for
|
|
486
|
+
that step: it is only ever taken for the page's from a text field, and this one starts on `<body>`.
|
|
487
|
+
An id with no marker then leaves the focus in the frame, with the keys going to the page.
|
|
488
|
+
|
|
489
|
+
**Known gap, nested pages (P135).** On a nested page that had the focus, `display.focus()` doesn't
|
|
490
|
+
bring it back into the page (measured on Chromium, WebKit and Firefox), so a `focusMark` that waits
|
|
491
|
+
is dropped even after it, and the person is left without the marker. On a calm page the second
|
|
492
|
+
call doesn't wait and lands. On a page that is changing, it doesn't, and nothing tells you: keep
|
|
493
|
+
your own list of marks as the way back. A fix to the shell is open; this paragraph goes with it.
|
|
494
|
+
|
|
495
|
+
Without the second call, nothing changes on a calm page. On a busy one, a word that the frame
|
|
496
|
+
finishes with before your own move is lost where it used to land, so the person gets the frame and
|
|
497
|
+
not the marker. That is the cost of never pulling the keyboard into the page.
|
|
445
498
|
- **Labels and quotes are the page's text**: shown only as text. Porthole takes out of a label what
|
|
446
499
|
the person can't see; a quote (`exact`) keeps it, to be found again. Hand either to a model only
|
|
447
500
|
as the page's words.
|
|
@@ -545,7 +598,8 @@ display.on("contentError", ({ message }) => log(message)); // "The content kept
|
|
|
545
598
|
display.focus(); // not frame.focus(): from a text field, that one is taken for the page's and undone
|
|
546
599
|
// Opening your composer focused: only in a comment mode the person started, for a composer that can
|
|
547
600
|
// only save a draft (Enter adds it to the batch; submitting is only your own "Submit N"), and that
|
|
548
|
-
// shows plainly it is a draft (THREAT_MODEL §6, P112); any other view a report opens takes no focus
|
|
601
|
+
// shows plainly it is a draft (THREAT_MODEL §6, P112); any other view a report opens takes no focus (P134's
|
|
602
|
+
// exception, §6, is a container only, and its own conditions). Then
|
|
549
603
|
// Porthole's move, not textarea.focus().
|
|
550
604
|
import { focusField } from "@botiverse/porthole";
|
|
551
605
|
focusField(composer.textarea); // Firefox ignores a plain focus() while a fighting frame holds focus
|
package/docs/DECISIONS.md
CHANGED
|
@@ -7597,7 +7597,7 @@ control: nothing here is a defense; the bound is `parseRect`'s, which existing p
|
|
|
7597
7597
|
box, and its scroll), the scroll without following a mark (a page with no marks the host follows),
|
|
7598
7598
|
or a host draws from `documentRect` inside the frame's own area and wants Porthole to clip for it.
|
|
7599
7599
|
|
|
7600
|
-
## P133 · 2026-11-06 · Markers are labelled buttons, a posted comment's sits at its paragraph's end, and reports say where the last line is · Accepted
|
|
7600
|
+
## P133 · 2026-11-06 · Markers are labelled buttons, a posted comment's sits at its paragraph's end, and reports say where the last line is · Accepted; amended by P134
|
|
7601
7601
|
|
|
7602
7602
|
Amends P104 (its point 6, and its "Revisit when" on a keyboard inside the frame) and P105 (its
|
|
7603
7603
|
point 3, for posted text marks, and P2-B's click listener on each marker). Three follow-ups for
|
|
@@ -7733,3 +7733,238 @@ it didn't focus is missed, or reported as the marker that has the focus, so the
|
|
|
7733
7733
|
(give the layer a way to learn its target); a right-to-left paragraph's
|
|
7734
7734
|
end should be on its left (P105's places aren't direction-aware either); paragraphs split by `<br>`
|
|
7735
7735
|
should count as many; or a host wants a picked paragraph's marker at its end.
|
|
7736
|
+
|
|
7737
|
+
## P134 · 2026-11-06 · The keyboard back on a marker after the host's card closes, and a marker's name without an element's tag · Accepted; amended by P135
|
|
7738
|
+
|
|
7739
|
+
Amends P133 (its point 1, the name) and adds to P104's host API. Two follow-ups for comment markers,
|
|
7740
|
+
from a host (Raft web): a person who pressed Enter on a marker reads the host's card, presses
|
|
7741
|
+
Escape, and lands on the host's `<body>`, the marker's place in the Tab order lost, and an element
|
|
7742
|
+
anchor's marker is read out as "1 comment on p Paragraph 3. Filler…", the tag and all.
|
|
7743
|
+
|
|
7744
|
+
**Decision.**
|
|
7745
|
+
|
|
7746
|
+
1. **`annotations.focusMark(id)`** (`porthole/annotate.focusMark`, `{ id }`; React: `focusMark(id)` on
|
|
7747
|
+
`PortholeFrameHandle`, as `clearSelection` is, since it is a moment and not a state). The name
|
|
7748
|
+
is `focus(id)`'s, for the mark's marker: `focus` scrolls to a mark and lights it, and moves no DOM
|
|
7749
|
+
focus. The shell moves the DOM focus to that mark's marker button, with the platform's `focus`
|
|
7750
|
+
kept before content runs and `preventScroll`: the focus listener P133 added lights the words and
|
|
7751
|
+
brings it into view, as for a Tab. **It is for the Esc path only** (widened the same day: a Tab past the view's ends closes it the same way, the same word, for the same reason; the shell doesn't change, and `THREAT_MODEL` §6 says so): after Escape closed the host's
|
|
7752
|
+
own view of that mark. Nothing else needs a host to move the keyboard into a frame, and P109 and
|
|
7753
|
+
§6 spend a good deal on keeping it out.
|
|
7754
|
+
2. **No content, and nothing new back.** An id the host already sent in `show`; no report, no field,
|
|
7755
|
+
no rate. It is host to frame only, and kept for no later frame.
|
|
7756
|
+
3. **No such marker, nothing happens.** No fault either: the mark may have gone with the card. The
|
|
7757
|
+
host sends nothing for an id with no shown mark or no marker; the shell does nothing for a mark
|
|
7758
|
+
with no marker now (orphaned, the page moved its words) or while elements are picked (markers step
|
|
7759
|
+
aside, P133). After a `show` it waits for the marks to be found, as `focus` does: a host commonly
|
|
7760
|
+
sends a new `show` as a card closes. Without `annotate` it throws, as every call does.
|
|
7761
|
+
4. **The shell alone moves it, not the host's `display.focus()` first.** A marker's `focus()` from
|
|
7762
|
+
inside takes the frame's focus with it, as any page's does (P109, measured on all three), and
|
|
7763
|
+
the host doesn't know whether the frame still has the marker: moving the frame first would give
|
|
7764
|
+
the frame the keyboard for a marker that isn't there. So the focus guard sees the move as the
|
|
7765
|
+
frame's own, and rightly does nothing to a move from `<body>`. A host calls it once its card is
|
|
7766
|
+
closed. Still in a text field of the host's page, the guard undoes the move and counts it
|
|
7767
|
+
(`focusTaken`, Escape counting as typing), which can stop the display (P109).
|
|
7768
|
+
5. **A marker's name is the words it is on, in quotes, with no tag**: `1 comment on "Paragraph 3.
|
|
7769
|
+
Filler…"`, `Draft comment on "…"`, and `1 comment` for a wordless element with nothing to say.
|
|
7770
|
+
Text anchors are quoted too, one form for one kind of button. `describe` gives an element's
|
|
7771
|
+
`anchor.label` its tag, and the host stores and shows that label, so it stays as it is, in the
|
|
7772
|
+
picking outline and in every report. The name is worked out from the anchor: an element's
|
|
7773
|
+
`TextQuoteSelector`, cut at the label's 40 characters with an ellipsis; with no quote (an image
|
|
7774
|
+
named by its `alt`) what follows the first space of the label; nothing else. No field, no message.
|
|
7775
|
+
6. **The host's way to tell a key from a pointer is its own**: `document.activeElement` on the host's
|
|
7776
|
+
page, read as `activated` arrives. A marker's press by a pointer moves no focus (P105), so a click
|
|
7777
|
+
from outside the frame finds the frame not focused, and a key on a marker finds it focused. The
|
|
7778
|
+
host reads that itself: `activated` is unchanged, no new field. It is a hint, what the next section
|
|
7779
|
+
says of it holds, and Porthole does nothing with it.
|
|
7780
|
+
|
|
7781
|
+
**Compatibility.** An older shell ignores `focusMark` (it knows no such method), which is a call
|
|
7782
|
+
that did nothing. `PortholeFrameHandle` gains a method, which only Porthole implements. `activated`,
|
|
7783
|
+
`AnnotationAnchor` and everything stored are as they were. Names change in place on a host doing
|
|
7784
|
+
nothing. The shell is the content server's: upgrade that.
|
|
7785
|
+
|
|
7786
|
+
**Threat.**
|
|
7787
|
+
- `focusMark` gives the page nothing new. It reads the message in its own window and learns that a
|
|
7788
|
+
card closed just now, and which mark's, which it could tell from the focus moving anyway. It can
|
|
7789
|
+
take the focus straight back or spoil the move: failure is fine, and a host can't rely on it, as
|
|
7790
|
+
P133 says of markers. A page can make up the message with a `MessageEvent` naming the frame's
|
|
7791
|
+
parent as its source (the shell's listener checks those, not `isTrusted`, for every message here)
|
|
7792
|
+
and so focus a marker itself: a marker's press has no power but `activated`, which it can fake
|
|
7793
|
+
anyway. The key the person then presses is a trusted click on a marker, and as guarded.
|
|
7794
|
+
- The move is through the kept `focus`, so a page that patched `HTMLElement.prototype.focus` isn't
|
|
7795
|
+
handed a marker from inside the closed root (control `marker-focus`, as P129 holds the guards).
|
|
7796
|
+
- The name's quotes are punctuation, no bound: a page's words can hold a `"`. The kind of thing the
|
|
7797
|
+
name says it is stays first, the shell's, as in P133. An element's quote keeps what can't be seen,
|
|
7798
|
+
as its selector does (P105 cleans labels), and it is the text the page shows anyway, only read out.
|
|
7799
|
+
- **The host's signal.** The page can't change what `document.activeElement` says on the host's
|
|
7800
|
+
page. That is all it gives: it says the focus is in the frame, not that a key was pressed or by
|
|
7801
|
+
whom. The page can forge `activated` while the person really is in the frame, and the signal
|
|
7802
|
+
doesn't stop that. The page can also make it true, with `focus()` on its own element from anywhere
|
|
7803
|
+
but a text field of the host's (P109 lets that be). And a pointer's click on a marker reads as a
|
|
7804
|
+
key if the person was already in the frame. So a host that moves the keyboard into its view on this
|
|
7805
|
+
signal takes the second exception to "takes no focus" that this decision adds (THREAT_MODEL §6,
|
|
7806
|
+
after P112's): a page can time a forged `activated` and put the person's next keys in that view.
|
|
7807
|
+
All three conditions are the host's: the signal read on its own page, focus only on a container
|
|
7808
|
+
that takes no input, and its own gate on every control there that can write, so a forged opening
|
|
7809
|
+
and the keys after it can't submit. Porthole can't do that for it.
|
|
7810
|
+
|
|
7811
|
+
**Tested.** `test/annotate.test.ts`: what `createHost` sends and for which ids, kept for no later
|
|
7812
|
+
frame, the throw without `annotate`; the kept `focus` and no `tell` in the shell's; every name
|
|
7813
|
+
(`MARKER_NAME`, spliced into the runtime as `MARKER_HIT` is, and run). `leak/annotate.spec.ts` (three
|
|
7814
|
+
engines; written and not yet run: test runs were paused where this was written, so the behaviour of
|
|
7815
|
+
engines above is reasoned from P109's and P105's measurements and awaits CI): "focusMark puts the
|
|
7816
|
+
focus on that mark's marker…", from the host's `<body>` after a card's field went, with the frame the
|
|
7817
|
+
host page's `activeElement`, nothing but `anchored` reported, Enter reporting that mark, and the
|
|
7818
|
+
focus left where it was for an unknown id, no marker, an orphaned mark, words the page removed, and
|
|
7819
|
+
picking; "focusMark right after a show…"; "a page that patched focus…" (new control `marker-focus`);
|
|
7820
|
+
"a marker's name is the words it is on…" (Chromium, by its inspector). `leak/react.spec.ts`: "a ref's
|
|
7821
|
+
focusMark…". Reports are found by what they say, and a control's own follow-up doesn't fail these.
|
|
7822
|
+
|
|
7823
|
+
**Rejected.**
|
|
7824
|
+
- `keyboard: true` on `activated` (the first draft of this decision, from the click's `detail` 0):
|
|
7825
|
+
a field the page can forge with the rest of the report, to tell the host what it can read for itself
|
|
7826
|
+
from a place the page can't write to. Neither stops a forged `activated`.
|
|
7827
|
+
- The host's `display.focus()` before the message: see point 4.
|
|
7828
|
+
- An answer from the shell (did the marker take it?), for a host to fall back on: a new report for a
|
|
7829
|
+
moment where failing is fine.
|
|
7830
|
+
- `focus(id)` also moving the DOM focus: `focus` is what a host's own list calls, and that keeps
|
|
7831
|
+
the keyboard in the host's list.
|
|
7832
|
+
- A hole in the focus guard for this call: a window in which a frame's move from a text field
|
|
7833
|
+
passes as the host's, for a page to use, to save a host from closing its card first.
|
|
7834
|
+
- Changing `describe`, or a new `words` field on an anchor: the first changes what hosts have stored
|
|
7835
|
+
and show, the second what they store and send back; neither is needed.
|
|
7836
|
+
|
|
7837
|
+
**Revisit when** a host needs to return focus somewhere other than after Escape; a host's card has a
|
|
7838
|
+
reason to stay open while the keyboard goes back; or a platform's guard should take a host's own word
|
|
7839
|
+
for a move into a frame it can't make itself.
|
|
7840
|
+
|
|
7841
|
+
## P135 · 2026-11-06 · A parked `focusMark` lands only while the focus is in the frame's document · Accepted
|
|
7842
|
+
|
|
7843
|
+
Amends P134 (its points 3 and 4: a `focusMark` that waits, and the host's `display.focus()`).
|
|
7844
|
+
|
|
7845
|
+
**Context.** The shell parks `focusMark` while the marks are being found (`settling()`: about 150 ms
|
|
7846
|
+
after a change of the content or a `show`, up to 1 s on a page that keeps changing, and for as long as
|
|
7847
|
+
the content isn't in). It then landed in the anchor timer with nothing asked of the focus: nothing but
|
|
7848
|
+
`clear` cancelled it, and it didn't expire. A marker's kept `focus()` takes the keyboard with no
|
|
7849
|
+
gesture on Chromium and WebKit (P109, P134), and the focus guard defends only the host's text fields.
|
|
7850
|
+
So a word parked as a card closed, landing after the person had moved on to a host's button or link,
|
|
7851
|
+
pulled the keyboard into the page.
|
|
7852
|
+
|
|
7853
|
+
**Found: an unparked call has no such test.** `focusMark` read nothing of the focus when this was
|
|
7854
|
+
written: the shell asked `settling()`, `mode.elements`, `isShown(id)` and for a marker, and
|
|
7855
|
+
`create-host.ts` asks only that a shown mark has a marker, the React handle nothing more. So an
|
|
7856
|
+
unparked call lands from wherever the focus is, and that is what the Esc path needs: after a card
|
|
7857
|
+
closes the focus is on the host's `<body>`, so the frame's `document.hasFocus()` is false at exactly
|
|
7858
|
+
the moment P134 is for.
|
|
7859
|
+
|
|
7860
|
+
**Decision.**
|
|
7861
|
+
|
|
7862
|
+
1. **Where `pendingMarker` lands, it is dropped unless `document.hasFocus()` is true**, asked in the
|
|
7863
|
+
anchor timer, at the landing, not when the word came: where the focus was when it was parked says
|
|
7864
|
+
nothing of where the person is now. Dropped is dropped: not parked again, and nothing is told.
|
|
7865
|
+
2. **The test is on the parked path only.** It sits at the landing, not in `focusMark`, so an unparked
|
|
7866
|
+
call is as P134 left it. In `focusMark` it would refuse every call of P134's normal flow on a calm
|
|
7867
|
+
page, and Escape would stop reaching the marker. The two paths differ in what the word is: unparked,
|
|
7868
|
+
it is the host's word of this moment, about a focus the host can see on its own page; parked, it
|
|
7869
|
+
is up to a second old, and the frame can't know what happened on the host's page since. All the
|
|
7870
|
+
shell can ask then is whether the focus is still its own.
|
|
7871
|
+
3. **That is the intended logic, with this consequence: no focus, no grab.** In the normal flow the
|
|
7872
|
+
focus is on the host's body, so a first `focusMark` that happens to park is dropped, and a host
|
|
7873
|
+
that sends a `show` as its card closes (P134's point 3 says many do) parks every time. Only a call
|
|
7874
|
+
after the focus is in the frame lands: **a host calls `focusMark` again after its own move of the
|
|
7875
|
+
focus into the frame** (`display.focus()`). This is the host's fallback P134's point 4 didn't need,
|
|
7876
|
+
and that point stands for a calm page: `focusMark` first, on its own. The word can't be parked for
|
|
7877
|
+
the host to know, and nothing says it was dropped, so the host reads its own page a moment later:
|
|
7878
|
+
the frame not `document.activeElement`, and the focus still on the body (the person hasn't moved
|
|
7879
|
+
on), is when to move and ask again (ADOPTING has the code). Asking again is cheap: a second word
|
|
7880
|
+
after a landing moves nothing, and one sent while the first waits takes its place. If the host's
|
|
7881
|
+
move comes while the first word waits, the first lands by itself.
|
|
7882
|
+
4. **The kept `hasFocus`.** `Document.prototype.hasFocus`, taken before content runs beside the kept
|
|
7883
|
+
`focus`, and called with `callOf` (the kept `Reflect.apply`), as `marker-originals` keeps a press's
|
|
7884
|
+
readers, so neither a patched `hasFocus` nor a patched `Function.prototype.call` answers.
|
|
7885
|
+
|
|
7886
|
+
**What gets worse for a host that adds no second call.** The trade is the accuracy of "back on the
|
|
7887
|
+
marker" against never pulling the keyboard into the page. Read against the shell's anchor timer and
|
|
7888
|
+
Raft's `backToMark` (`focusMark` once, then after 150 ms, from `<body>` only, the frame's own
|
|
7889
|
+
`focus()`, and no second call). A call that doesn't wait is unchanged. A call that waits meets the
|
|
7890
|
+
timer, which fires 150 ms after the last change or `show`, or at its run's one-second deadline
|
|
7891
|
+
whichever is first, so on a page still changing too, and a change after the call pushes it later:
|
|
7892
|
+
- **Normal frame, the timer fires before the host's fallback:** dropped, since the focus is on the
|
|
7893
|
+
body. The fallback then gives the frame the focus and not the marker; before this decision it
|
|
7894
|
+
landed on the marker. This is what gets worse.
|
|
7895
|
+
- **Normal frame, the timer fires after the fallback:** the focus is in the frame by then, and it
|
|
7896
|
+
lands, as before. A word parked by a `show` sent with it starts a 150 ms timer of its own, so
|
|
7897
|
+
against a 150 ms fallback the two are within a post of each other and either can come first.
|
|
7898
|
+
(Raft's marks don't change as a card closes, so there it is the page's changes that park it.)
|
|
7899
|
+
- **Nested page that had the focus:** the page's `hasFocus` stays false after the host's move (below),
|
|
7900
|
+
so a call that waits is dropped whenever the timer fires, whatever parked it, where it used to land.
|
|
7901
|
+
A nested page that never had the focus isn't measured. Raft has no nested pages today.
|
|
7902
|
+
|
|
7903
|
+
**Compatibility.** No API, message or report changes. A host that only ever calls on a calm page sees
|
|
7904
|
+
no change. A host whose first call parks stops getting the landing it got by luck: that landing was
|
|
7905
|
+
the bug, on a page the person may have left. Its fallback is the second call. An older shell lands
|
|
7906
|
+
as it did, and a second call there is harmless. The shell is the content server's: upgrade that. Hosts whose fallback already moves the focus into the frame (Raft: "within
|
|
7907
|
+
150 ms if the marker didn't take it") must add the second `focusMark`, or the keyboard stops at the
|
|
7908
|
+
frame's document and not on the marker.
|
|
7909
|
+
|
|
7910
|
+
**Threat.**
|
|
7911
|
+
- A page that patches `hasFocus` to say yes gets no landing the platform's answer refuses (control
|
|
7912
|
+
`marker-has-focus`; `marker-late` takes the test out). A page saying no only loses its own marker.
|
|
7913
|
+
- A page can make the true answer true: it may `focus()` its own element from anywhere but a host's
|
|
7914
|
+
text field (P109), and a parked word then lands. That gives it nothing: it already has the keyboard,
|
|
7915
|
+
and it can forge the message and focus a marker itself (P134).
|
|
7916
|
+
- A page can make a word park, by changing its content as the word comes, and so get it dropped. It
|
|
7917
|
+
reads the message anyway, and can take the focus back at once: failing is fine (P134), and the
|
|
7918
|
+
host's fallback then asks again.
|
|
7919
|
+
- `hasFocus` says the focus is in this document (or a frame of its own), not where. A parked word can
|
|
7920
|
+
still move the focus off the page's own field onto a marker. That stays inside the frame, is no
|
|
7921
|
+
keyboard taken from the host, and a page's own focus order is not the host's to defend (P133).
|
|
7922
|
+
- It still doesn't expire. Nothing here bounds a word parked while the content isn't in: it is only
|
|
7923
|
+
held to the same test when it lands, however late.
|
|
7924
|
+
- An unparked call lands from anywhere on the host's page, a host's button too, as in P134: it is the
|
|
7925
|
+
host's own word, for one moment, and calling it after the person moved on is the host's mistake.
|
|
7926
|
+
The fallback above must look before it moves. The focus guard is unchanged.
|
|
7927
|
+
|
|
7928
|
+
**Known gap: a nested page (#proj-workspace:#214).** Measured by CI on Chromium with frames in and
|
|
7929
|
+
out of process, WebKit and Firefox (Playwright 1.63): after a nested page had the focus and the
|
|
7930
|
+
person moved to a host's button, `display.focus()` leaves the page's `hasFocus` false, so this
|
|
7931
|
+
decision's fallback doesn't work there for a call that waits. The host's `activeElement` is the
|
|
7932
|
+
frame. On Chromium and WebKit the shell's is still the page's frame, so `frame.ts`'s focus listener
|
|
7933
|
+
doesn't pass the move on (`document.activeElement !== frame`). On Firefox the shell's isn't, so that
|
|
7934
|
+
listener's test doesn't explain it, and why isn't known. No focus goes to the page, so nothing leaks,
|
|
7935
|
+
and a call that doesn't wait lands (tested). This is an older path than P135, in `frame.ts`, which
|
|
7936
|
+
this decision doesn't change; `nested.spec.ts` marks the one step `test.fail` until #214 closes.
|
|
7937
|
+
|
|
7938
|
+
**Tested.** Measured by CI's run of these specs, on the engines as Playwright builds them.
|
|
7939
|
+
`leak/annotate.spec.ts`, three engines: "document.hasFocus() in a frame says where a host's moves leave the focus…" (the probe:
|
|
7940
|
+
a host's field, the body, the host's move in, the page's field, a host's button, the move back, an
|
|
7941
|
+
unparked landing); "a parked focusMark doesn't land once the person has moved on…" (`marker-late`),
|
|
7942
|
+
parked by a `show` with the person already gone; "a focusMark parked with the focus in the frame…"
|
|
7943
|
+
(`marker-late`), on a page that keeps changing, the person gone before it lands; "a parked focusMark
|
|
7944
|
+
with the focus on the host's body is dropped; after the host's own move…" (`marker-late`), the second
|
|
7945
|
+
parked too, and Enter on it reporting that mark; "a page that patched hasFocus…" (`marker-has-focus`, `marker-late`). P134's
|
|
7946
|
+
"focusMark puts the focus on that mark's marker…" is the unparked call from the body, on a calm page,
|
|
7947
|
+
unchanged; "focusMark right after a show…" now moves the focus in first. `leak/served/nested.spec.ts`:
|
|
7948
|
+
"a parked focusMark lands on a nested page's marker while the focus is in the page…", "a focusMark that
|
|
7949
|
+
doesn't wait lands on a nested page that had the focus…", and "a page that had the focus gets it back
|
|
7950
|
+
by the host's own move…", the known gap, `test.fail` from that step on. `test/annotate.test.ts`: the kept function, the
|
|
7951
|
+
landing's test, and no read of the focus in `focusMark`. CI's WebKit is Playwright's build, not
|
|
7952
|
+
Safari; Safari and iOS are unmeasured. Playwright emulates a focused window on every engine, so
|
|
7953
|
+
`hasFocus` false for a window behind another app (dropped, by the standard) is unmeasured too.
|
|
7954
|
+
|
|
7955
|
+
**Rejected.**
|
|
7956
|
+
- The test in `focusMark`: see point 2.
|
|
7957
|
+
- A time limit on the parked word: how long a word has waited says nothing of where the person is;
|
|
7958
|
+
a word 100 ms old can land on a person who moved on at 90.
|
|
7959
|
+
- Reading the host's focus from the host: `focusMark` sent only if the frame holds the focus, or a
|
|
7960
|
+
host-side recheck when the frame settles. The first is the Esc path again, the second a new report
|
|
7961
|
+
and a round trip for a moment where failing is fine.
|
|
7962
|
+
- `activeElement` in the frame (dropped unless on `<body>` or the layer): stricter inside the page, and
|
|
7963
|
+
the page writes that document; the wall here is the frame's edge.
|
|
7964
|
+
- Parking the word and landing it when focus next comes into the frame: a word with no end, landing
|
|
7965
|
+
at a moment nobody asked for.
|
|
7966
|
+
|
|
7967
|
+
**Revisit when** #214 closes (take off the `test.fail`, and assert the landing after the host's move
|
|
7968
|
+
on a nested page); a host needs a parked word to land without moving the focus in first; CI or a real
|
|
7969
|
+
Safari shows `hasFocus` disagreeing with the host's `activeElement` after `display.focus()`; or a
|
|
7970
|
+
word must expire by itself (a host that sends many, or content that stays out for long).
|