@botiverse/porthole 0.14.11 → 0.14.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/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; a call that had to wait for them is dropped unless the focus is in the frame's document as it lands (the DOM's own `hasFocus`, taken before content runs; P135; on a nested page that had the focus the host's `display.focus()` doesn't bring it back, a known gap), one that didn't wait isn't asked; nothing is reported back, and with no such marker, or while elements are picked, nothing happens. For after the keyboard closed the host's view: Escape, or a Tab past its ends (P134); a host calls it again after its own `display.focus()` |
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,12 @@ 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`), a call parked meanwhile
1196
+ dropped once the person has moved on or the focus is on the host's body, and a second after the
1197
+ host's `display.focus()` landing (P135, `marker-late`), by the kept
1198
+ `hasFocus`, which a page's patch can't answer (`marker-has-focus`); on a nested page a parked call
1199
+ lands while the focus is in the page, and that host's move is a known gap (`test.fail`, P135), at its paragraph's end past the last word, a nested block's
1194
1200
  words not its own, a draft's by its words; focus and
1195
1201
  selection kept, a drag from a marker too (`marker-prevent` → the press case), none
1196
1202
  without a count, stepping aside while picking, drawn whole at the frame's top; a
@@ -1532,6 +1538,9 @@ control the tables above name to the registry):
1532
1538
  | `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
1539
  | `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
1540
  | `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)` | — | — |
1541
+ | `marker-focus` | `annotate.spec.ts` | `a page that patched focus isn't handed the marker the host's focusMark moves to (P134)` | — | — |
1542
+ | `marker-late` | `annotate.spec.ts` | `a parked focusMark doesn't land once the person has moved on to the host's button (P135)`, `a focusMark parked with the focus in the frame doesn't land once the person moves on while it waits (P135)`, `a parked focusMark with the focus on the host's body is dropped; after the host's own move into the frame a second one, parked too, lands on the marker (P135)`, `a page that patched hasFocus to say yes gets no landing the platform's own answer refuses (P135)` | — | — |
1543
+ | `marker-has-focus` | `annotate.spec.ts` | `a page that patched hasFocus to say yes gets no landing the platform's own answer refuses (P135)` | — | — |
1535
1544
  | `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
1545
  | `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
