@botiverse/porthole 0.14.12 → 0.14.14

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.
@@ -5,7 +5,7 @@ What Porthole protects, from whom, and where that protection ends. For each way
5
5
  guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
6
6
  [DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
7
7
 
8
- **Status.** This describes Porthole 0.14.12 (2026-11-06). A review on 2026-10-19 found gaps, and every decision it led to
8
+ **Status.** This describes Porthole 0.14.14 (2026-11-07). A review on 2026-10-19 found gaps, and every decision it led to
9
9
  has merged ([§8](#8-fixes-in-flight) lists them). P096 changed the negative-control runner and CI,
10
10
  and the shipped conformance probes' messages and timing, not what they check. P104 (0.9.0's
11
11
  annotation markers) had a review of its own, and P105, in 0.10.0, is what it led to. 0.11.0 was
@@ -36,7 +36,10 @@ order, so it can steer or spoil the focus, and a host keeps its own list of mark
36
36
  reports `activated`, which the page could already fake; `lastLineDocumentRect` is unclamped, for a
37
37
  host to clip as P132's are; no wall moves. 0.14.12: P134 adds `annotations.focusMark(id)`, the host's
38
38
  word to put the keyboard back on a marker, and a second exception to "takes no focus" whose conditions
39
- are the host's own (§6, §7); no wall moves.
39
+ are the host's own (§6, §7); no wall moves. 0.14.13: P135 drops a `focusMark` that had to wait unless the focus is
40
+ in the frame's document by then; a call on a calm page is unchanged. 0.14.14: P136 brings `display.focus()`
41
+ through a nested page's shell with a new host-to-shell word no page can say; P137 applies P135's check to a
42
+ word 100 ms old or more; no wall moves.
40
43
 
41
44
  ## 1. Two layers
42
45
 
@@ -233,7 +236,10 @@ Whatever the use:
233
236
  it reads its own page's `document.activeElement` and that is this frame; the focus goes only to a
234
237
  container that takes no input (`tabindex="-1"`), never a field or a button; and every control in
235
238
  that view that can write has the host's own gate, so that a forged opening and the keys right after
236
- it can't submit. That's the host's duty: Porthole doesn't guarantee it.
239
+ it can't submit. The gate covers keys as well as controls: with the focus in that view the person's
240
+ next keys reach the host's document, so the view's own key handlers and the host's page-wide
241
+ shortcuts that write (an `r` that resolves, Cmd+Enter that posts) need it too (P137). That's the
242
+ host's duty: Porthole doesn't guarantee it.
237
243
  - Know that a display can take the keyboard: a page calls `focus()` on its own input whenever it
238
244
  likes (on Chromium and WebKit with no gesture), and what the person goes on typing goes to it.
239
245
  `createHost` (every `PortholeView` too) gives focus back when it leaves one of the page's text
@@ -243,6 +249,17 @@ Whatever the use:
243
249
  your composer with `focusField(field)`, not the field's own `focus()` (Firefox ignores that while
244
250
  a fighting frame holds focus); and with a platform of your own, implement its focus guard
245
251
  (`focused`, `onFocusTaken`, `focus`) or accept that a display can read what is typed beside it.
252
+ - Call `annotations.focusMark(id)` only as the person's key closes your view of that mark, and know
253
+ it can be dropped (P135, P137): one that has to wait while the frame finds its marks, or that the
254
+ frame takes more than 100 ms after you sent it because its page is busy, lands only if the focus
255
+ is in the frame by then, and in the normal flow it is on your `<body>`. Nothing says so. If
256
+ the focus is still on your body a moment later, the person hasn't moved on: `display.focus()`,
257
+ then `focusMark(id)` again. Look first: that move is yours, the focus guard doesn't judge it, and
258
+ a move after the person went on to a button of yours takes the keyboard from them. On a nested
259
+ page, use `display.focus()`: it tells the page's shell to pass the focus on (P136), and the frame's
260
+ own `focus()` stops at the shell, so a word that waits is dropped even after it. On Firefox,
261
+ `display.focus()` inside a key's own handler moves nothing: call it from a task (measured on a
262
+ nested page). Nothing leaks either way: the keyboard stays out of the page.
246
263
  - List every app origin in `appOrigins` (`hostOrigins` in `/server`): only those may frame content,
