@botiverse/porthole 0.14.0 → 0.14.2

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 (46) hide show
  1. package/CHANGELOG.md +782 -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 +30 -4
  12. package/dist/react/frame.js +69 -5
  13. package/dist/react/index.d.ts +1 -1
  14. package/dist/react/view.js +10 -4
  15. package/dist/server/index.d.ts +1 -1
  16. package/dist/server/index.js +4 -3
  17. package/dist/server/naming.js +4 -0
  18. package/dist/server/nested.d.ts +24 -2
  19. package/dist/server/nested.js +28 -2
  20. package/dist/server/server.js +145 -25
  21. package/dist/server/types.d.ts +5 -0
  22. package/dist/shell/annotate.d.ts +3 -2
  23. package/dist/shell/annotate.js +22 -2
  24. package/dist/shell/runtime.d.ts +6 -0
  25. package/dist/shell/runtime.js +11 -1
  26. package/docs/ADOPTING.md +55 -7
  27. package/docs/ARCHITECTURE.md +10 -5
  28. package/docs/DECISIONS.md +248 -1
  29. package/docs/DESIGN.md +18 -7
  30. package/docs/THREAT_MODEL.md +30 -3
  31. package/package.json +6 -5
  32. package/src/annotate/types.ts +4 -1
  33. package/src/annotate/validate.ts +11 -6
  34. package/src/compile/policy.ts +2 -2
  35. package/src/host/create-host.ts +5 -0
  36. package/src/host/types.ts +7 -0
  37. package/src/react/frame.tsx +114 -6
  38. package/src/react/index.ts +1 -0
  39. package/src/react/view.tsx +20 -2
  40. package/src/server/index.ts +6 -2
  41. package/src/server/naming.ts +4 -0
  42. package/src/server/nested.ts +32 -2
  43. package/src/server/server.ts +168 -24
  44. package/src/server/types.ts +5 -0
  45. package/src/shell/annotate.ts +22 -2
  46. package/src/shell/runtime.ts +12 -1
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,250 @@ 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).
6261
+
6262
+ ## P118 · 2026-10-28 · React: `trackedAnnotation` and a handle with `clearSelection` · Accepted
6263
+
6264
+ **Context.** Raft's web app (Kirby) shows displays through `PortholeFrame` and `PortholeView`,
6265
+ which hold the display handle inside: it could not follow a mark (`annotations.track`, P112) or
6266
+ clear a used selection (`annotations.clearSelection()`, P115), both added to the core in 0.14.
6267
+
6268
+ **Decision.** Two additions to both components, the core's calls and nothing more:
6269
+
6270
+ - **`trackedAnnotation?: string | null`**, by value, as `annotations` and `focusedAnnotation`
6271
+ are: the binding calls `display.annotations.track(id)` when the prop changes and when a display
6272
+ is made with it set (a new generation, config or instance), after the marks are shown, so a
6273
+ mark and its following can arrive in one render. `null`, or leaving the prop out once it was
6274
+ set, calls `track(null)`. The core's semantics hold: an id no shown mark has, or a config
6275
+ without `annotate`, is the core's `TypeError`, told to `onHostError` (kind `"annotations"`) and
6276
+ never thrown during render; `annotations` without the followed mark stop the following, as the
6277
+ core's `show` does, and the binding follows it again when the marks have it back (the prop says
6278
+ to follow it; no second error is told while it is off). The `tracked` reports reach the existing
6279
+ `onAnnotation`, as every annotation report does (no new callback).
6280
+ - **A `ref`** holding a `PortholeFrameHandle`, exactly `{ clearSelection(): void }`, through
6281
+ React 19's `ref` prop and `useImperativeHandle` (the binding's peer is React 19.2+; no
6282
+ `forwardRef`). `clearSelection()` calls `display.annotations.clearSelection()` on the display
6283
+ running now; with none (waiting to near the screen, stopped for others, a view's fallback) it
6284
+ does nothing. As with the prop, a config without `annotate` is `onHostError`, not a throw. The
6285
+ handle is the same object for the component's life; a `PortholeView`'s is its own and reaches
6286
+ the frame it draws.
6287
+
6288
+ **Rejected.** Exposing the whole `DisplayHandle` through the ref: the binding owns the display's
6289
+ lifecycle (it is made and destroyed as frames near the screen, stop and run again), and a host
6290
+ holding it would call into a destroyed display or fight the props (`show`, `start`) the binding
6291
+ feeds it. `clearSelection` as a prop (a counter to bump): it is an event, not a state, and a ref
6292
+ says so. A `track` method on the handle: following is state the host keeps (which comment's card
6293
+ is open), so it is a prop, by value, like the marks.
6294
+
6295
+ Tested: `test/react-ssr.test.ts` (the prop's and the handle's types, exactly `clearSelection`;
6296
+ both render on the server, the ref unset there); `leak/react.spec.ts` "trackedAnnotation follows
6297
+ its mark through onAnnotation's `tracked`, and null stops it (P118)" (followed on mount, reports
6298
+ as the frame scrolls, none after `null`, again when set again, an unshown id told as a host error)
6299
+ and "a ref's clearSelection takes the frame's selection away; nothing without a display (P118)"
6300
+ (a text selection cleared, a frame not yet running and a config without `annotate`, the ref let
6301
+ go on unmount).
package/docs/DESIGN.md CHANGED
@@ -741,7 +741,8 @@ binding is mounting and lifecycle (P034).
741
741
  onContentError onHostError onResize onNavigated onNavigationBlocked onRefused onMuted
