@botiverse/porthole 0.15.3 → 0.16.0

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 (107) hide show
  1. package/CHANGELOG.md +58 -0
  2. package/dist/bridge/bridge.d.ts +1 -8
  3. package/dist/bridge/bridge.js +0 -7
  4. package/dist/check/page-source.js +1 -1
  5. package/dist/check/page.js +1 -1
  6. package/dist/compile/policy.d.ts +0 -7
  7. package/dist/compile/policy.js +1 -10
  8. package/dist/config/capabilities.d.ts +8 -14
  9. package/dist/config/capabilities.js +4 -5
  10. package/dist/config/schema.d.ts +2 -13
  11. package/dist/config/validate.js +0 -24
  12. package/dist/conformance/behavior.js +26 -37
  13. package/dist/conformance/clipboard.js +47 -1
  14. package/dist/conformance/harness-source.js +1 -1
  15. package/dist/displays/displays.js +1 -3
  16. package/dist/guide/limits.js +1 -1
  17. package/dist/guide/runtime.js +1 -1
  18. package/dist/host/create-host.d.ts +1 -1
  19. package/dist/host/create-host.js +6 -51
  20. package/dist/host/door.d.ts +1 -1
  21. package/dist/host/locate.d.ts +1 -1
  22. package/dist/host/locate.js +2 -2
  23. package/dist/host/outcome.d.ts +5 -12
  24. package/dist/host/outcome.js +8 -16
  25. package/dist/host/types.d.ts +6 -22
  26. package/dist/index.d.ts +2 -4
  27. package/dist/index.js +2 -4
  28. package/dist/isolation/served.d.ts +4 -14
  29. package/dist/isolation/served.js +7 -28
  30. package/dist/isolation/types.d.ts +2 -25
  31. package/dist/isolation/types.js +0 -23
  32. package/dist/platform/focus-field.d.ts +11 -0
  33. package/dist/platform/focus-field.js +18 -0
  34. package/dist/platform/types.d.ts +6 -22
  35. package/dist/platform/web.js +8 -106
  36. package/dist/presets/presets.d.ts +0 -2
  37. package/dist/presets/presets.js +0 -1
  38. package/dist/react/frame.d.ts +0 -8
  39. package/dist/react/frame.js +0 -4
  40. package/dist/runtime/contract.d.ts +2 -2
  41. package/dist/runtime/contract.js +2 -2
  42. package/dist/runtime/types.generated.js +6 -6
  43. package/dist/server/files.js +7 -23
  44. package/dist/server/host.d.ts +1 -1
  45. package/dist/server/index.d.ts +1 -1
  46. package/dist/server/index.js +4 -6
  47. package/dist/server/naming.js +1 -1
  48. package/dist/server/server.js +28 -166
  49. package/dist/server/types.d.ts +7 -7
  50. package/dist/shell/plan.d.ts +0 -5
  51. package/dist/shell/plan.js +2 -4
  52. package/dist/shell/runtime.js +1 -268
  53. package/docs/ADOPTING.md +42 -138
  54. package/docs/ARCHITECTURE.md +0 -33
  55. package/docs/DECISIONS.md +115 -10
  56. package/docs/DESIGN.md +27 -64
  57. package/docs/THREAT_MODEL.md +128 -255
  58. package/package.json +1 -1
  59. package/src/bridge/bridge.ts +1 -17
  60. package/src/check/page.ts +1 -1
  61. package/src/compile/policy.ts +1 -11
  62. package/src/config/capabilities.ts +8 -14
  63. package/src/config/schema.ts +2 -13
  64. package/src/config/validate.ts +0 -28
  65. package/src/conformance/behavior.ts +50 -52
  66. package/src/conformance/clipboard.ts +56 -1
  67. package/src/displays/displays.ts +1 -3
  68. package/src/guide/limits.ts +1 -1
  69. package/src/guide/runtime.ts +1 -1
  70. package/src/host/create-host.ts +6 -52
  71. package/src/host/door.ts +1 -1
  72. package/src/host/locate.ts +2 -2
  73. package/src/host/outcome.ts +8 -21
  74. package/src/host/types.ts +6 -20
  75. package/src/index.ts +2 -4
  76. package/src/isolation/served.ts +6 -34
  77. package/src/isolation/types.ts +2 -31
  78. package/src/platform/focus-field.ts +18 -0
  79. package/src/platform/types.ts +6 -21
  80. package/src/platform/web.ts +8 -129
  81. package/src/presets/presets.ts +0 -3
  82. package/src/react/frame.tsx +0 -10
  83. package/src/runtime/contract.ts +4 -4
  84. package/src/runtime/types.generated.ts +6 -6
  85. package/src/server/files.ts +4 -19
  86. package/src/server/host.ts +1 -1
  87. package/src/server/index.ts +4 -16
  88. package/src/server/naming.ts +1 -1
  89. package/src/server/server.ts +29 -189
  90. package/src/server/types.ts +7 -7
  91. package/src/shell/plan.ts +2 -9
  92. package/src/shell/runtime.ts +1 -268
  93. package/types/runtime/v1/artifact.d.ts +2 -3
  94. package/types/runtime/v1/assets.d.ts +1 -1
  95. package/types/runtime/v1/chat.d.ts +2 -2
  96. package/types/runtime/v1/comments.d.ts +1 -1
  97. package/types/runtime/v1/downloads.d.ts +2 -2
  98. package/types/runtime/v1/links.d.ts +2 -2
  99. package/dist/platform/focus-guard.d.ts +0 -288
  100. package/dist/platform/focus-guard.js +0 -838
  101. package/dist/server/nested.d.ts +0 -66
  102. package/dist/server/nested.js +0 -121
  103. package/dist/shell/frame.d.ts +0 -28
  104. package/dist/shell/frame.js +0 -407
  105. package/src/platform/focus-guard.ts +0 -1114
  106. package/src/server/nested.ts +0 -157
  107. package/src/shell/frame.ts +0 -444
