@botiverse/porthole 0.13.0 → 0.14.1

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.
Files changed (77) hide show
  1. package/CHANGELOG.md +770 -0
  2. package/dist/annotate/types.d.ts +36 -4
  3. package/dist/annotate/types.js +6 -0
  4. package/dist/annotate/validate.d.ts +2 -1
  5. package/dist/annotate/validate.js +30 -6
  6. package/dist/check/page-source.js +1 -1
  7. package/dist/compile/policy.d.ts +7 -0
  8. package/dist/compile/policy.js +13 -1
  9. package/dist/config/schema.d.ts +11 -0
  10. package/dist/config/validate.js +19 -0
  11. package/dist/conformance/harness-source.js +1 -1
  12. package/dist/displays/displays.js +3 -1
  13. package/dist/guide/limits.js +1 -1
  14. package/dist/host/create-host.d.ts +2 -0
  15. package/dist/host/create-host.js +78 -3
  16. package/dist/host/pass-on.d.ts +15 -0
  17. package/dist/host/pass-on.js +65 -0
  18. package/dist/host/types.d.ts +29 -0
  19. package/dist/index.d.ts +4 -1
  20. package/dist/index.js +4 -1
  21. package/dist/isolation/types.d.ts +8 -0
  22. package/dist/isolation/types.js +8 -0
  23. package/dist/platform/focus-guard.d.ts +71 -2
  24. package/dist/platform/focus-guard.js +187 -12
  25. package/dist/platform/types.d.ts +8 -1
  26. package/dist/platform/web.js +60 -4
  27. package/dist/presets/presets.d.ts +2 -0
  28. package/dist/presets/presets.js +1 -0
  29. package/dist/react/frame.d.ts +4 -3
  30. package/dist/server/files.js +19 -3
  31. package/dist/server/index.d.ts +1 -0
  32. package/dist/server/index.js +5 -0
  33. package/dist/server/naming.js +4 -0
  34. package/dist/server/nested.d.ts +59 -0
  35. package/dist/server/nested.js +96 -0
  36. package/dist/server/server.js +193 -23
  37. package/dist/server/types.d.ts +5 -0
  38. package/dist/shell/annotate.d.ts +4 -3
  39. package/dist/shell/annotate.js +179 -9
  40. package/dist/shell/frame.d.ts +45 -0
  41. package/dist/shell/frame.js +250 -0
  42. package/dist/shell/plan.js +2 -1
  43. package/dist/shell/runtime.d.ts +6 -0
  44. package/dist/shell/runtime.js +60 -15
  45. package/docs/ADOPTING.md +85 -2
  46. package/docs/ARCHITECTURE.md +28 -0
  47. package/docs/DECISIONS.md +416 -1
  48. package/docs/DESIGN.md +21 -4
  49. package/docs/THREAT_MODEL.md +102 -5
  50. package/package.json +6 -5
  51. package/src/annotate/types.ts +32 -4
  52. package/src/annotate/validate.ts +34 -8
  53. package/src/compile/policy.ts +14 -1
  54. package/src/config/schema.ts +11 -0
  55. package/src/config/validate.ts +23 -0
  56. package/src/displays/displays.ts +3 -1
  57. package/src/guide/limits.ts +1 -1
  58. package/src/host/create-host.ts +81 -4
  59. package/src/host/pass-on.ts +73 -0
  60. package/src/host/types.ts +27 -0
  61. package/src/index.ts +4 -1
  62. package/src/isolation/types.ts +12 -0
  63. package/src/platform/focus-guard.ts +258 -15
  64. package/src/platform/types.ts +8 -1
  65. package/src/platform/web.ts +81 -9
  66. package/src/presets/presets.ts +3 -0
  67. package/src/react/frame.tsx +4 -3
  68. package/src/server/files.ts +19 -3
  69. package/src/server/index.ts +14 -0
  70. package/src/server/naming.ts +4 -0
  71. package/src/server/nested.ts +116 -0
  72. package/src/server/server.ts +224 -21
  73. package/src/server/types.ts +5 -0
  74. package/src/shell/annotate.ts +179 -9
  75. package/src/shell/frame.ts +268 -0
  76. package/src/shell/plan.ts +2 -1
  77. package/src/shell/runtime.ts +61 -15
@@ -62,6 +62,50 @@ export const TAKES = {
62
62
  any: { most: 5, withinMs: 2_000 },
63
63
  } as const;
64
64
 
