@botiverse/porthole 0.14.12 → 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.
@@ -335,6 +335,14 @@ export interface AnnotationControls {
335
335
  * Call it once the view is closed: from one of the page's text fields that still has focus, the
336
336
  * move is the frame's own to the focus guard, undone and counted (P109). The page can take the
337
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).
338
346
  */
339
347
  focusMark(id: string): void;
340
348
  }
@@ -157,7 +157,9 @@ export interface PortholeFrameHandle {
157
157
  /**
158
158
  * Puts the keyboard back on a mark's marker in the frame (`annotations.focusMark(id)`, P134),
159
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"`.
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.
161
163
  */
162
164
  focusMark(id: string): void;
163
165
  /**
@@ -39,7 +39,8 @@ export declare const MARKER_NAME: string;
39
39
  * focus on it (P133), is reported (`activated`), and the content's own handlers never see it; a
40
40
  * draft is drawn apart, a dashed line and a hollow bubble with no number, and has a marker with
41
41
  * or without a count; the host's `focusMark` (P134) puts the focus on a marker that is there, and
42
- * tells nothing back;
42
+ * tells nothing back; one that had to wait for the marks lands only if the focus is still in this
43
+ * document (P135);
43
44
  * - following: while a mark has a marker, once a scroll, a resize or a change of the content
44
45
  * settles, the marks that moved since the host was last told are reported, at most once a
45
46
  * second, so the host's own UI beside a mark can follow;
@@ -77,7 +77,8 @@ export const MARKER_NAME = String.raw `(mark) => {
77
77
  * focus on it (P133), is reported (`activated`), and the content's own handlers never see it; a
78
78
  * draft is drawn apart, a dashed line and a hollow bubble with no number, and has a marker with
79
79
  * or without a count; the host's `focusMark` (P134) puts the focus on a marker that is there, and
80
- * tells nothing back;
80
+ * tells nothing back; one that had to wait for the marks lands only if the focus is still in this
81
+ * document (P135);
81
82
  * - following: while a mark has a marker, once a scroll, a resize or a change of the content
82
83
  * settles, the marks that moved since the host was last told are reported, at most once a
83
84
  * second, so the host's own UI beside a mark can follow;
@@ -120,6 +121,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
120
121
  const selectionOf = Document.prototype.getSelection;
121
122
  const removeAllRanges = Selection.prototype.removeAllRanges;
122
123
  const focusElement = HTMLElement.prototype.focus;
124
+ const hasFocus = Document.prototype.hasFocus;
123
125
  const elementRect = Element.prototype.getBoundingClientRect;
124
126
  const rangeRect = Range.prototype.getBoundingClientRect;
125
127
  const rangeRects = Range.prototype.getClientRects;
@@ -1113,7 +1115,13 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1113
1115
  if (pendingMarker !== null) {
1114
1116
  const id = pendingMarker;
1115
1117
  pendingMarker = null;
1116
- focusMark(id);
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
+ }
1117
1125
  }
1118
1126
  }, wait);
1119
1127
  };
@@ -1223,7 +1231,9 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1223
1231
  // markers yet, so it waits for them, as focus does; then a marker that isn't there, or has
1224
1232
  // stepped aside for picking, is nothing to do. The kept function, so a page that patched
1225
1233
  // 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.
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).
1227
1237
  const focusMark = (id) => {
1228
1238
  if (settling()) {
1229
1239
  pendingMarker = id;
package/docs/ADOPTING.md CHANGED
@@ -453,13 +453,48 @@ composer.onClose(() => display.annotations.clearSelection());
453
453
  can forge `activated` while the person really is there, which this doesn't stop. So moving the
454
454
  keyboard into your view on it is your own step outside "takes no focus" above, and a page can
455
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
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
457
459
  `display.annotations.focusMark(id)` (React: `focusMark(id)` on the `ref`) to put the keyboard back
458
460
  on the marker. It carries no content and reports nothing; an id with no marker, or a marker the
459
461
  page has moved away, does nothing and throws nothing; the page can take the focus straight back.
460
462
  Close the view first: from one of your text fields that still has focus, the focus guard takes
461
463
  the move for the page's, undoes it and counts it (`focusTaken`). Keep your own list of marks as
462
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.
463
498
  - **Labels and quotes are the page's text**: shown only as text. Porthole takes out of a label what
464
499
  the person can't see; a quote (`exact`) keeps it, to be found again. Hand either to a model only
465
500
  as the page's words.
package/docs/DECISIONS.md CHANGED
@@ -7734,7 +7734,7 @@ it didn't focus is missed, or reported as the marker that has the focus, so the
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
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
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
7738
 
7739
7739
  Amends P133 (its point 1, the name) and adds to P104's host API. Two follow-ups for comment markers,
7740
7740
  from a host (Raft web): a person who pressed Enter on a marker reads the host's card, presses
@@ -7748,7 +7748,7 @@ anchor's marker is read out as "1 comment on p Paragraph 3. Filler…", the tag
7748
7748
  is `focus(id)`'s, for the mark's marker: `focus` scrolls to a mark and lights it, and moves no DOM
7749
7749
  focus. The shell moves the DOM focus to that mark's marker button, with the platform's `focus`
7750
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
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
7752
  own view of that mark. Nothing else needs a host to move the keyboard into a frame, and P109 and
7753
7753
  §6 spend a good deal on keeping it out.
7754
7754
  2. **No content, and nothing new back.** An id the host already sent in `show`; no report, no field,
@@ -7837,3 +7837,134 @@ focusMark…". Reports are found by what they say, and a control's own follow-up
7837
7837
  **Revisit when** a host needs to return focus somewhere other than after Escape; a host's card has a
7838
7838
  reason to stay open while the keyboard goes back; or a platform's guard should take a host's own word
7839
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).
package/docs/DESIGN.md CHANGED
@@ -1047,7 +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
+ | 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()` |
1051
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) |
1052
1052
  | frame → host | `porthole/annotate.unselected` | — (the text selection went away) |
1053
1053
  | frame → host | `porthole/annotate.cancelled` | — (Escape) |
@@ -1192,7 +1192,11 @@ too (P133: a button in reading order and named for what it is, Enter and Space
1192
1192
  reported once, a key held down once, none of it heard, nothing while elements are
1193
1193
  picked; `marker-key`, `marker-click` too), brought into view by the focus and keeping
1194
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
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
1196
1200
  words not its own, a draft's by its words; focus and
1197
1201
  selection kept, a drag from a marker too (`marker-prevent` → the press case), none
1198
1202
  without a count, stepping aside while picking, drawn whole at the frame's top; a
@@ -1535,6 +1539,8 @@ control the tables above name to the registry):
1535
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)` | — | — |
1536
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)` | — | — |
1537
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)` | — | — |
1538
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)` | — | — |
1539
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` | — | — |
1540
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.12 (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
@@ -36,7 +36,9 @@ order, so it can steer or spoil the focus, and a host keeps its own list of mark
36
36
  reports `activated`, which the page could already fake; `lastLineDocumentRect` is unclamped, for a
37
37
  host to clip as P132's are; no wall moves. 0.14.12: P134 adds `annotations.focusMark(id)`, the host's
38
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.
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).
40
42
 
41
43
  ## 1. Two layers
42
44
 
@@ -243,6 +245,14 @@ Whatever the use:
243
245
  your composer with `focusField(field)`, not the field's own `focus()` (Firefox ignores that while
244
246
  a fighting frame holds focus); and with a platform of your own, implement its focus guard
245
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.
246
256
  - List every app origin in `appOrigins` (`hostOrigins` in `/server`): only those may frame content,
247
257
  and only those are checked against the content domain for a shared site.
248
258
  - Under the app runtime, run `defineRuntimeConformance` with `api` in CI (§7).
@@ -878,8 +888,8 @@ own frame, below the shell, P111), so:
878
888
  conditions: a page can put the person's next keys in that view, and keeping those keys from posting
879
889
  is the host's own gate on that view's controls, not Porthole's.
880
890
  - *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
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
883
893
  shell moves the focus through the platform's `focus` as it was before content ran (control
884
894
  `marker-focus`: a page that replaced it is handed the marker otherwise); with no such marker it does
885
895
  nothing. The page reads the message, so it learns a card closed, and can take the focus back at once
@@ -887,6 +897,22 @@ own frame, below the shell, P111), so:
887
897
  a host can't rely on the focus landing. To the focus guard the move is the frame's own, so from a
888
898
  host's text field that still has focus it is undone and counted (P109), not passed as the host's:
889
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.
890
916
  - *What doesn't hold against content that does.* The shell shares the content's realm. It reads
891
917
  and stops a marker's press through the platform's own functions and getters, kept before
892
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.12",
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": {
@@ -240,7 +240,10 @@ 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). */
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
+ */
244
247
  focusMark: "porthole/annotate.focusMark",
245
248
  } as const;