@@ -271,8 +271,6 @@ export const SHELL_RUNTIME = String.raw `(() => {
271
271
  // takes the next load for that page, not for content that left). Anything else stays stopped:
272
272
  // another path of the origin, a file that isn't a page, another origin.
273
273
  let navigating = (_url) => {};
274
- // A nested page's files' address renewed by its shell (P111), which the shell's message gives.
275
- let adoptFiles = (_base) => false;
276
274
  let filesBase = plan.files && typeof plan.files.base === "string" ? plan.files.base : null;
277
275
  // Every address the page's files had (P083: a sealed one is renewed): what reports say as "./".
278
276
  const filesBases = filesBase === null ? [] : [filesBase];
@@ -926,14 +924,9 @@ export const SHELL_RUNTIME = String.raw `(() => {
926
924
  const noRewrite = function () {
927
925
  throw new Error("document.open and document.write aren't available here: build the page with DOM methods");
928
926
  };
929
- const unfixedBeforeRewrite = unfixed.length;
930
927
  for (const name of ["open", "write", "writeln"]) {
931
928
  lock(Document.prototype, name, noRewrite);
932
929
  }
933
- // Whether all three are fixed in place. The press port rests on it (P148): document.open() takes
934
- // every listener off the window, the runtime's among them, and a document opened and closed
935
- // again loads again, so content that could call it would hear a port before the runtime did.
936
- const rewriteFixed = unfixed.length === unfixedBeforeRewrite;
937
930
 
938
931
  // Some engines act on a hint the moment its element is connected or changed (WebKit opens a
939
932
  // preconnect then, outside the CSP), before the observer's microtask. So every way to connect a
@@ -1397,254 +1390,6 @@ export const SHELL_RUNTIME = String.raw `(() => {
1397
1390
  ]);
1398
1391
  }
1399
1392
 
1400
- // A nested page's real presses, told to its shell (P148). The shell sees a press in the page only
1401
- // as its own activation turning on, and a press within 5 s of the last gesture turns nothing on
1402
- // (P111): to the host that reads as a button that does nothing. So the runtime, which runs before
1403
- // any content and hears the browser's own events first, tells the shell each one, over a
1404
- // MessagePort the shell sends at each load of the page's frame. What keeps that the runtime's
1405
- // word and never the content's:
1406
- // - the port: taken here, by the first listener there is (on window, capturing), from the first
1407
- // message that is the browser's own (isTrusted), from the parent read now, that names the
1408
- // method and carries exactly one port. The event goes no further. Every other event of that
1409
- // name is stopped too, so content never hears one, and one that fails a check doesn't use up
1410
- // the one port. The port is in this closure alone: no content holds it or can post on it. No
1411
- // second port is taken: the shell's next one (it sends one at every load of the frame, and
1412
- // WebKit fires a load for a navigation within the document) is answered on the first, that
1413
- // this document is still here;
1414
- // - the press: only the browser's own events (isTrusted), read through the platform's getters
1415
- // kept now. A mouse on its way down; a finger or a pen on its way up (one that scrolls ends in
1416
- // pointercancel: HTML's own rule for what activates); Enter or Space, not held down, on a
1417
- // native control that isn't editable (a link takes Enter alone), by its tag and type, never
1418
- // its role, which is the content's word; a click on such a control (an assistive technology's
1419
- // activation is a click alone), but not the click a form gives its submit button when Enter is
1420
- // pressed in another of its fields, which is typing, nor any click while a key is down;
1421
- // - what is told: nothing but that there was one. No place, no target, no time.
1422
- // After a press is told, what the page's calls say to its host (send, below) waits for the
1423
- // shell's word that it has the press (it tells the host before it answers), so a call made in
1424
- // the press's own handler never arrives ahead of it; a shell that doesn't answer in 250 ms
1425
- // holds nothing back.
1426
- // None of it is installed unless all of it can be (a built-in missing, or document.open, write
1427
- // or writeln not fixed in place above): the page then tells no press, and the host has the
1428
- // shell's activation alone, as before.
1429
- let pressHeld = null;
1430
- const pressParent = window.parent;
1431
- if (plan.press === true && !hostless && pressParent !== window && rewriteFixed) {
1432
- const messageProto = typeof MessageEvent === "function" ? MessageEvent.prototype : null;
1433
- const messageSourceOf = getterOf(messageProto, "source");
1434
- const messageDataOf = getterOf(messageProto, "data");
1435
- const messagePortsOf = getterOf(messageProto, "ports");
1436
- const stopNow = Event.prototype.stopImmediatePropagation;
1437
- const portProto = typeof MessagePort === "function" ? MessagePort.prototype : null;
1438
- const portPost = portProto === null ? null : portProto.postMessage;
1439
- const portStart = portProto === null ? null : portProto.start;
1440
- const eventTargetOf = getterOf(Event.prototype, "target");
1441
- const pointerTypeOf = getterOf(typeof PointerEvent === "function" ? PointerEvent.prototype : null, "pointerType");
1442
- const keyProto = typeof KeyboardEvent === "function" ? KeyboardEvent.prototype : null;
1443
- const keyOf = getterOf(keyProto, "key");
1444
- const repeatOf = getterOf(keyProto, "repeat");
1445
- const editableOf = getterOf(HTMLElement.prototype, "isContentEditable");
1446
- const designModeOf = getterOf(Document.prototype, "designMode");
1447
- const activeOf = getterOf(Document.prototype, "activeElement");
1448
- const controlTypeOf = getterOf(HTMLInputElement.prototype, "type");
1449
- // Each control's form through its own getter: a field tied to a form by its form attribute is
1450
- // not inside that form's element.
1451
- const formGetters = bare(null);
1452
- formGetters.button = getterOf(HTMLButtonElement.prototype, "form");
1453
- formGetters.input = getterOf(HTMLInputElement.prototype, "form");
1454
- formGetters.select = getterOf(HTMLSelectElement.prototype, "form");
1455
- formGetters.textarea = getterOf(HTMLTextAreaElement.prototype, "form");
1456
- const pressLater = setTimeout;
1457
- const pressNoLater = clearTimeout;
1458
- const pressListen = EventTarget.prototype.addEventListener;
1459
- const all =
1460
- messageSourceOf !== null && messageDataOf !== null && messagePortsOf !== null &&
1461
- typeof stopNow === "function" && typeof portPost === "function" && typeof portStart === "function" &&
1462
- eventTargetOf !== null && pointerTypeOf !== null && keyOf !== null && repeatOf !== null &&
1463
- editableOf !== null && designModeOf !== null && activeOf !== null && controlTypeOf !== null &&
1464
- formGetters.button !== null && formGetters.input !== null && formGetters.select !== null && formGetters.textarea !== null &&
1465
- localNameOf !== null && namespaceOf !== null && nodeTypeOf !== null;
1466
- if (all) {
1467
- let port = null;
1468
- // How many presses the shell hasn't answered yet, and the timer that stops waiting for it.
1469
- let unanswered = 0;
1470
- let giveUp = 0;
1471
- const release = () => {
1472
- unanswered = 0;
1473
- callOf(pressNoLater, window, [giveUp]);
1474
- const held = pressHeld;
1475
- pressHeld = null;
1476
- if (held !== null) {
1477
- for (let i = 0; i < held.length; i += 1) {
1478
- post(held[i]);
1479
- }
1480
- }
1481
- };
1482
- const tellPress = () => {
1483
- if (port === null) {
1484
- return;
1485
- }
1486
- try {
1487
- callOf(portPost, port, [0]);
1488
- } catch (_) {
1489
- return;
1490
- }
1491
- unanswered += 1;
1492
- if (pressHeld === null) {
1493
- pressHeld = [];
1494
- }
1495
- callOf(pressNoLater, window, [giveUp]);
1496
- giveUp = callOf(pressLater, window, [release, 250]);
1497
- };
1498
- callOf(pressListen, window, [
1499
- "message",
1500
- (event) => {
1501
- let named = false;
1502
- try {
1503
- const data = callOf(messageDataOf, event, []);
1504
- named = data !== null && typeof data === "object" && data.method === "porthole/shell/press-port";
1505
- } catch (_) {}
1506
- if (!named) {
1507
- return;
1508
- }
1509
- callOf(stopNow, event, []);
1510
- if (event.isTrusted !== true) {
1511
- return;
1512
- }
1513
- try {
1514
- const ports = callOf(messagePortsOf, event, []);
1515
- if (callOf(messageSourceOf, event, []) !== pressParent || ports === null || ports.length !== 1) {
1516
- return;
1517
- }
1518
- // Only the first is ever taken. A later one is the shell's for a load that left this
1519
- // document where it was (WebKit's, for a navigation within it, P142): told, on the
1520
- // port held, that this document is still here, so the shell goes on hearing that one.
1521
- if (port !== null) {
1522
- callOf(portPost, port, [1]);
1523
- return;
1524
- }
1525
- const taken = ports[0];
1526
- // The shell's answer to a press: it has it, and has told the host.
1527
- callOf(pressListen, taken, [
1528
- "message",
1529
- () => {
1530
- unanswered -= 1;
1531
- if (unanswered <= 0) {
1532
- release();
1533
- }
1534
- },
1535
- ]);
1536
- callOf(portStart, taken, []);
1537
- port = taken;
1538
- } catch (_) {}
1539
- },
1540
- true,
1541
- ]);
1542
- // A native control a key or a click presses: "both" (Enter and Space), "enter" (a link), or
1543
- // "" for anything else, an editable one included. By the kept getters: the tag and the type,
1544
- // never an attribute the content writes to say what it is.
1545
- const controlOf = (node) => {
1546
- if (typeOf(node) !== 1 || callOf(namespaceOf, node, []) !== XHTML) {
1547
- return "";
1548
- }
1549
- const name = callOf(localNameOf, node, []);
1550
- let kind = "";
1551
- if (name === "button" || name === "summary") {
1552
- kind = "both";
1553
- } else if (name === "input") {
1554
- const type = callOf(controlTypeOf, node, []);
1555
- kind = type === "button" || type === "submit" || type === "reset" ? "both" : "";
1556
- } else if (name === "a") {
1557
- kind = callOf(hasAttributeIn, node, ["href"]) === true ? "enter" : "";
1558
- }
1559
- return kind !== "" && callOf(editableOf, node, []) !== true ? kind : "";
1560
- };
1561
- const formOf = (node) => {
1562
- if (typeOf(node) !== 1 || callOf(namespaceOf, node, []) !== XHTML) {
1563
- return null;
1564
- }
1565
- const getter = formGetters[callOf(localNameOf, node, [])];
1566
- return typeof getter === "function" ? callOf(getter, node, []) : null;
1567
- };
1568
- // The browser's own event: nothing a page dispatches is a press.
1569
- const real = (event) => event.isTrusted === true;
1570
- // Whether a key is down: from the browser's own keydown to its keyup, or the next press of
1571
- // a pointer. No click in that time is a press. The key's own press was judged as it went
1572
- // down, where it went down: content that moves the focus to its button inside the keydown
1573
- // of an Enter typed in a text field gets that button a click of the browser's own, and a
1574
- // held key's repeats give a button one each. An assistive technology's click comes with no
1575
- // key down.
1576
- let keyDown = false;
1577
- const pointed = (down) => (event) => {
1578
- if (!real(event)) {
1579
- return;
1580
- }
1581
- keyDown = false;
1582
- try {
1583
- if ((callOf(pointerTypeOf, event, []) === "mouse") === down) {
1584
- tellPress();
1585
- }
1586
- } catch (_) {}
1587
- };
1588
- callOf(pressListen, window, ["pointerdown", pointed(true), true]);
1589
- callOf(pressListen, window, ["pointerup", pointed(false), true]);
1590
- callOf(pressListen, window, [
1591
- "keyup",
1592
- (event) => {
1593
- if (real(event)) {
1594
- keyDown = false;
1595
- }
1596
- },
1597
- true,
1598
- ]);
1599
- callOf(pressListen, window, [
1600
- "keydown",
1601
- (event) => {
1602
- if (!real(event)) {
1603
- return;
1604
- }
1605
- keyDown = true;
1606
- try {
1607
- // A key held down goes on being the key it was when it went down, wherever the focus
1608
- // has moved since: its repeats are no press.
1609
- const key = callOf(keyOf, event, []);
1610
- if ((key !== "Enter" && key !== " ") || callOf(repeatOf, event, []) === true || callOf(designModeOf, document, []) === "on") {
1611
- return;
1612
- }
1613
- const kind = controlOf(callOf(eventTargetOf, event, []));
1614
- if (kind === "both" || (kind === "enter" && key === "Enter")) {
1615
- tellPress();
1616
- }
1617
- } catch (_) {}
1618
- },
1619
- true,
1620
- ]);
1621
- callOf(pressListen, window, [
1622
- "click",
1623
- (event) => {
1624
- if (!real(event)) {
1625
- return;
1626
- }
1627
- try {
1628
- const target = callOf(eventTargetOf, event, []);
1629
- if (keyDown || controlOf(target) === "") {
1630
- return;
1631
- }
1632
- // A form's own click on its submit button, for Enter in another of its fields.
1633
- const active = callOf(activeOf, document, []);
1634
- if (active !== null && active !== target) {
1635
- const form = formOf(target);
1636
- if (form !== null && form === formOf(active)) {
1637
- return;
1638
- }
1639
- }
1640
- tellPress();
1641
- } catch (_) {}
1642
- },
1643
- true,
1644
- ]);
1645
- }
1646
- }
1647
-
1648
1393
  // The clipboard is the host's to write (P051): content can neither write nor read it. A copy
1649
1394
  // the person makes (their keys, their menu) copies their selection as the browser makes it: no
1650
1395
  // copy or cut listener of the content's runs, so none can swap what goes on the clipboard.
@@ -1863,14 +1608,8 @@ export const SHELL_RUNTIME = String.raw `(() => {
1863
1608
  window.parent.postMessage(Object.assign({ jsonrpc: "2.0" }, message), "*");
1864
1609
  }
1865
1610
  };
1866
- // After a press was told to the shell (P148), what the shell's protocol says next (a call, an
1867
- // answer) waits for the shell to have the press: posted by the release above, through post.
1868
1611
  const send = (message) => {
1869
1612
  if (plan.protocol === "shell") {
1870
- if (pressHeld !== null) {
1871
- pressHeld[pressHeld.length] = message;
1872
- return;
1873
- }
1874
1613
  post(message);
1875
1614
  }
1876
1615
  };
@@ -1911,7 +1650,7 @@ export const SHELL_RUNTIME = String.raw `(() => {
1911
1650
  // modules keep the address they loaded from; the server serves their own loads till the session
1912
1651
  // ends.
1913
1652
  const replace = History.prototype.replaceState;
1914
- // The files' origin, read from the address itself: a nested page's own origin is opaque (P111).
1653
+ // The files' origin, read from the address itself.
1915
1654
  const filesOrigin = filesBase === null ? null : new NativeURL(filesBase).origin;
1916
1655
  // A renewed sealed address (P083): one segment under the same origin's sealed prefix, checked
1917
1656
  // through the platform's own functions (content may have replaced a prototype's, and the base
@@ -1931,7 +1670,6 @@ export const SHELL_RUNTIME = String.raw `(() => {
1931
1670
  filesBases.push(base);
1932
1671
  return true;
1933
1672
  };
1934
- adoptFiles = adopt;
1935
1673
  if (filesBase !== null && typeof plan.files.expires === "number") {
1936
1674
  const nativeFetch = window.fetch.bind(window);
1937
1675
  const renewIn = (expires) => Math.max(30000, expires - Date.now() - 300000);
@@ -2501,11 +2239,6 @@ export const SHELL_RUNTIME = String.raw `(() => {
2501
2239
  case "ui/notifications/tool-input":
2502
2240
  void render(params.arguments);
2503
2241
  break;
2504
- case "porthole/files-renewed":
2505
- // From the page's parent only (the listener's check): a nested page's shell renewed its
2506
- // files' sealed address, which this page can't (its loads aren't its origin's own, P111).
2507
- adoptFiles(params.base);
2508
- break;
2509
2242
  case "ui/notifications/host-context-changed":
2510
2243
  applyTheme(params);
2511
2244
  break;
package/docs/ADOPTING.md CHANGED
@@ -319,8 +319,8 @@ composer.onClose(() => display.annotations.clearSelection());
319
319
  `"draft"` throws, as a bad anchor does (React: `onHostError`, kind `"annotations"`). The shell
320
320
  is your content server's: upgrade its Porthole first, or an older shell draws a draft as a
321
321
  posted mark without a marker. The view a draft's `activated` opens is guarded like any (below)
322
- and puts no "Post", "Submit review" or "Discard" one click away: a page can fake that click on
323
- the person's own press in the content (P107, P109).
322
+ and puts no "Post", "Submit review" or "Discard" one click away: a page can say that click
323
+ itself, at a moment it picks (P107; no gesture is asked of it since 0.16.0, P149).
324
324
  - **No drafts to a page that can pass them on**, or accept that it does: a page with the runtime's
325
325
  `db` writes and `user` can store who is drafting where (`user.get()` and the marks it is shown)
326
326
  for its author and other viewers to read before the draft is posted, and tie the posted comment
@@ -489,7 +489,7 @@ composer.onClose(() => display.annotations.clearSelection());
489
489
  stops, in reading order, named for what it is (`3 comments on "the words"`, from the `count` and
490
490
  the anchor's words, without an element's tag, P134; in English, whatever your UI's language). The
491
491
  `label` you store keeps its tag. Enter or Space on it is `activated`,
492
- through the same path and the same gesture check as a click: nothing to handle apart. It is the
492
+ through the same path as a click: nothing to handle apart. It is the
493
493
  page's focus order, which a page can steal from or hide a marker from, and it is one more
494
494
  `activated` the content can time: keep your own list of marks as the way a keyboard can rely on,
495
495
  with `annotations.focus(id)` to bring one into view, and leave your view's guard as it is (it
@@ -513,9 +513,7 @@ composer.onClose(() => display.annotations.clearSelection());
513
513
  `display.annotations.focusMark(id)` (React: `focusMark(id)` on the `ref`) to put the keyboard back
514
514
  on the marker. It carries no content and reports nothing; an id with no marker, or a marker the
515
515
  page has moved away, does nothing and throws nothing; the page can take the focus straight back.
516
- Close the view first: from one of your text fields that still has focus, the focus guard takes
517
- the move for the page's, undoes it and counts it (`focusTaken`). Keep your own list of marks as
518
- the way that holds.
516
+ Keep your own list of marks as the way that holds.
519
517
  On a calm page that lands at once, from your `<body>`. While the frame is finding its marks (a
520
518
  `show` just sent, which many hosts send as a card closes, or content that just changed) the word
521
519
  waits, up to a second, and is then dropped unless the focus is in the frame by then. A word the
@@ -541,17 +539,8 @@ composer.onClose(() => display.annotations.clearSelection());
541
539
 
542
540
  Keep the check: on a button of yours, the person has moved on, and `display.focus()` would take the
543
541
  keyboard from them. With React, whose `ref` has no `focus()`, call the frame's own `focus()` for
544
- that step: it is only ever taken for the page's from a text field, and this one starts on `<body>`.
545
- An id with no marker then leaves the focus in the frame, with the keys going to the page.
546
-
547
- **Nested pages (P136).** `display.focus()` reaches a nested page on every engine, whether or not
548
- it had the focus. Two ways don't:
549
- - The frame's own `focus()`, which the React step above is: it stops at the page's shell (Chromium
550
- and WebKit from anywhere, Firefox from a focused element of yours), so a `focusMark` that waits
551
- is dropped even after it, and nothing tells you. On a calm page the second call doesn't wait and
552
- lands. On a page that is changing, keep your own list of marks as the way back.
553
- - `display.focus()` inside a key's own handler, on Firefox (measured on a nested page): it moves
554
- nothing. Call it from a task, as the timer above does.
542
+ that step. An id with no marker then leaves the focus in the frame, with the keys going to the
543
+ page.
555
544
 
556
545
  Without the second call, nothing changes on a calm page. On a busy one, a word that the frame
557
546
  finishes with before your own move is lost where it used to land, so the person gets the frame and
@@ -645,54 +634,33 @@ display.on("navigated", () => bar.reset());
645
634
  const result = await frame.current?.find(query, { direction: "next" });
646
635
  ```
647
636
 
648
- ### The keyboard: what a display can take, and what you get
637
+ ### The keyboard: a display can take it
649
638
 
650
639
  Any display can move the keyboard into its frame (`element.focus()` in the page, with no gesture
651
640
  on Chromium and WebKit), and what the person goes on typing in your composer or chat box then goes
652
- to the page. `createHost` (and so `PortholeView`) guards every display (P109): when focus leaves
653
- one of your page's text fields (a `<textarea>`, an `<input>` that takes text, a `contenteditable`
654
- region) for a display's frame without the person's press on the frame or a Tab into it, focus goes
655
- back to the field, and the display tells you; a display that keeps doing it is stopped.
641
+ to the page, until they see it and click back. Porthole doesn't stop that. From 0.13 to 0.15 a
642
+ guard took such a move back when it judged the move to be the page's; it could only guess whose
643
+ move it was (your page sees no press inside a cross-site frame), and a wrong guess refused a
644
+ person's own click. 0.16.0 removed it ([P149](DECISIONS.md)): no `focusTaken` event, no
645
+ `onFocusTaken`, and a display is never stopped for taking the keyboard.
656
646
 
657
647
  ```js
658
- display.on("focusTaken", ({ typing }) => toast(typing ? "This page tried to take what you were typing." : "This page tried to take the keyboard."));
659
- display.on("contentError", ({ message }) => log(message)); // "The content kept taking the keyboard from the page; it was stopped."
660
- // Moving focus into a display yourself (a "focus the page" shortcut): use the display's own move.
661
- display.focus(); // not frame.focus(): from a text field, that one is taken for the page's and undone
662
- // Opening your composer focused: only in a comment mode the person started, for a composer that can
663
- // only save a draft (Enter adds it to the batch; submitting is only your own "Submit N"), and that
664
- // shows plainly it is a draft (THREAT_MODEL §6, P112); any other view a report opens takes no focus (P134's
665
- // exception, §6, is a container only, and its own conditions). Then
666
- // Porthole's move, not textarea.focus().
648
+ // Moving focus into a display yourself (a "focus the page" shortcut):
649
+ display.focus();
650
+ // Moving it to a field of yours (opening your composer focused): Porthole's move, which lands on
651
+ // every engine. Firefox ignores a plain focus() while a frame that takes focus back on its blur
652
+ // holds it.
667
653
  import { focusField } from "@botiverse/porthole";
668
- focusField(composer.textarea); // Firefox ignores a plain focus() while a fighting frame holds focus
654
+ focusField(composer.textarea);
669
655
  ```
670
656
 
671
- - **Free:** the guard, on by default, with no option. A page gets at most the keys typed before
672
- focus is back (none or one in a sentence, measured on all three engines); three tries while the
673
- person types (within 10 s), or five within 2 s, stop the display (`reload()` runs it again).
674
- - **Yours:** don't move focus from a text field into a display with the frame's own `focus()`
675
- (use `display.focus()`), nor into your composer with the field's own `focus()` where a display
676
- may hold focus (use `focusField`: on Firefox a page with the person's gesture that takes focus
677
- back on its blur keeps a plain `focus()` from landing, and gets the keys); with a platform of your own (a native web view), implement `focused`,
678
- `onFocusTaken` and `focus` on its surface, or a display can read what is typed beside it; know
679
- the limits (THREAT_MODEL §7 "The keyboard": on Firefox, which shows your page no press
680
- in a frame, a page keeps the keyboard if the pointer came over its frame after the person last
681
- typed and after the field got focus; moves between two frames aren't judged).
682
- - **Served pages in full Chromium:** nest them ("Nested pages" below, P111). A served page's
683
- frame there is out of process: your page sees no press in it, so a person's click into the
684
- page's field is taken back. A nested page's shell sees it: a move into the frame is the
685
- person's if the shell's activation turned on within the last second and you saw no press or key
686
- of your own since. A second press in the page within 5 s of the last turns nothing on; from
687
- 0.15.3 the page's runtime tells its shell each real press (P148), so the person's next press in
688
- the page counts as the first did, after they went back to your composer too. Nothing for you to
689
- do but run 0.15.3 on both sides (your page, and whatever serves the content origins): an older
690
- side ignores what the newer says, and the 5 s stay until both are new. A
691
- nested page that takes the keyboard back as the guard returns it is fought as any page is, and
692
- stopped (P120). A move into the page within 250 ms of the person's key on your page is taken
693
- back on every engine (no hand presses that fast after typing, P122); on full Chromium a key the
694
- person types into the page just as it takes the keyboard, slower than that, can still pass for a
695
- press (THREAT_MODEL §7).
657
+ - **Yours:** where a field must never lose a key to a page (a password, a payment field), don't
658
+ show a display you don't trust beside it. A view a display's report opens still takes no focus
659
+ and no press for its first 500 ms (THREAT_MODEL §6); that is your view's own guard, and it
660
+ doesn't depend on this.
661
+ - **A platform of your own** (a native web view): `focus` on its surface is what `display.focus()`
662
+ calls; `focused`, if you give it, says whether the keyboard is in the display, which the find
663
+ shortcut reads (P131). `onFocusTaken` is no longer read.
696
664
 
697
665
  ## 4. Served pages: the host kit
698
666
 
@@ -755,16 +723,15 @@ nodeServer({ content, app: async (request) => (await routes(request)) ?? app(req
755
723
  or tells it, it isn't in `data-porthole-hosts`, and redirect entry and the handoff stay
756
724
  `appOrigins`' alone. Exact https origins (`http://` on loopback), none an app origin. Your own
757
725
  page between them is still the frame's parent, and its `frame-ancestors` is yours to set. A
758
- content Worker of your own passes the same list to `statusPage`, `doorResponse`,
759
- `doorStatusResponse` and `nestedShellResponse` (`framedBy`), and puts it in the nested page's
760
- rows below (`<framedBy>`). The outer page is then an ancestor of content: a content page can
726
+ content Worker of your own passes the same list to `statusPage`, `doorResponse` and
727
+ `doorStatusResponse` (`framedBy`). The outer page is then an ancestor of content: a content page can
761
728
  `postMessage` it and every frame in its tree, and learn its origin, so the outer page's authors
762
729
  must check `event.source` and `event.origin` in every message listener
763
730
  ([THREAT_MODEL.md §6 "What every host must do"](THREAT_MODEL.md#what-every-host-must-do)).
764
731
  - **`embeds`** (P143): to let any site embed a public artifact page, set `embeds: true` and, from
765
732
  one route of your own that decides the page is public (never your reader's issue endpoint),
766
- issue it with `{ anonymous: true, embed: true }` (no `level`, no `user`; an artifact's page that
767
- isn't nested): `host.server.issue(instance, { anonymous: true, embed: true })`. Never answer
733
+ issue it with `{ anonymous: true, embed: true }` (no `level`, no `user`; an artifact's page):
734
+ `host.server.issue(instance, { anonymous: true, embed: true })`. Never answer
768
735
  `embed` from `access`: it answers your readers, and the kit refuses it there (409 from the issue
769
736
  endpoint and a clean address's resolve, its 409 page at a clean address's tab; P145). That
770
737
  session's answers say `frame-ancestors *`, and nothing else's do. It has no
@@ -893,70 +860,8 @@ artifact: { preset: "artifact", options: { layout: { kind: "fill" }, nestedFrame
893
860
 
894
861
  It is a weakening: a nested frame is a realm of its own where the shell's defenses never ran, so
895
862
  content there has WebRTC (a way out past `connect-src`) and can put text on the clipboard from a
896
- click, with no notice. The CSP still governs every frame's loads and navigations. Not for url mode,
897
- nested pages or live widgets (refused). Turn it on only where your product accepts that.
898
-
899
- ### Nested pages: the page below Porthole's shell
900
-
901
- `nested: true` (P111) on an artifact kind served by the host kit puts the page in a frame of its
902
- own below Porthole's shell, with an opaque origin of its own. The shell, the page and its files are
903
- served on a label of the scope's own, `porthole-<24 base32>.<content domain>` (P114), not on the
904
- scope's label: the scope's other displays run content there with `allow-same-origin`, which would
905
- reach the shell (porthole#56). Do it where people
906
- type beside your displays: in full Chromium (a person's browser, not Playwright's headless shell) a
907
- served page's frame is out of process, and your page can't see a press in it, so without nesting a
908
- real click into the page's field is taken back and `comments.open` from a real click is refused
909
- within 5 s of any input on your page (porthole#53). The page's shell sees it, and tells your page.
910
-
911
- ```ts
912
- const displays = defineDisplays({
913
- page: {
914
- preset: "artifact",
915
- // No `served.storage`: a nested page keeps no storage of its own (localStorage lasts the load).
916
- options: { runtime: "1", capabilities: { annotate: {}, comments: {} }, nested: true },
917
- },
918
- });
919
- ```
920
-
921
- Nothing else changes on your page: the same `createHost` (or `PortholeFrame`), the same handlers
922
- and events, the same `frame-src` (the content domain's wildcard covers the shell's label). Your
923
- frames route answers the shell's origin (`issue`'s location); a clean address stays on the scope's
924
- label and sends the browser on to the shell's with a one-time ticket.
925
-
926
- **Route the shell's label.** `porthole-<…>.<content domain>` must reach the content server as
927
- your other labels do. Wildcard DNS and a wildcard certificate (`*.<content domain>`) already cover
928
- it; a route, an edge rule or a firewall that matches labels by a pattern of yours (`a-*`) must let
929
- `porthole-*` through too. Every `porthole-` label is Porthole's: your naming may not make one
930
- (`content.name` giving one throws), and `reserved` may not hold one a shell would be on. The display has one more event, `storage` (`{ used }`, once per
931
- run: whether the page touched `localStorage` or `sessionStorage`, never what it kept), for you to
932
- count the pages that would need storage. A nested page's workers come from Blob URLs (a worker from
933
- a script of its own set is refused: its origin is opaque), which may `importScripts` the set's
934
- scripts; Chromium refuses a Blob module worker there. Not yet with a nested page: the asset library (`assets`)
935
- and Porthole's libraries (`egress.libraries`); the config refuses them.
936
-
937
- What a content origin serves for a nested page (`/server` does all of it; a content Worker of your
938
- own answers the same, with the helpers `/server` exports: `nestedLabelOf`, `nestedShellResponse`,
939
- `nestedFileCsp`, `NESTED_FILE_HEADERS`, `nestedAncestors`). `<origin>` is the shell's own,
940
- `https://<nestedLabelOf(label)>.<content domain>`, where `label` is the scope's label (the one its
941
- other displays are served on); `<token>` is the access in the path (Porthole's sealed session, or a
942
- signed token of your own: the shell only needs addresses under the prefix). Your frame location
943
- for a nested page is on `<origin>`.
944
-
945
- **The rule** (P114): `<origin>` answers the four rows below and Porthole's status pages, nothing
946
- else (no other display, no clean address, no asset, no app), and the scope's label never answers a
947
- nested page's shell, page or files. That is what keeps the shell's realm (its word to your page,
948
- the page's sealed address) out of every other display's reach. Porthole holds the shell to that
949
- label (P121): `createHost` refuses a nested page located anywhere else (a host error, `locate`, and
950
- no frame), `nestedShellResponse` throws for another origin, and the shell runs nowhere else. That
951
- `<origin>` answers nothing but these is yours to hold: Porthole can't see your Worker's routes.
952
-
953
- | Request | Answer |
954
- | --- | --- |
955
- | `<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. |
956
- | `<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> <framedBy>")`: 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`). |
957
- | `<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, `<origin> <host origins> <framedBy>`): 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. |
958
- | `<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. |
959
- | A token that ended, under the prefix | Porthole's status page (`401`, reason `session`), `frame-ancestors <origin> <host origins> <framedBy>`: it tells the shell, which tells your page (`outcome` blocked). |
863
+ click, with no notice. The CSP still governs every frame's loads and navigations. Not for url mode
864
+ or live widgets (refused). Turn it on only where your product accepts that.
960
865
 
961
866
  ### The capability runtime: pages that are apps
962
867
 
@@ -1004,10 +909,11 @@ if (shown && !shown.ok) return <VersionError problems={shown.problems} />; //
1004
909
  <PortholeView display="page" instance={instance} declaration={shown ? shown.declaration : null} />
1005
910
  ```
1006
911
 
1007
- - **A page's draft in your composer** (P108, P109): `comments.open` reaches your handler only from
1008
- a gesture with the person in that frame (a press in it, a Tab into it; not their typing in your
1009
- UI), but the page still picks the moment (the second click of a double click, a field it asked
1010
- them to type into). So the composer it fills is the person's to act on:
912
+ - **A page's draft in your composer** (P108): `comments.open` reaches your handler whenever the
913
+ page calls it, within its rate (30 a minute by default). No proof of a click is asked since
914
+ 0.16.0 ([P149](DECISIONS.md)): the page picks the moment, and may call with no one pressing
915
+ anything. So the composer it fills is the person's to act on, and whether it opens at all is
916
+ yours to say (return false while the person is writing, or after they closed several unused):
1011
917
 
1012
918
  ```js
1013
919
  // A composer the page filled: its words are the page's until the person acts in it.
@@ -1132,7 +1038,7 @@ hears those as a `hostError` of kind `"frame-status"` (log it, show nothing for
1132
1038
  fallback from `outcome` only. A url-mode app is the exception: it can say any outcome (THREAT_MODEL
1133
1039
  S6).
1134
1040
 
1135
- **The door (P125).** A served display that isn't nested (a served shell, a page, a view through the
1041
+ **The door (P125).** A served display (a served shell, a page, a view through the
1136
1042
  sandbox proxy) is framed on its scope's origin, where the scope's other displays run content: its
1137
1043
  own frame can't be trusted for how loading went (a same-scope sibling could speak for it). So
1138
1044
  `createHost` first frames a **door** — a page of Porthole's on the display's origin, in a hidden
@@ -1142,14 +1048,14 @@ for those kinds). The content frame's own frame status is then never taken, and
1142
1048
  requirements:
1143
1049
 
1144
1050
  - **Deploy the server (or your content Worker) before the host.** The door is minted and served by
1145
- the server; a host given a served non-nested location with no door (from a server that doesn't
1051
+ the server; a host given a served location with no door (from a server that doesn't
1146
1052
  yet mint one) builds no frame for it: `blocked: locate`, and a `hostError` of kind `"door"`
1147
1053
  naming the fix. Upgrade the server/Worker first, then the host. This is a hard requirement, not a
1148
1054
  preference.
1149
1055
  - **A custom locator must pass `door` through, and issue anew for every run.** If you rebuild
1150
1056
  `FrameLocation` yourself (a locator of your own rather than `httpLocator`), carry `door` from your
1151
1057
  issue endpoint unchanged; `httpLocator` and the host kit's client already do. Dropping it refuses
1152
- every served non-nested display, as above. And `locate` is called again on every run (a reload,
1058
+ every served display, as above. And `locate` is called again on every run (a reload,
1153
1059
  a restart after the content navigated its frame away): answer each call with a fresh issue (a new
1154
1060
  ticket, a new door ticket). A location reused from an earlier run carries tickets already taken,
1155
1061
  so its door says `blocked: session` ("this link has been used"), and `createHost` tells you
@@ -1157,8 +1063,7 @@ requirements:
1157
1063
  display.)
1158
1064
  - **A platform of your own makes the web's doors.** A `PlatformHost` that wraps
1159
1065
  `webPlatform.createSurface` must also give `createDoor` (delegate to `webPlatform.createDoor`):
1160
- a platform without doors frames no served display that isn't nested (`blocked: locate`, a `door`
1161
- host error).
1066
+ a platform without doors frames no served display (`blocked: locate`, a `door` host error).
1162
1067
  - **The door sits in the display's container while it decides**, a hidden 0×0 frame
1163
1068
  (`data-porthole-door`), removed once it says its word. Code that grabs
1164
1069
  `container.querySelector("iframe")` just after mounting may get the door: select
@@ -1180,8 +1085,7 @@ Worker routes `DOOR_PATH + <key>` (`/__porthole/door/<key>`) on every label —
1180
1085
  (`TicketRecord.door === true`, bound to the label and key), run the same access, document and entry
1181
1086
  checks the content route runs for that grant, then answer `doorResponse({ hostOrigins, framedBy })` (open) or
1182
1087
  `doorStatusResponse({ status, reason, code?, hostOrigins, framedBy })` (401 `session` / 403 `denied` / 404
1183
- `not-found` / 500 `error`). Refuse a door ticket at `/__porthole/d/`, and serve no door on a nested
1184
- page's shell label. `DOOR_PATH`, `doorResponse` and `doorStatusResponse` are exported from
1088
+ `not-found` / 500 `error`). Refuse a door ticket at `/__porthole/d/`. `DOOR_PATH`, `doorResponse` and `doorStatusResponse` are exported from
1185
1089
  `@botiverse/porthole/server`.
1186
1090
 
1187
1091
  **A host that signs its own tickets** (P126) — its server mints its own ticket for a display and its
@@ -1197,7 +1101,7 @@ document and version, a file set's entry being a page (`not-found`), `doorRespon
1197
1101
  about the request but its method: **you must have authenticated the request and established the
1198
1102
  grant yourself**, as before `issue`. Pass the request so `authorize.check` sees it, and `{ page }`
1199
1103
  as the fourth argument for a frame that opens at a file set's page below its version. It throws for
1200
- an instance with no door (a nested page, a url-mode app) and for an instance or grant `issue` would
1104
+ an instance with no door (a url-mode app) and for an instance or grant `issue` would
1201
1105
  refuse. The content route still takes its own ticket and checks again (P050).
1202
1106
 
1203
1107
  `porthole.config(kind)` is the served config while frames are served, the opaque one while they