@botiverse/porthole 0.15.2 → 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.
@@ -63,8 +63,17 @@ export function isExactOrigin(origin: unknown): origin is string {
63
63
  const HOST_ORIGIN =
64
64
  /^[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;
65
65
 
66
+ /** Whether `origin` is written as an origin is (`HOST_ORIGIN`), whatever a browser makes of it. */
67
+ const shapedAsOrigin = (origin: unknown): origin is string =>
68
+ typeof origin === "string" && origin.length <= 300 && HOST_ORIGIN.test(origin);
69
+
70
+ /**
71
+ * Whether `origin` can be a host origin: written as one, and one a browser serializes as it is
72
+ * written (`serializable`: never `:0`, a port past 65535 or with a leading zero, a host the URL
73
+ * parser would rewrite). `hostOriginProblem` says why not.
74
+ */
66
75
  export function isHostOrigin(origin: unknown): origin is string {
67
- return typeof origin === "string" && origin.length <= 300 && HOST_ORIGIN.test(origin);
76
+ return shapedAsOrigin(origin) && serializable(origin);
68
77
  }
69
78
 
70
79
  /**
@@ -94,7 +103,7 @@ function serializable(origin: string): boolean {
94
103
 
95
104
  /** Why `origin` can't be a host origin, in words a host's developer can act on; null if it can. */
96
105
  export function hostOriginProblem(origin: unknown): string | null {
97
- if (isHostOrigin(origin)) {
106
+ if (shapedAsOrigin(origin)) {
98
107
  return serializable(origin)
99
108
  ? null
100
109
  : `${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)`;
@@ -142,7 +151,7 @@ const LOOPBACK_HOST = (host: string): boolean =>
142
151
  * in plain decimal, and its host is as the URL parser gives it back (P145). Null if it can be.
143
152
  */
144
153
  export function framedByProblem(origin: unknown): string | null {
145
- const parsed = typeof origin === "string" && isHostOrigin(origin) ? parseOrigin(origin) : null;
154
+ const parsed = shapedAsOrigin(origin) ? parseOrigin(origin) : null;
146
155
  if (
147
156
  parsed === null ||
148
157
  !(parsed.scheme === "https" || (parsed.scheme === "http" && LOOPBACK_HOST(parsed.host)))
@@ -107,6 +107,13 @@ export const SHELL_LOOK_METHOD = "porthole/shell/look";
107
107
  */
108
108
  export const SHELL_FOCUS_METHOD = "porthole/shell/focus";
109
109
 
110
+ /**
111
+ * A nested page's shell's word to its page's runtime (P148): one `MessagePort`, sent at each load
112
+ * of the page's frame, over which the runtime tells the shell each real press in the page. The
113
+ * runtime takes the first one alone, before any content runs, and no content ever holds it.
114
+ */
115
+ export const SHELL_PRESS_PORT_METHOD = "porthole/shell/press-port";
116
+
110
117
  /** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
111
118
  export const SHELL_METHOD_PREFIX = "porthole/shell/";
112
119
 
@@ -113,6 +113,15 @@ export const SHELL_EARLY_MS = 150;
113
113
  */
114
114
  export const SHELL_STALL_MS = 100;
115
115
 
116
+ /**
117
+ * A press a nested page's runtime told its shell (P148) within this long after the shell was seen
118
+ * to have stalled is no one's. The shell notes a press when it hears it, and a page that holds the
119
+ * thread it shares with its shell makes that late, by as long as it likes: when the page lets go,
120
+ * what waited behind it runs at once, the shell's own look among it, which may come first and say
121
+ * the stall, the press following a moment later as if it were new.
122
+ */
123
+ export const SHELL_AFTER_STALL_MS = 500;
124
+
116
125
  /** What a nested page's shell last said (P111), on the host's clock. */
117
126
  export interface ShellWord {
118
127
  /** Whether its engine tells activation at all (`navigator.userActivation`). */
@@ -130,6 +139,15 @@ export interface ShellWord {
130
139
  * host's page sees the pointer, their key landing in the page, no press (P120).
131
140
  */
132
141
  readonly keyed?: boolean;
142
+ /**
143
+ * When it last heard a real press from its page's runtime (P148); -Infinity, or absent, if it
144
+ * heard none, or the one it heard is uncertain (judged as an activation that turned on is).
145
+ */
146
+ readonly pressedAt?: number;
147
+ /** How many presses it said it had heard, the last time it spoke: more is a new one. */
148
+ readonly presses?: number;
149
+ /** `keyed`, for the press at `pressedAt`: judged as the shell told it. */
150
+ readonly pressKeyed?: boolean;
133
151
  }
134
152
 
135
153
  /** One move of the keyboard the guard undid. */
@@ -211,8 +229,12 @@ export function personMoved(move: FocusMove): boolean {
211
229
  return (
212
230
  (move.seen && move.pressed) ||
213
231
  (move.now - move.typedAt >= KEY_PRESS_MS &&
214
- shellGesture(move.shell.word, move.shell.hostInputAt, move.now) &&
215
- !(move.shell.pointerShown === true && move.shell.word.keyed === true))
232
+ shellSaw(
233
+ move.shell.word,
234
+ move.shell.hostInputAt,
235
+ move.now,
236
+ move.shell.pointerShown === true,
237
+ ))
216
238
  );
217
239
  }
218
240
  if (
@@ -239,6 +261,39 @@ export function shellGesture(word: ShellWord, hostInputAt: number, now: number):
239
261
  );
240
262
  }
241
263
 
264
+ /**
265
+ * Whether a nested page's runtime told its shell a real press just now (P148): the shell heard it
266
+ * within `SHELL_GESTURE_MS`, after the host's page's last trusted press or key. What the shell's
267
+ * activation can't say: a press while it is already on (within 5 s of the last gesture).
268
+ */
269
+ export function shellPress(word: ShellWord, hostInputAt: number, now: number): boolean {
270
+ const pressedAt = word.pressedAt ?? -Infinity;
271
+ return (
272
+ word.supported &&
273
+ now - pressedAt <= SHELL_GESTURE_MS &&
274
+ now >= pressedAt &&
275
+ hostInputAt < pressedAt
276
+ );
277
+ }
278
+
279
+ /**
280
+ * Whether a nested page's shell saw the person's gesture just now, either way: its activation
281
+ * turned on (`shellGesture`, P111), or its page's runtime told it a press (`shellPress`, P148);
282
+ * each only where a press could have made it (P120: `shown`, the host's page sees the pointer over
283
+ * its frames, and the word is `keyed`, the person's key landing in the page).
284
+ */
285
+ export function shellSaw(
286
+ word: ShellWord,
287
+ hostInputAt: number,
288
+ now: number,
289
+ shown: boolean,
290
+ ): boolean {
291
+ return (
292
+ (shellGesture(word, hostInputAt, now) && !(shown && word.keyed === true)) ||
293
+ (shellPress(word, hostInputAt, now) && !(shown && word.pressKeyed === true))
294
+ );
295
+ }
296
+
242
297
  /**
243
298
  * Whether the person could have pressed the frame just before `at` (P120): a nested page's shell
244
299
  * says its activation turned on, which a key typed into the page does as well as a press. Where the
@@ -317,6 +372,12 @@ export interface FocusGuard {
317
372
  readonly gap: number;
318
373
  /** The ask this report answers (P120), if it answers one. */
319
374
  readonly asked?: number;
375
+ /**
376
+ * Its page's runtime's real presses (P148): how long ago the shell heard the last (null:
377
+ * none since the frame's last load), and how many it has heard. Absent from an older shell.
378
+ */
379
+ readonly pressed?: number | null;
380
+ readonly presses?: number;
320
381
  },
321
382
  ): void;
322
383
  /** A nested page's shell's heartbeat (P111): it is looking. */
@@ -341,6 +402,8 @@ interface Guarded {
341
402
  word: ShellWord | null;
342
403
  /** When the host last heard the shell (a report or a heartbeat). */
343
404
  heardAt: number;
405
+ /** When the shell was last seen to have stalled (`SHELL_STALL_MS`); -Infinity if never. */
406
+ stalledAt: number;
344
407
  /** Asks the shell to look now (P120), the last ask's number, and whether it was answered. */
345
408
  readonly ask: ((n: number) => void) | undefined;
346
409
  asked: number;
@@ -543,8 +606,7 @@ export function focusGuard(view: Window): FocusGuard {
543
606
  // The shell's activation, where a press could have made it: within a second of the person's
544
607
  // typing on the host's page with the pointer elsewhere, it is their keys landing in the page
545
608
  // (P120). Read as of the move.
546
- const theirs =
547
- word !== null && shellGesture(word, inputAt, at) && !(pointerShown && word.keyed === true);
609
+ const theirs = word !== null && shellSaw(word, inputAt, at, pointerShown);
548
610
  // It said focus came in around the move, or answered the ask the move made with focus in it.
549
611
  const spoke =
550
612
  word !== null &&
@@ -853,6 +915,7 @@ export function focusGuard(view: Window): FocusGuard {
853
915
  taken: new Set(),
854
916
  overSince: -Infinity,
855
917
  heardAt: -Infinity,
918
+ stalledAt: -Infinity,
856
919
  ask: options?.nested === true ? options.ask : undefined,
857
920
  asked: 0,
858
921
  answered: false,
@@ -893,6 +956,9 @@ export function focusGuard(view: Window): FocusGuard {
893
956
  // before it (P122): that key's successor, landing in the page.
894
957
  const turnedOn = said.ago !== null && before.activatedAt === -Infinity && !before.uncertain;
895
958
  const stalled = said.gap > SHELL_STALL_MS || at - guarded.heardAt > SHELL_STALL_MS;
959
+ if (stalled) {
960
+ guarded.stalledAt = at;
961
+ }
896
962
  const fought = contest !== null && contest.fight && contest.frame === frame;
897
963
  // The typing before it, never after: a key the person typed on the host's page after they
898
964
  // pressed the page, before the shell's word came, says nothing of that press (P122, after
@@ -918,6 +984,41 @@ export function focusGuard(view: Window): FocusGuard {
918
984
  : turnedOn
919
985
  ? !pressPossible(true, frame.matches(":hover"), guarded.overSince, typing, turnedAt)
920
986
  : before.keyed === true;
987
+ // A press its page's runtime told it (P148), new when it has heard more than it had: judged
988
+ // as an activation that turned on is. Heard in or just after a stall
989
+ // (`SHELL_AFTER_STALL_MS`), in a fight for a text field, or within `KEY_PRESS_MS` of a key
990
+ // the person typed on the host's page before it, it is no one's (a press says nothing of
991
+ // when it was until the shell hears it, and Enter or Space on a button the page put the
992
+ // focus on is the person's key landing in the page); and whether a press could have made
993
+ // it is judged now, as the shell tells it (P120).
994
+ const pressNew = typeof said.presses === "number" && said.presses !== (before.presses ?? 0);
995
+ const pressHeardAt =
996
+ typeof said.pressed === "number"
997
+ ? at - said.pressed - Math.min(said.gap, SHELL_STALL_MS)
998
+ : -Infinity;
999
+ const pressTyping = typedBefore(pressHeardAt);
1000
+ const pressedAt =
1001
+ typeof said.pressed !== "number"
1002
+ ? -Infinity
1003
+ : !pressNew
1004
+ ? (before.pressedAt ?? -Infinity)
1005
+ : at - guarded.stalledAt <= SHELL_AFTER_STALL_MS ||
1006
+ fought ||
1007
+ pressHeardAt - pressTyping < KEY_PRESS_MS
1008
+ ? -Infinity
1009
+ : at - said.pressed;
1010
+ const pressKeyed =
1011
+ pressedAt === -Infinity
1012
+ ? false
1013
+ : pressNew
1014
+ ? !pressPossible(
1015
+ true,
1016
+ frame.matches(":hover"),
1017
+ guarded.overSince,
1018
+ pressTyping,
1019
+ pressHeardAt,
1020
+ )
1021
+ : before.pressKeyed === true;
921
1022
  guarded.word = {
922
1023
  supported: said.supported,
923
1024
  activatedAt,
@@ -925,15 +1026,34 @@ export function focusGuard(view: Window): FocusGuard {
925
1026
  focusedAt: said.focused && !before.focused ? at : before.focusedAt,
926
1027
  ...(uncertain ? { uncertain: true } : {}),
927
1028
  ...(keyed ? { keyed: true } : {}),
1029
+ ...(said.presses === undefined ? {} : { pressedAt, presses: said.presses }),
1030
+ ...(pressKeyed ? { pressKeyed: true } : {}),
928
1031
  };
929
1032
  if (waiting?.frame === frame) {
930
1033
  settle(at);
1034
+ } else if (
1035
+ pressNew &&
1036
+ known === frame &&
1037
+ document.activeElement === frame &&
1038
+ contest === null &&
1039
+ shellPress(guarded.word, inputAt, at) &&
1040
+ !(pointerShown && pressKeyed)
1041
+ ) {
1042
+ // Focus is in the frame already and the person pressed in its page: theirs from here on,
1043
+ // as a move into it they made is (the shell's word on the move may have come before the
1044
+ // press's did).
1045
+ earned = true;
931
1046
  }
932
1047
  },
933
1048
  beat(frame) {
934
1049
  const guarded = frames.get(frame);
935
1050
  if (guarded !== undefined && guarded.word !== null) {
936
- guarded.heardAt = now();
1051
+ const at = now();
1052
+ // The first word after a silence may be a heartbeat: the stall is the same.
1053
+ if (at - guarded.heardAt > SHELL_STALL_MS) {
1054
+ guarded.stalledAt = at;
1055
+ }
1056
+ guarded.heardAt = at;
937
1057
  }
938
1058
  },
939
1059
  gesture(frame) {
@@ -942,12 +1062,7 @@ export function focusGuard(view: Window): FocusGuard {
942
1062
  const at = now();
943
1063
  // Where a press could have made it (P120): a key the person typed into the page, meant for
944
1064
  // the host's composer, turns the shell's activation on too.
945
- return (
946
- guarded !== undefined &&
947
- word !== null &&
948
- shellGesture(word, inputAt, at) &&
949
- !(pointerShown && word.keyed === true)
950
- );
1065
+ return guarded !== undefined && word !== null && shellSaw(word, inputAt, at, pointerShown);
951
1066
  },
952
1067
  focus(frame) {
953
1068
  hostMove = { frame, at: now() };
@@ -36,7 +36,10 @@ function shellWords(opened: Transport, frame: HTMLIFrameElement, guard: FocusGua
36
36
  if (params === null || typeof params !== "object") {
37
37
  return;
38
38
  }
39
- const { supported, ago, focused, gap, asked } = params as Record<string, unknown>;
39
+ const { supported, ago, focused, gap, asked, pressed, presses } = params as Record<
40
+ string,
41
+ unknown
42
+ >;
40
43
  const span = (value: unknown) =>
41
44
  typeof value === "number" && Number.isFinite(value) && value >= 0;
42
45
  if (message.method === SHELL_BEAT_METHOD) {
@@ -51,7 +54,14 @@ function shellWords(opened: Transport, frame: HTMLIFrameElement, guard: FocusGua
51
54
  typeof focused !== "boolean" ||
52
55
  !(ago === null || span(ago)) ||
53
56
  !span(gap) ||
54
- !(asked === undefined || (Number.isSafeInteger(asked) && (asked as number) >= 0))
57
+ !(asked === undefined || (Number.isSafeInteger(asked) && (asked as number) >= 0)) ||
58
+ // The page's presses (P148): absent from a shell older than them, or both there.
59
+ !(
60
+ (pressed === undefined && presses === undefined) ||
61
+ ((pressed === null || span(pressed)) &&
62
+ Number.isSafeInteger(presses) &&
63
+ (presses as number) >= 0)
64
+ )
55
65
  ) {
56
66
  return;
57
67
  }
@@ -61,6 +71,9 @@ function shellWords(opened: Transport, frame: HTMLIFrameElement, guard: FocusGua
61
71
  focused,
62
72
  gap: gap as number,
63
73
  ...(asked === undefined ? {} : { asked: asked as number }),
74
+ ...(presses === undefined
75
+ ? {}
76
+ : { pressed: pressed as number | null, presses: presses as number }),
64
77
  });
65
78
  });
66
79
  return {
@@ -9,7 +9,7 @@ import {
9
9
  import { frameShellDocument, frameShellScript, type FrameShellOptions } from "../shell/frame.ts";
10
10
  import { onNestedLabel, PORTHOLE_LABEL_PREFIX } from "../isolation/served.ts";
11
11
  import { sha256, utf8 } from "./crypto.ts";
12
- import { ancestorsOf } from "./pages.ts";
12
+ import { ancestorsOf, checkHostOrigins } from "./pages.ts";
13
13
  import { base32 } from "./keys.ts";
14
14
 
15
15
  export { isNestedLabel, PORTHOLE_LABEL_PREFIX } from "../isolation/served.ts";
@@ -56,6 +56,7 @@ export function nestedShellCsp(
56
56
  hostOrigins: readonly string[],
57
57
  framedBy: readonly string[] = [],
58
58
  ): string {
59
+ checkHostOrigins("nestedShellCsp", hostOrigins);
59
60
  const files = `${origin}${NESTED_FILES_PREFIX}`;
60
61
  const directives: CspDirective[] = [
61
62
  ["default-src", "'none'"],
@@ -1,5 +1,10 @@
1
1
  import { DOOR_SANDBOX_TOKENS } from "../compile/policy.ts";
2
- import { framedByProblem, includesOrigin, normalOrigin } from "../isolation/served.ts";
2
+ import {
3
+ framedByProblem,
4
+ hostOriginProblem,
5
+ includesOrigin,
6
+ normalOrigin,
7
+ } from "../isolation/served.ts";
3
8
  import { FRAME_STATUS_METHOD } from "../isolation/types.ts";
4
9
  import type { FrameBlock } from "../host/types.ts";
5
10
  import { base64url, sha256, utf8 } from "./crypto.ts";
@@ -32,8 +37,23 @@ const isStrict = (frameAncestors: string, hostOrigins: readonly string[]): boole
32
37
  const strictParent = (strict: boolean): string => (strict ? ' data-porthole-strict-parent=""' : "");
33
38
 
34
39
  /**
35
- * Who may frame a page: the host origins, then a host's `framedBy` (P141), each checked (they go
36
- * into a header).
40
+ * The host origins a helper was given, each checked as a config's are (`hostOriginProblem`, P145):
41
+ * they go into a header (`frame-ancestors`) and into the page's own list of whom it tells, and a
42
+ * content Worker of a host's own passes them here itself. `who` names the helper in the error.
43
+ */
44
+ export function checkHostOrigins(who: string, hostOrigins: readonly string[]): void {
45
+ for (const origin of hostOrigins) {
46
+ const problem = hostOriginProblem(origin);
47
+ if (problem !== null) {
48
+ throw new TypeError(`${who}: hostOrigins: ${problem}`);
49
+ }
50
+ }
51
+ }
52
+
53
+ /**
54
+ * Who may frame a page: the host origins, then a host's `framedBy` (P141), each `framedBy`
55
+ * checked here (they go into a header); the host origins by whoever was given them (a config's by
56
+ * `createServer`, a helper's by `checkHostOrigins`).
37
57
  */
38
58
  export function ancestorsOf(
39
59
  hostOrigins: readonly string[],
@@ -289,14 +309,19 @@ export interface EmbedPage {
289
309
 
290
310
  /** Whom a page tells, and who may frame it: the host origins' (P141), or an embed's (P143). */
291
311
  const framingOf = (
312
+ who: string,
292
313
  options: HostedPage | EmbedPage,
293
- ): { readonly hosts: readonly string[]; readonly ancestors: string } =>
294
- options.embed === true
295
- ? { hosts: [], ancestors: "*" }
296
- : {
297
- hosts: options.hostOrigins,
298
- ancestors: options.frameAncestors ?? ancestorsOf(options.hostOrigins, options.framedBy),
299
- };
314
+ ): { readonly hosts: readonly string[]; readonly ancestors: string } => {
315
+ if (options.embed === true) {
316
+ return { hosts: [], ancestors: "*" };
317
+ }
318
+ // Checked here too: with `frameAncestors` given, `ancestorsOf` never sees them.
319
+ checkHostOrigins(who, options.hostOrigins);
320
+ return {
321
+ hosts: options.hostOrigins,
322
+ ancestors: options.frameAncestors ?? ancestorsOf(options.hostOrigins, options.framedBy),
323
+ };
324
+ };
300
325
 
301
326
  /**
302
327
  * A page saying why a frame shows nothing, for a relay of the app's own (P072): told to the page
@@ -314,7 +339,7 @@ export function statusPageOf(
314
339
  readonly method?: string;
315
340
  } & (HostedPage | EmbedPage),
316
341
  ): Response {
317
- const { hosts, ancestors } = framingOf(options);
342
+ const { hosts, ancestors } = framingOf("statusPage", options);
318
343
  return appStatusPage(
319
344
  options.status,
320
345
  options.title,
@@ -372,6 +397,7 @@ export interface DoorOptions {
372
397
  * own ticket was taken and the checks the content's address runs passed for the same grant.
373
398
  */
374
399
  export function doorResponse(options: DoorOptions): Response {
400
+ checkHostOrigins("doorResponse", options.hostOrigins);
375
401
  const hosts = escape(JSON.stringify(options.hostOrigins));
376
402
  const ancestors = options.frameAncestors ?? ancestorsOf(options.hostOrigins, options.framedBy);
377
403
  const strict = isStrict(ancestors, options.hostOrigins);
@@ -401,7 +427,7 @@ export function doorStatusResponse(
401
427
  },
402
428
  ): Response {
403
429
  const { status, reason, code } = options;
404
- const framing = framingOf(options);
430
+ const framing = framingOf("doorStatusResponse", options);
405
431
  const hosts = escape(JSON.stringify(framing.hosts));
406
432
  const ancestors = framing.ancestors;
407
433
  const strict = isStrict(ancestors, framing.hosts);
@@ -28,6 +28,15 @@ import {
28
28
  * before the shell's next frame would turn its activation on as a press does). What it can't
29
29
  * see: a gesture while its activation is already on (within 5 s of the last one) turns nothing
30
30
  * on;
31
+ * - hears each real press in the page from the page's runtime (P148), over a `MessagePort` it makes
32
+ * at each load of the page's frame and sends down (`porthole/shell/press-port`): the runtime
33
+ * takes it before any content runs, and no content holds it. A message on it says only that
34
+ * there was a press; the shell notes when it heard it, on its own clock, tells the host in its
35
+ * state (how long ago, and how many it has heard), and then answers on the port, so what the
36
+ * page says next arrives after the state that says so. Only the port of the frame's last load is
37
+ * heard, and what was said of a press before it is forgotten; the port before is heard again
38
+ * only if the runtime that holds it says, on it, that its document is still there (WebKit fires
39
+ * a load for a navigation within the document, P142);
31
40
  * - renews the page's sealed files' address before it ends, and gives the page the new one
32
41
  * (`porthole/files-renewed`): the page's own loads aren't its origin's (an opaque origin's never
33
42
  * are), so only the shell, on that origin, may renew it (P083);
@@ -82,6 +91,63 @@ const frameShellRuntime = (strict: boolean): string => String.raw`(() => {
82
91
  frame.style.width = "100%";
83
92
  frame.style.height = "100%";
84
93
  frame.style.background = "transparent";
94
+ // The page's real presses (P148): when the last one was heard (null: none since the frame's last
95
+ // load), how many were heard in all, and the one port listened to.
96
+ let pressedAt = null;
97
+ let presses = 0;
98
+ let pressPort = null;
99
+ // The port a load set aside, until the next one: its document may still be there (below).
100
+ let asidePort = null;
101
+ const shut = (port) => {
102
+ if (port !== null) {
103
+ port.onmessage = null;
104
+ port.close();
105
+ }
106
+ };
107
+ const hear = (port) => {
108
+ port.onmessage = (event) => {
109
+ if (pressPort !== port || event.data !== 0) {
110
+ return;
111
+ }
112
+ pressedAt = performance.now();
113
+ presses += 1;
114
+ // To the host first, then the answer: what the page held back follows the state.
115
+ look(undefined, true);
116
+ port.postMessage(0);
117
+ };
118
+ };
119
+ frame.addEventListener("load", () => {
120
+ shut(asidePort);
121
+ const before = pressPort;
122
+ asidePort = before;
123
+ pressedAt = null;
124
+ const child = frame.contentWindow;
125
+ if (child === null || typeof MessageChannel !== "function") {
126
+ shut(before);
127
+ asidePort = null;
128
+ pressPort = null;
129
+ return;
130
+ }
131
+ const channel = new MessageChannel();
132
+ const port = channel.port1;
133
+ pressPort = port;
134
+ hear(port);
135
+ if (before !== null) {
136
+ // A load is a new document, whose runtime takes this port, and the one before is heard no
137
+ // more. But not every load is one: WebKit fires it for a navigation within the document
138
+ // (P142), whose runtime is still there and takes no second port. It says so (1) on the port
139
+ // it holds, which no one else can: that port is then the one again, and the new one is shut.
140
+ before.onmessage = (event) => {
141
+ if (event.data === 1 && pressPort === port && asidePort === before) {
142
+ shut(port);
143
+ asidePort = null;
144
+ pressPort = before;
145
+ hear(before);
146
+ }
147
+ };
148
+ }
149
+ child.postMessage({ jsonrpc: "2.0", method: PREFIX + "press-port" }, "*", [channel.port2]);
150
+ });
85
151
  frame.src = page.href;
86
152
  document.body.append(frame);
87
153
 
@@ -126,6 +192,9 @@ const frameShellRuntime = (strict: boolean): string => String.raw`(() => {
126
192
  ago: active ? Math.max(0, Math.round(performance.now() - since)) : null,
127
193
  focused,
128
194
  gap: Math.max(0, Math.round(gap)),
195
+ // The page's last real press (P148): how long ago the shell heard it, and how many so far.
196
+ pressed: pressedAt === null ? null : Math.max(0, Math.round(performance.now() - pressedAt)),
197
+ presses,
129
198
  };
130
199
  // The answer to the host's ask (P120), by its number.
131
200
  if (asked !== undefined) {
@@ -133,7 +202,7 @@ const frameShellRuntime = (strict: boolean): string => String.raw`(() => {
133
202
  }
134
203
  toHost({ jsonrpc: "2.0", method: PREFIX + "state", params });
135
204
  };
136
- const look = (asked) => {
205
+ const look = (asked, pressed) => {
137
206
  const now = performance.now();
138
207
  const gap = now - lookedAt;
139
208
  lookedAt = now;
@@ -151,7 +220,7 @@ const frameShellRuntime = (strict: boolean): string => String.raw`(() => {
151
220
  focused = inside;
152
221
  changed = true;
153
222
  }
154
- if (changed || typeof asked === "number") {
223
+ if (changed || pressed === true || typeof asked === "number") {
155
224
  tell(gap, typeof asked === "number" ? asked : undefined);
156
225
  } else if (now - toldAt >= 50) {
157
226
  // The heartbeat: the host knows the shell was looking, every 50 ms.
@@ -283,7 +352,11 @@ export const FRAME_SHELL_RUNTIME = frameShellRuntime(false);
283
352
  /** A strict shell's runtime (P141): its parent may be an outer page. */
284
353
  export const STRICT_FRAME_SHELL_RUNTIME = frameShellRuntime(true);
285
354
 
286
- export { SHELL_METHOD_PREFIX, SHELL_STATE_METHOD } from "../isolation/types.ts";
355
+ export {
356
+ SHELL_METHOD_PREFIX,
357
+ SHELL_PRESS_PORT_METHOD,
358
+ SHELL_STATE_METHOD,
359
+ } from "../isolation/types.ts";
287
360
 
288
361
  export interface FrameShellOptions {
289
362
  /** The host origins: the shell takes messages from its parent only from these. */
package/src/shell/plan.ts CHANGED
@@ -61,6 +61,11 @@ export interface ShellPlan {
61
61
  * those iframes and removes every other frame-like element. Absent: it removes them all.
62
62
  */
63
63
  readonly nestedFrames?: "own";
64
+ /**
65
+ * A nested page's (P148): its runtime tells its shell each real press, over the port the shell
66
+ * sends it. Absent for every other plan: their runtime listens for no port and tells no press.
67
+ */
68
+ readonly press?: true;
64
69
  }
65
70
 
66
71
  export function shellPlan(config: PortholeConfig): ShellPlan | null {
@@ -110,5 +115,7 @@ export function shellPlan(config: PortholeConfig): ShellPlan | null {
110
115
  protocolVersion: MCP_APPS_PROTOCOL_VERSION,
111
116
  // Only where opted into (P128): every other plan is the same as before it.
112
117
  ...(config.nestedFrames === "own" ? { nestedFrames: "own" as const } : {}),
118
+ // A nested page's alone (P148): every other plan is the same as before it.
119
+ ...(config.nested === true ? { press: true as const } : {}),
113
120
  };
114
121
  }