65
+ /**
66
+ * A nested page's shell (P111) says its own activation turned on: a press or key of the person's
67
+ * in that page (activation goes up to ancestors, never down, so nothing on the host's page turns
68
+ * it on). A move of focus into the frame within this long of it, with no press or key on the
69
+ * host's page since, is the person's; so is a `comments.open` the page sends within it.
70
+ */
71
+ export const SHELL_GESTURE_MS = 1_000;
72
+
73
+ /**
74
+ * How long a move into a nested page's frame waits for its shell's word before it is taken for
75
+ * the page's: the shell says what it saw at its next animation frame, after the host's page
76
+ * already heard the move. A shell that says nothing in time (gone, stalled) has its frame's move
77
+ * taken back, as any page's.
78
+ */
79
+ export const SHELL_WAIT_MS = 500;
80
+
81
+ /**
82
+ * A shell's word that came this long before the host's page heard the move is about that move
83
+ * (the shell's frame can come first); one from before then is about an earlier one.
84
+ */
85
+ export const SHELL_EARLY_MS = 150;
86
+
87
+ /**
88
+ * A shell that went this long without a look, or without a word to the host (its heartbeat is every
89
+ * 50 ms), was stalled (P111, after its review): where the page shares the shell's thread (WebKit,
90
+ * Firefox), a page that holds it from its own click handler pushes the moment the shell sees its
91
+ * activation turn on past the person's next keys on the host's page. An activation it saw then is
92
+ * uncertain: it is no one's gesture until it lapses.
93
+ */
94
+ export const SHELL_STALL_MS = 100;
95
+
96
+ /** What a nested page's shell last said (P111), on the host's clock. */
97
+ export interface ShellWord {
98
+ /** Whether its engine tells activation at all (`navigator.userActivation`). */
99
+ readonly supported: boolean;
100
+ /** When its activation last turned on; -Infinity if it hasn't, or is off. */
101
+ readonly activatedAt: number;
102
+ /** Whether it last said the page's focus is in it, and when it last said focus came in. */
103
+ readonly focused: boolean;
104
+ readonly focusedAt: number;
105
+ /** Its activation turned on while it was stalled: uncertain until it goes off (`SHELL_STALL_MS`). */
106
+ readonly uncertain?: boolean;
107
+ }
108
+
65
109
  /** One move of the keyboard the guard undid. */