246
249
 
package/src/host/types.ts CHANGED
@@ -329,6 +329,14 @@ export interface AnnotationControls {
329
329
  * Call it once the view is closed: from one of the page's text fields that still has focus, the
330
330
  * move is the frame's own to the focus guard, undone and counted (P109). The page can take the
331
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).
332
340
  */
333
341
  focusMark(id: string): void;
334
342
  }
@@ -500,7 +500,9 @@ export interface PortholeFrameHandle {
500
500
  /**
501
501
  * Puts the keyboard back on a mark's marker in the frame (`annotations.focusMark(id)`, P134),
502
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"`.
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.
504
506
  */
505
507
  focusMark(id: string): void;
506
508
  /**
@@ -80,7 +80,8 @@ export const MARKER_NAME = String.raw`(mark) => {
80
80
  * focus on it (P133), is reported (`activated`), and the content's own handlers never see it; a
81
81
  * draft is drawn apart, a dashed line and a hollow bubble with no number, and has a marker with
82
82
  * or without a count; the host's `focusMark` (P134) puts the focus on a marker that is there, and
83
- * tells nothing back;
83
+ * tells nothing back; one that had to wait for the marks lands only if the focus is still in this
84
+ * document (P135);
84
85
  * - following: while a mark has a marker, once a scroll, a resize or a change of the content
85
86
  * settles, the marks that moved since the host was last told are reported, at most once a
86
87
  * second, so the host's own UI beside a mark can follow;
@@ -123,6 +124,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
123
124
  const selectionOf = Document.prototype.getSelection;
124
125
  const removeAllRanges = Selection.prototype.removeAllRanges;
125
126
  const focusElement = HTMLElement.prototype.focus;
127
+ const hasFocus = Document.prototype.hasFocus;
126
128
  const elementRect = Element.prototype.getBoundingClientRect;
127
129
  const rangeRect = Range.prototype.getBoundingClientRect;
128
130
  const rangeRects = Range.prototype.getClientRects;
@@ -1116,7 +1118,13 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1116
1118
  if (pendingMarker !== null) {
1117
1119
  const id = pendingMarker;
1118
1120
  pendingMarker = null;
1119
- focusMark(id);
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
+ }
1120
1128
  }
1121
1129
  }, wait);
1122
1130
  };
@@ -1226,7 +1234,9 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1226
1234
  // markers yet, so it waits for them, as focus does; then a marker that isn't there, or has
1227
1235
  // stepped aside for picking, is nothing to do. The kept function, so a page that patched
1228
1236
  // focus isn't handed the marker from inside the closed root. The shell's focus listener
1229
- // lights it and brings it into view; nothing is told.
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).
1230
1240
  const focusMark = (id) => {
1231
1241
  if (settling()) {
1232
1242
  pendingMarker = id;