742
742
  onInitialized onOutcome
743
743
  fill? // fill the box and scroll inside, not grow with the content
744
- annotating? annotations? focusedAnnotation? onAnnotation? // where annotate is declared
744
+ annotating? annotations? focusedAnnotation? trackedAnnotation? onAnnotation? // where annotate is declared
745
+ ref? // a PortholeFrameHandle: clearSelection() (P118)
745
746
  aliases? themeKey? renderPlaceholder? eager? confirm? document? instance?
746
747
  className? style? />
747
748
  </PortholeProvider>
@@ -775,8 +776,10 @@ binding is mounting and lifecycle (P034).
775
776
  overwrites a remembered height (the first host's frame jumped there).
776
777
  - **Annotations** follow props: `annotating` (what the person may point at now, or
777
778
  null), `annotations` (the marks), `focusedAnnotation` (each new id is brought into
778
- view; `{ id, key }` with a new key focuses the same one again); `onAnnotation` gets
779
- what the frame reported. A frame that mounts again gets them all.
779
+ view; `{ id, key }` with a new key focuses the same one again), `trackedAnnotation`
780
+ (the mark followed, or null, P118); `onAnnotation` gets what the frame reported, `tracked`
781
+ boxes too. A frame that mounts again gets them all. A `ref` holds `clearSelection()` alone
782
+ (`PortholeFrameHandle`), a no-op while no display runs.
780
783
  - **Errors** (P055): `onContentError` gets what the content did wrong (what it
781
784
  threw, what the sandbox blocked, a navigation the shell stopped, that it kept
782
785
  navigating away): the agent's to hear. `onNavigationBlocked` gets a stopped
@@ -996,6 +999,7 @@ for that to lapse and click with raw input.
996
999
  | 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
1000
  | 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
1001
  | 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) |
1002
+ | 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
1003
  | 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
1004
  | 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
1005
 
@@ -1035,9 +1039,10 @@ chooses), and the annotation runtime is in the shell only then.
1035
1039
  |-----------|---------|--------|
1036
1040
  | 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
1041
  | 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) |
1042
+ | 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
1043
  | host → frame | `porthole/annotate.focus` | `{ id }`: scrolled into view inside the frame, made the active mark, flashed |
1040
1044
  | host → frame | `porthole/annotate.clear` | — |
1045
+ | 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
1046
  | 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
1047
  | frame → host | `porthole/annotate.unselected` | — (the text selection went away) |
1043
1048
  | frame → host | `porthole/annotate.cancelled` | — (Escape) |
@@ -1117,8 +1122,9 @@ chooses), and the annotation runtime is in the shell only then.
1117
1122
  see or do anything. A view a report opens or moves guards its presses
1118
1123
  (THREAT_MODEL §6).
1119
1124
  - **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
1125
+ `focus(id)`, `track(id)`, `clear()`, `clearSelection()` (P115), and the `annotation`
1126
+ event (`AnnotationReport`); the state is given to every frame the display runs (not a
1127
+ `clearSelection`: a new frame has no selection). `parseAnchor` checks an anchor a host
1122
1128
  stores (its server, before saving a comment).
1123
1129
 
1124
1130
  Tests (`leak/annotate.spec.ts`, all three engines): a pick outlines and picks
@@ -1159,7 +1165,10 @@ page reading a draft's kind and never its count (`draft-count`), a raw `show` pa
1159
1165
  an unknown kind (`draft-shell-checks`), and drafts alone followed after a scroll; and ADOPTING.md's `guardPresses`, as written
1160
1166
  there, taking no press within 500 ms of its view opening (a release on a menu item,
1161
1167
  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.
1168
+ arming) and the person's own press or key after. The host's `clearSelection` (P115) takes
1169
+ a selection away from a page that patched `Selection.prototype.removeAllRanges`, tells
1170
+ nothing back, leaves marks and drafts found, and the same words selected again are told
1171
+ (`clear-selection`).
1163
1172
 
1164
1173
  ## The shell runtime
1165
1174
 
@@ -1471,7 +1480,9 @@ control the tables above name to the registry):
1471
1480
  | `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
1481
  | `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
1482
  | `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)` | — | — |
1483
+ | `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
1484
  | `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` | — | — |
1485
+ | `shell-label` | `served/nested-siblings.spec.ts` | `[nested-siblings]` | — | — |
1475
1486
  | `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
1487
  | `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
1488
  | `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.2 (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.2",
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 {