@botiverse/porthole 0.14.11 → 0.14.12
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 +16 -0
- package/dist/annotate/types.d.ts +4 -2
- package/dist/annotate/types.js +2 -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 +11 -0
- package/dist/react/frame.d.ts +6 -0
- package/dist/react/frame.js +6 -0
- package/dist/react/view.js +1 -0
- package/dist/shell/annotate.d.ts +13 -3
- package/dist/shell/annotate.js +60 -10
- package/docs/ADOPTING.md +23 -4
- package/docs/DECISIONS.md +105 -1
- package/docs/DESIGN.md +11 -8
- package/docs/THREAT_MODEL.md +33 -5
- package/package.json +1 -1
- package/src/annotate/types.ts +4 -2
- package/src/host/create-host.ts +8 -0
- package/src/host/types.ts +11 -0
- package/src/react/frame.tsx +12 -0
- package/src/react/view.tsx +1 -0
- package/src/shell/annotate.ts +61 -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,17 @@ 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
|
+
focusMark(id: string): void;
|
|
329
340
|
}
|
|
330
341
|
export interface DisplayControls {
|
|
331
342
|
readonly displayId: string;
|
package/dist/react/frame.d.ts
CHANGED
|
@@ -154,6 +154,12 @@ 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"`.
|
|
161
|
+
*/
|
|
162
|
+
focusMark(id: string): void;
|
|
157
163
|
/**
|
|
158
164
|
* Finds `query` in the frame and highlights it (`find.query`, P131): where the matches stand,
|
|
159
165
|
* 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,8 @@ 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;
|
|
33
43
|
* - following: while a mark has a marker, once a scroll, a resize or a change of the content
|
|
34
44
|
* settles, the marks that moved since the host was last told are reported, at most once a
|
|
35
45
|
* 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,8 @@ 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;
|
|
58
81
|
* - following: while a mark has a marker, once a scroll, a resize or a change of the content
|
|
59
82
|
* settles, the marks that moved since the host was last told are reported, at most once a
|
|
60
83
|
* second, so the host's own UI beside a mark can follow;
|
|
@@ -85,6 +108,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
85
108
|
track: "porthole/annotate.track",
|
|
86
109
|
tracked: "porthole/annotate.tracked",
|
|
87
110
|
clearSelection: "porthole/annotate.clearSelection",
|
|
111
|
+
focusMark: "porthole/annotate.focusMark",
|
|
88
112
|
};
|
|
89
113
|
// The DOM's own functions, taken before content runs.
|
|
90
114
|
const elementFromPoint = Document.prototype.elementFromPoint;
|
|
@@ -95,6 +119,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
95
119
|
const createElementNS = Document.prototype.createElementNS;
|
|
96
120
|
const selectionOf = Document.prototype.getSelection;
|
|
97
121
|
const removeAllRanges = Selection.prototype.removeAllRanges;
|
|
122
|
+
const focusElement = HTMLElement.prototype.focus;
|
|
98
123
|
const elementRect = Element.prototype.getBoundingClientRect;
|
|
99
124
|
const rangeRect = Range.prototype.getBoundingClientRect;
|
|
100
125
|
const rangeRects = Range.prototype.getClientRects;
|
|
@@ -399,13 +424,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
399
424
|
const markerWidth = (label) => Math.max(MARKER_HEIGHT, 23 + (label === "" ? 0 : 3 + label.length * 7));
|
|
400
425
|
// Compact (P105): the number alone, or the glyph alone for none, with less padding.
|
|
401
426
|
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
|
-
};
|
|
427
|
+
const nameOf = ${MARKER_NAME};
|
|
409
428
|
// A rect's last line with words on it: its last box with a width, else any with a size.
|
|
410
429
|
const lastBox = (rects) => {
|
|
411
430
|
let any = null;
|
|
@@ -1052,6 +1071,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1052
1071
|
// mark), nor before a run of changes settles; a focus asked for meanwhile waits for it.
|
|
1053
1072
|
let waitingForContent = false;
|
|
1054
1073
|
let pendingFocus = null;
|
|
1074
|
+
let pendingMarker = null;
|
|
1055
1075
|
const settling = () => anchorTimer !== 0 || waitingForContent || marks.some((mark) => mark.state === null);
|
|
1056
1076
|
const scheduleAnchor = (all) => {
|
|
1057
1077
|
if (all) {
|
|
@@ -1090,6 +1110,11 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1090
1110
|
pendingFocus = null;
|
|
1091
1111
|
focus(id);
|
|
1092
1112
|
}
|
|
1113
|
+
if (pendingMarker !== null) {
|
|
1114
|
+
const id = pendingMarker;
|
|
1115
|
+
pendingMarker = null;
|
|
1116
|
+
focusMark(id);
|
|
1117
|
+
}
|
|
1093
1118
|
}, wait);
|
|
1094
1119
|
};
|
|
1095
1120
|
new MutationObserver((records) => {
|
|
@@ -1194,6 +1219,27 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1194
1219
|
report([{ mark, result: resultOf(mark, null, scroll) }], scroll);
|
|
1195
1220
|
};
|
|
1196
1221
|
|
|
1222
|
+
// The focus on a mark's marker, at the host's word (P134). Marks a show just replaced have no
|
|
1223
|
+
// markers yet, so it waits for them, as focus does; then a marker that isn't there, or has
|
|
1224
|
+
// stepped aside for picking, is nothing to do. The kept function, so a page that patched
|
|
1225
|
+
// 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
|
+
const focusMark = (id) => {
|
|
1228
|
+
if (settling()) {
|
|
1229
|
+
pendingMarker = id;
|
|
1230
|
+
return;
|
|
1231
|
+
}
|
|
1232
|
+
if (mode.elements || !isShown(id)) {
|
|
1233
|
+
return;
|
|
1234
|
+
}
|
|
1235
|
+
for (let i = 0; i < markers.length; i += 1) {
|
|
1236
|
+
if (markers[i].id === id) {
|
|
1237
|
+
callOf(focusElement, markers[i].element, [{ preventScroll: true }]);
|
|
1238
|
+
return;
|
|
1239
|
+
}
|
|
1240
|
+
}
|
|
1241
|
+
};
|
|
1242
|
+
|
|
1197
1243
|
// A marker's click (P104). The layer takes no pointer but on its markers, so a press whose
|
|
1198
1244
|
// target is the layer is on a marker: the content's handlers never see it (this listener
|
|
1199
1245
|
// runs before any of theirs), nor does what lies under it, and a click is reported. A press
|
|
@@ -1628,9 +1674,13 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1628
1674
|
}
|
|
1629
1675
|
break;
|
|
1630
1676
|
}
|
|
1677
|
+
case M.focusMark:
|
|
1678
|
+
focusMark(String(params.id));
|
|
1679
|
+
break;
|
|
1631
1680
|
case M.clear:
|
|
1632
1681
|
track(null);
|
|
1633
1682
|
pendingFocus = null;
|
|
1683
|
+
pendingMarker = null;
|
|
1634
1684
|
marks = [];
|
|
1635
1685
|
active = null;
|
|
1636
1686
|
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,31 @@ 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 Escape closes that view, and only then, close it and call
|
|
457
|
+
`display.annotations.focusMark(id)` (React: `focusMark(id)` on the `ref`) to put the keyboard back
|
|
458
|
+
on the marker. It carries no content and reports nothing; an id with no marker, or a marker the
|
|
459
|
+
page has moved away, does nothing and throws nothing; the page can take the focus straight back.
|
|
460
|
+
Close the view first: from one of your text fields that still has focus, the focus guard takes
|
|
461
|
+
the move for the page's, undoes it and counts it (`focusTaken`). Keep your own list of marks as
|
|
462
|
+
the way that holds.
|
|
445
463
|
- **Labels and quotes are the page's text**: shown only as text. Porthole takes out of a label what
|
|
446
464
|
the person can't see; a quote (`exact`) keeps it, to be found again. Hand either to a model only
|
|
447
465
|
as the page's words.
|
|
@@ -545,7 +563,8 @@ display.on("contentError", ({ message }) => log(message)); // "The content kept
|
|
|
545
563
|
display.focus(); // not frame.focus(): from a text field, that one is taken for the page's and undone
|
|
546
564
|
// Opening your composer focused: only in a comment mode the person started, for a composer that can
|
|
547
565
|
// 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
|
|
566
|
+
// shows plainly it is a draft (THREAT_MODEL §6, P112); any other view a report opens takes no focus (P134's
|
|
567
|
+
// exception, §6, is a container only, and its own conditions). Then
|
|
549
568
|
// Porthole's move, not textarea.focus().
|
|
550
569
|
import { focusField } from "@botiverse/porthole";
|
|
551
570
|
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,107 @@ 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
|
|
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:** 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.
|
package/docs/DESIGN.md
CHANGED
|
@@ -780,8 +780,8 @@ binding is mounting and lifecycle (P034).
|
|
|
780
780
|
null), `annotations` (the marks), `focusedAnnotation` (each new id is brought into
|
|
781
781
|
view; `{ id, key }` with a new key focuses the same one again), `trackedAnnotation`
|
|
782
782
|
(the mark followed, or null, P118); `onAnnotation` gets what the frame reported, `tracked`
|
|
783
|
-
boxes too. A frame that mounts again gets them all. A `ref` holds `clearSelection()`
|
|
784
|
-
(`PortholeFrameHandle`), a no-op while no display runs.
|
|
783
|
+
boxes too. A frame that mounts again gets them all. A `ref` holds `clearSelection()`, `find`,
|
|
784
|
+
`clearFind` and `focusMark(id)` (`PortholeFrameHandle`), each a no-op while no display runs.
|
|
785
785
|
- **Errors** (P055): `onContentError` gets what the content did wrong (what it
|
|
786
786
|
threw, what the sandbox blocked, a navigation the shell stopped, that it kept
|
|
787
787
|
navigating away): the agent's to hear. `onNavigationBlocked` gets a stopped
|
|
@@ -1047,6 +1047,7 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1047
1047
|
| host → frame | `porthole/annotate.focus` | `{ id }`: scrolled into view inside the frame, made the active mark, flashed |
|
|
1048
1048
|
| host → frame | `porthole/annotate.clear` | — |
|
|
1049
1049
|
| host → frame | `porthole/annotate.clearSelection` | —: the page's text selection is taken away (the DOM's own `removeAllRanges`, taken before content runs) with what the shell held of it, and nothing is reported back; marks, drafts and the mode stay (P115) |
|
|
1050
|
+
| host → frame | `porthole/annotate.focusMark` | `{ id }`: the DOM focus goes to that mark's marker (the DOM's own `focus`, taken before content runs), once the marks of a `show` are found; nothing is reported back, and with no such marker, or while elements are picked, nothing happens. For after Escape closed the host's view (P134) |
|
|
1050
1051
|
| frame → host | `porthole/annotate.selected` | `{ anchor, rect, lastLineDocumentRect?, scroll? }` (a newer shell's last two: P133, below); after a scroll, the same selection again only if its box moved more than 0.5 px, on the follow-ups' clock (P105) |
|
|
1051
1052
|
| frame → host | `porthole/annotate.unselected` | — (the text selection went away) |
|
|
1052
1053
|
| frame → host | `porthole/annotate.cancelled` | — (Escape) |
|
|
@@ -1126,8 +1127,8 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1126
1127
|
while elements are picked, the keyboard's Tab too.
|
|
1127
1128
|
- **Markers from the keyboard** (P133). Each marker is a `<button>` with a tab stop,
|
|
1128
1129
|
in the page's reading order after the page's own stops (the layer is the document's
|
|
1129
|
-
last child), named for what it is (`aria-label`:
|
|
1130
|
-
…"
|
|
1130
|
+
last child), named for what it is (`aria-label`: `3 comments on "…"`, `Draft comment
|
|
1131
|
+
on "…"`, with the words it is on, an element's tag left out, P134, in English); only the markers are exposed to
|
|
1131
1132
|
assistive technology, the layer no longer `aria-hidden`, its marks and outline are.
|
|
1132
1133
|
A press of a pointer still moves no focus. Enter and Space make the button's own
|
|
1133
1134
|
trusted click, which goes the way a pointer's does, but has no count and no place, so
|
|
@@ -1172,9 +1173,9 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1172
1173
|
see or do anything. A view a report opens or moves guards its presses
|
|
1173
1174
|
(THREAT_MODEL §6).
|
|
1174
1175
|
- **Host API.** `display.annotations.start(mode?)`, `stop()`, `show(marks)`,
|
|
1175
|
-
`focus(id)`, `track(id)`, `clear()`, `clearSelection()` (P115), and the
|
|
1176
|
-
event (`AnnotationReport`); the state is given to every frame the display runs (not a
|
|
1177
|
-
`clearSelection`: a new frame has no selection). `parseAnchor` checks an anchor a host
|
|
1176
|
+
`focus(id)`, `track(id)`, `clear()`, `clearSelection()` (P115), `focusMark(id)` (P134), and the
|
|
1177
|
+
`annotation` event (`AnnotationReport`); the state is given to every frame the display runs (not a
|
|
1178
|
+
`clearSelection`: a new frame has no selection; nor a `focusMark`). `parseAnchor` checks an anchor a host
|
|
1178
1179
|
stores (its server, before saving a comment).
|
|
1179
1180
|
|
|
1180
1181
|
Tests (`leak/annotate.spec.ts`, all three engines): a pick outlines and picks
|
|
@@ -1190,7 +1191,8 @@ double, right or middle click (`marker-click` → those two cases), by the keybo
|
|
|
1190
1191
|
too (P133: a button in reading order and named for what it is, Enter and Space
|
|
1191
1192
|
reported once, a key held down once, none of it heard, nothing while elements are
|
|
1192
1193
|
picked; `marker-key`, `marker-click` too), brought into view by the focus and keeping
|
|
1193
|
-
it through redraws,
|
|
1194
|
+
it through redraws, reached by the host's `focusMark` after its card closed and left
|
|
1195
|
+
alone where there's no such marker, by the kept `focus` (P134, `marker-focus`), at its paragraph's end past the last word, a nested block's
|
|
1194
1196
|
words not its own, a draft's by its words; focus and
|
|
1195
1197
|
selection kept, a drag from a marker too (`marker-prevent` → the press case), none
|
|
1196
1198
|
without a count, stepping aside while picking, drawn whole at the frame's top; a
|
|
@@ -1532,6 +1534,7 @@ control the tables above name to the registry):
|
|
|
1532
1534
|
| `marker-prevent` | `annotate.spec.ts` | `a marker's press, of any kind, moves nothing of the content's: no handler, no focus, no selection` | — | — |
|
|
1533
1535
|
| `marker-place` | `annotate.spec.ts` | `text markers cover no word: on a column page, and on a phone's lines with one marker each (P105, #36)` | — | — |
|
|
1534
1536
|
| `marker-key` | `annotate.spec.ts` | `a marker is a button the keyboard reaches: Tab in reading order, Enter and Space report it once, the content hears neither, and it steps aside while elements are picked (P133)` | — | — |
|
|
1537
|
+
| `marker-focus` | `annotate.spec.ts` | `a page that patched focus isn't handed the marker the host's focusMark moves to (P134)` | — | — |
|
|
1535
1538
|
| `marker-originals` | `annotate.spec.ts` | `a page that patches the event's built-ins neither hears a marker's press nor stops its report (P105)` | — | — |
|
|
1536
1539
|
| `follow-throttle` | `annotate.spec.ts` | `an honest scroll session, long, in comment mode, leaves room for a marker's click: follow-ups, the selection's too, at most one a second` | — | — |
|
|
1537
1540
|
| `selection-follow` | `annotate.spec.ts` | `an honest scroll session, long, in comment mode, leaves room for a marker's click: follow-ups, the selection's too, at most one a second` | — | — |
|
package/docs/THREAT_MODEL.md
CHANGED
|
@@ -5,7 +5,7 @@ What Porthole protects, from whom, and where that protection ends. For each way
|
|
|
5
5
|
guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
|
|
6
6
|
[DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
|
|
7
7
|
|
|
8
|
-
**Status.** This describes Porthole 0.14.
|
|
8
|
+
**Status.** This describes Porthole 0.14.12 (2026-11-06). A review on 2026-10-19 found gaps, and every decision it led to
|
|
9
9
|
has merged ([§8](#8-fixes-in-flight) lists them). P096 changed the negative-control runner and CI,
|
|
10
10
|
and the shipped conformance probes' messages and timing, not what they check. P104 (0.9.0's
|
|
11
11
|
annotation markers) had a review of its own, and P105, in 0.10.0, is what it led to. 0.11.0 was
|
|
@@ -34,7 +34,9 @@ draws from them to its own region (§6, §7); `rect` stays clamped and no wall m
|
|
|
34
34
|
makes markers buttons in the frame's Tab order, reversing P104's "no tab stop": the page shares that
|
|
35
35
|
order, so it can steer or spoil the focus, and a host keeps its own list of marks (§7). A press only
|
|
36
36
|
reports `activated`, which the page could already fake; `lastLineDocumentRect` is unclamped, for a
|
|
37
|
-
host to clip as P132's are; no wall moves.
|
|
37
|
+
host to clip as P132's are; no wall moves. 0.14.12: P134 adds `annotations.focusMark(id)`, the host's
|
|
38
|
+
word to put the keyboard back on a marker, and a second exception to "takes no focus" whose conditions
|
|
39
|
+
are the host's own (§6, §7); no wall moves.
|
|
38
40
|
|
|
39
41
|
## 1. Two layers
|
|
40
42
|
|
|
@@ -227,6 +229,11 @@ Whatever the use:
|
|
|
227
229
|
when `selected` comes, so what it can do with that moment is put the person's next keys into a
|
|
228
230
|
draft they see and can discard, never send one; outside such a mode, or for a composer that can
|
|
229
231
|
send, it takes no focus.
|
|
232
|
+
A second exception (P134): a host may move focus into a view a report opened if all of these hold:
|
|
233
|
+
it reads its own page's `document.activeElement` and that is this frame; the focus goes only to a
|
|
234
|
+
container that takes no input (`tabindex="-1"`), never a field or a button; and every control in
|
|
235
|
+
that view that can write has the host's own gate, so that a forged opening and the keys right after
|
|
236
|
+
it can't submit. That's the host's duty: Porthole doesn't guarantee it.
|
|
230
237
|
- Know that a display can take the keyboard: a page calls `focus()` on its own input whenever it
|
|
231
238
|
likes (on Chromium and WebKit with no gesture), and what the person goes on typing goes to it.
|
|
232
239
|
`createHost` (every `PortholeView` too) gives focus back when it leaves one of the page's text
|
|
@@ -856,9 +863,30 @@ own frame, below the shell, P111), so:
|
|
|
856
863
|
power but `activated`, which it can fake anyway within the host's checks, keys go to a marker only
|
|
857
864
|
while the frame has the focus, so nothing typed in the host passes through it (P109 is unchanged),
|
|
858
865
|
and a page's made-up key or `click()` is no trusted click. Assistive technology now reads the
|
|
859
|
-
marker's name, the page's own words
|
|
860
|
-
|
|
861
|
-
seen: its own list of marks is the
|
|
866
|
+
marker's name, the page's own words after the shell's, in quotes that bound nothing (P134: a
|
|
867
|
+
text anchor's `label`, an element's quote, or what follows the tag in its `label`). A host can't
|
|
868
|
+
rely on a marker being reached, as it can't on one being seen: its own list of marks is the
|
|
869
|
+
keyboard way that holds.
|
|
870
|
+
- *Which input made an `activated`* (P134). The report doesn't say, and a field saying so would be
|
|
871
|
+
the page's word. A host reads its own page instead, as the report arrives: is the frame element
|
|
872
|
+
`document.activeElement`? The page can't fake that reading, and that is all it gets. It tells that
|
|
873
|
+
the focus is in the frame, not that a key was pressed: a pointer's click after the person was
|
|
874
|
+
in the frame reads the same, and the page can move the focus into its frame itself, from anywhere
|
|
875
|
+
but one of the host's text fields (the guard lets that be, P109). **The page can still forge
|
|
876
|
+
`activated` while the person really is in the frame, and this signal doesn't stop that.** A host
|
|
877
|
+
that moves the keyboard into its view on the signal takes §6's second exception, with its
|
|
878
|
+
conditions: a page can put the person's next keys in that view, and keeping those keys from posting
|
|
879
|
+
is the host's own gate on that view's controls, not Porthole's.
|
|
880
|
+
- *Back to a marker* (P134). `annotations.focusMark(id)` is the host's word to the frame
|
|
881
|
+
(`porthole/annotate.focusMark`, `{ id }`), for one moment only: after Escape closed the host's own
|
|
882
|
+
view of that mark. No content goes with it, beyond an id the frame has, and nothing comes back. The
|
|
883
|
+
shell moves the focus through the platform's `focus` as it was before content ran (control
|
|
884
|
+
`marker-focus`: a page that replaced it is handed the marker otherwise); with no such marker it does
|
|
885
|
+
nothing. The page reads the message, so it learns a card closed, and can take the focus back at once
|
|
886
|
+
or forge the message and focus a marker itself, which gives it nothing a fake `activated` doesn't:
|
|
887
|
+
a host can't rely on the focus landing. To the focus guard the move is the frame's own, so from a
|
|
888
|
+
host's text field that still has focus it is undone and counted (P109), not passed as the host's:
|
|
889
|
+
no window was opened in the guard for it.
|
|
862
890
|
- *What doesn't hold against content that does.* The shell shares the content's realm. It reads
|
|
863
891
|
and stops a marker's press through the platform's own functions and getters, kept before
|
|
864
892
|
content runs (P105, control `marker-originals`), so patching `Event`'s or `MouseEvent`'s
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.14.
|
|
3
|
+
"version": "0.14.12",
|
|
4
4
|
"description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
|
|
5
5
|
"homepage": "https://github.com/botiverse/porthole#readme",
|
|
6
6
|
"bugs": {
|
package/src/annotate/types.ts
CHANGED
|
@@ -100,8 +100,8 @@ export interface AnnotationMark {
|
|
|
100
100
|
* draws the bubble alone) at the end of a text anchor's paragraph (P133) and the top right of an
|
|
101
101
|
* element. The person can click it, or reach it with the keyboard and press Enter or Space
|
|
102
102
|
* (P133): the frame reports `activated`. Its accessible name says what it is, with the count and
|
|
103
|
-
*
|
|
104
|
-
* draft's is dropped (P107): its marker has no number.
|
|
103
|
+
* the words it is on, quoted, an element's tag left out (P134). The content can read the number;
|
|
104
|
+
* give one only where the page may know it. A draft's is dropped (P107): its marker has no number.
|
|
105
105
|
*/
|
|
106
106
|
readonly count?: number;
|
|
107
107
|
/**
|
|
@@ -240,6 +240,8 @@ export const ANNOTATE_METHODS = {
|
|
|
240
240
|
tracked: "porthole/annotate.tracked",
|
|
241
241
|
/** Host → frame: take the page's text selection away, telling nothing back (P115). */
|
|
242
242
|
clearSelection: "porthole/annotate.clearSelection",
|
|
243
|
+
/** Host → frame: put the focus on one mark's marker (`{ id }`), telling nothing back (P134). */
|
|
244
|
+
focusMark: "porthole/annotate.focusMark",
|
|
243
245
|
} as const;
|
|
244
246
|
|
|
245
247
|
/** The most of each part of an anchor or report the host takes. */
|
package/src/host/create-host.ts
CHANGED
|
@@ -664,6 +664,14 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
664
664
|
needsAnnotate("clearSelection");
|
|
665
665
|
toFrame(ANNOTATE_METHODS.clearSelection, {});
|
|
666
666
|
},
|
|
667
|
+
focusMark(id) {
|
|
668
|
+
// Host → frame only, and kept for no later frame (P134). A mark that has gone, or has no
|
|
669
|
+
// marker, is nothing to ask for, and no fault: the host's card closed with the mark's.
|
|
670
|
+
needsAnnotate("focusMark");
|
|
671
|
+
if (marks.some((mark) => mark.id === id && hasMarker(mark))) {
|
|
672
|
+
toFrame(ANNOTATE_METHODS.focusMark, { id });
|
|
673
|
+
}
|
|
674
|
+
},
|
|
667
675
|
};
|
|
668
676
|
|
|
669
677
|
const hostContext = (): HostContext => {
|
package/src/host/types.ts
CHANGED
|
@@ -320,6 +320,17 @@ export interface AnnotationControls {
|
|
|
320
320
|
* a frame that runs later (it has no selection to clear).
|
|
321
321
|
*/
|
|
322
322
|
clearSelection(): void;
|
|
323
|
+
/**
|
|
324
|
+
* Puts the keyboard back on a mark's marker in the frame (P134): for after Escape closed the
|
|
325
|
+
* host's own view of that mark, and for nothing else. No content goes with it, and no report
|
|
326
|
+
* comes of it. Nothing happens, and nothing throws, for an id no mark with a marker is shown
|
|
327
|
+
* under, or if the frame has no such marker now (its words are gone, elements are being picked):
|
|
328
|
+
* the display's own `focus()` isn't used, so the frame takes no focus for a marker it hasn't got.
|
|
329
|
+
* Call it once the view is closed: from one of the page's text fields that still has focus, the
|
|
330
|
+
* move is the frame's own to the focus guard, undone and counted (P109). The page can take the
|
|
331
|
+
* focus back at once. Not kept for a frame that runs later.
|
|
332
|
+
*/
|
|
333
|
+
focusMark(id: string): void;
|
|
323
334
|
}
|
|
324
335
|
|
|
325
336
|
export interface DisplayControls {
|