@botiverse/porthole 0.12.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 (94) 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/bridge/bridge.d.ts +8 -1
  5. package/dist/bridge/bridge.js +7 -0
  6. package/dist/bridge/unseen.d.ts +8 -0
  7. package/dist/bridge/unseen.js +17 -0
  8. package/dist/check/files.js +14 -10
  9. package/dist/check/lint.js +1 -1
  10. package/dist/check/page-source.js +1 -1
  11. package/dist/check/scroll.d.ts +29 -13
  12. package/dist/check/scroll.js +74 -18
  13. package/dist/compile/policy.d.ts +7 -0
  14. package/dist/compile/policy.js +13 -1
  15. package/dist/config/capabilities.d.ts +16 -3
  16. package/dist/config/capabilities.js +1 -0
  17. package/dist/config/schema.d.ts +11 -0
  18. package/dist/config/validate.js +19 -0
  19. package/dist/conformance/harness-source.js +1 -1
  20. package/dist/displays/displays.js +3 -1
  21. package/dist/guide/limits.js +1 -1
  22. package/dist/guide/runtime.js +1 -1
  23. package/dist/host/create-host.d.ts +2 -0
  24. package/dist/host/create-host.js +100 -3
  25. package/dist/host/pass-on.d.ts +15 -0
  26. package/dist/host/pass-on.js +65 -0
  27. package/dist/host/types.d.ts +37 -0
  28. package/dist/index.d.ts +5 -1
  29. package/dist/index.js +5 -1
  30. package/dist/isolation/types.d.ts +8 -0
  31. package/dist/isolation/types.js +8 -0
  32. package/dist/platform/focus-guard.d.ts +212 -0
  33. package/dist/platform/focus-guard.js +620 -0
  34. package/dist/platform/types.d.ts +25 -0
  35. package/dist/platform/web.js +80 -2
  36. package/dist/presets/presets.d.ts +2 -0
  37. package/dist/presets/presets.js +1 -0
  38. package/dist/react/frame.d.ts +8 -0
  39. package/dist/react/frame.js +4 -0
  40. package/dist/runtime/requests.js +34 -12
  41. package/dist/runtime/types.generated.js +1 -1
  42. package/dist/server/files.js +19 -3
  43. package/dist/server/index.d.ts +1 -0
  44. package/dist/server/index.js +4 -0
  45. package/dist/server/nested.d.ts +37 -0
  46. package/dist/server/nested.js +70 -0
  47. package/dist/server/server.js +57 -7
  48. package/dist/shell/annotate.d.ts +1 -1
  49. package/dist/shell/annotate.js +157 -7
  50. package/dist/shell/frame.d.ts +45 -0
  51. package/dist/shell/frame.js +250 -0
  52. package/dist/shell/plan.js +2 -1
  53. package/dist/shell/runtime.js +49 -14
  54. package/docs/ADOPTING.md +140 -7
  55. package/docs/ARCHITECTURE.md +23 -0
  56. package/docs/DECISIONS.md +564 -5
  57. package/docs/DESIGN.md +18 -2
  58. package/docs/THREAT_MODEL.md +192 -30
  59. package/package.json +1 -1
  60. package/src/annotate/types.ts +28 -3
  61. package/src/annotate/validate.ts +23 -2
  62. package/src/bridge/bridge.ts +17 -1
  63. package/src/bridge/unseen.ts +24 -0
  64. package/src/check/files.ts +14 -10
  65. package/src/check/lint.ts +1 -1
  66. package/src/check/scroll.ts +106 -38
  67. package/src/compile/policy.ts +14 -1
  68. package/src/config/capabilities.ts +16 -3
  69. package/src/config/schema.ts +11 -0
  70. package/src/config/validate.ts +23 -0
  71. package/src/displays/displays.ts +3 -1
  72. package/src/guide/limits.ts +1 -1
  73. package/src/guide/runtime.ts +1 -1
  74. package/src/host/create-host.ts +105 -4
  75. package/src/host/pass-on.ts +73 -0
  76. package/src/host/types.ts +33 -0
  77. package/src/index.ts +5 -1
  78. package/src/isolation/types.ts +12 -0
  79. package/src/platform/focus-guard.ts +815 -0
  80. package/src/platform/types.ts +24 -0
  81. package/src/platform/web.ts +96 -2
  82. package/src/presets/presets.ts +3 -0
  83. package/src/react/frame.tsx +10 -0
  84. package/src/runtime/requests.ts +36 -14
  85. package/src/runtime/types.generated.ts +1 -1
  86. package/src/server/files.ts +19 -3
  87. package/src/server/index.ts +10 -0
  88. package/src/server/nested.ts +86 -0
  89. package/src/server/server.ts +65 -6
  90. package/src/shell/annotate.ts +157 -7
  91. package/src/shell/frame.ts +268 -0
  92. package/src/shell/plan.ts +2 -1
  93. package/src/shell/runtime.ts +49 -14
  94. package/types/runtime/v1/comments.d.ts +8 -4