66
110
  export interface FocusTake {
67
111
  /** The person pressed a key on the host's page within the last second. */
@@ -96,6 +140,11 @@ export interface FocusMove {
96
140
  readonly activation: boolean | undefined;
97
141
  /** The host moved focus into the frame itself (`DisplayHandle.focus()`), just now. */
98
142
  readonly hostMoved: boolean;
143
+ /**
144
+ * A nested page's frame (P111): what its shell said, and when the host's page last had a
145
+ * trusted press or key of its own. Absent for any other frame.
146
+ */
147
+ readonly shell?: { readonly word: ShellWord; readonly hostInputAt: number };
99
148
  }
100
149
 
101
150
  /**
@@ -122,6 +171,14 @@ export function personMoved(move: FocusMove): boolean {
122
171
  if (move.lastKey !== null && move.lastKey.key === "Tab" && move.now - move.lastKey.at <= TAB_MS) {
123
172
  return true;
124
173
  }
174
+ // A nested page (P111): its shell's activation turned on within the last second, and the host's
175
+ // page had no press or key of its own since (the person went back to it); or, where the engine
176
+ // tells it, a press on the frame. Nothing else: no pointer over it, no host-wide activation.
177
+ if (move.shell !== undefined && move.shell.word.supported) {
178
+ return (
179
+ (move.seen && move.pressed) || shellGesture(move.shell.word, move.shell.hostInputAt, move.now)
180
+ );
181
+ }
125
182
  if (
126
183
  move.seen ? move.pressed : move.over && move.overSince > Math.max(move.typedAt, move.focusedAt)
127
184
  ) {
@@ -133,6 +190,19 @@ export function personMoved(move: FocusMove): boolean {
133
190
  );
134
191
  }
135
192
 
193
+ /**
194
+ * Whether a nested page's shell saw the person's gesture just now (P111): its activation turned on
195
+ * within `SHELL_GESTURE_MS`, after the host's page's last trusted press or key.
196
+ */
197
+ export function shellGesture(word: ShellWord, hostInputAt: number, now: number): boolean {
198
+ return (
199
+ word.supported &&
200
+ now - word.activatedAt <= SHELL_GESTURE_MS &&
201
+ now >= word.activatedAt &&
202
+ hostInputAt < word.activatedAt
203
+ );
204
+ }
205
+
136
206
  /** Keys that type nothing on their own: they don't count as typing (a gesture still). */
137
207
  const MODIFIERS = new Set(["Shift", "Control", "Alt", "Meta", "AltGraph", "CapsLock", "Fn"]);
138
208
 
@@ -169,8 +239,30 @@ function deepActive(document: Document): Element | null {
169
239
 
170
240
  /** One page's guard, shared by every display's frame on it. */
171
241
  export interface FocusGuard {
172
- /** Guards `frame`: `taken` hears each move into it that was undone. */
173
- add(frame: HTMLIFrameElement, taken: (take: FocusTake) => void): () => void;
242
+ /**
243
+ * Guards `frame`: `taken` hears each move into it that was undone. `nested`: it holds a nested
244
+ * page's shell (P111), whose word (`shell`) decides the moves into it.
245
+ */
246
+ add(
247
+ frame: HTMLIFrameElement,
248
+ taken: (take: FocusTake) => void,
249
+ options?: { readonly nested?: boolean },
250
+ ): () => void;
251
+ /** What a nested page's shell said (P111): its activation, its focus. */
252
+ shell(
253
+ frame: HTMLIFrameElement,
254
+ said: {
255
+ readonly supported: boolean;
256
+ readonly ago: number | null;
257
+ readonly focused: boolean;
258
+ /** How long the shell went without a look before this one (its own clock). */
259
+ readonly gap: number;
260
+ },
261
+ ): void;
262
+ /** A nested page's shell's heartbeat (P111): it is looking. */
263
+ beat(frame: HTMLIFrameElement): void;
264
+ /** Whether a nested page's shell saw the person's gesture just now (`shellGesture`). */
265
+ gesture(frame: HTMLIFrameElement): boolean;
174
266
  /** The host moves focus into `frame` itself. */
175
267
  focus(frame: HTMLIFrameElement): void;
176
268
  /**
@@ -185,6 +277,10 @@ export interface FocusGuard {
185
277
  interface Guarded {
186
278
  readonly taken: Set<(take: FocusTake) => void>;
187
279
  overSince: number;
280
+ /** A nested page's shell's word (P111); null for any other frame. */
281
+ word: ShellWord | null;
282
+ /** When the host last heard the shell (a report or a heartbeat). */
283
+ heardAt: number;
188
284
  }
189
285
 
190
286
  const guards = new WeakMap<Window, FocusGuard>();
@@ -204,6 +300,20 @@ export function focusGuard(view: Window): FocusGuard {
204
300
  let typedAt = -Infinity;
205
301
  let gestureAt = -Infinity;
206
302
  let pressAt = -Infinity;
303
+ /** The host's page's last trusted press or key (P111: a nested page's gesture must be later). */
304
+ let inputAt = -Infinity;
305
+ /**
306
+ * A move into a nested page's frame waiting for its shell's word (P111): from a text field
307
+ * (`field`: taken back unless the shell says the person's), or from anything else (null: only
308
+ * whether the frame is the person's for a gesture gate).
309
+ */
310
+ let waiting: {
311
+ readonly field: HTMLElement | null;
312
+ readonly frame: HTMLIFrameElement;
313
+ readonly guarded: Guarded;
314
+ readonly since: number;
315
+ readonly failed: boolean;
316
+ } | null = null;
207
317
  /** When focus last went into a guarded frame, and whether the person moved it there. */
208
318
  let enteredAt = -Infinity;
209
319
  let earned = false;
@@ -238,13 +348,17 @@ export function focusGuard(view: Window): FocusGuard {
238
348
  }
239
349
  };
240
350
 
241
- /** What the person's move would need, read now: see `personMoved`. */
351
+ /**
352
+ * What the person's move would need, read now: see `personMoved`. Into a nested page's frame
353
+ * whose shell hasn't spoken of this move yet, `wait` (P111).
354
+ */
242
355
  const judge = (
243
356
  frame: HTMLIFrameElement,
244
357
  guarded: Guarded,
245
358
  seen: boolean,
246
359
  at: number,
247
- ): boolean => {
360
+ ): boolean | "wait" => {
361
+ const word = guarded.word;
248
362
  const moved = personMoved({
249
363
  now: at,
250
364
  seen,
@@ -257,11 +371,66 @@ export function focusGuard(view: Window): FocusGuard {
257
371
  gestureAt,
258
372
  activation: activation(),
259
373
  hostMoved: hostMove !== null && hostMove.frame === frame && at - hostMove.at <= TAB_MS,
374
+ ...(word === null ? {} : { shell: { word, hostInputAt: inputAt } }),
260
375
  });
261
376
  hostMove = null;
377
+ // The shell tells a move at its next frame, the host's page hears it first: until the shell
378
+ // said focus came in (around now), its activation may be on its way.
379
+ if (!moved && word !== null && word.supported && word.focusedAt < at - SHELL_EARLY_MS) {
380
+ return "wait";
381
+ }
262
382
  return moved;
263
383
  };
264
384
 
385
+ /** Waits for a nested page's shell's word on a move (P111): decided by `settle`. */
386
+ const wait = (
387
+ field: HTMLElement | null,
388
+ frame: HTMLIFrameElement,
389
+ guarded: Guarded,
390
+ at: number,
391
+ failed: boolean,
392
+ ) => {
393
+ waiting = { field, frame, guarded, since: at, failed };
394
+ known = frame;
395
+ enteredAt = at;
396
+ earned = false;
397
+ schedule();
398
+ };
399
+
400
+ /**
401
+ * A waiting move, once its shell spoke or the wait is over: the person's (the frame keeps
402
+ * focus), or the page's (from a text field, taken back). A move elsewhere since ends it.
403
+ */
404
+ const settle = (at: number) => {
405
+ const held = waiting;
406
+ if (held === null) {
407
+ return;
408
+ }
409
+ const { field, frame, guarded } = held;
410
+ if (deepActive(document) !== frame || !frames.has(frame)) {
411
+ // Moved on since: from the frame, as the next look judges it.
412
+ waiting = null;
413
+ known = frame;
414
+ return;
415
+ }
416
+ const word = guarded.word;
417
+ const theirs = word !== null && shellGesture(word, inputAt, at);
418
+ const spoke = word !== null && word.focusedAt >= held.since - SHELL_EARLY_MS;
419
+ if (theirs) {
420
+ waiting = null;
421
+ known = frame;
422
+ earned = true;
423
+ return;
424
+ }
425
+ if (!spoke && at - held.since < SHELL_WAIT_MS) {
426
+ return;
427
+ }
428
+ waiting = null;
429
+ if (field !== null && field.isConnected) {
430
+ takeBack(field, frame, guarded, at, held.failed);
431
+ }
432
+ };
433
+
265
434
  /**
266
435
  * Focus goes back to `field` once the engine has finished the move: given back inside its blur
267
436
  * it stays with the frame on Chromium and WebKit, and Firefox takes it back only from a frame
@@ -339,12 +508,23 @@ export function focusGuard(view: Window): FocusGuard {
339
508
  contest = null;
340
509
  return false;
341
510
  }
342
- if (active === frame && judge(frame, guarded, seen, at)) {
343
- contest = null;
344
- known = frame;
345
- enteredAt = at;
346
- earned = true;
347
- return true;
511
+ if (active === frame) {
512
+ const verdict = judge(frame, guarded, seen, at);
513
+ if (verdict === true) {
514
+ contest = null;
515
+ known = frame;
516
+ enteredAt = at;
517
+ earned = true;
518
+ return true;
519
+ }
520
+ if (verdict === "wait") {
521
+ // A nested page's frame took it again (P111): its shell decides, as it would at first.
522
+ if (watched.heldSince !== null || at - watched.gaveAt >= GIVE_BACK_MS) {
523
+ contest = null;
524
+ wait(field, frame, guarded, at, true);
525
+ }
526
+ return true;
527
+ }
348
528
  }
349
529
  // Taken again once it was back (within `HELD_MS`), or not back yet after `GIVE_BACK_MS`: a
350
530
  // take-back that failed, given again and counted.
@@ -358,6 +538,10 @@ export function focusGuard(view: Window): FocusGuard {
358
538
  const look = (seen: boolean) => {
359
539
  const active = deepActive(document);
360
540
  const at = now();
541
+ if (waiting !== null) {
542
+ settle(at);
543
+ return;
544
+ }
361
545
  if (watch(seen, active, at)) {
362
546
  return;
363
547
  }
@@ -393,7 +577,13 @@ export function focusGuard(view: Window): FocusGuard {
393
577
  // From a text field it is judged below; from anything else it is let be, but only the
394
578
  // person's own move makes the frame theirs for a gesture gate (`focused`).
395
579
  enteredAt = at;
396
- earned = takesText(was) || judge(active as HTMLIFrameElement, entered, seen, at);
580
+ const verdict = takesText(was) || judge(active as HTMLIFrameElement, entered, seen, at);
581
+ if (verdict === "wait") {
582
+ // A nested page's (P111): theirs once its shell says so; nothing to take back.
583
+ wait(null, active as HTMLIFrameElement, entered, at, false);
584
+ return;
585
+ }
586
+ earned = verdict;
397
587
  }
398
588
  // Into a text field from a display's frame (the person pressed the composer while the frame
399
589
  // had focus): watched as a take-back is, since a page that takes focus back on its own blur
@@ -414,7 +604,12 @@ export function focusGuard(view: Window): FocusGuard {
414
604
  return;
415
605
  }
416
606
  const frame = active as HTMLIFrameElement;
417
- if (judge(frame, guarded, seen, at)) {
607
+ const verdict = judge(frame, guarded, seen, at);
608
+ if (verdict === true) {
609
+ return;
610
+ }
611
+ if (verdict === "wait") {
612
+ wait(was, frame, guarded, at, false);
418
613
  return;
419
614
  }
420
615
  takeBack(was, frame, guarded, at, false);
@@ -431,7 +626,7 @@ export function focusGuard(view: Window): FocusGuard {
431
626
  schedule();
432
627
  };
433
628
  const schedule = () => {
434
- if (polling === 0 && (frames.size > 0 || contest !== null)) {
629
+ if (polling === 0 && (frames.size > 0 || contest !== null || waiting !== null)) {
435
630
  polling = view.requestAnimationFrame(poll);
436
631
  }
437
632
  };
@@ -441,6 +636,9 @@ export function focusGuard(view: Window): FocusGuard {
441
636
  };
442
637
  const press = (event: Event) => {
443
638
  pressAt = now();
639
+ if (event.isTrusted) {
640
+ inputAt = pressAt;
641
+ }
444
642
  gestureAt = pressAt;
445
643
  const target = event.composedPath()[0];
446
644
  pressed =
@@ -454,6 +652,9 @@ export function focusGuard(view: Window): FocusGuard {
454
652
  const at = now();
455
653
  gestureAt = at;
456
654
  lastKey = { key: event.key, at };
655
+ if (event.isTrusted) {
656
+ inputAt = at;
657
+ }
457
658
  if (event.key !== "Tab" && !MODIFIERS.has(event.key)) {
458
659
  typedAt = at;
459
660
  }
@@ -502,10 +703,18 @@ export function focusGuard(view: Window): FocusGuard {
502
703
  );
503
704
 
504
705
  const guard: FocusGuard = {
505
- add(frame, taken) {
706
+ add(frame, taken, options) {
506
707
  let guarded = frames.get(frame);
507
708
  if (guarded === undefined) {
508
- const entry: Guarded = { taken: new Set(), overSince: -Infinity };
709
+ const entry: Guarded = {
710
+ taken: new Set(),
711
+ overSince: -Infinity,
712
+ heardAt: -Infinity,
713
+ word:
714
+ options?.nested === true
715
+ ? { supported: true, activatedAt: -Infinity, focused: false, focusedAt: -Infinity }
716
+ : null,
717
+ };
509
718
  frame.addEventListener("pointerover", () => {
510
719
  entry.overSince = now();
511
720
  });
@@ -522,6 +731,40 @@ export function focusGuard(view: Window): FocusGuard {
522
731
  }
523
732
  };
524
733
  },
734
+ shell(frame, said) {
735
+ const guarded = frames.get(frame);
736
+ const before = guarded?.word ?? null;
737
+ if (guarded === undefined || before === null) {
738
+ return;
739
+ }
740
+ const at = now();
741
+ // Off to on after a stall, the shell's or the host's (no word for longer than its beat
742
+ // allows): uncertain, and so until it goes off (P111, after its review).
743
+ const turnedOn = said.ago !== null && before.activatedAt === -Infinity && !before.uncertain;
744
+ const stalled = said.gap > SHELL_STALL_MS || at - guarded.heardAt > SHELL_STALL_MS;
745
+ const uncertain = said.ago !== null && (before.uncertain === true || (turnedOn && stalled));
746
+ guarded.heardAt = at;
747
+ guarded.word = {
748
+ supported: said.supported,
749
+ activatedAt: said.ago === null || uncertain ? -Infinity : at - said.ago,
750
+ focused: said.focused,
751
+ focusedAt: said.focused && !before.focused ? at : before.focusedAt,
752
+ ...(uncertain ? { uncertain: true } : {}),
753
+ };
754
+ if (waiting?.frame === frame) {
755
+ settle(at);
756
+ }
757
+ },
758
+ beat(frame) {
759
+ const guarded = frames.get(frame);
760
+ if (guarded !== undefined && guarded.word !== null) {
761
+ guarded.heardAt = now();
762
+ }
763
+ },
764
+ gesture(frame) {
765
+ const word = frames.get(frame)?.word ?? null;
766
+ return word !== null && shellGesture(word, inputAt, now());
767
+ },
525
768
  focus(frame) {
526
769
  hostMove = { frame, at: now() };
527
770
  frame.focus();
@@ -24,6 +24,12 @@ export interface SurfaceSpec {
24
24
  readonly fill?: boolean;
25
25
  /** The height to start at (a remembered height, so a frame mounting again doesn't jump). */
26
26
  readonly initialHeightPx: number;
27
+ /**
28
+ * The frame holds a nested page's shell (P111): the host's config says so, never the frame. What
29
+ * the shell says of itself (`porthole/shell/state`) decides moves of focus into it and the
30
+ * gesture its page's calls need; nothing else in that namespace reaches the transport.
31
+ */
32
+ readonly nested?: boolean;
27
33
  }
28
34
 
29
35
  /** One isolated frame. */
@@ -49,7 +55,8 @@ export interface Surface {
49
55
  /**
50
56
  * Whether the embedding page's focus is in this frame now, once the platform's focus guard
51
57
  * judged any move into it (P109); undefined, or absent, where the platform can't tell. A gesture
52
- * gate that asks for the person in the calling frame (`comments`) reads it: false refuses.
58
+ * gate that asks for the person in the calling frame (`comments`) reads it: false refuses. A
59
+ * nested page's frame (P111) is the person's too while its shell saw their gesture just now.
53
60
  */
54
61
  focused?(): boolean | undefined;
55
62
  /**
@@ -1,7 +1,13 @@
1
1
  import type { ColorScheme } from "../config/schema.ts";
2
- import { FRAME_STATUS_METHOD } from "../isolation/types.ts";
2
+ import {
3
+ FRAME_STATUS_METHOD,
4
+ SHELL_BEAT_METHOD,
5
+ SHELL_METHOD_PREFIX,
6
+ SHELL_STATE_METHOD,
7
+ } from "../isolation/types.ts";
3
8
  import { postMessageTransport } from "../transport/post-message.ts";
4
- import { focusGuard, type FocusTake } from "./focus-guard.ts";
9
+ import { focusGuard, type FocusGuard, type FocusTake } from "./focus-guard.ts";
10
+ import type { Transport } from "../transport/types.ts";
5
11
  import type { PlatformHost, Surface, SurfaceSpec } from "./types.ts";
6
12
 
7
13
  /** A frame-status message (`porthole/notifications/frame-status`), by its method alone. */
@@ -11,6 +17,63 @@ const isFrameStatus = (data: unknown): boolean =>
11
17
  (data as { jsonrpc?: unknown }).jsonrpc === "2.0" &&
12
18
  (data as { method?: unknown }).method === FRAME_STATUS_METHOD;
13
19
 
20
+ /** A shell's own message (P111), by its namespace. */
21
+ const isShellWord = (data: unknown): data is { method: string; params?: unknown } =>
22
+ data !== null &&
23
+ typeof data === "object" &&
24
+ typeof (data as { method?: unknown }).method === "string" &&
25
+ (data as { method: string }).method.startsWith(SHELL_METHOD_PREFIX);
26
+
27
+ /**
28
+ * A nested page's transport (P111): the shell's state, checked, to the focus guard; the rest of
29
+ * the shell's namespace dropped; everything else as it came.
30
+ */
31
+ function shellWords(opened: Transport, frame: HTMLIFrameElement, guard: FocusGuard): Transport {
32
+ const listeners = new Set<(message: unknown) => void>();
33
+ opened.listen((message) => {
34
+ if (!isShellWord(message)) {
35
+ for (const listener of listeners) {
36
+ listener(message);
37
+ }
38
+ return;
39
+ }
40
+ const params = message.params;
41
+ if (params === null || typeof params !== "object") {
42
+ return;
43
+ }
44
+ const { supported, ago, focused, gap } = params as Record<string, unknown>;
45
+ const span = (value: unknown) =>
46
+ typeof value === "number" && Number.isFinite(value) && value >= 0;
47
+ if (message.method === SHELL_BEAT_METHOD) {
48
+ if (span(gap)) {
49
+ guard.beat(frame);
50
+ }
51
+ return;
52
+ }
53
+ if (
54
+ message.method !== SHELL_STATE_METHOD ||
55
+ typeof supported !== "boolean" ||
56
+ typeof focused !== "boolean" ||
57
+ !(ago === null || span(ago)) ||
58
+ !span(gap)
59
+ ) {
60
+ return;
61
+ }
62
+ guard.shell(frame, { supported, ago: ago as number | null, focused, gap: gap as number });
63
+ });
64
+ return {
65
+ send: (message) => opened.send(message),
66
+ listen(listener) {
67
+ listeners.add(listener);
68
+ return () => listeners.delete(listener);
69
+ },
70
+ close() {
71
+ listeners.clear();
72
+ opened.close();
73
+ },
74
+ };
75
+ }
76
+
14
77
  /**
15
78
  * The web platform: an `<iframe>` whose policy attributes are set before its document is given,
16
79
  * talking over `postMessage`. Its first load is the document it was given; any later load is the
@@ -67,15 +130,20 @@ export const webPlatform: PlatformHost = {
67
130
  // fields that the person didn't make is undone.
68
131
  const guard = focusGuard(view);
69
132
  const taken = new Set<(take: FocusTake) => void>();
70
- const unguard = guard.add(frame, (take) => {
71
- for (const listener of taken) {
72
- listener(take);
73
- }
74
- });
133
+ const nested = spec.nested === true && spec.source.kind === "url";
134
+ const unguard = guard.add(
135
+ frame,
136
+ (take) => {
137
+ for (const listener of taken) {
138
+ listener(take);
139
+ }
140
+ },
141
+ { nested },
142
+ );
75
143
  // A served frame may pass through the host's own pages (a redirect entry's, P068): what they
76
144
  // say of the frame's status is heard too, and nothing else from there.
77
145
  const own = view.origin;
78
- const transport = postMessageTransport(
146
+ const opened = postMessageTransport(
79
147
  () => frame.contentWindow,
80
148
  origin,
81
149
  view,
@@ -83,6 +151,10 @@ export const webPlatform: PlatformHost = {
83
151
  ? undefined
84
152
  : { origin: own, accept: isFrameStatus },
85
153
  );
154
+ // A nested page's shell (P111): its own words go to the guard, by the frame's window and the
155
+ // content origin (the transport's checks); the page's pass on. The shell drops any page
156
+ // message in its namespace, so there none is the page's.
157
+ const transport = nested ? shellWords(opened, frame, guard) : opened;
86
158
  return {
87
159
  transport,
88
160
  element: frame,
@@ -111,7 +183,7 @@ export const webPlatform: PlatformHost = {
111
183
  return activation === undefined ? undefined : activation.isActive;
112
184
  },
113
185
  focused() {
114
- return guard.focused(frame);
186
+ return guard.focused(frame) || (nested && guard.gesture(frame));
115
187
  },
116
188
  onFocusTaken(listener) {
117
189
  taken.add(listener);
@@ -56,6 +56,8 @@ export interface PresetOptions {
56
56
  * be offered the runtime's own (`user`, `comments`, `artifact`, `assets`, `db`).
57
57
  */
58
58
  readonly runtime?: RuntimeVersion;
59
+ /** Domain isolation, artifact pages: the page in an opaque child of Porthole's shell (P111). */
60
+ readonly nested?: true;
59
61
  }
60
62
 
61
63
  /** What a live widget may say about a capability (P103): anything but origins of its own. */
@@ -241,6 +243,7 @@ function build(
241
243
  ...(options.storage === undefined ? {} : { storage: options.storage }),
242
244
  ...(options.errors === undefined ? {} : { errors: options.errors }),
243
245
  ...(options.runtime === undefined ? {} : { runtime: options.runtime }),
246
+ ...(options.nested === undefined ? {} : { nested: options.nested }),
244
247
  });
245
248
  }
