@botiverse/porthole 0.15.2 → 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 (109) hide show
  1. package/CHANGELOG.md +89 -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 +9 -14
  29. package/dist/isolation/served.js +17 -31
  30. package/dist/isolation/types.d.ts +2 -19
  31. package/dist/isolation/types.js +0 -17
  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 -98
  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/pages.d.ts +9 -2
  49. package/dist/server/pages.js +28 -8
  50. package/dist/server/server.js +28 -166
  51. package/dist/server/types.d.ts +7 -7
  52. package/dist/shell/plan.js +2 -2
  53. package/dist/shell/runtime.js +1 -9
  54. package/docs/ADOPTING.md +42 -135
  55. package/docs/ARCHITECTURE.md +0 -33
  56. package/docs/DECISIONS.md +296 -9
  57. package/docs/DESIGN.md +27 -50
  58. package/docs/THREAT_MODEL.md +140 -242
  59. package/package.json +1 -1
  60. package/src/bridge/bridge.ts +1 -17
  61. package/src/check/page.ts +1 -1
  62. package/src/compile/policy.ts +1 -11
  63. package/src/config/capabilities.ts +8 -14
  64. package/src/config/schema.ts +2 -13
  65. package/src/config/validate.ts +0 -28
  66. package/src/conformance/behavior.ts +50 -52
  67. package/src/conformance/clipboard.ts +56 -1
  68. package/src/displays/displays.ts +1 -3
  69. package/src/guide/limits.ts +1 -1
  70. package/src/guide/runtime.ts +1 -1
  71. package/src/host/create-host.ts +6 -52
  72. package/src/host/door.ts +1 -1
  73. package/src/host/locate.ts +2 -2
  74. package/src/host/outcome.ts +8 -21
  75. package/src/host/types.ts +6 -20
  76. package/src/index.ts +2 -4
  77. package/src/isolation/served.ts +18 -37
  78. package/src/isolation/types.ts +2 -24
  79. package/src/platform/focus-field.ts +18 -0
  80. package/src/platform/types.ts +6 -21
  81. package/src/platform/web.ts +8 -116
  82. package/src/presets/presets.ts +0 -3
  83. package/src/react/frame.tsx +0 -10
  84. package/src/runtime/contract.ts +4 -4
  85. package/src/runtime/types.generated.ts +6 -6
  86. package/src/server/files.ts +4 -19
  87. package/src/server/host.ts +1 -1
  88. package/src/server/index.ts +4 -16
  89. package/src/server/naming.ts +1 -1
  90. package/src/server/pages.ts +38 -12
  91. package/src/server/server.ts +29 -189
  92. package/src/server/types.ts +7 -7
  93. package/src/shell/plan.ts +2 -2
  94. package/src/shell/runtime.ts +1 -9
  95. package/types/runtime/v1/artifact.d.ts +2 -3
  96. package/types/runtime/v1/assets.d.ts +1 -1
  97. package/types/runtime/v1/chat.d.ts +2 -2
  98. package/types/runtime/v1/comments.d.ts +1 -1
  99. package/types/runtime/v1/downloads.d.ts +2 -2
  100. package/types/runtime/v1/links.d.ts +2 -2
  101. package/dist/platform/focus-guard.d.ts +0 -252
  102. package/dist/platform/focus-guard.js +0 -764
  103. package/dist/server/nested.d.ts +0 -66
  104. package/dist/server/nested.js +0 -120
  105. package/dist/shell/frame.d.ts +0 -28
  106. package/dist/shell/frame.js +0 -338
  107. package/src/platform/focus-guard.ts +0 -999
  108. package/src/server/nested.ts +0 -156
  109. package/src/shell/frame.ts +0 -371
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,51 +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: after the
687
- person went back to your composer, their next move in is taken back until then, or a Tab. A
688
- nested page that takes the keyboard back as the guard returns it is fought as any page is, and
689
- stopped (P120). A move into the page within 250 ms of the person's key on your page is taken
690
- back on every engine (no hand presses that fast after typing, P122); on full Chromium a key the
691
- person types into the page just as it takes the keyboard, slower than that, can still pass for a
692
- 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.
693
664
 
694
665
  ## 4. Served pages: the host kit
695
666
 
