@botiverse/porthole 0.13.0 → 0.14.0

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 (68) hide show
  1. package/dist/annotate/types.d.ts +32 -3
  2. package/dist/annotate/types.js +4 -0
  3. package/dist/annotate/validate.js +19 -2
  4. package/dist/check/page-source.js +1 -1
  5. package/dist/compile/policy.d.ts +7 -0
  6. package/dist/compile/policy.js +13 -1
  7. package/dist/config/schema.d.ts +11 -0
  8. package/dist/config/validate.js +19 -0
  9. package/dist/conformance/harness-source.js +1 -1
  10. package/dist/displays/displays.js +3 -1
  11. package/dist/guide/limits.js +1 -1
  12. package/dist/host/create-host.d.ts +2 -0
  13. package/dist/host/create-host.js +73 -3
  14. package/dist/host/pass-on.d.ts +15 -0
  15. package/dist/host/pass-on.js +65 -0
  16. package/dist/host/types.d.ts +22 -0
  17. package/dist/index.d.ts +4 -1
  18. package/dist/index.js +4 -1
  19. package/dist/isolation/types.d.ts +8 -0
  20. package/dist/isolation/types.js +8 -0
  21. package/dist/platform/focus-guard.d.ts +71 -2
  22. package/dist/platform/focus-guard.js +187 -12
  23. package/dist/platform/types.d.ts +8 -1
  24. package/dist/platform/web.js +60 -4
  25. package/dist/presets/presets.d.ts +2 -0
  26. package/dist/presets/presets.js +1 -0
  27. package/dist/server/files.js +19 -3
  28. package/dist/server/index.d.ts +1 -0
  29. package/dist/server/index.js +4 -0
  30. package/dist/server/nested.d.ts +37 -0
  31. package/dist/server/nested.js +70 -0
  32. package/dist/server/server.js +57 -7
  33. package/dist/shell/annotate.d.ts +1 -1
  34. package/dist/shell/annotate.js +157 -7
  35. package/dist/shell/frame.d.ts +45 -0
  36. package/dist/shell/frame.js +250 -0
  37. package/dist/shell/plan.js +2 -1
  38. package/dist/shell/runtime.js +49 -14
  39. package/docs/ADOPTING.md +56 -2
  40. package/docs/ARCHITECTURE.md +23 -0
  41. package/docs/DECISIONS.md +209 -0
  42. package/docs/DESIGN.md +9 -0
  43. package/docs/THREAT_MODEL.md +75 -5
  44. package/package.json +1 -1
  45. package/src/annotate/types.ts +28 -3
  46. package/src/annotate/validate.ts +23 -2
  47. package/src/compile/policy.ts +14 -1
  48. package/src/config/schema.ts +11 -0
  49. package/src/config/validate.ts +23 -0
  50. package/src/displays/displays.ts +3 -1
  51. package/src/guide/limits.ts +1 -1
  52. package/src/host/create-host.ts +76 -4
  53. package/src/host/pass-on.ts +73 -0
  54. package/src/host/types.ts +20 -0
  55. package/src/index.ts +4 -1
  56. package/src/isolation/types.ts +12 -0
  57. package/src/platform/focus-guard.ts +258 -15
  58. package/src/platform/types.ts +8 -1
  59. package/src/platform/web.ts +81 -9
  60. package/src/presets/presets.ts +3 -0
  61. package/src/server/files.ts +19 -3
  62. package/src/server/index.ts +10 -0
  63. package/src/server/nested.ts +86 -0
  64. package/src/server/server.ts +65 -6
  65. package/src/shell/annotate.ts +157 -7
  66. package/src/shell/frame.ts +268 -0
  67. package/src/shell/plan.ts +2 -1
  68. package/src/shell/runtime.ts +49 -14
@@ -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.0 (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,10 @@ 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).
20
23
 
21
24
  ## 1. Two layers
22
25
 
@@ -162,6 +165,15 @@ Whatever the use:
162
165
  nothing one click away that posts, submits, resolves, deletes or discards (a draft's view, P107,
163
166
  included: no "Post" or "Submit review" in it). Its menus and popovers are part of it, portaled