1546
  | `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.13 (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,11 @@ 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. 0.14.13: P135 drops a `focusMark` that had to wait unless the focus is
40
+ in the frame's document by then; a call on a calm page is unchanged. Known gap: a nested page that had the
41
+ focus doesn't get it back from `display.focus()` (§6).
38
42
 
39
43
  ## 1. Two layers
40
44
 
@@ -227,6 +231,11 @@ Whatever the use:
227
231
  when `selected` comes, so what it can do with that moment is put the person's next keys into a
228
232
  draft they see and can discard, never send one; outside such a mode, or for a composer that can
229
233
  send, it takes no focus.
234
+ A second exception (P134): a host may move focus into a view a report opened if all of these hold:
235
+ it reads its own page's `document.activeElement` and that is this frame; the focus goes only to a
236
+ container that takes no input (`tabindex="-1"`), never a field or a button; and every control in
237
+ that view that can write has the host's own gate, so that a forged opening and the keys right after
238
+ it can't submit. That's the host's duty: Porthole doesn't guarantee it.
230
239
  - Know that a display can take the keyboard: a page calls `focus()` on its own input whenever it
231
240
  likes (on Chromium and WebKit with no gesture), and what the person goes on typing goes to it.
232
241
  `createHost` (every `PortholeView` too) gives focus back when it leaves one of the page's text
@@ -236,6 +245,14 @@ Whatever the use:
236
245
  your composer with `focusField(field)`, not the field's own `focus()` (Firefox ignores that while
237
246
  a fighting frame holds focus); and with a platform of your own, implement its focus guard
238
247
  (`focused`, `onFocusTaken`, `focus`) or accept that a display can read what is typed beside it.
248
+ - Call `annotations.focusMark(id)` only as the person's key closes your view of that mark, and know
249
+ it can be dropped (P135): one that has to wait while the frame finds its marks lands only if the
250
+ focus is in the frame by then, and in the normal flow it is on your `<body>`. Nothing says so. If
251
+ the focus is still on your body a moment later, the person hasn't moved on: `display.focus()`,
252
+ then `focusMark(id)` again. Look first: that move is yours, the focus guard doesn't judge it, and
253
+ a move after the person went on to a button of yours takes the keyboard from them. A known gap
254
+ (P135): on a nested page that had the focus, `display.focus()` doesn't bring it back, so a word
255
+ that waits is dropped even then. Nothing leaks: the keyboard stays out of the page.
239
256
  - List every app origin in `appOrigins` (`hostOrigins` in `/server`): only those may frame content,
240
257
  and only those are checked against the content domain for a shared site.
241
258
  - Under the app runtime, run `defineRuntimeConformance` with `api` in CI (§7).
@@ -856,9 +873,46 @@ own frame, below the shell, P111), so:
856
873
  power but `activated`, which it can fake anyway within the host's checks, keys go to a marker only
857
874
  while the frame has the focus, so nothing typed in the host passes through it (P109 is unchanged),
858
875
  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.
876
+ marker's name, the page's own words after the shell's, in quotes that bound nothing (P134: a
877
+ text anchor's `label`, an element's quote, or what follows the tag in its `label`). A host can't
878
+ rely on a marker being reached, as it can't on one being seen: its own list of marks is the
879
+ keyboard way that holds.
880
+ - *Which input made an `activated`* (P134). The report doesn't say, and a field saying so would be
881
+ the page's word. A host reads its own page instead, as the report arrives: is the frame element
882
+ `document.activeElement`? The page can't fake that reading, and that is all it gets. It tells that
883
+ the focus is in the frame, not that a key was pressed: a pointer's click after the person was
884
+ in the frame reads the same, and the page can move the focus into its frame itself, from anywhere
885
+ but one of the host's text fields (the guard lets that be, P109). **The page can still forge
886
+ `activated` while the person really is in the frame, and this signal doesn't stop that.** A host
887
+ that moves the keyboard into its view on the signal takes §6's second exception, with its
888
+ conditions: a page can put the person's next keys in that view, and keeping those keys from posting
889
+ is the host's own gate on that view's controls, not Porthole's.
890
+ - *Back to a marker* (P134). `annotations.focusMark(id)` is the host's word to the frame
891
+ (`porthole/annotate.focusMark`, `{ id }`), for one moment only: after the keyboard closed the host's
892
+ own view of that mark, by Escape or by a Tab past its first or last control. No content goes with it, beyond an id the frame has, and nothing comes back. The
893
+ shell moves the focus through the platform's `focus` as it was before content ran (control
894
+ `marker-focus`: a page that replaced it is handed the marker otherwise); with no such marker it does
895
+ nothing. The page reads the message, so it learns a card closed, and can take the focus back at once
896
+ or forge the message and focus a marker itself, which gives it nothing a fake `activated` doesn't:
897
+ a host can't rely on the focus landing. To the focus guard the move is the frame's own, so from a
898
+ host's text field that still has focus it is undone and counted (P109), not passed as the host's:
899
+ no window was opened in the guard for it.
900
+ A word that has to wait while the frame finds its marks is up to a second old when it could land
901
+ (P135), and a marker's `focus()` takes the keyboard with no gesture on Chromium and WebKit, past a
902
+ guard that defends only text fields: a person gone on to a host's button would be pulled back. So
903
+ the shell drops a parked word unless the focus is in its document as it lands, by `hasFocus` as it
904
+ was before content ran (control `marker-has-focus`: a page that replaced it to say yes gets the
905
+ landing otherwise; `marker-late` takes the test out). A word that doesn't wait isn't asked: it is
906
+ the host's word of this moment, and the frame has no focus then on the very path it is for. A page
907
+ can really take the focus and so pass the test, which gives it nothing, since it then has the
908
+ keyboard; and a parked word can still move the focus off the page's own field onto a marker, inside
909
+ the frame. §6 has the host's side: a second `focusMark` after its own `display.focus()`.
910
+ The word is a message, so from the host's close until the frame moves, the focus rests on the host's
911
+ body. A forged `activated` in that gap finds no frame focused, so a host that gates a view on "the
912
+ frame had the focus" doesn't gate that one. That is accepted, on the host's side of the wall: such
913
+ a view takes no focus and keeps keys out until the focus has reached the frame (in Raft, content
914
+ inert for 500 ms, and the focus handed back to the frame within 150 ms if the marker didn't take
915
+ it, with `focusMark` again after it, P135), so the keys go to the page and nothing is written.
862
916
  - *What doesn't hold against content that does.* The shell shares the content's realm. It reads
863
917
  and stops a marker's press through the platform's own functions and getters, kept before
864
918
  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.13",
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,11 @@ 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
+ /**
244
+ * Host → frame: put the focus on one mark's marker (`{ id }`), telling nothing back (P134); one
245
+ * that waited for the marks is dropped unless the focus is in the frame's document by then (P135).
246
+ */
247
+ focusMark: "porthole/annotate.focusMark",
243
248
  } as const;
244
249
 
245
250
  /** 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,25 @@ 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
+ * On a calm page it lands at once, from anywhere on the host's page. While the frame is finding
334
+ * its marks (a `show` just sent, the content just changed) it waits, and is then dropped unless
335
+ * the focus is in the frame by then (P135), so a word that comes late takes no keyboard from a
336
+ * person who moved on. Nothing says it was dropped: if the frame isn't your page's
337
+ * `document.activeElement` soon after and the person hasn't moved on, call `focus()` and then
338
+ * `focusMark(id)` again. Known gap: on a nested page that had the focus, `focus()` doesn't bring
339
+ * it back into the page, so a second call that waits is dropped too (ADOPTING).
340
+ */
341
+ focusMark(id: string): void;
323
342
  }
324
343
 
325
344
  export interface DisplayControls {
@@ -497,6 +497,14 @@ export interface PortholeFrameHandle {
497
497
  * `"annotations"` (the core's call throws; this never does).
498
498
  */
499
499
  clearSelection(): void;
500
+ /**
501
+ * Puts the keyboard back on a mark's marker in the frame (`annotations.focusMark(id)`, P134),
502
+ * once Escape closed your own view of that mark. Nothing happens for an id with no marker, or
503
+ * while no display runs. A config without `annotate`: `onHostError`, kind `"annotations"`. While
504
+ * the frame is finding its marks it waits, and is dropped unless the focus is in the frame by
505
+ * then (P135): call it again after your own move of the focus into the frame.
506
+ */
507
+ focusMark(id: string): void;
500
508
  /**
501
509
  * Finds `query` in the frame and highlights it (`find.query`, P131): where the matches stand,
502
510
  * or `"unsupported"` (a config without `find`, an older shell, no answer in time, a later
@@ -812,6 +820,12 @@ export function PortholeFrame(props: PortholeFrameProps): ReactElement {
812
820
  attempt(() => now.annotations.clearSelection(), own.current);
813
821
  }
814
822
  },
823
+ focusMark(id) {
824
+ const now = display.current;
825
+ if (now !== null) {
826
+ attempt(() => now.annotations.focusMark(id), own.current);
827
+ }
828
+ },
815
829
  find(query, options) {
816
830
  try {
817
831
  checkFindQuery(query, options);
@@ -253,6 +253,7 @@ function InstanceView(props: PortholeViewProps): ReactElement | null {
253
253
  ref,
254
254
  (): PortholeFrameHandle => ({
255
255
  clearSelection: () => shown.current?.clearSelection(),
256
+ focusMark: (id) => shown.current?.focusMark(id),
256
257
  find: (query, options) =>
257
258
  shown.current?.find(query, options) ?? Promise.resolve("unsupported"),
258
259
  clearFind: () => shown.current?.clearFind(),
@@ -34,14 +34,37 @@ export const MARKER_HIT = String.raw`(count, boxAt, x, y, touch) => {
34
34
  return best;
35
35
  }`;
36
36
 
37
+ /**
38
+ * What a marker is called (P133, P134), to whoever can't see it, spliced into the runtime: what it
39
+ * is, and the words it is on, in quotes. In English, whatever the page's language: the shell has no
40
+ * words of the host's. `anchor.label` stays as the host stores it (it is the host's to show): an
41
+ * element's starts with its tag (`describe`, "p#intro.lead Words"), so an element's words are its
42
+ * quote, cut where the label's are and marked so, or for one with no text of its own (an image's
43
+ * `alt`) what follows the tag in the label. An element with neither has no words.
44
+ */
45
+ export const MARKER_NAME = String.raw`(mark) => {
46
+ const squash = (text) => String(text).replace(/\s+/g, " ").trim();
47
+ const anchor = mark.anchor;
48
+ const label = typeof anchor.label === "string" ? squash(anchor.label).slice(0, 120) : "";
49
+ let words = label;
50
+ if (anchor.kind === "element") {
51
+ const quote = anchor.selectors.filter((each) => each && each.type === "TextQuoteSelector")[0];
52
+ const said = quote && typeof quote.exact === "string" ? squash(quote.exact.slice(0, 300)) : "";
53
+ const space = label.indexOf(" ");
54
+ words = said.length > 40 ? said.slice(0, 40).trim() + "\u2026" : said !== "" ? said : space === -1 ? "" : label.slice(space + 1);
55
+ }
56
+ const what = mark.draft ? "Draft comment" : mark.count === 1 ? "1 comment" : mark.count > 1 ? mark.count + " comments" : "Comment";
57
+ return words === "" ? what : what + ' on "' + words + '"';
58
+ }`;
59
+
37
60
  /**
38
61
  * The shell's annotation runtime (P053), spliced into the shell's runtime (`__ANNOTATE__`) when
39
62
  * the config declares `annotate`, so it runs before any content does, with the DOM's own
40
63
  * functions as they were. Plain ES2020 like the rest of the shell; no template literals (it sits
41
64
  * in one).
42
65
  *
43
- * The host drives it (`porthole/annotate.start|stop|show|focus|clear|track|clearSelection`) and it
44
- * reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked`):
66
+ * The host drives it (`porthole/annotate.start|stop|show|focus|clear|track|clearSelection|focusMark`)
67
+ * and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked`):
45
68
  * - picking an element: the element under the pointer (or finger) is outlined with its name; a
46
69
  * click or tap picks it, and the content's own handlers never see that click (unless the content
47
70
  * patched the DOM's built-ins, P105); Escape cancels (while selecting text too, P112);
@@ -56,7 +79,9 @@ export const MARKER_HIT = String.raw`(count, boxAt, x, y, touch) => {
56
79
  * in the line's gutter), an element's on its corner; a click on it, or Enter or Space with the
57
80
  * focus on it (P133), is reported (`activated`), and the content's own handlers never see it; a
58
81
  * draft is drawn apart, a dashed line and a hollow bubble with no number, and has a marker with
59
- * or without a count;
82
+ * or without a count; the host's `focusMark` (P134) puts the focus on a marker that is there, and
83
+ * tells nothing back; one that had to wait for the marks lands only if the focus is still in this
84
+ * document (P135);
60
85
  * - following: while a mark has a marker, once a scroll, a resize or a change of the content
61
86
  * settles, the marks that moved since the host was last told are reported, at most once a
62
87
  * second, so the host's own UI beside a mark can follow;
@@ -87,6 +112,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
87
112
  track: "porthole/annotate.track",
88
113
  tracked: "porthole/annotate.tracked",
89
114
  clearSelection: "porthole/annotate.clearSelection",
115
+ focusMark: "porthole/annotate.focusMark",
90
116
  };
