@botiverse/porthole 0.14.0 → 0.14.1

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 (41) hide show
  1. package/CHANGELOG.md +770 -0
  2. package/dist/annotate/types.d.ts +4 -1
  3. package/dist/annotate/types.js +2 -0
  4. package/dist/annotate/validate.d.ts +2 -1
  5. package/dist/annotate/validate.js +11 -4
  6. package/dist/check/page-source.js +1 -1
  7. package/dist/compile/policy.js +2 -2
  8. package/dist/conformance/harness-source.js +1 -1
  9. package/dist/host/create-host.js +5 -0
  10. package/dist/host/types.d.ts +7 -0
  11. package/dist/react/frame.d.ts +4 -3
  12. package/dist/server/index.d.ts +1 -1
  13. package/dist/server/index.js +4 -3
  14. package/dist/server/naming.js +4 -0
  15. package/dist/server/nested.d.ts +24 -2
  16. package/dist/server/nested.js +28 -2
  17. package/dist/server/server.js +145 -25
  18. package/dist/server/types.d.ts +5 -0
  19. package/dist/shell/annotate.d.ts +3 -2
  20. package/dist/shell/annotate.js +22 -2
  21. package/dist/shell/runtime.d.ts +6 -0
  22. package/dist/shell/runtime.js +11 -1
  23. package/docs/ADOPTING.md +36 -7
  24. package/docs/ARCHITECTURE.md +10 -5
  25. package/docs/DECISIONS.md +207 -1
  26. package/docs/DESIGN.md +12 -4
  27. package/docs/THREAT_MODEL.md +30 -3
  28. package/package.json +6 -5
  29. package/src/annotate/types.ts +4 -1
  30. package/src/annotate/validate.ts +11 -6
  31. package/src/compile/policy.ts +2 -2
  32. package/src/host/create-host.ts +5 -0
  33. package/src/host/types.ts +7 -0
  34. package/src/react/frame.tsx +4 -3
  35. package/src/server/index.ts +6 -2
  36. package/src/server/naming.ts +4 -0
  37. package/src/server/nested.ts +32 -2
  38. package/src/server/server.ts +168 -24
  39. package/src/server/types.ts +5 -0
  40. package/src/shell/annotate.ts +22 -2
  41. package/src/shell/runtime.ts +12 -1
package/docs/ADOPTING.md CHANGED
@@ -267,8 +267,19 @@ display.on("annotation", (report) => {
267
267
  if (report.type === "activated") bubble.openBeside(frame, report.rect, report.id);
268
268
  if (report.type === "anchored") bubble.follow(report.results);
269
269
  });
270
+ // The selection was used (a comment posted, a draft added): take it, and its highlight, away.
271
+ composer.onDone(() => display.annotations.clearSelection());
270
272
  ```
271
273
 
274
+ - **Clear the selection once you used it** (`annotations.clearSelection()`, P115): the page's text
275
+ selection, and the highlight the browser leaves on it (gray while focus is in your composer),
276
+ stay until something clears them; the person's next click in the page would, and this does it
277
+ when your composer is done with it. No `unselected` follows it (you know), and nothing else
278
+ changes: your marks and drafts, the mode (`start`) and a followed mark stay. With nothing
279
+ selected it does nothing; it is never sent to a frame that runs later (a reload has no selection
280
+ to clear). Like `start` and `show`, only where the config declares `annotate`. The shell is your
281
+ content server's: an older one ignores it.
282
+
272
283
  - **Ids say nothing, and a count only where the page may know it**: the content reads every
273
284
  `show`. Who wrote what stays in your view, outside the frame.
274
285
  - **Drafts only to their author's frame**: the page reads which marks are drafts (that its viewer
@@ -544,7 +555,10 @@ entry: {
544
555
  ### Nested pages: the page below Porthole's shell
545
556
 
546
557
  `nested: true` (P111) on an artifact kind served by the host kit puts the page in a frame of its
547
- own below Porthole's shell, on the same origin, with an opaque origin of its own. Do it where people
558
+ own below Porthole's shell, with an opaque origin of its own. The shell, the page and its files are
559
+ served on a label of the scope's own, `porthole-<24 base32>.<content domain>` (P114), not on the
560
+ scope's label: the scope's other displays run content there with `allow-same-origin`, which would
561
+ reach the shell (porthole#56). Do it where people
548
562
  type beside your displays: in full Chromium (a person's browser, not Playwright's headless shell) a
549
563
  served page's frame is out of process, and your page can't see a press in it, so without nesting a
550
564
  real click into the page's field is taken back and `comments.open` from a real click is refused
@@ -561,7 +575,15 @@ const displays = defineDisplays({
561
575
  ```
562
576
 
563
577
  Nothing else changes on your page: the same `createHost` (or `PortholeFrame`), the same handlers
564
- and events, the same `frame-src`. The display has one more event, `storage` (`{ used }`, once per
578
+ and events, the same `frame-src` (the content domain's wildcard covers the shell's label). Your
579
+ frames route answers the shell's origin (`issue`'s location); a clean address stays on the scope's
580
+ label and sends the browser on to the shell's with a one-time ticket.
581
+
582
+ **Route the shell's label.** `porthole-<…>.<content domain>` must reach the content server as
583
+ your other labels do. Wildcard DNS and a wildcard certificate (`*.<content domain>`) already cover
584
+ it; a route, an edge rule or a firewall that matches labels by a pattern of yours (`a-*`) must let
585
+ `porthole-*` through too. Every `porthole-` label is Porthole's: your naming may not make one
586
+ (`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
565
587
  run: whether the page touched `localStorage` or `sessionStorage`, never what it kept), for you to
566
588
  count the pages that would need storage. A nested page's workers come from Blob URLs (a worker from
567
589
  a script of its own set is refused: its origin is opaque), which may `importScripts` the set's
@@ -569,14 +591,21 @@ scripts; Chromium refuses a Blob module worker there. Not yet with a nested page
569
591
  and Porthole's libraries (`egress.libraries`); the config refuses them.
570
592
 
571
593
  What a content origin serves for a nested page (`/server` does all of it; a content Worker of your
572
- own answers the same, with the helpers `/server` exports: `nestedShellResponse`,
573
- `NESTED_FILE_HEADERS`, `nestedAncestors`). `<origin>` is the artifact's own,
574
- `https://<label>.<content domain>`; `<token>` is the access in the path (Porthole's sealed
575
- session, or a signed token of your own: the shell only needs addresses under the prefix).
594
+ own answers the same, with the helpers `/server` exports: `nestedLabelOf`, `nestedShellResponse`,
595
+ `NESTED_FILE_HEADERS`, `nestedAncestors`). `<origin>` is the shell's own,
596
+ `https://<nestedLabelOf(label)>.<content domain>`, where `label` is the scope's label (the one its
597
+ other displays are served on); `<token>` is the access in the path (Porthole's sealed session, or a
598
+ signed token of your own: the shell only needs addresses under the prefix). Your frame location
599
+ for a nested page is on `<origin>`.
600
+
601
+ **The rule** (P114): `<origin>` answers the four rows below and Porthole's status pages, nothing
602
+ else (no other display, no clean address, no asset, no app), and the scope's label never answers a
603
+ nested page's shell, page or files. That is what keeps the shell's realm (its word to your page,
604
+ the page's sealed address) out of every other display's reach.
576
605
 
577
606
  | Request | Answer |
578
607
  | --- | --- |
579
- | The framed address (a ticket's, a cookie's reload, an entered clean address), 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. |
608
+ | `<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. |
580
609
  | `<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: <the page's directives, its files' prefix opened>; sandbox allow-scripts; frame-ancestors <origin> <host origins>` (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`). |