164
167
  ones too (P105; ADOPTING.md § Annotations has the code: the view `inert` while it arms).
168
+ One exception to "takes no focus" (P112): in a comment mode the person started themselves (the
169
+ host's own control, never a report), a composer their selection opens (`selected`) may take
170
+ focus, with `focusField`, if all it can do is save a draft: nothing in it posts, submits or sends,
171
+ Enter in it only adds the draft to the batch (submitting is only ever the host's own "Submit N"
172
+ control, outside the composer), it shows plainly that it is a draft (so the person can see where
173
+ their keys are going), and the rest of this guard holds (no press for 500 ms, beside the frame). The page still chooses
174
+ when `selected` comes, so what it can do with that moment is put the person's next keys into a
175
+ draft they see and can discard, never send one; outside such a mode, or for a composer that can
176
+ send, it takes no focus.
165
177
  - Know that a display can take the keyboard: a page calls `focus()` on its own input whenever it
166
178
  likes (on Chromium and WebKit with no gesture), and what the person goes on typing goes to it.
167
179
  `createHost` (every `PortholeView` too) gives focus back when it leaves one of the page's text
@@ -322,6 +334,30 @@ encrypted into the path, since WebKit keeps no cookie in a frame (P083).
322
334
  worker; a page's CSP opens its own version's path, not its whole origin.
323
335
  - With a per-request check (`authorize`), the host decides again on every request; a deny is a
324
336
  403 that says `denied`.
337
+ - A nested page (`nested: true`, P111): the framed address answers Porthole's shell alone, its
338
+ script the only one its CSP runs, framing and fetching only the origin's sealed files' prefix.
339
+ The page is the shell's child, `sandbox="allow-scripts"` (never `allow-same-origin`, held by a
340
+ static check over every sandbox Porthole writes) and the same sandbox in its own CSP, so it is an
341
+ opaque origin in its frame and on a tab; it is loaded, and loads its files, at its sealed address
342
+ without a cookie, and its files then carry `Cross-Origin-Resource-Policy: cross-origin` and
343
+ `Access-Control-Allow-Origin: *` (an opaque page's own loads are cross-origin: the address is
344
+ the access, never the request's origin). So whoever holds a page's sealed address can read its
345
+ files from any origin, a page of their own included, until the address ends (an hour on its own,
346
+ P083): it is a bearer credential, as safe as it is unleaked. Porthole keeps it out of what it
347
+ says: no referrer goes with any load (`Referrer-Policy: no-referrer`, the shell's frame
348
+ `referrerpolicy="no-referrer"`), the host's reports name it as `./` (P083), and the shell's own
349
+ answer is `no-store`. The page itself can read it (its address) and so pass it on by any channel
350
+ it has, as it can pass on its files' bytes. The page has none of the origin's storage, and nothing
351
+ of the shell's realm: messages between them go by `postMessage`, the page's trusted by
352
+ `event.source`, and the shell drops what the page says in the shell's own namespace. Only the
353
+ shell (same-origin) renews the page's address; a module the page loaded keeps one that ends
354
+ within the hour. Every answer below the sealed prefix carries a CSP sandbox, never
355
+ `allow-same-origin` (a page's `allow-scripts`, every other file's runs nothing): a file opened on
356
+ a tab of its own (an SVG or XML file with a script) is opaque, never the shell's origin (negative
357
+ control `file-sandbox`). The sandbox refuses no worker (measured on the four engines): a nested
358
+ page's workers come from Blob URLs (a worker from its set's own script is refused by its opaque
359
+ origin, sandbox or not), and those load the set's scripts. Assets and Porthole's libraries aren't
360
+ served to a nested page yet.
325
361
 
326
362
  **The host must**
327
363
 
@@ -556,7 +592,8 @@ wall on three engines, and `defineHostConformance` runs it against a host's own
556
592
  effects are its own), and group displays by page (S7).
557
593
 
558
594
  **Annotations** (`annotate`, P053, P104, P107). The shell that draws marks and reports anchors shares