91
117
  // The DOM's own functions, taken before content runs.
92
118
  const elementFromPoint = Document.prototype.elementFromPoint;
@@ -97,6 +123,8 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
97
123
  const createElementNS = Document.prototype.createElementNS;
98
124
  const selectionOf = Document.prototype.getSelection;
99
125
  const removeAllRanges = Selection.prototype.removeAllRanges;
126
+ const focusElement = HTMLElement.prototype.focus;
127
+ const hasFocus = Document.prototype.hasFocus;
100
128
  const elementRect = Element.prototype.getBoundingClientRect;
101
129
  const rangeRect = Range.prototype.getBoundingClientRect;
102
130
  const rangeRects = Range.prototype.getClientRects;
@@ -401,13 +429,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
401
429
  const markerWidth = (label) => Math.max(MARKER_HEIGHT, 23 + (label === "" ? 0 : 3 + label.length * 7));
402
430
  // Compact (P105): the number alone, or the glyph alone for none, with less padding.
403
431
  const compactWidth = (label) => (label === "" ? 21 : Math.max(MARKER_HEIGHT, 10 + label.length * 7));
404
- // What a marker is called (P133), to whoever can't see it: what it is, and the words it is
405
- // on. In English, whatever the page's language: the shell has no words of the host's.
406
- const nameOf = (mark) => {
407
- const words = typeof mark.anchor.label === "string" ? squash(mark.anchor.label).slice(0, LIMIT.label) : "";
408
- const what = mark.draft ? "Draft comment" : mark.count === 1 ? "1 comment" : mark.count > 1 ? mark.count + " comments" : "Comment";
409
- return words === "" ? what : what + " on " + words;
410
- };
432
+ const nameOf = ${MARKER_NAME};
411
433
  // A rect's last line with words on it: its last box with a width, else any with a size.