581
610
  | `<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`: 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. |
582
611
  | `<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. |
@@ -202,13 +202,14 @@ holds the page and needs no stable origin, the shell writes it into an opaque
202
202
  frame instead.
203
203
 
204
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 the content origin. It
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
206
207
  frames the page in a child sandboxed without `allow-same-origin` (an opaque origin) at
207
- the page's sealed files' address, fetched without a cookie, and passes messages between
208
- the host and the page:
208
+ the page's sealed files' address on that origin, fetched without a cookie, and passes
209
+ messages between the host and the page:
209
210
 
210
211
  ```
211
- Host app Shell (content origin) Page (opaque child)
212
+ Host app Shell (its own origin) Page (opaque child)
212
213
  │ frame src = ticketed URL ──►│ frames the sealed address ───►│ runtime + page
213
214
  │◄── the page's messages ──────│◄── postMessage (by source) ───│
214
215
  │── the host's messages ──────►│── postMessage ───────────────►│
@@ -281,7 +282,11 @@ several displays on one page are in [THREAT_MODEL.md](THREAT_MODEL.md).
281
282
  bounds it and uses it as a UI hint, never as a permission (P053).
282
283
  A nested page (P111) is the one place they don't: the shell is a document of its
283
284
  own, the page's parent, on another origin than the page's (opaque), so the page