package/docs/ADOPTING.md CHANGED
@@ -277,21 +277,28 @@ display.on("annotation", (report) => {
277
277
  drawn), so give a draft's id at random like any other; a `kind` other than `"posted"` or
278
278
  `"draft"` throws, as a bad anchor does (React: `onHostError`, kind `"annotations"`). The shell
279
279
  is your content server's: upgrade its Porthole first, or an older shell draws a draft as a
280
- posted mark without a marker.
280
+ posted mark without a marker. The view a draft's `activated` opens is guarded like any (below)
281
+ and puts no "Post", "Submit review" or "Discard" one click away: a page can fake that click on
282
+ the person's own press in the content (P107, P109).
281
283
  - **No drafts to a page that can pass them on**, or accept that it does: a page with the runtime's
282
284
  `db` writes and `user` can store who is drafting where (`user.get()` and the marks it is shown)
283
285
  for its author and other viewers to read before the draft is posted, and tie the posted comment
284
286
  to its author after; origins its config declares for egress (an MCP App's `connectDomains`, an
285
287
  `egress` you opened) can carry the same out. Send
286
288
  drafts only to pages without such a channel (annotations, `copyText`, `openLink` and the like),
287
- 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.
288
294
  - **The content chooses when your view opens and where** (it can post `activated` for a mark you
289
295
  show on the person's own press in the content, under their pointer, P105), so a view that a
290
296
  report opens or moves takes no press of any kind for 500 ms after it appears or moves (no
291
297
  `pointerdown`, `pointerup`, `click` or key: menu triggers act on a press, and menu items click
292
298
  themselves on a release), ignores a press that began before that, opens beside the frame rather
293
- than over `rect` where the layout allows, takes no focus, and has no destructive action (resolve,
294
- delete) one click away. Making it `inert` while it arms does all of the first:
299
+ than over `rect` where the layout allows, takes no focus, and has nothing one click away that
300
+ posts, submits, resolves, deletes or discards. Making it `inert` while it arms does all of the
301
+ first:
295
302
 
296
303
  ```js
297
304
  // Call placed() each time the view appears or moves. For 500 ms it takes nothing (inert: no
@@ -342,6 +349,46 @@ display.on("annotation", (report) => {
342
349
  the person can't see; a quote (`exact`) keeps it, to be found again. Hand either to a model only
343
350
  as the page's words.
344
351
 
352
+ ### The keyboard: what a display can take, and what you get
353
+
354
+ Any display can move the keyboard into its frame (`element.focus()` in the page, with no gesture
355
+ on Chromium and WebKit), and what the person goes on typing in your composer or chat box then goes
356
+ to the page. `createHost` (and so `PortholeView`) guards every display (P109): when focus leaves
357
+ one of your page's text fields (a `<textarea>`, an `<input>` that takes text, a `contenteditable`
358
+ region) for a display's frame without the person's press on the frame or a Tab into it, focus goes
359
+ back to the field, and the display tells you; a display that keeps doing it is stopped.
360
+
361
+ ```js
362
+ display.on("focusTaken", ({ typing }) => toast(typing ? "This page tried to take what you were typing." : "This page tried to take the keyboard."));
363
+ display.on("contentError", ({ message }) => log(message)); // "The content kept taking the keyboard from the page; it was stopped."
364
+ // Moving focus into a display yourself (a "focus the page" shortcut): use the display's own move.
365
+ display.focus(); // not frame.focus(): from a text field, that one is taken for the page's and undone
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().
370
+ import { focusField } from "@botiverse/porthole";
371
+ focusField(composer.textarea); // Firefox ignores a plain focus() while a fighting frame holds focus
372
+ ```
373
+
374
+ - **Free:** the guard, on by default, with no option. A page gets at most the keys typed before
375
+ focus is back (none or one in a sentence, measured on all three engines); three tries while the
376
+ person types (within 10 s), or five within 2 s, stop the display (`reload()` runs it again).
377
+ - **Yours:** don't move focus from a text field into a display with the frame's own `focus()`
378
+ (use `display.focus()`), nor into your composer with the field's own `focus()` where a display
379
+ may hold focus (use `focusField`: on Firefox a page with the person's gesture that takes focus
380
+ back on its blur keeps a plain `focus()` from landing, and gets the keys); with a platform of your own (a native web view), implement `focused`,
381
+ `onFocusTaken` and `focus` on its surface, or a display can read what is typed beside it; know
382
+ the limits (THREAT_MODEL §7 "The keyboard": on Firefox, which shows your page no press
383
+ in a frame, a page keeps the keyboard if the pointer came over its frame after the person last
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.
391
+
345
392
  ## 4. Served pages: the host kit
346
393
 
347
394
  ### Local development
@@ -494,6 +541,47 @@ entry: {
494
541
  })` to run it, and the manual's Files section where a kind serves files. Show a set served: an
495
542
  opaque frame has no origin to serve its files from.
496
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
+
497
585
  ### The capability runtime: pages that are apps
498
586
 
499
587
  0.7 (P085–P090). A page reaches your services through one global, `porthole.use(name)`, for what
@@ -525,9 +613,11 @@ handlers: {
525
613
  db: (args, { viewer, declared, instance, changed, signal }) => myApi.db(instance, viewer, args, declared?.rules, { changed, signal }),
526
614
  artifact: (args, { viewer, instance }) => myApi.artifact(instance, viewer, args), // Refused("conflict") when base moved
527
615
  assets: (args, { viewer, instance }) => myApi.assets(instance, viewer, args),
528
- // true if it opened; a draft (P108) is shown whole and editable, posted only on the person's Send,
529
- // the composer armed for 500 ms (THREAT_MODEL §6)
530
- comments: ({ anchor, draft }) => composer.open(anchor, { draft }),
616
+ // true if it opened. Never over the person's own words or place; a page's draft (P108) shown whole,
617
+ // editable, as the page's suggestion, taking no focus, posted only on the person's Send (below)
618
+ // (inUse: the composer holds the person's own words, or a place they chose)
619
+ comments: ({ anchor, draft }) =>
620
+ composer.inUse() ? false : draft === undefined ? composer.open(anchor) : openPageDraft(composer, anchor, draft),
531
621
  },
532
622
  // 5. The mount: what this version declared, within what the artifact declares now; null for a
533
623
  // page published before 0.7 (required under a runtime). Before rendering: a stored
@@ -538,6 +628,49 @@ if (shown && !shown.ok) return <VersionError problems={shown.problems} />; //
538
628
  <PortholeView display="page" instance={instance} declaration={shown ? shown.declaration : null} />
539
629
  ```
540
630
 
631
+ - **A page's draft in your composer** (P108, P109): `comments.open` reaches your handler only from
632
+ a gesture with the person in that frame (a press in it, a Tab into it; not their typing in your
633
+ UI), but the page still picks the moment (the second click of a double click, a field it asked
634
+ them to type into). So the composer it fills is the person's to act on:
635
+
636
+ ```js
637
+ // A composer the page filled: its words are the page's until the person acts in it.
638
+ function openPageDraft(composer, anchor, draft) {
639
+ // Opens beside the frame, and takes no focus: keys stay where the person was typing, so what
640
+ // they type for the page never lands in a postable comment.
641
+ composer.open(anchor, { text: draft, focus: false }); // where your composer focuses, focusField
642
+ // Armed as THREAT_MODEL §6 says: no press of any kind for 500 ms (guardPresses, § Annotations).
643
+ guardPresses(composer.element).placed();
644
+ // Said by you, outside the frame where the page can't draw, until they edit it: never shown as
645
+ // one of their own drafts.
646
+ composer.setNote("Suggested by this page");
647
+ composer.input.addEventListener("input", () => composer.setNote(null), { once: true });
648
+ // Enter sends only once the person has focused or edited the composer themselves (a press in
649
+ // it, a Tab into it, their typing); until then Send is a click. It opened without focus, and a
650
+ // page can't move focus into your page's fields, so its focus is theirs.
651
+ let theirs = false;
652
+ for (const type of ["pointerdown", "focus", "input"]) {
653
+ composer.input.addEventListener(type, () => (theirs = true), { once: true });
654
+ }
655
+ composer.input.addEventListener("keydown", (event) => {
656
+ if (event.key === "Enter" && !theirs) event.preventDefault();
657
+ });
658
+ return true;
659
+ }
660
+ ```
661
+
662
+ - Never over the person's words: while the composer holds their text, or a place they chose,
663
+ answer `false`, or show the page's words as a separate suggestion that takes no focus; never
664
+ replace, append to or retarget what they wrote.
665
+ - Show the draft whole, as plain text (a comment that renders as markdown hides an HTML comment
666
+ or a link definition from readers but not from an agent: render a page-drafted comment as
667
+ plain text, or show before Send what readers will see); show the anchor's `label` and `quote`
668
+ as isolated text (`<bdi>`, `dir="auto"`). Porthole has already refused a draft with anything
669
+ invisible, a line separator or a run of blanks, and taken what can't be seen out of the label
670
+ and quote.
671
+ - Nothing one click away in it, or in a draft's view, posts, submits or discards; your own list
672
+ of a person's drafts (not the frame's markers, which a page can draw too) is how they find
673
+ theirs.
541
674
  - **Built-ins** (`clipboard`, `links`, `downloads`, `comments`) reach every page whose kind offers
542
675
  them; everything else only a page that declared it. A page with no declaration (one published
543
676
  before 0.7) gets the built-ins through `use` and 0.6's globals as before: give it a declaration
@@ -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