@botiverse/porthole 0.14.15 → 0.14.17

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 (45) hide show
  1. package/CHANGELOG.md +50 -0
  2. package/dist/annotate/types.d.ts +10 -1
  3. package/dist/annotate/validate.d.ts +9 -2
  4. package/dist/annotate/validate.js +9 -2
  5. package/dist/check/page-source.js +1 -1
  6. package/dist/conformance/harness-source.js +1 -1
  7. package/dist/host/create-host.js +11 -8
  8. package/dist/host/types.d.ts +13 -6
  9. package/dist/isolation/served.d.ts +8 -0
  10. package/dist/isolation/served.js +16 -0
  11. package/dist/react/frame.d.ts +9 -1
  12. package/dist/react/frame.js +23 -3
  13. package/dist/server/host.d.ts +14 -1
  14. package/dist/server/host.js +8 -3
  15. package/dist/server/nested.d.ts +5 -4
  16. package/dist/server/nested.js +8 -6
  17. package/dist/server/pages.d.ts +16 -2
  18. package/dist/server/pages.js +51 -16
  19. package/dist/server/server.js +26 -2
  20. package/dist/server/types.d.ts +8 -0
  21. package/dist/shell/annotate.d.ts +5 -3
  22. package/dist/shell/annotate.js +36 -16
  23. package/dist/shell/frame.d.ts +6 -0
  24. package/dist/shell/frame.js +16 -3
  25. package/dist/shell/runtime.d.ts +10 -0
  26. package/dist/shell/runtime.js +72 -26
  27. package/docs/ADOPTING.md +40 -22
  28. package/docs/DECISIONS.md +318 -3
  29. package/docs/DESIGN.md +19 -10
  30. package/docs/THREAT_MODEL.md +39 -7
  31. package/package.json +1 -1
  32. package/src/annotate/types.ts +10 -1
  33. package/src/annotate/validate.ts +15 -3
  34. package/src/host/create-host.ts +13 -14
  35. package/src/host/types.ts +13 -6
  36. package/src/isolation/served.ts +21 -0
  37. package/src/react/frame.tsx +36 -5
  38. package/src/server/host.ts +22 -4
  39. package/src/server/nested.ts +13 -5
  40. package/src/server/pages.ts +72 -18
  41. package/src/server/server.ts +32 -1
  42. package/src/server/types.ts +8 -0
  43. package/src/shell/annotate.ts +36 -16
  44. package/src/shell/frame.ts +22 -3
  45. package/src/shell/runtime.ts +73 -26