247
264
  and only those are checked against the content domain for a shared site.
248
265
  - Under the app runtime, run `defineRuntimeConformance` with `api` in CI (§7).
@@ -838,7 +855,8 @@ own frame, below the shell, P111), so:
838
855
  the frame as well (accepted, P132; the host's duty in §6). They say nothing else: the page knows
839
856
  where its words are anyway. Where a selection or a mark's words end (`lastLineDocumentRect` in
840
857
  `selected`, `anchored` and `tracked`, P133) is one more such box, read, checked and left unclamped
841
- the same way, with the same duty; `selected` also carries `scroll` now.
858
+ the same way, with the same duty; `selected` also carries `scroll` now. A report with a last line
859
+ and no `scroll` is dropped (P137), as a malformed part drops one.
842
860
  - *What holds, against content that patches none of the DOM's or JavaScript's built-ins.* A real
843
861
  press or click on a marker reaches none of the content's handlers (the shell's first listener
844
862
  stops it; control `marker-click`) and moves neither focus nor a selection (control
@@ -876,10 +894,10 @@ own frame, below the shell, P111), so:
876
894
  `activated` while the person really is in the frame, and this signal doesn't stop that.** A host
877
895
  that moves the keyboard into its view on the signal takes §6's second exception, with its
878
896
  conditions: a page can put the person's next keys in that view, and keeping those keys from posting
879
- is the host's own gate on that view's controls, not Porthole's.
897
+ is the host's own gate on that view's controls and on its shortcuts, not Porthole's.
880
898
  - *Back to a marker* (P134). `annotations.focusMark(id)` is the host's word to the frame
881
- (`porthole/annotate.focusMark`, `{ id }`), for one moment only: after Escape closed the host's own
882
- view of that mark. No content goes with it, beyond an id the frame has, and nothing comes back. The
899
+ (`porthole/annotate.focusMark`, `{ id }`), for one moment only: after the keyboard closed the host's
900
+ own view of that mark, by Escape or by a Tab past its first or last control. No content goes with it, beyond an id the frame has, and nothing comes back. The
883
901
  shell moves the focus through the platform's `focus` as it was before content ran (control
884
902
  `marker-focus`: a page that replaced it is handed the marker otherwise); with no such marker it does
885
903
  nothing. The page reads the message, so it learns a card closed, and can take the focus back at once
@@ -887,6 +905,30 @@ own frame, below the shell, P111), so:
887
905
  a host can't rely on the focus landing. To the focus guard the move is the frame's own, so from a
888
906
  host's text field that still has focus it is undone and counted (P109), not passed as the host's:
889
907
  no window was opened in the guard for it.
908
+ A word that has to wait while the frame finds its marks is up to a second old when it could land
909
+ (P135). A word the shell doesn't park can be as old: the frame takes it when its thread is free, a
910
+ busy page changes nothing the shell can see, and a frame out of process doesn't stop the host's
911
+ page meanwhile (P137). A marker's `focus()` takes the keyboard with no gesture on Chromium and
912
+ WebKit, past a guard that defends only text fields: a person gone on to a host's button would be
913
+ pulled back. So the shell drops a parked word unless the focus is in its document as it lands, and
914
+ a word older than 100 ms unless the focus is there as it comes, by `hasFocus` as it was before
915
+ content ran (control `marker-has-focus`: a page that replaced it to say yes gets the landing
916
+ otherwise; `marker-late` takes the first test out, `marker-busy` the second). A word's age is the
917
+ shell's `Date.now` as it was before content ran, less the stamp `createHost` put on it as it was
918
+ sent (`at`): one machine's wall clock (control `marker-clock`: a page that stopped its own clock
919
+ makes a late word look fresh otherwise). A word with no stamp, from an older host, is old. A fresh
920
+ word isn't asked: the frame has no focus then on the very path it is for. That leaves a person who
921
+ moves on within those 100 ms, faster than a person does, and a page that forges the whole word with
922
+ a fresh stamp, or rewrites a real word as it arrives, as it can forge the word at all, which gives it nothing (P134). A page
923
+ can really take the focus and so pass the test, which gives it nothing, since it then has the
924
+ keyboard; and a word that passes it can still move the focus off the page's own field onto a marker,
925
+ inside the frame. §6 has the host's side: a second `focusMark` after its own `display.focus()`.
926
+ The word is a message, so from the host's close until the frame moves, the focus rests on the host's
927
+ body. A forged `activated` in that gap finds no frame focused, so a host that gates a view on "the
928
+ frame had the focus" doesn't gate that one. That is accepted, on the host's side of the wall: such
929
+ a view takes no focus and keeps keys out until the focus has reached the frame (in Raft, content
930
+ inert for 500 ms, and the focus handed back to the frame within 150 ms if the marker didn't take
931
+ it, with `focusMark` again after it, P135), so the keys go to the page and nothing is written.
890
932
  - *What doesn't hold against content that does.* The shell shares the content's realm. It reads
