@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.
@@ -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,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;
@@ -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
@@ -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,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;
@@ -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,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
- // 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
- };
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, 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,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 ("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 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. Then
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()` alone
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`: "3 comments on …", "Draft comment on
1130
- …", with the mark's `anchor.label`, in English); only the markers are exposed to
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 `annotation`
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, at its paragraph's end past the last word, a nested block's
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` | — | — |
@@ -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.11 (2026-11-06). A review on 2026-10-19 found gaps, and every decision it led to
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 (`anchor.label`, the host's copy with what can't be seen taken
860
- out) after the shell's. A host can't rely on a marker being reached, as it can't on one being
861
- seen: its own list of marks is the keyboard way that holds.
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.11",
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": {
@@ -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
- * `anchor.label`. The content can read the number; give one only where the page may know it. A
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. */
@@ -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 {