@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.
@@ -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);
@@ -414,7 +414,37 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
414
414
  // The selection the host follows (P138) is drawn as what is picked is: an element in the
415
415
  // picking outline, a little lighter and without its name; words with a light fill and a line
416
416
  // under them, in the same blue, apart from the marks' yellow (no comment is there yet).
417
- 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}";
417
+ 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)))}}}";
418
+ // The marks ride the document's own scroll (P147). The layer stays fixed and clipped to the
419
+ // viewport, so it adds nothing to what the page can scroll; inside it one box holds every
420
+ // mark, marker and outline at its place in the document (its top plus how far the document
421
+ // is scrolled), and a scroll-driven animation moves that box up by the scroll. The engine
422
+ // runs it with the scroll itself, so a mark is where its words are in every frame, not a
423
+ // frame behind (a scroll event is heard after the frame it scrolled). Down the page only:
424
+ // sideways, and where the engine has no scroll timeline (ridden: 0), a mark is placed in the
425
+ // viewport and follows from the scroll event as before. Read with the DOM's own getters,
426
+ // taken before content runs; the range is what the timeline runs over (0: it is inactive,
427
+ // and nothing moves).
428
+ const rides = typeof CSS === "object" && CSS !== null && typeof CSS.supports === "function" && CSS.supports("animation-timeline: scroll()");
429
+ const scrollerOf = getterOf(Document.prototype, "scrollingElement");
430
+ const scrollTopOf = getterOf(Element.prototype, "scrollTop");
431
+ const scrollHeightOf = getterOf(Element.prototype, "scrollHeight");
432
+ const clientHeightOf = getterOf(Element.prototype, "clientHeight");
433
+ // How far down the document is scrolled as the marks are drawn, and how far it can be.
434
+ let ridden = 0;
435
+ const rideOf = () => {
436
+ const none = { by: 0, range: 0 };
437
+ if (!rides || scrollerOf === null || scrollTopOf === null || scrollHeightOf === null || clientHeightOf === null) {
438
+ return none;
439
+ }
440
+ const scroller = callOf(scrollerOf, document, []);
441
+ if (!scroller) {
442
+ return none;
443
+ }
444
+ const range = callOf(scrollHeightOf, scroller, []) - callOf(clientHeightOf, scroller, []);
445
+ const by = callOf(scrollTopOf, scroller, []);
446
+ return range > 0 && by >= 0 && by <= range + 1 ? { by, range } : none;
447
+ };
418
448
  // Inline and important: the content's own style sheets can't hide, shrink or move it by
419
449
  // accident. Set again at each draw, since its scripts can rewrite it (narrowing only: the
420
450
  // content can still cover the layer, or move it with its ancestors, P104). Clipped, where an
@@ -792,7 +822,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
792
822
  // button: Safari's Tab skips a button without one, unless the person asked otherwise.
793
823
  marker.tabIndex = mode.elements ? -1 : 0;
794
824
  marker.className = "marker" + (mark.draft ? " draft" : "") + (each.compact ? " compact" : "") + (mark.id === active ? " active" : "") + (mode.elements ? " inert" : "");
795
- marker.style.cssText = "left:" + each.left + "px;top:" + each.top + "px";
825
+ marker.style.cssText = "left:" + each.left + "px;top:" + (each.top + ridden) + "px";
796
826
  markers.push({ id: mark.id, element: marker });
797
827
  const name = nameOf(mark);
798
828
  const form = (mark.draft ? "draft:" : "") + (each.compact ? "compact:" : "full:") + label + ":" + name;
@@ -839,17 +869,19 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
839
869
  // the pointer's arrival on a marker lit its mark and redrew).
840
870
  let boxes = null;
