@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
@@ -38,7 +38,8 @@ export function shellPlan(config) {
38
38
  themeVariables: Object.keys(config.theme.variables),
39
39
  themeEvent: config.theme.event,
40
40
  themeDocuments: config.theme.documents ?? "declared",
41
- storage: config.isolation === "opaque" ? "memory" : "native",
41
+ // An opaque origin has no storage: an opaque frame's, and a nested page's (P111).
42
+ storage: config.isolation === "opaque" || config.nested === true ? "memory" : "native",
42
43
  maxErrorReports: config.limits.maxErrorReports,
43
44
  maxPromptChars: config.limits.maxPromptChars,
44
45
  maxCopyChars: MAX_COPY_CHARS,
@@ -68,6 +68,9 @@ export const SHELL_RUNTIME = String.raw `(() => {
68
68
  }
69
69
  };
70
70
 
71
+ // Whether the page touched storage, told to the host once (P111): yes, never what it keeps.
72
+ let storageTouched = false;
73
+ let tellStorage = () => {};
71
74
  if (plan.storage === "memory") {
72
75
  // An opaque origin has no storage: a map stands in, for as long as the frame lives.
73
76
  const store = () => {
@@ -84,8 +87,18 @@ export const SHELL_RUNTIME = String.raw `(() => {
84
87
  };
85
88
  };
86
89
  for (const name of ["localStorage", "sessionStorage"]) {
90
+ const kept = store();
87
91
  try {
88
- Object.defineProperty(window, name, { configurable: true, value: store() });
92
+ Object.defineProperty(window, name, {
93
+ configurable: true,
94
+ get() {
95
+ if (!storageTouched) {
96
+ storageTouched = true;
97
+ tellStorage();
98
+ }
99
+ return kept;
100
+ },
101
+ });
89
102
  } catch (_) {}
90
103
  }
91
104
  }
