@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.
- package/CHANGELOG.md +782 -0
- package/dist/annotate/types.d.ts +4 -1
- package/dist/annotate/types.js +2 -0
- package/dist/annotate/validate.d.ts +2 -1
- package/dist/annotate/validate.js +11 -4
- package/dist/check/page-source.js +1 -1
- package/dist/compile/policy.js +2 -2
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +5 -0
- package/dist/host/types.d.ts +7 -0
- package/dist/react/frame.d.ts +30 -4
- package/dist/react/frame.js +69 -5
- package/dist/react/index.d.ts +1 -1
- package/dist/react/view.js +10 -4
- package/dist/server/index.d.ts +1 -1
- package/dist/server/index.js +4 -3
- package/dist/server/naming.js +4 -0
- package/dist/server/nested.d.ts +24 -2
- package/dist/server/nested.js +28 -2
- package/dist/server/server.js +145 -25
- package/dist/server/types.d.ts +5 -0
- package/dist/shell/annotate.d.ts +3 -2
- package/dist/shell/annotate.js +22 -2
- package/dist/shell/runtime.d.ts +6 -0
- package/dist/shell/runtime.js +11 -1
- package/docs/ADOPTING.md +55 -7
- package/docs/ARCHITECTURE.md +10 -5
- package/docs/DECISIONS.md +248 -1
- package/docs/DESIGN.md +18 -7
- package/docs/THREAT_MODEL.md +30 -3
- package/package.json +6 -5
- package/src/annotate/types.ts +4 -1
- package/src/annotate/validate.ts +11 -6
- package/src/compile/policy.ts +2 -2
- package/src/host/create-host.ts +5 -0
- package/src/host/types.ts +7 -0
- package/src/react/frame.tsx +114 -6
- package/src/react/index.ts +1 -0
- package/src/react/view.tsx +20 -2
- package/src/server/index.ts +6 -2
- package/src/server/naming.ts +4 -0
- package/src/server/nested.ts +32 -2
- package/src/server/server.ts +168 -24
- package/src/server/types.ts +5 -0
- package/src/shell/annotate.ts +22 -2
- 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)
|
|
779
|
-
|
|
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()`,
|
|
1121
|
-
is given to every frame the display runs
|
|
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` | — | — |
|
package/docs/THREAT_MODEL.md
CHANGED
|
@@ -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.
|
|
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.
|
|
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.
|
|
69
|
-
"@modelcontextprotocol/server-basic-react": "2.0.
|
|
70
|
-
"@modelcontextprotocol/server-basic-vanillajs": "2.0.
|
|
71
|
-
"@modelcontextprotocol/server-threejs": "2.0.
|
|
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",
|
package/src/annotate/types.ts
CHANGED
|
@@ -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
|
|
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. */
|
package/src/annotate/validate.ts
CHANGED
|
@@ -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
|
|
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
|
-
|
|
248
|
-
|
|
249
|
-
|
|
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 {
|
|
261
|
+
return {
|
|
262
|
+
id: mark.id,
|
|
263
|
+
anchor,
|
|
264
|
+
...(mark.count === undefined ? {} : { count: Math.min(mark.count, LIMITS.count) }),
|
|
265
|
+
};
|
|
261
266
|
});
|
|
262
267
|
}
|
package/src/compile/policy.ts
CHANGED
|
@@ -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
|
|
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.
|
package/src/host/create-host.ts
CHANGED
|
@@ -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 {
|