@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.
- package/CHANGELOG.md +12 -0
- package/dist/annotate/types.d.ts +4 -1
- package/dist/annotate/types.js +4 -1
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/types.d.ts +8 -0
- package/dist/react/frame.d.ts +3 -1
- package/dist/shell/annotate.d.ts +2 -1
- package/dist/shell/annotate.js +13 -3
- package/docs/ADOPTING.md +36 -1
- package/docs/DECISIONS.md +133 -2
- package/docs/DESIGN.md +8 -2
- package/docs/THREAT_MODEL.md +30 -4
- package/package.json +1 -1
- package/src/annotate/types.ts +4 -1
- package/src/host/types.ts +8 -0
- package/src/react/frame.tsx +3 -1
- package/src/shell/annotate.ts +13 -3
package/dist/host/types.d.ts
CHANGED
|
@@ -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
|
}
|
package/dist/react/frame.d.ts
CHANGED
|
@@ -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
|
/**
|
package/dist/shell/annotate.d.ts
CHANGED
|
@@ -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;
|
package/dist/shell/annotate.js
CHANGED
|
@@ -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
|
-
|
|
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
|
|
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
|
|
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
|
|
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`),
|
|
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` | — | — |
|
package/docs/THREAT_MODEL.md
CHANGED
|
@@ -5,7 +5,7 @@ What Porthole protects, from whom, and where that protection ends. For each way
|
|
|
5
5
|
guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
|
|
6
6
|
[DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
|
|
7
7
|
|
|
8
|
-
**Status.** This describes Porthole 0.14.
|
|
8
|
+
**Status.** This describes Porthole 0.14.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
|
|
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.
|
|
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": {
|
package/src/annotate/types.ts
CHANGED
|
@@ -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
|
-
/**
|
|
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
|
}
|
package/src/react/frame.tsx
CHANGED
|
@@ -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
|
/**
|
package/src/shell/annotate.ts
CHANGED
|
@@ -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
|
-
|
|
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;
|