891
933
  and stops a marker's press through the platform's own functions and getters, kept before
892
934
  content runs (P105, control `marker-originals`), so patching `Event`'s or `MouseEvent`'s
@@ -1017,7 +1059,8 @@ unposted words beside the frame and tell the page when.
1017
1059
  since; or a Tab, the host's own move, or a press the engine shows on the frame element. Nothing
1018
1060
  else counts as a press: no pointer over the frame, no host-wide activation. A move the shell
1019
1061
  hasn't spoken of yet waits for its word at most 500 ms (the host asks it to look at once,
1020
- `porthole/shell/look`), then is taken back. A key the person types into the page turns its
1062
+ `porthole/shell/look`), then is taken back. The shell passes a focus on to the page by the host's
1063
+ word (`porthole/shell/focus`, P136), which only `display.focus()` sends and no page can say. A key the person types into the page turns its
1021
1064
  activation on as a press does, so (P120, after the audit of P111's guard, NG-1): where the
1022
1065
  host's page sees the pointer over its frames (Firefox; Chromium and WebKit where the frame is in
1023
1066
  their process, once the pointer has been over one), an activation while the pointer isn't over
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.14.12",
3
+ "version": "0.14.14",
4
4
  "description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
5
5
  "homepage": "https://github.com/botiverse/porthole#readme",