412
434
  const lastBox = (rects) => {
413
435
  let any = null;
@@ -1054,6 +1076,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1054
1076
  // mark), nor before a run of changes settles; a focus asked for meanwhile waits for it.
1055
1077
  let waitingForContent = false;
1056
1078
  let pendingFocus = null;
1079
+ let pendingMarker = null;
1057
1080
  const settling = () => anchorTimer !== 0 || waitingForContent || marks.some((mark) => mark.state === null);
1058
1081
  const scheduleAnchor = (all) => {
1059
1082
  if (all) {
@@ -1092,6 +1115,17 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1092
1115
  pendingFocus = null;
1093
1116
  focus(id);
1094
1117
  }
1118
+ if (pendingMarker !== null) {
1119
+ const id = pendingMarker;
1120
+ pendingMarker = null;
1121
+ // Parked, the host's word is old: the person may have moved on, and a marker's focus
1122
+ // takes the keyboard with no gesture. So it lands only if the focus is still in this
1123
+ // document, asked through the kept function: a page that says it has the focus gets
1124
+ // no landing the platform would refuse. Otherwise it is dropped (P135).
1125
+ if (callOf(hasFocus, document, []) === true) {
1126
+ focusMark(id);
1127
+ }
1128
+ }
1095
1129
  }, wait);