559
- its realm with the content, so:
595
+ its realm with the content (a nested page's too: its marks are drawn by the runtime in the page's
596
+ own frame, below the shell, P111), so:
560
597
 
561
598
  - *What content learns.* Everything the host sends in a `show` is posted into the frame's window,
562
599
  where the content can listen: each mark's id, anchor and, where given, `count` (the number on
@@ -692,6 +729,35 @@ unposted words beside the frame and tell the page when.
692
729
  technology's activation within 5 s of their key or press on the page): focus goes back, and
693
730
  their next press once the pointer has left the frame and come back, a Tab, or an activation 5 s
694
731
  later keeps it.
732
+ - *Full Chromium* (P111, measured on Chromium 153, not the headless shell): a cross-site frame is
733
+ out of process, and the host's page sees nothing of a press in it (no `:active`, no `:hover`, no
734
+ pointer event past the frame's edge). For a served page that isn't nested, a person's real click
735
+ into its field is taken back every time there (the display stopped at the third), and
736
+ `comments.open` from a real click is refused within 5 s of any input on the host's page
737
+ (porthole#53). Nest it.
738
+ - *A nested page* (P111): the guard asks the page's shell, a realm the page can't reach above its
739
+ frame, whose transient activation turns on only from a press or key in the page (activation goes
740
+ up, never down). A move into the frame is the person's if the shell's activation turned on within
741
+ the last second and the host's page had no trusted press or key since; or a Tab, the host's own
742
+ move, or a press the engine shows on the frame element. Nothing else counts: no pointer over the
743
+ frame, no host-wide activation. A move the shell hasn't spoken of yet waits for its word (its next
744
+ frame) at most 500 ms, then is taken back. Measured on full Chromium, the headless shell, WebKit
745
+ and Firefox (`leak/served/nested.spec.ts`): a real click into the page's field keeps the
746
+ keyboard; the page's `focus()` as it loads, on a timer while the person types, right after a
747
+ click on the host's own button, 1.2 to 4.5 s after the person paused typing, and 700 ms after
748
+ they pressed it and went back to the composer is taken back; what a page says in the shell's
749
+ name, to its parent or to the host's window, moves nothing (negative controls `shell-namespace`,
750
+ `shell-host-input`). *What doesn't*: a press in the page within 5 s of the last one turns no
751
+ activation on, so a second move into it after the person went back to the host's page is taken
752
+ back until 5 s after their last press or key in the page, or they Tab in; the page gets the keys
753
+ typed while a move waits for the shell's word; a shell without `navigator.userActivation` leaves
754
+ 0.13's rule. A page that holds the thread it shares with its shell (WebKit; Firefox and Chromium
755
+ where the frames share a process) from its own click handler would push the moment the shell sees
756
+ its activation past the person's next keys on the host's page: so the shell looks and beats every
757
+ 50 ms and says how long it went without a look, and an activation it reports after a stall of over
758
+ 100 ms (its own, or no word heard) is no one's gesture until it lapses (P111, after its review;
759
+ negative control `shell-stall`). The cost: in those engines a page that keeps its thread busy has
760
+ the person's real click taken for uncertain until it is idle.
695
761
 
696
762
  ### The app runtime
697
763
 
@@ -727,7 +793,11 @@ section.
727
793
  - `comments` is write-only: the page learns only whether the composer opened. It opens only from
728
794
  a gesture with the host page's focus in the calling frame (P109: a press in it or a Tab into it;
729
795
  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
