@botiverse/porthole 0.14.13 → 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 +36 -2
- package/dist/annotate/types.d.ts +6 -3
- 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 +5 -4
- 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 +2 -1
- package/dist/shell/annotate.d.ts +12 -2
- package/dist/shell/annotate.js +35 -11
- package/dist/shell/frame.d.ts +6 -1
- package/dist/shell/frame.js +45 -5
- package/docs/ADOPTING.md +28 -14
- package/docs/ARCHITECTURE.md +1 -0
- package/docs/DECISIONS.md +335 -16
- package/docs/DESIGN.md +18 -8
- package/docs/THREAT_MODEL.md +37 -20
- package/package.json +1 -1
- package/src/annotate/types.ts +6 -3
- package/src/annotate/validate.ts +23 -4
- package/src/host/create-host.ts +2 -1
- package/src/host/types.ts +5 -4
- package/src/isolation/types.ts +7 -0
- package/src/platform/web.ts +6 -0
- package/src/react/frame.tsx +2 -1
- package/src/shell/annotate.ts +36 -11
- 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
|
|
@@ -37,8 +37,9 @@ reports `activated`, which the page could already fake; `lastLineDocumentRect` i
|
|
|
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
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.
|
|
41
|
-
|
|
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.
|
|
42
43
|
|
|
43
44
|
## 1. Two layers
|
|
44
45
|
|
|
@@ -235,7 +236,10 @@ Whatever the use:
|
|
|
235
236
|
it reads its own page's `document.activeElement` and that is this frame; the focus goes only to a
|
|
236
237
|
container that takes no input (`tabindex="-1"`), never a field or a button; and every control in
|
|
237
238
|
that view that can write has the host's own gate, so that a forged opening and the keys right after
|
|
238
|
-
it can't submit.
|
|
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.
|
|
239
243
|
- Know that a display can take the keyboard: a page calls `focus()` on its own input whenever it
|
|
240
244
|
likes (on Chromium and WebKit with no gesture), and what the person goes on typing goes to it.
|
|
241
245
|
`createHost` (every `PortholeView` too) gives focus back when it leaves one of the page's text
|
|
@@ -246,13 +250,16 @@ Whatever the use:
|
|
|
246
250
|
a fighting frame holds focus); and with a platform of your own, implement its focus guard
|
|
247
251
|
(`focused`, `onFocusTaken`, `focus`) or accept that a display can read what is typed beside it.
|
|
248
252
|
- 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
|
|
250
|
-
|
|
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
|
|
251
256
|
the focus is still on your body a moment later, the person hasn't moved on: `display.focus()`,
|
|
252
257
|
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.
|
|
254
|
-
(
|
|
255
|
-
|
|
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.
|
|
256
263
|
- List every app origin in `appOrigins` (`hostOrigins` in `/server`): only those may frame content,
|
|
257
264
|
and only those are checked against the content domain for a shared site.
|
|
258
265
|
- Under the app runtime, run `defineRuntimeConformance` with `api` in CI (§7).
|
|
@@ -848,7 +855,8 @@ own frame, below the shell, P111), so:
|
|
|
848
855
|
the frame as well (accepted, P132; the host's duty in §6). They say nothing else: the page knows
|
|
849
856
|
where its words are anyway. Where a selection or a mark's words end (`lastLineDocumentRect` in
|
|
850
857
|
`selected`, `anchored` and `tracked`, P133) is one more such box, read, checked and left unclamped
|
|
851
|
-
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.
|
|
852
860
|
- *What holds, against content that patches none of the DOM's or JavaScript's built-ins.* A real
|
|
853
861
|
press or click on a marker reaches none of the content's handlers (the shell's first listener
|
|
854
862
|
stops it; control `marker-click`) and moves neither focus nor a selection (control
|
|
@@ -886,7 +894,7 @@ own frame, below the shell, P111), so:
|
|
|
886
894
|
`activated` while the person really is in the frame, and this signal doesn't stop that.** A host
|
|
887
895
|
that moves the keyboard into its view on the signal takes §6's second exception, with its
|
|
888
896
|
conditions: a page can put the person's next keys in that view, and keeping those keys from posting
|
|
889
|
-
is the host's own gate on that view's controls, not Porthole's.
|
|
897
|
+
is the host's own gate on that view's controls and on its shortcuts, not Porthole's.
|
|
890
898
|
- *Back to a marker* (P134). `annotations.focusMark(id)` is the host's word to the frame
|
|
891
899
|
(`porthole/annotate.focusMark`, `{ id }`), for one moment only: after the keyboard closed the host's
|
|
892
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
|
|
@@ -898,15 +906,23 @@ own frame, below the shell, P111), so:
|
|
|
898
906
|
host's text field that still has focus it is undone and counted (P109), not passed as the host's:
|
|
899
907
|
no window was opened in the guard for it.
|
|
900
908
|
A word that has to wait while the frame finds its marks is up to a second old when it could land
|
|
901
|
-
(P135)
|
|
902
|
-
|
|
903
|
-
|
|
904
|
-
|
|
905
|
-
|
|
906
|
-
|
|
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
|
|
907
923
|
can really take the focus and so pass the test, which gives it nothing, since it then has the
|
|
908
|
-
keyboard; and a
|
|
909
|
-
the frame. §6 has the host's side: a second `focusMark` after its own `display.focus()`.
|
|
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()`.
|
|
910
926
|
The word is a message, so from the host's close until the frame moves, the focus rests on the host's
|
|
911
927
|
body. A forged `activated` in that gap finds no frame focused, so a host that gates a view on "the
|
|
912
928
|
frame had the focus" doesn't gate that one. That is accepted, on the host's side of the wall: such
|
|
@@ -1043,7 +1059,8 @@ unposted words beside the frame and tell the page when.
|
|
|
1043
1059
|
since; or a Tab, the host's own move, or a press the engine shows on the frame element. Nothing
|
|
1044
1060
|
else counts as a press: no pointer over the frame, no host-wide activation. A move the shell
|
|
1045
1061
|
hasn't spoken of yet waits for its word at most 500 ms (the host asks it to look at once,
|
|
1046
|
-
`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
|
|
1047
1064
|
activation on as a press does, so (P120, after the audit of P111's guard, NG-1): where the
|
|
1048
1065
|
host's page sees the pointer over its frames (Firefox; Chromium and WebKit where the frame is in
|
|
1049
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";
|
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
|
@@ -332,11 +332,12 @@ export interface AnnotationControls {
|
|
|
332
332
|
*
|
|
333
333
|
* On a calm page it lands at once, from anywhere on the host's page. While the frame is finding
|
|
334
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)
|
|
336
|
-
*
|
|
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
|
|
337
338
|
* `document.activeElement` soon after and the person hasn't moved on, call `focus()` and then
|
|
338
|
-
* `focusMark(id)` again.
|
|
339
|
-
*
|
|
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.
|
|
340
341
|
*/
|
|
341
342
|
focusMark(id: string): void;
|
|
342
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
|
@@ -502,7 +502,8 @@ export interface PortholeFrameHandle {
|
|
|
502
502
|
* once Escape closed your own view of that mark. Nothing happens for an id with no marker, or
|
|
503
503
|
* while no display runs. A config without `annotate`: `onHostError`, kind `"annotations"`. While
|
|
504
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
|
|
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.
|
|
506
507
|
*/
|
|
507
508
|
focusMark(id: string): void;
|
|
508
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,8 +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; one that had to wait for the marks
|
|
84
|
-
* document
|
|
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;
|
|
85
102
|
* - following: while a mark has a marker, once a scroll, a resize or a change of the content
|
|
86
103
|
* settles, the marks that moved since the host was last told are reported, at most once a
|
|
87
104
|
* second, so the host's own UI beside a mark can follow;
|
|
@@ -125,6 +142,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
125
142
|
const removeAllRanges = Selection.prototype.removeAllRanges;
|
|
126
143
|
const focusElement = HTMLElement.prototype.focus;
|
|
127
144
|
const hasFocus = Document.prototype.hasFocus;
|
|
145
|
+
const wallClock = Date.now;
|
|
128
146
|
const elementRect = Element.prototype.getBoundingClientRect;
|
|
129
147
|
const rangeRect = Range.prototype.getBoundingClientRect;
|
|
130
148
|
const rangeRects = Range.prototype.getClientRects;
|
|
@@ -1077,6 +1095,10 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1077
1095
|
let waitingForContent = false;
|
|
1078
1096
|
let pendingFocus = null;
|
|
1079
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};
|
|
1080
1102
|
const settling = () => anchorTimer !== 0 || waitingForContent || marks.some((mark) => mark.state === null);
|
|
1081
1103
|
const scheduleAnchor = (all) => {
|
|
1082
1104
|
if (all) {
|
|
@@ -1120,10 +1142,9 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1120
1142
|
pendingMarker = null;
|
|
1121
1143
|
// Parked, the host's word is old: the person may have moved on, and a marker's focus
|
|
1122
1144
|
// takes the keyboard with no gesture. So it lands only if the focus is still in this
|
|
1123
|
-
// document
|
|
1124
|
-
|
|
1125
|
-
|
|
1126
|
-
focusMark(id);
|
|
1145
|
+
// document. Otherwise it is dropped (P135).
|
|
1146
|
+
if (focusIsHere()) {
|
|
1147
|
+
focusMark(id, false);
|
|
1127
1148
|
}
|
|
1128
1149
|
}
|
|
1129
1150
|
}, wait);
|
|
@@ -1234,10 +1255,11 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1234
1255
|
// markers yet, so it waits for them, as focus does; then a marker that isn't there, or has
|
|
1235
1256
|
// stepped aside for picking, is nothing to do. The kept function, so a page that patched
|
|
1236
1257
|
// focus isn't handed the marker from inside the closed root. The shell's focus listener
|
|
1237
|
-
// lights it and brings it into view; nothing is told. A
|
|
1238
|
-
// focus
|
|
1239
|
-
//
|
|
1240
|
-
|
|
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) => {
|
|
1241
1263
|
if (settling()) {
|
|
1242
1264
|
pendingMarker = id;
|
|
1243
1265
|
return;
|
|
@@ -1245,6 +1267,9 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1245
1267
|
if (mode.elements || !isShown(id)) {
|
|
1246
1268
|
return;
|
|
1247
1269
|
}
|
|
1270
|
+
if (late && !focusIsHere()) {
|
|
1271
|
+
return;
|
|
1272
|
+
}
|
|
1248
1273
|
for (let i = 0; i < markers.length; i += 1) {
|
|
1249
1274
|
if (markers[i].id === id) {
|
|
1250
1275
|
callOf(focusElement, markers[i].element, [{ preventScroll: true }]);
|
|
@@ -1688,7 +1713,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1688
1713
|
break;
|
|
1689
1714
|
}
|
|
1690
1715
|
case M.focusMark:
|
|
1691
|
-
focusMark(String(params.id));
|
|
1716
|
+
focusMark(String(params.id), wordLate(params.at, callOf(wallClock, undefined, [])));
|
|
1692
1717
|
break;
|
|
1693
1718
|
case M.clear:
|
|
1694
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;
|