246
249
 
@@ -500,10 +500,11 @@ export interface PortholeFrameProps {
500
500
  readonly instance?: InstanceRef;
501
501
  /**
502
502
  * What the page declared (P086), as the host stored it with the artifact: the capabilities it
503
- * reaches through `porthole.use`, and its pinned runtime. By value: a change makes the display
504
- * again.
503
+ * reaches through `porthole.use`, and its pinned runtime. Under `config.runtime`, `null` says
504
+ * the page was published before 0.7 and has 0.6's surface (`MountOptions.declaration`). By
505
+ * value: a change makes the display again.
505
506
  */
506
- readonly declaration?: PageDeclaration;
507
+ readonly declaration?: PageDeclaration | null;
507
508
  /**
508
509
  * Who is viewing (P087), for an opaque frame or one whose issue gave none. By value: a change
509
510
  * makes the display again.
@@ -11,6 +11,7 @@ import { DEFAULT_ENTRY, lookupFile, requestFilePath, type FileLookup } from "../
11
11
  import { fileTypeOf } from "../files/types.ts";
12
12
  import { isCodeAsset } from "../runtime/requests.ts";
13
13
  import { sha256, utf8 } from "./crypto.ts";
14
+ import { NESTED_FILE_HEADERS } from "./nested.ts";
14
15
  import type { FileBody, StoredAsset, StoredFiles } from "./types.ts";
15
16
 
16
17
  /**
@@ -226,6 +227,8 @@ export async function serveFile(serving: FileServing): Promise<Response> {
226
227
  return nothing(serving, 404, method);
227
228
  }
228
229
  const { type, role } = fileTypeOf(found.path);
230
+ // A nested page (P111): in its shell's child, an opaque origin.
231
+ const nested = serving.compiled.config.nested === true;
229
232
  // In a frame, the version's files are at a sealed address (P083), which their own loads of the
230
233
  // artifact's assets carry as their `Referer` (P091): to this origin only, never another.
231
234
  const referrer =
@@ -242,12 +245,18 @@ export async function serveFile(serving: FileServing): Promise<Response> {
242
245
  // A page and a script (a worker's policy is its script's) get the page's CSP, a page with its
243
246
  // frame's sandbox, on a tab of its own too (P099); anything else runs nothing when opened on
244
247
  // its own.
248
+ // A nested page's files are on its shell's origin (P111, after the review): every one carries a
249
+ // sandbox, so none opened as a document on its own (a tab, "open image in new tab") runs on that
250
+ // origin. Pages run their scripts, opaque; anything else runs nothing (a file's is inert already,
251
+ // a script's gets one too).
245
252
  const csp =
246
253
  role === "file"
247
254
  ? INERT_FILE_CSP
248
255
  : role === "page"
249
256
  ? servedDocumentCsp(serving.compiled.config, directives)
250
- : serializeCsp(directives);
257
+ : nested
258
+ ? `${serializeCsp(directives)}; sandbox`
259
+ : serializeCsp(directives);
251
260
  const headers = new Headers({
252
261
  "content-type": type,
253
262
  "x-content-type-options": "nosniff",
@@ -263,7 +272,8 @@ export async function serveFile(serving: FileServing): Promise<Response> {
263
272
  if (role === "page") {
264
273
  // Every page of the set in the shell (P081): its hardening, its host functions, its theme.
265
274
  const html = serving.compiled.shellDocument({
266
- origins: serving.hostOrigins,
275
+ // A nested page hears its shell, on its own origin, never the host (P111).
276
+ origins: nested ? [serving.origin] : serving.hostOrigins,
267
277
  document: await textOf(body),
268
278
  cspMeta: false,
269
279
  ...(referrer === "same-origin" ? { referrer } : {}),
@@ -303,8 +313,14 @@ export async function serveFile(serving: FileServing): Promise<Response> {
303
313
  serving.pinned ? `private, max-age=${YEAR}, immutable` : "private, no-cache",
304
314
  );
305
315
  // Only this origin's own pages load it: no other content origin (a sibling, same-site without
306
- // the public suffix list) can embed it with the viewer's cookie.
316
+ // the public suffix list) can embed it with the viewer's cookie. A nested page's origin is
317
+ // opaque, and its files carry their access in their path, never a cookie (P111).
307
318
  headers.set("cross-origin-resource-policy", "same-origin");
319
+ if (nested) {
320
+ for (const [name, value] of Object.entries(NESTED_FILE_HEADERS)) {
321
+ headers.set(name, value);
322
+ }
323
+ }
308
324
  headers.set("accept-ranges", "bytes");
309
325
  if (role === "file" && type === "application/octet-stream") {
310
326
  headers.set("content-disposition", "attachment");
@@ -70,6 +70,20 @@ export {
70
70
  type D1StatementLike,
71
71
  } from "./tickets.ts";
72
72
  export { FRAME_STATUS_METHOD } from "../isolation/types.ts";
73
+ // A nested page (P111): Porthole's shell at the framed address, the page and its files below the
74
+ // sealed prefix, all on the shell's own label (P114, `nestedLabelOf`). `/server` serves them for a
75
+ // config with `nested`; a content Worker of its own answers the same (docs/ADOPTING.md, "Nested
76
+ // pages").
77
+ export {
78
+ isNestedLabel,
79
+ NESTED_FILE_HEADERS,
80
+ NESTED_FILES_PREFIX,
81
+ nestedAncestors,
82
+ nestedLabelOf,
83
+ nestedShellCsp,
84
+ nestedShellResponse,
85
+ PORTHOLE_LABEL_PREFIX,
86
+ } from "./nested.ts";
73
87
  export { isHostLabel, prefixedName, type Naming } from "./naming.ts";
74
88
  // The page an app serves in conformance test mode (P071).
75
89
  export { conformancePage } from "../conformance/page.ts";
@@ -42,6 +42,10 @@ export function prefixedName(prefix: string): Naming & {
42
42
  "A name prefix is a lowercase letter, then letters or digits, then '-' (a-)",
43
43
  );
44
44
  }
45
+ // Porthole's own labels (a nested page's shell's, P114) are never a scope's.
46
+ if (prefix === "porthole-") {
47
+ throw new TypeError("The name prefix porthole- is Porthole's own: choose another (a-)");
48
+ }
45
49
  const name = (scope: string): string => {
46
50
  const label = `${prefix}${scope}`;
47
51
  if (!ID.test(scope) || !isHostLabel(label)) {