@botiverse/porthole 0.13.0 → 0.14.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/CHANGELOG.md +770 -0
  2. package/dist/annotate/types.d.ts +36 -4
  3. package/dist/annotate/types.js +6 -0
  4. package/dist/annotate/validate.d.ts +2 -1
  5. package/dist/annotate/validate.js +30 -6
  6. package/dist/check/page-source.js +1 -1
  7. package/dist/compile/policy.d.ts +7 -0
  8. package/dist/compile/policy.js +13 -1
  9. package/dist/config/schema.d.ts +11 -0
  10. package/dist/config/validate.js +19 -0
  11. package/dist/conformance/harness-source.js +1 -1
  12. package/dist/displays/displays.js +3 -1
  13. package/dist/guide/limits.js +1 -1
  14. package/dist/host/create-host.d.ts +2 -0
  15. package/dist/host/create-host.js +78 -3
  16. package/dist/host/pass-on.d.ts +15 -0
  17. package/dist/host/pass-on.js +65 -0
  18. package/dist/host/types.d.ts +29 -0
  19. package/dist/index.d.ts +4 -1
  20. package/dist/index.js +4 -1
  21. package/dist/isolation/types.d.ts +8 -0
  22. package/dist/isolation/types.js +8 -0
  23. package/dist/platform/focus-guard.d.ts +71 -2
  24. package/dist/platform/focus-guard.js +187 -12
  25. package/dist/platform/types.d.ts +8 -1
  26. package/dist/platform/web.js +60 -4
  27. package/dist/presets/presets.d.ts +2 -0
  28. package/dist/presets/presets.js +1 -0
  29. package/dist/react/frame.d.ts +4 -3
  30. package/dist/server/files.js +19 -3
  31. package/dist/server/index.d.ts +1 -0
  32. package/dist/server/index.js +5 -0
  33. package/dist/server/naming.js +4 -0
  34. package/dist/server/nested.d.ts +59 -0
  35. package/dist/server/nested.js +96 -0
  36. package/dist/server/server.js +193 -23
  37. package/dist/server/types.d.ts +5 -0
  38. package/dist/shell/annotate.d.ts +4 -3
  39. package/dist/shell/annotate.js +179 -9
  40. package/dist/shell/frame.d.ts +45 -0
  41. package/dist/shell/frame.js +250 -0
  42. package/dist/shell/plan.js +2 -1
  43. package/dist/shell/runtime.d.ts +6 -0
  44. package/dist/shell/runtime.js +60 -15
  45. package/docs/ADOPTING.md +85 -2
  46. package/docs/ARCHITECTURE.md +28 -0
  47. package/docs/DECISIONS.md +416 -1
  48. package/docs/DESIGN.md +21 -4
  49. package/docs/THREAT_MODEL.md +102 -5
  50. package/package.json +6 -5
  51. package/src/annotate/types.ts +32 -4
  52. package/src/annotate/validate.ts +34 -8
  53. package/src/compile/policy.ts +14 -1
  54. package/src/config/schema.ts +11 -0
  55. package/src/config/validate.ts +23 -0
  56. package/src/displays/displays.ts +3 -1
  57. package/src/guide/limits.ts +1 -1
  58. package/src/host/create-host.ts +81 -4
  59. package/src/host/pass-on.ts +73 -0
  60. package/src/host/types.ts +27 -0
  61. package/src/index.ts +4 -1
  62. package/src/isolation/types.ts +12 -0
  63. package/src/platform/focus-guard.ts +258 -15
  64. package/src/platform/types.ts +8 -1
  65. package/src/platform/web.ts +81 -9
  66. package/src/presets/presets.ts +3 -0
  67. package/src/react/frame.tsx +4 -3
  68. package/src/server/files.ts +19 -3
  69. package/src/server/index.ts +14 -0
  70. package/src/server/naming.ts +4 -0
  71. package/src/server/nested.ts +116 -0
  72. package/src/server/server.ts +224 -21
  73. package/src/server/types.ts +5 -0
  74. package/src/shell/annotate.ts +179 -9
  75. package/src/shell/frame.ts +268 -0
  76. package/src/shell/plan.ts +2 -1
  77. package/src/shell/runtime.ts +61 -15
