@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
@@ -105,9 +105,11 @@ export const WORD_LATE = String.raw `(at, now) => {
105
105
  * - the last line (P133): where a selection or a mark's words end, in the document's coordinates
106
106
  * too (`lastLineDocumentRect`), so a host places its UI after them;
107
107
  * - the selection followed (P138): what the last `selected` reported (the element picked, or the
108
- * words selected) is kept, and while the host follows it (`track` with `selection`) it is drawn
109
- * in the layer and its boxes are reported as a followed mark's are (`selectionTracked`), with
110
- * whether it is in view, or that it is gone; it takes no pointer, no focus and no key.
108
+ * words selected) is kept while the host follows the selection (`track` with `selection`) or said
109
+ * at `start` that it will (`keepSelection`, P140), and nothing is kept otherwise; while followed
110
+ * it is drawn in the layer and its boxes are reported as a followed mark's are
111
+ * (`selectionTracked`), with whether it is in view, or that it is gone; it takes no pointer, no
112
+ * focus and no key.
111
113
  *
112
114
  * It shares the realm with the content, which can interfere with all of it: the host takes its
113
115
  * reports as UI hints only.
@@ -436,20 +438,25 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
436
438
  // The selection last reported as selected (P138): its anchor, and what it is in the page (the
437
439
  // element picked, or a copy of the selection's range, which the page's changes keep up to
438
440
  // date and which stays when the page's own selection goes). Followed while the host asks
439
- // (track with selection), and drawn then. Each new selected replaces it.
441
+ // (track with selection), and drawn then. Each new selected replaces it. Kept only while the
442
+ // host follows the selection, or said at its last start that it will (keepSelection, P140):
443
+ // for any other host nothing is kept, as before P138.
440
444
  let held = null;
441
445
  let followingSelection = false;
446
+ let keeping = false;
447
+ const keeps = () => followingSelection || keeping;
442
448
  // What the host was last told of it: "attached", "orphaned", or null (nothing yet).
443
449
  let heldTold = null;
444
450
  const heldGone = (found) => (found.range ? found.range.collapsed || !found.range.startContainer.isConnected : !found.element.isConnected);
445
451
  const heldShown = () => followingSelection && held !== null && heldTold !== "orphaned" && !heldGone(held.found);
446
- // The element just picked (P138, Tenny's review): it keeps its outline after selected, so
447
- // there is no gap before the host follows it, and the follow's highlight takes over where it
448
- // does. Without a follow (an older host) it ends as a selection does: the next pick or
449
- // selection, the host's clearSelection, a mode started or stopped, clear, Escape, or the
450
- // element leaving the page. Not unselected: a selection made after the pick has already
451
- // ended it as it was reported, so the one unselected can clear is one from before, which
452
- // the pick's own click takes away when text is selected too.
452
+ // The element just picked (P138, Tenny's review): for a host that will follow it
453
+ // (keepSelection, P140), it keeps its outline after selected, so there is no gap before the
454
+ // host follows it, and the follow's highlight takes over where it does. For any other host
455
+ // the outline goes with the pick, as before P138. Until the follow comes it ends as a
456
+ // selection does: the next pick or selection, the host's clearSelection, a mode started or
457
+ // stopped, clear, Escape, or the element leaving the page. Not unselected: a selection made
458
+ // after the pick has already ended it as it was reported, so the one unselected can clear is
459
+ // one from before, which the pick's own click takes away when text is selected too.
453
460
  let picked = null;
454
461
  const endPick = () => {
455
462
  if (picked !== null) {
@@ -1090,6 +1097,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1090
1097
  if (followingSelection) {
1091
1098
  picked = null;
1092
1099
  }
1100
+ // Its end lets the selection go, unless the host said it follows it again (P140).
1101
+ if (!keeps()) {
1102
+ held = null;
1103
+ }
1093
1104
  trackedBox = null;
1094
1105
  trackedView = null;
1095
1106
  heldTold = null;
@@ -1100,9 +1111,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1100
1111
  draw();
1101
1112
  }
1102
1113
  };
1103
- // A new selected (P138): what is followed, if the selection is, from the next frame on.
1114
+ // A new selected (P138): what is followed, if the selection is, from the next frame on; kept
1115
+ // only for a host that follows it or will (P140).
1104
1116
  const holdSelected = (anchor, found) => {
1105
- held = { anchor, found, tried: 0 };
1117
+ held = keeps() ? { anchor, found, tried: 0 } : null;
1106
1118
  if (followingSelection) {
1107
1119
  trackedBox = null;
1108
1120
  heldTold = null;
@@ -1653,7 +1665,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1653
1665
  }
1654
1666
  swallowUntil = performance.now() + 2000;
1655
1667
  holdSelected(anchor, { element });
1656
- picked = followingSelection ? null : element;
1668
+ picked = keeping && !followingSelection ? element : null;
1657
1669
  redraw();
1658
1670
  tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
1659
1671
  }, HOLD_MS),
@@ -1703,8 +1715,9 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1703
1715
  hover = null;
1704
1716
  setCursor(false);
1705
1717
  holdSelected(anchor, { element });
1706
- // Its outline stays (P138), now without its name, until the host follows it or it ends.
1707
- picked = followingSelection ? null : element;
1718
+ // Its outline stays (P138), now without its name, until the host follows it or it ends;
1719
+ // only for a host that will follow it (P140): for any other it goes with the pick.
1720
+ picked = keeping && !followingSelection ? element : null;
1708
1721
  draw();
1709
1722
  tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
1710
1723
  }, true);
@@ -1801,6 +1814,13 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1801
1814
  switch (data.method) {
1802
1815
  case M.start:
1803
1816
  mode = { elements: params.elements === true, text: params.text === true, hold: params.elements === "hold" };
1817
+ // Whether the host will follow what is selected (P140): only then is it kept before
1818
+ // the host follows it. A stop leaves it, so a stop sent as the composer opens doesn't
1819
+ // take the selection away before the follow comes.
1820
+ keeping = params.keepSelection === true;
1821
+ if (!keeps()) {
1822
+ held = null;
1823
+ }
1804
1824
  hover = null;
1805
1825
  picked = null;
1806
1826
  reported = null;
@@ -37,6 +37,12 @@ export { SHELL_METHOD_PREFIX, SHELL_STATE_METHOD } from "../isolation/types.ts";
37
37
  export interface FrameShellOptions {
38
38
  /** The host origins: the shell takes messages from its parent only from these. */
39
39
  readonly origins: readonly string[];
40
+ /**
41
+ * Origins of an outer page that may be an ancestor above a host origin's page (P141): in the
42
+ * shell's `frame-ancestors` after `origins` (`nestedShellResponse`), never heard or told. Where
43
+ * there are any, the shell says `*` only to a parent the engine names as a host origin.
44
+ */
45
+ readonly framedBy?: readonly string[];
40
46
  /** The page's address: absolute, on the shell's own origin, under `/__porthole/f/`. */
41
47
  readonly page: string;
42
48
  /** The page frame's accessible name. */
@@ -1,5 +1,5 @@
1
1
  import { PAGE_SANDBOX_TOKENS } from "../compile/policy.js";
2
- import { hostOriginProblem, onNestedLabel } from "../isolation/served.js";
2
+ import { framedByProblem, hostOriginProblem, onNestedLabel } from "../isolation/served.js";
3
3
  /**
4
4
  * Porthole's shell for a nested page (P111): the whole document at the address the host frames,
5
5
  * with no content in it. It frames the page (the same origin's sealed files' address) in a child
@@ -80,7 +80,9 @@ export const FRAME_SHELL_RUNTIME = String.raw `(() => {
80
80
  const web = plan.origins.filter((origin) => origin.indexOf("https://") === 0 || origin.indexOf("http://") === 0);
81
81
  // To the host: each web host origin (only the parent's is delivered); a desktop app's own scheme
82
82
  // is no target a browser takes, so where one is listed and the parent isn't a known web origin,
83
- // "*" (frame-ancestors holds the parent to the host origins; nothing said here is secret).
83
+ // "*" (frame-ancestors holds the parent to the host origins; nothing said here is secret). Where
84
+ // it names an outer page above them too (the host's framedBy, P141: plan.strictParent), the parent
85
+ // may be the outer page: "*" then goes only to a parent the engine names as a host origin.
84
86
  const toHost = (message) => {
85
87
  if (!framed) {
86
88
  return;
@@ -91,7 +93,11 @@ export const FRAME_SHELL_RUNTIME = String.raw `(() => {
91
93
  } catch (_) {}
92
94
  }
93
95
  const parent = location.ancestorOrigins && location.ancestorOrigins.length > 0 ? location.ancestorOrigins[0] : null;
94
- if (web.length < plan.origins.length && (parent === null || web.indexOf(parent) === -1)) {
96
+ if (
97
+ web.length < plan.origins.length &&
98
+ (parent === null || web.indexOf(parent) === -1) &&
99
+ (plan.strictParent !== true || (parent !== null && plan.origins.indexOf(parent) !== -1))
100
+ ) {
95
101
  try {
96
102
  window.parent.postMessage(message, "*");
97
103
  } catch (_) {}
@@ -271,6 +277,12 @@ export function frameShellScript(options) {
271
277
  throw new TypeError(`frameShellScript: ${problem}`);
272
278
  }
273
279
  }
280
+ for (const origin of options.framedBy ?? []) {
281
+ const problem = framedByProblem(origin);
282
+ if (problem !== null || options.origins.includes(origin)) {
283
+ throw new TypeError(`frameShellScript: framedBy: ${problem ?? `${origin} is a host origin`}`);
284
+ }
285
+ }
274
286
  let page;
275
287
  try {
276
288
  page = new URL(options.page);
@@ -287,6 +299,7 @@ export function frameShellScript(options) {
287
299
  }
288
300
  return FRAME_SHELL_RUNTIME.replace("__PLAN__", () => scriptJson({
289
301
  origins: options.origins,
302
+ ...((options.framedBy ?? []).length === 0 ? {} : { strictParent: true }),
290
303
  page: page.href,
291
304
  sandbox: PAGE_SANDBOX_TOKENS.join(" "),
292
305
  ...(options.title === undefined ? {} : { title: options.title }),
@@ -29,6 +29,16 @@ export declare const PASSES_AS_IS: string;
29
29
  * and nothing is forwarded): fail closed.
30
30
  */
31
31
  export declare const ONCE: string;
32
+ /**
33
+ * The shell's handshake with its host (P085, P139), spliced into the runtime as
34
+ * `HANDSHAKE(topLevel, ask, answered, none, later)`. On a tab of its own (`topLevel`: the window is
35
+ * its own top, so its parent is itself and no host can hear it) there is no host to ask: `none()`
36
+ * at once, and nothing is asked. In a frame it asks (`ask()`, a promise of the host's answer) up to
37
+ * 40 times, 250 ms apart (`later(run, ms)`), since the host may start listening after the shell
38
+ * runs; the first answer is taken (`answered(result)`), once. After the 40th try with no answer,
39
+ * `none()`; an answer that comes later still is taken.
40
+ */
41
+ export declare const HANDSHAKE: string;
32
42
  /**
33
43
  * The shell's runtime: the code that runs first in the frame, before any content. Plain ES2020,
34
44
  * no imports and no build step, so every engine (a browser frame now, a native web view later)
@@ -88,6 +88,42 @@ export const ONCE = String.raw `(passesAsIs, toText) => (value) => {
88
88
  }
89
89
  return text;
90
90
  }`;
91
+ /**
92
+ * The shell's handshake with its host (P085, P139), spliced into the runtime as
93
+ * `HANDSHAKE(topLevel, ask, answered, none, later)`. On a tab of its own (`topLevel`: the window is
94
+ * its own top, so its parent is itself and no host can hear it) there is no host to ask: `none()`
95
+ * at once, and nothing is asked. In a frame it asks (`ask()`, a promise of the host's answer) up to
96
+ * 40 times, 250 ms apart (`later(run, ms)`), since the host may start listening after the shell
97
+ * runs; the first answer is taken (`answered(result)`), once. After the 40th try with no answer,
98
+ * `none()`; an answer that comes later still is taken.
99
+ */
100
+ export const HANDSHAKE = String.raw `(topLevel, ask, answered, none, later) => {
101
+ if (topLevel === true) {
102
+ none();
103
+ return;
104
+ }
105
+ let initialized = false;
106
+ let tries = 0;
107
+ const initialize = () => {
108
+ if (initialized) {
109
+ return;
110
+ }
111
+ if (tries >= 40) {
112
+ none();
113
+ return;
114
+ }
115
+ tries += 1;
116
+ ask().then((result) => {
117
+ if (initialized) {
118
+ return;
119
+ }
120
+ initialized = true;
121
+ answered(result);
122
+ }, () => {});
123
+ later(initialize, 250);
124
+ };
125
+ initialize();
126
+ }`;
91
127
  /**
92
128
  * The shell's runtime: the code that runs first in the frame, before any content. Plain ES2020,
93
129
  * no imports and no build step, so every engine (a browser frame now, a native web view later)
@@ -151,6 +187,9 @@ export const SHELL_RUNTIME = String.raw `(() => {
151
187
  // such name goes on the shell's own script element (data-porthole-unfixed, for a test or a
152
188
  // person to see) and, once the shell can speak, to the host as an error report.
153
189
  const shellScript = document.currentScript;
190
+ // The platform's own, kept before the shell's guards wrap it: the shell marks the document's root
191
+ // with it (data-porthole-host, P139).
192
+ const setAttributeOfShell = Element.prototype.setAttribute;
154
193
  const unfixed = [];
155
194
  let tellUnfixed = (_name) => {};
156
195
  const lock = (target, name, value) => {
@@ -2228,36 +2267,43 @@ export const SHELL_RUNTIME = String.raw `(() => {
2228
2267
  whenLoaded(() => void render({ html: plan.document }));
2229
2268
  }
2230
2269
 
2231
- // Ask until answered: the host may start listening after this runs.
2232
- let initialized = false;
2233
- let tries = 0;
2234
- const initialize = () => {
2235
- if (initialized) {
2236
- return;
2237
- }
2238
- if (tries >= 40) {
2239
- // No host answered: the runtime has nothing to offer.
2240
- runtimeOffer(null);
2241
- return;
2242
- }
2243
- tries += 1;
2244
- request("ui/initialize", {
2245
- protocolVersion: plan.protocolVersion,
2246
- appInfo: { name: "porthole-shell", version: "1" },
2247
- appCapabilities: {},
2248
- }).then((result) => {
2249
- if (initialized) {
2250
- return;
2251
- }
2252
- initialized = true;
2270
+ // The handshake (HANDSHAKE, P085): asked until answered, since the host may start listening
2271
+ // after this runs; on a tab of its own, not asked at all (P139): its parent is itself, so no host
2272
+ // hears it, and the runtime has nothing to offer from the start. How it ended goes on the
2273
+ // document's root element (data-porthole-host: "answered", or "none" where no host answered), for
2274
+ // a test, a person or a tool that shoots the page to see (P139): not on the shell's own script,
2275
+ // which a whole document's render takes out with the body it replaces, while the root stays (the
2276
+ // render adds the page's own attributes to it and removes none). The page's own word, never a
2277
+ // gate, set through the platform's setAttribute kept before the guards (setAttributeOfShell).
2278
+ const shellRoot = document.documentElement;
2279
+ const settled = (how) => {
2280
+ try {
2281
+ callOf(setAttributeOfShell, shellRoot, ["data-porthole-host", how]);
2282
+ } catch (_) {}
2283
+ };
2284
+ const handshake = ${HANDSHAKE};
2285
+ handshake(
2286
+ window.top === window,
2287
+ () =>
2288
+ request("ui/initialize", {
2289
+ protocolVersion: plan.protocolVersion,
2290
+ appInfo: { name: "porthole-shell", version: "1" },
2291
+ appCapabilities: {},
2292
+ }),
2293
+ (result) => {
2294
+ settled("answered");
2253
2295
  const capabilities = result && result.hostCapabilities;
2254
2296
  const experimental = capabilities && capabilities.experimental;
2255
2297
  runtimeOffer(experimental && typeof experimental === "object" ? experimental["porthole/runtime"] : null);
2256
2298
  applyTheme(result && result.hostContext);
2257
2299
  notify("ui/notifications/initialized", {});
2258
2300
  schedule();
2259
- }, () => {});
2260
- setTimeout(initialize, 250);
2261
- };
2262
- initialize();
2301
+ },
2302
+ () => {
2303
+ // No host answered (or none can): the runtime has nothing to offer.
2304
+ settled("none");
2305
+ runtimeOffer(null);
2306
+ },
2307
+ (run, ms) => setTimeout(run, ms),
2308
+ );
2263
2309
  })();`;
package/docs/ADOPTING.md CHANGED
@@ -290,7 +290,8 @@ composer.onClose(() => display.annotations.clearSelection());
290
290
  - **React** (P118): `PortholeFrame` and `PortholeView` take the same as props: `annotating`,
291
291
  `annotations`, `focusedAnnotation` and `trackedAnnotation` (the mark to follow, by value; `null`
292
292
  stops), `trackedSelection` (true while your composer is open: the selection is followed in the
293
- mark's place, P138), every report through `onAnnotation` (`tracked` and `selectionTracked` too). The selection is cleared through a
293
+ mark's place, P138; give it from the first render, `false` until then, so the mode starts with
294
+ `keepSelection`, P140: it is read as the mode starts, and giving it later restarts nothing), every report through `onAnnotation` (`tracked` and `selectionTracked` too). The selection is cleared through a
294
295
  ref, which holds `clearSelection()` only (a `PortholeFrameHandle`; never the display, whose life
295
296
  is the binding's); with no display running it does nothing. Errors the core's calls throw (an id
296
297
  no shown mark has, a config without `annotate`) reach `onHostError`, kind `"annotations"`.
@@ -437,30 +438,38 @@ composer.onClose(() => display.annotations.clearSelection());
437
438
  composer.openAt(frame, clipToFrame(at), report.anchor); // the frame's px: clip them, then add its position
438
439
  });
439
440
  ```
440
- - **A composer that stays beside what it is for** (P138): `selected` comes once for a pick (and
441
- for words again only once a scroll settles), and a pick's outline goes with it. Follow the
442
- selection while your composer is open, `annotations.track({ selection: true })` (React:
443
- `trackedSelection`), and the frame highlights it (a picked element in the picking outline) and
441
+ - **A composer that stays beside what it is for** (P138, P140): `selected` comes once for a pick
442
+ (and for words again only once a scroll settles), and by default a pick's outline goes with it
443
+ and the frame keeps nothing of it. To follow it, start with `keepSelection: true`
444
+ (`annotations.start({ elements: true, keepSelection: true })`; React does it while you give
445
+ `trackedSelection`), so the frame keeps what is picked or selected, then follow the selection
446
+ while your composer is open, `annotations.track({ selection: true })` (React:
447
+ `trackedSelection`). The frame highlights it (a picked element in the picking outline) and
444
448
  reports `selectionTracked` as `tracked` reports a mark: at most 60 a second, its `rect` clamped,
445
449
  `documentRect`, `lastLineDocumentRect` and `scroll` as above, and `inView`, so you hide the
446
450
  composer (and show your own marker at the frame's edge, from `documentRect` and `scroll`, clipped)
447
451
  while it is out of view. `state: "orphaned"`: it isn't in the page now (a re-render took it out;
448
- a reload); keep the person's words, it may be found again. It follows the latest `selected`, so a
449
- new pick or selection moves it. One thing is followed at a time: it takes a followed mark's
450
- place, and `track(null)`, a mark's id or `clear` ends it, the highlight with it. End it on every
451
- close (posted, dismissed, Escape in your composer: the frame's own Escape doesn't end it), as you
452
- clear the selection: the page reads when it starts and ends, so an end on every close says nothing
453
- of what came of it. The composer moves at the page's word: guard it as below, armed again each
454
- time it moves or shows again. An older shell sends nothing (and draws nothing): place by
455
- `selected` until the first `selectionTracked`, which a newer one sends at its next animation
456
- frame. A newer shell keeps the picked element outlined from the pick on, so there is no gap
457
- before the follow's highlight; ask for the follow before a `start` or `stop` you send as the
458
- composer opens (React orders them so), or the stop ends that outline a moment before the follow
459
- draws it again. Without a follow the outline ends as a selection does (the next pick, Escape,
460
- `clearSelection`, `start`, `stop`, `clear`). While you follow the selection, `selected` isn't
461
- re-sent after a scroll: read where it is from `selectionTracked`.
452
+ a reload); keep the person's words, it may be found again. Without `keepSelection`, a follow
453
+ asked after `selected` has nothing to follow and answers `orphaned`; one asked before the pick
454
+ follows each selection made while it lasts. It follows the latest `selected`, so a new pick or
455
+ selection moves it. One thing is followed at a time: it takes a followed mark's place, and
456
+ `track(null)`, a mark's id or `clear` ends it, the highlight with it. End it on every close
457
+ (posted, dismissed, Escape in your composer: the frame's own Escape doesn't end it), as you
458
+ clear the selection: the page reads when it starts and ends, so an end on every close says
459
+ nothing of what came of it. The composer moves at the page's word: guard it as below, armed
460
+ again each time it moves or shows again. An older shell sends nothing (and draws nothing): place
461
+ by `selected` until the first `selectionTracked`, which a newer one sends at its next animation
462
+ frame. Under `keepSelection` a newer shell keeps the picked element outlined from the pick on,
463
+ so there is no gap before the follow's highlight; ask for the follow before a `start` or `stop`
464
+ you send as the composer opens (React orders them so), or the stop ends that outline a moment
465
+ before the follow draws it again. Until the follow comes, the outline ends as a selection does
466
+ (the next pick, Escape, `clearSelection`, `start`, `stop`, `clear`). Without `keepSelection` the
467
+ outline goes with the pick, as before 0.14.15. While you follow the selection, `selected` isn't
468
+ re-sent after a scroll: read where it is from `selectionTracked`; and while you don't, a
469
+ `selectionTracked` from the page is dropped unread.
462
470
 
463
471
  ```js
472
+ display.annotations.start({ elements: true, text: true, keepSelection: true });
464
473
  display.on("annotation", (report) => {
465
474
  if (report.type === "selected") {
466
475
  composer.openBeside(frame, report.rect, report.anchor); // as before: an older shell stops here
@@ -736,6 +745,15 @@ nodeServer({ content, app: async (request) => (await routes(request)) ?? app(req
736
745
  - **`Response.redirect` needs an absolute URL** outside a browser (Node throws on `/login`).
737
746
  - **`reserved`** is only for labels your app itself serves on the content domain (previews of a
738
747
  dev server, `p-*`). Labels nothing serves need nothing: they are a 404 there.
748
+ - **`framedBy`** (P141): where another app frames yours (a dashboard that embeds your app in an
749
+ iframe), its origins: `framedBy: ["https://dashboard.example.com"]`. `frame-ancestors` names every
750
+ ancestor, so without it each of your frames is blank inside that app. Each may then be an
751
+ ancestor of every frame Porthole serves, after `appOrigins`, and is never a host: no frame hears
752
+ or tells it, it isn't in `data-porthole-hosts`, and redirect entry and the handoff stay
753
+ `appOrigins`' alone. Exact https origins (`http://` on loopback), none an app origin. Your own
754
+ page between them is still the frame's parent, and its `frame-ancestors` is yours to set. A
755
+ content Worker of your own passes the same list to `statusPage`, `doorResponse`,
756
+ `doorStatusResponse` and `nestedShellResponse` (`framedBy`).
739
757
  - **No content domain** (self-hosted without one): still make the host, with `domain: null` (or
740
758
  `""`). That is the supported setup: no secret is needed, `GET /porthole/meta` answers
741
759
  `{ served: false }`, and pages show every kind opaque (a url kind, its fallback) instead of
@@ -910,7 +928,7 @@ no frame), `nestedShellResponse` throws for another origin, and the shell runs n
910
928
 
911
929
  | Request | Answer |
912
930
  | --- | --- |
913
- | `<origin>/__porthole/d/<key>`, the framed address (a ticket's, a cookie's reload; an entered clean address on the scope's label answers a `303` here with a one-time ticket), a navigation | 200, `text/html`: Porthole's shell, `nestedShellResponse(compiled, { origin, origins: hostOrigins, page: "<origin>/__porthole/f/<token>/<entry>", renew: { url: "<origin>/__porthole/f/<token>/__porthole/renew", expires } })`. Headers: `Content-Security-Policy: default-src 'none'; script-src 'sha256-<its script>'; frame-src <origin>/__porthole/f/; connect-src <origin>/__porthole/f/; base-uri 'none'; form-action 'none'; frame-ancestors <host origins>`; `Cache-Control: no-store`; `Referrer-Policy: no-referrer`; `X-Content-Type-Options: nosniff`; the served `Permissions-Policy`. No content in it. Any other request there: 404. |
931
+ | `<origin>/__porthole/d/<key>`, the framed address (a ticket's, a cookie's reload; an entered clean address on the scope's label answers a `303` here with a one-time ticket), a navigation | 200, `text/html`: Porthole's shell, `nestedShellResponse(compiled, { origin, origins: hostOrigins, framedBy, page: "<origin>/__porthole/f/<token>/<entry>", renew: { url: "<origin>/__porthole/f/<token>/__porthole/renew", expires } })`. Headers: `Content-Security-Policy: default-src 'none'; script-src 'sha256-<its script>'; frame-src <origin>/__porthole/f/; connect-src <origin>/__porthole/f/; base-uri 'none'; form-action 'none'; frame-ancestors <host origins> <framedBy>`; `Cache-Control: no-store`; `Referrer-Policy: no-referrer`; `X-Content-Type-Options: nosniff`; the served `Permissions-Policy`. No content in it. Any other request there: 404. |
914
932
  | `<origin>/__porthole/f/<token>/<page>` (the shell's child, or a tab) | The page as served before (the shell's runtime and the page), its plan's `origins` the content origin alone (`[<origin>]`) and its storage `memory`. `Content-Security-Policy`: `nestedFileCsp("page", fileSetCspDirectives(compiled.cspDirectives, "<origin>/__porthole/f/"))` then `; frame-ancestors ` and `nestedAncestors("<origin>", "<host origins>")`: the page's directives, its files' prefix opened, and `sandbox allow-scripts` (never `allow-same-origin`). Access from `<token>` alone: no cookie is sent (the page's origin is opaque), and never decide by `Origin` (it is `null`) or `Sec-Fetch-Site` (`cross-site`). |
915
933
  | `<origin>/__porthole/f/<token>/<file>` (the page's loads) | As served files are, plus `Cross-Origin-Resource-Policy: cross-origin` and `Access-Control-Allow-Origin: *` (`NESTED_FILE_HEADERS`): the opaque page's images, scripts, modules, fonts and fetches are cross-origin. Every one carries a CSP sandbox, never `allow-same-origin` (`nestedFileCsp(fileTypeOf(path).role, directives)`, then the `frame-ancestors` above): a non-page file `default-src 'none'; sandbox`, a script its directives plus `sandbox`, so none opened on a tab of its own (an SVG, an XML file) runs on the shell's origin. |
916
934
  | `<origin>/__porthole/f/<token>/__porthole/renew` | Only the shell's own fetch (`Sec-Fetch-Site: same-origin`, not a navigation): `{ "base": "<origin>/__porthole/f/<new token>/", "expires": <epoch ms> }`, `no-store`; anything else 403. The shell renews 5 minutes before `expires` and moves the page to the new base. |
@@ -1136,8 +1154,8 @@ A **content Worker of your own** (one that answers the content origins itself, i
1136
1154
  `/server`) serves the door too: `issue` mints the door ticket and returns `door: { url }`, and the
1137
1155
  Worker routes `DOOR_PATH + <key>` (`/__porthole/door/<key>`) on every label — take the door ticket
1138
1156
  (`TicketRecord.door === true`, bound to the label and key), run the same access, document and entry
1139
- checks the content route runs for that grant, then answer `doorResponse({ hostOrigins })` (open) or
1140
- `doorStatusResponse({ status, reason, code?, hostOrigins })` (401 `session` / 403 `denied` / 404
1157
+ checks the content route runs for that grant, then answer `doorResponse({ hostOrigins, framedBy })` (open) or
1158
+ `doorStatusResponse({ status, reason, code?, hostOrigins, framedBy })` (401 `session` / 403 `denied` / 404
1141
1159
  `not-found` / 500 `error`). Refuse a door ticket at `/__porthole/d/`, and serve no door on a nested
1142
1160
  page's shell label. `DOOR_PATH`, `doorResponse` and `doorStatusResponse` are exported from
1143
1161
  `@botiverse/porthole/server`.