@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.
@@ -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;
@@ -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;
@@ -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
@@ -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);
@@ -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
  }), []);
@@ -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`) and it
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;
@@ -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`) and it
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
- // What a marker is called (P133), to whoever can't see it: what it is, and the words it is
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, and has nothing one click away that
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 ("3 comments on …", from the `count` and the
438
- anchor's `label`; in English, whatever your UI's language). Enter or Space on it is `activated`,
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. Then
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).