@@ -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.13.0 (2026-10-27). A review on 2026-10-19 found gaps, and every decision it led to
8
+ **Status.** This describes Porthole 0.14.1 (2026-10-28). A review on 2026-10-19 found gaps, and every decision it led to
9
9
  has merged ([§8](#8-fixes-in-flight) lists them). P096 changed the negative-control runner and CI,
10
10
  and the shipped conformance probes' messages and timing, not what they check. P104 (0.9.0's
11
11
  annotation markers) had a review of its own, and P105, in 0.10.0, is what it led to. 0.11.0 was
@@ -16,7 +16,13 @@ around it). The review of 0.12.0's drafts led to P109, in 0.13.0: a display can
16
16
  `createHost` now gives back (§6, §7 "The keyboard"); `comments.open` needs the person in the
17
17
  calling frame; a page's draft text is stricter, and the composer it fills is the person's to act
18
18
  on (§7). 0.13.0 also makes P106's lint fail soft and read only what it may (P110, no change to
19
- isolation).
19
+ isolation). 0.14.0 adds a nested page (P111, `nested: true`, S3): the framed address is Porthole's
20
+ shell alone and the page its opaque child, so a realm the page can't reach tells the host when the
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). 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).
20
26
 
21
27
  ## 1. Two layers
22
28
 
@@ -162,6 +168,15 @@ Whatever the use:
162
168
  nothing one click away that posts, submits, resolves, deletes or discards (a draft's view, P107,
163
169
  included: no "Post" or "Submit review" in it). Its menus and popovers are part of it, portaled
164
170
  ones too (P105; ADOPTING.md § Annotations has the code: the view `inert` while it arms).