796
+ `comments-in-frame`). In a nested page (P111) it opens too while the page's shell saw the
797
+ person's gesture within the last second, with no press or key on the host's page since: a real
798
+ click on the page's button a moment after typing in the host's composer opens it, on full
799
+ Chromium too (porthole#53); with no click it is refused, whatever the page says in the shell's
800
+ name. A draft it gives (P108) is at most 2,000 characters of text a person can
731
801
  see (P109): nothing invisible (zero-width characters, bidi and tag characters, controls but a
732
802
  new line and a tab; U+200C and U+200D only between two letters or marks, where Persian and the
733
803
  Indic scripts need them, never first, last, doubled, beside a space or punctuation, or in an
@@ -796,7 +866,7 @@ section.
796
866
  The decisions below come from the 2026-10-19 review, and all of them have merged. Each row says
797
867
  what was wrong, what holds now, and the limit its decision accepts, if any. Later reviews' decisions
798
868
  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).
869
+ of 0.12.0's drafts), P111 (a nested page, S3; in 0.14.0).
800
870
 
801
871
  | Decision | State | What it closes | Sections |
802
872
  | --- | --- | --- | --- |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.13.0",
3
+ "version": "0.14.0",
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": {
@@ -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
  }
@@ -106,6 +111,12 @@ export interface AnchorResult {
106
111
  readonly state: AnchorState;
107
112
  /** Where it is now, when attached. */
108
113
  readonly rect?: AnnotationRect;
114
+ /**
115
+ * Its place in the document among the found marks, from 0 (P112): where it starts, offscreen
116
+ * marks included, for a host that lists marks in reading order. The content's word: an order to
117
+ * sort by, never a fact.
118
+ */
119
+ readonly order?: number;
109
120
  }
110
121
 
111
122
  /** What the frame reports, once the host has checked it. */
@@ -118,7 +129,11 @@ export type AnnotationReport =
118
129
  }
119
130
  /** The text selection went away. */
120
131
  | { readonly type: "unselected" }
121
- /** The person pressed Escape while picking an element. */
132
+ /**
133
+ * The person pressed Escape while picking an element (the pick ends), or while selecting text
134
+ * (P112: the page keeps the key; the host decides what ends). The page's word too: a page can
135
+ * send it, and the host takes it only while it asked for a pick or for text.
136
+ */
122
137
  | { readonly type: "cancelled" }
123
138
  /**
124
139
  * Where the marked anchors are now: every mark after `show`, the focused one after `focus`,
@@ -128,6 +143,12 @@ export type AnnotationReport =
128
143
  * host was last told, at most once a second (P104).
129
144
  */
130
145
  | { readonly type: "anchored"; readonly results: readonly AnchorResult[] }
146
+ /**
147
+ * The box of the mark the host follows (`annotations.track`, P112), in the frame's viewport, at
148
+ * an animation frame where it moved: at most 60 a second, for that mark only, clamped to the
149
+ * frame. The content's word: where to put a card beside it, nothing more.
150
+ */
151
+ | { readonly type: "tracked"; readonly id: string; readonly rect: AnnotationRect }
131
152
  /**
132
153
  * The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
133
154
  * (P107); `rect` is the marker's box, to open the host's own UI beside it. The content can fake
@@ -155,6 +176,10 @@ export const ANNOTATE_METHODS = {
155
176
  anchored: "porthole/annotate.anchored",
156
177
  /** Frame → host: a mark's marker was clicked (P104). */
157
178
  activated: "porthole/annotate.activated",
179
+ /** Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112). */
180
+ track: "porthole/annotate.track",
181
+ /** Frame → host: the followed mark's box, as it moves (P112). */
182
+ tracked: "porthole/annotate.tracked",
158
183
  } as const;
159
184
 
160
185
  /** 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 };
@@ -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 the content origin, and the page is
221
+ // 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.`
@@ -26,8 +26,9 @@ import { isRefused } from "../bridge/refusal.ts";
26
26
  import { capabilitySpec } from "../config/capabilities.ts";
27
27
  import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
28
28
  import { locateServed } from "./locate.ts";
29
+ import { mayPassOn } from "./pass-on.ts";
29
30
  import { watchOutcome, type OutcomeWatch } from "./outcome.ts";
30
- import type { FrameSource } from "../isolation/types.ts";
31
+ import { STORAGE_USED_METHOD, type FrameSource } from "../isolation/types.ts";
31
32
  import { webPlatform } from "../platform/web.ts";
32
33
  import { TAKES } from "../platform/focus-guard.ts";
33
34
  import type { Surface } from "../platform/types.ts";
@@ -66,8 +67,12 @@ const REPORTS: Readonly<Record<string, AnnotationReport["type"]>> = {
66
67
  [ANNOTATE_METHODS.cancelled]: "cancelled",
67
68
  [ANNOTATE_METHODS.anchored]: "anchored",
68
69
  [ANNOTATE_METHODS.activated]: "activated",
70
+ [ANNOTATE_METHODS.tracked]: "tracked",
69
71
  };
70
72
 
73
+ /** The most `tracked` reports a second the host takes (P112): one per animation frame at 60 Hz. */
74
+ export const TRACKED_PER_SECOND = 60;
75
+
71
76
  const isRecord = (value: unknown): value is Record<string, unknown> =>
