@botiverse/porthole 0.14.13 → 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.
@@ -581,9 +581,10 @@ export function createHost(config, options = {}) {
581
581
  focusMark(id) {
582
582
  // Host → frame only, and kept for no later frame (P134). A mark that has gone, or has no
583
583
  // marker, is nothing to ask for, and no fault: the host's card closed with the mark's.
584
+ // Stamped as it is sent: a frame judges by that how old the word is as it takes it (P137).
584
585
  needsAnnotate("focusMark");
585
586
  if (marks.some((mark) => mark.id === id && hasMarker(mark))) {
586
- toFrame(ANNOTATE_METHODS.focusMark, { id });
587
+ toFrame(ANNOTATE_METHODS.focusMark, { id, at: Date.now() });
587
588
  }
588
589
  },
589
590
  };
@@ -338,11 +338,12 @@ export interface AnnotationControls {
338
338
  *
339
339
  * On a calm page it lands at once, from anywhere on the host's page. While the frame is finding
340
340
  * its marks (a `show` just sent, the content just changed) it waits, and is then dropped unless
341
- * the focus is in the frame by then (P135), so a word that comes late takes no keyboard from a
342
- * person who moved on. Nothing says it was dropped: if the frame isn't your page's
341
+ * the focus is in the frame by then (P135). One the frame takes more than 100 ms after you sent
342
+ * it (its page is busy) is held to the same test (P137), so a word that comes late takes no
343
+ * keyboard from a person who moved on. Nothing says it was dropped: if the frame isn't your page's
343
344
  * `document.activeElement` soon after and the person hasn't moved on, call `focus()` and then
344
- * `focusMark(id)` again. Known gap: on a nested page that had the focus, `focus()` doesn't bring
345
- * it back into the page, so a second call that waits is dropped too (ADOPTING).
345
+ * `focusMark(id)` again. On a nested page only `focus()` reaches the page (P136): the frame's own
346
+ * `focus()` stops at its shell, and a second call that waits is dropped.
346
347
  */
347
348
  focusMark(id: string): void;
348
349
  }
@@ -103,6 +103,12 @@ export declare const SHELL_BEAT_METHOD = "porthole/shell/beat";
103
103
  * that names the ask (`asked`). The host asks as it hears focus move into the frame.
104
104
  */
105
105
  export declare const SHELL_LOOK_METHOD = "porthole/shell/look";
106
+ /**
107
+ * The host's word to a nested page's shell (P136) that it moved the focus into the frame: pass it on
108
+ * to the page, in this task, not in the focus event (where the shell's move doesn't take). Sent by
109
+ * `display.focus()` alone; a page has no way to say it.
110
+ */
111
+ export declare const SHELL_FOCUS_METHOD = "porthole/shell/focus";
106
112
  /** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
107
113
  export declare const SHELL_METHOD_PREFIX = "porthole/shell/";
108
114
  /** A page's word that it used storage, once per load (P111): never a key or a value. */
@@ -11,6 +11,12 @@ export const SHELL_BEAT_METHOD = "porthole/shell/beat";
11
11
  * that names the ask (`asked`). The host asks as it hears focus move into the frame.
12
12
  */
13
13
  export const SHELL_LOOK_METHOD = "porthole/shell/look";
14
+ /**
15
+ * The host's word to a nested page's shell (P136) that it moved the focus into the frame: pass it on
16
+ * to the page, in this task, not in the focus event (where the shell's move doesn't take). Sent by
17
+ * `display.focus()` alone; a page has no way to say it.
18
+ */
19
+ export const SHELL_FOCUS_METHOD = "porthole/shell/focus";
14
20
  /** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
15
21
  export const SHELL_METHOD_PREFIX = "porthole/shell/";
16
22
  /** A page's word that it used storage, once per load (P111): never a key or a value. */
@@ -1,5 +1,5 @@
1
1
  import { DOOR_SANDBOX_TOKENS } from "../compile/policy.js";