171
+ One exception to "takes no focus" (P112): in a comment mode the person started themselves (the
172
+ host's own control, never a report), a composer their selection opens (`selected`) may take
173
+ focus, with `focusField`, if all it can do is save a draft: nothing in it posts, submits or sends,
174
+ Enter in it only adds the draft to the batch (submitting is only ever the host's own "Submit N"
175
+ control, outside the composer), it shows plainly that it is a draft (so the person can see where
176
+ their keys are going), and the rest of this guard holds (no press for 500 ms, beside the frame). The page still chooses
177
+ when `selected` comes, so what it can do with that moment is put the person's next keys into a
178
+ draft they see and can discard, never send one; outside such a mode, or for a composer that can
179
+ send, it takes no focus.
165
180
  - Know that a display can take the keyboard: a page calls `focus()` on its own input whenever it
166
181
  likes (on Chromium and WebKit with no gesture), and what the person goes on typing goes to it.
167
182
  `createHost` (every `PortholeView` too) gives focus back when it leaves one of the page's text
@@ -322,6 +337,40 @@ encrypted into the path, since WebKit keeps no cookie in a frame (P083).
322
337
  worker; a page's CSP opens its own version's path, not its whole origin.
323
338
  - With a per-request check (`authorize`), the host decides again on every request; a deny is a
324
339
  403 that says `denied`.
340
+ - A nested page (`nested: true`, P111): the framed address answers Porthole's shell alone, its
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`).
352
+ The page is the shell's child, `sandbox="allow-scripts"` (never `allow-same-origin`, held by a
353
+ static check over every sandbox Porthole writes) and the same sandbox in its own CSP, so it is an
354
+ opaque origin in its frame and on a tab; it is loaded, and loads its files, at its sealed address
355
+ without a cookie, and its files then carry `Cross-Origin-Resource-Policy: cross-origin` and
356
+ `Access-Control-Allow-Origin: *` (an opaque page's own loads are cross-origin: the address is
357
+ the access, never the request's origin). So whoever holds a page's sealed address can read its
358
+ files from any origin, a page of their own included, until the address ends (an hour on its own,
359
+ P083): it is a bearer credential, as safe as it is unleaked. Porthole keeps it out of what it
360
+ says: no referrer goes with any load (`Referrer-Policy: no-referrer`, the shell's frame
361
+ `referrerpolicy="no-referrer"`), the host's reports name it as `./` (P083), and the shell's own
362
+ answer is `no-store`. The page itself can read it (its address) and so pass it on by any channel
363
+ it has, as it can pass on its files' bytes. The page has none of the origin's storage, and nothing
364
+ of the shell's realm: messages between them go by `postMessage`, the page's trusted by
365
+ `event.source`, and the shell drops what the page says in the shell's own namespace. Only the
366
+ shell (same-origin) renews the page's address; a module the page loaded keeps one that ends
367
+ within the hour. Every answer below the sealed prefix carries a CSP sandbox, never
368
+ `allow-same-origin` (a page's `allow-scripts`, every other file's runs nothing): a file opened on
369
+ a tab of its own (an SVG or XML file with a script) is opaque, never the shell's origin (negative
370
+ control `file-sandbox`). The sandbox refuses no worker (measured on the four engines): a nested
371
+ page's workers come from Blob URLs (a worker from its set's own script is refused by its opaque
372
+ origin, sandbox or not), and those load the set's scripts. Assets and Porthole's libraries aren't
373
+ served to a nested page yet.
325
374
 
326
375
  **The host must**
327
376
 
@@ -335,6 +384,10 @@ encrypted into the path, since WebKit keeps no cookie in a frame (P083).
335
384
  uncached (the default; `authorizeTtlSeconds` in the host kit) or call `content.forget(…)` when
336
385
  revoking, or a cached answer holds for up to that long.
337
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).
338
391
 
339
392
  **Not guaranteed**
340
393
 
@@ -556,7 +609,8 @@ wall on three engines, and `defineHostConformance` runs it against a host's own
556
609
  effects are its own), and group displays by page (S7).
557
610
 
558
611
  **Annotations** (`annotate`, P053, P104, P107). The shell that draws marks and reports anchors shares
559
- its realm with the content, so:
612
+ its realm with the content (a nested page's too: its marks are drawn by the runtime in the page's
613
+ own frame, below the shell, P111), so:
560
614
 
561
615
  - *What content learns.* Everything the host sends in a `show` is posted into the frame's window,
562
616
  where the content can listen: each mark's id, anchor and, where given, `count` (the number on
@@ -634,6 +688,15 @@ its realm with the content, so:
634
688
  `Element.prototype.matches` on them), so content can reach the closed shadow root that way,
635
689
  read the markers and rewrite them (the review of P104, on all three engines). Nothing in the
636
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).
637
700
  - *What content can always do.* Hide, shrink, move or cover the layer (its scripts can rewrite the
638
701
  layer's style, lay elements over it, or transform the page it sits in), change its words so a
639
702
  mark is orphaned, or flood the shared rate so real reports are refused. It can also make the
@@ -692,6 +755,35 @@ unposted words beside the frame and tell the page when.
692
755
  technology's activation within 5 s of their key or press on the page): focus goes back, and
693
756
  their next press once the pointer has left the frame and come back, a Tab, or an activation 5 s
694
757
  later keeps it.
758
+ - *Full Chromium* (P111, measured on Chromium 153, not the headless shell): a cross-site frame is
759
+ out of process, and the host's page sees nothing of a press in it (no `:active`, no `:hover`, no
760
+ pointer event past the frame's edge). For a served page that isn't nested, a person's real click
761
+ into its field is taken back every time there (the display stopped at the third), and
762
+ `comments.open` from a real click is refused within 5 s of any input on the host's page
763
+ (porthole#53). Nest it.
764
+ - *A nested page* (P111): the guard asks the page's shell, a realm the page can't reach above its
765
+ frame, whose transient activation turns on only from a press or key in the page (activation goes
766
+ up, never down). A move into the frame is the person's if the shell's activation turned on within
767
+ the last second and the host's page had no trusted press or key since; or a Tab, the host's own
768
+ move, or a press the engine shows on the frame element. Nothing else counts: no pointer over the
769
+ frame, no host-wide activation. A move the shell hasn't spoken of yet waits for its word (its next
770
+ frame) at most 500 ms, then is taken back. Measured on full Chromium, the headless shell, WebKit
771
+ and Firefox (`leak/served/nested.spec.ts`): a real click into the page's field keeps the
772
+ keyboard; the page's `focus()` as it loads, on a timer while the person types, right after a
773
+ click on the host's own button, 1.2 to 4.5 s after the person paused typing, and 700 ms after
774
+ they pressed it and went back to the composer is taken back; what a page says in the shell's
775
+ name, to its parent or to the host's window, moves nothing (negative controls `shell-namespace`,
776
+ `shell-host-input`). *What doesn't*: a press in the page within 5 s of the last one turns no
777
+ activation on, so a second move into it after the person went back to the host's page is taken
778
+ back until 5 s after their last press or key in the page, or they Tab in; the page gets the keys
779
+ typed while a move waits for the shell's word; a shell without `navigator.userActivation` leaves
780
+ 0.13's rule. A page that holds the thread it shares with its shell (WebKit; Firefox and Chromium
781
+ where the frames share a process) from its own click handler would push the moment the shell sees
782
+ its activation past the person's next keys on the host's page: so the shell looks and beats every
783
+ 50 ms and says how long it went without a look, and an activation it reports after a stall of over
784
+ 100 ms (its own, or no word heard) is no one's gesture until it lapses (P111, after its review;
785
+ negative control `shell-stall`). The cost: in those engines a page that keeps its thread busy has
786
+ the person's real click taken for uncertain until it is idle.
695
787
 
696
788
  ### The app runtime
697
789
 
@@ -727,7 +819,11 @@ section.
727
819
  - `comments` is write-only: the page learns only whether the composer opened. It opens only from
728
820
  a gesture with the host page's focus in the calling frame (P109: a press in it or a Tab into it;
729
821
  not the person typing in the host's UI, nor a gesture in another display; negative control
730
- `comments-in-frame`). A draft it gives (P108) is at most 2,000 characters of text a person can
822
+ `comments-in-frame`). In a nested page (P111) it opens too while the page's shell saw the
823
+ person's gesture within the last second, with no press or key on the host's page since: a real
824
+ click on the page's button a moment after typing in the host's composer opens it, on full
825
+ Chromium too (porthole#53); with no click it is refused, whatever the page says in the shell's
826
+ name. A draft it gives (P108) is at most 2,000 characters of text a person can
731
827
  see (P109): nothing invisible (zero-width characters, bidi and tag characters, controls but a
732
828
  new line and a tab; U+200C and U+200D only between two letters or marks, where Persian and the
733
829
  Indic scripts need them, never first, last, doubled, beside a space or punctuation, or in an
@@ -796,7 +892,8 @@ section.
796
892
  The decisions below come from the 2026-10-19 review, and all of them have merged. Each row says
797
893
  what was wrong, what holds now, and the limit its decision accepts, if any. Later reviews' decisions
798
894
  are in the status line and in DECISIONS.md: P105 (after the review of P104), P109 (after the review
799
- of 0.12.0's drafts).
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).
800
897
 
801
898
  | Decision | State | What it closes | Sections |
802
899
  | --- | --- | --- | --- |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.13.0",
3
+ "version": "0.14.1",
4
4
  "description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
5
5
  "homepage": "https://github.com/botiverse/porthole#readme",
6
6
  "bugs": {
@@ -22,6 +22,7 @@
22
22
  "docs",
23
23
  "examples",
24
24
  "README.md",
25
+ "CHANGELOG.md",
25
26
  "THIRD_PARTY_NOTICES.md"
26
27
  ],
27
28
  "type": "module",
@@ -65,10 +66,10 @@
65
66
  }
66
67
  },
67
68
  "devDependencies": {
68
- "@modelcontextprotocol/ext-apps": "2.0.3",
69
- "@modelcontextprotocol/server-basic-react": "2.0.3",
70
- "@modelcontextprotocol/server-basic-vanillajs": "2.0.3",
71
- "@modelcontextprotocol/server-threejs": "2.0.3",
69
+ "@modelcontextprotocol/ext-apps": "2.0.4",
70
+ "@modelcontextprotocol/server-basic-react": "2.0.4",
71
+ "@modelcontextprotocol/server-basic-vanillajs": "2.0.4",
72
+ "@modelcontextprotocol/server-threejs": "2.0.4",
72
73
  "@playwright/test": "1.63.0",
73
74
  "@types/node": "26.6.3",
74
75
  "@types/react": "19.3.0",
@@ -63,8 +63,13 @@ export interface AnnotationRect {
63
63
 
64
64
  /** What the person may point at while the host is asking. */
65
65
  export interface AnnotateMode {
66
- /** Elements, picked with a click or tap (the one under the pointer is outlined); one pick. */
67
- readonly elements?: boolean;
66
+ /**
67
+ * Elements, picked with a click or tap (the one under the pointer is outlined); one pick. Or
68
+ * `"hold"` (P112): a finger held still on a block for 500 ms selects it (reported as `selected`,
69
+ * and the click its release makes never reaches the page); every other tap, and any mouse, is the
70
+ * page's; it lasts until the host stops it.
71
+ */
72
+ readonly elements?: boolean | "hold";
68
73
  /** Text, by selecting it: each settled selection is reported, and its clearing. */
69
74
  readonly text?: boolean;
70
75
  }
@@ -79,7 +84,8 @@ export interface AnnotationMark {
79
84
  readonly anchor: AnnotationAnchor;
80
85
  /**
81
86
  * A marker (P104): with a count, the shell also draws a small bubble with this number (0 to
82
- * `ANNOTATION_LIMITS.count`; above 99 it reads "99+", 0 draws the bubble alone) at the end of a
87
+ * `ANNOTATION_LIMITS.count`, a larger one clamped to it (P116); above 99 it reads "99+", 0 draws
88
+ * the bubble alone) at the end of a
83
89
  * text anchor and the top right of an element. The person can click it: the frame reports
84
90
  * `activated`. The content can read the number; give one only where the page may know it. A
85
91
  * draft's is dropped (P107): its marker has no number.
@@ -106,6 +112,12 @@ export interface AnchorResult {
106
112
  readonly state: AnchorState;
107
113
  /** Where it is now, when attached. */
108
114
  readonly rect?: AnnotationRect;
115
+ /**
116
+ * Its place in the document among the found marks, from 0 (P112): where it starts, offscreen
117
+ * marks included, for a host that lists marks in reading order. The content's word: an order to
118
+ * sort by, never a fact.
119
+ */
120
+ readonly order?: number;
109
121
  }
110
122
 
111
123
  /** What the frame reports, once the host has checked it. */
@@ -118,7 +130,11 @@ export type AnnotationReport =
118
130
  }
119
131
  /** The text selection went away. */
120
132
  | { readonly type: "unselected" }
121
- /** The person pressed Escape while picking an element. */
133
+ /**
134
+ * The person pressed Escape while picking an element (the pick ends), or while selecting text
135
+ * (P112: the page keeps the key; the host decides what ends). The page's word too: a page can
136
+ * send it, and the host takes it only while it asked for a pick or for text.
137
+ */
122
138
  | { readonly type: "cancelled" }
123
139
  /**
124
140
  * Where the marked anchors are now: every mark after `show`, the focused one after `focus`,
@@ -128,6 +144,12 @@ export type AnnotationReport =
128
144
  * host was last told, at most once a second (P104).
129
145
  */
130
146
  | { readonly type: "anchored"; readonly results: readonly AnchorResult[] }
147
+ /**
148
+ * The box of the mark the host follows (`annotations.track`, P112), in the frame's viewport, at
149
+ * an animation frame where it moved: at most 60 a second, for that mark only, clamped to the
150
+ * frame. The content's word: where to put a card beside it, nothing more.
151
+ */
152
+ | { readonly type: "tracked"; readonly id: string; readonly rect: AnnotationRect }
131
153
  /**
132
154
  * The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
133
155
  * (P107); `rect` is the marker's box, to open the host's own UI beside it. The content can fake
@@ -155,6 +177,12 @@ export const ANNOTATE_METHODS = {
155
177
  anchored: "porthole/annotate.anchored",
156
178
  /** Frame → host: a mark's marker was clicked (P104). */
157
179
  activated: "porthole/annotate.activated",
180
+ /** Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112). */
181
+ track: "porthole/annotate.track",
182
+ /** Frame → host: the followed mark's box, as it moves (P112). */
183
+ tracked: "porthole/annotate.tracked",
184
+ /** Host → frame: take the page's text selection away, telling nothing back (P115). */
185
+ clearSelection: "porthole/annotate.clearSelection",
158
186
  } as const;
159
187
 
160
188
  /** The most of each part of an anchor or report the host takes. */
@@ -155,7 +155,20 @@ function results(value: unknown): AnchorResult[] | null {
155
155
  if (rect === null) {
156
156
  return null;
157
157
  }
158
- out.push({ id: each.id, state: "attached", ...(rect === undefined ? {} : { rect }) });
158
+ // A place among the marks (P112): a whole number below the most marks a show carries.
159
+ const order = each.order;
160
+ if (
161
+ order !== undefined &&
162
+ !(typeof order === "number" && Number.isInteger(order) && order >= 0 && order < LIMITS.marks)
163
+ ) {
164
+ return null;
165
+ }
166
+ out.push({
167
+ id: each.id,
168
+ state: "attached",
169
+ ...(rect === undefined ? {} : { rect }),
170
+ ...(order === undefined ? {} : { order }),
171
+ });
159
172
  }
160
173
  return out;
161
174
  }
@@ -183,6 +196,10 @@ export function parseReport(value: unknown): AnnotationReport | null {
183
196
  const rect = parseRect(value.rect);
184
197
  return !markId(value.id) || rect === null ? null : { type: "activated", id: value.id, rect };
185
198
  }
199
+ case "tracked": {
200
+ const rect = parseRect(value.rect);
201
+ return !markId(value.id) || rect === null ? null : { type: "tracked", id: value.id, rect };
202
+ }
186
203
  default:
187
204
  return null;
188
205
  }
@@ -192,7 +209,11 @@ export function parseReport(value: unknown): AnnotationReport | null {
192
209
  export function annotateMode(mode: AnnotateMode | undefined): Required<AnnotateMode> {
193
210
  const elements = mode?.elements ?? true;
194
211
  const words = mode?.text ?? true;
195
- if (typeof elements !== "boolean" || typeof words !== "boolean" || (!elements && !words)) {
212
+ if (
213
+ (typeof elements !== "boolean" && elements !== "hold") ||
214
+ typeof words !== "boolean" ||
215
+ (elements === false && !words)
216
+ ) {
196
217
  throw new TypeError("annotations.start: elements, text, or both");
197
218
  }
198
219
  return { elements, text: words };
@@ -206,7 +227,8 @@ export const hasMarker = (mark: AnnotationMark): boolean =>
206
227
  mark.count !== undefined || mark.kind === "draft";
207
228
 
208
229
  /**
209
- * The host's marks, checked before they go to the frame; throws on the first bad one. Each is
230
+ * The host's marks, checked before they go to the frame; throws on the first bad one (a count above
231
+ * `ANNOTATION_LIMITS.count` isn't bad: it is clamped to it, P116). Each is
210
232
  * rebuilt as the frame gets it: a posted mark as 0.10.0 sent it (no `kind`), a draft with
211
233
  * `kind: "draft"` and without its count (P107: a draft's marker shows no number, so the page isn't
212
234
  * told one).
@@ -223,10 +245,10 @@ export function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[] {
223
245
  `annotations.show: mark ${index} needs a unique id (1 to ${LIMITS.id} characters) and a valid anchor`,
224
246
  );
225
247
  }
226
- if (mark.count !== undefined && !count(mark.count, LIMITS.count)) {
227
- throw new TypeError(
228
- `annotations.show: mark ${index}'s count is a whole number from 0 to ${LIMITS.count}`,
229
- );
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`);
230
252
  }
231
253
  const kind: unknown = mark.kind;
232
254
  if (kind !== undefined && kind !== "posted" && kind !== "draft") {
@@ -236,6 +258,10 @@ export function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[] {
236
258
  if (kind === "draft") {
237
259
  return { id: mark.id, anchor, kind };
238
260
  }
239
- return { id: mark.id, anchor, ...(mark.count === undefined ? {} : { count: mark.count }) };
261
+ return {
262
+ id: mark.id,
263
+ anchor,
264
+ ...(mark.count === undefined ? {} : { count: Math.min(mark.count, LIMITS.count) }),
265
+ };
240
266
  });
241
267
  }
@@ -217,6 +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 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`).
220
222
  return ["allow-scripts", "allow-same-origin"];