284
- reaches nothing of the shell's realm. The shell trusts the page's messages by
285
+ reaches nothing of the shell's realm. Nor does any other content: the shell's
286
+ origin is a label of its own that hosts nothing but nested pages' shells, their
287
+ opaque pages, those pages' files and status pages (P114), never the scope's
288
+ origin, where the scope's other displays run content with `allow-same-origin`
289
+ (porthole#56). The server holds that rule, not the host's layout. The shell trusts the page's messages by
285
290
  `event.source` alone and passes them on unchanged, never in its own namespace
286
291
  (`porthole/shell/`); what it says in that namespace is the shell's own word (its
287
292
  transient activation, which only a press or key in the page turns on, and whether
package/docs/DECISIONS.md CHANGED
@@ -4595,7 +4595,7 @@ second wall on a tab); a host needs a served page to open windows from a tab (th
4595
4595
  `'self'` default (it joins `FRAME_DENIED_FEATURES`); or WebKit and Firefox apply
4596
4596
  `Permissions-Policy` to these features (the shell's device locks become the second wall there too).
4597
4597
 
4598
- ## P104 · 2026-10-20 · Annotation markers: a number at an anchor, a click the host hears, marks that follow a scroll · Accepted; amended by P105, P107
4598
+ ## P104 · 2026-10-20 · Annotation markers: a number at an anchor, a click the host hears, marks that follow a scroll · Accepted; amended by P105, P107, P116
4599
4599
 
4600
4600
  A host that shows its comments beside an artifact page wants, at each comment's anchor in the page,
4601
4601
  a small marker (a bubble and how many comments are there) that scrolls with the content; a click on
@@ -6052,3 +6052,209 @@ takes it only while it asked for it. Each item below landed on its own, with its
6052
6052
  `comments` (the host's own UI; the composer is the person's, under the host's duties), and `user`
6053
6053
  (it only reads). Tested: `test/pass-on.test.ts`, each channel alone.
6054
6054
 
6055
+ ## P115 · 2026-10-28 · The host clears the page's selection: `annotations.clearSelection()` · Accepted
6056
+
6057
+ **Context.** In a comment mode (Raft's web app, Kirby) the person selects words, the host's
6058
+ composer opens beside them, and they post a comment or add a draft. The selection stays: the
6059
+ browser keeps drawing it (gray, since focus is in the host's composer) over words that now carry
6060
+ a mark, until the person clicks in the page. 0.13 and 0.14 give the host no way to clear it;
6061
+ Kirby asked for one (`selection.clear()`) to call once the selection is used.
6062
+
6063
+ **Decision.** `display.annotations.clearSelection()`, beside `start`, `stop`, `show`, `focus`,
6064
+ `track` and `clear` (a control of the display's annotations, named for what it clears: `clear`
6065
+ already means every mark). It sends `porthole/annotate.clearSelection` (no params) to the frame,
6066
+ only where the config declares `annotate` (else it throws, as the others do), and to no frame that
6067
+ runs later (nothing is kept: a new frame has no selection). The shell then:
6068
+
6069
+ - removes the page's selection with `Selection.prototype.removeAllRanges` as it was before content
6070
+ ran (taken with the DOM's other functions), on `Document.prototype.getSelection`'s answer, so a
6071
+ page that replaced either keeps nothing the host cleared;
6072
+ - forgets what it held of it: the report waiting for the selection to settle (250 ms), the one it
6073
+ last told and its box, and a scroll's follow-up of it. So nothing is told back: the
6074
+ `selectionchange` the clear makes finds nothing to report (no `unselected`: the host knows), and
6075
+ the same words selected again are a new selection, told as any is;
6076
+ - changes nothing else: marks (posted and drafts), the active and the followed mark, the mode,
6077
+ and an element picked. With nothing selected it is a no-op; it clears in any mode, text
6078
+ selection on or not (the host is trusted with the page's view, as it is with `focus`, which
6079
+ scrolls it).
6080
+
6081
+ There is no highlight of Porthole's own to remove: a settled selection is drawn by the browser
6082
+ (the shell draws marks, and an outline only while picking).
6083
+
6084
+ **Trust.** Host to frame only. The host takes no `clearSelection` from a frame (it is no report);
6085
+ the shell takes it only from its frame's parent and the host's origins, as every host message
6086
+ (a page that posts it to its own window is dropped). It gives the page nothing it hasn't: a page
6087
+ can clear or select its own text at any time, and can select the words again right after (the
6088
+ host hears that as a selection, while it asked for text). A report the shell posted just before
6089
+ the clear arrived (a selection that settled in the same moment) still reaches the host after its
6090
+ call; a host that cares drops a `selected` it gets right after clearing, as it would one it
6091
+ didn't ask for.
6092
+
6093
+ **Rejected.** A `selection` namespace (`display.selection.clear()`, as Kirby wrote it): the
6094
+ selection is the annotation runtime's (only `annotate` reports it), and one namespace for
6095
+ annotations is what hosts already hold. Clearing the selection inside `stop()` or `clear()`: a
6096
+ host stops the mode or redraws its marks for other reasons, with a selection the person still
6097
+ means to use. Telling the host `unselected` after a clear: it would arrive after the host's own
6098
+ call, as if the person did it, and a host that opens or closes UI on it would act twice.
6099
+ Clearing through the page's own `getSelection().removeAllRanges()`: a page (or a library it
6100
+ loads) that patched it would keep the highlight.
6101
+
6102
+ Tested: `test/annotate.test.ts` (sent as it is, after the handshake only, never replayed, throws
6103
+ without `annotate`; the shell uses the function it took); `leak/annotate.spec.ts` "clearSelection
6104
+ takes the page's selection away and tells nothing back; marks and drafts stay, the next selection
6105
+ is told (P115)", on a page that replaced `removeAllRanges`, with no selection, in text mode and with
6106
+ the mode stopped; `leak/served/nested.spec.ts` "the host's clearSelection reaches the nested page
6107
+ through its shell (P115)"; negative control `clear-selection` (the page's own `removeAllRanges`, and the
6108
+ told selection kept: each alone fails the probe, measured on Chromium).
6109
+
6110
+ **Revisit when** a host needs the element picked (`elements: true`) or a held block cleared too
6111
+ (they leave no highlight now), or the MCP Apps spec gains a host-to-view way to clear a selection.
6112
+
6113
+ ## P114 · 2026-10-28 · A nested page's shell on a label of its own, where nothing else is ever served · Accepted
6114
+
6115
+ **Context.** porthole#56 (Ferry's audit of what merged after 0.13.0). P111 rests on the shell
6116
+ being a realm content can't reach (ARCHITECTURE "Trust boundaries" 4): the host trusts the shell's
6117
+ word (`porthole/shell/state`: the keyboard rule, `comments.open`), and the shell holds the page's
6118
+ sealed files' address, a bearer credential (P083). The opaque page can't reach it. But the shell
6119
+ was served on its scope's content origin, where every other domain-mode display of the scope (an
6120
+ inline widget, a live widget, an MCP app, an artifact that isn't nested) runs agent-made content
6121
+ with `allow-same-origin`. Such a display on the host's page is same-origin with the shell: from a
6122
+ plain artifact or an inline widget of the same scope, `parent.frames[0].document` was the shell,
6123
+ its page's frame inside it (measured by Ferry on the headless shell, full Chromium and Firefox). So
6124
+ it could make the shell's word say "the person pressed" (P109's threat back for nested pages) and
6125
+ take the sealed address. P0 for a host that maps several artifacts to one scope. Nothing refused
6126
+ the mix: `nested` can't have `storage`, `assets` or `egress.libraries`, so a nested kind beside
6127
+ other kinds of one scope is the expected layout. The nested suite missed it because each of its
6128
+ cases had a scope of its own.
6129
+
6130
+ **Decision.** The shell's origin hosts nothing but nested pages' shells, their opaque pages, those
6131
+ pages' files and Porthole's status pages. `/server` holds the rule; it isn't left to how a host
6132
+ lays out `defineDisplays` or names its scopes.
6133
+
6134
+ - **The label.** A nested page is served on `nestedLabelOf(label)`: `porthole-` and 24 base32
6135
+ characters (120 bits) of the SHA-256 of `porthole/nested/<the scope's label>`. One per scope:
6136
+ every nested page of the scope shares it, as they shared the scope's origin before (only
6137
+ Porthole's shell runs there with that origin, and each page is opaque and opens only with its
6138
+ own sealed address). Not keyed and not secret: it says nothing the scope's label doesn't, and a
6139
+ content Worker of a host's own works it out from the label alone. It is one label under the
6140
+ content domain, so its wildcard DNS name, its wildcard certificate and the hosts'
6141
+ `frame-src https://*.<domain>` already cover it.
6142
+ - **What it answers.** The frame's address (`/__porthole/d/<key>`: the shell), the sealed
6143
+ prefix (`/__porthole/f/<token>/…`: the page, its files, the renewal, each with a CSP sandbox
6144
+ without `allow-same-origin`, P111), and Porthole's status pages and their script. Anything else
6145
+ is a 404 there: no clean address, entry, asset (`/_blob/`), library, session check or url-mode
6146
+ app. A ticket, cookie or sealed address is good there only for a nested page whose shell's label
6147
+ it is; and on the scope's label never for a nested page (its ticket, cookie or sealed address is
6148
+ refused there: a 401).
6149
+ - **No content label is ever one.** The keyed default has no hyphen; every `porthole-` label is
6150
+ Porthole's own: `content.name` giving one throws (as a reserved label does), and
6151
+ `prefixedName("porthole-")` throws. A shell's label the host reserved (`content.reserved`)
6152
+ makes `issue` throw: the request would go to the host's routes.
6153
+ - **Where the frame is.** `issue` answers the shell's origin for a nested page
6154
+ (`FrameLocation.origin`, and its `url`); the host page's checks take it as they take any served
6155
+ origin (it matches the content source, it isn't the host's site). `originFor(scope)` and
6156
+ `urlOf(scope, path)` stay the scope's: they are where its other displays and its clean addresses
6157
+ are.
6158
+ - **A clean address** (P068) stays on the scope's label: the entry, its code and its session are
6159
+ there, as before. Opened for a nested page, the scope's label answers it with a `303` to the
6160
+ shell's label (`/__porthole/d/<key>?ticket=<one-time>`): a ticket of its own for the same access
6161
+ (viewer, subject, anonymous), good for 60 s, buying what is left of the session, with the path
6162
+ below the file set's base the address asked for (`TicketRecord.page`, checked: a relative path,
6163
+ no dot segment, no query). The shell's label sets its own session there, so a reload rides on
6164
+ it; the scope's label never answers the shell.
6165
+ - **An entry code is no ticket.** A document's address takes a ticket from `issue` (or a hop)
6166
+ only, never an entry code (`TicketRecord.entry`), which opens its entry alone with its own
6167
+ browser's nonce. Before, a code could stand in for a ticket at the scope's label's
6168
+ `/__porthole/d/`; at the shell's it would have skipped the nonce (an attacker's session planted
6169
+ in a victim's frame).
6170
+ - `configFor` checks that a nested config's `contentOrigins` match a shell's sample origin too.
6171
+
6172
+ **Threat it closes.** A same-scope display reading or driving the shell: the shell's word to the
6173
+ host, its focus and activation, the page's sealed address. A content display is now never
6174
+ same-origin with any shell (its label is never a `porthole-` one), whatever the host's scopes.
6175
+
6176
+ **Limits.** On a tab, a nested page's clean address ends at the shell's document address (with its
6177
+ spent ticket), not the clean one; a reload rides the shell's session, and after it ends that
6178
+ address says "This link has been used" where the clean one would sign in again. The hop's ticket is
6179
+ in a `Location`, as exposed as `issue`'s frame address (P020): one use, a minute. A host that frames
6180
+ a clean address itself (not `issue`'s location) gets the shell's origin after the hop; with
6181
+ `createHost` the frame's origin is the location's, so such a host frames `issue`'s location.
6182
+
6183
+ **Rejected.**
6184
+ - A label in the form IDNA reserves (`??--`), which no host's naming can make today (P047): ACME
6185
+ CAs (Let's Encrypt) refuse certificates for such names, so a host with a certificate per name
6186
+ couldn't serve it. The `porthole-` prefix narrows what a host may name instead (the kit's health
6187
+ gate already reserved `porthole-health`).
6188
+ - A deeper name (`<x>.n.<domain>`): a second wildcard certificate and DNS name for every host.
6189
+ - A keyed label: a host's own content Worker couldn't work it out without the server's secret, and
6190
+ it would hide nothing the scope's label shows.
6191
+ - A label per page instead of per scope: nothing runs on the shell's origin but the shell, so
6192
+ per scope is enough, and its sessions stay per scope as before.
6193
+ - Refusing other kinds of a nested kind's scope (in `defineDisplays`, or at `issue`): the layout is
6194
+ the expected one, and scopes are the host's, not the registry's.
6195
+ - The shell on the scope's label on a tab only (a clean address): a same-scope page could open it
6196
+ in a window it names and reach its realm.
6197
+
6198
+ **Adopters.** Every host on `/server` or the host kit: the shell's label is under the content
6199
+ domain's wildcard, so wildcard DNS and a wildcard certificate need nothing; an edge, a route or a
6200
+ firewall that matches labels by pattern (`a-*.<domain>`) must let `porthole-*` through to the
6201
+ content server too. A host whose naming makes `porthole-` labels must change it. A content Worker
6202
+ of a host's own (Raft's, on 0.13 today) that adopts nested pages serves the shell, the page and
6203
+ its files on `nestedLabelOf(label)` (`nestedAncestors(<that origin>, <host origins>)`, the shell's
6204
+ `origin` that origin), answers the frame location with it, serves nothing else there, and never
6205
+ answers a nested page on the scope's label (ADOPTING "Nested pages").
6206
+
6207
+ **Tested.** `test/nested.test.ts` "a nested page's shell on a label of its own (P114)" (the
6208
+ label, one per scope, under host naming and the keyed default; the scope's label answers no
6209
+ nested page; the shell's answers nothing else, another display's ticket or sealed address
6210
+ included; naming and reserved labels); `test/entry.test.ts` "a nested page's clean address
6211
+ (P114)" (the hop, the page it was entered at, the shell's own session; an attacker's entry code
6212
+ at the shell's document address opens nothing); `leak/served/nested-siblings.spec.ts`
6213
+ `[nested-siblings]`: a nested page beside an inline widget and a plain artifact of its scope, which
6214
+ read each other (the positive control) and nothing of the shell (not its document, no sealed
6215
+ address, not its page's address); `leak/served/nested.spec.ts`'s first case beside a widget of its
6216
+ scope; `leak/kit.spec.ts` (through `nodeHost`) and the prod-shape profile (through Caddy's TLS and
6217
+ CoreDNS): framed by `issue`'s location, and from a clean address. Negative control `shell-label`:
6218
+ the harness answers the shell's frame address and sealed files on the scope's label (from the
6219
+ shell's, every mention of its origin made the scope's), and `[nested-siblings]` fails, nothing
6220
+ else. Measured on the headless shell, full Chromium, WebKit and Firefox (the last two in the
6221
+ prod-shape profile's browser image).
6222
+
6223
+ **Revisit when** a nested page gets storage, assets or libraries (they would be served on the
6224
+ shell's label: the rule must say what may run there), or a host needs a nested page's shell per
6225
+ page.
6226
+
6227
+ ## P116 · 2026-10-28 · A mark's count above the limit is clamped, not refused · Accepted
6228
+
6229
+ **Context.** P104 had `checkMarks` throw on a `count` above `ANNOTATION_LIMITS.count` (999), as on
6230
+ a bad anchor, so one mark refused the whole `show`. The count is a host's data that anyone can
6231
+ grow: in Ferry, one comment with 999 replies made `annotations.show` throw, the host got
6232
+ `onHostError({ kind: "annotations" })`, and treated it as fatal (porthole#40).
6233
+
6234
+ **Decision.** A whole number above the limit is clamped to it before the mark goes to the frame.
6235
+ The marker reads "99+" above 99 either way, so nothing a person sees changes, and the page is told
6236
+ no more than 999, as before. Anything that isn't a whole number from 0 (negative, a fraction,
6237
+ NaN, Infinity, not a number) still throws: that is a host's bug, not data that grew.
6238
+
6239
+ **Rejected (for now).** Dropping only a bad mark rather than refusing the list, and running
6240
+ `focus`/`start` after a refused `show` (porthole#40's other suggestions): they change what a host
6241
+ hears about its own bugs; left for their own decision.
6242
+
6243
+ Tested: `test/annotate.test.ts` (counts above the limit clamped, the rest refused as before).
6244
+
6245
+ ## P117 · 2026-10-28 · A draft holds back a tag start it was cut in · Accepted
6246
+
6247
+ **Context.** While content streams, the shell draws each partial (`tool-input-partial`) inert as
6248
+ it has come so far. Cut right after `<` or `</`, the HTML tokenizer emits them as text, so the
6249
+ draft shows a stray `<` until the next fragment (porthole#16: Ferry's screenshot, a lone `<` under
6250
+ eight drawn rows, cut just before `<script>`). Agents cut their arguments at arbitrary points.
6251
+
6252
+ **Decision.** Before parsing a draft, the shell leaves out a trailing tag start: from the last
6253
+ `<`, if what follows is empty, `/`, or a letter and no `>` (a tag's name or attributes, which the
6254
+ tokenizer drops anyway). A `<` that starts no tag (`1 < 2`), a comment, and a `<` with a `>` after
6255
+ it are drawn as they are. The whole content (`tool-input`) is never trimmed; nothing runs
6256
+ differently, since a draft runs nothing.
6257
+
6258
+ Tested: `test/shell.test.ts` (`<`, `</`, `</di`, inside an attribute, and whole content
6259
+ unchanged); `leak/react.spec.ts` "content streams through props…" (a draft cut after `</` and
6260
+ after `<` draws neither).
package/docs/DESIGN.md CHANGED
@@ -996,6 +996,7 @@ for that to lapse and click with raw input.
996
996
  | The keyboard: the focus guard (P109) | a move of the keyboard from one of the host page's text fields into a display's frame that the person didn't make (no press on the frame, `:active` on Chromium and WebKit, the pointer coming over it on Firefox; no Tab; no gesture the page's own events don't explain) is undone once the move is over; three while typing within 10 s, or five within 2 s, stop the display | `test/focus-guard.test.ts`; `leak/served/runtime.spec.ts`: "a page that takes the keyboard while the person types in the host's composer…", "a page that takes the keyboard back on its own blur keeps none of it…" (GK-1), "a composer the host focuses with focusField…", "the person's own moves into the frame keep the keyboard…" | `focus-guard` → the first (all three) and the next two (Firefox); `focus-guard-watch` (the watch after a take-back, the look at every frame) → those two (Firefox) |
997
997
  | The runtime: `comments.open` from the frame the person is in (P109) | its `user-activation` gate also needs the host page's focus in the calling frame (`CapabilitySpec.inFrame`, `Surface.focused`), after the focus guard | `leak/served/runtime.spec.ts`: "comments.open while the person types in the host's composer reaches no handler…" | `comments-in-frame` → that case (all three) |
998
998
  | A nested page: Porthole's shell above an opaque page (P111) | the framed address answers the shell alone (its own script by hash, framing and fetching only the sealed prefix); the page is its child, `sandbox="allow-scripts"` in the attribute and its CSP (never `allow-same-origin`: a static check over every sandbox Porthole writes), loaded without a cookie; the shell passes messages by `event.source`, never in its own namespace; the host takes a move into the frame, or a `comments.open`, for the person's only if the shell's activation turned on within the last second with no trusted press or key on the host's page since (or a Tab, the host's move, a press the engine shows) | `test/nested.test.ts`; `leak/served/nested.spec.ts` on full Chromium, the headless shell, WebKit and Firefox | `shell-namespace` → "the shell's words are the shell's alone…" (all three); `shell-host-input` → "a page's focus() just after the person pressed it and went back…" (all three) |
999
+ | A nested page's shell on a label of its own (P114, porthole#56) | the shell, its page and that page's files are served on `nestedLabelOf(<scope's label>)` (`porthole-<24 base32>`, one per scope), never on the scope's label, where the scope's other displays run content with `allow-same-origin`; that label answers only frame addresses of nested pages, their sealed prefix and status pages (no clean address, entry, asset, library, app, nor another instance's ticket, cookie or sealed address), the scope's label no nested page (a clean address goes on with a one-time ticket); no host's naming makes a `porthole-` label; an entry code is no document's ticket | `test/nested.test.ts`, `test/entry.test.ts` ("… (P114)"); `leak/served/nested-siblings.spec.ts` (`[nested-siblings]`: a same-scope inline widget and artifact read each other, not the shell) on full Chromium, the headless shell, WebKit and Firefox; `leak/kit.spec.ts` and the prod-shape profile (the label through `nodeHost`, and through a TLS edge and DNS) | `shell-label` (the shell on the scope's label) → `[nested-siblings]` (all three) |
999
1000
  | The asset library (P089, P091) | `/_blob/<id>` (or the frame's `<sealed base>__porthole/blob/<id>`) for an access to its artifact (a cookie, a sealed `Referer`, the sealed path), then the host's check, the store asked with it; typed by name, never a page, code only where trusted and uploaded code may run (asked at each load; by id alone, every artifact config must, P103), inert CSP, CORP, revalidated; the page's CSP opens `<origin>/_blob/` for images, media, fonts and data, for scripts and styles only where uploads are the admins' | `test/assets.test.ts` (a forged same-origin claim: 401; another artifact's session: 404; revoked: 403; bearer mode; a stricter config turns trusted code into a download, bearer mode too); `leak/served/runtime.spec.ts`: an upload loads in its frame; a set's page loads it; static `/_blob/` in a frame by `Referer` (Chromium, Firefox; WebKit sends only the origin: measured); "a script asset runs as code only if an admin uploaded it"; "scripts load from /_blob/ only where uploads are the admins'"; "an asset reaches only its own artifact's pages"; "an asset opened on its own runs nothing" | `blob-trusted` → the trusted-code case; `blob-script,blob-trusted` (two walls) → that case and the tab's CSP case; `blob-inert` → the opened-on-its-own case (all three; `scripts/controls.ts`) |
1000
1001
  | Workers (P044, P045) | no Node module in `/server`; D1 tickets taken by one `DELETE … RETURNING` | `test/workers.test.ts` (workerd, no `nodejs_compat`, real D1: once per ticket, a race, anonymous, a revocation, flat names, reserved namespaces) | — |
1001
1002
 
@@ -1035,9 +1036,10 @@ chooses), and the annotation runtime is in the shell only then.
1035
1036
  |-----------|---------|--------|
1036
1037
  | host → frame | `porthole/annotate.start` | `{ elements, text }`: picking elements (the one under the pointer or finger outlined with its name; a click or tap picks it, never reaching the content; Escape cancels; one pick), selecting text (each settled selection), or both (a click picks, a drag selects) |
1037
1038
  | host → frame | `porthole/annotate.stop` | — |
1038
- | host → frame | `porthole/annotate.show` | `{ marks: [{ id, anchor, count?, kind? }], active? }`: drawn over the content in the shell's own layer (a closed shadow root), found again whenever the content changes; a mark with a `count` (0 to 999) also gets a marker (P104); `kind: "draft"` (absent: posted) is drawn apart, with a marker and never a count (P107) |
1039
+ | host → frame | `porthole/annotate.show` | `{ marks: [{ id, anchor, count?, kind? }], active? }`: drawn over the content in the shell's own layer (a closed shadow root), found again whenever the content changes; a mark with a `count` (0 to 999; the host clamps a larger one, P116) also gets a marker (P104); `kind: "draft"` (absent: posted) is drawn apart, with a marker and never a count (P107) |
1039
1040
  | host → frame | `porthole/annotate.focus` | `{ id }`: scrolled into view inside the frame, made the active mark, flashed |
1040
1041
  | host → frame | `porthole/annotate.clear` | — |
1042
+ | host → frame | `porthole/annotate.clearSelection` | —: the page's text selection is taken away (the DOM's own `removeAllRanges`, taken before content runs) with what the shell held of it, and nothing is reported back; marks, drafts and the mode stay (P115) |
1041
1043
  | frame → host | `porthole/annotate.selected` | `{ anchor, rect }`; after a scroll, the same selection again only if its box moved more than 0.5 px, on the follow-ups' clock (P105) |
1042
1044
  | frame → host | `porthole/annotate.unselected` | — (the text selection went away) |
1043
1045
  | frame → host | `porthole/annotate.cancelled` | — (Escape) |
@@ -1117,8 +1119,9 @@ chooses), and the annotation runtime is in the shell only then.
1117
1119
  see or do anything. A view a report opens or moves guards its presses
1118
1120
  (THREAT_MODEL §6).
1119
1121
  - **Host API.** `display.annotations.start(mode?)`, `stop()`, `show(marks)`,
1120
- `focus(id)`, `clear()`, and the `annotation` event (`AnnotationReport`); the state
1121
- is given to every frame the display runs. `parseAnchor` checks an anchor a host
1122
+ `focus(id)`, `track(id)`, `clear()`, `clearSelection()` (P115), and the `annotation`
1123
+ event (`AnnotationReport`); the state is given to every frame the display runs (not a
1124
+ `clearSelection`: a new frame has no selection). `parseAnchor` checks an anchor a host
1122
1125
  stores (its server, before saving a comment).
1123
1126
 
1124
1127
  Tests (`leak/annotate.spec.ts`, all three engines): a pick outlines and picks
@@ -1159,7 +1162,10 @@ page reading a draft's kind and never its count (`draft-count`), a raw `show` pa
1159
1162
  an unknown kind (`draft-shell-checks`), and drafts alone followed after a scroll; and ADOPTING.md's `guardPresses`, as written
1160
1163
  there, taking no press within 500 ms of its view opening (a release on a menu item,
1161
1164
  a double click's second press on a button or a trigger, a press held past the
1162
- arming) and the person's own press or key after.
1165
+ arming) and the person's own press or key after. The host's `clearSelection` (P115) takes
1166
+ a selection away from a page that patched `Selection.prototype.removeAllRanges`, tells
1167
+ nothing back, leaves marks and drafts found, and the same words selected again are told
1168
+ (`clear-selection`).
1163
1169
 
1164
1170
  ## The shell runtime
1165
1171
 
@@ -1471,7 +1477,9 @@ control the tables above name to the registry):
1471
1477
  | `track-checks` | `annotate.spec.ts` | `a followed mark's box comes as it moves, for that mark only, at most 60 a second, clamped to the frame, until the host stops (P112)` | — | — |
1472
1478
  | `order-check` | `annotate.spec.ts` | `every found mark's place in the document comes with its box, offscreen ones too; a place that isn't one is no report (P112)` | — | — |
1473
1479
  | `hold-click` | `annotate.spec.ts` | `holding a block 500 ms selects it and its release's click never reaches the page; a tap, a moving finger and a mouse are the page's (P112)` | — | — |
1480
+ | `clear-selection` | `annotate.spec.ts` | `clearSelection takes the page's selection away and tells nothing back; marks and drafts stay, the next selection is told (P115)` | — | — |
1474
1481
  | `shell-namespace` | `served/nested.spec.ts` | `the shell's words are the shell's alone: a page that says them, to its parent or to the host's window, moves nothing` | — | — |
1482
+ | `shell-label` | `served/nested-siblings.spec.ts` | `[nested-siblings]` | — | — |
1475
1483
  | `file-sandbox` | `served/nested.spec.ts` | `a page's SVG or XML file opened on a tab of its own is an opaque origin, and its script touches nothing of the shell's (P111, after its review)` | — | — |
1476
1484
  | `shell-stall` | `served/nested.spec.ts` | `a shell's activation seen after a stall is no one's gesture until it goes off (P111, after its review)` | — | — |
1477
1485
  | `shell-host-input` | `served/nested.spec.ts` | `a page's focus() just after the person pressed it and went back to the host's composer is taken back` | — | — |
@@ -5,7 +5,7 @@ What Porthole protects, from whom, and where that protection ends. For each way
5
5
  guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
6
6
  [DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
7
7
 
8
- **Status.** This describes Porthole 0.14.0 (2026-10-28). A review on 2026-10-19 found gaps, and every decision it led to
8
+ **Status.** This describes Porthole 0.14.1 (2026-10-28). A review on 2026-10-19 found gaps, and every decision it led to
9
9
  has merged ([§8](#8-fixes-in-flight) lists them). P096 changed the negative-control runner and CI,
10
10
  and the shipped conformance probes' messages and timing, not what they check. P104 (0.9.0's
11
11
  annotation markers) had a review of its own, and P105, in 0.10.0, is what it led to. 0.11.0 was
@@ -19,7 +19,10 @@ on (§7). 0.13.0 also makes P106's lint fail soft and read only what it may (P11
19
19
  isolation). 0.14.0 adds a nested page (P111, `nested: true`, S3): the framed address is Porthole's
20
20
  shell alone and the page its opaque child, so a realm the page can't reach tells the host when the
21
21
  person, not the page, pressed in it (§7 "The keyboard", `comments`); and P112's annotation
22
- additions for a host's comment modes (hints, as every report is, §7).
22
+ additions for a host's comment modes (hints, as every report is, §7). 0.14.1: P114
23
+ (porthole#56) serves a nested page's shell on a label of its own, on which nothing but nested
24
+ pages' shells, their pages, those pages' files and status pages is ever served, so no other
25
+ display of the scope is same-origin with the shell (S3).
23
26
 
24
27
  ## 1. Two layers
25
28
 
@@ -336,6 +339,16 @@ encrypted into the path, since WebKit keeps no cookie in a frame (P083).
336
339
  403 that says `denied`.
337
340
  - A nested page (`nested: true`, P111): the framed address answers Porthole's shell alone, its
338
341
  script the only one its CSP runs, framing and fetching only the origin's sealed files' prefix.
342
+ **The shell's origin hosts nothing but the shell, its opaque page, the sealed files and status
343
+ pages** (P114, porthole#56): the shell, the page and its files are served on a label of the
344
+ scope's own, `porthole-<24 base32>` (`nestedLabelOf`), never on the scope's label, where its
345
+ other displays (inline and live widgets, MCP apps, artifacts that aren't nested) run agent-made
346
+ content with `allow-same-origin`. `/server` holds it: that label answers no clean address,
347
+ entry, asset, library, app or other display, and takes no other instance's ticket, cookie or
348
+ sealed address; the scope's label answers no nested page (its clean address goes on to the
349
+ shell's label with a one-time ticket); no host's naming makes a `porthole-` label. So no
350
+ content, of any scope, can read the shell's realm (its word to the host, the page's sealed
351
+ address) or drive it (`leak/served/nested-siblings.spec.ts`, negative control `shell-label`).
339
352
  The page is the shell's child, `sandbox="allow-scripts"` (never `allow-same-origin`, held by a
340
353
  static check over every sandbox Porthole writes) and the same sandbox in its own CSP, so it is an
341
354
  opaque origin in its frame and on a tab; it is loaded, and loads its files, at its sealed address
@@ -371,6 +384,10 @@ encrypted into the path, since WebKit keeps no cookie in a frame (P083).
371
384
  uncached (the default; `authorizeTtlSeconds` in the host kit) or call `content.forget(…)` when
372
385
  revoking, or a cached answer holds for up to that long.
373
386
  - Send the page's `frame-src`.
387
+ - With nested pages, route the shell's label (`porthole-<…>.<domain>`) to the content server as
388
+ every content label is (a wildcard needs nothing; a pattern of the host's own, `a-*`, must add
389
+ it). A content Worker of the host's own serves nested pages on that label alone, and nothing
390
+ else there (P114).
374
391
 
375
392
  **Not guaranteed**
376
393
 
@@ -671,6 +688,15 @@ own frame, below the shell, P111), so:
671
688
  `Element.prototype.matches` on them), so content can reach the closed shadow root that way,
672
689
  read the markers and rewrite them (the review of P104, on all three engines). Nothing in the
673
690
  layer is secret: it holds only what `show` sent, which the content can read anyway.
691
+ - *Clearing the selection* (P115). `annotations.clearSelection()` is the host's word to the frame
692
+ (`porthole/annotate.clearSelection`), with nothing back: the shell takes the page's selection
693
+ away through `Selection.prototype.removeAllRanges` as it was before content ran (control
694
+ `clear-selection`: a page that replaced it keeps its selection otherwise) and forgets the one it
695
+ told, so the clear makes no `unselected` or `selected`. It goes host to frame only: the host
696
+ takes no such message from a frame, and the shell takes it only from its frame's parent (a page
697
+ that posts it to its own window is dropped). It gives the page nothing new: a page can clear or
698
+ select its own text at any time, and can select the words again right after a clear (the host
699
+ hears that as any selection, while it asked for text).
674
700
  - *What content can always do.* Hide, shrink, move or cover the layer (its scripts can rewrite the
675
701
  layer's style, lay elements over it, or transform the page it sits in), change its words so a
676
702
  mark is orphaned, or flood the shared rate so real reports are refused. It can also make the
@@ -866,7 +892,8 @@ section.
866
892
  The decisions below come from the 2026-10-19 review, and all of them have merged. Each row says
867
893
  what was wrong, what holds now, and the limit its decision accepts, if any. Later reviews' decisions
868
894
  are in the status line and in DECISIONS.md: P105 (after the review of P104), P109 (after the review
869
- of 0.12.0's drafts), P111 (a nested page, S3; in 0.14.0).
895
+ of 0.12.0's drafts), P111 (a nested page, S3; in 0.14.0), P114 (a nested page's shell on a label of
896
+ its own, after porthole#56; in 0.14.1).
870
897
 
871
898
  | Decision | State | What it closes | Sections |
872
899
  | --- | --- | --- | --- |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.14.0",
3
+ "version": "0.14.1",
4
4
  "description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
5
5
  "homepage": "https://github.com/botiverse/porthole#readme",
6
6
  "bugs": {
@@ -22,6 +22,7 @@
22
22
  "docs",
23
23
  "examples",
24
24
  "README.md",
25
+ "CHANGELOG.md",
25
26
  "THIRD_PARTY_NOTICES.md"
26
27
  ],
27
28
  "type": "module",
@@ -65,10 +66,10 @@
65
66
  }
66
67
  },
67
68
  "devDependencies": {
68
- "@modelcontextprotocol/ext-apps": "2.0.3",
69
- "@modelcontextprotocol/server-basic-react": "2.0.3",
70
- "@modelcontextprotocol/server-basic-vanillajs": "2.0.3",
71
- "@modelcontextprotocol/server-threejs": "2.0.3",
69
+ "@modelcontextprotocol/ext-apps": "2.0.4",
70
+ "@modelcontextprotocol/server-basic-react": "2.0.4",
71
+ "@modelcontextprotocol/server-basic-vanillajs": "2.0.4",
72
+ "@modelcontextprotocol/server-threejs": "2.0.4",
72
73
  "@playwright/test": "1.63.0",
73
74
  "@types/node": "26.6.3",
74
75
  "@types/react": "19.3.0",
@@ -84,7 +84,8 @@ export interface AnnotationMark {
84
84
  readonly anchor: AnnotationAnchor;
85
85
  /**
86
86
  * A marker (P104): with a count, the shell also draws a small bubble with this number (0 to
87
- * `ANNOTATION_LIMITS.count`; above 99 it reads "99+", 0 draws the bubble alone) at the end of a
87
+ * `ANNOTATION_LIMITS.count`, a larger one clamped to it (P116); above 99 it reads "99+", 0 draws
88
+ * the bubble alone) at the end of a
88
89
  * text anchor and the top right of an element. The person can click it: the frame reports
89
90
  * `activated`. The content can read the number; give one only where the page may know it. A
90
91
  * draft's is dropped (P107): its marker has no number.
@@ -180,6 +181,8 @@ export const ANNOTATE_METHODS = {
180
181
  track: "porthole/annotate.track",
181
182
  /** Frame → host: the followed mark's box, as it moves (P112). */
182
183
  tracked: "porthole/annotate.tracked",
184
+ /** Host → frame: take the page's text selection away, telling nothing back (P115). */
185
+ clearSelection: "porthole/annotate.clearSelection",
183
186
  } as const;
184
187
 
185
188
  /** The most of each part of an anchor or report the host takes. */
@@ -227,7 +227,8 @@ export const hasMarker = (mark: AnnotationMark): boolean =>
227
227
  mark.count !== undefined || mark.kind === "draft";
228
228
 
229
229
  /**
230
- * The host's marks, checked before they go to the frame; throws on the first bad one. Each is
230
+ * The host's marks, checked before they go to the frame; throws on the first bad one (a count above
231
+ * `ANNOTATION_LIMITS.count` isn't bad: it is clamped to it, P116). Each is
231
232
  * rebuilt as the frame gets it: a posted mark as 0.10.0 sent it (no `kind`), a draft with
232
233
  * `kind: "draft"` and without its count (P107: a draft's marker shows no number, so the page isn't
233
234
  * told one).
@@ -244,10 +245,10 @@ export function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[] {
244
245
  `annotations.show: mark ${index} needs a unique id (1 to ${LIMITS.id} characters) and a valid anchor`,
245
246
  );
246
247
  }
247
- if (mark.count !== undefined && !count(mark.count, LIMITS.count)) {
248
- throw new TypeError(
249
- `annotations.show: mark ${index}'s count is a whole number from 0 to ${LIMITS.count}`,
250
- );
248
+ // A count above the limit is clamped to it (P116): the marker reads "99+" either way, and a
249
+ // count is data anyone can grow (a thread's replies), so it mustn't reject the whole list.
250
+ if (mark.count !== undefined && !count(mark.count, Infinity)) {
251
+ throw new TypeError(`annotations.show: mark ${index}'s count is a whole number, 0 or more`);
251
252
  }
252
253
  const kind: unknown = mark.kind;
253
254
  if (kind !== undefined && kind !== "posted" && kind !== "draft") {
@@ -257,6 +258,10 @@ export function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[] {
257
258
  if (kind === "draft") {
258
259
  return { id: mark.id, anchor, kind };
259
260
  }
260
- return { id: mark.id, anchor, ...(mark.count === undefined ? {} : { count: mark.count }) };
261
+ return {
262
+ id: mark.id,
263
+ anchor,
264
+ ...(mark.count === undefined ? {} : { count: Math.min(mark.count, LIMITS.count) }),
265
+ };
261
266
  });
262
267
  }
@@ -217,8 +217,8 @@ export function sandboxTokens(config: PortholeConfig): string[] {
217
217
  case "opaque":
218
218
  return ["allow-scripts"];
219
219
  case "domain":
220
- // Nested (P111), this frame holds Porthole's shell, on the content origin, and the page is
221
- // the shell's child (`PAGE_SANDBOX_TOKENS`).
220
+ // Nested (P111), this frame holds Porthole's shell, on a label of its own where no content
221
+ // runs with this origin (P114), and the page is the shell's child (`PAGE_SANDBOX_TOKENS`).
222
222
  return ["allow-scripts", "allow-same-origin"];
223
223
  case "external":
224
224
  // The host may add a documented few (popups, modals, downloads), never top navigation.
@@ -425,6 +425,11 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
425
425
  tracking = null;
426
426
  toFrame(ANNOTATE_METHODS.clear, {});
427
427
  },
428
+ clearSelection() {
429
+ // Host → frame only, and kept for no later frame (P115).
430
+ needsAnnotate("clearSelection");
431
+ toFrame(ANNOTATE_METHODS.clearSelection, {});
432
+ },
428
433
  };
429
434
 
430
435
  const hostContext = (): HostContext => {
package/src/host/types.ts CHANGED
@@ -245,6 +245,13 @@ export interface AnnotationControls {
245
245
  track(id: string | null): void;
246
246
  /** Removes every mark. */
247
247
  clear(): void;
248
+ /**
249
+ * Takes the page's text selection away (P115), its highlight with it: for when the host has
250
+ * used it (a comment posted, a draft added). No `unselected` follows; marks (posted and drafts),
251
+ * the mode and a followed mark stay as they are. Nothing selected: nothing happens. Not kept for
252
+ * a frame that runs later (it has no selection to clear).
253
+ */
254
+ clearSelection(): void;
248
255
  }
249
256
 
250
257
  export interface DisplayControls {
@@ -500,10 +500,11 @@ export interface PortholeFrameProps {
500
500
  readonly instance?: InstanceRef;
501
501
  /**
502
502
  * What the page declared (P086), as the host stored it with the artifact: the capabilities it
503
- * reaches through `porthole.use`, and its pinned runtime. By value: a change makes the display
504
- * again.
503
+ * reaches through `porthole.use`, and its pinned runtime. Under `config.runtime`, `null` says
504
+ * the page was published before 0.7 and has 0.6's surface (`MountOptions.declaration`). By
505
+ * value: a change makes the display again.
505
506
  */
506
- readonly declaration?: PageDeclaration;
507
+ readonly declaration?: PageDeclaration | null;
507
508
  /**
508
509
  * Who is viewing (P087), for an opaque frame or one whose issue gave none. By value: a change
509
510
  * makes the display again.