@@ -115,6 +128,8 @@ export const SHELL_RUNTIME = String.raw `(() => {
115
128
  // takes the next load for that page, not for content that left). Anything else stays stopped:
116
129
  // another path of the origin, a file that isn't a page, another origin.
117
130
  let navigating = (_url) => {};
131
+ // A nested page's files' address renewed by its shell (P111), which the shell's message gives.
132
+ let adoptFiles = (_base) => false;
118
133
  let filesBase = plan.files && typeof plan.files.base === "string" ? plan.files.base : null;
119
134
  // Every address the page's files had (P083: a sealed one is renewed): what reports say as "./".
120
135
  const filesBases = filesBase === null ? [] : [filesBase];
@@ -880,6 +895,11 @@ export const SHELL_RUNTIME = String.raw `(() => {
880
895
  const filesSet = plan.files && plan.files.set && typeof plan.files.set === "object" ? { id: String(plan.files.set.id), version: String(plan.files.set.version) } : null;
881
896
  const notice = (url, more) => post({ method: "porthole/navigating", params: Object.assign({ url: ownAddresses(url).slice(0, 4096) }, filesSet === null ? {} : { set: filesSet }, more) });
882
897
  navigating = (url) => notice(url, {});
898
+ // The page used storage (P111): said once, as soon as the shell can speak; never keys or values.
899
+ tellStorage = () => post({ method: "porthole/storage-used", params: {} });
900
+ if (storageTouched) {
901
+ tellStorage();
902
+ }
883
903
  if (arrived) {
884
904
  notice(location.href, { arrived: true });
885
905
  }
@@ -887,28 +907,38 @@ export const SHELL_RUNTIME = String.raw `(() => {
887
907
  // it ends, the page moved to the new one in place (the same page, the same history entry). Its
888
908
  // modules keep the address they loaded from; the server serves their own loads till the session
889
909
  // ends.
910
+ const replace = History.prototype.replaceState;
911
+ // The files' origin, read from the address itself: a nested page's own origin is opaque (P111).
912
+ const filesOrigin = filesBase === null ? null : new NativeURL(filesBase).origin;
913
+ // A renewed sealed address (P083): one segment under the same origin's sealed prefix, checked
914
+ // through the platform's own functions (content may have replaced a prototype's, and the base
915
+ // decides where this page may go, ownPage); the page moves there in place.
916
+ const adopt = (base) => {
917
+ const prefix = filesOrigin + "/__porthole/f/";
918
+ if (filesBase === null || typeof base !== "string" || callOf(indexIn, base, [prefix]) !== 0 || callOf(indexIn, callOf(sliceOf, base, [prefix.length, -1]), ["/"]) !== -1 || callOf(sliceOf, base, [-1]) !== "/") {
919
+ return false;
920
+ }
921
+ const here = location.href;
922
+ if (here.indexOf(filesBase) === 0) {
923
+ try {
924
+ applyOf(replace, history, [history.state, "", base + here.slice(filesBase.length)]);
925
+ } catch (_) {}
926
+ }
927
+ filesBase = base;
928
+ filesBases.push(base);
929
+ return true;
930
+ };
931
+ adoptFiles = adopt;
890
932
  if (filesBase !== null && typeof plan.files.expires === "number") {
891
933
  const nativeFetch = window.fetch.bind(window);
892
- const replace = History.prototype.replaceState;
893
934
  const renewIn = (expires) => Math.max(30000, expires - Date.now() - 300000);
894
935
  const renew = () => {
895
936
  nativeFetch(filesBase + "__porthole/renew", { credentials: "omit", cache: "no-store" })
896
937
  .then((answer) => (answer.ok ? answer.json() : null))
897
938
  .then((renewed) => {
898
- // Checked through the platform's own functions: content may have replaced a prototype's,
899
- // and the base decides where this page may go (ownPage).
900
- const prefix = location.origin + "/__porthole/f/";
901
- if (!renewed || typeof renewed.base !== "string" || typeof renewed.expires !== "number" || callOf(indexIn, renewed.base, [prefix]) !== 0 || callOf(indexIn, callOf(sliceOf, renewed.base, [prefix.length, -1]), ["/"]) !== -1 || callOf(sliceOf, renewed.base, [-1]) !== "/") {
939
+ if (!renewed || typeof renewed.expires !== "number" || !adopt(renewed.base)) {
902
940
  return;
903
941
  }
904
- const here = location.href;
905
- if (here.indexOf(filesBase) === 0) {
906
- try {
907
- applyOf(replace, history, [history.state, "", renewed.base + here.slice(filesBase.length)]);
908
- } catch (_) {}
909
- }
910
- filesBase = renewed.base;
911
- filesBases.push(renewed.base);
912
942
  setTimeout(renew, renewIn(renewed.expires));
913
943
  })
914
944
  .catch(() => setTimeout(renew, 60000));
@@ -1465,6 +1495,11 @@ export const SHELL_RUNTIME = String.raw `(() => {
1465
1495
  case "ui/notifications/tool-input":
1466
1496
  void render(params.arguments);
1467
1497
  break;
1498
+ case "porthole/files-renewed":
1499
+ // From the page's parent only (the listener's check): a nested page's shell renewed its
1500
+ // files' sealed address, which this page can't (its loads aren't its origin's own, P111).
1501
+ adoptFiles(params.base);
1502
+ break;
1468
1503
  case "ui/notifications/host-context-changed":
1469
1504
  applyTheme(params);
1470
1505
  break;
package/docs/ADOPTING.md CHANGED
@@ -286,7 +286,11 @@ display.on("annotation", (report) => {
286
286
  to its author after; origins its config declares for egress (an MCP App's `connectDomains`, an
287
287
  `egress` you opened) can carry the same out. Send
288
288
  drafts only to pages without such a channel (annotations, `copyText`, `openLink` and the like),
289
- or accept that the page's author and other viewers can learn of them (THREAT_MODEL §7).
289
+ or accept that the page's author and other viewers can learn of them (THREAT_MODEL §7). Ask
290
+ `host.mayPassOn(declaration)` (or `mayPassOn(config, declaration)`, P112): true for a page that
291
+ can reach `db`, `artifact`, `assets`, `openLink`, `sendPrompt`, `setModelContext`, `callTool`,
292
+ `readData` or `subscribeData` (or `reportError` with errors to the agent), or egress beyond the
293
+ library CDNs (whose paths only their operators read); show such a page no draft marks.
290
294
  - **The content chooses when your view opens and where** (it can post `activated` for a mark you
291
295
  show on the person's own press in the content, under their pointer, P105), so a view that a
292
296
  report opens or moves takes no press of any kind for 500 ms after it appears or moves (no
@@ -359,7 +363,10 @@ display.on("focusTaken", ({ typing }) => toast(typing ? "This page tried to take
359
363
  display.on("contentError", ({ message }) => log(message)); // "The content kept taking the keyboard from the page; it was stopped."
360
364
  // Moving focus into a display yourself (a "focus the page" shortcut): use the display's own move.
361
365
  display.focus(); // not frame.focus(): from a text field, that one is taken for the page's and undone
362
- // Opening your composer focused (on `selected`, say): Porthole's move, not textarea.focus().
366
+ // Opening your composer focused: only in a comment mode the person started, for a composer that can
367
+ // only save a draft (Enter adds it to the batch; submitting is only your own "Submit N"), and that
368
+ // shows plainly it is a draft (THREAT_MODEL §6, P112); any other view a report opens takes no focus. Then
369
+ // Porthole's move, not textarea.focus().
363
370
  import { focusField } from "@botiverse/porthole";
364
371
  focusField(composer.textarea); // Firefox ignores a plain focus() while a fighting frame holds focus
365
372
  ```
@@ -375,6 +382,12 @@ focusField(composer.textarea); // Firefox ignores a plain focus() while a fighti
375
382
  the limits (THREAT_MODEL §7 "The keyboard": on Firefox, which shows your page no press
376
383
  in a frame, a page keeps the keyboard if the pointer came over its frame after the person last
377
384
  typed and after the field got focus; moves between two frames aren't judged).
385
+ - **Served pages in full Chromium:** nest them ("Nested pages" below, P111). A served page's
386
+ frame there is out of process: your page sees no press in it, so a person's click into the
387
+ page's field is taken back. A nested page's shell sees it: a move into the frame is the
388
+ person's if the shell's activation turned on within the last second and you saw no press or key
389
+ of your own since. A second press in the page within 5 s of the last turns nothing on: after the
390
+ person went back to your composer, their next move in is taken back until then, or a Tab.
378
391
 
379
392
  ## 4. Served pages: the host kit
380
393
 
@@ -528,6 +541,47 @@ entry: {
528
541
  })` to run it, and the manual's Files section where a kind serves files. Show a set served: an
529
542
  opaque frame has no origin to serve its files from.
530
543
 
544
+ ### Nested pages: the page below Porthole's shell
545
+
546
+ `nested: true` (P111) on an artifact kind served by the host kit puts the page in a frame of its
547
+ own below Porthole's shell, on the same origin, with an opaque origin of its own. Do it where people
548
+ type beside your displays: in full Chromium (a person's browser, not Playwright's headless shell) a
549
+ served page's frame is out of process, and your page can't see a press in it, so without nesting a
550
+ real click into the page's field is taken back and `comments.open` from a real click is refused
551
+ within 5 s of any input on your page (porthole#53). The page's shell sees it, and tells your page.
552
+
553
+ ```ts
554
+ const displays = defineDisplays({
555
+ page: {
556
+ preset: "artifact",
557
+ // No `served.storage`: a nested page keeps no storage of its own (localStorage lasts the load).
558
+ options: { runtime: "1", capabilities: { annotate: {}, comments: {} }, nested: true },
559
+ },
560
+ });
561
+ ```
562
+
563
+ Nothing else changes on your page: the same `createHost` (or `PortholeFrame`), the same handlers
564
+ and events, the same `frame-src`. The display has one more event, `storage` (`{ used }`, once per
565
+ run: whether the page touched `localStorage` or `sessionStorage`, never what it kept), for you to
566
+ count the pages that would need storage. A nested page's workers come from Blob URLs (a worker from
567
+ a script of its own set is refused: its origin is opaque), which may `importScripts` the set's
568
+ scripts; Chromium refuses a Blob module worker there. Not yet with a nested page: the asset library (`assets`)
569
+ and Porthole's libraries (`egress.libraries`); the config refuses them.
570
+
571
+ What a content origin serves for a nested page (`/server` does all of it; a content Worker of your
572
+ own answers the same, with the helpers `/server` exports: `nestedShellResponse`,
573
+ `NESTED_FILE_HEADERS`, `nestedAncestors`). `<origin>` is the artifact's own,
574
+ `https://<label>.<content domain>`; `<token>` is the access in the path (Porthole's sealed
575
+ session, or a signed token of your own: the shell only needs addresses under the prefix).
576
+
577
+ | Request | Answer |
578
+ | --- | --- |
579
+ | The framed address (a ticket's, a cookie's reload, an entered clean address), a navigation | 200, `text/html`: Porthole's shell, `nestedShellResponse(compiled, { origin, origins: hostOrigins, page: "<origin>/__porthole/f/<token>/<entry>", renew: { url: "<origin>/__porthole/f/<token>/__porthole/renew", expires } })`. Headers: `Content-Security-Policy: default-src 'none'; script-src 'sha256-<its script>'; frame-src <origin>/__porthole/f/; connect-src <origin>/__porthole/f/; base-uri 'none'; form-action 'none'; frame-ancestors <host origins>`; `Cache-Control: no-store`; `Referrer-Policy: no-referrer`; `X-Content-Type-Options: nosniff`; the served `Permissions-Policy`. No content in it. Any other request there: 404. |
580
+ | `<origin>/__porthole/f/<token>/<page>` (the shell's child, or a tab) | The page as served before (the shell's runtime and the page), its plan's `origins` the content origin alone (`[<origin>]`) and its storage `memory`. `Content-Security-Policy: <the page's directives, its files' prefix opened>; sandbox allow-scripts; frame-ancestors <origin> <host origins>` (never `allow-same-origin`). Access from `<token>` alone: no cookie is sent (the page's origin is opaque), and never decide by `Origin` (it is `null`) or `Sec-Fetch-Site` (`cross-site`). |
581
+ | `<origin>/__porthole/f/<token>/<file>` (the page's loads) | As served files are, plus `Cross-Origin-Resource-Policy: cross-origin` and `Access-Control-Allow-Origin: *` (`NESTED_FILE_HEADERS`): the opaque page's images, scripts, modules, fonts and fetches are cross-origin. Every one carries a CSP sandbox, never `allow-same-origin`: a non-page file `default-src 'none'; sandbox`, a script its directives plus `sandbox`, so none opened on a tab of its own (an SVG, an XML file) runs on the shell's origin. |
582
+ | `<origin>/__porthole/f/<token>/__porthole/renew` | Only the shell's own fetch (`Sec-Fetch-Site: same-origin`, not a navigation): `{ "base": "<origin>/__porthole/f/<new token>/", "expires": <epoch ms> }`, `no-store`; anything else 403. The shell renews 5 minutes before `expires` and moves the page to the new base. |
583
+ | A token that ended, under the prefix | Porthole's status page (`401`, reason `session`), `frame-ancestors <origin> <host origins>`: it tells the shell, which tells your page (`outcome` blocked). |
584
+
531
585
  ### The capability runtime: pages that are apps
532
586
 
533
587
  0.7 (P085–P090). A page reaches your services through one global, `porthole.use(name)`, for what
@@ -201,6 +201,20 @@ Access is gated by a one-time ticket exchanged for a scoped cookie. Where the ho
201
201
  holds the page and needs no stable origin, the shell writes it into an opaque
202
202
  frame instead.
203
203
 
204
+ A **nested** page (P111) splits the shell from the page. The address the host frames
205
+ serves Porthole's shell alone: a document with no content, on the content origin. It
206
+ frames the page in a child sandboxed without `allow-same-origin` (an opaque origin) at
207
+ the page's sealed files' address, fetched without a cookie, and passes messages between
208
+ the host and the page:
209
+
210
+ ```
211
+ Host app Shell (content origin) Page (opaque child)
212
+ │ frame src = ticketed URL ──►│ frames the sealed address ───►│ runtime + page
213
+ │◄── the page's messages ──────│◄── postMessage (by source) ───│
214
+ │── the host's messages ──────►│── postMessage ───────────────►│
215
+ │◄── porthole/shell/state ─────│ its own activation, its focus │
216
+ ```
217
+
204
218
  ### URL frame
205
219
 
206
220
  ```
@@ -265,6 +279,15 @@ several displays on one page are in [THREAT_MODEL.md](THREAT_MODEL.md).
265
279
  itself (its size, its errors, an annotation's anchor and where it is) is the
266
280
  content's word even when the shell says it, since they share a realm: the host
267
281
  bounds it and uses it as a UI hint, never as a permission (P053).
282
+ A nested page (P111) is the one place they don't: the shell is a document of its
283
+ own, the page's parent, on another origin than the page's (opaque), so the page
284
+ reaches nothing of the shell's realm. The shell trusts the page's messages by
285
+ `event.source` alone and passes them on unchanged, never in its own namespace
286
+ (`porthole/shell/`); what it says in that namespace is the shell's own word (its
287
+ transient activation, which only a press or key in the page turns on, and whether
288
+ focus is in it), and the host, which knows the frame is nested from its config
289
+ only, uses it to tell the person's gesture from the page's (the focus guard,
290
+ `comments.open`). Everything else the page says is still the content's word.
268
291
 
269
292
  5. **Host's decision ↔ content domain.** Authentication and authorization
270
293
  *policy* are the host's; carrying the host's decision safely onto the content
package/docs/DECISIONS.md CHANGED
@@ -5843,3 +5843,212 @@ that throws gives the "wasn't checked" warning; `admitFiles` with `\ffffff` in a
5843
5843
 
5844
5844
  **Revisit when** a page's own document is ever shown outside the shell (then quirks mode is real),
5845
5845
  or an engine starts counting fixed boxes in what the viewport scrolls.
5846
+
5847
+ ## P111 · 2026-10-28 · A nested page: Porthole's shell at the framed address, the page its opaque child, and the shell's own activation decides the keyboard and `comments.open` · Accepted
5848
+
5849
+ **Context.** P109's focus guard and `comments.open`'s gate ask whether the person, not the page,
5850
+ moved the keyboard into a frame or clicked in it. In full Chromium a cross-site frame is out of
5851
+ process, and the host's page sees nothing of a press in it: measured on Chromium 153 (2026-10-28,
5852
+ not the headless shell Playwright runs by default), no `:active`, no `:hover`, no pointer event past
5853
+ the frame's edge, only its window blurring with its own activation on, which a page's `focus()`
5854
+ after the person typed in the host also gives. So a person's real click into a page's field was
5855
+ taken back every time (the display stopped at the third), and `comments.open` from a real click was
5856
+ refused within 5 s of any input on the host's page (porthole#53). WebKit keeps these frames in
5857
+ process (`:active` holds there) and was right. Nothing in the page's realm can be asked instead:
5858
+ in every mode before this one, the shell's runtime and the page share a document (served, opaque,
5859
+ the MCP proxy), so whatever the shell would report, the page could post from the same window
5860
+ (ARCHITECTURE "Trust boundaries" 4, P053).
5861
+
5862
+ **Decision.** A config may nest its artifact pages (`nested: true`: domain isolation, artifact
5863
+ mode). The address the host frames (a ticket's answer, a cookie's reload, an entered address)
5864
+ answers Porthole's shell alone, a document with no content in it, on the content origin, its script
5865
+ the only one its CSP runs (by hash), framing and fetching only the origin's sealed files' prefix.
5866
+ The shell frames the page in a child `<iframe sandbox="allow-scripts">` at the page's sealed address
5867
+ (P083); the page's answer carries the same sandbox in its CSP, so on a tab of its own it is opaque
5868
+ too. The page is the served page as before (the shell's runtime and its document), but its origin
5869
+ is opaque, its storage the runtime's in-memory stand-in, and it hears its parent, the shell, on the
5870
+ content origin; it never fetches with a cookie. The shell:
5871
+ - passes every message between the host and the page unchanged, the page's trusted by
5872
+ `event.source` alone (its origin is "null"), and drops any the page sends in the shell's own
5873
+ namespace (`porthole/shell/`);
5874
+ - tells the host its own state (`porthole/shell/state`: its transient activation and how long ago
5875
+ it turned on, and whether focus is in it), read each animation frame, on its focus and blur, and
5876
+ before each message of the page's is passed on. Activation goes up to ancestors, never down: a
5877
+ press or key in the page turns the shell's on, and nothing on the host's page does;
5878
+ - renews the page's sealed address (`<base>__porthole/renew`, same-origin, as P083 asks) and gives
5879
+ the page the new one (`porthole/files-renewed`), which the page's own loads can't (an opaque
5880
+ origin's are never same-origin).
5881
+ The host knows a frame is nested from its config only, never from the frame. For such a frame the
5882
+ focus guard's rule is: the person moved focus in if the shell's activation turned on within the
5883
+ last second (`SHELL_GESTURE_MS`) and the host's page had no trusted pointerdown or keydown of its
5884
+ own since; or by Tab, or the host's own move, or (where the engine shows it) a press on the frame
5885
+ element. No pointer-over or host-wide activation cue counts for it. A move the shell hasn't spoken
5886
+ of yet waits for its word (it comes at the shell's next frame, after the host heard the move) at
5887
+ most `SHELL_WAIT_MS` (500 ms), then is taken back. The same signal opens `comments.open`: its
5888
+ gate's "person in this frame" holds while the shell saw that gesture, or focus is in the frame by
5889
+ the person's move. An engine whose shell has no `navigator.userActivation` keeps 0.13's rule. A
5890
+ `storage` event tells the host, once per run, whether the page touched `localStorage` or
5891
+ `sessionStorage` (the page's word; never a key or a value).
5892
+
5893
+ **Threat it re-opens.** (1) A nested page's files are served with
5894
+ `Cross-Origin-Resource-Policy: cross-origin` and `Access-Control-Allow-Origin: *`, where P081 had
5895
+ `same-origin`: an opaque page's own loads are cross-origin. Whoever holds the sealed address could
5896
+ embed or read the files from any page; they could already fetch them with it, and P083 bounds the
5897
+ address (one version, one viewer, an hour on its own). (2) The page's sealed address opens past its
5898
+ hour only through the shell's renewal: P083's grace for a running page's own loads (same-origin
5899
+ only) can't apply, so a module the page loaded keeps an address that ends within the hour (its later
5900
+ imports fail), where P083 served them till the session's end. (3) The page loses its origin's
5901
+ storage (an in-memory stand-in, as opaque frames have). (4) A press in the page within 5 s of the
5902
+ last one turns no activation on: the second move into the frame (after the person went back to the
5903
+ host's page) is taken back until the activation lapses, or they Tab in. Accepted by the CTO.
5904
+
5905
+ **Why.** The shell is a realm the page can't reach, above its frame: the page is a different origin
5906
+ (opaque), so it has nothing of the shell's (DOM, globals, the window the host hears), and it can
5907
+ neither navigate it nor post as it. Its activation is the person's gesture in this page and no other.
5908
+
5909
+ **Rejected.** A shared shell on one host for every artifact (the per-artifact host stays: decided
5910
+ with the CTO); the page's runtime reporting its own gestures (the page's word, in the page's realm);
5911
+ the host's own activation edge (refreshed by the person's typing, so a press in the frame within 5 s
5912
+ of it is invisible); the pointer's last position on the host's page (it stops at the frame's edge,
5913
+ measured); consuming activation to see a new edge (it consumes the whole page's, the host's
5914
+ included).
5915
+
5916
+ **Residual.** Assets (`/_blob/`) and Porthole's vendored libraries aren't served to a nested page
5917
+ yet (the config refuses them). Another page of the set opens in the frame (the shell's `frame-src`
5918
+ is the sealed prefix) without the navigate events a served page's guard uses (opaque documents get
5919
+ none): the shell's CSP is the wall, as `frame-src` is for opaque frames (P033). The host's page gets
5920
+ the keys a person types within the wait for the shell's word on a move it can't judge at once (on a
5921
+ slow machine, up to 500 ms; measured well under a frame's time on Chromium). A trace's snapshots in
5922
+ Playwright are evaluations in each frame, as gestures: the browser cases run untraced.
5923
+
5924
+ **Tested.** `test/nested.test.ts`: the config's bounds; the page's sandbox (scripts only) and a
5925
+ static check that `allow-same-origin` appears in no sandbox Porthole writes or serves but a frame's
5926
+ on an origin of its own, and that every sandbox attribute is written from those lists; the shell's
5927
+ CSP and document; `/server`: the framed address answers the shell, the page at its sealed address
5928
+ without a cookie is sandboxed and hears the shell alone, its files' resource policy and CORS, only
5929
+ the shell renews; the host's rule. `leak/served/nested.spec.ts` on full Chromium (out-of-process
5930
+ frames), the headless shell, WebKit and Firefox, real input only: the page is an opaque origin at its
5931
+ sealed address; a real click into its field keeps the keyboard there; its `focus()` as it loads, on a
5932
+ timer while the person types, right after a click on the host's own button, 1.2, 3 and 4.5 s after
5933
+ the person paused typing in the host's composer, and 700 ms after the person pressed it and went
5934
+ back to the composer, is taken back; a marker's click is heard; `comments.open` from a real click
5935
+ within a second of typing in the host is allowed, and without one refused; a page that says the
5936
+ shell's words to its parent or to the host's window moves nothing; the host hears storage used.
5937
+ Negative controls `shell-namespace` (the shell passes its namespace on) and `shell-host-input` (no
5938
+ quiet host needed) each fail their probe on Chromium, WebKit and Firefox.
5939
+
5940
+ **Revisit when** an engine shows the host's page a press in an out-of-process frame, or a page needs
5941
+ its own storage (then a capability for it, never the content origin's), assets, or libraries.
5942
+
5943
+ **Amended after the CTO's review (porthole#54): a stalled shell.** The shell's "since" is when it
5944
+ saw its activation turn on, not when the press was. Where the page shares the shell's thread
5945
+ (WebKit; Firefox and Chromium where the frames share a process), a page that holds the thread from
5946
+ its own click handler pushes that moment past the person's next press and keys on the host's page,
5947
+ which then pass the "no host input since" check: the page could take the keyboard, or open the
5948
+ composer, after the person went back to the host. Now the shell looks every 50 ms (an interval as
5949
+ well as each animation frame), beats to the host as often (`porthole/shell/beat`), and says in each
5950
+ report how long it went without a look (`gap`). An activation that turns on in a report after the
5951
+ shell went more than `SHELL_STALL_MS` (100 ms) without a look, or the host heard nothing from it
5952
+ for longer, is uncertain: no one's gesture (the focus guard takes the move back, `comments.open` is
5953
+ refused) until it goes off. **Cost:** a page that keeps its thread busy (or a machine that is), in
5954
+ an engine where it shares the thread with the shell, has a person's real click taken for
5955
+ uncertain; their next press once the page is idle, or a Tab, gets in (measured on a machine at load
5956
+ 45: Firefox took back one of two rounds of a real click). Two messages a 50 ms per display. **Tested:**
5957
+ `leak/served/nested.spec.ts` "a shell's activation seen after a stall is no one's gesture until it
5958
+ goes off" (the host's rule, in the browser's own event loop, on every engine), and
5959
+ `leak/served/nested-stall.spec.ts` (the race end to end with real input: the page's handler holds
5960
+ the thread 1.5 s while the person goes back to the composer; on the headless shell it got through
5961
+ without the check, measured; elsewhere Playwright's input waits the stall out, so that case is no
5962
+ control's probe); negative control `shell-stall` (the gap ignored).
5963
+
5964
+ **Amended after the CTO's review (porthole#54): every file sandboxed.** A nested page's files are on
5965
+ its shell's origin, so a file a browser can run as a document, opened on a tab of its own (an SVG
5966
+ or an XML file with a script, "open image in new tab"), must not run there. Every answer below the
5967
+ sealed prefix carries a CSP sandbox, never `allow-same-origin`: a page's `sandbox allow-scripts`
5968
+ (opaque); every other file's `default-src 'none'; sandbox` (opaque, nothing runs: P081's inert CSP);
5969
+ and now a script's too (`sandbox`, where a served script had none). **Tested:**
5970
+ `test/nested.test.ts` (every type in Porthole's table, opened as a tab opens it: a sandbox, never
5971
+ `allow-same-origin`), and `leak/served/nested.spec.ts` "a page's SVG or XML file opened on a tab of
5972
+ its own is an opaque origin…" (each opaque; its script wrote nothing to the shell's origin's
5973
+ storage); negative control `file-sandbox` (a file without its sandbox).
5974
+
5975
+ **Workers in a nested page (the CTO's follow-up #85).** Whether the sandbox on a script's answer
5976
+ refuses a worker, measured on full Chromium, the headless shell, WebKit and Firefox
5977
+ (`leak/served/nested-workers.spec.ts`): it refuses none, every outcome the same with it taken out
5978
+ (the `file-sandbox` control). A worker from a script of the page's own set, classic or module, is
5979
+ refused on every engine, sandbox or not: a worker's script must be its creator's origin, and a
5980
+ nested page's is opaque (Chromium throws `SecurityError`, WebKit and Firefox fire `error`). A worker
5981
+ from a Blob URL starts and answers on every engine, and loads the set's scripts (`importScripts`,
5982
+ CORS-free) and, on WebKit and Firefox, its modules; Chromium refuses a module worker from a Blob URL
5983
+ in an opaque document, one that imports nothing included (no script's answer is involved). So no
5984
+ answer needs its sandbox taken off for a worker, and none is: the narrowest fix (no sandbox on a
5985
+ `Sec-Fetch-Dest: worker` answer) would fix nothing. The agent manual already teaches workers from
5986
+ `blob:` URLs only.
5987
+
5988
+ ## P112 · 2026-10-28 · 0.14's comment UX: what annotations add for a host's comment modes · Accepted
5989
+
5990
+ **Context.** Raft's comment design (its modes A–C, a card that follows its mark, a list in document
5991
+ order, block selection on touch) needs more from `annotate` than 0.13 has. Each addition is the
5992
+ content's word, as every report is (P053): the host uses it as a hint, never as a permission, and
5993
+ takes it only while it asked for it. Each item below landed on its own, with its negative control.
5994
+
5995
+ - **Escape while selecting text** (P4). In text selection mode an Escape is reported as
5996
+ `cancelled`, as it is while picking an element; the key stays the page's (a page that closes its
5997
+ own dialog on Escape still does), and the host decides what ends (a pick ends with it, as
5998
+ before). The host takes `cancelled` only while it asked for a pick or for text: a page can send
5999
+ it, and then only gets the host out of a mode the person can enter again (Raft: mode B ends, its
6000
+ drafts kept). Tested: `leak/annotate.spec.ts` "Escape while selecting text is cancelled…";
6001
+ negative control `cancel-any-mode` (a cancel with no mode on is heard).
6002
+ - **Following a mark** (P1). `annotations.track(id | null)`: while the followed mark moves (a
6003
+ scroll, a layout change), the frame reports `{ type: "tracked", id, rect }` at most once per
6004
+ animation frame. One mark at a time, and only a shown one (`track` throws for another; a `show`
6005
+ without it, or `clear`, stops it). The host takes a `tracked` only for the mark it follows, at
6006
+ most 60 a second, its box clamped to the frame, outside the bridge's 120 reports a minute (which
6007
+ a card that follows its mark would spend in two seconds). It costs a message and a box read per
6008
+ frame, only while the host follows a mark. The box is where to put a card, nothing more: a page
6009
+ can move it within its frame, as it can draw anything there. Tested: `leak/annotate.spec.ts` "a
6010
+ followed mark's box comes as it moves…"; negative control `track-checks` (any mark, any rate).
6011
+ - **A mark's place** (P2). Each attached result in `anchored` carries `order`: its place among the
6012
+ found marks by where it starts in the document, from 0, offscreen marks included (orphans have
6013
+ none); a change of place is reported as a move is. The host takes a whole number below the most
6014
+ marks a show carries, or drops the report. The page knows where its anchors are anyway; the host
6015
+ sorts by it and takes it as nothing more. Tested: `leak/annotate.spec.ts` "every found mark's
6016
+ place in the document…"; negative control `order-check` (any number taken).
6017
+ - **Holding a block** (P3). `start({ text: true, elements: "hold" })`: a finger held still (within
6018
+ 10 px) for 500 ms on a block selects it, reported as `selected` with an element anchor, as a pick
6019
+ is; the click its release makes (and a context menu) never reaches the page. Every other tap, a
6020
+ finger that moved, and any mouse are the page's, so the page stays usable while comments are on;
6021
+ the mode lasts until the host stops it (a pick ends after one). It makes nothing but `selected`,
6022
+ as `elements: true` does; a page can tell a long press happened, as it can tell a selection.
6023
+ Tested: `leak/annotate.spec.ts` "holding a block 500 ms selects it…" (the events as the browser
6024
+ dispatches them, sent in the frame: a page's realm can send them too, and what comes of them is a
6025
+ report, the page's word); negative control `hold-click` (the release's click reaches the page).
6026
+ - **Whether a page may pass a draft on** (P8). `mayPassOn(config, declaration)`, and
6027
+ `host.mayPassOn(declaration)`: true where the page can keep what it is given where others read
6028
+ it, knowing whose it is (`db` and `user`, both declared and offered), or reaches the network
6029
+ beyond the library CDNs (`anyHttps`, or any origin the config or a capability opens for any kind
6030
+ that isn't one of `LIBRARY_CDNS`'s for that kind: a CDN serves published packages by their path,
6031
+ and its logs are its operator's, not the page author's). ADOPTING's "no drafts to a page that can
6032
+ pass them on" as a function a host calls instead of reading the declaration itself. A pure
6033
+ function of the host's own records: `test/pass-on.test.ts` holds each channel alone, and none;
6034
+ there is no browser probe for it to fail.
6035
+ - **A draft-only composer may take focus** (P6). THREAT_MODEL §6 said every view a report opens
6036
+ takes no focus; ADOPTING's keyboard section opened a composer focused on `selected`. Now one
6037
+ rule in both: in a comment mode the person started themselves (the host's own control), a
6038
+ composer their selection opens may take focus with `focusField` if all it can do is save a draft
6039
+ (nothing posts, submits or sends from it), the rest of §6's guard holding; any other view a
6040
+ report opens takes none. What the page gains by choosing that moment is the person's next keys in
6041
+ a draft they see and can discard. As Raft's comment design proposes it (its mode B); Tenny's to
6042
+ confirm.
6043
+ *Amended after the CTO's review (porthole#54):* `db` alone was missed (a page can store the draft
6044
+ where its other readers see it, whoever wrote it), and so were `openLink` (the draft in a URL the
6045
+ person opens) and `artifact` (the draft in a new version). The whole vocabulary now: what carries
6046
+ what the page puts in it to someone other than the person viewing it counts, wherever the page
6047
+ can reach it (the config declares it, and under the runtime with a declaration through a built-in
6048
+ family or one the page declared): `db`, `artifact`, `assets`, `openLink`, `sendPrompt`,
6049
+ `setModelContext`, `callTool`, `readData`, `subscribeData` (their arguments go to the host's data
6050
+ services, which may be someone else's), and `reportError` where errors go to the agent. Not:
6051
+ `copyText` and `downloadFile` (the person's own clipboard and disk), `annotate`, `resize` and
6052
+ `comments` (the host's own UI; the composer is the person's, under the host's duties), and `user`
6053
+ (it only reads). Tested: `test/pass-on.test.ts`, each channel alone.
6054
+
package/docs/DESIGN.md CHANGED
@@ -995,6 +995,7 @@ for that to lapse and click with raw input.
995
995
  | The runtime: a draft is visible text, strictly; the anchor beside it cleaned (P109) | a draft with a joiner (U+200C, U+200D) anywhere but between two letters or marks (first, last, doubled, beside a space or punctuation, in an emoji sequence), a line or paragraph separator, blank-looking text, more than 32 blanks or two blank lines in a row is refused; the label and quote lose what a person can't see, refused if nothing visible is left | `test/runtime.test.ts`: "a draft is visible text, strictly (P109)" | — (unit-tested: the bridge's own check, behind `comment-draft`'s) |
996
996
  | The keyboard: the focus guard (P109) | a move of the keyboard from one of the host page's text fields into a display's frame that the person didn't make (no press on the frame, `:active` on Chromium and WebKit, the pointer coming over it on Firefox; no Tab; no gesture the page's own events don't explain) is undone once the move is over; three while typing within 10 s, or five within 2 s, stop the display | `test/focus-guard.test.ts`; `leak/served/runtime.spec.ts`: "a page that takes the keyboard while the person types in the host's composer…", "a page that takes the keyboard back on its own blur keeps none of it…" (GK-1), "a composer the host focuses with focusField…", "the person's own moves into the frame keep the keyboard…" | `focus-guard` → the first (all three) and the next two (Firefox); `focus-guard-watch` (the watch after a take-back, the look at every frame) → those two (Firefox) |
997
997
  | The runtime: `comments.open` from the frame the person is in (P109) | its `user-activation` gate also needs the host page's focus in the calling frame (`CapabilitySpec.inFrame`, `Surface.focused`), after the focus guard | `leak/served/runtime.spec.ts`: "comments.open while the person types in the host's composer reaches no handler…" | `comments-in-frame` → that case (all three) |
998
+ | A nested page: Porthole's shell above an opaque page (P111) | the framed address answers the shell alone (its own script by hash, framing and fetching only the sealed prefix); the page is its child, `sandbox="allow-scripts"` in the attribute and its CSP (never `allow-same-origin`: a static check over every sandbox Porthole writes), loaded without a cookie; the shell passes messages by `event.source`, never in its own namespace; the host takes a move into the frame, or a `comments.open`, for the person's only if the shell's activation turned on within the last second with no trusted press or key on the host's page since (or a Tab, the host's move, a press the engine shows) | `test/nested.test.ts`; `leak/served/nested.spec.ts` on full Chromium, the headless shell, WebKit and Firefox | `shell-namespace` → "the shell's words are the shell's alone…" (all three); `shell-host-input` → "a page's focus() just after the person pressed it and went back…" (all three) |
998
999
  | The asset library (P089, P091) | `/_blob/<id>` (or the frame's `<sealed base>__porthole/blob/<id>`) for an access to its artifact (a cookie, a sealed `Referer`, the sealed path), then the host's check, the store asked with it; typed by name, never a page, code only where trusted and uploaded code may run (asked at each load; by id alone, every artifact config must, P103), inert CSP, CORP, revalidated; the page's CSP opens `<origin>/_blob/` for images, media, fonts and data, for scripts and styles only where uploads are the admins' | `test/assets.test.ts` (a forged same-origin claim: 401; another artifact's session: 404; revoked: 403; bearer mode; a stricter config turns trusted code into a download, bearer mode too); `leak/served/runtime.spec.ts`: an upload loads in its frame; a set's page loads it; static `/_blob/` in a frame by `Referer` (Chromium, Firefox; WebKit sends only the origin: measured); "a script asset runs as code only if an admin uploaded it"; "scripts load from /_blob/ only where uploads are the admins'"; "an asset reaches only its own artifact's pages"; "an asset opened on its own runs nothing" | `blob-trusted` → the trusted-code case; `blob-script,blob-trusted` (two walls) → that case and the tab's CSP case; `blob-inert` → the opened-on-its-own case (all three; `scripts/controls.ts`) |
999
1000
  | Workers (P044, P045) | no Node module in `/server`; D1 tickets taken by one `DELETE … RETURNING` | `test/workers.test.ts` (workerd, no `nodejs_compat`, real D1: once per ticket, a race, anonymous, a revocation, flat names, reserved namespaces) | — |
1000
1001
 
@@ -1466,6 +1467,14 @@ control the tables above name to the registry):
1466
1467
  | `focus-guard` | `served/runtime.spec.ts` | `a page that takes the keyboard while the person types in the host's composer gets a key or two at most, and is stopped` | Firefox: `a page that takes the keyboard back on its own blur keeps none of it: the composer keeps its words, and comments.open reaches no handler`, `a composer the host focuses with focusField, beside a page with the person's gesture that takes focus back on its blur, gets their words` | — |
1467
1468
  | `focus-guard-watch` | `served/runtime.spec.ts` | nothing | Firefox: `a page that takes the keyboard back on its own blur keeps none of it: the composer keeps its words, and comments.open reaches no handler`, `a composer the host focuses with focusField, beside a page with the person's gesture that takes focus back on its blur, gets their words` | no probe can see it on Chromium and WebKit: they blur the host's window on every move into a frame and a take-back lands, and a page can't take focus back from its own blur there (measured) |
1468
1469
  | `comments-in-frame` | `served/runtime.spec.ts` | `comments.open while the person types in the host's composer reaches no handler, by the page's own call or the shell's; from a press in the frame it does` | — | — |
1470
+ | `cancel-any-mode` | `annotate.spec.ts` | `Escape while selecting text is cancelled, and stays the page's key; with no mode on, a page's own cancel isn't heard (P112)`, `a hostile page fakes reports: the host takes none it didn't ask for, nothing malformed, and not a flood` | — | — |
1471
+ | `track-checks` | `annotate.spec.ts` | `a followed mark's box comes as it moves, for that mark only, at most 60 a second, clamped to the frame, until the host stops (P112)` | — | — |
1472
+ | `order-check` | `annotate.spec.ts` | `every found mark's place in the document comes with its box, offscreen ones too; a place that isn't one is no report (P112)` | — | — |
1473
+ | `hold-click` | `annotate.spec.ts` | `holding a block 500 ms selects it and its release's click never reaches the page; a tap, a moving finger and a mouse are the page's (P112)` | — | — |
1474
+ | `shell-namespace` | `served/nested.spec.ts` | `the shell's words are the shell's alone: a page that says them, to its parent or to the host's window, moves nothing` | — | — |
1475
+ | `file-sandbox` | `served/nested.spec.ts` | `a page's SVG or XML file opened on a tab of its own is an opaque origin, and its script touches nothing of the shell's (P111, after its review)` | — | — |
1476
+ | `shell-stall` | `served/nested.spec.ts` | `a shell's activation seen after a stall is no one's gesture until it goes off (P111, after its review)` | — | — |
1477
+ | `shell-host-input` | `served/nested.spec.ts` | `a page's focus() just after the person pressed it and went back to the host's composer is taken back` | — | — |
1469
1478
  | `comment-draft` | `served/runtime.spec.ts` | `a comment's draft is the host's to check: past the limit, holding what a person can't see, or not text, it opens no composer (P108)` | — | — |
1470
1479
  | `blob-script` | `served/runtime.spec.ts` | nothing | — | an untrusted script asset is served as a download (`blob-script,blob-trusted`) |
1471
1480
  | `blob-trusted` | `served/runtime.spec.ts` | `a script asset runs as code only if an admin uploaded it where uploads are the admins'` | — | — |