@botiverse/porthole 0.14.12 → 0.14.14
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 +46 -0
- package/dist/annotate/types.d.ts +10 -4
- package/dist/annotate/types.js +4 -1
- package/dist/annotate/validate.js +19 -4
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +2 -1
- package/dist/host/types.d.ts +9 -0
- package/dist/isolation/types.d.ts +6 -0
- package/dist/isolation/types.js +6 -0
- package/dist/platform/web.js +6 -1
- package/dist/react/frame.d.ts +4 -1
- package/dist/shell/annotate.d.ts +12 -1
- package/dist/shell/annotate.js +39 -5
- package/dist/shell/frame.d.ts +6 -1
- package/dist/shell/frame.js +45 -5
- package/docs/ADOPTING.md +53 -4
- package/docs/ARCHITECTURE.md +1 -0
- package/docs/DECISIONS.md +454 -4
- package/docs/DESIGN.md +21 -5
- package/docs/THREAT_MODEL.md +51 -8
- package/package.json +1 -1
- package/src/annotate/types.ts +10 -4
- package/src/annotate/validate.ts +23 -4
- package/src/host/create-host.ts +2 -1
- package/src/host/types.ts +9 -0
- package/src/isolation/types.ts +7 -0
- package/src/platform/web.ts +6 -0
- package/src/react/frame.tsx +4 -1
- package/src/shell/annotate.ts +40 -5
- package/src/shell/frame.ts +45 -5
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.14 (2026-11-07). 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,10 @@ 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. 0.14.14: P136 brings `display.focus()`
|
|
41
|
+
through a nested page's shell with a new host-to-shell word no page can say; P137 applies P135's check to a
|
|
42
|
+
word 100 ms old or more; no wall moves.
|
|
40
43
|
|
|
41
44
|
## 1. Two layers
|
|
42
45
|
|
|
@@ -233,7 +236,10 @@ Whatever the use:
|
|
|
233
236
|
it reads its own page's `document.activeElement` and that is this frame; the focus goes only to a
|
|
234
237
|
container that takes no input (`tabindex="-1"`), never a field or a button; and every control in
|
|
235
238
|
that view that can write has the host's own gate, so that a forged opening and the keys right after
|
|
236
|
-
it can't submit.
|
|
239
|
+
it can't submit. The gate covers keys as well as controls: with the focus in that view the person's
|
|
240
|
+
next keys reach the host's document, so the view's own key handlers and the host's page-wide
|
|
241
|
+
shortcuts that write (an `r` that resolves, Cmd+Enter that posts) need it too (P137). That's the
|
|
242
|
+
host's duty: Porthole doesn't guarantee it.
|
|
237
243
|
- Know that a display can take the keyboard: a page calls `focus()` on its own input whenever it
|
|
238
244
|
likes (on Chromium and WebKit with no gesture), and what the person goes on typing goes to it.
|
|
239
245
|
`createHost` (every `PortholeView` too) gives focus back when it leaves one of the page's text
|
|
@@ -243,6 +249,17 @@ Whatever the use:
|
|
|
243
249
|
your composer with `focusField(field)`, not the field's own `focus()` (Firefox ignores that while
|
|
244
250
|
a fighting frame holds focus); and with a platform of your own, implement its focus guard
|
|
245
251
|
(`focused`, `onFocusTaken`, `focus`) or accept that a display can read what is typed beside it.
|
|
252
|
+
- Call `annotations.focusMark(id)` only as the person's key closes your view of that mark, and know
|
|
253
|
+
it can be dropped (P135, P137): one that has to wait while the frame finds its marks, or that the
|
|
254
|
+
frame takes more than 100 ms after you sent it because its page is busy, lands only if the focus
|
|
255
|
+
is in the frame by then, and in the normal flow it is on your `<body>`. Nothing says so. If
|
|
256
|
+
the focus is still on your body a moment later, the person hasn't moved on: `display.focus()`,
|
|
257
|
+
then `focusMark(id)` again. Look first: that move is yours, the focus guard doesn't judge it, and
|
|
258
|
+
a move after the person went on to a button of yours takes the keyboard from them. On a nested
|
|
259
|
+
page, use `display.focus()`: it tells the page's shell to pass the focus on (P136), and the frame's
|
|
260
|
+
own `focus()` stops at the shell, so a word that waits is dropped even after it. On Firefox,
|
|
261
|
+
`display.focus()` inside a key's own handler moves nothing: call it from a task (measured on a
|
|
262
|
+
nested page). Nothing leaks either way: the keyboard stays out of the page.
|
|
246
263
|
- List every app origin in `appOrigins` (`hostOrigins` in `/server`): only those may frame content,
|
|
247
264
|
and only those are checked against the content domain for a shared site.
|
|
248
265
|
- Under the app runtime, run `defineRuntimeConformance` with `api` in CI (§7).
|
|
@@ -838,7 +855,8 @@ own frame, below the shell, P111), so:
|
|
|
838
855
|
the frame as well (accepted, P132; the host's duty in §6). They say nothing else: the page knows
|
|
839
856
|
where its words are anyway. Where a selection or a mark's words end (`lastLineDocumentRect` in
|
|
840
857
|
`selected`, `anchored` and `tracked`, P133) is one more such box, read, checked and left unclamped
|
|
841
|
-
the same way, with the same duty; `selected` also carries `scroll` now.
|
|
858
|
+
the same way, with the same duty; `selected` also carries `scroll` now. A report with a last line
|
|
859
|
+
and no `scroll` is dropped (P137), as a malformed part drops one.
|
|
842
860
|
- *What holds, against content that patches none of the DOM's or JavaScript's built-ins.* A real
|
|
843
861
|
press or click on a marker reaches none of the content's handlers (the shell's first listener
|
|
844
862
|
stops it; control `marker-click`) and moves neither focus nor a selection (control
|
|
@@ -876,10 +894,10 @@ own frame, below the shell, P111), so:
|
|
|
876
894
|
`activated` while the person really is in the frame, and this signal doesn't stop that.** A host
|
|
877
895
|
that moves the keyboard into its view on the signal takes §6's second exception, with its
|
|
878
896
|
conditions: a page can put the person's next keys in that view, and keeping those keys from posting
|
|
879
|
-
is the host's own gate on that view's controls, not Porthole's.
|
|
897
|
+
is the host's own gate on that view's controls and on its shortcuts, not Porthole's.
|
|
880
898
|
- *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
|
|
899
|
+
(`porthole/annotate.focusMark`, `{ id }`), for one moment only: after the keyboard closed the host's
|
|
900
|
+
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
901
|
shell moves the focus through the platform's `focus` as it was before content ran (control
|
|
884
902
|
`marker-focus`: a page that replaced it is handed the marker otherwise); with no such marker it does
|
|
885
903
|
nothing. The page reads the message, so it learns a card closed, and can take the focus back at once
|
|
@@ -887,6 +905,30 @@ own frame, below the shell, P111), so:
|
|
|
887
905
|
a host can't rely on the focus landing. To the focus guard the move is the frame's own, so from a
|
|
888
906
|
host's text field that still has focus it is undone and counted (P109), not passed as the host's:
|
|
889
907
|
no window was opened in the guard for it.
|
|
908
|
+
A word that has to wait while the frame finds its marks is up to a second old when it could land
|
|
909
|
+
(P135). A word the shell doesn't park can be as old: the frame takes it when its thread is free, a
|
|
910
|
+
busy page changes nothing the shell can see, and a frame out of process doesn't stop the host's
|
|
911
|
+
page meanwhile (P137). A marker's `focus()` takes the keyboard with no gesture on Chromium and
|
|
912
|
+
WebKit, past a guard that defends only text fields: a person gone on to a host's button would be
|
|
913
|
+
pulled back. So the shell drops a parked word unless the focus is in its document as it lands, and
|
|
914
|
+
a word older than 100 ms unless the focus is there as it comes, by `hasFocus` as it was before
|
|
915
|
+
content ran (control `marker-has-focus`: a page that replaced it to say yes gets the landing
|
|
916
|
+
otherwise; `marker-late` takes the first test out, `marker-busy` the second). A word's age is the
|
|
917
|
+
shell's `Date.now` as it was before content ran, less the stamp `createHost` put on it as it was
|
|
918
|
+
sent (`at`): one machine's wall clock (control `marker-clock`: a page that stopped its own clock
|
|
919
|
+
makes a late word look fresh otherwise). A word with no stamp, from an older host, is old. A fresh
|
|
920
|
+
word isn't asked: the frame has no focus then on the very path it is for. That leaves a person who
|
|
921
|
+
moves on within those 100 ms, faster than a person does, and a page that forges the whole word with
|
|
922
|
+
a fresh stamp, or rewrites a real word as it arrives, as it can forge the word at all, which gives it nothing (P134). A page
|
|
923
|
+
can really take the focus and so pass the test, which gives it nothing, since it then has the
|
|
924
|
+
keyboard; and a word that passes it can still move the focus off the page's own field onto a marker,
|
|
925
|
+
inside the frame. §6 has the host's side: a second `focusMark` after its own `display.focus()`.
|
|
926
|
+
The word is a message, so from the host's close until the frame moves, the focus rests on the host's
|
|
927
|
+
body. A forged `activated` in that gap finds no frame focused, so a host that gates a view on "the
|
|
928
|
+
frame had the focus" doesn't gate that one. That is accepted, on the host's side of the wall: such
|
|
929
|
+
a view takes no focus and keeps keys out until the focus has reached the frame (in Raft, content
|
|
930
|
+
inert for 500 ms, and the focus handed back to the frame within 150 ms if the marker didn't take
|
|
931
|
+
it, with `focusMark` again after it, P135), so the keys go to the page and nothing is written.
|
|
890
932
|
- *What doesn't hold against content that does.* The shell shares the content's realm. It reads
|
|
891
933
|
and stops a marker's press through the platform's own functions and getters, kept before
|
|
892
934
|
content runs (P105, control `marker-originals`), so patching `Event`'s or `MouseEvent`'s
|
|
@@ -1017,7 +1059,8 @@ unposted words beside the frame and tell the page when.
|
|
|
1017
1059
|
since; or a Tab, the host's own move, or a press the engine shows on the frame element. Nothing
|
|
1018
1060
|
else counts as a press: no pointer over the frame, no host-wide activation. A move the shell
|
|
1019
1061
|
hasn't spoken of yet waits for its word at most 500 ms (the host asks it to look at once,
|
|
1020
|
-
`porthole/shell/look`), then is taken back.
|
|
1062
|
+
`porthole/shell/look`), then is taken back. The shell passes a focus on to the page by the host's
|
|
1063
|
+
word (`porthole/shell/focus`, P136), which only `display.focus()` sends and no page can say. A key the person types into the page turns its
|
|
1021
1064
|
activation on as a press does, so (P120, after the audit of P111's guard, NG-1): where the
|
|
1022
1065
|
host's page sees the pointer over its frames (Firefox; Chromium and WebKit where the frame is in
|
|
1023
1066
|
their process, once the pointer has been over one), an activation while the pointer isn't over
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.14.
|
|
3
|
+
"version": "0.14.14",
|
|
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
|
@@ -137,7 +137,8 @@ export interface AnchorResult {
|
|
|
137
137
|
* Where its last line is in the document (P133), in the coordinates of `documentRect` and as
|
|
138
138
|
* unclamped: its last line with words on it for text, its whole box for an element, which has no
|
|
139
139
|
* lines of its own. For a host's UI after the last line (its right, or its bottom). Absent from
|
|
140
|
-
* an older shell, and where nothing of the mark is drawn.
|
|
140
|
+
* an older shell, and where nothing of the mark is drawn. Never without its report's `scroll`
|
|
141
|
+
* (a report that tries is dropped, P137). The page's word.
|
|
141
142
|
*/
|
|
142
143
|
readonly lastLineDocumentRect?: AnnotationRect;
|
|
143
144
|
/**
|
|
@@ -154,7 +155,8 @@ export type AnnotationReport =
|
|
|
154
155
|
* The person pointed at an element or settled a text selection. A newer shell (P133) adds where
|
|
155
156
|
* it ends, for a host's UI after its last line: `lastLineDocumentRect` as a result's is, with
|
|
156
157
|
* how far the document was scrolled as it was read (so its place in the frame's viewport is the
|
|
157
|
-
* one less the other, unclamped). Both absent from an older shell
|
|
158
|
+
* one less the other, unclamped). Both absent from an older shell, and never one alone (a report
|
|
159
|
+
* that tries is dropped, P137).
|
|
158
160
|
*/
|
|
159
161
|
| {
|
|
160
162
|
readonly type: "selected";
|
|
@@ -196,7 +198,8 @@ export type AnnotationReport =
|
|
|
196
198
|
* document scrolls, so a host following one mark hears the scroll at every animation frame where
|
|
197
199
|
* it changed, whether that mark is in the frame or not, and places every mark it holds a
|
|
198
200
|
* `documentRect` for (an `anchored` report's) without asking again. A newer one still (P133) adds
|
|
199
|
-
* its `lastLineDocumentRect
|
|
201
|
+
* its `lastLineDocumentRect`, never without `scroll` (a report that tries is dropped, P137), though
|
|
202
|
+
* `scroll` comes without it.
|
|
200
203
|
*/
|
|
201
204
|
| {
|
|
202
205
|
readonly type: "tracked";
|
|
@@ -240,7 +243,10 @@ export const ANNOTATE_METHODS = {
|
|
|
240
243
|
tracked: "porthole/annotate.tracked",
|
|
241
244
|
/** Host → frame: take the page's text selection away, telling nothing back (P115). */
|
|
242
245
|
clearSelection: "porthole/annotate.clearSelection",
|
|
243
|
-
/**
|
|
246
|
+
/**
|
|
247
|
+
* Host → frame: put the focus on one mark's marker (`{ id }`), telling nothing back (P134); one
|
|
248
|
+
* that waited for the marks is dropped unless the focus is in the frame's document by then (P135).
|
|
249
|
+
*/
|
|
244
250
|
focusMark: "porthole/annotate.focusMark",
|
|
245
251
|
} as const;
|
|
246
252
|
|
package/src/annotate/validate.ts
CHANGED
|
@@ -192,6 +192,15 @@ function results(value: unknown): AnchorResult[] | null {
|
|
|
192
192
|
return out;
|
|
193
193
|
}
|
|
194
194
|
|
|
195
|
+
/**
|
|
196
|
+
* A last line with nothing to read it by (P137): its place in the frame's viewport is its own less
|
|
197
|
+
* the scroll it was read at, so a shell sends no last line without one, and a host needn't test for
|
|
198
|
+
* both. The scroll alone is a shell's own: 0.14.10's `tracked` and `anchored` (P132, no last line yet),
|
|
199
|
+
* and a newer one's where nothing of the mark is drawn.
|
|
200
|
+
*/
|
|
201
|
+
const lineWithoutScroll = (line: AnnotationRect | undefined, scroll: unknown): boolean =>
|
|
202
|
+
line !== undefined && scroll === undefined;
|
|
203
|
+
|
|
195
204
|
/** A report from the frame, checked; null if malformed (it is then dropped). */
|
|
196
205
|
export function parseReport(value: unknown): AnnotationReport | null {
|
|
197
206
|
if (!isRecord(value)) {
|
|
@@ -210,6 +219,10 @@ export function parseReport(value: unknown): AnnotationReport | null {
|
|
|
210
219
|
if (anchor === null || rect === null || lastLineDocumentRect === null || scroll === null) {
|
|
211
220
|
return null;
|
|
212
221
|
}
|
|
222
|
+
// A pair, here (P137): a selection has never had one without the other.
|
|
223
|
+
if ((lastLineDocumentRect === undefined) !== (scroll === undefined)) {
|
|
224
|
+
return null;
|
|
225
|
+
}
|
|
213
226
|
return {
|
|
214
227
|
type: "selected",
|
|
215
228
|
anchor,
|
|
@@ -225,9 +238,14 @@ export function parseReport(value: unknown): AnnotationReport | null {
|
|
|
225
238
|
case "anchored": {
|
|
226
239
|
const checked = results(value.results);
|
|
227
240
|
const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
241
|
+
if (
|
|
242
|
+
checked === null ||
|
|
243
|
+
scroll === null ||
|
|
244
|
+
checked.some((each) => lineWithoutScroll(each.lastLineDocumentRect, scroll))
|
|
245
|
+
) {
|
|
246
|
+
return null;
|
|
247
|
+
}
|
|
248
|
+
return { type: "anchored", results: checked, ...(scroll === undefined ? {} : { scroll }) };
|
|
231
249
|
}
|
|
232
250
|
case "activated": {
|
|
233
251
|
const rect = parseRect(value.rect);
|
|
@@ -248,7 +266,8 @@ export function parseReport(value: unknown): AnnotationReport | null {
|
|
|
248
266
|
rect === null ||
|
|
249
267
|
documentRect === null ||
|
|
250
268
|
lastLineDocumentRect === null ||
|
|
251
|
-
scroll === null
|
|
269
|
+
scroll === null ||
|
|
270
|
+
lineWithoutScroll(lastLineDocumentRect, scroll)
|
|
252
271
|
) {
|
|
253
272
|
return null;
|
|
254
273
|
}
|
package/src/host/create-host.ts
CHANGED
|
@@ -667,9 +667,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
667
667
|
focusMark(id) {
|
|
668
668
|
// Host → frame only, and kept for no later frame (P134). A mark that has gone, or has no
|
|
669
669
|
// marker, is nothing to ask for, and no fault: the host's card closed with the mark's.
|
|
670
|
+
// Stamped as it is sent: a frame judges by that how old the word is as it takes it (P137).
|
|
670
671
|
needsAnnotate("focusMark");
|
|
671
672
|
if (marks.some((mark) => mark.id === id && hasMarker(mark))) {
|
|
672
|
-
toFrame(ANNOTATE_METHODS.focusMark, { id });
|
|
673
|
+
toFrame(ANNOTATE_METHODS.focusMark, { id, at: Date.now() });
|
|
673
674
|
}
|
|
674
675
|
},
|
|
675
676
|
};
|
package/src/host/types.ts
CHANGED
|
@@ -329,6 +329,15 @@ 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). One the frame takes more than 100 ms after you sent
|
|
336
|
+
* it (its page is busy) is held to the same test (P137), so a word that comes late takes no
|
|
337
|
+
* keyboard from a person who moved on. Nothing says it was dropped: if the frame isn't your page's
|
|
338
|
+
* `document.activeElement` soon after and the person hasn't moved on, call `focus()` and then
|
|
339
|
+
* `focusMark(id)` again. On a nested page only `focus()` reaches the page (P136): the frame's own
|
|
340
|
+
* `focus()` stops at its shell, and a second call that waits is dropped.
|
|
332
341
|
*/
|
|
333
342
|
focusMark(id: string): void;
|
|
334
343
|
}
|
package/src/isolation/types.ts
CHANGED
|
@@ -100,6 +100,13 @@ export const SHELL_BEAT_METHOD = "porthole/shell/beat";
|
|
|
100
100
|
*/
|
|
101
101
|
export const SHELL_LOOK_METHOD = "porthole/shell/look";
|
|
102
102
|
|
|
103
|
+
/**
|
|
104
|
+
* The host's word to a nested page's shell (P136) that it moved the focus into the frame: pass it on
|
|
105
|
+
* to the page, in this task, not in the focus event (where the shell's move doesn't take). Sent by
|
|
106
|
+
* `display.focus()` alone; a page has no way to say it.
|
|
107
|
+
*/
|
|
108
|
+
export const SHELL_FOCUS_METHOD = "porthole/shell/focus";
|
|
109
|
+
|
|
103
110
|
/** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
|
|
104
111
|
export const SHELL_METHOD_PREFIX = "porthole/shell/";
|
|
105
112
|
|
package/src/platform/web.ts
CHANGED
|
@@ -2,6 +2,7 @@ import { DOOR_SANDBOX_TOKENS } from "../compile/policy.ts";
|
|
|
2
2
|
import type { ColorScheme } from "../config/schema.ts";
|
|
3
3
|
import {
|
|
4
4
|
SHELL_BEAT_METHOD,
|
|
5
|
+
SHELL_FOCUS_METHOD,
|
|
5
6
|
SHELL_LOOK_METHOD,
|
|
6
7
|
SHELL_METHOD_PREFIX,
|
|
7
8
|
SHELL_STATE_METHOD,
|
|
@@ -194,6 +195,11 @@ export const webPlatform: PlatformHost = {
|
|
|
194
195
|
},
|
|
195
196
|
focus() {
|
|
196
197
|
guard.focus(frame);
|
|
198
|
+
// A nested page (P136): the move stops at its shell on every engine, one way or another,
|
|
199
|
+
// and only the shell can pass it on. Only a move that landed: the shell asks no more of it.
|
|
200
|
+
if (nested && view.document.activeElement === frame) {
|
|
201
|
+
opened.send({ jsonrpc: "2.0", method: SHELL_FOCUS_METHOD });
|
|
202
|
+
}
|
|
197
203
|
},
|
|
198
204
|
onLoad(listener) {
|
|
199
205
|
loaded.add(listener);
|
package/src/react/frame.tsx
CHANGED
|
@@ -500,7 +500,10 @@ 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), and so is one a busy page takes late (P137): call it again after your own move of
|
|
506
|
+
* the focus into the frame.
|
|
504
507
|
*/
|
|
505
508
|
focusMark(id: string): void;
|
|
506
509
|
/**
|
package/src/shell/annotate.ts
CHANGED
|
@@ -57,6 +57,23 @@ export const MARKER_NAME = String.raw`(mark) => {
|
|
|
57
57
|
return words === "" ? what : what + ' on "' + words + '"';
|
|
58
58
|
}`;
|
|
59
59
|
|
|
60
|
+
/**
|
|
61
|
+
* Whether a host's `focusMark` is too old to land unasked (P137): `at` is the host's `Date.now()` as
|
|
62
|
+
* it sent the word, `now` the shell's, kept before content runs. Both read the one wall clock of
|
|
63
|
+
* this machine, the only clock two realms share (`performance.now()` counts from each one's own
|
|
64
|
+
* start). No number is an older host's word, which can't be known fresh. A word from ahead of the
|
|
65
|
+
* clock has the same bound behind it: two processes can read the clock a little apart, and past
|
|
66
|
+
* that the clock was set back, and the age says nothing. Comparisons only, nothing a page can
|
|
67
|
+
* patch, and a word that makes no number (`NaN`, `Infinity`) passes neither test.
|
|
68
|
+
*/
|
|
69
|
+
export const WORD_LATE = String.raw`(at, now) => {
|
|
70
|
+
if (typeof at !== "number") {
|
|
71
|
+
return true;
|
|
72
|
+
}
|
|
73
|
+
const age = now - at;
|
|
74
|
+
return !(age > -100 && age < 100);
|
|
75
|
+
}`;
|
|
76
|
+
|
|
60
77
|
/**
|
|
61
78
|
* The shell's annotation runtime (P053), spliced into the shell's runtime (`__ANNOTATE__`) when
|
|
62
79
|
* the config declares `annotate`, so it runs before any content does, with the DOM's own
|
|
@@ -80,7 +97,8 @@ export const MARKER_NAME = String.raw`(mark) => {
|
|
|
80
97
|
* focus on it (P133), is reported (`activated`), and the content's own handlers never see it; a
|
|
81
98
|
* draft is drawn apart, a dashed line and a hollow bubble with no number, and has a marker with
|
|
82
99
|
* or without a count; the host's `focusMark` (P134) puts the focus on a marker that is there, and
|
|
83
|
-
* tells nothing back;
|
|
100
|
+
* tells nothing back; one that had to wait for the marks (P135), or that this document took late
|
|
101
|
+
* (P137), lands only if the focus is in this document by then;
|
|
84
102
|
* - following: while a mark has a marker, once a scroll, a resize or a change of the content
|
|
85
103
|
* settles, the marks that moved since the host was last told are reported, at most once a
|
|
86
104
|
* second, so the host's own UI beside a mark can follow;
|
|
@@ -123,6 +141,8 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
123
141
|
const selectionOf = Document.prototype.getSelection;
|
|
124
142
|
const removeAllRanges = Selection.prototype.removeAllRanges;
|
|
125
143
|
const focusElement = HTMLElement.prototype.focus;
|
|
144
|
+
const hasFocus = Document.prototype.hasFocus;
|
|
145
|
+
const wallClock = Date.now;
|
|
126
146
|
const elementRect = Element.prototype.getBoundingClientRect;
|
|
127
147
|
const rangeRect = Range.prototype.getBoundingClientRect;
|
|
128
148
|
const rangeRects = Range.prototype.getClientRects;
|
|
@@ -1075,6 +1095,10 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1075
1095
|
let waitingForContent = false;
|
|
1076
1096
|
let pendingFocus = null;
|
|
1077
1097
|
let pendingMarker = null;
|
|
1098
|
+
// Asked through the kept function: a page that says it has the focus gets no landing the
|
|
1099
|
+
// platform would refuse (P135).
|
|
1100
|
+
const focusIsHere = () => callOf(hasFocus, document, []) === true;
|
|
1101
|
+
const wordLate = ${WORD_LATE};
|
|
1078
1102
|
const settling = () => anchorTimer !== 0 || waitingForContent || marks.some((mark) => mark.state === null);
|
|
1079
1103
|
const scheduleAnchor = (all) => {
|
|
1080
1104
|
if (all) {
|
|
@@ -1116,7 +1140,12 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1116
1140
|
if (pendingMarker !== null) {
|
|
1117
1141
|
const id = pendingMarker;
|
|
1118
1142
|
pendingMarker = null;
|
|
1119
|
-
|
|
1143
|
+
// Parked, the host's word is old: the person may have moved on, and a marker's focus
|
|
1144
|
+
// takes the keyboard with no gesture. So it lands only if the focus is still in this
|
|
1145
|
+
// document. Otherwise it is dropped (P135).
|
|
1146
|
+
if (focusIsHere()) {
|
|
1147
|
+
focusMark(id, false);
|
|
1148
|
+
}
|
|
1120
1149
|
}
|
|
1121
1150
|
}, wait);
|
|
1122
1151
|
};
|
|
@@ -1226,8 +1255,11 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1226
1255
|
// markers yet, so it waits for them, as focus does; then a marker that isn't there, or has
|
|
1227
1256
|
// stepped aside for picking, is nothing to do. The kept function, so a page that patched
|
|
1228
1257
|
// 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.
|
|
1230
|
-
|
|
1258
|
+
// lights it and brings it into view; nothing is told. A fresh word reads no focus: after the
|
|
1259
|
+
// host's card closed the focus is on the host's body, so this document has none yet. One
|
|
1260
|
+
// parked is asked as it lands (P135), and one this document took late (P137: late, by when
|
|
1261
|
+
// the host sent it: a busy page doesn't park it) is asked here: its moment has passed.
|
|
1262
|
+
const focusMark = (id, late) => {
|
|
1231
1263
|
if (settling()) {
|
|
1232
1264
|
pendingMarker = id;
|
|
1233
1265
|
return;
|
|
@@ -1235,6 +1267,9 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1235
1267
|
if (mode.elements || !isShown(id)) {
|
|
1236
1268
|
return;
|
|
1237
1269
|
}
|
|
1270
|
+
if (late && !focusIsHere()) {
|
|
1271
|
+
return;
|
|
1272
|
+
}
|
|
1238
1273
|
for (let i = 0; i < markers.length; i += 1) {
|
|
1239
1274
|
if (markers[i].id === id) {
|
|
1240
1275
|
callOf(focusElement, markers[i].element, [{ preventScroll: true }]);
|
|
@@ -1678,7 +1713,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1678
1713
|
break;
|
|
1679
1714
|
}
|
|
1680
1715
|
case M.focusMark:
|
|
1681
|
-
focusMark(String(params.id));
|
|
1716
|
+
focusMark(String(params.id), wordLate(params.at, callOf(wallClock, undefined, [])));
|
|
1682
1717
|
break;
|
|
1683
1718
|
case M.clear:
|
|
1684
1719
|
track(null);
|
package/src/shell/frame.ts
CHANGED
|
@@ -26,7 +26,12 @@ import { hostOriginProblem, onNestedLabel } from "../isolation/served.ts";
|
|
|
26
26
|
* - renews the page's sealed files' address before it ends, and gives the page the new one
|
|
27
27
|
* (`porthole/files-renewed`): the page's own loads aren't its origin's (an opaque origin's never
|
|
28
28
|
* are), so only the shell, on that origin, may renew it (P083);
|
|
29
|
-
* - passes its focus to the page
|
|
29
|
+
* - passes its focus to the page: at the focus event where that takes (Firefox, from the host's
|
|
30
|
+
* `<body>`), and on the host's word that it moved it there (`porthole/shell/focus`, P136), where
|
|
31
|
+
* it doesn't: a frame's move inside the focus event that made it the focused frame sets the
|
|
32
|
+
* shell's `activeElement` and goes no further (Chromium, WebKit), and from a focused element of
|
|
33
|
+
* the host's the window hears no focus event at all (Firefox). A later task's `frame.focus()`
|
|
34
|
+
* goes through on all of them, the frame blurred first as the failed one left it active.
|
|
30
35
|
*
|
|
31
36
|
* Plain ES2020, no imports and no build step, like the runtime. `__PLAN__` is its plan.
|
|
32
37
|
*/
|
|
@@ -152,12 +157,39 @@ export const FRAME_SHELL_RUNTIME = String.raw`(() => {
|
|
|
152
157
|
};
|
|
153
158
|
requestAnimationFrame(tick);
|
|
154
159
|
setInterval(look, 50);
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
160
|
+
|
|
161
|
+
// Whether the focus is on the shell's own document, not through it on the page's (P136). Firefox
|
|
162
|
+
// tells a move from a focused element of the host's on the document alone. The host's word needs
|
|
163
|
+
// this: it never moves a focus that isn't here, and a page that has it hears no blur.
|
|
164
|
+
let holds = false;
|
|
165
|
+
// Until when a word that came ahead of the focus it speaks of holds (it crosses processes too).
|
|
166
|
+
let wordUntil = 0;
|
|
167
|
+
const handOn = () => {
|
|
168
|
+
if (holds && document.hasFocus()) {
|
|
169
|
+
frame.blur();
|
|
159
170
|
frame.focus();
|
|
160
171
|
}
|
|
172
|
+
};
|
|
173
|
+
const came = () => {
|
|
174
|
+
holds = true;
|
|
175
|
+
if (performance.now() < wordUntil) {
|
|
176
|
+
wordUntil = 0;
|
|
177
|
+
setTimeout(handOn, 0);
|
|
178
|
+
}
|
|
179
|
+
};
|
|
180
|
+
document.addEventListener("focus", came);
|
|
181
|
+
addEventListener("blur", () => {
|
|
182
|
+
holds = false;
|
|
183
|
+
look();
|
|
184
|
+
});
|
|
185
|
+
addEventListener("focus", (event) => {
|
|
186
|
+
if (event.target === window) {
|
|
187
|
+
came();
|
|
188
|
+
// Where a move can go on from inside this event (P136): Firefox, from the host's <body>.
|
|
189
|
+
if (document.activeElement !== frame) {
|
|
190
|
+
frame.focus();
|
|
191
|
+
}
|
|
192
|
+
}
|
|
161
193
|
look();
|
|
162
194
|
});
|
|
163
195
|
document.addEventListener("visibilitychange", look);
|
|
@@ -184,6 +216,14 @@ export const FRAME_SHELL_RUNTIME = String.raw`(() => {
|
|
|
184
216
|
if (data.method === PREFIX + "look" && typeof n === "number" && n >= 0 && Math.floor(n) === n) {
|
|
185
217
|
look(n);
|
|
186
218
|
}
|
|
219
|
+
// The host's own move into the frame, done (P136): on to the page.
|
|
220
|
+
if (data.method === PREFIX + "focus") {
|
|
221
|
+
if (holds) {
|
|
222
|
+
handOn();
|
|
223
|
+
} else {
|
|
224
|
+
wordUntil = performance.now() + 250;
|
|
225
|
+
}
|
|
226
|
+
}
|
|
187
227
|
return;
|
|
188
228
|
}
|
|
189
229
|
const child = frame.contentWindow;
|