6
6
  "bugs": {
@@ -137,7 +137,8 @@ export interface AnchorResult {
137
137
  * Where its last line is in the document (P133), in the coordinates of `documentRect` and as
138
138
  * unclamped: its last line with words on it for text, its whole box for an element, which has no
139
139
  * lines of its own. For a host's UI after the last line (its right, or its bottom). Absent from
140
- * an older shell, and where nothing of the mark is drawn. The page's word.
140
+ * an older shell, and where nothing of the mark is drawn. Never without its report's `scroll`
141
+ * (a report that tries is dropped, P137). The page's word.
141
142
  */
142
143
  readonly lastLineDocumentRect?: AnnotationRect;
143
144
  /**
@@ -154,7 +155,8 @@ export type AnnotationReport =
154
155
  * The person pointed at an element or settled a text selection. A newer shell (P133) adds where
155
156
  * it ends, for a host's UI after its last line: `lastLineDocumentRect` as a result's is, with
156
157
  * how far the document was scrolled as it was read (so its place in the frame's viewport is the
157
- * one less the other, unclamped). Both absent from an older shell.
158
+ * one less the other, unclamped). Both absent from an older shell, and never one alone (a report
159
+ * that tries is dropped, P137).
158
160
  */
159
161
  | {
160
162
  readonly type: "selected";
@@ -196,7 +198,8 @@ export type AnnotationReport =
196
198
  * document scrolls, so a host following one mark hears the scroll at every animation frame where
197
199
  * it changed, whether that mark is in the frame or not, and places every mark it holds a
198
200
  * `documentRect` for (an `anchored` report's) without asking again. A newer one still (P133) adds
199
- * its `lastLineDocumentRect`.
201
+ * its `lastLineDocumentRect`, never without `scroll` (a report that tries is dropped, P137), though
202
+ * `scroll` comes without it.
200
203
  */
201
204
  | {
202
205
  readonly type: "tracked";
@@ -240,7 +243,10 @@ export const ANNOTATE_METHODS = {
240
243
  tracked: "porthole/annotate.tracked",
241
244
  /** Host → frame: take the page's text selection away, telling nothing back (P115). */
242
245
  clearSelection: "porthole/annotate.clearSelection",
243
- /** Host → frame: put the focus on one mark's marker (`{ id }`), telling nothing back (P134). */
246
+ /**
247
+ * Host → frame: put the focus on one mark's marker (`{ id }`), telling nothing back (P134); one
248
+ * that waited for the marks is dropped unless the focus is in the frame's document by then (P135).
249
+ */
244
250
  focusMark: "porthole/annotate.focusMark",
245
251
  } as const;
246
252
 
@@ -192,6 +192,15 @@ function results(value: unknown): AnchorResult[] | null {
192
192
  return out;
193
193
  }
194
194
 
195
+ /**
196
+ * A last line with nothing to read it by (P137): its place in the frame's viewport is its own less
197
+ * the scroll it was read at, so a shell sends no last line without one, and a host needn't test for
198
+ * both. The scroll alone is a shell's own: 0.14.10's `tracked` and `anchored` (P132, no last line yet),
199
+ * and a newer one's where nothing of the mark is drawn.
200
+ */
201
+ const lineWithoutScroll = (line: AnnotationRect | undefined, scroll: unknown): boolean =>
202
+ line !== undefined && scroll === undefined;
203
+
195
204
  /** A report from the frame, checked; null if malformed (it is then dropped). */
196
205
  export function parseReport(value: unknown): AnnotationReport | null {
197
206
  if (!isRecord(value)) {
@@ -210,6 +219,10 @@ export function parseReport(value: unknown): AnnotationReport | null {
210
219
  if (anchor === null || rect === null || lastLineDocumentRect === null || scroll === null) {
211
220
  return null;
212
221
  }
222
+ // A pair, here (P137): a selection has never had one without the other.
223
+ if ((lastLineDocumentRect === undefined) !== (scroll === undefined)) {
224
+ return null;
225
+ }
213
226
  return {
214
227
  type: "selected",
215
228
  anchor,
@@ -225,9 +238,14 @@ export function parseReport(value: unknown): AnnotationReport | null {
225
238
  case "anchored": {
226
239
  const checked = results(value.results);
227
240
  const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
228
- return checked === null || scroll === null
229
- ? null
230
- : { type: "anchored", results: checked, ...(scroll === undefined ? {} : { scroll }) };
241
+ if (
242
+ checked === null ||
243
+ scroll === null ||
244
+ checked.some((each) => lineWithoutScroll(each.lastLineDocumentRect, scroll))
245
+ ) {
246
+ return null;
247
+ }
248
+ return { type: "anchored", results: checked, ...(scroll === undefined ? {} : { scroll }) };
231
249
  }
232
250
  case "activated": {
233
251
  const rect = parseRect(value.rect);
@@ -248,7 +266,8 @@ export function parseReport(value: unknown): AnnotationReport | null {
248
266
  rect === null ||
249
267
  documentRect === null ||
250
268
  lastLineDocumentRect === null ||
251
- scroll === null
269
+ scroll === null ||
270
+ lineWithoutScroll(lastLineDocumentRect, scroll)
252
271
  ) {
253
272
  return null;
254
273
  }
@@ -667,9 +667,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
667
667
  focusMark(id) {
668
668
  // Host → frame only, and kept for no later frame (P134). A mark that has gone, or has no
669
669
  // marker, is nothing to ask for, and no fault: the host's card closed with the mark's.
670
+ // Stamped as it is sent: a frame judges by that how old the word is as it takes it (P137).
670
671
  needsAnnotate("focusMark");
671
672
  if (marks.some((mark) => mark.id === id && hasMarker(mark))) {
672
- toFrame(ANNOTATE_METHODS.focusMark, { id });
673
+ toFrame(ANNOTATE_METHODS.focusMark, { id, at: Date.now() });
673
674
  }
674
675
  },
675
676
  };
package/src/host/types.ts CHANGED
@@ -329,6 +329,15 @@ export interface AnnotationControls {
329
329
  * Call it once the view is closed: from one of the page's text fields that still has focus, the
330
330
  * move is the frame's own to the focus guard, undone and counted (P109). The page can take the
331
331
  * focus back at once. Not kept for a frame that runs later.
332
+ *
333
+ * On a calm page it lands at once, from anywhere on the host's page. While the frame is finding
334
+ * its marks (a `show` just sent, the content just changed) it waits, and is then dropped unless
335
+ * the focus is in the frame by then (P135). One the frame takes more than 100 ms after you sent
336
+ * it (its page is busy) is held to the same test (P137), so a word that comes late takes no
337
+ * keyboard from a person who moved on. Nothing says it was dropped: if the frame isn't your page's
338
+ * `document.activeElement` soon after and the person hasn't moved on, call `focus()` and then
339
+ * `focusMark(id)` again. On a nested page only `focus()` reaches the page (P136): the frame's own
340
+ * `focus()` stops at its shell, and a second call that waits is dropped.
332
341
  */
333
342
  focusMark(id: string): void;
334
343
  }
@@ -100,6 +100,13 @@ export const SHELL_BEAT_METHOD = "porthole/shell/beat";
100
100
  */
101
101
  export const SHELL_LOOK_METHOD = "porthole/shell/look";
102
102
 
103
+ /**
104
+ * The host's word to a nested page's shell (P136) that it moved the focus into the frame: pass it on
105
+ * to the page, in this task, not in the focus event (where the shell's move doesn't take). Sent by
106
+ * `display.focus()` alone; a page has no way to say it.
107
+ */
108
+ export const SHELL_FOCUS_METHOD = "porthole/shell/focus";
109
+
103
110
  /** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
104
111
  export const SHELL_METHOD_PREFIX = "porthole/shell/";
105
112
 
@@ -2,6 +2,7 @@ import { DOOR_SANDBOX_TOKENS } from "../compile/policy.ts";
2
2
  import type { ColorScheme } from "../config/schema.ts";
3
3
  import {
4
4
  SHELL_BEAT_METHOD,
5
+ SHELL_FOCUS_METHOD,
5
6
  SHELL_LOOK_METHOD,
6
7
  SHELL_METHOD_PREFIX,
7
8
  SHELL_STATE_METHOD,
@@ -194,6 +195,11 @@ export const webPlatform: PlatformHost = {
194
195
  },
195
196
  focus() {
196
197
  guard.focus(frame);
198
+ // A nested page (P136): the move stops at its shell on every engine, one way or another,
199
+ // and only the shell can pass it on. Only a move that landed: the shell asks no more of it.
200
+ if (nested && view.document.activeElement === frame) {
201
+ opened.send({ jsonrpc: "2.0", method: SHELL_FOCUS_METHOD });
202
+ }
197
203
  },
198
204
  onLoad(listener) {
199
205
  loaded.add(listener);
@@ -500,7 +500,10 @@ export interface PortholeFrameHandle {
500
500
  /**
501
501
  * Puts the keyboard back on a mark's marker in the frame (`annotations.focusMark(id)`, P134),
502
502
  * once Escape closed your own view of that mark. Nothing happens for an id with no marker, or
503
- * while no display runs. A config without `annotate`: `onHostError`, kind `"annotations"`.
503
+ * while no display runs. A config without `annotate`: `onHostError`, kind `"annotations"`. While
504
+ * the frame is finding its marks it waits, and is dropped unless the focus is in the frame by
505
+ * then (P135), and so is one a busy page takes late (P137): call it again after your own move of
506
+ * the focus into the frame.
504
507
  */
505
508
  focusMark(id: string): void;
506
509
  /**
@@ -57,6 +57,23 @@ export const MARKER_NAME = String.raw`(mark) => {
57
57
  return words === "" ? what : what + ' on "' + words + '"';
58
58
  }`;
59
59
 
60
+ /**
61
+ * Whether a host's `focusMark` is too old to land unasked (P137): `at` is the host's `Date.now()` as
62
+ * it sent the word, `now` the shell's, kept before content runs. Both read the one wall clock of
63
+ * this machine, the only clock two realms share (`performance.now()` counts from each one's own
64
+ * start). No number is an older host's word, which can't be known fresh. A word from ahead of the
65
+ * clock has the same bound behind it: two processes can read the clock a little apart, and past
66
+ * that the clock was set back, and the age says nothing. Comparisons only, nothing a page can
67
+ * patch, and a word that makes no number (`NaN`, `Infinity`) passes neither test.
68
+ */
69
+ export const WORD_LATE = String.raw`(at, now) => {
70
+ if (typeof at !== "number") {
71
+ return true;
72
+ }
73
+ const age = now - at;
74
+ return !(age > -100 && age < 100);
75
+ }`;
76
+
60
77
  /**
61
78
  * The shell's annotation runtime (P053), spliced into the shell's runtime (`__ANNOTATE__`) when
62
79
  * the config declares `annotate`, so it runs before any content does, with the DOM's own
@@ -80,7 +97,8 @@ export const MARKER_NAME = String.raw`(mark) => {
80
97
  * focus on it (P133), is reported (`activated`), and the content's own handlers never see it; a
81
98
  * draft is drawn apart, a dashed line and a hollow bubble with no number, and has a marker with
82
99
  * or without a count; the host's `focusMark` (P134) puts the focus on a marker that is there, and
83
- * tells nothing back;
100
+ * tells nothing back; one that had to wait for the marks (P135), or that this document took late
101
+ * (P137), lands only if the focus is in this document by then;
84
102
  * - following: while a mark has a marker, once a scroll, a resize or a change of the content
85
103
  * settles, the marks that moved since the host was last told are reported, at most once a
86
104
  * second, so the host's own UI beside a mark can follow;
@@ -123,6 +141,8 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
123
141
  const selectionOf = Document.prototype.getSelection;
124
142
  const removeAllRanges = Selection.prototype.removeAllRanges;
125
143
  const focusElement = HTMLElement.prototype.focus;
144
+ const hasFocus = Document.prototype.hasFocus;
145
+ const wallClock = Date.now;
126
146
  const elementRect = Element.prototype.getBoundingClientRect;
127
147
  const rangeRect = Range.prototype.getBoundingClientRect;
128
148
  const rangeRects = Range.prototype.getClientRects;
@@ -1075,6 +1095,10 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1075
1095
  let waitingForContent = false;
1076
1096
  let pendingFocus = null;
1077
1097
  let pendingMarker = null;
1098
+ // Asked through the kept function: a page that says it has the focus gets no landing the
1099
+ // platform would refuse (P135).
1100
+ const focusIsHere = () => callOf(hasFocus, document, []) === true;
1101
+ const wordLate = ${WORD_LATE};
1078
1102
  const settling = () => anchorTimer !== 0 || waitingForContent || marks.some((mark) => mark.state === null);
1079
1103
  const scheduleAnchor = (all) => {
1080
1104
  if (all) {
@@ -1116,7 +1140,12 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1116
1140
  if (pendingMarker !== null) {
1117
1141
  const id = pendingMarker;
1118
1142
  pendingMarker = null;
1119
- focusMark(id);
1143
+ // Parked, the host's word is old: the person may have moved on, and a marker's focus
1144
+ // takes the keyboard with no gesture. So it lands only if the focus is still in this
1145
+ // document. Otherwise it is dropped (P135).
1146
+ if (focusIsHere()) {
1147
+ focusMark(id, false);
1148
+ }
1120
1149
  }
1121
1150
  }, wait);
1122
1151
  };
@@ -1226,8 +1255,11 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1226
1255
  // markers yet, so it waits for them, as focus does; then a marker that isn't there, or has
1227
1256
  // stepped aside for picking, is nothing to do. The kept function, so a page that patched
1228
1257
  // focus isn't handed the marker from inside the closed root. The shell's focus listener
1229
- // lights it and brings it into view; nothing is told.
1230
- const focusMark = (id) => {
1258
+ // lights it and brings it into view; nothing is told. A fresh word reads no focus: after the
1259
+ // host's card closed the focus is on the host's body, so this document has none yet. One
1260
+ // parked is asked as it lands (P135), and one this document took late (P137: late, by when
1261
+ // the host sent it: a busy page doesn't park it) is asked here: its moment has passed.
1262
+ const focusMark = (id, late) => {
1231
1263
  if (settling()) {
1232
1264
  pendingMarker = id;
1233
1265
  return;
@@ -1235,6 +1267,9 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1235
1267
  if (mode.elements || !isShown(id)) {
1236
1268
  return;
1237
1269
  }
1270
+ if (late && !focusIsHere()) {
1271
+ return;
1272
+ }
1238
1273
  for (let i = 0; i < markers.length; i += 1) {
1239
1274
  if (markers[i].id === id) {
1240
1275
  callOf(focusElement, markers[i].element, [{ preventScroll: true }]);
@@ -1678,7 +1713,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1678
1713
  break;
1679
1714
  }
1680
1715
  case M.focusMark:
1681
- focusMark(String(params.id));
1716
+ focusMark(String(params.id), wordLate(params.at, callOf(wallClock, undefined, [])));
1682
1717
  break;
1683
1718
  case M.clear:
1684
1719
  track(null);
@@ -26,7 +26,12 @@ import { hostOriginProblem, onNestedLabel } from "../isolation/served.ts";
26
26
  * - renews the page's sealed files' address before it ends, and gives the page the new one
27
27
  * (`porthole/files-renewed`): the page's own loads aren't its origin's (an opaque origin's never
28
28
  * are), so only the shell, on that origin, may renew it (P083);
29
- * - passes its focus to the page (the host's own move into the frame, or a Tab).
29
+ * - passes its focus to the page: at the focus event where that takes (Firefox, from the host's
30
+ * `<body>`), and on the host's word that it moved it there (`porthole/shell/focus`, P136), where
31
+ * it doesn't: a frame's move inside the focus event that made it the focused frame sets the
32
+ * shell's `activeElement` and goes no further (Chromium, WebKit), and from a focused element of
33
+ * the host's the window hears no focus event at all (Firefox). A later task's `frame.focus()`
34
+ * goes through on all of them, the frame blurred first as the failed one left it active.
30
35
  *
31
36
  * Plain ES2020, no imports and no build step, like the runtime. `__PLAN__` is its plan.
32
37
  */
@@ -152,12 +157,39 @@ export const FRAME_SHELL_RUNTIME = String.raw`(() => {
152
157
  };
153
158
  requestAnimationFrame(tick);
154
159
  setInterval(look, 50);
155
- addEventListener("blur", look);
156
- addEventListener("focus", (event) => {
157
- // The host's move into the frame (or a Tab) lands here: on to the page.
158
- if (event.target === window && document.activeElement !== frame) {
160
+
161
+ // Whether the focus is on the shell's own document, not through it on the page's (P136). Firefox
162
+ // tells a move from a focused element of the host's on the document alone. The host's word needs
163
+ // this: it never moves a focus that isn't here, and a page that has it hears no blur.
164
+ let holds = false;
165
+ // Until when a word that came ahead of the focus it speaks of holds (it crosses processes too).
166
+ let wordUntil = 0;
167
+ const handOn = () => {
168
+ if (holds && document.hasFocus()) {
169
+ frame.blur();
159
170
  frame.focus();
160
171
  }
172
+ };
173
+ const came = () => {
174
+ holds = true;
175
+ if (performance.now() < wordUntil) {
176
+ wordUntil = 0;
177
+ setTimeout(handOn, 0);
178
+ }
179
+ };
180
+ document.addEventListener("focus", came);
181
+ addEventListener("blur", () => {
182
+ holds = false;
183
+ look();
184
+ });
185
+ addEventListener("focus", (event) => {
186
+ if (event.target === window) {
187
+ came();
188
+ // Where a move can go on from inside this event (P136): Firefox, from the host's <body>.
189
+ if (document.activeElement !== frame) {
190
+ frame.focus();
191
+ }
192
+ }
161
193
  look();
162
194
  });
163
195
  document.addEventListener("visibilitychange", look);
@@ -184,6 +216,14 @@ export const FRAME_SHELL_RUNTIME = String.raw`(() => {
184
216
  if (data.method === PREFIX + "look" && typeof n === "number" && n >= 0 && Math.floor(n) === n) {
185
217
  look(n);
186
218
  }
219
+ // The host's own move into the frame, done (P136): on to the page.
220
+ if (data.method === PREFIX + "focus") {
221
+ if (holds) {
222
+ handOn();
223
+ } else {
224
+ wordUntil = performance.now() + 250;
225
+ }
226
+ }
187
227
  return;
188
228
  }
189
229
  const child = frame.contentWindow;