@botiverse/porthole 0.15.1 → 0.15.3

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.
@@ -22,6 +22,11 @@ export declare const isNestedLabel: (label: string) => boolean;
22
22
  export declare function onNestedLabel(origin: string): boolean;
23
23
  /** Whether `origin` is an exact origin (`https://host[:port]`, lowercase, no path). */
24
24
  export declare function isExactOrigin(origin: unknown): origin is string;
25
+ /**
26
+ * Whether `origin` can be a host origin: written as one, and one a browser serializes as it is
27
+ * written (`serializable`: never `:0`, a port past 65535 or with a leading zero, a host the URL
28
+ * parser would rewrite). `hostOriginProblem` says why not.
29
+ */
25
30
  export declare function isHostOrigin(origin: unknown): origin is string;
26
31
  /** Why `origin` can't be a host origin, in words a host's developer can act on; null if it can. */
27
32
  export declare function hostOriginProblem(origin: unknown): string | null;
@@ -45,8 +45,15 @@ export function isExactOrigin(origin) {
45
45
  * page says "null") and never a path. The shell takes messages only from these, exactly.
46
46
  */
47
47
  const HOST_ORIGIN = /^[a-z][a-z0-9+.-]*:\/\/([a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*|\[[0-9a-f:.]+\])(:\d{1,5})?$/u;
48
+ /** Whether `origin` is written as an origin is (`HOST_ORIGIN`), whatever a browser makes of it. */
49
+ const shapedAsOrigin = (origin) => typeof origin === "string" && origin.length <= 300 && HOST_ORIGIN.test(origin);
50
+ /**
51
+ * Whether `origin` can be a host origin: written as one, and one a browser serializes as it is
52
+ * written (`serializable`: never `:0`, a port past 65535 or with a leading zero, a host the URL
53
+ * parser would rewrite). `hostOriginProblem` says why not.
54
+ */
48
55
  export function isHostOrigin(origin) {
49
- return typeof origin === "string" && origin.length <= 300 && HOST_ORIGIN.test(origin);
56
+ return shapedAsOrigin(origin) && serializable(origin);
50
57
  }
51
58
  /**
52
59
  * Whether an origin that matched `HOST_ORIGIN` is one a browser can serialize as it is written
@@ -75,7 +82,7 @@ function serializable(origin) {
75
82
  }
76
83
  /** Why `origin` can't be a host origin, in words a host's developer can act on; null if it can. */
77
84
  export function hostOriginProblem(origin) {
78
- if (isHostOrigin(origin)) {
85
+ if (shapedAsOrigin(origin)) {
79
86
  return serializable(origin)
80
87
  ? null
81
88
  : `${JSON.stringify(origin)} is not an origin a browser serializes so (a port is 1 to 65535, no leading zero; a host as the URL parser gives it)`;
@@ -118,7 +125,7 @@ const LOOPBACK_HOST = (host) => host === "localhost" || host.endsWith(".localhos
118
125
  * in plain decimal, and its host is as the URL parser gives it back (P145). Null if it can be.
119
126
  */
120
127
  export function framedByProblem(origin) {
121
- const parsed = typeof origin === "string" && isHostOrigin(origin) ? parseOrigin(origin) : null;
128
+ const parsed = shapedAsOrigin(origin) ? parseOrigin(origin) : null;
122
129
  if (parsed === null ||
123
130
  !(parsed.scheme === "https" || (parsed.scheme === "http" && LOOPBACK_HOST(parsed.host)))) {
124
131
  return `${JSON.stringify(origin)} is not an exact https origin (https://host[:port], lowercase, no path; http only on loopback)`;
@@ -109,6 +109,12 @@ export declare const SHELL_LOOK_METHOD = "porthole/shell/look";
109
109
  * `display.focus()` alone; a page has no way to say it.
110
110
  */
111
111
  export declare const SHELL_FOCUS_METHOD = "porthole/shell/focus";
112
+ /**
113
+ * A nested page's shell's word to its page's runtime (P148): one `MessagePort`, sent at each load
114
+ * of the page's frame, over which the runtime tells the shell each real press in the page. The
115
+ * runtime takes the first one alone, before any content runs, and no content ever holds it.
116
+ */
117
+ export declare const SHELL_PRESS_PORT_METHOD = "porthole/shell/press-port";
112
118
  /** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
113
119
  export declare const SHELL_METHOD_PREFIX = "porthole/shell/";
114
120
  /** A page's word that it used storage, once per load (P111): never a key or a value. */
@@ -17,6 +17,12 @@ export const SHELL_LOOK_METHOD = "porthole/shell/look";
17
17
  * `display.focus()` alone; a page has no way to say it.
18
18
  */
19
19
  export const SHELL_FOCUS_METHOD = "porthole/shell/focus";
20
+ /**
21
+ * A nested page's shell's word to its page's runtime (P148): one `MessagePort`, sent at each load
22
+ * of the page's frame, over which the runtime tells the shell each real press in the page. The
23
+ * runtime takes the first one alone, before any content runs, and no content ever holds it.
24
+ */
25
+ export const SHELL_PRESS_PORT_METHOD = "porthole/shell/press-port";
20
26
  /** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
21
27
  export const SHELL_METHOD_PREFIX = "porthole/shell/";
22
28
  /** A page's word that it used storage, once per load (P111): never a key or a value. */
@@ -106,6 +106,14 @@ export declare const SHELL_EARLY_MS = 150;
106
106
  * uncertain: it is no one's gesture until it lapses.
107
107
  */
108
108
  export declare const SHELL_STALL_MS = 100;
109
+ /**
110
+ * A press a nested page's runtime told its shell (P148) within this long after the shell was seen
111
+ * to have stalled is no one's. The shell notes a press when it hears it, and a page that holds the
112
+ * thread it shares with its shell makes that late, by as long as it likes: when the page lets go,
113
+ * what waited behind it runs at once, the shell's own look among it, which may come first and say
114
+ * the stall, the press following a moment later as if it were new.
115
+ */
116
+ export declare const SHELL_AFTER_STALL_MS = 500;
109
117
  /** What a nested page's shell last said (P111), on the host's clock. */
110
118
  export interface ShellWord {
111
119
  /** Whether its engine tells activation at all (`navigator.userActivation`). */
@@ -123,6 +131,15 @@ export interface ShellWord {
123
131
  * host's page sees the pointer, their key landing in the page, no press (P120).
124
132
  */
125
133
  readonly keyed?: boolean;
134
+ /**
135
+ * When it last heard a real press from its page's runtime (P148); -Infinity, or absent, if it
136
+ * heard none, or the one it heard is uncertain (judged as an activation that turned on is).
137
+ */
138
+ readonly pressedAt?: number;
139
+ /** How many presses it said it had heard, the last time it spoke: more is a new one. */
140
+ readonly presses?: number;
141
+ /** `keyed`, for the press at `pressedAt`: judged as the shell told it. */
142
+ readonly pressKeyed?: boolean;
126
143
  }
127
144
  /** One move of the keyboard the guard undid. */
128
145
  export interface FocusTake {
@@ -194,6 +211,19 @@ export declare function personMoved(move: FocusMove): boolean;
194
211
  * within `SHELL_GESTURE_MS`, after the host's page's last trusted press or key.
195
212
  */
196
213
  export declare function shellGesture(word: ShellWord, hostInputAt: number, now: number): boolean;
214
+ /**
215
+ * Whether a nested page's runtime told its shell a real press just now (P148): the shell heard it
216
+ * within `SHELL_GESTURE_MS`, after the host's page's last trusted press or key. What the shell's
217
+ * activation can't say: a press while it is already on (within 5 s of the last gesture).
218
+ */
219
+ export declare function shellPress(word: ShellWord, hostInputAt: number, now: number): boolean;
220
+ /**
221
+ * Whether a nested page's shell saw the person's gesture just now, either way: its activation
222
+ * turned on (`shellGesture`, P111), or its page's runtime told it a press (`shellPress`, P148);
223
+ * each only where a press could have made it (P120: `shown`, the host's page sees the pointer over
224
+ * its frames, and the word is `keyed`, the person's key landing in the page).
225
+ */
226
+ export declare function shellSaw(word: ShellWord, hostInputAt: number, now: number, shown: boolean): boolean;
197
227
  /**
198
228
  * Whether the person could have pressed the frame just before `at` (P120): a nested page's shell
199
229
  * says its activation turned on, which a key typed into the page does as well as a press. Where the
@@ -225,6 +255,12 @@ export interface FocusGuard {
225
255
  readonly gap: number;
226
256
  /** The ask this report answers (P120), if it answers one. */
227
257
  readonly asked?: number;
258
+ /**
259
+ * Its page's runtime's real presses (P148): how long ago the shell heard the last (null:
260
+ * none since the frame's last load), and how many it has heard. Absent from an older shell.
261
+ */
262
+ readonly pressed?: number | null;
263
+ readonly presses?: number;
228
264
  }): void;
229
265
  /** A nested page's shell's heartbeat (P111): it is looking. */
230
266
  beat(frame: HTMLIFrameElement): void;
@@ -100,6 +100,14 @@ export const SHELL_EARLY_MS = 150;
100
100
  * uncertain: it is no one's gesture until it lapses.
101
101
  */
102
102
  export const SHELL_STALL_MS = 100;
103
+ /**
104
+ * A press a nested page's runtime told its shell (P148) within this long after the shell was seen
105
+ * to have stalled is no one's. The shell notes a press when it hears it, and a page that holds the
106
+ * thread it shares with its shell makes that late, by as long as it likes: when the page lets go,
107
+ * what waited behind it runs at once, the shell's own look among it, which may come first and say
108
+ * the stall, the press following a moment later as if it were new.
109
+ */
110
+ export const SHELL_AFTER_STALL_MS = 500;
103
111
  /**
104
112
  * Whether the person moved focus into the frame themselves:
105
113
  * - the host did (`DisplayHandle.focus()`);
@@ -132,8 +140,7 @@ export function personMoved(move) {
132
140
  if (move.shell !== undefined && move.shell.word.supported) {
133
141
  return ((move.seen && move.pressed) ||
134
142
  (move.now - move.typedAt >= KEY_PRESS_MS &&
135
- shellGesture(move.shell.word, move.shell.hostInputAt, move.now) &&
136
- !(move.shell.pointerShown === true && move.shell.word.keyed === true)));
143
+ shellSaw(move.shell.word, move.shell.hostInputAt, move.now, move.shell.pointerShown === true)));
137
144
  }
138
145
  if (move.seen ? move.pressed : move.over && move.overSince > Math.max(move.typedAt, move.focusedAt)) {
139
146
  return true;
@@ -151,6 +158,28 @@ export function shellGesture(word, hostInputAt, now) {
151
158
  now >= word.activatedAt &&
152
159
  hostInputAt < word.activatedAt);
153
160
  }
161
+ /**
162
+ * Whether a nested page's runtime told its shell a real press just now (P148): the shell heard it
163
+ * within `SHELL_GESTURE_MS`, after the host's page's last trusted press or key. What the shell's
164
+ * activation can't say: a press while it is already on (within 5 s of the last gesture).
165
+ */
166
+ export function shellPress(word, hostInputAt, now) {
167
+ const pressedAt = word.pressedAt ?? -Infinity;
168
+ return (word.supported &&
169
+ now - pressedAt <= SHELL_GESTURE_MS &&
170
+ now >= pressedAt &&
171
+ hostInputAt < pressedAt);
172
+ }
173
+ /**
174
+ * Whether a nested page's shell saw the person's gesture just now, either way: its activation
175
+ * turned on (`shellGesture`, P111), or its page's runtime told it a press (`shellPress`, P148);
176
+ * each only where a press could have made it (P120: `shown`, the host's page sees the pointer over
177
+ * its frames, and the word is `keyed`, the person's key landing in the page).
178
+ */
179
+ export function shellSaw(word, hostInputAt, now, shown) {
180
+ return ((shellGesture(word, hostInputAt, now) && !(shown && word.keyed === true)) ||
181
+ (shellPress(word, hostInputAt, now) && !(shown && word.pressKeyed === true)));
182
+ }
154
183
  /**
155
184
  * Whether the person could have pressed the frame just before `at` (P120): a nested page's shell
156
185
  * says its activation turned on, which a key typed into the page does as well as a press. Where the
@@ -349,7 +378,7 @@ export function focusGuard(view) {
349
378
  // The shell's activation, where a press could have made it: within a second of the person's
350
379
  // typing on the host's page with the pointer elsewhere, it is their keys landing in the page
351
380
  // (P120). Read as of the move.
352
- const theirs = word !== null && shellGesture(word, inputAt, at) && !(pointerShown && word.keyed === true);
381
+ const theirs = word !== null && shellSaw(word, inputAt, at, pointerShown);
353
382
  // It said focus came in around the move, or answered the ask the move made with focus in it.
354
383
  const spoke = word !== null &&
355
384
  (word.focusedAt >= held.since - SHELL_EARLY_MS || (guarded.answered && word.focused));
@@ -625,6 +654,7 @@ export function focusGuard(view) {
625
654
  taken: new Set(),
626
655
  overSince: -Infinity,
627
656
  heardAt: -Infinity,
657
+ stalledAt: -Infinity,
628
658
  ask: options?.nested === true ? options.ask : undefined,
629
659
  asked: 0,
630
660
  answered: false,
@@ -664,6 +694,9 @@ export function focusGuard(view) {
664
694
  // before it (P122): that key's successor, landing in the page.
665
695
  const turnedOn = said.ago !== null && before.activatedAt === -Infinity && !before.uncertain;
666
696
  const stalled = said.gap > SHELL_STALL_MS || at - guarded.heardAt > SHELL_STALL_MS;
697
+ if (stalled) {
698
+ guarded.stalledAt = at;
699
+ }
667
700
  const fought = contest !== null && contest.fight && contest.frame === frame;
668
701
  // The typing before it, never after: a key the person typed on the host's page after they
669
702
  // pressed the page, before the shell's word came, says nothing of that press (P122, after
@@ -686,6 +719,32 @@ export function focusGuard(view) {
686
719
  : turnedOn
687
720
  ? !pressPossible(true, frame.matches(":hover"), guarded.overSince, typing, turnedAt)
688
721
  : before.keyed === true;
722
+ // A press its page's runtime told it (P148), new when it has heard more than it had: judged
723
+ // as an activation that turned on is. Heard in or just after a stall
724
+ // (`SHELL_AFTER_STALL_MS`), in a fight for a text field, or within `KEY_PRESS_MS` of a key
725
+ // the person typed on the host's page before it, it is no one's (a press says nothing of
726
+ // when it was until the shell hears it, and Enter or Space on a button the page put the
727
+ // focus on is the person's key landing in the page); and whether a press could have made
728
+ // it is judged now, as the shell tells it (P120).
729
+ const pressNew = typeof said.presses === "number" && said.presses !== (before.presses ?? 0);
730
+ const pressHeardAt = typeof said.pressed === "number"
731
+ ? at - said.pressed - Math.min(said.gap, SHELL_STALL_MS)
732
+ : -Infinity;
733
+ const pressTyping = typedBefore(pressHeardAt);
734
+ const pressedAt = typeof said.pressed !== "number"
735
+ ? -Infinity
736
+ : !pressNew
737
+ ? (before.pressedAt ?? -Infinity)
738
+ : at - guarded.stalledAt <= SHELL_AFTER_STALL_MS ||
739
+ fought ||
740
+ pressHeardAt - pressTyping < KEY_PRESS_MS
741
+ ? -Infinity
742
+ : at - said.pressed;
743
+ const pressKeyed = pressedAt === -Infinity
744
+ ? false
745
+ : pressNew
746
+ ? !pressPossible(true, frame.matches(":hover"), guarded.overSince, pressTyping, pressHeardAt)
747
+ : before.pressKeyed === true;
689
748
  guarded.word = {
690
749
  supported: said.supported,
691
750
  activatedAt,
@@ -693,15 +752,33 @@ export function focusGuard(view) {
693
752
  focusedAt: said.focused && !before.focused ? at : before.focusedAt,
694
753
  ...(uncertain ? { uncertain: true } : {}),
695
754
  ...(keyed ? { keyed: true } : {}),
755
+ ...(said.presses === undefined ? {} : { pressedAt, presses: said.presses }),
756
+ ...(pressKeyed ? { pressKeyed: true } : {}),
696
757
  };
697
758
  if (waiting?.frame === frame) {
698
759
  settle(at);
699
760
  }
761
+ else if (pressNew &&
762
+ known === frame &&
763
+ document.activeElement === frame &&
764
+ contest === null &&
765
+ shellPress(guarded.word, inputAt, at) &&
766
+ !(pointerShown && pressKeyed)) {
767
+ // Focus is in the frame already and the person pressed in its page: theirs from here on,
768
+ // as a move into it they made is (the shell's word on the move may have come before the
769
+ // press's did).
770
+ earned = true;
771
+ }
700
772
  },
701
773
  beat(frame) {
702
774
  const guarded = frames.get(frame);
703
775
  if (guarded !== undefined && guarded.word !== null) {
704
- guarded.heardAt = now();
776
+ const at = now();
777
+ // The first word after a silence may be a heartbeat: the stall is the same.
778
+ if (at - guarded.heardAt > SHELL_STALL_MS) {
779
+ guarded.stalledAt = at;
780
+ }
781
+ guarded.heardAt = at;
705
782
  }
706
783
  },
707
784
  gesture(frame) {
@@ -710,10 +787,7 @@ export function focusGuard(view) {
710
787
  const at = now();
711
788
  // Where a press could have made it (P120): a key the person typed into the page, meant for
712
789
  // the host's composer, turns the shell's activation on too.
713
- return (guarded !== undefined &&
714
- word !== null &&
715
- shellGesture(word, inputAt, at) &&
716
- !(pointerShown && word.keyed === true));
790
+ return guarded !== undefined && word !== null && shellSaw(word, inputAt, at, pointerShown);
717
791
  },
718
792
  focus(frame) {
719
793
  hostMove = { frame, at: now() };
@@ -24,7 +24,7 @@ function shellWords(opened, frame, guard) {
24
24
  if (params === null || typeof params !== "object") {
25
25
  return;
26
26
  }
27
- const { supported, ago, focused, gap, asked } = params;
27
+ const { supported, ago, focused, gap, asked, pressed, presses } = params;
28
28
  const span = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0;
29
29
  if (message.method === SHELL_BEAT_METHOD) {
30
30
  if (span(gap)) {
@@ -37,7 +37,12 @@ function shellWords(opened, frame, guard) {
37
37
  typeof focused !== "boolean" ||
38
38
  !(ago === null || span(ago)) ||
39
39
  !span(gap) ||
40
- !(asked === undefined || (Number.isSafeInteger(asked) && asked >= 0))) {
40
+ !(asked === undefined || (Number.isSafeInteger(asked) && asked >= 0)) ||
41
+ // The page's presses (P148): absent from a shell older than them, or both there.
42
+ !((pressed === undefined && presses === undefined) ||
43
+ ((pressed === null || span(pressed)) &&
44
+ Number.isSafeInteger(presses) &&
45
+ presses >= 0))) {
41
46
  return;
42
47
  }
43
48
  guard.shell(frame, {
@@ -46,6 +51,9 @@ function shellWords(opened, frame, guard) {
46
51
  focused,
47
52
  gap: gap,
48
53
  ...(asked === undefined ? {} : { asked: asked }),
54
+ ...(presses === undefined
55
+ ? {}
56
+ : { pressed: pressed, presses: presses }),
49
57
  });
50
58
  });
51
59
  return {
@@ -2,7 +2,7 @@ import { INERT_FILE_CSP, PAGE_SANDBOX_TOKENS, servedPermissionsPolicy, serialize
2
2
  import { frameShellDocument, frameShellScript } from "../shell/frame.js";
3
3
  import { onNestedLabel, PORTHOLE_LABEL_PREFIX } from "../isolation/served.js";
4
4
  import { sha256, utf8 } from "./crypto.js";
5
- import { ancestorsOf } from "./pages.js";
5
+ import { ancestorsOf, checkHostOrigins } from "./pages.js";
6
6
  import { base32 } from "./keys.js";
7
7
  export { isNestedLabel, PORTHOLE_LABEL_PREFIX } from "../isolation/served.js";
8
8
  /**
@@ -38,6 +38,7 @@ const base64 = (bytes) => btoa(String.fromCharCode(...bytes));
38
38
  * document of its own, which inherits none of this (a framed URL's document never does).
39
39
  */
40
40
  export function nestedShellCsp(script, origin, hostOrigins, framedBy = []) {
41
+ checkHostOrigins("nestedShellCsp", hostOrigins);
41
42
  const files = `${origin}${NESTED_FILES_PREFIX}`;
42
43
  const directives = [
43
44
  ["default-src", "'none'"],
@@ -1,7 +1,14 @@
1
1
  import type { FrameBlock } from "../host/types.ts";
2
2
  /**
3
- * Who may frame a page: the host origins, then a host's `framedBy` (P141), each checked (they go
4
- * into a header).
3
+ * The host origins a helper was given, each checked as a config's are (`hostOriginProblem`, P145):
4
+ * they go into a header (`frame-ancestors`) and into the page's own list of whom it tells, and a
5
+ * content Worker of a host's own passes them here itself. `who` names the helper in the error.
6
+ */
7
+ export declare function checkHostOrigins(who: string, hostOrigins: readonly string[]): void;
8
+ /**
9
+ * Who may frame a page: the host origins, then a host's `framedBy` (P141), each `framedBy`
10
+ * checked here (they go into a header); the host origins by whoever was given them (a config's by
11
+ * `createServer`, a helper's by `checkHostOrigins`).
5
12
  */
6
13
  export declare function ancestorsOf(hostOrigins: readonly string[], framedBy?: readonly string[]): string;
7
14
  /** Where the pages' scripts are served, on every content origin. */
@@ -1,5 +1,5 @@
1
1
  import { DOOR_SANDBOX_TOKENS } from "../compile/policy.js";
2
- import { framedByProblem, includesOrigin, normalOrigin } from "../isolation/served.js";
2
+ import { framedByProblem, hostOriginProblem, includesOrigin, normalOrigin, } from "../isolation/served.js";
3
3
  import { FRAME_STATUS_METHOD } from "../isolation/types.js";
4
4
  import { base64url, sha256, utf8 } from "./crypto.js";
5
5
  /**
@@ -24,8 +24,22 @@ const isStrict = (frameAncestors, hostOrigins) => !heldToHosts(frameAncestors, h
24
24
  /** The attribute that says so, on a page's `<main>`: none where its parent is held to its hosts. */
25
25
  const strictParent = (strict) => (strict ? ' data-porthole-strict-parent=""' : "");
26
26
  /**
27
- * Who may frame a page: the host origins, then a host's `framedBy` (P141), each checked (they go
28
- * into a header).
27
+ * The host origins a helper was given, each checked as a config's are (`hostOriginProblem`, P145):
28
+ * they go into a header (`frame-ancestors`) and into the page's own list of whom it tells, and a
29
+ * content Worker of a host's own passes them here itself. `who` names the helper in the error.
30
+ */
31
+ export function checkHostOrigins(who, hostOrigins) {
32
+ for (const origin of hostOrigins) {
33
+ const problem = hostOriginProblem(origin);
34
+ if (problem !== null) {
35
+ throw new TypeError(`${who}: hostOrigins: ${problem}`);
36
+ }
37
+ }
38
+ }
39
+ /**
40
+ * Who may frame a page: the host origins, then a host's `framedBy` (P141), each `framedBy`
41
+ * checked here (they go into a header); the host origins by whoever was given them (a config's by
42
+ * `createServer`, a helper's by `checkHostOrigins`).
29
43
  */
30
44
  export function ancestorsOf(hostOrigins, framedBy = []) {
31
45
  for (const origin of framedBy) {
@@ -209,12 +223,17 @@ export function appStatusPage(status, title, detail, frameAncestors, reason, hos
209
223
  });
210
224
  }
211
225
  /** Whom a page tells, and who may frame it: the host origins' (P141), or an embed's (P143). */
212
- const framingOf = (options) => options.embed === true
213
- ? { hosts: [], ancestors: "*" }
214
- : {
226
+ const framingOf = (who, options) => {
227
+ if (options.embed === true) {
228
+ return { hosts: [], ancestors: "*" };
229
+ }
230
+ // Checked here too: with `frameAncestors` given, `ancestorsOf` never sees them.
231
+ checkHostOrigins(who, options.hostOrigins);
232
+ return {
215
233
  hosts: options.hostOrigins,
216
234
  ancestors: options.frameAncestors ?? ancestorsOf(options.hostOrigins, options.framedBy),
217
235
  };
236
+ };
218
237
  /**
219
238
  * A page saying why a frame shows nothing, for a relay of the app's own (P072): told to the page
220
239
  * that frames it, at each web host origin and (a desktop scheme among them) to its parent (P070),
@@ -222,7 +241,7 @@ const framingOf = (options) => options.embed === true
222
241
  * any page and told to no one.
223
242
  */
224
243
  export function statusPageOf(options) {
225
- const { hosts, ancestors } = framingOf(options);
244
+ const { hosts, ancestors } = framingOf("statusPage", options);
226
245
  return appStatusPage(options.status, options.title, options.detail, ancestors, options.reason ?? "error", hosts, options.link, options.method);
227
246
  }
228
247
  /** A door's word that its display may be framed (P125), from the page's data attributes. */
@@ -256,6 +275,7 @@ const doorHeaders = (script, frameAncestors) => new Headers({
256
275
  * own ticket was taken and the checks the content's address runs passed for the same grant.
257
276
  */
258
277
  export function doorResponse(options) {
278
+ checkHostOrigins("doorResponse", options.hostOrigins);
259
279
  const hosts = escape(JSON.stringify(options.hostOrigins));
260
280
  const ancestors = options.frameAncestors ?? ancestorsOf(options.hostOrigins, options.framedBy);
261
281
  const strict = isStrict(ancestors, options.hostOrigins);
@@ -275,7 +295,7 @@ export function doorResponse(options) {
275
295
  */
276
296
  export function doorStatusResponse(options) {
277
297
  const { status, reason, code } = options;
278
- const framing = framingOf(options);
298
+ const framing = framingOf("doorStatusResponse", options);
279
299
  const hosts = escape(JSON.stringify(framing.hosts));
280
300
  const ancestors = framing.ancestors;
281
301
  const strict = isStrict(ancestors, framing.hosts);
@@ -410,7 +410,37 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
410
410
  // The selection the host follows (P138) is drawn as what is picked is: an element in the
411
411
  // picking outline, a little lighter and without its name; words with a light fill and a line
412
412
  // under them, in the same blue, apart from the marks' yellow (no comment is there yet).
413
- const STYLE = ".mark{position:absolute;border-radius:2px;background:rgba(250,204,21,.18);box-shadow:inset 0 -2px 0 rgba(234,179,8,.95)}.mark.element{background:rgba(250,204,21,.07);box-shadow:none;outline:2px solid rgba(234,179,8,.9);outline-offset:1px}.mark.active{background:rgba(250,204,21,.26);box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 2px rgba(234,179,8,.45)}.mark.element.active{background:rgba(250,204,21,.12);box-shadow:none;outline-width:3px}.mark.element.quiet{background:rgba(250,204,21,.05);outline:1px solid rgba(234,179,8,.6);outline-offset:2px}.mark.element.quiet.active{background:rgba(250,204,21,.1);outline:2px solid rgba(234,179,8,.9)}.mark.draft{box-sizing:border-box;background:rgba(250,204,21,.08);box-shadow:none;border-bottom:2px dashed rgba(202,138,4,.95)}.mark.draft.active{background:rgba(250,204,21,.16);box-shadow:0 0 0 2px rgba(234,179,8,.45);border-bottom-width:3px}.mark.element.draft{background:rgba(250,204,21,.04);border-bottom:0;outline-style:dashed}.mark.element.draft.active{background:rgba(250,204,21,.08);box-shadow:none;outline-style:dashed}.marker{position:absolute;box-sizing:border-box;height:18px;min-width:18px;display:flex;align-items:center;justify-content:center;gap:3px;margin:0;padding:0 5px;border:1px solid rgba(161,98,7,.6);border-radius:9px 9px 9px 2px;background:#fde68a;color:#422006;box-shadow:0 1px 2px rgba(0,0,0,.3);font:600 11px/16px system-ui,-apple-system,Segoe UI,Roboto,sans-serif;font-style:normal;letter-spacing:0;word-spacing:0;text-transform:none;text-indent:0;text-shadow:none;direction:ltr;writing-mode:horizontal-tb;white-space:nowrap;user-select:none;-webkit-user-select:none;cursor:pointer;pointer-events:auto;appearance:none;-webkit-appearance:none}.marker:focus-visible{outline:2px solid #2563eb;outline-offset:1px}.marker:hover{background:#fcd34d}.marker.active{background:#facc15;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.3)}.marker.compact{padding:0 4px}.marker.draft{border:1px dashed rgb(202,138,4);background:#fffdf5;color:#a16207;box-shadow:0 1px 2px rgba(0,0,0,.2)}.marker.draft:hover{background:#fef9e7}.marker.draft.active{background:#fef3c7;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.2)}.marker.inert,[data-placing]>.marker{pointer-events:none}.touch>.marker::before{content:'';position:absolute;left:50%;top:50%;width:max(100% + 2px,44px);height:max(100% + 2px,44px);transform:translate(-50%,-50%)}.marker svg{display:block;width:11px;height:11px;flex:none}.mark.flash{animation:flash 1.8s ease-out}@keyframes flash{from{box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 6px rgba(250,204,21,.6)}}.hover{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.12)}.held{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.06)}.held.text{outline:0;border-radius:2px;background:rgba(37,99,235,.12);box-shadow:inset 0 -2px 0 #2563eb}.tag{position:absolute;max-width:70vw;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:12px/18px ui-monospace,SFMono-Regular,Menlo,monospace;padding:0 6px;border-radius:4px;background:#1e293b;color:#fff}";
413
+ const STYLE = ".mark{position:absolute;border-radius:2px;background:rgba(250,204,21,.18);box-shadow:inset 0 -2px 0 rgba(234,179,8,.95)}.mark.element{background:rgba(250,204,21,.07);box-shadow:none;outline:2px solid rgba(234,179,8,.9);outline-offset:1px}.mark.active{background:rgba(250,204,21,.26);box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 2px rgba(234,179,8,.45)}.mark.element.active{background:rgba(250,204,21,.12);box-shadow:none;outline-width:3px}.mark.element.quiet{background:rgba(250,204,21,.05);outline:1px solid rgba(234,179,8,.6);outline-offset:2px}.mark.element.quiet.active{background:rgba(250,204,21,.1);outline:2px solid rgba(234,179,8,.9)}.mark.draft{box-sizing:border-box;background:rgba(250,204,21,.08);box-shadow:none;border-bottom:2px dashed rgba(202,138,4,.95)}.mark.draft.active{background:rgba(250,204,21,.16);box-shadow:0 0 0 2px rgba(234,179,8,.45);border-bottom-width:3px}.mark.element.draft{background:rgba(250,204,21,.04);border-bottom:0;outline-style:dashed}.mark.element.draft.active{background:rgba(250,204,21,.08);box-shadow:none;outline-style:dashed}.marker{position:absolute;box-sizing:border-box;height:18px;min-width:18px;display:flex;align-items:center;justify-content:center;gap:3px;margin:0;padding:0 5px;border:1px solid rgba(161,98,7,.6);border-radius:9px 9px 9px 2px;background:#fde68a;color:#422006;box-shadow:0 1px 2px rgba(0,0,0,.3);font:600 11px/16px system-ui,-apple-system,Segoe UI,Roboto,sans-serif;font-style:normal;letter-spacing:0;word-spacing:0;text-transform:none;text-indent:0;text-shadow:none;direction:ltr;writing-mode:horizontal-tb;white-space:nowrap;user-select:none;-webkit-user-select:none;cursor:pointer;pointer-events:auto;appearance:none;-webkit-appearance:none}.marker:focus-visible{outline:2px solid #2563eb;outline-offset:1px}.marker:hover{background:#fcd34d}.marker.active{background:#facc15;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.3)}.marker.compact{padding:0 4px}.marker.draft{border:1px dashed rgb(202,138,4);background:#fffdf5;color:#a16207;box-shadow:0 1px 2px rgba(0,0,0,.2)}.marker.draft:hover{background:#fef9e7}.marker.draft.active{background:#fef3c7;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.2)}.marker.inert,[data-placing]>.marker{pointer-events:none}.touch>.marker::before{content:'';position:absolute;left:50%;top:50%;width:max(100% + 2px,44px);height:max(100% + 2px,44px);transform:translate(-50%,-50%)}.marker svg{display:block;width:11px;height:11px;flex:none}.mark.flash{animation:flash 1.8s ease-out}@keyframes flash{from{box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 6px rgba(250,204,21,.6)}}.hover{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.12)}.held{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.06)}.held.text{outline:0;border-radius:2px;background:rgba(37,99,235,.12);box-shadow:inset 0 -2px 0 #2563eb}.tag{position:absolute;max-width:70vw;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:12px/18px ui-monospace,SFMono-Regular,Menlo,monospace;padding:0 6px;border-radius:4px;background:#1e293b;color:#fff}.ride{position:absolute;left:0;top:0;width:0;height:0}@supports (animation-timeline:scroll()){.ride{animation:ride 1ms linear both;animation-timeline:scroll(root y)}@keyframes ride{to{transform:translateY(calc(-1px*var(--ride)))}}}";
414
+ // The marks ride the document's own scroll (P147). The layer stays fixed and clipped to the
415
+ // viewport, so it adds nothing to what the page can scroll; inside it one box holds every
416
+ // mark, marker and outline at its place in the document (its top plus how far the document
417
+ // is scrolled), and a scroll-driven animation moves that box up by the scroll. The engine
418
+ // runs it with the scroll itself, so a mark is where its words are in every frame, not a
419
+ // frame behind (a scroll event is heard after the frame it scrolled). Down the page only:
420
+ // sideways, and where the engine has no scroll timeline (ridden: 0), a mark is placed in the
421
+ // viewport and follows from the scroll event as before. Read with the DOM's own getters,
422
+ // taken before content runs; the range is what the timeline runs over (0: it is inactive,
423
+ // and nothing moves).
424
+ const rides = typeof CSS === "object" && CSS !== null && typeof CSS.supports === "function" && CSS.supports("animation-timeline: scroll()");
425
+ const scrollerOf = getterOf(Document.prototype, "scrollingElement");
426
+ const scrollTopOf = getterOf(Element.prototype, "scrollTop");
427
+ const scrollHeightOf = getterOf(Element.prototype, "scrollHeight");
428
+ const clientHeightOf = getterOf(Element.prototype, "clientHeight");
429
+ // How far down the document is scrolled as the marks are drawn, and how far it can be.
430
+ let ridden = 0;
431
+ const rideOf = () => {
432
+ const none = { by: 0, range: 0 };
433
+ if (!rides || scrollerOf === null || scrollTopOf === null || scrollHeightOf === null || clientHeightOf === null) {
434
+ return none;
435
+ }
436
+ const scroller = callOf(scrollerOf, document, []);
437
+ if (!scroller) {
438
+ return none;
439
+ }
440
+ const range = callOf(scrollHeightOf, scroller, []) - callOf(clientHeightOf, scroller, []);
441
+ const by = callOf(scrollTopOf, scroller, []);
442
+ return range > 0 && by >= 0 && by <= range + 1 ? { by, range } : none;
443
+ };
414
444
  // Inline and important: the content's own style sheets can't hide, shrink or move it by
415
445
  // accident. Set again at each draw, since its scripts can rewrite it (narrowing only: the
416
446
  // content can still cover the layer, or move it with its ancestors, P104). Clipped, where an
@@ -788,7 +818,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
788
818
  // button: Safari's Tab skips a button without one, unless the person asked otherwise.
789
819
  marker.tabIndex = mode.elements ? -1 : 0;
790
820
  marker.className = "marker" + (mark.draft ? " draft" : "") + (each.compact ? " compact" : "") + (mark.id === active ? " active" : "") + (mode.elements ? " inert" : "");
791
- marker.style.cssText = "left:" + each.left + "px;top:" + each.top + "px";
821
+ marker.style.cssText = "left:" + each.left + "px;top:" + (each.top + ridden) + "px";
792
822
  markers.push({ id: mark.id, element: marker });
793
823
  const name = nameOf(mark);
794
824
  const form = (mark.draft ? "draft:" : "") + (each.compact ? "compact:" : "full:") + label + ":" + name;
@@ -835,17 +865,19 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
835
865
  // the pointer's arrival on a marker lit its mark and redrew).
836
866
  let boxes = null;
837
867
  const boxesOf = (root) => {
838
- if (boxes === null || boxes.style.parentNode !== root || boxes.marks.parentNode !== root || boxes.markers.parentNode !== root || boxes.hover.parentNode !== root) {
868
+ if (boxes === null || boxes.style.parentNode !== root || boxes.ride.parentNode !== root || boxes.marks.parentNode !== boxes.ride || boxes.markers.parentNode !== boxes.ride || boxes.hover.parentNode !== boxes.ride) {
839
869
  const style = createElement.call(document, "style");
840
870
  if (nonce !== "") {
841
871
  style.nonce = nonce;
842
872
  }
843
- boxes = { style, marks: createElement.call(document, "div"), markers: createElement.call(document, "div"), hover: createElement.call(document, "div") };
873
+ boxes = { style, ride: createElement.call(document, "div"), marks: createElement.call(document, "div"), markers: createElement.call(document, "div"), hover: createElement.call(document, "div") };
874
+ boxes.ride.className = "ride";
844
875
  // Only the markers are for assistive technology (P133): the rest draws what the page
845
876
  // already says.
846
877
  boxes.marks.setAttribute("aria-hidden", "true");
847
878
  boxes.hover.setAttribute("aria-hidden", "true");
848
- root.replaceChildren(boxes.style, boxes.marks, boxes.markers, boxes.hover);
879
+ boxes.ride.replaceChildren(boxes.marks, boxes.markers, boxes.hover);
880
+ root.replaceChildren(boxes.style, boxes.ride);
849
881
  }
850
882
  if (boxes.style.textContent !== STYLE) {
851
883
  boxes.style.textContent = STYLE;
@@ -863,6 +895,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
863
895
  const into = boxesOf(root);
864
896
  const parts = [];
865
897
  const flashOn = Date.now() < flashUntil;
898
+ // Read with the boxes, in this one task: a place in the document is a box's top in the
899
+ // viewport plus this.
900
+ const ride = rideOf();
901
+ ridden = ride.by;
866
902
  // What is measured first, then drawn: no node of the layer changes while the page is read.
867
903
  const corners = [];
868
904
  const wanted = [];
@@ -879,7 +915,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
879
915
  }
880
916
  const each = createElement.call(document, "div");
881
917
  each.className = "mark " + (mark.found.range ? "text" : "element") + (mark.marker ? " quiet" : "") + (mark.draft ? " draft" : "") + (mark.id === active || mark.id === hot ? " active" : "") + (flashOn && mark.id === flashing ? " flash" : "");
882
- each.style.cssText = "left:" + rect.left + "px;top:" + rect.top + "px;width:" + rect.width + "px;height:" + rect.height + "px";
918
+ each.style.cssText = "left:" + rect.left + "px;top:" + (rect.top + ridden) + "px;width:" + rect.width + "px;height:" + rect.height + "px";
883
919
  parts.push(each);
884
920
  }
885
921
  if (mark.marker) {
@@ -965,7 +1001,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
965
1001
  }
966
1002
  const each = createElement.call(document, "div");
967
1003
  each.className = lit.range ? "held text" : "held";
968
- each.style.cssText = "left:" + rect.left + "px;top:" + rect.top + "px;width:" + rect.width + "px;height:" + rect.height + "px";
1004
+ each.style.cssText = "left:" + rect.left + "px;top:" + (rect.top + ridden) + "px;width:" + rect.width + "px;height:" + rect.height + "px";
969
1005
  outlines.push(each);
970
1006
  }
971
1007
  }
@@ -973,13 +1009,18 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
973
1009
  const rect = elementRect.call(hover);
974
1010
  const outline = createElement.call(document, "div");
975
1011
  outline.className = "hover";
976
- outline.style.cssText = "left:" + rect.left + "px;top:" + rect.top + "px;width:" + rect.width + "px;height:" + rect.height + "px";
1012
+ outline.style.cssText = "left:" + rect.left + "px;top:" + (rect.top + ridden) + "px;width:" + rect.width + "px;height:" + rect.height + "px";
977
1013
  const tag = createElement.call(document, "div");
978
1014
  tag.className = "tag";
979
1015
  tag.textContent = describe(hover).slice(0, 80);
980
- tag.style.cssText = "left:" + Math.max(4, rect.left) + "px;top:" + (rect.top >= 24 ? rect.top - 22 : Math.max(4, rect.bottom + 4)) + "px";
1016
+ tag.style.cssText = "left:" + Math.max(4, rect.left) + "px;top:" + ((rect.top >= 24 ? rect.top - 22 : Math.max(4, rect.bottom + 4)) + ridden) + "px";
981
1017
  outlines.push(outline, tag);
982
1018
  }
1019
+ // How far the ride goes, for the animation; set only when it changed.
1020
+ const range = String(ride.range);
1021
+ if (into.ride.style.getPropertyValue("--ride") !== range) {
1022
+ into.ride.style.setProperty("--ride", range);
1023
+ }
983
1024
  into.marks.replaceChildren(...parts);
984
1025
  for (const child of Array.from(into.markers.childNodes)) {
985
1026
  if (badges.indexOf(child) === -1) {
@@ -2,7 +2,7 @@
2
2
  export declare const FRAME_SHELL_RUNTIME: string;
3
3
  /** A strict shell's runtime (P141): its parent may be an outer page. */
4
4
  export declare const STRICT_FRAME_SHELL_RUNTIME: string;
5
- export { SHELL_METHOD_PREFIX, SHELL_STATE_METHOD } from "../isolation/types.ts";
5
+ export { SHELL_METHOD_PREFIX, SHELL_PRESS_PORT_METHOD, SHELL_STATE_METHOD, } from "../isolation/types.ts";
6
6
  export interface FrameShellOptions {
7
7
  /** The host origins: the shell takes messages from its parent only from these. */
8
8
  readonly origins: readonly string[];