@botiverse/porthole 0.14.3 → 0.14.4

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.
@@ -27,6 +27,28 @@ export function parseOrigin(origin: string): ParsedOrigin | null {
27
27
  return { scheme, host, port: port ?? DEFAULT_PORTS[scheme] ?? "" };
28
28
  }
29
29
 
30
+ /**
31
+ * The start of every label Porthole serves for itself on a content domain (P114): no host's naming
32
+ * may make one (`content.name` is refused one, and `prefixedName` won't take the prefix).
33
+ */
34
+ export const PORTHOLE_LABEL_PREFIX = "porthole-";
35
+
36
+ const NESTED_LABEL = /^porthole-[a-z2-7]{24}$/u;
37
+
38
+ /** Whether a label is a nested page's shell's own (P114, `nestedLabelOf`'s form). */
39
+ export const isNestedLabel = (label: string): boolean => NESTED_LABEL.test(label);
40
+
41
+ /**
42
+ * Whether `origin` is on a nested page's shell's own label (P114): its host's first label is one.
43
+ * The shell runs nowhere else (P121): the host's mount, the shell itself and `/server`'s helpers
44
+ * each refuse any other origin, so a content Worker of a host's own can't put it beside other
45
+ * content by mistake.
46
+ */
47
+ export function onNestedLabel(origin: string): boolean {
48
+ const parsed = parseOrigin(origin);
49
+ return parsed !== null && isNestedLabel(parsed.host.split(".")[0] ?? "");
50
+ }
51
+
30
52
  /** Whether `origin` is an exact origin (`https://host[:port]`, lowercase, no path). */