2
- import { SHELL_BEAT_METHOD, SHELL_LOOK_METHOD, SHELL_METHOD_PREFIX, SHELL_STATE_METHOD, } from "../isolation/types.js";
2
+ import { SHELL_BEAT_METHOD, SHELL_FOCUS_METHOD, SHELL_LOOK_METHOD, SHELL_METHOD_PREFIX, SHELL_STATE_METHOD, } from "../isolation/types.js";
3
3
  import { postMessageTransport } from "../transport/post-message.js";
4
4
  import { focusGuard } from "./focus-guard.js";
5
5
  /** A shell's own message (P111), by its namespace. */
@@ -169,6 +169,11 @@ export const webPlatform = {
169
169
  },
170
170
  focus() {
171
171
  guard.focus(frame);
172
+ // A nested page (P136): the move stops at its shell on every engine, one way or another,
173
+ // and only the shell can pass it on. Only a move that landed: the shell asks no more of it.
174
+ if (nested && view.document.activeElement === frame) {
175
+ opened.send({ jsonrpc: "2.0", method: SHELL_FOCUS_METHOD });
176
+ }
172
177
  },
173
178
  onLoad(listener) {
174
179
  loaded.add(listener);
@@ -159,7 +159,8 @@ export interface PortholeFrameHandle {
159
159
  * once Escape closed your own view of that mark. Nothing happens for an id with no marker, or
160
160
  * while no display runs. A config without `annotate`: `onHostError`, kind `"annotations"`. While
161
161
  * the frame is finding its marks it waits, and is dropped unless the focus is in the frame by
162
- * then (P135): call it again after your own move of the focus into the frame.
162
+ * then (P135), and so is one a busy page takes late (P137): call it again after your own move of
163
+ * the focus into the frame.
163
164
  */
164
165
  focusMark(id: string): void;
165
166
  /**
@@ -16,6 +16,16 @@ export declare const MARKER_HIT: string;
16
16
  * `alt`) what follows the tag in the label. An element with neither has no words.
17
17
  */
18
18
  export declare const MARKER_NAME: string;
19
+ /**
20
+ * Whether a host's `focusMark` is too old to land unasked (P137): `at` is the host's `Date.now()` as
21
+ * it sent the word, `now` the shell's, kept before content runs. Both read the one wall clock of
22
+ * this machine, the only clock two realms share (`performance.now()` counts from each one's own
23
+ * start). No number is an older host's word, which can't be known fresh. A word from ahead of the
24
+ * clock has the same bound behind it: two processes can read the clock a little apart, and past
25
+ * that the clock was set back, and the age says nothing. Comparisons only, nothing a page can
26
+ * patch, and a word that makes no number (`NaN`, `Infinity`) passes neither test.
27
+ */
28
+ export declare const WORD_LATE: string;
19
29
  /**
20
30
  * The shell's annotation runtime (P053), spliced into the shell's runtime (`__ANNOTATE__`) when
21
31
  * the config declares `annotate`, so it runs before any content does, with the DOM's own
@@ -39,8 +49,8 @@ export declare const MARKER_NAME: string;
39
49
  * focus on it (P133), is reported (`activated`), and the content's own handlers never see it; a
40
50
  * draft is drawn apart, a dashed line and a hollow bubble with no number, and has a marker with
41
51
  * or without a count; the host's `focusMark` (P134) puts the focus on a marker that is there, and
42
- * tells nothing back; one that had to wait for the marks lands only if the focus is still in this
43
- * document (P135);
52
+ * tells nothing back; one that had to wait for the marks (P135), or that this document took late
53
+ * (P137), lands only if the focus is in this document by then;
44
54
  * - following: while a mark has a marker, once a scroll, a resize or a change of the content
45
55
  * settles, the marks that moved since the host was last told are reported, at most once a
46
56
  * second, so the host's own UI beside a mark can follow;
@@ -54,6 +54,22 @@ export const MARKER_NAME = String.raw `(mark) => {
54
54
  const what = mark.draft ? "Draft comment" : mark.count === 1 ? "1 comment" : mark.count > 1 ? mark.count + " comments" : "Comment";
55
55
  return words === "" ? what : what + ' on "' + words + '"';
56
56
  }`;
57
+ /**
58
+ * Whether a host's `focusMark` is too old to land unasked (P137): `at` is the host's `Date.now()` as
59
+ * it sent the word, `now` the shell's, kept before content runs. Both read the one wall clock of
60
+ * this machine, the only clock two realms share (`performance.now()` counts from each one's own
61
+ * start). No number is an older host's word, which can't be known fresh. A word from ahead of the
62
+ * clock has the same bound behind it: two processes can read the clock a little apart, and past
63
+ * that the clock was set back, and the age says nothing. Comparisons only, nothing a page can
64
+ * patch, and a word that makes no number (`NaN`, `Infinity`) passes neither test.
65
+ */
66
+ export const WORD_LATE = String.raw `(at, now) => {
67
+ if (typeof at !== "number") {
68
+ return true;
69
+ }
70
+ const age = now - at;
71
+ return !(age > -100 && age < 100);
72
+ }`;
57
73
  /**
58
74
  * The shell's annotation runtime (P053), spliced into the shell's runtime (`__ANNOTATE__`) when
59
75
  * the config declares `annotate`, so it runs before any content does, with the DOM's own
@@ -77,8 +93,8 @@ export const MARKER_NAME = String.raw `(mark) => {
77
93
  * focus on it (P133), is reported (`activated`), and the content's own handlers never see it; a
78
94
  * draft is drawn apart, a dashed line and a hollow bubble with no number, and has a marker with
79
95
  * or without a count; the host's `focusMark` (P134) puts the focus on a marker that is there, and
80
- * tells nothing back; one that had to wait for the marks lands only if the focus is still in this
81
- * document (P135);
96
+ * tells nothing back; one that had to wait for the marks (P135), or that this document took late
97
+ * (P137), lands only if the focus is in this document by then;
82
98
  * - following: while a mark has a marker, once a scroll, a resize or a change of the content
83
99
  * settles, the marks that moved since the host was last told are reported, at most once a
84
100
  * second, so the host's own UI beside a mark can follow;
@@ -122,6 +138,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
122
138
  const removeAllRanges = Selection.prototype.removeAllRanges;
123
139
  const focusElement = HTMLElement.prototype.focus;
124
140
  const hasFocus = Document.prototype.hasFocus;
141
+ const wallClock = Date.now;
125
142
  const elementRect = Element.prototype.getBoundingClientRect;
126
143
  const rangeRect = Range.prototype.getBoundingClientRect;
127
144
  const rangeRects = Range.prototype.getClientRects;
@@ -1074,6 +1091,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1074
1091
  let waitingForContent = false;
1075
1092
  let pendingFocus = null;
1076
1093
  let pendingMarker = null;
1094
+ // Asked through the kept function: a page that says it has the focus gets no landing the
1095
+ // platform would refuse (P135).
1096
+ const focusIsHere = () => callOf(hasFocus, document, []) === true;
1097
+ const wordLate = ${WORD_LATE};
1077
1098
  const settling = () => anchorTimer !== 0 || waitingForContent || marks.some((mark) => mark.state === null);
1078
1099
  const scheduleAnchor = (all) => {
1079
1100
  if (all) {
@@ -1117,10 +1138,9 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1117
1138
  pendingMarker = null;
1118
1139
  // Parked, the host's word is old: the person may have moved on, and a marker's focus
1119
1140
  // takes the keyboard with no gesture. So it lands only if the focus is still in this
1120
- // document, asked through the kept function: a page that says it has the focus gets
1121
- // no landing the platform would refuse. Otherwise it is dropped (P135).
1122
- if (callOf(hasFocus, document, []) === true) {
1123
- focusMark(id);
1141
+ // document. Otherwise it is dropped (P135).
1142
+ if (focusIsHere()) {
1143
+ focusMark(id, false);
1124
1144
  }
1125
1145
  }
1126
1146
  }, wait);
@@ -1231,10 +1251,11 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1231
1251
  // markers yet, so it waits for them, as focus does; then a marker that isn't there, or has
1232
1252
  // stepped aside for picking, is nothing to do. The kept function, so a page that patched
1233
1253
  // focus isn't handed the marker from inside the closed root. The shell's focus listener
1234
- // lights it and brings it into view; nothing is told. A call that isn't parked reads no
1235
- // focus: it is the host's word just now, and after its card closed the focus is on the
1236
- // host's body, so this document has none yet. Only the landing of a parked one asks (P135).
1237
- const focusMark = (id) => {
1254
+ // lights it and brings it into view; nothing is told. A fresh word reads no focus: after the
1255
+ // host's card closed the focus is on the host's body, so this document has none yet. One
1256
+ // parked is asked as it lands (P135), and one this document took late (P137: late, by when
1257
+ // the host sent it: a busy page doesn't park it) is asked here: its moment has passed.
1258
+ const focusMark = (id, late) => {
1238
1259
  if (settling()) {
1239
1260
  pendingMarker = id;
1240
1261
  return;
@@ -1242,6 +1263,9 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1242
1263
  if (mode.elements || !isShown(id)) {
1243
1264
  return;
1244
1265
  }
1266
+ if (late && !focusIsHere()) {
1267
+ return;
1268
+ }
1245
1269
  for (let i = 0; i < markers.length; i += 1) {
1246
1270
  if (markers[i].id === id) {
1247
1271
  callOf(focusElement, markers[i].element, [{ preventScroll: true }]);
@@ -1685,7 +1709,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1685
1709
  break;
1686
1710
  }
1687
1711
  case M.focusMark:
1688
- focusMark(String(params.id));
1712
+ focusMark(String(params.id), wordLate(params.at, callOf(wallClock, undefined, [])));
1689
1713
  break;
1690
1714
  case M.clear:
1691
1715
  track(null);
@@ -23,7 +23,12 @@
23
23
  * - renews the page's sealed files' address before it ends, and gives the page the new one
24
24
  * (`porthole/files-renewed`): the page's own loads aren't its origin's (an opaque origin's never
25
25
  * are), so only the shell, on that origin, may renew it (P083);
26
- * - passes its focus to the page (the host's own move into the frame, or a Tab).
26
+ * - passes its focus to the page: at the focus event where that takes (Firefox, from the host's
27
+ * `<body>`), and on the host's word that it moved it there (`porthole/shell/focus`, P136), where
28
+ * it doesn't: a frame's move inside the focus event that made it the focused frame sets the
29
+ * shell's `activeElement` and goes no further (Chromium, WebKit), and from a focused element of
30
+ * the host's the window hears no focus event at all (Firefox). A later task's `frame.focus()`
31
+ * goes through on all of them, the frame blurred first as the failed one left it active.
27
32
  *
28
33
  * Plain ES2020, no imports and no build step, like the runtime. `__PLAN__` is its plan.
29
34
  */
@@ -25,7 +25,12 @@ import { hostOriginProblem, onNestedLabel } from "../isolation/served.js";
25
25
  * - renews the page's sealed files' address before it ends, and gives the page the new one
26
26
  * (`porthole/files-renewed`): the page's own loads aren't its origin's (an opaque origin's never
27
27
  * are), so only the shell, on that origin, may renew it (P083);
28
- * - passes its focus to the page (the host's own move into the frame, or a Tab).
28
+ * - passes its focus to the page: at the focus event where that takes (Firefox, from the host's
29
+ * `<body>`), and on the host's word that it moved it there (`porthole/shell/focus`, P136), where
30
+ * it doesn't: a frame's move inside the focus event that made it the focused frame sets the
31
+ * shell's `activeElement` and goes no further (Chromium, WebKit), and from a focused element of
32
+ * the host's the window hears no focus event at all (Firefox). A later task's `frame.focus()`
33
+ * goes through on all of them, the frame blurred first as the failed one left it active.
29
34
  *
30
35
  * Plain ES2020, no imports and no build step, like the runtime. `__PLAN__` is its plan.
31
36
  */
@@ -151,12 +156,39 @@ export const FRAME_SHELL_RUNTIME = String.raw `(() => {
151
156
  };
152
157
  requestAnimationFrame(tick);
153
158
  setInterval(look, 50);
154
- addEventListener("blur", look);
155
- addEventListener("focus", (event) => {
156
- // The host's move into the frame (or a Tab) lands here: on to the page.
157
- if (event.target === window && document.activeElement !== frame) {
159
+
160
+ // Whether the focus is on the shell's own document, not through it on the page's (P136). Firefox
161
+ // tells a move from a focused element of the host's on the document alone. The host's word needs
162
+ // this: it never moves a focus that isn't here, and a page that has it hears no blur.
163
+ let holds = false;
164
+ // Until when a word that came ahead of the focus it speaks of holds (it crosses processes too).
165
+ let wordUntil = 0;
166
+ const handOn = () => {
167
+ if (holds && document.hasFocus()) {
168
+ frame.blur();
158
169
  frame.focus();
159
170
  }
171
+ };
172
+ const came = () => {
173
+ holds = true;
174
+ if (performance.now() < wordUntil) {
175
+ wordUntil = 0;
176
+ setTimeout(handOn, 0);
177
+ }
178
+ };
179
+ document.addEventListener("focus", came);
180
+ addEventListener("blur", () => {
181
+ holds = false;
182
+ look();
183
+ });
184
+ addEventListener("focus", (event) => {
185
+ if (event.target === window) {
186
+ came();
187
+ // Where a move can go on from inside this event (P136): Firefox, from the host's <body>.
188
+ if (document.activeElement !== frame) {
189
+ frame.focus();
190
+ }
191
+ }
160
192
  look();
161
193
  });
162
194
  document.addEventListener("visibilitychange", look);
@@ -183,6 +215,14 @@ export const FRAME_SHELL_RUNTIME = String.raw `(() => {
183
215
  if (data.method === PREFIX + "look" && typeof n === "number" && n >= 0 && Math.floor(n) === n) {
184
216
  look(n);
185
217
  }
218
+ // The host's own move into the frame, done (P136): on to the page.
219
+ if (data.method === PREFIX + "focus") {
220
+ if (holds) {
221
+ handOn();
222
+ } else {
223
+ wordUntil = performance.now() + 250;
224
+ }
225
+ }
186
226
  return;
187
227
  }
188
228
  const child = frame.contentWindow;
package/docs/ADOPTING.md CHANGED
@@ -420,9 +420,11 @@ composer.onClose(() => display.annotations.clearSelection());
420
420
  their whole box (a composer's button, a card), a newer shell gives `selected`, each attached
421
421
  result and `tracked` a `lastLineDocumentRect`: the last line with words on it, in the document's
422
422
  coordinates (an element's whole box: it has no lines), unclamped as `documentRect` is. `selected`
423
- carries the `scroll` it was read at too; an `anchored` report and `tracked` already do. A line's
424
- end in the frame's viewport is `x + width - scroll.x`, its bottom `y + height - scroll.y`. Clip
425
- what you draw from it, as above, and keep `rect` where it is absent (an older shell):
423
+ carries the `scroll` it was read at too; an `anchored` report and `tracked` already do, and
424
+ `createHost` drops a report with a last line and no `scroll`, so where you have the line you have
425
+ the scroll (P137). A line's end in the frame's viewport is `x + width - scroll.x`, its bottom
426
+ `y + height - scroll.y`. Clip what you draw from it, as above, and keep `rect` where it is absent
427
+ (an older shell):
426
428
 
427
429
  ```js
428
430
  display.on("annotation", (report) => {
@@ -453,7 +455,10 @@ composer.onClose(() => display.annotations.clearSelection());
453
455
  can forge `activated` while the person really is there, which this doesn't stop. So moving the
454
456
  keyboard into your view on it is your own step outside "takes no focus" above, and a page can
455
457
  bring it about: gate whatever posts from that view (a Reply in a frame-opened card) yourself;
456
- Porthole can't. When the person's key closes your view of that mark from inside it (Escape, or a
458
+ Porthole can't. That goes for keys too: with the focus in your view the person's next keys reach
459
+ your document, so the view's own key handlers and your page-wide shortcuts that write (an `r` that
460
+ resolves, Cmd+Enter that posts) need the same gate (P137). When the person's key closes your view
461
+ of that mark from inside it (Escape, or a
457
462
  Tab past its first or last control), whether or not the keyboard got there through `activated`,
458
463
  and only then, close it and call
459
464
  `display.annotations.focusMark(id)` (React: `focusMark(id)` on the `ref`) to put the keyboard back
@@ -464,10 +469,14 @@ composer.onClose(() => display.annotations.clearSelection());
464
469
  the way that holds.
465
470
  On a calm page that lands at once, from your `<body>`. While the frame is finding its marks (a
466
471
  `show` just sent, which many hosts send as a card closes, or content that just changed) the word
467
- waits, up to a second, and is then dropped unless the focus is in the frame by then, so it takes no
468
- keyboard from a person who moved on ([P135](DECISIONS.md)). As your card has just closed, the focus
469
- is on your `<body>`, so a word that waited is dropped, and nothing tells you: **call `focusMark`
470
- again after your own move of the focus into the frame.**
472
+ waits, up to a second, and is then dropped unless the focus is in the frame by then. A word the
473
+ frame takes more than 100 ms after you sent it, because its page is busy, is held to the same
474
+ test. So a late word takes no keyboard from a person who moved on ([P135](DECISIONS.md),
475
+ [P137](DECISIONS.md)). As your card has just closed, the focus is on your `<body>`, so a word that
476
+ waited or came late is dropped, and nothing tells you: **call `focusMark` again after your own
477
+ move of the focus into the frame.** Call it as your close runs, not after other work: its age
478
+ starts when you call it, and where the browser runs the frame on your thread, what your task does
479
+ next counts too.
471
480
 
472
481
  ```js
473
482
  closeCard();
@@ -486,15 +495,20 @@ composer.onClose(() => display.annotations.clearSelection());
486
495
  that step: it is only ever taken for the page's from a text field, and this one starts on `<body>`.
487
496
  An id with no marker then leaves the focus in the frame, with the keys going to the page.
488
497
 
489
- **Known gap, nested pages (P135).** On a nested page that had the focus, `display.focus()` doesn't
490
- bring it back into the page (measured on Chromium, WebKit and Firefox), so a `focusMark` that waits
491
- is dropped even after it, and the person is left without the marker. On a calm page the second
492
- call doesn't wait and lands. On a page that is changing, it doesn't, and nothing tells you: keep
493
- your own list of marks as the way back. A fix to the shell is open; this paragraph goes with it.
498
+ **Nested pages (P136).** `display.focus()` reaches a nested page on every engine, whether or not
499
+ it had the focus. Two ways don't:
500
+ - The frame's own `focus()`, which the React step above is: it stops at the page's shell (Chromium
501
+ and WebKit from anywhere, Firefox from a focused element of yours), so a `focusMark` that waits
502
+ is dropped even after it, and nothing tells you. On a calm page the second call doesn't wait and
503
+ lands. On a page that is changing, keep your own list of marks as the way back.
504
+ - `display.focus()` inside a key's own handler, on Firefox (measured on a nested page): it moves
505
+ nothing. Call it from a task, as the timer above does.
494
506
 
495
507
  Without the second call, nothing changes on a calm page. On a busy one, a word that the frame
496
508
  finishes with before your own move is lost where it used to land, so the person gets the frame and
497
- not the marker. That is the cost of never pulling the keyboard into the page.
509
+ not the marker. That is the cost of never pulling the keyboard into the page. Upgrade the host and
510
+ the content server together: a newer shell takes a word from an older `createHost`, which has no
511
+ stamp, as a late one (the second call still lands), and an older shell ignores the stamp.
498
512
  - **Labels and quotes are the page's text**: shown only as text. Porthole takes out of a label what
499
513
  the person can't see; a quote (`exact`) keeps it, to be found again. Hand either to a model only
500
514
  as the page's words.
@@ -215,6 +215,7 @@ Host app Shell (its own origin) Page (opaque child)
215
215
  │── the host's messages ──────►│── postMessage ───────────────►│
216
216
  │◄── porthole/shell/state ─────│ its own activation, its focus │
217
217
  │── porthole/shell/look ──────►│ look now (as a move is heard) │
218
+ │── porthole/shell/focus ─────►│ display.focus(): on to the ──►│ the page's window
218
219
  ```
219
220
 
220
221
  ### URL frame