221
223
  case "external":
222
224
  // The host may add a documented few (popups, modals, downloads), never top navigation.
@@ -235,9 +237,20 @@ export function sandboxTokens(config: PortholeConfig): string[] {
235
237
  * own documents, and opaque content is never served. Never in a `<meta>` (browsers ignore it there).
236
238
  */
237
239
  export function servedSandboxDirective(config: PortholeConfig): CspDirective | null {
238
- return config.isolation === "domain" ? ["sandbox", ...sandboxTokens(config)] : null;
240
+ if (config.isolation !== "domain") {
241
+ return null;
242
+ }
243
+ return ["sandbox", ...(config.nested === true ? PAGE_SANDBOX_TOKENS : sandboxTokens(config))];
239
244
  }
240
245
 
246
+ /**
247
+ * A nested page's sandbox (P111): its frame's attribute, set by Porthole's shell, and its own CSP
248
+ * header's, so it is an opaque origin in the shell's child frame and on a tab of its own. Scripts
249
+ * only: never `allow-same-origin`, which would give the page its served origin, the shell's, and
250
+ * so the shell's realm (a test holds every sandbox Porthole writes to this).
251
+ */
252
+ export const PAGE_SANDBOX_TOKENS: readonly string[] = ["allow-scripts"];
253
+
241
254
  /** A served page's CSP header: the page's directives, then its sandbox (P099). */
242
255
  export function servedDocumentCsp(
243
256
  config: PortholeConfig,
@@ -258,6 +258,17 @@ export interface PortholeConfig {
258
258
  * `db`). Absent: 0.6's frames, globals and manual, exactly.
259
259
  */
260
260
  readonly runtime?: RuntimeVersion;
261
+ /**
262
+ * Domain isolation, artifact pages (P111): the address the host frames serves Porthole's shell
263
+ * alone, a document of Porthole's own with no content in it, and the page runs in a child frame
264
+ * of the shell's, sandboxed without `allow-same-origin` (an opaque origin), served from the same
265
+ * origin at its files' sealed address. The shell is then a realm the page can't reach, above the
266
+ * page's frame: it relays the page's messages, and tells the host when its own transient
267
+ * activation turns on (a press in the page activates its ancestors only), which is how the host
268
+ * knows the person, not the page, moved the keyboard into the frame or opened a comment. The
269
+ * page has no storage of its own (an in-memory stand-in) and fetches nothing with a cookie.
270
+ */
271
+ readonly nested?: true;
261
272
  }
262
273
 
263
274
  export interface StorageConfig {
@@ -324,6 +324,7 @@ export function validateConfig(
324
324
  "storage",
325
325
  "errors",
326
326
  "runtime",
327
+ "nested",
327
328
  ],
328
329
  "config",
329
330
  );
@@ -687,6 +688,28 @@ export function validateConfig(
687
688
  }
688
689
  }