31
53
  export function isExactOrigin(origin: unknown): origin is string {
32
54
  return typeof origin === "string" && parseOrigin(origin) !== null;
@@ -124,6 +146,8 @@ export function checkFrameLocation(
124
146
  location: FrameLocation,
125
147
  contentOrigins: readonly string[],
126
148
  hostOrigin: string,
149
+ /** The config nests its pages (P111): the location must be on a shell's own label (P121). */
150
+ nested = false,
127
151
  ): void {
128
152
  const origin = parseOrigin(location.origin);
129
153
  let url: URL;
@@ -143,6 +167,11 @@ export function checkFrameLocation(
143
167
  `The located origin ${location.origin} is not one of the config's content origins`,
144
168
  );
145
169
  }
170
+ if (nested && !onNestedLabel(location.origin)) {
171
+ throw new TypeError(
172
+ `The located origin ${location.origin} isn't a nested page's own: its shell is served on a label of its own alone (${PORTHOLE_LABEL_PREFIX}<24 base32>, nestedLabelOf(label), P114), never beside other content`,
173
+ );
174
+ }
146
175
  const host = parseOrigin(hostOrigin);
147
176
  if (host !== null && maybeSameSite(origin.host, host.host)) {
148
177
  throw new TypeError(
@@ -80,6 +80,12 @@ export const SHELL_STATE_METHOD = "porthole/shell/state";
80
80
  /** A nested page's shell's heartbeat, every 50 ms while it runs (P111, after its review). */
81
81
  export const SHELL_BEAT_METHOD = "porthole/shell/beat";
82
82
 
83
+ /**
84
+ * The host's ask to a nested page's shell (P120): look now, and say what it saw in a state report
85
+ * that names the ask (`asked`). The host asks as it hears focus move into the frame.
86
+ */
87
+ export const SHELL_LOOK_METHOD = "porthole/shell/look";
88
+
83
89
  /** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
84
90
  export const SHELL_METHOD_PREFIX = "porthole/shell/";
85
91
 
@@ -18,6 +18,15 @@
18
18
  * frame again (the review of the guard, GK-1): the guard keeps watching after each take-back and
19
19
  * counts one that didn't hold. Every engine keeps a gesture's transient activation for 5 s
20
20
  * (measured: 5.04 to 5.10 s).
21
+ *
22
+ * A nested page's shell (P111) says when its activation turned on, which a press in the page does,
23
+ * and so does a key the person typed into it: one meant for the host's composer, after the page took
24
+ * the keyboard and before the guard took it back (the audit of P111's guard, NG-1). Neither the
25
+ * shell nor the host's page can tell the two apart from the activation (the shell gets no event as
26
+ * focus comes into its child, measured), so (P120): in a fight over a text field the shell's word
27
+ * isn't asked; a wait on a move from a text field doesn't end with the frame holding focus unjudged;
28
+ * and where the host's page sees the pointer over its frames, an activation while it isn't over the
29
+ * frame and the person was typing is no press.
21
30
  */
22
31
 
23
32
  /** How long the person's Tab counts as moving focus (the move follows its keydown at once). */
@@ -32,6 +41,17 @@ export const ACTIVATION_SPAN_MS = 5_000;
32
41
  /** The person is typing: a key on the host's page within this long. */
33
42
  export const TYPING_MS = 1_000;
34
43
 
44
+ /**
45
+ * No press of the person's lands on a frame this soon after a key they typed on the host's page
46
+ * (P122): a hand on the keys doesn't reach the pointer and press that fast (the Keystroke-Level
47
+ * Model gives 400 ms to the hand's move from the keys to the mouse alone; Card, Moran and Newell,
48
+ * 1980). A move into a nested page's frame, or its shell's activation turning on, within this long
49
+ * is the person's next key landing in the page, which turns its activation on as a press does.
50
+ * Where neither the host's page nor the shell sees the pointer (full Chromium), it holds a page that
51
+ * takes the keyboard while the person types even when their key outruns the shell's answer.
52
+ */
53
+ export const KEY_PRESS_MS = 250;
54
+
35
55
  /**
36
56
  * After a take-back, the guard keeps watching (each animation frame) until focus has stayed in the
37
57
  * text field this long: a page that takes it again at once (on its own blur, which the take-back
@@ -104,6 +124,12 @@ export interface ShellWord {
104
124
  readonly focusedAt: number;
105
125
  /** Its activation turned on while it was stalled: uncertain until it goes off (`SHELL_STALL_MS`). */
106
126
  readonly uncertain?: boolean;
127
+ /**
128
+ * Its activation turned on within `TYPING_MS` of the person's typing on the host's page, the
129
+ * pointer not come over the frame since (`pressPossible`, judged as it turned on): where the
130
+ * host's page sees the pointer, their key landing in the page, no press (P120).
131
+ */
132
+ readonly keyed?: boolean;
107
133
  }
108
134
 
109
135
  /** One move of the keyboard the guard undid. */
@@ -144,7 +170,12 @@ export interface FocusMove {
144
170
  * A nested page's frame (P111): what its shell said, and when the host's page last had a
145
171
  * trusted press or key of its own. Absent for any other frame.
146
172
  */
147
- readonly shell?: { readonly word: ShellWord; readonly hostInputAt: number };
173
+ readonly shell?: {
174
+ readonly word: ShellWord;
175
+ readonly hostInputAt: number;
176
+ /** The host's page sees the pointer over its frames on this engine (`pressPossible`, P120). */
177
+ readonly pointerShown?: boolean;
178
+ };
148
179
  }
149
180
 
150
181
  /**
@@ -172,11 +203,16 @@ export function personMoved(move: FocusMove): boolean {
172
203
  return true;
173
204
  }
174
205
  // 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.
206
+ // page had no press or key of its own since (the person went back to it), where it may have been
207
+ // a press (P120) and not within `KEY_PRESS_MS` of the person's last key (P122); or, where the
208
+ // engine tells it, a press on the frame. Nothing else: no pointer over it, no host-wide
209
+ // activation.
177
210
  if (move.shell !== undefined && move.shell.word.supported) {
178
211
  return (
179
- (move.seen && move.pressed) || shellGesture(move.shell.word, move.shell.hostInputAt, move.now)
212
+ (move.seen && move.pressed) ||
213
+ (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))
180
216
  );
181
217
  }
182
218
  if (
@@ -203,6 +239,24 @@ export function shellGesture(word: ShellWord, hostInputAt: number, now: number):
203
239
  );
204
240
  }
205
241
 
242
+ /**
243
+ * Whether the person could have pressed the frame just before `at` (P120): a nested page's shell
244
+ * says its activation turned on, which a key typed into the page does as well as a press. Where the
245
+ * host's page sees the pointer over its frames (`shown`: Firefox; Chromium and WebKit where the frame
246
+ * is in their process, not full Chromium), a press needs the pointer over the frame, come over it
247
+ * since the person last typed on the host's page; within `TYPING_MS` of that typing, an activation
248
+ * with the pointer elsewhere is their keys landing in the page. Anywhere else it may be a press.
249
+ */
250
+ export function pressPossible(
251
+ shown: boolean,
252
+ over: boolean,
253
+ overSince: number,
254
+ typedAt: number,
255
+ at: number,
256
+ ): boolean {
257
+ return !shown || at - typedAt > TYPING_MS || (over && overSince > typedAt);
258
+ }
259
+
206
260
  /** Keys that type nothing on their own: they don't count as typing (a gesture still). */
207
261
  const MODIFIERS = new Set(["Shift", "Control", "Alt", "Meta", "AltGraph", "CapsLock", "Fn"]);
208
262
 
@@ -246,7 +300,11 @@ export interface FocusGuard {
246
300
  add(
247
301
  frame: HTMLIFrameElement,
248
302
  taken: (take: FocusTake) => void,
249
- options?: { readonly nested?: boolean },
303
+ options?: {
304
+ readonly nested?: boolean;
305
+ /** Asks a nested page's shell to look now (P120); it answers with a report naming `n`. */
306
+ readonly ask?: (n: number) => void;
307
+ },
250
308
  ): () => void;
251
309
  /** What a nested page's shell said (P111): its activation, its focus. */
252
310
  shell(
@@ -257,6 +315,8 @@ export interface FocusGuard {
257
315
  readonly focused: boolean;
258
316
  /** How long the shell went without a look before this one (its own clock). */
259
317
  readonly gap: number;
318
+ /** The ask this report answers (P120), if it answers one. */
319
+ readonly asked?: number;
260
320
  },
261
321
  ): void;
262
322
  /** A nested page's shell's heartbeat (P111): it is looking. */
@@ -281,6 +341,10 @@ interface Guarded {
281
341
  word: ShellWord | null;
282
342
  /** When the host last heard the shell (a report or a heartbeat). */
283
343
  heardAt: number;
344
+ /** Asks the shell to look now (P120), the last ask's number, and whether it was answered. */
345
+ readonly ask: ((n: number) => void) | undefined;
346
+ asked: number;
347
+ answered: boolean;
284
348
  }
285
349
 
286
350
  const guards = new WeakMap<Window, FocusGuard>();
@@ -298,6 +362,25 @@ export function focusGuard(view: Window): FocusGuard {
298
362
  let focusedAt = now();
299
363
  let lastKey: { key: string; at: number } | null = null;
300
364
  let typedAt = -Infinity;
365
+ /** When the person typed on the host's page, the last two seconds of it (P122). */
366
+ const typings: number[] = [];
367
+ const typed = (at: number) => {
368
+ typedAt = at;
369
+ typings.push(at);
370
+ while (typings.length > 0 && at - (typings[0] as number) > 2 * TYPING_MS) {
371
+ typings.shift();
372
+ }
373
+ };
374
+ /** The person's last typing on the host's page at or before `at` (-Infinity: none known). */
375
+ const typedBefore = (at: number): number => {
376
+ for (let index = typings.length - 1; index >= 0; index -= 1) {
377
+ const each = typings[index] as number;
378
+ if (each <= at) {
379
+ return each;
380
+ }
381
+ }
382
+ return -Infinity;
383
+ };
301
384
  let gestureAt = -Infinity;
302
385
  let pressAt = -Infinity;
303
386
  /** The host's page's last trusted press or key (P111: a nested page's gesture must be later). */
@@ -312,8 +395,14 @@ export function focusGuard(view: Window): FocusGuard {
312
395
  readonly frame: HTMLIFrameElement;
313
396
  readonly guarded: Guarded;
314
397
  readonly since: number;
315
- readonly failed: boolean;
316
398
  } | null = null;
399
+ /**
400
+ * Whether the host's page sees the pointer over its frames (P120): learned once the pointer comes
401
+ * over one (`pointerover` on its element: Firefox, and Chromium and WebKit where frames are in their
402
+ * process), or a move from a text field into one doesn't blur the window (Firefox, which shows
403
+ * the pointer over a frame, measured). Full Chromium shows neither, and never learns it.
404
+ */
405
+ let pointerShown = false;
317
406
  /** When focus last went into a guarded frame, and whether the person moved it there. */
318
407
  let enteredAt = -Infinity;
319
408
  let earned = false;
@@ -328,12 +417,15 @@ export function focusGuard(view: Window): FocusGuard {
328
417
  /**
329
418
  * A take-back in progress: the field focus goes back to, the frame it came from, when focus was
330
419
  * last given back, and since when it has stayed in the field. Ends once it has stayed `HELD_MS`,
331
- * the person moves focus somewhere of their own, or the field or frame is gone.
420
+ * the person moves focus somewhere of their own, or the field or frame is gone. A `fight` undoes
421
+ * the page's own move (a take-back, `focusField`, or the person leaving a frame that took focus
422
+ * itself), not the person leaving a frame they moved into (P120).
332
423
  */
333
424
  let contest: {
334
425
  readonly field: HTMLElement;
335
426
  readonly frame: HTMLIFrameElement;
336
427
  readonly guarded: Guarded;
428
+ readonly fight: boolean;
337
429
  gaveAt: number;
338
430
  heldSince: number | null;
339
431
  } | null = null;
@@ -350,20 +442,25 @@ export function focusGuard(view: Window): FocusGuard {
350
442
 
351
443
  /**
352
444
  * 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).
445
+ * whose shell hasn't spoken of this move yet, `wait` (P111). In a fight over a text field
446
+ * (`fight`, P120), a nested page's frame is judged as any frame is, its shell's word not asked:
447
+ * an activation it says turned on then is the person's keys landing in it far more often than a
448
+ * press (a press back into the page within `HELD_MS` of focus landing in the field).
354
449
  */
355
450
  const judge = (
356
451
  frame: HTMLIFrameElement,
357
452
  guarded: Guarded,
358
453
  seen: boolean,
359
454
  at: number,
455
+ fight = false,
360
456
  ): boolean | "wait" => {
361
- const word = guarded.word;
457
+ const word = fight ? null : guarded.word;
458
+ const over = frame.matches(":hover");
362
459
  const moved = personMoved({
363
460
  now: at,
364
461
  seen,
365
462
  pressed: frame.matches(":active"),
366
- over: frame.matches(":hover"),
463
+ over,
367
464
  overSince: guarded.overSince,
368
465
  lastKey,
369
466
  typedAt,
@@ -371,12 +468,20 @@ export function focusGuard(view: Window): FocusGuard {
371
468
  gestureAt,
372
469
  activation: activation(),
373
470
  hostMoved: hostMove !== null && hostMove.frame === frame && at - hostMove.at <= TAB_MS,
374
- ...(word === null ? {} : { shell: { word, hostInputAt: inputAt } }),
471
+ ...(word === null ? {} : { shell: { word, hostInputAt: inputAt, pointerShown } }),
375
472
  });
376
473
  hostMove = null;
377
474
  // 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) {
475
+ // said focus came in (around now), its activation may be on its way; unless no press could
476
+ // have made the move (P120), which nothing the shell says changes.
477
+ if (
478
+ !moved &&
479
+ word !== null &&
480
+ word.supported &&
481
+ word.focusedAt < at - SHELL_EARLY_MS &&
482
+ at - typedAt >= KEY_PRESS_MS &&
483
+ pressPossible(pointerShown, over, guarded.overSince, typedAt, at)
484
+ ) {
380
485
  return "wait";
381
486
  }
382
487
  return moved;
@@ -388,9 +493,14 @@ export function focusGuard(view: Window): FocusGuard {
388
493
  frame: HTMLIFrameElement,
389
494
  guarded: Guarded,
390
495
  at: number,
391
- failed: boolean,
392
496
  ) => {
393
- waiting = { field, frame, guarded, since: at, failed };
497
+ waiting = { field, frame, guarded, since: at };
498
+ // The shell looks at its next frame, and a key the person types into the page before then
499
+ // turns its activation on as a press does: asked to look now, it says what it saw as the move
500
+ // was heard (P120).
501
+ guarded.asked += 1;
502
+ guarded.answered = false;
503
+ guarded.ask?.(guarded.asked);
394
504
  known = frame;
395
505
  enteredAt = at;
396
506
  earned = false;
@@ -407,15 +517,38 @@ export function focusGuard(view: Window): FocusGuard {
407
517
  return;
408
518
  }
409
519
  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.
520
+ const active = deepActive(document);
521
+ if (active !== frame || !frames.has(frame)) {
412
522
  waiting = null;
523
+ // Moved on since to nothing, or back to the field, with no press of the person's on the
524
+ // host's page: still the page's move from that field (P120, after the audit of P111's guard:
525
+ // NG-1, where the frame took it again at once and was then let be), watched as a take-back
526
+ // is, focus on nothing given back and counted.
527
+ if (
528
+ field !== null &&
529
+ field.isConnected &&
530
+ pressAt <= held.since &&
531
+ (active === null || active === document.body || active === field)
532
+ ) {
533
+ known = field;
534
+ contest = { field, frame, guarded, fight: true, gaveAt: held.since, heldSince: null };
535
+ schedule();
536
+ return;
537
+ }
538
+ // Anywhere else: from the frame, as the next look judges it.
413
539
  known = frame;
414
540
  return;
415
541
  }
416
542
  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;
543
+ // The shell's activation, where a press could have made it: within a second of the person's
544
+ // typing on the host's page with the pointer elsewhere, it is their keys landing in the page
545
+ // (P120). Read as of the move.
546
+ const theirs =
547
+ word !== null && shellGesture(word, inputAt, at) && !(pointerShown && word.keyed === true);
548
+ // It said focus came in around the move, or answered the ask the move made with focus in it.
549
+ const spoke =
550
+ word !== null &&
551
+ (word.focusedAt >= held.since - SHELL_EARLY_MS || (guarded.answered && word.focused));
419
552
  if (theirs) {
420
553
  waiting = null;
421
554
  known = frame;
@@ -427,7 +560,7 @@ export function focusGuard(view: Window): FocusGuard {
427
560
  }
428
561
  waiting = null;
429
562
  if (field !== null && field.isConnected) {
430
- takeBack(field, frame, guarded, at, held.failed);
563
+ takeBack(field, frame, guarded, at, false);
431
564
  }
432
565
  };
433
566
 
@@ -460,7 +593,7 @@ export function focusGuard(view: Window): FocusGuard {
460
593
  // Until it is back, the field counts as the page's focus, so a move that didn't take is seen.
461
594
  known = field;
462
595
  focusedAt = at;
463
- contest = { field, frame, guarded, gaveAt: at, heldSince: null };
596
+ contest = { field, frame, guarded, fight: true, gaveAt: at, heldSince: null };
464
597
  giveBack(field, frame);
465
598
  schedule();
466
599
  const take: FocusTake = { typing: at - typedAt <= TYPING_MS, failed };
@@ -509,7 +642,10 @@ export function focusGuard(view: Window): FocusGuard {
509
642
  return false;
510
643
  }
511
644
  if (active === frame) {
512
- const verdict = judge(frame, guarded, seen, at);
645
+ // The frame has it again. In a fight, the person's only by a Tab, the host's own move, or a
646
+ // press the engine shows: a nested page's too, its shell's word not asked (P120, after the
647
+ // audit of P111's guard, NG-1, where waiting for it let the frame keep the keyboard).
648
+ const verdict = judge(frame, guarded, seen, at, watched.fight);
513
649
  if (verdict === true) {
514
650
  contest = null;
515
651
  known = frame;
@@ -518,10 +654,11 @@ export function focusGuard(view: Window): FocusGuard {
518
654
  return true;
519
655
  }
520
656
  if (verdict === "wait") {
521
- // A nested page's frame took it again (P111): its shell decides, as it would at first.
657
+ // The person left a nested page they had moved into, and focus went back in (P111): its
658
+ // shell decides, as it would at first.
522
659
  if (watched.heldSince !== null || at - watched.gaveAt >= GIVE_BACK_MS) {
523
660
  contest = null;
524
- wait(field, frame, guarded, at, true);
661
+ wait(field, frame, guarded, at);
525
662
  }
526
663
  return true;
527
664
  }
@@ -580,7 +717,7 @@ export function focusGuard(view: Window): FocusGuard {
580
717
  const verdict = takesText(was) || judge(active as HTMLIFrameElement, entered, seen, at);
581
718
  if (verdict === "wait") {
582
719
  // A nested page's (P111): theirs once its shell says so; nothing to take back.
583
- wait(null, active as HTMLIFrameElement, entered, at, false);
720
+ wait(null, active as HTMLIFrameElement, entered, at);
584
721
  return;
585
722
  }
586
723
  earned = verdict;
@@ -594,6 +731,7 @@ export function focusGuard(view: Window): FocusGuard {
594
731
  field: active,
595
732
  frame: was as HTMLIFrameElement,
596
733
  guarded: left,
734
+ fight: !earned,
597
735
  gaveAt: at,
598
736
  heldSince: at,
599
737
  };
@@ -604,12 +742,17 @@ export function focusGuard(view: Window): FocusGuard {
604
742
  return;
605
743
  }
606
744
  const frame = active as HTMLIFrameElement;
745
+ if (!seen) {
746
+ // A move out of a text field the window didn't blur for: Firefox, which shows the host's
747
+ // page the pointer over a frame (P120).
748
+ pointerShown = true;
749
+ }
607
750
  const verdict = judge(frame, guarded, seen, at);
608
751
  if (verdict === true) {
609
752
  return;
610
753
  }
611
754
  if (verdict === "wait") {
612
- wait(was, frame, guarded, at, false);
755
+ wait(was, frame, guarded, at);
613
756
  return;
614
757
  }
615
758
  takeBack(was, frame, guarded, at, false);
@@ -656,7 +799,7 @@ export function focusGuard(view: Window): FocusGuard {
656
799
  inputAt = at;
657
800
  }
658
801
  if (event.key !== "Tab" && !MODIFIERS.has(event.key)) {
659
- typedAt = at;
802
+ typed(at);
660
803
  }
661
804
  },
662
805
  true,
@@ -672,7 +815,7 @@ export function focusGuard(view: Window): FocusGuard {
672
815
  view.addEventListener(
673
816
  "input",
674
817
  () => {
675
- typedAt = now();
818
+ typed(now());
676
819
  gestureAt = typedAt;
677
820
  },
678
821
  true,
@@ -710,6 +853,9 @@ export function focusGuard(view: Window): FocusGuard {
710
853
  taken: new Set(),
711
854
  overSince: -Infinity,
712
855
  heardAt: -Infinity,
856
+ ask: options?.nested === true ? options.ask : undefined,
857
+ asked: 0,
858
+ answered: false,
713
859
  word:
714
860
  options?.nested === true
715
861
  ? { supported: true, activatedAt: -Infinity, focused: false, focusedAt: -Infinity }
@@ -717,6 +863,7 @@ export function focusGuard(view: Window): FocusGuard {
717
863
  };
718
864
  frame.addEventListener("pointerover", () => {
719
865
  entry.overSince = now();
866
+ pointerShown = true;
720
867
  });
721
868
  frames.set(frame, entry);
722
869
  guarded = entry;
@@ -739,17 +886,45 @@ export function focusGuard(view: Window): FocusGuard {
739
886
  }
740
887
  const at = now();
741
888
  // 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).
889
+ // allows): uncertain, and so until it goes off (P111, after its review). So is one that
890
+ // turned on while the guard fights this frame for a text field (P120): the person's keys,
891
+ // meant for the field, landing in the page.
892
+ // So is one that turned on within `KEY_PRESS_MS` of a key the person typed on the host's page
893
+ // before it (P122): that key's successor, landing in the page.
743
894
  const turnedOn = said.ago !== null && before.activatedAt === -Infinity && !before.uncertain;
744
895
  const stalled = said.gap > SHELL_STALL_MS || at - guarded.heardAt > SHELL_STALL_MS;
745
- const uncertain = said.ago !== null && (before.uncertain === true || (turnedOn && stalled));
896
+ const fought = contest !== null && contest.fight && contest.frame === frame;
897
+ // The typing before it, never after: a key the person typed on the host's page after they
898
+ // pressed the page, before the shell's word came, says nothing of that press (P122, after
899
+ // CI). The shell saw it turn on at its look, so it turned on at most a look's gap before:
900
+ // only a key before then counts.
901
+ const turnedAt =
902
+ said.ago === null ? -Infinity : at - said.ago - Math.min(said.gap, SHELL_STALL_MS);
903
+ const typing = typedBefore(turnedAt);
904
+ const soon = said.ago !== null && turnedAt - typing < KEY_PRESS_MS;
905
+ const uncertain =
906
+ said.ago !== null &&
907
+ (before.uncertain === true || (turnedOn && (stalled || fought || soon)));
746
908
  guarded.heardAt = at;
909
+ if (said.asked !== undefined && said.asked === guarded.asked) {
910
+ guarded.answered = true;
911
+ }
912
+ // Whether a press could have turned it on, judged as it did (P120, after its review): the
913
+ // person's typing then, and the pointer then, not when a move is later judged.
914
+ const activatedAt = said.ago === null || uncertain ? -Infinity : at - said.ago;
915
+ const keyed =
916
+ activatedAt === -Infinity
917
+ ? false
918
+ : turnedOn
919
+ ? !pressPossible(true, frame.matches(":hover"), guarded.overSince, typing, turnedAt)
920
+ : before.keyed === true;
747
921
  guarded.word = {
748
922
  supported: said.supported,
749
- activatedAt: said.ago === null || uncertain ? -Infinity : at - said.ago,
923
+ activatedAt,
750
924
  focused: said.focused,
751
925
  focusedAt: said.focused && !before.focused ? at : before.focusedAt,
752
926
  ...(uncertain ? { uncertain: true } : {}),
927
+ ...(keyed ? { keyed: true } : {}),
753
928
  };
754
929
  if (waiting?.frame === frame) {
755
930
  settle(at);
@@ -762,8 +937,17 @@ export function focusGuard(view: Window): FocusGuard {
762
937
  }
763
938
  },
764
939
  gesture(frame) {
765
- const word = frames.get(frame)?.word ?? null;
766
- return word !== null && shellGesture(word, inputAt, now());
940
+ const guarded = frames.get(frame);
941
+ const word = guarded?.word ?? null;
942
+ const at = now();
943
+ // Where a press could have made it (P120): a key the person typed into the page, meant for
944
+ // 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
+ );
767
951
  },
768
952
  focus(frame) {
769
953
  hostMove = { frame, at: now() };
@@ -790,7 +974,7 @@ export function focusGuard(view: Window): FocusGuard {
790
974
  field.focus({ preventScroll: true });
791
975
  known = field;
792
976
  focusedAt = now();
793
- contest = { field, frame, guarded, gaveAt: focusedAt, heldSince: null };
977
+ contest = { field, frame, guarded, fight: true, gaveAt: focusedAt, heldSince: null };
794
978
  schedule();
795
979
  },
796
980
  };
@@ -2,6 +2,7 @@ import type { ColorScheme } from "../config/schema.ts";
2
2
  import {
3
3
  FRAME_STATUS_METHOD,
4
4
  SHELL_BEAT_METHOD,
5
+ SHELL_LOOK_METHOD,
5
6
  SHELL_METHOD_PREFIX,
6
7
  SHELL_STATE_METHOD,
7
8
  } from "../isolation/types.ts";
@@ -41,7 +42,7 @@ function shellWords(opened: Transport, frame: HTMLIFrameElement, guard: FocusGua
41
42
  if (params === null || typeof params !== "object") {
42
43
  return;
43
44
  }
44
- const { supported, ago, focused, gap } = params as Record<string, unknown>;
45
+ const { supported, ago, focused, gap, asked } = params as Record<string, unknown>;
45
46
  const span = (value: unknown) =>
46
47
  typeof value === "number" && Number.isFinite(value) && value >= 0;
47
48
  if (message.method === SHELL_BEAT_METHOD) {
@@ -55,11 +56,18 @@ function shellWords(opened: Transport, frame: HTMLIFrameElement, guard: FocusGua
55
56
  typeof supported !== "boolean" ||
56
57
  typeof focused !== "boolean" ||
57
58
  !(ago === null || span(ago)) ||
58
- !span(gap)
59
+ !span(gap) ||
60
+ !(asked === undefined || (Number.isSafeInteger(asked) && (asked as number) >= 0))
59
61
  ) {
60
62
  return;
61
63
  }
62
- guard.shell(frame, { supported, ago: ago as number | null, focused, gap: gap as number });
64
+ guard.shell(frame, {
65
+ supported,
66
+ ago: ago as number | null,
67
+ focused,
68
+ gap: gap as number,
69
+ ...(asked === undefined ? {} : { asked: asked as number }),
70
+ });
63
71
  });
64
72
  return {
65
73
  send: (message) => opened.send(message),
@@ -131,15 +139,6 @@ export const webPlatform: PlatformHost = {
131
139
  const guard = focusGuard(view);
132
140
  const taken = new Set<(take: FocusTake) => void>();
133
141
  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
- );
143
142
  // A served frame may pass through the host's own pages (a redirect entry's, P068): what they
144
143
  // say of the frame's status is heard too, and nothing else from there.
145
144
  const own = view.origin;
@@ -151,6 +150,24 @@ export const webPlatform: PlatformHost = {
151
150
  ? undefined
152
151
  : { origin: own, accept: isFrameStatus },
153
152
  );
153
+ const unguard = guard.add(
154
+ frame,
155
+ (take) => {
156
+ for (const listener of taken) {
157
+ listener(take);
158
+ }
159
+ },
160
+ {
161
+ nested,
162
+ // A nested page's shell is asked to look as the guard hears a move into its frame (P120).
163
+ ...(nested
164
+ ? {
165
+ ask: (n: number) =>
166
+ opened.send({ jsonrpc: "2.0", method: SHELL_LOOK_METHOD, params: { n } }),
167
+ }
168
+ : {}),
169
+ },
170
+ );
154
171
  // A nested page's shell (P111): its own words go to the guard, by the frame's window and the
155
172
  // content origin (the transport's checks); the page's pass on. The shell drops any page
156
173
  // message in its namespace, so there none is the page's.
@@ -11,7 +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
+ import { NESTED_FILE_HEADERS, nestedFileCsp } from "./nested.ts";
15
15
  import type { FileBody, StoredAsset, StoredFiles } from "./types.ts";
16
16
 
17
17
  /**
@@ -249,14 +249,13 @@ export async function serveFile(serving: FileServing): Promise<Response> {
249
249
  // sandbox, so none opened as a document on its own (a tab, "open image in new tab") runs on that
250
250
  // origin. Pages run their scripts, opaque; anything else runs nothing (a file's is inert already,
251
251
  // a script's gets one too).
252
- const csp =
253
- role === "file"
252
+ const csp = nested
253
+ ? nestedFileCsp(role, directives)
254
+ : role === "file"
254
255
  ? INERT_FILE_CSP
255
256
  : role === "page"
256
257
  ? servedDocumentCsp(serving.compiled.config, directives)
257
- : nested
258
- ? `${serializeCsp(directives)}; sandbox`
259
- : serializeCsp(directives);
258
+ : serializeCsp(directives);
260
259
  const headers = new Headers({
261
260
  "content-type": type,
262
261
  "x-content-type-options": "nosniff",
@@ -79,6 +79,7 @@ export {
79
79
  NESTED_FILE_HEADERS,
80
80
  NESTED_FILES_PREFIX,
81
81
  nestedAncestors,
82
+ nestedFileCsp,
82
83
  nestedLabelOf,
83
84
  nestedShellCsp,
84
85
  nestedShellResponse,