841
871
  const boxesOf = (root) => {
842
- if (boxes === null || boxes.style.parentNode !== root || boxes.marks.parentNode !== root || boxes.markers.parentNode !== root || boxes.hover.parentNode !== root) {
872
+ 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) {
843
873
  const style = createElement.call(document, "style");
844
874
  if (nonce !== "") {
845
875
  style.nonce = nonce;
846
876
  }
847
- boxes = { style, marks: createElement.call(document, "div"), markers: createElement.call(document, "div"), hover: createElement.call(document, "div") };
877
+ boxes = { style, ride: createElement.call(document, "div"), marks: createElement.call(document, "div"), markers: createElement.call(document, "div"), hover: createElement.call(document, "div") };
878
+ boxes.ride.className = "ride";
848
879
  // Only the markers are for assistive technology (P133): the rest draws what the page
849
880
  // already says.
850
881
  boxes.marks.setAttribute("aria-hidden", "true");
851
882
  boxes.hover.setAttribute("aria-hidden", "true");
852
- root.replaceChildren(boxes.style, boxes.marks, boxes.markers, boxes.hover);
883
+ boxes.ride.replaceChildren(boxes.marks, boxes.markers, boxes.hover);
884
+ root.replaceChildren(boxes.style, boxes.ride);
853
885
  }
854
886
  if (boxes.style.textContent !== STYLE) {
855
887
  boxes.style.textContent = STYLE;
@@ -867,6 +899,10 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
867
899
  const into = boxesOf(root);
868
900
  const parts = [];
869
901
  const flashOn = Date.now() < flashUntil;
902
+ // Read with the boxes, in this one task: a place in the document is a box's top in the
903
+ // viewport plus this.
904
+ const ride = rideOf();
905
+ ridden = ride.by;
870
906
  // What is measured first, then drawn: no node of the layer changes while the page is read.
871
907
  const corners = [];
872
908
  const wanted = [];
@@ -883,7 +919,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
883
919
  }
884
920
  const each = createElement.call(document, "div");
885
921
  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" : "");
886
- each.style.cssText = "left:" + rect.left + "px;top:" + rect.top + "px;width:" + rect.width + "px;height:" + rect.height + "px";
922
+ each.style.cssText = "left:" + rect.left + "px;top:" + (rect.top + ridden) + "px;width:" + rect.width + "px;height:" + rect.height + "px";
887
923
  parts.push(each);
888
924
  }
889
925
  if (mark.marker) {
@@ -969,7 +1005,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
969
1005
  }
970
1006
  const each = createElement.call(document, "div");
971
1007
  each.className = lit.range ? "held text" : "held";
972
- each.style.cssText = "left:" + rect.left + "px;top:" + rect.top + "px;width:" + rect.width + "px;height:" + rect.height + "px";
1008
+ each.style.cssText = "left:" + rect.left + "px;top:" + (rect.top + ridden) + "px;width:" + rect.width + "px;height:" + rect.height + "px";
973
1009
  outlines.push(each);
974
1010
  }
975
1011
  }
@@ -977,13 +1013,18 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
977
1013
  const rect = elementRect.call(hover);
978
1014
  const outline = createElement.call(document, "div");
979
1015
  outline.className = "hover";
980
- outline.style.cssText = "left:" + rect.left + "px;top:" + rect.top + "px;width:" + rect.width + "px;height:" + rect.height + "px";
1016
+ outline.style.cssText = "left:" + rect.left + "px;top:" + (rect.top + ridden) + "px;width:" + rect.width + "px;height:" + rect.height + "px";
981
1017
  const tag = createElement.call(document, "div");
982
1018
  tag.className = "tag";
983
1019
  tag.textContent = describe(hover).slice(0, 80);
984
- tag.style.cssText = "left:" + Math.max(4, rect.left) + "px;top:" + (rect.top >= 24 ? rect.top - 22 : Math.max(4, rect.bottom + 4)) + "px";
1020
+ 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";
985
1021
  outlines.push(outline, tag);
986
1022
  }
1023
+ // How far the ride goes, for the animation; set only when it changed.
1024
+ const range = String(ride.range);
1025
+ if (into.ride.style.getPropertyValue("--ride") !== range) {
1026
+ into.ride.style.setProperty("--ride", range);
1027
+ }
987
1028
  into.marks.replaceChildren(...parts);
988
1029
  for (const child of Array.from(into.markers.childNodes)) {
989
1030
  if (badges.indexOf(child) === -1) {
@@ -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
  }