689
690
 
691
+ if (config.nested !== undefined) {
692
+ if (config.nested !== true) {
693
+ fail("config.nested", "must be true, or left out");
694
+ }
695
+ if (config.isolation !== "domain" || config.mode !== "artifact") {
696
+ fail("config.nested", "nests artifact pages served on their own origin (domain isolation)");
697
+ }
698
+ // The page's origin is opaque (P111): nothing of the content origin's own is its.
699
+ if (config.storage !== undefined) {
700
+ fail("config.nested", "a nested page keeps no storage: drop config.storage");
701
+ }
702
+ if (capabilities.assets !== undefined) {
703
+ fail(
704
+ "config.nested",
705
+ "a nested page can't load its asset library (/_blob/) yet: drop assets",
706
+ );
707
+ }
708
+ if (isObject(config.egress) && config.egress.libraries === true) {
709
+ fail("config.nested", "a nested page can't load Porthole's libraries from its origin yet");
710
+ }
711
+ }
712
+
690
713
  if (config.errors !== undefined) {
691
714
  if (config.errors !== "agent" && config.errors !== "host" && config.errors !== "none") {
692
715
  fail("config.errors", 'must be "agent", "host" or "none"');
@@ -93,9 +93,11 @@ export function defineDisplays<N extends string>(
93
93
  return presets.url({ ...kind.options, contentOrigins: [source] });
94
94
  }
95
95
  const options = kind.options ?? {};
96
+ // Nesting (P111) is a served page's: an opaque frame has nothing to nest.
97
+ const { nested: _nested, ...opaque } = options;
96
98
  return presets[kind.preset](
97
99
  source === null
98
- ? options
100
+ ? opaque
99
101
  : { ...options, ...kind.served, isolation: "domain", contentOrigins: [source] },
100
102
  );
101
103
  };
@@ -196,7 +196,7 @@ export function manualLimits(config: PortholeConfig, network: string): ManualLim
196
196
  );
197
197
  add(
198
198
  "storage",
199
- config.isolation === "opaque"
199
+ config.isolation === "opaque" || config.nested === true
200
200
  ? `State isn't saved: localStorage works but lasts only while the ${it} is on screen, and a reload or another device starts fresh. Keep what matters in the ${it}'s code.`
201
201
  : config.storage?.scope !== undefined
202
202
  ? `localStorage is kept for ${config.storage.scope}, in this browser; another browser or device starts fresh. Reads and writes can throw (private windows, strict settings): wrap them in try/catch and keep only what can be lost.`