72
77
  value !== null && typeof value === "object" && !Array.isArray(value);
73
78
  const STANDARD = new Set(MCP_APPS_STYLE_VARIABLES);
@@ -95,6 +100,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
95
100
 
96
101
  return {
97
102
  compiled,
103
+ mayPassOn: (declaration) => mayPassOn(config, declaration),
98
104
  mount(container: HTMLElement, mount: MountOptions): DisplayHandle<C> {
99
105
  const handlers = { ...options.handlers, ...mount.handlers };
100
106
  // A host whose consent is a Refused refuses every consent-gated call before its handler:
@@ -184,7 +190,11 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
184
190
  let annotating: Required<AnnotateMode> | null = null;
185
191
  let marks: AnnotationMark[] = [];
186
192
  let activeMark: string | null = null;
193
+ // The mark the host follows (P112), and when it took each `tracked` in the last second.
194
+ let tracking: string | null = null;
195
+ const trackedTimes: number[] = [];
187
196
  let handshaken = false;
197
+ let storageTold = false;
188
198
  const toFrame = (method: string, params: Record<string, unknown>) => {
189
199
  if (handshaken && surface !== null) {
190
200
  surface.transport.send({ jsonrpc: "2.0", method, params });
@@ -200,6 +210,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
200
210
  if (annotating !== null) {
201
211
  toFrame(ANNOTATE_METHODS.start, { ...annotating });
202
212
  }
213
+ if (tracking !== null) {
214
+ toFrame(ANNOTATE_METHODS.track, { id: tracking });
215
+ }
203
216
  };
204
217
  /**
205
218
  * The frame's viewport as the platform tells it now; undefined where it can't (no
@@ -243,6 +256,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
243
256
  switch (report.type) {
244
257
  case "selected":
245
258
  case "activated":
259
+ case "tracked":
246
260
  return { ...report, rect: clampRect(report.rect, viewport) };
247
261
  case "anchored":
248
262
  return {
@@ -281,6 +295,25 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
281
295
  void through.call("annotate", null);
282
296
  return;
283
297
  }
298
+ // The followed mark's box (P112): the mark the host follows and no other, while it is
299
+ // shown, at most 60 a second; past the bridge's rate for reports, which a card that follows
300
+ // its mark at every frame would spend at once.
301
+ if (report.type === "tracked") {
302
+ const { id } = report;
303
+ if (id !== tracking || !marks.some((mark) => mark.id === id)) {
304
+ return;
305
+ }
306
+ const at = Date.now();
307
+ while (trackedTimes.length > 0 && at - (trackedTimes[0] as number) >= 1_000) {
308
+ trackedTimes.shift();
309
+ }
310
+ if (trackedTimes.length >= TRACKED_PER_SECOND) {
311
+ return;
312
+ }
313
+ trackedTimes.push(at);
314
+ emit("annotation", withinFrame(report));
315
+ return;
316
+ }
284
317
  switch (report.type) {
285
318
  case "selected": {
286
319
  const kind = report.anchor.kind;
@@ -290,7 +323,8 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
290
323
  ) {
291
324
  return;
292
325
  }
293
- if (kind === "element") {
326
+ // A pick ends with it; holding a block (P112) lasts until the host stops it.
327
+ if (kind === "element" && annotating.elements === true) {
294
328
  annotating = annotating.text ? { elements: false, text: true } : null;
295
329
  }
296
330
  break;
@@ -301,10 +335,14 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
301
335
  }
302
336
  break;
303
337
  case "cancelled":
304
- if (annotating?.elements !== true) {
338
+ // While the host asked for a pick or for text (P112: Escape while selecting text);
339
+ // a pick ends with it, text selection is the host's to stop.
340
+ if (annotating === null) {
305
341
  return;
306
342
  }
307
- annotating = annotating.text ? { elements: false, text: true } : null;
343
+ if (annotating.elements === true) {
344
+ annotating = annotating.text ? { elements: false, text: true } : null;
345
+ }
308
346
  break;
309
347
  case "anchored": {
310
348
  const known = new Set(marks.map((mark) => mark.id));
@@ -354,6 +392,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
354
392
  if (activeMark !== null && !marks.some((mark) => mark.id === activeMark)) {
355
393
  activeMark = null;
356
394
  }
395
+ if (tracking !== null && !marks.some((mark) => mark.id === tracking)) {
396
+ tracking = null;
397
+ toFrame(ANNOTATE_METHODS.track, { id: null });
398
+ }
357
399
  toFrame(ANNOTATE_METHODS.show, {
358
400
  marks,
359
401
  ...(activeMark === null ? {} : { active: activeMark }),
@@ -367,10 +409,20 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
367
409
  activeMark = id;
368
410
  toFrame(ANNOTATE_METHODS.focus, { id });
369
411
  },
412
+ track(id) {
413
+ needsAnnotate("track");
414
+ if (id !== null && !marks.some((mark) => mark.id === id)) {
415
+ throw new TypeError(`annotations.track: no mark ${JSON.stringify(id)} is shown`);
416
+ }
417
+ tracking = id;
418
+ trackedTimes.length = 0;
419
+ toFrame(ANNOTATE_METHODS.track, { id });
420
+ },
370
421
  clear() {
371
422
  needsAnnotate("clear");
372
423
  marks = [];
373
424
  activeMark = null;
425
+ tracking = null;
374
426
  toFrame(ANNOTATE_METHODS.clear, {});
375
427
  },
376
428
  };
@@ -436,6 +488,11 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
436
488
  };
437
489
 
438
490
  const stop = () => {
491
+ // A run that ran a page with storage of its own making and never heard it used: no (P111).
492
+ if (bridge !== null && handshaken && !storageTold && compiled.shell?.storage === "memory") {
493
+ emit("storage", { used: false });
494
+ }
495
+ storageTold = false;
439
496
  // The run's bridge refuses what still waits for a confirmation: a yes to it runs nothing
440
497
  // (P095, after the review), and the next run's bridge starts its count again.
441
498
  bridge?.close();
@@ -469,6 +526,8 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
469
526
  allow: compiled.allow,
470
527
  referrerPolicy: compiled.referrerPolicy,
471
528
  colorScheme: scheme,
529
+ // A nested page's shell (P111): the config's word, never the frame's.
530
+ ...(config.nested === true ? { nested: true } : {}),
472
531
  // An app reports no size: its frame fills the host's container, at least the minimum;
473
532
  // so does any display the host mounts to fill, or whose layout fills (P065): its
474
533
  // content scrolls itself.
@@ -563,6 +622,19 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
563
622
  if (annotates) {
564
623
  created.transport.listen((raw) => onAnnotation(raw, opening));
565
624
  }
625
+ // Whether the page used storage (P111): once per run, the page's word (a count, no more).
626
+ created.transport.listen((raw) => {
627
+ if (
628
+ !storageTold &&
629
+ isRecord(raw) &&
630
+ raw.jsonrpc === "2.0" &&
631
+ raw.method === STORAGE_USED_METHOD &&
632
+ !("id" in raw)
633
+ ) {
634
+ storageTold = true;
635
+ emit("storage", { used: true });
636
+ }
637
+ });
566
638
  bridge = opening;
567
639
  const opened = adapter.connect({
568
640
  display: { id: mount.displayId, title: mount.title },
@@ -0,0 +1,73 @@
1
+ import type { CapabilityName } from "../config/capabilities.ts";
2
+ import type { PortholeConfig } from "../config/schema.ts";
3
+ import { egressOrigins, type EgressKind } from "../compile/policy.ts";
4
+ import { LIBRARY_CDNS } from "../presets/presets.ts";
5
+ import { familyOf, runtimeCapability } from "../runtime/contract.ts";
6
+ import type { PageDeclaration } from "../runtime/declaration.ts";
7
+
8
+ /** Every kind a page reaches the network by. */
9
+ const KINDS: readonly EgressKind[] = ["connect", "script", "style", "img", "font", "media"];
10
+
11
+ /**
12
+ * The host functions that carry what a page puts in them to someone other than the person viewing
13
+ * it (P112, after the review, porthole#54): stores others read (`db`, a new version through
14
+ * `artifact`, the asset library through `assets`), a URL the person opens (`openLink`), the agent's
15
+ * conversation and context (`sendPrompt`, `setModelContext`), and the host's data services, which
16
+ * may be someone else's (`callTool`, `readData`, `subscribeData`: their arguments are the page's).
17
+ * Not here: the person's own clipboard and disk (`copyText`, `downloadFile`), the host's own UI
18
+ * (`annotate`, `resize`, `comments`: the composer is the person's, under the host's duties), and
19
+ * what only reads (`user`). `reportError` is one where the config sends errors to the agent.
20
+ */
21
+ const CARRIERS: readonly CapabilityName[] = [
22
+ "db",
23
+ "artifact",
24
+ "assets",
25
+ "openLink",
26
+ "sendPrompt",
27
+ "setModelContext",
28
+ "callTool",
29
+ "readData",
30
+ "subscribeData",
31
+ ];
32
+
33
+ /**
34
+ * Whether a page shown under `config` with `declaration` may pass on what it is given (P112: a
35
+ * person's draft, which a host shows a page only where it can't). It may when it can reach one of
36
+ * the host functions that carry what it puts in them to others (`CARRIERS`; `reportError` where
37
+ * errors go to the agent), or the network beyond the library CDNs (`LIBRARY_CDNS`): any https site
38
+ * (`anyHttps`), or an origin the host (or a capability) added for connections, scripts, styles,
39
+ * images, fonts or media. A library CDN serves published packages by their path, and its logs are
40
+ * its operator's, not the page author's: not counted. A page reaches a host function the config
41
+ * declares: under the runtime with a declaration, only through a built-in family or one it
42
+ * declared (one no family serves, wherever the config declares it); without a declaration (a page from before 0.7), or without the runtime, every one, as
43
+ * 0.6's globals. The host's rule made checkable: "a page with a channel gets no drafts".
44
+ */
45
+ export function mayPassOn(config: PortholeConfig, declaration: PageDeclaration | null): boolean {
46
+ const declared = (declaration?.capabilities ?? {}) as Readonly<Record<string, unknown>>;
47
+ const reaches = (name: CapabilityName): boolean => {
48
+ if (config.capabilities[name] === undefined) {
49
+ return false;
50
+ }
51
+ if (config.runtime === undefined || declaration === null) {
52
+ return true;
53
+ }
54
+ // One no runtime family serves (`reportError`: the shell reports what the page throws) is
55
+ // the page's wherever the config declares it.
56
+ const family = familyOf(name);
57
+ return (
58
+ family === null ||
59
+ runtimeCapability(family.name).builtIn ||
60
+ declared[family.name] !== undefined
61
+ );
62
+ };
63
+ if (CARRIERS.some(reaches) || (config.errors === "agent" && reaches("reportError"))) {
64
+ return true;
65
+ }
66
+ if ((config.egress.anyHttps ?? []).length > 0) {
67
+ return true;
68
+ }
69
+ return KINDS.some((kind) => {
70
+ const cdns = new Set(LIBRARY_CDNS[kind] ?? []);
71
+ return egressOrigins(config, kind).some((origin) => !cdns.has(origin));
72
+ });
73
+ }