@@ -752,16 +723,15 @@ nodeServer({ content, app: async (request) => (await routes(request)) ?? app(req
752
723
  or tells it, it isn't in `data-porthole-hosts`, and redirect entry and the handoff stay
753
724
  `appOrigins`' alone. Exact https origins (`http://` on loopback), none an app origin. Your own
754
725
  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`), and puts it in the nested page's
757
- 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
758
728
  `postMessage` it and every frame in its tree, and learn its origin, so the outer page's authors
759
729
  must check `event.source` and `event.origin` in every message listener
760
730
  ([THREAT_MODEL.md §6 "What every host must do"](THREAT_MODEL.md#what-every-host-must-do)).
761
731
  - **`embeds`** (P143): to let any site embed a public artifact page, set `embeds: true` and, from
762
732
  one route of your own that decides the page is public (never your reader's issue endpoint),
763
- issue it with `{ anonymous: true, embed: true }` (no `level`, no `user`; an artifact's page that
764
- 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
765
735
  `embed` from `access`: it answers your readers, and the kit refuses it there (409 from the issue
766
736
  endpoint and a clean address's resolve, its 409 page at a clean address's tab; P145). That
767
737
  session's answers say `frame-ancestors *`, and nothing else's do. It has no
@@ -890,70 +860,8 @@ artifact: { preset: "artifact", options: { layout: { kind: "fill" }, nestedFrame
890
860
 
891
861
  It is a weakening: a nested frame is a realm of its own where the shell's defenses never ran, so
892
862
  content there has WebRTC (a way out past `connect-src`) and can put text on the clipboard from a
893
- click, with no notice. The CSP still governs every frame's loads and navigations. Not for url mode,
894
- nested pages or live widgets (refused). Turn it on only where your product accepts that.
895
-
896
- ### Nested pages: the page below Porthole's shell
897
-
898
- `nested: true` (P111) on an artifact kind served by the host kit puts the page in a frame of its
899
- own below Porthole's shell, with an opaque origin of its own. The shell, the page and its files are
900
- served on a label of the scope's own, `porthole-<24 base32>.<content domain>` (P114), not on the
901
- scope's label: the scope's other displays run content there with `allow-same-origin`, which would
902
- reach the shell (porthole#56). Do it where people
903
- type beside your displays: in full Chromium (a person's browser, not Playwright's headless shell) a
904
- served page's frame is out of process, and your page can't see a press in it, so without nesting a
905
- real click into the page's field is taken back and `comments.open` from a real click is refused
906
- within 5 s of any input on your page (porthole#53). The page's shell sees it, and tells your page.
907
-
908
- ```ts
909
- const displays = defineDisplays({
910
- page: {
911
- preset: "artifact",
912
- // No `served.storage`: a nested page keeps no storage of its own (localStorage lasts the load).
913
- options: { runtime: "1", capabilities: { annotate: {}, comments: {} }, nested: true },
914
- },
915
- });
916
- ```
917
-
918
- Nothing else changes on your page: the same `createHost` (or `PortholeFrame`), the same handlers
919
- and events, the same `frame-src` (the content domain's wildcard covers the shell's label). Your
920
- frames route answers the shell's origin (`issue`'s location); a clean address stays on the scope's
921
- label and sends the browser on to the shell's with a one-time ticket.
922
-
923
- **Route the shell's label.** `porthole-<…>.<content domain>` must reach the content server as
924
- your other labels do. Wildcard DNS and a wildcard certificate (`*.<content domain>`) already cover
925
- it; a route, an edge rule or a firewall that matches labels by a pattern of yours (`a-*`) must let
926
- `porthole-*` through too. Every `porthole-` label is Porthole's: your naming may not make one
927
- (`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
928
- run: whether the page touched `localStorage` or `sessionStorage`, never what it kept), for you to
929
- count the pages that would need storage. A nested page's workers come from Blob URLs (a worker from
930
- a script of its own set is refused: its origin is opaque), which may `importScripts` the set's
931
- scripts; Chromium refuses a Blob module worker there. Not yet with a nested page: the asset library (`assets`)
932
- and Porthole's libraries (`egress.libraries`); the config refuses them.
933
-
934
- What a content origin serves for a nested page (`/server` does all of it; a content Worker of your
935
- own answers the same, with the helpers `/server` exports: `nestedLabelOf`, `nestedShellResponse`,
936
- `nestedFileCsp`, `NESTED_FILE_HEADERS`, `nestedAncestors`). `<origin>` is the shell's own,
937
- `https://<nestedLabelOf(label)>.<content domain>`, where `label` is the scope's label (the one its
938
- other displays are served on); `<token>` is the access in the path (Porthole's sealed session, or a
939
- signed token of your own: the shell only needs addresses under the prefix). Your frame location
940
- for a nested page is on `<origin>`.
941
-
942
- **The rule** (P114): `<origin>` answers the four rows below and Porthole's status pages, nothing
943
- else (no other display, no clean address, no asset, no app), and the scope's label never answers a
944
- nested page's shell, page or files. That is what keeps the shell's realm (its word to your page,
945
- the page's sealed address) out of every other display's reach. Porthole holds the shell to that
946
- label (P121): `createHost` refuses a nested page located anywhere else (a host error, `locate`, and
947
- no frame), `nestedShellResponse` throws for another origin, and the shell runs nowhere else. That
948
- `<origin>` answers nothing but these is yours to hold: Porthole can't see your Worker's routes.
949
-
950
- | Request | Answer |
951
- | --- | --- |
952
- | `<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. |
953
- | `<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`). |
954
- | `<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. |
955
- | `<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. |
956
- | 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.
957
865
 
958
866
  ### The capability runtime: pages that are apps
959
867
 
@@ -1001,10 +909,11 @@ if (shown && !shown.ok) return <VersionError problems={shown.problems} />; //
1001
909
  <PortholeView display="page" instance={instance} declaration={shown ? shown.declaration : null} />
1002
910
  ```
1003
911
 
1004
- - **A page's draft in your composer** (P108, P109): `comments.open` reaches your handler only from
1005
- a gesture with the person in that frame (a press in it, a Tab into it; not their typing in your
1006
- UI), but the page still picks the moment (the second click of a double click, a field it asked
1007
- 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):
1008
917
 
1009
918
  ```js
1010
919
  // A composer the page filled: its words are the page's until the person acts in it.
@@ -1129,7 +1038,7 @@ hears those as a `hostError` of kind `"frame-status"` (log it, show nothing for
1129
1038
  fallback from `outcome` only. A url-mode app is the exception: it can say any outcome (THREAT_MODEL
1130
1039
  S6).
1131
1040
 
1132
- **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
1133
1042
  sandbox proxy) is framed on its scope's origin, where the scope's other displays run content: its
1134
1043
  own frame can't be trusted for how loading went (a same-scope sibling could speak for it). So
1135
1044
  `createHost` first frames a **door** — a page of Porthole's on the display's origin, in a hidden
@@ -1139,14 +1048,14 @@ for those kinds). The content frame's own frame status is then never taken, and
1139
1048
  requirements:
1140
1049
 
1141
1050
  - **Deploy the server (or your content Worker) before the host.** The door is minted and served by
1142
- 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
1143
1052
  yet mint one) builds no frame for it: `blocked: locate`, and a `hostError` of kind `"door"`
1144
1053
  naming the fix. Upgrade the server/Worker first, then the host. This is a hard requirement, not a
1145
1054
  preference.
1146
1055
  - **A custom locator must pass `door` through, and issue anew for every run.** If you rebuild
1147
1056
  `FrameLocation` yourself (a locator of your own rather than `httpLocator`), carry `door` from your
1148
1057
  issue endpoint unchanged; `httpLocator` and the host kit's client already do. Dropping it refuses
1149
- 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,
1150
1059
  a restart after the content navigated its frame away): answer each call with a fresh issue (a new
1151
1060
  ticket, a new door ticket). A location reused from an earlier run carries tickets already taken,
1152
1061
  so its door says `blocked: session` ("this link has been used"), and `createHost` tells you
@@ -1154,8 +1063,7 @@ requirements:
1154
1063
  display.)
1155
1064
  - **A platform of your own makes the web's doors.** A `PlatformHost` that wraps
1156
1065
  `webPlatform.createSurface` must also give `createDoor` (delegate to `webPlatform.createDoor`):
1157
- a platform without doors frames no served display that isn't nested (`blocked: locate`, a `door`
1158
- host error).
1066
+ a platform without doors frames no served display (`blocked: locate`, a `door` host error).
1159
1067
  - **The door sits in the display's container while it decides**, a hidden 0×0 frame
1160
1068
  (`data-porthole-door`), removed once it says its word. Code that grabs
1161
1069
  `container.querySelector("iframe")` just after mounting may get the door: select
@@ -1177,8 +1085,7 @@ Worker routes `DOOR_PATH + <key>` (`/__porthole/door/<key>`) on every label —
1177
1085
  (`TicketRecord.door === true`, bound to the label and key), run the same access, document and entry
1178
1086
  checks the content route runs for that grant, then answer `doorResponse({ hostOrigins, framedBy })` (open) or
1179
1087
  `doorStatusResponse({ status, reason, code?, hostOrigins, framedBy })` (401 `session` / 403 `denied` / 404
1180
- `not-found` / 500 `error`). Refuse a door ticket at `/__porthole/d/`, and serve no door on a nested
1181
- 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
1182
1089
  `@botiverse/porthole/server`.
1183
1090
 
1184
1091
  **A host that signs its own tickets** (P126) — its server mints its own ticket for a display and its
@@ -1194,7 +1101,7 @@ document and version, a file set's entry being a page (`not-found`), `doorRespon
1194
1101
  about the request but its method: **you must have authenticated the request and established the
1195
1102
  grant yourself**, as before `issue`. Pass the request so `authorize.check` sees it, and `{ page }`
1196
1103
  as the fourth argument for a frame that opens at a file set's page below its version. It throws for
1197
- 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
1198
1105
  refuse. The content route still takes its own ticket and checks again (P050).
1199
1106
 
1200
1107
  `porthole.config(kind)` is the served config while frames are served, the opaque one while they
@@ -201,23 +201,6 @@ Access is gated by a one-time ticket exchanged for a scoped cookie. Where the ho
201
201
  holds the page and needs no stable origin, the shell writes it into an opaque
202
202
  frame instead.
203
203
 
204
- A **nested** page (P111) splits the shell from the page. The address the host frames
205
- serves Porthole's shell alone: a document with no content, on an origin of its own (a
206
- label of the scope's, `porthole-<…>`, on which nothing else is ever served, P114). It
207
- frames the page in a child sandboxed without `allow-same-origin` (an opaque origin) at
208
- the page's sealed files' address on that origin, fetched without a cookie, and passes
209
- messages between the host and the page:
210
-
211
- ```
212
- Host app Shell (its own origin) Page (opaque child)
213
- │ frame src = ticketed URL ──►│ frames the sealed address ───►│ runtime + page
214
- │◄── the page's messages ──────│◄── postMessage (by source) ───│
215
- │── the host's messages ──────►│── postMessage ───────────────►│
216
- │◄── porthole/shell/state ─────│ its own activation, its focus │
217
- │── porthole/shell/look ──────►│ look now (as a move is heard) │
218
- │── porthole/shell/focus ─────►│ display.focus(): on to the ──►│ the page's window
219
- ```
220
-
221
204
  ### URL frame
222
205
 
223
206
  ```
@@ -283,22 +266,6 @@ several displays on one page are in [THREAT_MODEL.md](THREAT_MODEL.md).
283
266
  matches find found) is the content's word even when the shell says it, since they
284
267
  share a realm: the host bounds it and uses it as a UI hint, never as a permission
285
268
  (P053, P131). What the host sends in (a mark, a find query) the content can read.
286
- A nested page (P111) is the one place they don't: the shell is a document of its
287
- own, the page's parent, on another origin than the page's (opaque), so the page
288
- reaches nothing of the shell's realm. Nor does any other content: the shell's
289
- origin is a label of its own that hosts nothing but nested pages' shells, their
290
- opaque pages, those pages' files and status pages (P114), never the scope's
291
- origin, where the scope's other displays run content with `allow-same-origin`
292
- (porthole#56). The server holds that rule, not the host's layout. The shell trusts the page's messages by
293
- `event.source` alone and passes them on unchanged, never in its own namespace
294
- (`porthole/shell/`); what it says in that namespace is the shell's own word (its
295
- transient activation, which only a press or key in the page turns on, and whether
296
- focus is in it), and the host, which knows the frame is nested from its config
297
- only, uses it to tell the person's gesture from the page's (the focus guard,
298
- `comments.open`). The host's own words in that namespace (its ask to look, P120)
299
- go to the shell alone. A key and a press look the same in that word, so the host
300
- doesn't ask it while it fights a frame for the keyboard (P120). Everything else
301
- the page says is still the content's word.
302
269
 
303
270
  5. **Host's decision ↔ content domain.** Authentication and authorization
304
271
  *policy* are the host's; carrying the host's decision safely onto the content