@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/CHANGELOG.md ADDED
@@ -0,0 +1,782 @@
1
+ # Changelog
2
+
3
+ `@botiverse/porthole`. Each published release is a `v*` tag (0.11.0 was never published: see its
4
+ section); the reasons for every change are in [docs/DECISIONS.md](docs/DECISIONS.md), by the
5
+ P-numbers below.
6
+
7
+ ## 0.14.2
8
+
9
+ - **New (React, P118):** `PortholeFrame` and `PortholeView` take `trackedAnnotation` (a shown
10
+ mark's id, or `null`): by value, it follows that mark (`annotations.track`), its `tracked` boxes
11
+ reaching `onAnnotation`; `null` stops. And a `ref` (React 19's `ref` prop) holding a
12
+ `PortholeFrameHandle`, `{ clearSelection() }`: takes the frame's text selection away
13
+ (`annotations.clearSelection()`) where a display runs, nothing otherwise. Neither throws: an
14
+ unshown id, or a config without `annotate`, is `onHostError` (kind `"annotations"`). New export
15
+ from `/react`: `PortholeFrameHandle`.
16
+ - **Tests (P118):** `test/react-ssr.test.ts` (types, server render); `leak/react.spec.ts` (a mark
17
+ followed through the prop and stopped by `null`; the ref clearing a selection in the frame).
18
+
19
+ ## 0.14.1
20
+
21
+ - **Security (P114, porthole#56's P1):** a nested page's shell, its page and the page's files are
22
+ served on a label of their own, `porthole-<24 base32>.<content domain>` (`nestedLabelOf(label)`,
23
+ one per scope), on which nothing but nested pages' shells, their opaque pages, those pages' files
24
+ and status pages is ever served. In 0.14.0 the shell was on its scope's label, where the scope's
25
+ other displays (inline and live widgets, MCP apps, artifacts that aren't nested) run agent-made
26
+ content with `allow-same-origin`: such a display on the same page could read the shell's document,
27
+ drive its word to the host (the keyboard rule, `comments.open`) and take the page's sealed
28
+ address. `issue` answers the shell's origin for a nested page; the scope's label never answers a
29
+ nested page (a clean address sends the browser on to the shell's label with a one-time ticket).
30
+ An entry code is no longer taken as a document's ticket.
31
+ - **Adopters with nested pages:** route `porthole-*.<content domain>` to the content server as
32
+ your other labels (a wildcard DNS name and certificate already cover it; a route or edge rule of
33
+ your own that matches `a-*` must add it). Every `porthole-` label is Porthole's: a naming that
34
+ makes one throws, and `prefixedName("porthole-")` is refused. A content Worker of your own serves
35
+ nested pages on `nestedLabelOf(label)` alone (ADOPTING "Nested pages"). New exports from
36
+ `/server`: `nestedLabelOf`, `isNestedLabel`, `PORTHOLE_LABEL_PREFIX`; `TicketRecord.page`.
37
+ - **Tests (P114):** `leak/served/nested-siblings.spec.ts` (a same-scope inline widget and artifact
38
+ beside a nested page read nothing of its shell), negative control `shell-label`; the nested
39
+ suite's first case shares its scope with a widget; `test/nested.test.ts`, `test/entry.test.ts`;
40
+ the kit app and the prod-shape profile frame a nested page and open its clean address.
41
+ - **New:** `display.annotations.clearSelection()` (P115): takes the page's text selection away,
42
+ and the highlight the browser leaves on it, once the host has used it (a comment posted, a draft
43
+ added; asked for by Raft's comment mode). The shell clears it with the DOM's own
44
+ `removeAllRanges`, taken before content runs, and reports nothing back (no `unselected`); marks,
45
+ drafts, the mode and a followed mark stay. With nothing selected, nothing happens. Host to frame
46
+ only (`porthole/annotate.clearSelection`); an older shell ignores it.
47
+ - **Tests:** `leak/annotate.spec.ts` "clearSelection takes the page's selection away…", and through
48
+ a nested page's shell (`leak/served/nested.spec.ts`); negative control `clear-selection`.
49
+ - **Fixed:** `annotations.show` clamps a mark's `count` above `ANNOTATION_LIMITS.count` (999) to
50
+ it, where it threw and refused every mark (P116; porthole#40: a thread of 1,000 comments broke a
51
+ host's page). The marker reads "99+" either way. A count that isn't a whole number from 0 still
52
+ throws.
53
+ - **Fixed:** `PortholeFrame` and `PortholeView` take `declaration: null` (porthole#17), the
54
+ host's word under `config.runtime` for a page published before 0.7, as `MountOptions.declaration`
55
+ does. It already worked at run time; only the type refused it.
56
+ - **Fixed:** a streamed draft no longer shows a stray `<` when the content so far ends in `<` or
57
+ `</` (P117, porthole#16): the shell holds back a tag start it was cut in until more comes. The
58
+ whole content is drawn as it is.
59
+ - **Package:** the npm package ships `CHANGELOG.md` (copied from the repository's by `pnpm build`,
60
+ as `docs/` is), so the upgrade notes are in `node_modules` (porthole#32). 0.8.0's "Act on these
61
+ when upgrading" now says that `declareCapabilities`' declarations have no prototype either, and
62
+ what an ORM needs.
63
+
64
+ ## 0.14.0
65
+
66
+ **Withdrawn: do not use; stay on 0.13.0.** It was published by mistake on 2026-10-28, while
67
+ porthole#56's Firefox P0 (a nested page can read what the person types into the host's fields) and
68
+ its P1 were still open. The fixes ship as 0.14.1.
69
+
70
+ A nested page (P111): the address a served artifact's frame loads is Porthole's shell alone, and the
71
+ page runs in its child frame with an opaque origin, so the person's press in the page is seen in
72
+ full Chromium too, where a cross-site frame is out of process and the host's page sees nothing of
73
+ it. Fixes porthole#53. And what annotations add for a host's comment modes (P112): Escape while
74
+ selecting text, a mark followed as it moves, marks' places in the document, holding a block on
75
+ touch, and `mayPassOn`.
76
+
77
+ - **New:** `nested: true` on an artifact config with domain isolation (`presets.artifact`,
78
+ `defineDisplays` options). The host kit serves the shell at the framed address and the page at
79
+ its sealed files' address, `sandbox allow-scripts` in its frame and its CSP, fetched without a
80
+ cookie; its files carry `Cross-Origin-Resource-Policy: cross-origin` and
81
+ `Access-Control-Allow-Origin: *`. A content Worker of your own answers the same (ADOPTING.md
82
+ "Nested pages", with `nestedShellResponse`, `NESTED_FILE_HEADERS`, `nestedAncestors` from
83
+ `/server`). Not with `storage`, `assets` or `egress.libraries` (refused).
84
+ - **The keyboard and `comments.open` in a nested page:** the focus guard takes a move into the
85
+ frame for the person's if the page's shell saw its own activation turn on within the last second
86
+ and the host's page had no trusted press or key since (or a Tab, the host's own move, a press the
87
+ engine shows); `comments.open` opens on the same signal, so a click on the page's button a moment
88
+ after typing in the host's composer opens it (porthole#53). Limit: a press in the page within 5 s
89
+ of the last one turns no activation on (THREAT_MODEL §7 "The keyboard").
90
+ - **A stalled shell** (after the review, porthole#54): the shell looks and beats every 50 ms; an
91
+ activation it reports after a stall of over 100 ms is uncertain, no one's gesture, until it lapses.
92
+ - **Every file of a nested page sandboxed** (after the review): a script's answer too, so no file
93
+ opened on a tab of its own runs on the shell's origin.
94
+ - **Workers in a nested page** (measured, P111): from Blob URLs, which may `importScripts` the
95
+ set's scripts; a worker from the set's own script is refused (the page's origin is opaque), and
96
+ Chromium refuses a Blob module worker there. The sandbox on scripts' answers refuses none.
97
+ - **New event** `storage` (`{ used }`, once per run) for displays whose storage is the in-memory
98
+ stand-in (opaque, nested): whether the page touched `localStorage` or `sessionStorage`.
99
+ - **Annotations (P112):** Escape while selecting text reports `cancelled` too (the page keeps
100
+ the key); the host takes it only while it asked for a pick or for text.
101
+ `annotations.track(id | null)` follows one shown mark: `{ type: "tracked", id, rect }` as it
102
+ moves, at most 60 a second, clamped to the frame. Each attached `anchored` result carries
103
+ `order`, its place in the document among the found marks (offscreen ones too).
104
+ `start({ text: true, elements: "hold" })`: on touch, holding a block 500 ms selects it (its
105
+ release's click is the shell's); other taps stay the page's.
106
+ `mayPassOn(config, declaration)` / `host.mayPassOn(declaration)`: whether a page can pass a draft
107
+ on (any store others read, `openLink`, the agent, the host's data services, or egress beyond the
108
+ library CDNs), so a host can show it none.
109
+ - **Docs (P112):** THREAT_MODEL §6 and ADOPTING's keyboard section agree: a composer the person's
110
+ selection opens may take focus (`focusField`) only in a comment mode they started and only if it
111
+ can do nothing but save a draft.
112
+ - **Tests:** `leak/served/nested.spec.ts` runs on full Chromium (`chromium-oopif`, a new CI leg),
113
+ the headless shell, WebKit and Firefox; negative controls `shell-namespace`, `shell-host-input`.
114
+ `PORTHOLE_WEBKIT_PATH` runs the leak suite on a WebKit build of the machine's own.
115
+
116
+ ## 0.13.0
117
+
118
+ After the review of 0.12.0's drafts (P109): a display no longer keeps the keyboard it takes from
119
+ the host's composer, `comments.open` needs the person in the frame that calls it, a page's draft is
120
+ stricter text, and the composer it fills is the person's to act on. What a host must act on comes
121
+ first. 0.11.0 was never published, so its upgrade notes are repeated at the end for hosts coming
122
+ from 0.10.0.
123
+
124
+ - **Act on these when upgrading:**
125
+ - **The composer a page's draft fills** (THREAT_MODEL §7, ADOPTING.md `openPageDraft`): an open
126
+ never replaces, appends to or retargets what the person typed or the place they chose (answer
127
+ `false`, or show the page's words as a separate suggestion that takes no focus); it takes no
128
+ focus when it opens and sends on no Enter until the person has focused or edited it (Send is a
129
+ click until then); it says "Suggested by this page" (drawn by you, outside the frame) until they
130
+ edit it, and is never shown as one of their own drafts; render it as plain text, and show the
131
+ anchor's label and quote as isolated text (`<bdi>`, `dir="auto"`). The 0.12.0 one-liner,
132
+ `comments: ({ anchor, draft }) => composer.open(anchor, { draft })`, does none of this.
133
+ - **Nothing one click away that posts, submits, resolves, deletes or discards** in a view a
134
+ frame's report opens, a draft's view included (no "Post" or "Submit review" in it: THREAT_MODEL
135
+ §6, P107).
136
+ - **Moving focus into a display yourself:** `display.focus()` (new), not the frame's own
137
+ `focus()`, which from one of your text fields is taken for the page's and undone.
138
+ - **Opening your composer focused:** `focusField(textarea)` (new), not `textarea.focus()`: on
139
+ Firefox a page that has the person's gesture (the selection that opened the composer) and takes
140
+ focus back on its blur keeps a plain `focus()` from landing, and gets the keys.
141
+ - **A platform of your own** (not the web platform): implement `focused`, `onFocusTaken` and
142
+ `focus` on its surfaces, or a display can read what is typed beside it, and `comments` keeps
143
+ its old gate.
144
+ - **The keyboard given back** (P109): a display's page could move the keyboard into its frame
145
+ whenever it liked (on Chromium and WebKit with no gesture) and read what the person went on
146
+ typing in the host's composer. When focus leaves one of the host page's text fields for a
147
+ display's frame without the person's press on the frame or a Tab into it, `createHost` (every
148
+ `PortholeView`) gives it back once the move is over, and the display hears `focusTaken`
149
+ (`{ typing }`; React `onFocusTaken`); it keeps watching that focus stays back. Three within
150
+ 10 s that came while the person typed or that kept focus from staying back, or five within 2 s,
151
+ stop the display: a `contentError`, "The content kept taking the keyboard from the page; it was
152
+ stopped." Measured on Chromium, Firefox and WebKit: a page calling `focus()` every 700 ms down to
153
+ a busy loop, or taking focus back on its own blur, gets none or one key of a sentence before it
154
+ is stopped; a press on the page's own field, a Tab into it, and an assistive technology's
155
+ activation keep the keyboard there. Limits (THREAT_MODEL §7 "The keyboard"): on Firefox, which
156
+ shows the host's page no press in a frame, a page keeps the keyboard if the pointer came over its
157
+ frame after the person last typed and after the field got focus.
158
+ - **`comments.open` from the frame the person is in** (P109): its gesture gate also needs the host
159
+ page's focus in the calling frame, so a page no longer opens the composer, draft and all, while
160
+ the person types in the host's UI (the host page's activation lasts 5 s after any gesture on it;
161
+ 0.12.0's "a click to open" was that). Refused as `no-user-activation` (`not_allowed` to the page).
162
+ A press in the frame, or a Tab into it, opens it as before.
163
+ - **Stricter draft text** (P109): refused now, before the handler: a joiner (U+200C, U+200D)
164
+ anywhere but between two letters or marks (first, last, doubled, beside a space or punctuation,
165
+ or in an emoji sequence, 👩‍💻; Persian's می‌خواهم, Hindi's क्‍ष and Malayalam's എന്‍റെ, ❤️ and 1️⃣
166
+ still pass), U+2028 and U+2029, blank-looking text (spaces of any kind, U+2800), more than 32
167
+ blanks in a row, more than two blank lines in a row. The anchor's `label` and `quote` reach the
168
+ handler without what a person can't see, and are refused if nothing visible is left. The manual
169
+ and `comments.d.ts` say so.
170
+ - **Docs:** THREAT_MODEL §6, §7, §8 and its status line; P108's "a click to open" corrected;
171
+ capabilities' `user-activation` described as it is (any gesture on the host's page in the last
172
+ 5 s, `comments` also the person in the frame).
173
+ - New: `focusField`, `DisplayEvents.focusTaken`, `DisplayControls.focus()`, `onFocusTaken` (React),
174
+ `Surface.focused`, `Surface.onFocusTaken`, `Surface.focus` (optional, the platform seam).
175
+ - **From 0.10.0** (0.11.0's notes, never published on its own; all of it is in 0.12.0):
176
+ - **Drafts** (P107): send a person's drafts only to the frame that person views, and none to a
177
+ page with the runtime's `db` and `user` or with egress, or accept that its author and other
178
+ viewers can learn of them (THREAT_MODEL §7). Upgrade the content server's Porthole before
179
+ sending drafts: an older shell draws a draft as a posted mark without a marker. A `kind` other
180
+ than `"posted"` or `"draft"` throws from `annotations.show` (React: `onHostError`, kind
181
+ `"annotations"`). New: `AnnotationMarkKind`.
182
+ - **Lint** (P106): `LintRule` and `FileFinding["rule"]` take `"scroll-lock"` (a warning); a
183
+ switch over rules needs the case.
184
+
185
+ After the audit of P106's scroll-lock warning (P110): it no longer fails a show or a publish, and
186
+ it reads only the stylesheets it may.
187
+
188
+ - **A CSS escape past U+10FFFF no longer fails the check** (P110): one selector like `.\ffffff`
189
+ in a page or a linked stylesheet threw out of `lintContent`, `admitContent`, `lintFiles`,
190
+ `admitFiles` and `checkPage`. Such an escape (or 0, or a surrogate) is now U+FFFD, as CSS reads
191
+ it, and the rule fails soft: anything that throws in it is that page "not checked for scroll
192
+ lock" (a warning), never a failed check.
193
+ - **`lintFiles` decodes only the stylesheets the rule reads** (P110): a page linking many sheets
194
+ had every one decoded and kept for the whole call (400 sheets of 240 KB: 200 MB of heap, out of
195
+ memory at 64 MB), though the rule reads at most 32 sheets and 4 MiB a page. A sheet past the
196
+ caps is now refused before it is decoded, none is asked for once they are reached, and none is
197
+ kept: the same version runs under a 32 MB heap. The caps still count characters, whether the
198
+ host gives strings or bytes.
199
+ - **A fixed body is warned** (P110): `body { position: fixed; top: 0 }` with no bottom or height,
200
+ and `body { position: fixed; inset: 0; overflow: auto }` where html's overflow is visible, hold
201
+ the page on Chromium, Firefox and WebKit, and are now `scroll-lock` warnings.
202
+ - **`<html style="…">` is no longer warned** (P110): the shell drops html's `style` attribute, so
203
+ `<html style="overflow: hidden">` never held the page in Porthole's frame; the warning, and its
204
+ advice to edit the attribute, were wrong.
205
+
206
+ ## 0.12.0
207
+
208
+ A page's button can open the host's comment composer with a draft the person reviews and posts
209
+ themselves (P108). 0.12.0 also carries all of 0.11.0, which was never published: read 0.11.0's
210
+ notes below when coming from 0.10.0. (The review of 0.12.0 tightened all of this: see Unreleased,
211
+ P109.)
212
+
213
+ - **A comment's draft from the page** (P108): `comments.open(anchor, { draft })` opens the host's
214
+ composer starting with `draft` (at most 2,000 characters), which the person edits and posts, or
215
+ doesn't; the handler gets `{ anchor, draft }`. The page still never posts or reads a comment. A
216
+ draft is visible text only (P100's `unseen`): anything else is refused before the handler.
217
+ - **Hosts:** show the draft whole, as the person's editable plain text; post it only on their
218
+ Send; arm the composer as THREAT_MODEL §6 arms a view the content brought (no press, and no
219
+ Enter that sends, for 500 ms; Send not focused). `defineRuntimeConformance` now sends a draft.
220
+
221
+ ## 0.11.0 (not published)
222
+
223
+ Its release stopped at the CI gate (a timed-out Firefox shard) and was never tagged or published;
224
+ everything below shipped in 0.12.0.
225
+
226
+ The agent hears, before publishing, that its page's own styles hold it to one screen (P106), and
227
+ the manual says a page scrolls as a document. A host can mark a person's unposted comments,
228
+ drafts, apart from posted ones (P107).
229
+
230
+ - **A warning for a page held to one screen** (P106): `lintContent`, `admitContent`, `lintFiles`
231
+ and `admitFiles` warn (rule `scroll-lock`, never an error: a one-screen app means it) where the
232
+ page's own CSS stops it at its first screen in the frame: html or body with `overflow: hidden`
233
+ (or `clip`), or the body's one element of content (`#root`) one screen tall (100vh, dvh, svh,
234
+ 100% of a one-screen parent, fixed at the frame's edges) with `overflow: hidden` or
235
+ `position: fixed`, and no element in the page's markup below body scrolls itself (by
236
+ `style=""`, a Tailwind class, or a rule whose selector matches it: the page may scroll there;
237
+ the root counts only where it is one screen tall, or, in a one-screen body, under a flex or
238
+ grid body or in a height it can't read). A
239
+ page its script draws (an empty `#root`) has nothing to match: it is warned as one that "looks
240
+ held", which it may ignore if a box its script draws scrolls the content. It reads `<style>`,
241
+ the version's linked stylesheets and their `@import`s, `style=""` on those elements, and
242
+ Tailwind's utilities where the page loads Tailwind, by the cascade (specificity, order,
243
+ `!important`, layers), so a later override is seen; each sheet once, at most 32 and 4 MiB a
244
+ page (its own `<style>` included), 1,024 layers, and layer names of 256 characters. The warning names what holds the page and
245
+ the rule that undoes it, e.g. `add html, body, #root { height: auto; overflow: visible;
246
+ position: static } after those rules`; only values of a known shape and plain selectors are
247
+ echoed (and the root's id, else `body > div`, or `body > *` for a custom element), each at most
248
+ 60 characters with its `!important`. In `lintFiles` it reads the entry and at most 7 other
249
+ pages (path order), within one budget for them all (8 MiB of stylesheet, two million match
250
+ steps); past either, the pages left aren't checked, and one warning says how many. In `lintFiles` its `path` is the stylesheet's, where
251
+ the rule is there. Not read: rules under `@media` (but `all` and `screen`), `@supports`,
252
+ `@container`, `:is()`/`:where()`/`:not()` and sibling selectors, nested rules, `var()`, scripts.
253
+ - **The manual** (every kind): "It scrolls as a document: unless it's meant to fit one screen (a
254
+ game, a canvas), don't hold html, body or the element that holds it all to one screen …; a box that scrolls by itself takes the wheel while the
255
+ pointer is over it: keep those to parts of the page, never the whole of it."
256
+ - `LintRule` and `FileFinding["rule"]` take `"scroll-lock"`.
257
+ - **Drafts** (P107): `AnnotationMark.kind` is `"posted"` (the default, as absent) or `"draft"`. A
258
+ draft is drawn with a dashed underline (a dashed outline on an element) and a hollow marker with
259
+ no number, beside its words as a posted marker is; its click is `activated`, its place
260
+ `anchored`, and it is followed after a scroll, with or without a count. Posted marks are drawn,
261
+ sent and reported as before.
262
+ - **The page reads which marks are drafts**: send a person's drafts only to the frame that person
263
+ views (THREAT_MODEL §7). A draft's `count` is dropped before the frame.
264
+ - **Upgrade the content server's Porthole before sending drafts**: the shell is the content
265
+ server's. A shell before this one, given a draft by a newer host, draws it as a posted mark
266
+ without a marker (a solid underline, nothing to click), not apart.
267
+ - Any other `kind` is refused, as a bad anchor is: `annotations.show` throws; React's
268
+ `annotations` is refused (`onHostError`, kind `"annotations"`).
269
+ - New: `AnnotationMarkKind`.
270
+
271
+ ## 0.10.0
272
+
273
+ After the review of P104 (P105): a host guards the view a marker's click opens, `activated` needs
274
+ a gesture, follow-ups share one clock, and text markers sit beside their line instead of over the
275
+ next word. What a host must act on comes first.
276
+
277
+ - **Act on these when upgrading:**
278
+ - **Guard the view a report opens or moves** (P105, THREAT_MODEL §6): a comment's bubble opened
279
+ on `activated`, or a composer placed by `selected` or `anchored`, takes no press of any kind
280
+ for 500 ms after it appears or moves, ignores a press that began before that, opens beside the
281
+ frame where the layout allows, takes no focus, and has no destructive action one click away.
282
+ The content chooses when it appears and where, and can bring it under the person's own press
283
+ in the content. ADOPTING.md § Annotations has the code (`guardPresses`: the view `inert` while
284
+ it arms); its portaled menus and popovers go in a container inside it, or are guarded too.
285
+ - **`activated` is taken only within a gesture** (P105): while the host's page has transient
286
+ user activation, as a real click or tap on a marker gives it. A custom `PlatformHost` whose
287
+ `userActivation()` answers `false` (rather than `undefined`, can't tell) drops every marker
288
+ click, as it refuses every gesture-gated call. A gesture anywhere on the page in the last 5 s
289
+ lets a fake through: the guard above is the defence.
290
+ - **`selected` comes again after a scroll only when its box moved** more than 0.5 px, and on the
291
+ same clock as `anchored`'s follow-ups: at most one report a second together (P105). A host's
292
+ button placed by the selection's box can lag a scroll by up to a second; the person's own new
293
+ selections are told at once, as before.
294
+ - **`parseAnchor` takes out of a label everything the person can't see** (P105): every format
295
+ character (bidi controls, zero-width ones), default-ignorable code point, variation selector,
296
+ tag, private-use character and control. A label stored before may come back shorter;
297
+ selectors are kept as they are.
298
+ - **Text markers beside their line** (P105, #36): centred on the anchor's last line, in the line's
299
+ gutter past its block; at the frame's right edge where the frame is too narrow; past the line's
300
+ last word where something else is beside the block (a table's cell, a card). Never over another
301
+ word but where two or three anchors end on one full line of a narrow screen; the number alone
302
+ where the bubble with its glyph doesn't fit. The pointer on a marker lights its words. A tap on a
303
+ marker is reported on WebKit too (it was never, since 0.9.0).
304
+ - **What the shell guarantees, said against what** (P105): a marker's press is unheard and can't
305
+ be cancelled, and the layer out of reach, against content that patches none of the built-ins.
306
+ The shell now reads and stops a press through the platform's own functions, so patching
307
+ `Event`'s or `MouseEvent`'s prototypes no longer lets content hear or suppress it; reaching the
308
+ layer's nodes through other built-ins still works (nothing there is secret).
309
+ - **A custom platform's `viewport()` that answers no size or throws** clamps every box to nothing
310
+ at the frame's corner, and nothing throws out of the frame's listener (it raised a TypeError).
311
+ - Negative controls `marker-prevent`, `marker-originals`, `marker-tap`, `marker-place`,
312
+ `follow-throttle`, `follow-count`, `selection-follow` and `annotation-activated-gesture`, in
313
+ `scripts/controls.ts`.
314
+
315
+ ## 0.9.0
316
+
317
+ Annotation markers (P104): a host can show how many comments sit at each anchor, hear a click
318
+ on one, and follow the marks as the page scrolls. Every box a page reports is now held to the
319
+ frame, which changes what a host hears for a mark outside the viewport (below).
320
+
321
+ - **Annotation markers** (P104): `AnnotationMark.count` (0 to 999, `ANNOTATION_LIMITS.count`)
322
+ draws a small bubble with the number ("99+" above 99, the bubble alone for 0) at the end of a
323
+ text anchor and on an element's top right corner; that element's outline is then a thin line.
324
+ A click on a marker reaches none of the content's handlers and is reported as a new
325
+ `AnnotationReport`, `{ type: "activated", id, rect }` (`porthole/annotate.activated`), taken by
326
+ the host only for a mark it shows with a count. Open the host's own view of that mark with it,
327
+ never act on it: the content can fake it, can read every mark's count, and can tell that a
328
+ marker was pressed, and roughly where (it can't act on or cancel the click). Markers have no
329
+ tab stop; the host's own list of marks is the keyboard path.
330
+ - **Marks follow a scroll** (P104), while any mark has a count: once a scroll, a resize or a run of
331
+ content changes has settled (150 ms), `anchored` reports only the marks that moved since the
332
+ host was last told, at most once a second. A host that gives no counts hears exactly what 0.8
333
+ told it.
334
+ - **Reported boxes are clamped to the frame** (P104): every `rect` in `selected`, `activated`
335
+ and `anchored` reaches the host held to the frame's viewport as it is then; one wholly outside
336
+ becomes a box of no size on the nearest edge. A page can no longer make a host place its own UI
337
+ outside the frame. Act on this when upgrading: a mark scrolled out of the viewport is now told
338
+ on the edge it went past (below: `y` equals the viewport's height, `height` 0), not at its
339
+ place beyond it. A custom `PlatformHost` gives its surfaces `viewport()` (the new optional
340
+ `Surface.viewport`), or every box reaches the host as nothing at the frame's corner.
341
+ - **Wordless elements are named** (P104): a picked element with no text of its own (an image, an
342
+ icon button, a chart) is labelled by its `alt`, `aria-label` or `title`, in that order, instead
343
+ of its tag and classes alone.
344
+ - Negative controls `annotation-rect-clamp`, `annotation-activated`, `annotation-activated-count`,
345
+ `marker-trusted` and `marker-click`, in `scripts/controls.ts`.
346
+
347
+ ## 0.8.0
348
+
349
+ The fixes from the security review of 0.7.0 (2026-10-19): P092–P095, P098–P101 and P103, each
350
+ with its regression; a release that waits for its commit's CI (P097); and a threat model (P102).
351
+ Most of it refuses more than 0.7 did. What a host must act on when it upgrades comes first.
352
+
353
+ - **Act on these when upgrading:**
354
+ - `callTool` defaults to a confirmation and 30 a minute; it was a confirmation alone (P103). A
355
+ host whose `confirm` says yes by itself, for a view that polls a tool more often than every
356
+ 2 s, gives `callTool` its own `gates`.
357
+ - `setModelContext` defaults to 30 a minute and the new `show` gate (P100): the host shows the
358
+ person each update, whole, before it goes. Give `createHost` a `show` (`HostOptions.show`), or
359
+ the call is refused (`no-show`); the React provider shows updates with `ContextNotice` unless
360
+ `PortholeProvider.show` replaces it. A config that names its gates without `show` says so with
361
+ `withoutShow: true` (else it is warned of).
362
+ - Behind a proxy, set `rateLimit.trustedProxies` (how many proxies append to
363
+ `X-Forwarded-For`) or `rateLimit.key`. The issue endpoint's rate limit no longer reads
364
+ `X-Forwarded-For` by default: it keys an anonymous request by the socket's peer on Node and
365
+ `CF-Connecting-IP` on Workers, so without either setting every anonymous request through a
366
+ proxy shares that proxy's limit (P092).
367
+ - `callTool`'s arguments, `setModelContext`'s update and `downloadFile`'s contents are bounded
368
+ plain JSON or refused as malformed: an object reached twice, a `Date`, a `Map`, `NaN` or a
369
+ boxed value no longer passes (P095). A model-context update is text blocks and plain JSON, at
370
+ most 20,000 characters (`MAX_CONTEXT_CHARS`), with no invisible characters (P100).
371
+ - Under https Porthole's cookies are only its exact `__Host-porthole-` names: a `porthole-*`
372
+ cookie (which any sibling label can plant) is no longer read; loopback keeps its unprefixed
373
+ names (P101).
374
+ - A url-mode app answers its own origin only: a request with another `Origin`, or with
375
+ `Sec-Fetch-Site` `same-site` or `cross-site` that isn't a GET or HEAD navigation, is a 403, on
376
+ HTTP and on the socket path (`content.access`) alike (P101).
377
+ - Every served page carries its frame's sandbox in its CSP header and a `Permissions-Policy`
378
+ that denies what its frame's `allow` doesn't grant, on a tab as in a frame; on a tab the shell
379
+ opens no window (P099). An edge that rewrites headers keeps both.
380
+ - `presets.liveWidget` refuses a capability's `connect` or `resource` origins, and its config
381
+ is frozen (P103).
382
+ - New: `nodeListener(app, { scheme, onError })` (a fetch-style app as a Node listener) and
383
+ `onError` on `nodeHost`, `nodeServer` and `nodeListener` (P092); `tryIntersectDeclarations`,
384
+ which answers its problems instead of throwing (P093). The objects `intersectDeclarations`
385
+ returns have no prototype (P093).
386
+ - The declarations `declareCapabilities` and `intersectDeclarations` return hold objects with
387
+ no prototype (P093): an ORM or serializer that checks `constructor` (drizzle-orm does) refuses
388
+ them. Store a plain copy: `structuredClone` keeps every rule (a capability named `__proto__`
389
+ too). (Added after the release: porthole#32.)
390
+ - **The fixes:**
391
+ - **P092**: no request ends the Node process (a method fetch can't carry is a 405, anything
392
+ else it can't take a 400, a handler's failure a 500); the issue endpoint reads at most 64 KiB
393
+ of a body (`ISSUE_BODY_BYTES`); the rate limit's key is an address the client can't set.
394
+ - **P093**: `intersectDeclarations` reads each side as `dbAccess` does, wildcards included, so a
395
+ version keeps nothing the current declaration refuses; a collection named `__proto__` is a
396
+ rule.
397
+ - **P094**: a page's declared `data` names hold without a viewer; a result pushed with
398
+ `changed(result)` is a read, past `readData`'s gates; a `db` batch runs under its writes'
399
+ `methodGates` and a watch under its read's (`ConfirmRequest.askedBy` says which).
400
+ - **P095**: what content sends is read after its gate, into bounded text, and nothing it sends
401
+ throws out of an adapter; at most 10 confirmations wait per display.
402
+ - **P098**: a page of a file set whose notice arrives late is taken as the set's, not as a
403
+ navigation away (red on Chromium since 0.6.0); tests that waited a fixed time now wait for
404
+ what they check.
405
+ - **P099**: a served page on a tab of its own is sandboxed like its frame.
406
+ - **P100**: what content tells the model is shown to the person first, and what is shown is
407
+ what is sent; the manual calls it the content's unconfirmed text, never instructions.
408
+ - **P101**: siblings on the content domain: only `__Host-` names, an entered mark bound to its
409
+ label, and a url-mode app that answers its own origin.
410
+ - **P103**: a live widget takes no capability's origins; a trusted asset runs as code only while
411
+ the current config lets uploaded code run, in bearer mode too; `callTool` has a rate.
412
+ - **Release** (P097): a release is a commit of main whose CI passed, every job of it; the job
413
+ that publishes runs no project code; Actions are pinned to reviewed commits; third-party notices
414
+ for the vendored libraries and the leak suite's fixture.
415
+ - **Docs**: [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) (P102) says, use by use, what Porthole
416
+ guarantees, what the host must do, and what is out of scope; [SECURITY.md](SECURITY.md) says how
417
+ to report a vulnerability privately, which versions get fixes, and what happens next.
418
+
419
+ ## 0.7.0
420
+
421
+ The capability runtime (P085–P090): a page published as an artifact is an app, and reaches its host
422
+ through one global, `porthole.use(name)`, under a contract pinned per artifact. Porthole provides
423
+ the mechanism (declarations, levels, the wire, the gates, the asset library's serving); the app
424
+ provides the services behind the handlers. Additive for 0.6 hosts: a config without `runtime` is
425
+ 0.6's, frames, globals and manual alike.
426
+
427
+ - **The runtime** (P085): `config.runtime: "1"` (`presets.*({ runtime: "1" })`, inline widgets and
428
+ artifact pages). The shell defines `porthole`, frozen, with `use` only: `await
429
+ porthole.use("db")` is a frozen namespace or null (not offered, not declared, no host: the same
430
+ null), never a rejection. The roster comes in the handshake
431
+ (`hostCapabilities.experimental["porthole/runtime"]`); calls are `porthole/call { capability,
432
+ method, args }`, watches `porthole/event` / `porthole/unwatch`. Contract 1:
433
+ `clipboard`, `links`, `downloads`, `comments` (built in), `user`, `chat`, `data`, `context`,
434
+ `artifact`, `assets`, `db` (declared), each method served by one of the config's host functions
435
+ (`RUNTIME_CAPABILITIES`, the mapping in P085). New host functions: `user`, `comments`,
436
+ `artifact`, `assets`, `db`.
437
+ - **Types**: `types/runtime/v1/*.d.ts` (shipped; one per capability and the call contract), taught
438
+ by the manual's new `capabilities` topic with declaring, levels, errors and where state goes.
439
+ - **Declarations** (P086): `PageDeclaration` `{ capabilities, runtime }`; `declareCapabilities`
440
+ at publish (omitted carries forward with its pin, `{}` clears, an object replaces),
441
+ `declarationProblems`, `checkDeclaration`; `mount({ declaration })` (React: `declaration`). The
442
+ bridge refuses what a page didn't declare on every path, 0.6's requests included.
443
+ - **Levels** (P087): `view < interact < admin < owner`; each method's level (`CapabilityConfig.levels`
444
+ at or above its floor; a page may raise). `Grant.level` and `Grant.user` go in the issue's answer
445
+ (`FrameLocation.viewer`) through `httpLocator` to the bridge; `mount({ viewer })` (React:
446
+ `viewer`) otherwise. Refusals carry new codes: `forbidden`, `conflict`, `too_large`
447
+ (`REFUSAL_CODES`); handlers get `context.viewer` and `context.declared`.
448
+ - **State the host keeps** (P088, amending P023): `artifact.get()`/`publish({ base, files })`
449
+ (base-checked, admin), `db` (`get`, `query`, `onSnapshot`, `set`, `update`, `delete`, `batch`,
450
+ `ifVersion`, per-level `rules`, `data/users/<id>` private; `dbAccess` for the host's own API).
451
+ - **The asset library** (P089): `ServerOptions.assets` / `createContentHost({ assets })` serves
452
+ `/_blob/<id>` on the asset's own origin (its pages' loads, or a session with the host's check),
453
+ typed by name, never a page, inert, immutable; a page's CSP opens `<origin>/_blob/` for images,
454
+ media, fonts and data, and for scripts and styles only where uploads are the admins'.
455
+ - **Comments** (P090): `comments.open(anchor)` opens the host's composer at the page's anchor;
456
+ content hears only whether it opened.
457
+ - **Legacy**: 0.6's globals stay (`shell/legacy.ts`), untaught under a runtime, held to a declared
458
+ page's declaration.
459
+ - **Conformance**: `defineRuntimeConformance` (`/conformance`, no browser) runs an app's real
460
+ handlers through the bridge and past it; `leak/runtime/memory.ts` is the in-memory reference.
461
+ - **Leak suite**: `leak/served/runtime.spec.ts` on Chromium, WebKit and Firefox, with negative
462
+ controls `runtime-declaration`, `runtime-level`, `db-private`, `comments-result`, `blob-trusted`,
463
+ `blob-script,blob-trusted`, `blob-inert`, each required to fail exactly its probes
464
+ (`test:controls`, a CI job per engine).
465
+ - **From the security review of the first cut** (P091): assets need an access to their own artifact
466
+ and the host's check (`AssetStore.get(id, access)`, `StoredAsset.artifact`, `trusted`,
467
+ `bearer`; `assets.url(id)`; revalidated), db checks bounded and cheap ones first, gates per
468
+ method (`artifact.publish`, `assets.delete`: a click and a yes; `methodGates`), a batch at its
469
+ writes' levels and a watch at its read's, `data/users/me` in answers, no viewer refused above
470
+ view, own-property rules, watches ended on a new page, code-typed uploads refused where people
471
+ who interact upload, `MountOptions.declaration` required under a runtime (`null` for a page from
472
+ before 0.7), viewer ids one path segment, `intersectDeclarations`, `pseudonymFor`,
473
+ `defineRuntimeConformance({ api })`, `checkPage({ declaration })`, and a 0.6 config's own
474
+ `capabilities` topic kept.
475
+
476
+ ## 0.6.0
477
+
478
+ A served page may be many files (P081–P084): a build's output, a report with its images, a
479
+ dashboard that reads its data, published as it was made. Additive: a store that answers `{ html }`
480
+ is served as in 0.5, and so is everything else.
481
+
482
+ - **The store** (`ArtifactStore.get`, the kit's `source`) may answer a `StoredFiles`: `files`
483
+ (`path → { size, sha256, type? }`), `entry` (default `index.html`), `spa`, and `read(path)` (a
484
+ `Uint8Array` or a `ReadableStream`, whole). The published type is never served.
485
+ - **Paths and limits** (`@botiverse/porthole`, `/server`): `checkFileSet(files, { entry, limits })`
486
+ for a host to call when a version is published (canonical, case-sensitive, no `..`/`.`/empty
487
+ segments, no leading `/`, no `\ % ? #`, control or format characters, NFC, length caps, no case-fold
488
+ collisions, no file that is also a directory, the entry present), `filePathProblem`,
489
+ `fileLimits(config.limits)`; the config's `limits.maxFiles`, `maxFileBytes`, `maxVersionBytes`
490
+ (1,000, 25 MiB, 100 MiB by default). `requestFilePath`, `lookupFile`, `fileTypeOf`.
491
+ - **Serving** (P081): every file from the manifest only (decoded once; `dir/` its `index.html`,
492
+ `name` its `name.html`, the nearest `404.html`, the entry for a single-page app's navigations),
493
+ typed by Porthole's table (unknown: `application/octet-stream`, a download), `nosniff`, a CSP
494
+ header on every answer (anything but a page or a script: `default-src 'none'; sandbox`), files
495
+ `private, max-age=31536000, immutable` with their sha256 as ETag, pages revalidated with an
496
+ ETag, 304s, `Range` (206, 416), `Cross-Origin-Resource-Policy: same-origin`, service workers
497
+ refused. Every page of a set is in the shell.
498
+ - **Addresses.** On a tab, `entry.at` answers a `FileAddress` (`{ instance, base, file }`) and the
499
+ latest's address (`/`, `/style.css`) is redeemed to the version's own (`/v/3/`, `/v/3/style.css`),
500
+ so a page never loads a newer version's file published while it loads; `pinned: true` makes its
501
+ files immutable there (only then); `versionedAddress(path)` and `versionBase(n)` read the usual
502
+ convention. A subresource on a clean address with no session gets a 401 (no entry, no cookie). In a frame, the ticket's answer is the entry,
503
+ whose files are at `/__porthole/f/<sealed access>/` (AES-GCM, so WebKit, which keeps no cookie
504
+ in frames, loads them too: P083). The address opens on its own for an hour, renewed by the shell;
505
+ reports name it `./`.
506
+ - **The CSP** of a page with files opens its version's own path for scripts, styles, fonts, images,
507
+ media, fetches and workers, never `'self'` (P082, amending P022). Opaque frames and single pages
508
+ are unchanged.
509
+ - **A set's pages open each other in the frame** (P084): the shell lets a navigation to a page of
510
+ its set go on and tells the host first (`porthole/navigating`, `NAVIGATING_METHOD`); the display
511
+ goes on. Anything else is still stopped (P079).
512
+ - **The agent's side:** `lintFiles(config, files)` (each page linted, every relative reference
513
+ looked up in the set, a page's `/`-rooted reference an error), `admitFiles`, `checkPage({ files
514
+ })` (the whole set served, its entry run), and the manual's Files section where a kind serves
515
+ files. Tool schemas are unchanged.
516
+
517
+ ## 0.5.1
518
+
519
+ From Ferry's adoption of 0.5.0's live widgets (P080). Additive, except that a refused data call's
520
+ error message in the shell's globals is now a sentence for the person (its old text, `Refused
521
+ (denied)`, stays the JSON-RPC error's own message).
522
+
523
+ - **The host hears a navigation the shell stopped** (#12): `DisplayEvents.navigationBlocked`
524
+ (`{ url }`, the address whole; React `onNavigationBlocked`), and a `contentError` naming the
525
+ address without its query or fragment, so a host that passes content errors to the agent
526
+ (`errors: "agent"`) tells it its widget tried to leave its page. It is an error report: only
527
+ where the config declares `reportError`, within its reports and rate. The shell sends Porthole's
528
+ own `porthole/navigation-blocked` (`NAVIGATION_BLOCKED_METHOD`); both adapters carry it, MCP Apps
529
+ views included. Served frames only: an opaque frame's navigations get no events (the host hears
530
+ `navigated` when one replaces its document). `checkPage` reports it.
531
+ - **A host that refuses every data call needs no handlers** (#13): pass a `Refused` as `consent`
532
+ (`HostOptions.consent`, React's provider and frame `consent`), e.g.
533
+ `consent: new Refused("not_allowed", "Live data shows on the dashboard.")`: every
534
+ `consent`-gated call is refused with it, nothing is asked, and `readData`/`subscribeData` may be
535
+ declared without handlers. React compares it by value.
536
+ - **A refusal tells content why** (#14): a refused request's error carries
537
+ `data: { code, message }` (`RefusalReason`, `REFUSAL_CODES`): `consent_required`, `denied`,
538
+ `rate_limited`, `not_allowed` or `failed`, and a sentence to show. Hosts word their own with
539
+ `throw new Refused(code, message)` from a handler or a consent function (kept as the answer);
540
+ any other error a handler throws is `failed` in Porthole's words (its message stays the host's).
541
+ The shell's `readData` rejects, and `subscribeData`'s `onError` is called, with an `Error` whose
542
+ `code` is the code and whose `message` is the sentence. The manual teaches both. A consent
543
+ function that throws anything else is now `consent_required` to content (`denied` before).
544
+
545
+ ## 0.5.0
546
+
547
+ Live widgets (P079): content that shows its host's data, current, read as the person viewing it,
548
+ with no network of its own. Additive, but every shell now cancels its served frame's own
549
+ navigations to another document (below).
550
+
551
+ - **`presets.liveWidget(options)`**: an inline widget whose egress stays closed (its options have
552
+ no `egress`; passing one throws). It declares `readData` and `subscribeData`, each behind the
553
+ viewer's consent and a rate (120 and 60 a minute). Served (domain isolation), it loads
554
+ Porthole's own libraries from its origin. `defineDisplays` takes it as a preset.
555
+ - **Porthole's libraries (`egress.libraries`)**: Chart.js 4.5.1 and D3 7.9.0 (`VENDORED_LIBRARIES`),
556
+ npm's files byte for byte with their licenses, served by `/server` on every content origin at
557
+ `/__porthole/lib/<name>@<version>/<file>` (no ticket, immutable). The frame's `script-src` gets
558
+ that path on the content origins, nothing else. Domain isolation only; the manual gives a
559
+ `<script>` line for each.
560
+ - **The `consent` gate**: `HostOptions.consent` (React: `PortholeProvider`/`PortholeFrame`
561
+ `consent`) is asked once per display before its first consent-gated call; a no refuses them all
562
+ (`denied`), none refuses them (`no-consent`). Not a default gate of `readData` (hosts that declare
563
+ it keep working); the live widget preset has it.
564
+ - **`subscribeData`** (a new capability, needs `readData`): MCP's `resources/subscribe` and
565
+ `resources/unsubscribe`, and `notifications/resources/updated` from the host, after which the
566
+ content reads again. Offered as `hostCapabilities.serverResources.subscribe`. The handler gets
567
+ `changed(result?)` and an `AbortSignal` (`SubscriptionContext`). Both adapters (the shell's and
568
+ `/mcp`'s) carry it.
569
+ - **The host's cache** (`HostOptions.cached`, `DataCache`; React `cached`): a read of a subscribed
570
+ resource is answered from it at once, marked `_meta["porthole/stale"]` (`STALE_META`), and the
571
+ fresh read follows as an update.
572
+ - **Shell globals**: `readData(uri)` (a promise of the value: JSON parsed, else text) and
573
+ `subscribeData(uri, onData, onError)` (onData(value, { stale, uri }) now and at every change;
574
+ returns a stop function). The manual teaches them, the consent and the libraries.
575
+ - **No frame navigates itself away**: the shell cancels every navigation its frame starts to
576
+ another document (the Navigation API's `navigate` event), so a served frame can't carry data in a
577
+ URL to another content origin, which the page's `frame-src` must allow. Reloads and
578
+ same-document navigations go on. Opaque frames get no navigate events; their wall stays the
579
+ page's `frame-src`. Negative control `navigate-guard`.
580
+ - A shell config that declares `readData` (inline, artifact) now gives content a `readData`
581
+ global, fixed in place like the others: content that defines its own `readData` must rename it.
582
+ - `checkPage` answers consent-gated calls as a viewer who says no; `lintContent` points live
583
+ widgets at the libraries served here and at `readData`.
584
+
585
+ ## 0.4.1
586
+
587
+ - Annotation marks keep the words under them readable on a light page and a dark one: a lighter
588
+ fill (18%, 26% for the active mark) with an amber underline (text) or outline (an element), and
589
+ a ring around the active mark and a flash instead of more fill over its words (the 50% and 90%
590
+ yellow left light text yellow on dark yellow).
591
+
592
+ ## 0.4.0
593
+
594
+ - `LIBRARY_CDNS` adds three libraries' own CDNs, for scripts only: Tailwind's Play CDN
595
+ (`https://cdn.tailwindcss.com`), jQuery (`https://code.jquery.com`) and Plotly
596
+ (`https://cdn.plot.ly`) (P078, #11). **Hosts that pass `LIBRARY_CDNS` get them on upgrade**;
597
+ write the list out to keep the old one. The manual gives each a pinned line, and tells agents
598
+ how Plotly's maps draw here (`topojsonURL`, the copy on jsDelivr); `lintContent` asks for a
599
+ version in their URLs. Verified against the real CDNs under every preset, on three engines.
600
+ - `checkPage`: nobody clicks in a check, on any engine: a call on load that needs a click is
601
+ refused and reported as a problem (Firefox counted the check's own evaluations as gestures).
602
+
603
+ ## 0.3.5
604
+
605
+ - ADOPTING.md § "Choosing egress" (#7): the three levels (closed, `LIBRARY_CDNS`, passive kinds
606
+ from any https site) in one table, with the config for each, what it opens, the risk it
607
+ re-opens, who uses it, what the agent's manual says, and its decisions and tests; linked from
608
+ the README. The manual and the tool description word the any-https level the same way.
609
+
610
+ ## 0.3.4
611
+
612
+ - A confirmation names the instance the host gave the frame in opaque frames too, not only served
613
+ ones (`request.display.instance`): `PortholeView` passes it either way, and an opaque frame never
614
+ gets it (P077).
615
+
616
+ ## 0.3.3
617
+
618
+ - A confirmation names the instance a served frame shows (`request.display.instance`, in
619
+ `confirm` and `renderConfirm`), so a host can word its dialog from its own records (P076, #10).
620
+ - `ContentHost.start()` runs once; `nodeServer` starts a host made in its `listen` callback right
621
+ away instead of at the first request, and no longer starts again one the app started (P076,
622
+ #10).
623
+
624
+ ## 0.3.2
625
+
626
+ - Every entry point bundles whole (P075): `/check` imports its check page's script as a module,
627
+ and `/conformance` its harness, instead of loading files beside the module at run time, which a
628
+ bundle (a single executable built by rolldown, a Worker) doesn't have. `checkPage` needs no
629
+ `page` option anywhere now. Each release is bundled with rolldown and esbuild, checked for loads
630
+ left for run time, and runs a check from its bundle before it is published (`test:bundle`).
631
+
632
+ ## 0.3.1
633
+
634
+ From Ferry's and Raft Artifacts' adoptions of 0.3.0 and a second cold adoption (P074). Additive.
635
+
636
+ - `checkPage` runs a served config served: its own origin, the served CSP, shell, storage and
637
+ cookies, under an in-process server both drivers answer; errors name the content's own lines,
638
+ as the lint does. Configs that declare host functions can be checked (#8): each is answered as
639
+ a host that declines, and each call is reported (one hosts refuse is a problem, one a person
640
+ may decline a note). The manual's examples are checked under presets with every host function.
641
+ - React: flipping the provider's scheme, or a new themeKey, re-themes running frames in place;
642
+ it no longer makes every display again, losing widgets' state and reloading previews (#9).
643
+ - Sign-in comes back to `authorizeUrl` with the entry's state, never the request's own URL, so a
644
+ TLS edge or a dev proxy in front of the app no longer strands the person on the sign-in.
645
+ - `entryTarget(next, authorizeUrl, { app: true })` also takes the app's own pages.
646
+ `renderConfirm` gets `redirect()` ("redirected", not counted toward muting). `nodeServer` takes a
647
+ function for a host made after it listens. `entry.pathOf` may be async. A missing secret is
648
+ named. `portholeClient`'s functions pass bare (`this: void`). `PortholeView` renders its
649
+ placeholder or fallback on the server from the client's meta. `domain: null` is the documented
650
+ no-content-domain setup.
651
+ - Conformance: `@botiverse/porthole/conformance/reporter` prints why each case was skipped;
652
+ `contentSource` may be a function; `conformanceProjects` takes `use` and per-engine
653
+ `launchOptions` (a system Chromium).
654
+ - The examples run on `nodeServer` and `contentHostFor`, as ADOPTING recommends; ADOPTING says
655
+ when the other paths are right, how a page without a bundler loads Porthole's modules, and the
656
+ default authorize URL.
657
+
658
+ ## 0.3.0
659
+
660
+ Developer experience, for the people adopting Porthole and the agents writing for it.
661
+
662
+ - The host kit's client, bootstrap and relay (P072): `defineDisplays` (one registry of display
663
+ kinds for the server, the page, the CSP and the manual); `content.routes(viewerOf)` (one mount
664
+ under `/porthole`: frames, authorize, meta, handoff; `issue` answers the clean `link`);
665
+ `contentHostFor` (Workers) and `nodeServer` (Node); `portholeClient`, `frameFallback`,
666
+ `entryTarget`; React `PortholeView`, `usePortholeLink`, `cssVariableTheme`, `useRunAgain`, and
667
+ provider-wide `scheme`, `theme`, `nonce: "auto"`, `handlers`, `openLink`, `notify`,
668
+ `renderConfirm`; the viewer handoff for token-authenticated pages; `upstreamHeaders`,
669
+ `statusPage`, cookie-clean `appSocket` and `content.forget()` for url-mode relays;
670
+ `health.onServedChange`; logger adapters.
671
+ - The agent's side (P073): `lintContent`, `admitContent` (the show tool refuses only what certainly
672
+ fails, saying what to change), `checkPage` with `playwrightDriver` and `cdpDriver` (Cloudflare
673
+ Browser Rendering), `showTool`, `guideTool`, `checkTool`, `answerGuide`, `guideChanges`, and an
674
+ MCP server example. Every example in the manual passes the check under every preset.
675
+ - Additive: every 0.2 import works. Apps move their old frame and authorize routes to
676
+ `/porthole` themselves.
677
+
678
+ ## 0.2.4
679
+
680
+ - The package ships `docs/ADOPTING.md`, which 0.2.3's README links to and its build left out;
681
+ every doc in `docs/` is shipped from now on, and a test checks the README's links (P071).
682
+
683
+ ## 0.2.3
684
+
685
+ - Adopting from the package alone (P071): a README with a quickstart, `docs/ADOPTING.md`, and
686
+ runnable examples (`examples/`: one app on Node and Workers, and the conformance suite against
687
+ it). `npx porthole secret` and `npx porthole d1-schema`. `MountOptions.fill` and
688
+ `<PortholeFrame fill>` are deprecated in favor of `layout.kind: "fill"`. The runner asks less of
689
+ an app that serves only stored pages (`instances.shell`, `entry.denied`, `atSignIn`,
690
+ `completeSignIn` optional; `entry.unknown: "derive"`; `conformancePage`, `conformanceProjects`,
691
+ `onDemand`). `14.inline-assets` reports an inherited block as inapplicable. Host errors no
692
+ longer quote ticket URLs. DESIGN's snippet fixed; `'unsafe-eval'` documented.
693
+
694
+ ## 0.2.2
695
+
696
+ - From the host kit's first two adopters (P070, #5, #6): an address that names nothing (a label
697
+ the naming never makes, the bare domain, a path `entry.at` says has nothing) is a 404 on the
698
+ content domain, never a trip to the app's sign-in; `reserved` is only for labels the app
699
+ serves; the entry hooks get the address decoded (`EntryContext`) and `refusal` may return
700
+ nothing; `/server` exports `InstanceRef` and the other callback types; the server's pages talk
701
+ past a desktop scheme among the host origins (`ferry://app`), so framed url-mode apps no longer
702
+ hang; `nodeHost` streams with backpressure, stops with the client, and never ends a broken body
703
+ as whole; `health.onChange`; the runner takes async instances and entry addresses, adds
704
+ `served.entry.unknown`, and locates its tests in the app's spec file; the package ships the
705
+ docs.
706
+
707
+ ## 0.2.1
708
+
709
+ - The manual, for a whole-page viewer (P069): "Call <guide tool> once" with `guideToolName`;
710
+ `layout.kind: "fill"` says the page fills the app's viewer (not the window), keeping
711
+ phone-width-first; `theme.documents: "never"` drops every theme line but "always light". The
712
+ `14.sound` probe reports itself inapplicable where the page's own CSP blocks its media.
713
+
714
+ ## 0.2.0
715
+
716
+ - The host kit (P066): an app writes its policy (`instance`, `access`, `authorize`, `source`) and
717
+ its settings; Porthole does the rest. `createContentHost` (`/server`) gives the routing
718
+ middleware (reserved labels handed back), the issue endpoint (`{ instance }`, a proposal the
719
+ app maps; the client never chooses an origin), `meta`, `frameSources`, the content-domain
720
+ helpers (`contentDomain`, `ContentDomainError`: a clash throws at startup, or with the health
721
+ gate is a lasting "misconfigured", logged once) and the optional health gate with its opaque
722
+ fallback. New `/node` subpath: `nodeHost` (requests and WebSocket upgrades) and `nodeProbe`.
723
+ Client: `httpLocator`, `LocateError`, `servedOrOpaque`.
724
+ - Redirect entry (P068): `entry` gives every instance a clean address (`urlOf`) that opens
725
+ directly, through the app's authorize route (`authorize`) and its own sign-in, with a one-time
726
+ code bound to the address and the browser. Never the sign-in inside a frame (`FrameBlock`
727
+ `sign-in`); tickets stay the way frames load. `prefixedName` says a label's scope (`Naming`).
728
+ - The conformance runner: `defineHostConformance` / `hostConformance` run the leak suite, the
729
+ served cases and the redirect entry cases (`entryTests`) against an app's real page, with a
730
+ framework-free harness on `createHost` loaded under the page's nonce
731
+ (`dist/conformance/harness.js`). `served.url.ticket` uses a fresh browser.
732
+ - The prod-shape profile (`ops/prod-shape/run.sh`): Caddy's TLS, wildcard DNS, same-site
733
+ sibling origins, the kit reference app, a clash; CI on every push (checks, loopback on three
734
+ engines, prod shape).
735
+ - Compatible: every 0.1.x import works unchanged.
736
+
737
+ ## 0.1.8
738
+
739
+ - The manual's silent line says where a block is reported, following `errors`: back to the agent
740
+ (`agent`), to the app only (`host`), to the app (unset), or nowhere (no `reportError`), so it no
741
+ longer contradicts the Errors line (#4, P067). `14.silent` checks the host's side too.
742
+
743
+ ## 0.1.7
744
+
745
+ - The manual's "The sandbox:" list states every limit that silently changes behavior, derived
746
+ from the config (`manualLimits`), and each has a browser check (`LIMIT_CHECKS`, item-14 probes,
747
+ `served.domain.address`); a unit test fails on a line without one (P064). The forms advice is
748
+ now `type="button"` and a click handler: Chromium and Firefox fire no submit event in the
749
+ sandbox.
750
+ - A config can say a whole-page viewer's shape, and the manual and behavior follow (P065):
751
+ `layout.kind: "fill"` (every mount fills; fixed/sticky work), `theme.documents: "never"`
752
+ (always light, no theme changes), `storage.scope` (what one display's storage is kept for),
753
+ `errors: "agent" | "host" | "none"` (where content errors go); `limits.maxBytes` stated in KB
754
+ or MB. `LaunchSpec.heightPx` for checks that fill.
755
+
756
+ ## 0.1.6
757
+
758
+ - `served.domain.egress` holds a host to its own config's egress (P062).
759
+
760
+ ## 0.1.5
761
+
762
+ - Wildcards over public suffixes refused (P060); passive content from any https site by
763
+ `egress.anyHttps` (P059); inapplicable cases reported, not failed (P058); theme events only on
764
+ a change (P061).
765
+
766
+ ## 0.1.4
767
+
768
+ - Content and host errors apart (P055); nonce support (P054); `/server` routing (P056); fill
769
+ mode, by-value React props, settled annotations, shared-storage note (P057).
770
+
771
+ ## 0.1.3
772
+
773
+ - Content never writes the clipboard (P051); `copyText` (P052); annotations (P053).
774
+
775
+ ## 0.1.2
776
+
777
+ - `/server` on Workers with D1 tickets (P044, P045); anonymous grants (P046); host naming
778
+ (P047); artifact CDN opt-in (P048); url-mode delegation (P049); the host's check (P050).
779
+
780
+ ## 0.1.1 and 0.1.0
781
+
782
+ - Phase 1's milestones (M1–M5) and the first host's adoption fixes.