@@ -109,9 +109,11 @@ export const WORD_LATE = String.raw`(at, now) => {
109
109
  * - the last line (P133): where a selection or a mark's words end, in the document's coordinates
110
110
  * too (`lastLineDocumentRect`), so a host places its UI after them;
111
111
  * - the selection followed (P138): what the last `selected` reported (the element picked, or the
112
- * words selected) is kept, and while the host follows it (`track` with `selection`) it is drawn
113
- * in the layer and its boxes are reported as a followed mark's are (`selectionTracked`), with
114
- * whether it is in view, or that it is gone; it takes no pointer, no focus and no key.
112
+ * words selected) is kept while the host follows the selection (`track` with `selection`) or said
113
+ * at `start` that it will (`keepSelection`, P140), and nothing is kept otherwise; while followed
114
+ * it is drawn in the layer and its boxes are reported as a followed mark's are
115
+ * (`selectionTracked`), with whether it is in view, or that it is gone; it takes no pointer, no
116
+ * focus and no key.
115
117
  *
116
118
  * It shares the realm with the content, which can interfere with all of it: the host takes its
117
119
  * reports as UI hints only.
@@ -440,20 +442,25 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
440
442
  // The selection last reported as selected (P138): its anchor, and what it is in the page (the
441
443
  // element picked, or a copy of the selection's range, which the page's changes keep up to
442
444
  // date and which stays when the page's own selection goes). Followed while the host asks
443
- // (track with selection), and drawn then. Each new selected replaces it.
445
+ // (track with selection), and drawn then. Each new selected replaces it. Kept only while the
446
+ // host follows the selection, or said at its last start that it will (keepSelection, P140):
447
+ // for any other host nothing is kept, as before P138.
444
448
  let held = null;
445
449
  let followingSelection = false;
450
+ let keeping = false;
451
+ const keeps = () => followingSelection || keeping;
446
452
  // What the host was last told of it: "attached", "orphaned", or null (nothing yet).
447
453
  let heldTold = null;
448
454
  const heldGone = (found) => (found.range ? found.range.collapsed || !found.range.startContainer.isConnected : !found.element.isConnected);
449
455
  const heldShown = () => followingSelection && held !== null && heldTold !== "orphaned" && !heldGone(held.found);
450
- // The element just picked (P138, Tenny's review): it keeps its outline after selected, so
451
- // there is no gap before the host follows it, and the follow's highlight takes over where it
452
- // does. Without a follow (an older host) it ends as a selection does: the next pick or
453
- // selection, the host's clearSelection, a mode started or stopped, clear, Escape, or the
454
- // element leaving the page. Not unselected: a selection made after the pick has already
455
- // ended it as it was reported, so the one unselected can clear is one from before, which
456
- // the pick's own click takes away when text is selected too.
456
+ // The element just picked (P138, Tenny's review): for a host that will follow it
457
+ // (keepSelection, P140), it keeps its outline after selected, so there is no gap before the
458
+ // host follows it, and the follow's highlight takes over where it does. For any other host
459
+ // the outline goes with the pick, as before P138. Until the follow comes it ends as a
460
+ // selection does: the next pick or selection, the host's clearSelection, a mode started or
461
+ // stopped, clear, Escape, or the element leaving the page. Not unselected: a selection made
462
+ // after the pick has already ended it as it was reported, so the one unselected can clear is
463
+ // one from before, which the pick's own click takes away when text is selected too.
457
464
  let picked = null;
458
465
  const endPick = () => {
459
466
  if (picked !== null) {
@@ -1094,6 +1101,10 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1094
1101
  if (followingSelection) {
1095
1102
  picked = null;
1096
1103
  }
1104
+ // Its end lets the selection go, unless the host said it follows it again (P140).
1105
+ if (!keeps()) {
1106
+ held = null;
1107
+ }
1097
1108
  trackedBox = null;
1098
1109
  trackedView = null;
1099
1110
  heldTold = null;
@@ -1104,9 +1115,10 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1104
1115
  draw();
1105
1116
  }
1106
1117
  };
1107
- // A new selected (P138): what is followed, if the selection is, from the next frame on.
1118
+ // A new selected (P138): what is followed, if the selection is, from the next frame on; kept
1119
+ // only for a host that follows it or will (P140).
1108
1120
  const holdSelected = (anchor, found) => {
1109
- held = { anchor, found, tried: 0 };
1121
+ held = keeps() ? { anchor, found, tried: 0 } : null;
1110
1122
  if (followingSelection) {
1111
1123
  trackedBox = null;
1112
1124
  heldTold = null;
@@ -1657,7 +1669,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1657
1669
  }
1658
1670
  swallowUntil = performance.now() + 2000;
1659
1671
  holdSelected(anchor, { element });
1660
- picked = followingSelection ? null : element;
1672
+ picked = keeping && !followingSelection ? element : null;
1661
1673
  redraw();
1662
1674
  tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
1663
1675
  }, HOLD_MS),
@@ -1707,8 +1719,9 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1707
1719
  hover = null;
1708
1720
  setCursor(false);
1709
1721
  holdSelected(anchor, { element });
1710
- // Its outline stays (P138), now without its name, until the host follows it or it ends.
1711
- picked = followingSelection ? null : element;
1722
+ // Its outline stays (P138), now without its name, until the host follows it or it ends;
1723
+ // only for a host that will follow it (P140): for any other it goes with the pick.
1724
+ picked = keeping && !followingSelection ? element : null;
1712
1725
  draw();
1713
1726
  tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
1714
1727
  }, true);
@@ -1805,6 +1818,13 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1805
1818
  switch (data.method) {
1806
1819
  case M.start:
1807
1820
  mode = { elements: params.elements === true, text: params.text === true, hold: params.elements === "hold" };
1821
+ // Whether the host will follow what is selected (P140): only then is it kept before
1822
+ // the host follows it. A stop leaves it, so a stop sent as the composer opens doesn't
1823
+ // take the selection away before the follow comes.
1824
+ keeping = params.keepSelection === true;
1825
+ if (!keeps()) {
1826
+ held = null;
1827
+ }
1808
1828
  hover = null;
1809
1829
  picked = null;
1810
1830
  reported = null;
@@ -1,5 +1,5 @@
1
1
  import { PAGE_SANDBOX_TOKENS } from "../compile/policy.ts";
2
- import { hostOriginProblem, onNestedLabel } from "../isolation/served.ts";
2
+ import { framedByProblem, hostOriginProblem, onNestedLabel } from "../isolation/served.ts";
3
3
 
4
4
  /**
5
5
  * Porthole's shell for a nested page (P111): the whole document at the address the host frames,
@@ -81,7 +81,9 @@ export const FRAME_SHELL_RUNTIME = String.raw`(() => {
81
81
  const web = plan.origins.filter((origin) => origin.indexOf("https://") === 0 || origin.indexOf("http://") === 0);
82
82
  // To the host: each web host origin (only the parent's is delivered); a desktop app's own scheme
83
83
  // is no target a browser takes, so where one is listed and the parent isn't a known web origin,
84
- // "*" (frame-ancestors holds the parent to the host origins; nothing said here is secret).
84
+ // "*" (frame-ancestors holds the parent to the host origins; nothing said here is secret). Where
85
+ // it names an outer page above them too (the host's framedBy, P141: plan.strictParent), the parent
86
+ // may be the outer page: "*" then goes only to a parent the engine names as a host origin.
85
87
  const toHost = (message) => {
86
88
  if (!framed) {
87
89
  return;
@@ -92,7 +94,11 @@ export const FRAME_SHELL_RUNTIME = String.raw`(() => {
92
94
  } catch (_) {}
93
95
  }
94
96
  const parent = location.ancestorOrigins && location.ancestorOrigins.length > 0 ? location.ancestorOrigins[0] : null;
95
- if (web.length < plan.origins.length && (parent === null || web.indexOf(parent) === -1)) {
97
+ if (
98
+ web.length < plan.origins.length &&
99
+ (parent === null || web.indexOf(parent) === -1) &&
100
+ (plan.strictParent !== true || (parent !== null && plan.origins.indexOf(parent) !== -1))
101
+ ) {
96
102
  try {
97
103
  window.parent.postMessage(message, "*");
98
104
  } catch (_) {}
@@ -264,6 +270,12 @@ export { SHELL_METHOD_PREFIX, SHELL_STATE_METHOD } from "../isolation/types.ts";
264
270
  export interface FrameShellOptions {
265
271
  /** The host origins: the shell takes messages from its parent only from these. */
266
272
  readonly origins: readonly string[];
273
+ /**
274
+ * Origins of an outer page that may be an ancestor above a host origin's page (P141): in the
275
+ * shell's `frame-ancestors` after `origins` (`nestedShellResponse`), never heard or told. Where
276
+ * there are any, the shell says `*` only to a parent the engine names as a host origin.
277
+ */
278
+ readonly framedBy?: readonly string[];
267
279
  /** The page's address: absolute, on the shell's own origin, under `/__porthole/f/`. */
268
280
  readonly page: string;
269
281
  /** The page frame's accessible name. */
@@ -287,6 +299,12 @@ export function frameShellScript(options: FrameShellOptions): string {
287
299
  throw new TypeError(`frameShellScript: ${problem}`);
288
300
  }
289
301
  }
302
+ for (const origin of options.framedBy ?? []) {
303
+ const problem = framedByProblem(origin);
304
+ if (problem !== null || options.origins.includes(origin)) {
305
+ throw new TypeError(`frameShellScript: framedBy: ${problem ?? `${origin} is a host origin`}`);
306
+ }
307
+ }
290
308
  let page: URL;
291
309
  try {
292
310
  page = new URL(options.page);
@@ -305,6 +323,7 @@ export function frameShellScript(options: FrameShellOptions): string {
305
323
  return FRAME_SHELL_RUNTIME.replace("__PLAN__", () =>
306
324
  scriptJson({
307
325
  origins: options.origins,
326
+ ...((options.framedBy ?? []).length === 0 ? {} : { strictParent: true }),
308
327
  page: page.href,
309
328
  sandbox: PAGE_SANDBOX_TOKENS.join(" "),
310
329
  ...(options.title === undefined ? {} : { title: options.title }),
@@ -92,6 +92,43 @@ export const ONCE = String.raw`(passesAsIs, toText) => (value) => {
92
92
  return text;
93
93
  }`;
94
94
 
95
+ /**
96
+ * The shell's handshake with its host (P085, P139), spliced into the runtime as
97
+ * `HANDSHAKE(topLevel, ask, answered, none, later)`. On a tab of its own (`topLevel`: the window is
98
+ * its own top, so its parent is itself and no host can hear it) there is no host to ask: `none()`
99
+ * at once, and nothing is asked. In a frame it asks (`ask()`, a promise of the host's answer) up to
100
+ * 40 times, 250 ms apart (`later(run, ms)`), since the host may start listening after the shell
101
+ * runs; the first answer is taken (`answered(result)`), once. After the 40th try with no answer,
102
+ * `none()`; an answer that comes later still is taken.
103
+ */
104
+ export const HANDSHAKE = String.raw`(topLevel, ask, answered, none, later) => {
105
+ if (topLevel === true) {
106
+ none();
107
+ return;
108
+ }
109
+ let initialized = false;
110
+ let tries = 0;
111
+ const initialize = () => {
112
+ if (initialized) {
113
+ return;
114
+ }
115
+ if (tries >= 40) {
116
+ none();
117
+ return;
118
+ }
119
+ tries += 1;
120
+ ask().then((result) => {
121
+ if (initialized) {
122
+ return;
123
+ }
124
+ initialized = true;
125
+ answered(result);
126
+ }, () => {});
127
+ later(initialize, 250);
128
+ };
129
+ initialize();
130
+ }`;
131
+
95
132
  /**
96
133
  * The shell's runtime: the code that runs first in the frame, before any content. Plain ES2020,
97
134
  * no imports and no build step, so every engine (a browser frame now, a native web view later)
@@ -155,6 +192,9 @@ export const SHELL_RUNTIME = String.raw`(() => {
155
192
  // such name goes on the shell's own script element (data-porthole-unfixed, for a test or a
156
193
  // person to see) and, once the shell can speak, to the host as an error report.
157
194
  const shellScript = document.currentScript;
195
+ // The platform's own, kept before the shell's guards wrap it: the shell marks the document's root
196
+ // with it (data-porthole-host, P139).
197
+ const setAttributeOfShell = Element.prototype.setAttribute;
158
198
  const unfixed = [];
159
199
  let tellUnfixed = (_name) => {};
160
200
  const lock = (target, name, value) => {
@@ -2232,36 +2272,43 @@ export const SHELL_RUNTIME = String.raw`(() => {
2232
2272
  whenLoaded(() => void render({ html: plan.document }));
2233
2273
  }
2234
2274
 
2235
- // Ask until answered: the host may start listening after this runs.
2236
- let initialized = false;
2237
- let tries = 0;
2238
- const initialize = () => {
2239
- if (initialized) {
2240
- return;
2241
- }
2242
- if (tries >= 40) {
2243
- // No host answered: the runtime has nothing to offer.
2244
- runtimeOffer(null);
2245
- return;
2246
- }
2247
- tries += 1;
2248
- request("ui/initialize", {
2249
- protocolVersion: plan.protocolVersion,
2250
- appInfo: { name: "porthole-shell", version: "1" },
2251
- appCapabilities: {},
2252
- }).then((result) => {
2253
- if (initialized) {
2254
- return;
2255
- }
2256
- initialized = true;
2275
+ // The handshake (HANDSHAKE, P085): asked until answered, since the host may start listening
2276
+ // after this runs; on a tab of its own, not asked at all (P139): its parent is itself, so no host
2277
+ // hears it, and the runtime has nothing to offer from the start. How it ended goes on the
2278
+ // document's root element (data-porthole-host: "answered", or "none" where no host answered), for
2279
+ // a test, a person or a tool that shoots the page to see (P139): not on the shell's own script,
2280
+ // which a whole document's render takes out with the body it replaces, while the root stays (the
2281
+ // render adds the page's own attributes to it and removes none). The page's own word, never a
2282
+ // gate, set through the platform's setAttribute kept before the guards (setAttributeOfShell).
2283
+ const shellRoot = document.documentElement;
2284
+ const settled = (how) => {
2285
+ try {
2286
+ callOf(setAttributeOfShell, shellRoot, ["data-porthole-host", how]);
2287
+ } catch (_) {}
2288
+ };
2289
+ const handshake = ${HANDSHAKE};
2290
+ handshake(
2291
+ window.top === window,
2292
+ () =>
2293
+ request("ui/initialize", {
2294
+ protocolVersion: plan.protocolVersion,
2295
+ appInfo: { name: "porthole-shell", version: "1" },
2296
+ appCapabilities: {},
2297
+ }),
2298
+ (result) => {
2299
+ settled("answered");
2257
2300
  const capabilities = result && result.hostCapabilities;
2258
2301
  const experimental = capabilities && capabilities.experimental;
2259
2302
  runtimeOffer(experimental && typeof experimental === "object" ? experimental["porthole/runtime"] : null);
2260
2303
  applyTheme(result && result.hostContext);
2261
2304
  notify("ui/notifications/initialized", {});
2262
2305
  schedule();
2263
- }, () => {});
2264
- setTimeout(initialize, 250);
2265
- };
2266
- initialize();
2306
+ },
2307
+ () => {
2308
+ // No host answered (or none can): the runtime has nothing to offer.
2309
+ settled("none");
2310
+ runtimeOffer(null);
2311
+ },
2312
+ (run, ms) => setTimeout(run, ms),
2313
+ );
2267
2314
  })();`;