1096
1130
  };
1097
1131
  new MutationObserver((records) => {
@@ -1196,6 +1230,29 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1196
1230
  report([{ mark, result: resultOf(mark, null, scroll) }], scroll);
1197
1231
  };
1198
1232
 
1233
+ // The focus on a mark's marker, at the host's word (P134). Marks a show just replaced have no
1234
+ // markers yet, so it waits for them, as focus does; then a marker that isn't there, or has
1235
+ // stepped aside for picking, is nothing to do. The kept function, so a page that patched
1236
+ // focus isn't handed the marker from inside the closed root. The shell's focus listener
1237
+ // lights it and brings it into view; nothing is told. A call that isn't parked reads no
1238
+ // focus: it is the host's word just now, and after its card closed the focus is on the
1239
+ // host's body, so this document has none yet. Only the landing of a parked one asks (P135).
1240
+ const focusMark = (id) => {
1241
+ if (settling()) {
1242
+ pendingMarker = id;
1243
+ return;
1244
+ }
1245
+ if (mode.elements || !isShown(id)) {
1246
+ return;
1247
+ }
1248
+ for (let i = 0; i < markers.length; i += 1) {
1249
+ if (markers[i].id === id) {
1250
+ callOf(focusElement, markers[i].element, [{ preventScroll: true }]);
1251
+ return;
1252
+ }
1253
+ }
1254
+ };
1255
+
1199
1256
  // A marker's click (P104). The layer takes no pointer but on its markers, so a press whose
1200
1257
  // target is the layer is on a marker: the content's handlers never see it (this listener
1201
1258
  // runs before any of theirs), nor does what lies under it, and a click is reported. A press
@@ -1630,9 +1687,13 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1630
1687
  }
1631
1688
  break;
1632
1689
  }
1690
+ case M.focusMark:
1691
+ focusMark(String(params.id));
1692
+ break;
1633
1693
  case M.clear:
1634
1694
  track(null);
1635
1695
  pendingFocus = null;
1696
+ pendingMarker = null;
1636
1697
  marks = [];
1637
1698
  active = null;
1638
1699
  hot = null;