@botiverse/porthole 0.5.1 → 0.7.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 (167) hide show
  1. package/README.md +41 -0
  2. package/dist/bridge/bridge.d.ts +13 -0
  3. package/dist/bridge/bridge.js +208 -13
  4. package/dist/bridge/navigation.d.ts +1 -6
  5. package/dist/bridge/navigation.js +11 -0
  6. package/dist/bridge/refusal.d.ts +5 -1
  7. package/dist/bridge/refusal.js +16 -0
  8. package/dist/bridge/types.d.ts +41 -4
  9. package/dist/check/check.d.ts +19 -3
  10. package/dist/check/check.js +55 -8
  11. package/dist/check/files.d.ts +26 -0
  12. package/dist/check/files.js +307 -0
  13. package/dist/check/instrument.d.ts +3 -0
  14. package/dist/check/lint.js +31 -12
  15. package/dist/check/page-source.js +1 -1
  16. package/dist/check/page.js +14 -0
  17. package/dist/check/tools.d.ts +23 -0
  18. package/dist/check/tools.js +27 -3
  19. package/dist/compile/policy.d.ts +34 -0
  20. package/dist/compile/policy.js +74 -0
  21. package/dist/config/capabilities.d.ts +62 -3
  22. package/dist/config/capabilities.js +20 -0
  23. package/dist/config/schema.d.ts +32 -0
  24. package/dist/config/validate.d.ts +1 -1
  25. package/dist/config/validate.js +74 -5
  26. package/dist/conformance/harness-source.js +1 -1
  27. package/dist/conformance/index.d.ts +1 -0
  28. package/dist/conformance/index.js +2 -0
  29. package/dist/conformance/runtime.d.ts +58 -0
  30. package/dist/conformance/runtime.js +314 -0
  31. package/dist/files/paths.d.ts +99 -0
  32. package/dist/files/paths.js +263 -0
  33. package/dist/files/types.d.ts +24 -0
  34. package/dist/files/types.js +83 -0
  35. package/dist/guide/gates.d.ts +3 -0
  36. package/dist/guide/gates.js +19 -0
  37. package/dist/guide/guide.d.ts +2 -0
  38. package/dist/guide/guide.js +44 -32
  39. package/dist/guide/limits.js +4 -4
  40. package/dist/guide/runtime.d.ts +13 -0
  41. package/dist/guide/runtime.js +202 -0
  42. package/dist/host/create-host.js +45 -0
  43. package/dist/host/locate.js +8 -0
  44. package/dist/host/locator.js +7 -0
  45. package/dist/host/types.d.ts +18 -0
  46. package/dist/index.d.ts +13 -4
  47. package/dist/index.js +16 -3
  48. package/dist/isolation/types.d.ts +8 -0
  49. package/dist/presets/presets.d.ts +6 -0
  50. package/dist/presets/presets.js +1 -0
  51. package/dist/protocol/adapter.d.ts +4 -0
  52. package/dist/protocol/mcp-apps.d.ts +6 -0
  53. package/dist/protocol/mcp-apps.js +6 -0
  54. package/dist/protocol/runtime-calls.d.ts +28 -0
  55. package/dist/protocol/runtime-calls.js +113 -0
  56. package/dist/protocol/shell-adapter.js +52 -3
  57. package/dist/react/dialog.js +31 -0
  58. package/dist/react/frame.d.ts +13 -0
  59. package/dist/react/frame.js +6 -0
  60. package/dist/runtime/contract.d.ts +193 -0
  61. package/dist/runtime/contract.js +216 -0
  62. package/dist/runtime/db.d.ts +153 -0
  63. package/dist/runtime/db.js +398 -0
  64. package/dist/runtime/declaration.d.ts +86 -0
  65. package/dist/runtime/declaration.js +266 -0
  66. package/dist/runtime/levels.d.ts +33 -0
  67. package/dist/runtime/levels.js +41 -0
  68. package/dist/runtime/requests.d.ts +125 -0
  69. package/dist/runtime/requests.js +199 -0
  70. package/dist/runtime/segments.d.ts +8 -0
  71. package/dist/runtime/segments.js +14 -0
  72. package/dist/runtime/types.generated.d.ts +1 -0
  73. package/dist/runtime/types.generated.js +19 -0
  74. package/dist/server/files.d.ts +57 -0
  75. package/dist/server/files.js +338 -0
  76. package/dist/server/host.d.ts +44 -2
  77. package/dist/server/host.js +42 -2
  78. package/dist/server/index.d.ts +5 -2
  79. package/dist/server/index.js +5 -1
  80. package/dist/server/keys.d.ts +8 -0
  81. package/dist/server/keys.js +34 -0
  82. package/dist/server/pseudonym.d.ts +9 -0
  83. package/dist/server/pseudonym.js +20 -0
  84. package/dist/server/server.d.ts +0 -5
  85. package/dist/server/server.js +468 -24
  86. package/dist/server/types.d.ts +118 -5
  87. package/dist/shell/document.d.ts +27 -0
  88. package/dist/shell/document.js +46 -2
  89. package/dist/shell/legacy.d.ts +21 -0
  90. package/dist/shell/legacy.js +63 -0
  91. package/dist/shell/plan.d.ts +17 -1
  92. package/dist/shell/plan.js +13 -2
  93. package/dist/shell/runtime.d.ts +2 -1
  94. package/dist/shell/runtime.js +114 -46
  95. package/dist/shell/use.d.ts +15 -0
  96. package/dist/shell/use.js +235 -0
  97. package/docs/ADOPTING.md +142 -5
  98. package/docs/ARCHITECTURE.md +34 -5
  99. package/docs/DECISIONS.md +716 -7
  100. package/docs/DESIGN.md +97 -3
  101. package/package.json +3 -1
  102. package/src/bridge/bridge.ts +281 -17
  103. package/src/bridge/navigation.ts +12 -0
  104. package/src/bridge/refusal.ts +16 -0
  105. package/src/bridge/types.ts +46 -4
  106. package/src/check/check.ts +100 -14
  107. package/src/check/files.ts +384 -0
  108. package/src/check/instrument.ts +3 -0
  109. package/src/check/lint.ts +33 -12
  110. package/src/check/page.ts +14 -0
  111. package/src/check/tools.ts +52 -3
  112. package/src/compile/policy.ts +92 -0
  113. package/src/config/capabilities.ts +49 -2
  114. package/src/config/schema.ts +32 -0
  115. package/src/config/validate.ts +107 -5
  116. package/src/conformance/index.ts +7 -0
  117. package/src/conformance/runtime.ts +573 -0
  118. package/src/files/paths.ts +323 -0
  119. package/src/files/types.ts +101 -0
  120. package/src/guide/gates.ts +25 -0
  121. package/src/guide/guide.ts +78 -52
  122. package/src/guide/limits.ts +4 -4
  123. package/src/guide/runtime.ts +244 -0
  124. package/src/host/create-host.ts +55 -0
  125. package/src/host/locate.ts +10 -0
  126. package/src/host/locator.ts +11 -0
  127. package/src/host/types.ts +18 -0
  128. package/src/index.ts +121 -0
  129. package/src/isolation/types.ts +8 -0
  130. package/src/presets/presets.ts +7 -0
  131. package/src/protocol/adapter.ts +3 -1
  132. package/src/protocol/mcp-apps.ts +7 -0
  133. package/src/protocol/runtime-calls.ts +138 -0
  134. package/src/protocol/shell-adapter.ts +56 -2
  135. package/src/react/dialog.tsx +33 -0
  136. package/src/react/frame.tsx +19 -0
  137. package/src/runtime/contract.ts +305 -0
  138. package/src/runtime/db.ts +530 -0
  139. package/src/runtime/declaration.ts +378 -0
  140. package/src/runtime/levels.ts +69 -0
  141. package/src/runtime/requests.ts +339 -0
  142. package/src/runtime/segments.ts +17 -0
  143. package/src/runtime/types.generated.ts +19 -0
  144. package/src/server/files.ts +425 -0
  145. package/src/server/host.ts +84 -3
  146. package/src/server/index.ts +22 -0
  147. package/src/server/keys.ts +53 -0
  148. package/src/server/pseudonym.ts +21 -0
  149. package/src/server/server.ts +565 -26
  150. package/src/server/types.ts +124 -4
  151. package/src/shell/document.ts +74 -4
  152. package/src/shell/legacy.ts +64 -0
  153. package/src/shell/plan.ts +37 -3
  154. package/src/shell/runtime.ts +114 -46
  155. package/src/shell/use.ts +235 -0
  156. package/types/runtime/v1/artifact.d.ts +50 -0
  157. package/types/runtime/v1/assets.d.ts +43 -0
  158. package/types/runtime/v1/chat.d.ts +13 -0
  159. package/types/runtime/v1/clipboard.d.ts +14 -0
  160. package/types/runtime/v1/comments.d.ts +24 -0
  161. package/types/runtime/v1/context.d.ts +16 -0
  162. package/types/runtime/v1/data.d.ts +29 -0
  163. package/types/runtime/v1/db.d.ts +110 -0
  164. package/types/runtime/v1/downloads.d.ts +22 -0
  165. package/types/runtime/v1/links.d.ts +13 -0
  166. package/types/runtime/v1/porthole.d.ts +44 -0
  167. package/types/runtime/v1/user.d.ts +19 -0
package/docs/ADOPTING.md CHANGED
@@ -50,10 +50,10 @@ data (fetch, WebSocket). Every preset starts closed, and a kind opens more only
50
50
 
51
51
  | Level | Config (`options`) | What it opens | The risk it re-opens | Typical host | The agent's manual says | Why | Tested by |
52
52
  | --- | --- | --- | --- | --- | --- | --- | --- |
53
- | **Closed** (the default) | nothing to write | Nothing from outside the frame: content runs on what it carries (inline code, `data:` and `blob:` URLs). | None. | Widgets that draw their own SVG and CSS; any host that hasn't decided yet. | `Network: none. Nothing loads from outside` (and `write everything inline`) | [P006](DECISIONS.md#p006--2026-10-11--egress-is-closed-by-default-including-channels-a-frame-csp-doesnt-cover--accepted), [P022](DECISIONS.md#p022--2026-10-11--every-preset-starts-with-egress-closed-library-cdns-are-a-one-line-opt-in--accepted) | probes `1.connect`, `2.resources`, `3.webrtc`, `4.*` (nested frames), `5.*` (navigating out), `8.*` (resource hints), `10.self`; served `served.domain.egress` |
54
- | **Library CDNs** (`LIBRARY_CDNS`, plus script hosts of your own) | `egress: LIBRARY_CDNS`; more script hosts: `egress: { ...LIBRARY_CDNS, script: [...LIBRARY_CDNS.script, "https://cdn.example.com"] }` | Scripts, styles, fonts, images and data from cdnjs, jsDelivr, unpkg and esm.sh; Google Fonts; scripts only from three libraries' own CDNs (Tailwind's Play CDN, jQuery, Plotly). Nothing else. | Code you don't control runs in the frame (a compromised or look-alike package), still inside the sandbox and egress; and a path requested from a CDN is a narrow channel out, read by the CDN's operator. The manual tells agents to pin versions. | Ferry's widgets, Raft Artifacts' pages: agents load Chart.js, ECharts, d3, Mermaid, Tailwind, jQuery, Plotly. | `scripts, styles, fonts, images and data (fetch, WebSocket) from https://cdnjs.cloudflare.com` …, `scripts from https://cdn.tailwindcss.com, https://code.jquery.com, https://cdn.plot.ly` and `pin an exact version` | [P078](DECISIONS.md#p078--2026-10-13--library_cdns-adds-tailwinds-jquerys-and-plotlys-own-cdns-for-scripts-only--accepted), [P022](DECISIONS.md#p022--2026-10-11--every-preset-starts-with-egress-closed-library-cdns-are-a-one-line-opt-in--accepted), [P048](DECISIONS.md#p048--2026-10-11--artifact-pages-reach-library-cdns-only-by-the-hosts-config--accepted) | `leak/cdn.spec.ts` (a CDN library loads only when the config opens it, opaque and served; another origin never; the libraries' own CDNs serve scripts and nothing else); probes `1.connect`, `2.resources` (an allowed origin loads, no other does) |
53
+ | **Closed** (the default) | nothing to write | Nothing from outside the frame: content runs on what it carries (inline code, `data:` and `blob:` URLs). | None. | Widgets that draw their own SVG and CSS; any host that hasn't decided yet. | `Network: none. Nothing loads from outside` (and `write everything inline`) | [P006](DECISIONS.md#p006--2026-10-11--egress-is-closed-by-default-including-channels-a-frame-csp-doesnt-cover--accepted), [P022](DECISIONS.md#p022--2026-10-11--every-preset-starts-with-egress-closed-library-cdns-are-a-one-line-opt-in--accepted-amended-by-p082-p089) | probes `1.connect`, `2.resources`, `3.webrtc`, `4.*` (nested frames), `5.*` (navigating out), `8.*` (resource hints), `10.self`; served `served.domain.egress` |
54
+ | **Library CDNs** (`LIBRARY_CDNS`, plus script hosts of your own) | `egress: LIBRARY_CDNS`; more script hosts: `egress: { ...LIBRARY_CDNS, script: [...LIBRARY_CDNS.script, "https://cdn.example.com"] }` | Scripts, styles, fonts, images and data from cdnjs, jsDelivr, unpkg and esm.sh; Google Fonts; scripts only from three libraries' own CDNs (Tailwind's Play CDN, jQuery, Plotly). Nothing else. | Code you don't control runs in the frame (a compromised or look-alike package), still inside the sandbox and egress; and a path requested from a CDN is a narrow channel out, read by the CDN's operator. The manual tells agents to pin versions. | Ferry's widgets, Raft Artifacts' pages: agents load Chart.js, ECharts, d3, Mermaid, Tailwind, jQuery, Plotly. | `scripts, styles, fonts, images and data (fetch, WebSocket) from https://cdnjs.cloudflare.com` …, `scripts from https://cdn.tailwindcss.com, https://code.jquery.com, https://cdn.plot.ly` and `pin an exact version` | [P078](DECISIONS.md#p078--2026-10-13--library_cdns-adds-tailwinds-jquerys-and-plotlys-own-cdns-for-scripts-only--accepted), [P022](DECISIONS.md#p022--2026-10-11--every-preset-starts-with-egress-closed-library-cdns-are-a-one-line-opt-in--accepted-amended-by-p082-p089), [P048](DECISIONS.md#p048--2026-10-11--artifact-pages-reach-library-cdns-only-by-the-hosts-config--accepted) | `leak/cdn.spec.ts` (a CDN library loads only when the config opens it, opaque and served; another origin never; the libraries' own CDNs serve scripts and nothing else); probes `1.connect`, `2.resources` (an allowed origin loads, no other does) |
55
55
  | **Passive from any https site** (`anyHttps`, on top of either) | `egress: { ...LIBRARY_CDNS, anyHttps: ["img"] }`; closed but for them: `egress: { anyHttps: ["img"] }` | The passive kinds you name (`img`, `media`, `font`) from any https site. Never scripts, styles, data, workers or frames, and never `http:`: a config naming another kind is refused. | Any site an image names learns that someone viewed the content, and from which address; content can send data out in an image URL to a server of its choosing (the channel P006 closes); whoever owns an image controls what it shows, inside the frame. | A host showing content that already exists, with hotlinked media: Raft's HTML attachment previews, reports whose `<img>` point at other sites (the case P059 was written for). | `images from any https site` (`fonts, images, audio and video from any https site` for all three) | [P059](DECISIONS.md#p059--2026-10-11--passive-content-may-load-from-any-https-site-by-the-hosts-explicit-choice--accepted), [P062](DECISIONS.md#p062--2026-10-11--serveddomainegress-holds-a-host-to-its-own-configs-egress--accepted) | `leak/cdn.spec.ts` (a hotlinked image loads; a script, a stylesheet and a fetch to the same site never reach it; without the flag, nothing does); served `served.domain.egress` (the image must reach an https canary; scripts, styles, fetches and frames never), `leak/served/any-https.spec.ts` |
56
- | **Porthole's libraries** (`egress.libraries`, served kinds only; on in `presets.liveWidget`) | `egress: { libraries: true }` with `isolation: "domain"` | Chart.js 4.5.1 and D3 7.9.0 as scripts, from the frame's own origin (`/__porthole/lib/…`, served by `/server` on every content origin). Nothing from outside. | None from outside: the requests reach your content server, which serves fixed, pinned files. | Live widgets, which read your data and must have no network of their own (P079). | `Libraries, served from this frame's own address` with a `<script>` line for each | [P079](DECISIONS.md#p079--2026-10-15--live-widgets-no-network-of-their-own-portholes-libraries-on-their-origin-the-hosts-data-behind-the-viewers-consent-and-frames-that-never-navigate-away--accepted) | `test/libraries.test.ts`; `leak/served/live.spec.ts` (they load and draw; an external script, a stylesheet, an image and every fetch reach no oracle) |
56
+ | **Porthole's libraries** (`egress.libraries`, served kinds only; on in `presets.liveWidget`) | `egress: { libraries: true }` with `isolation: "domain"` | Chart.js 4.5.1 and D3 7.9.0 as scripts, from the frame's own origin (`/__porthole/lib/…`, served by `/server` on every content origin). Nothing from outside. | None from outside: the requests reach your content server, which serves fixed, pinned files. | Live widgets, which read your data and must have no network of their own (P079). | `Libraries, served from this frame's own address` with a `<script>` line for each | [P079](DECISIONS.md#p079--2026-10-15--live-widgets-no-network-of-their-own-portholes-libraries-on-their-origin-the-hosts-data-behind-the-viewers-consent-and-frames-that-never-navigate-away--accepted-amended-by-p084) | `test/libraries.test.ts`; `leak/served/live.spec.ts` (they load and draw; an external script, a stylesheet, an image and every fetch reach no oracle) |
57
57
 
58
58
  How to decide: **start closed; add `LIBRARY_CDNS` if agents use libraries; add passive `anyHttps`
59
59
  only for existing content with hotlinks**, and only the kinds it hotlinks (usually `img`). An
@@ -89,7 +89,7 @@ export const displays = defineDisplays({
89
89
  ### Live widgets: content that reads your data
90
90
 
91
91
  A live widget shows your data, current, read as the person viewing it, with no network of its own
92
- ([P079](DECISIONS.md#p079--2026-10-15--live-widgets-no-network-of-their-own-portholes-libraries-on-their-origin-the-hosts-data-behind-the-viewers-consent-and-frames-that-never-navigate-away--accepted)).
92
+ ([P079](DECISIONS.md#p079--2026-10-15--live-widgets-no-network-of-their-own-portholes-libraries-on-their-origin-the-hosts-data-behind-the-viewers-consent-and-frames-that-never-navigate-away--accepted-amended-by-p084)).
93
93
  Its only way out is your host: `readData` (MCP `resources/read`) and `subscribeData` (MCP
94
94
  `resources/subscribe`, `resources/unsubscribe`, `notifications/resources/updated`).
95
95
 
@@ -272,6 +272,142 @@ nodeServer({ content, app: async (request) => (await routes(request)) ?? app(req
272
272
  - **Health:** `health: { probe: nodeProbe(), onServedChange: (served) => … }` checks the content
273
273
  domain over the real network and falls back to opaque frames while it doesn't answer.
274
274
 
275
+ ### Pages made of many files
276
+
277
+ A stored version may be a set of files (a build's output, a report with its images; P081). The
278
+ store answers a manifest and the bytes by path; `{ html }` stays one page:
279
+
280
+ ```js
281
+ import { checkFileSet, fileLimits, versionBase, versionedAddress } from "@botiverse/porthole/server";
282
+
283
+ // When a version is published: every path canonical, within your page kind's limits.
284
+ const problems = checkFileSet(manifest, { limits: fileLimits(pageConfig.limits) }); // [] to take it
285
+
286
+ source: async (id, version) => {
287
+ const stored = await myStore.version(id, version); // { files: { path: { size, sha256 } }, entry? }
288
+ return stored.html !== undefined
289
+ ? { html: stored.html }
290
+ : { files: stored.files, entry: stored.entry, spa: stored.spa, read: (path) => myStore.bytes(stored.files[path].sha256) };
291
+ },
292
+ entry: {
293
+ // "/" and "/<file>" are the latest, "/v/<n>/<file>" version n: answer the version's own address.
294
+ at: async (scope, path) => {
295
+ const at = versionedAddress(path);
296
+ const version = at === null ? null : (at.version ?? (await latestOf(scope)));
297
+ return version === null ? null : { instance: pageOf(scope, version), base: versionBase(version), file: at.file, pinned: true };
298
+ },
299
+ pathOf: (instance) => versionBase(instance.document.version),
300
+ },
301
+ ```
302
+
303
+ - **Each file is served from the manifest only**, typed by its extension (Porthole's table, never
304
+ the type it was published with), `nosniff`, with a CSP that opens the version's own path and
305
+ nothing else of the origin (P082). Files are immutable at a version's address; pages revalidate
306
+ (the host's check runs on every load). `read` returns the whole file (`Uint8Array` or a
307
+ stream); Porthole cuts ranges.
308
+ - **A page never mixes versions.** The latest's address (`/`, `/style.css`) goes to the version's
309
+ own (`/v/3/`, `/v/3/style.css`) before the page loads anything, so a version published while it
310
+ loads never reaches it. Answer `entry.at` with the version's `base`, and `pinned: true` when that
311
+ base names one version only (its files are then immutable); a plain instance is served at a
312
+ frame's address instead. A base's segments are letters, digits and `. _ : ~ -`.
313
+ - **An artifact's versions share an origin**, so they are one trust domain (P082): give versions
314
+ that must stay apart scopes of their own.
315
+ - **Each version is a directory of its origin** (`/v/<n>/`). `/_blob/` (`ASSET_LIBRARY_PATH`) is
316
+ the asset library's, across versions (0.7, below); `versionedAddress` names nothing there.
317
+ - **In a frame**, the files' address carries the frame's access (WebKit keeps no cookie there,
318
+ P083): the frame's URL is `/__porthole/f/<sealed>/`, good for the session. A host's
319
+ `issue` and its locator don't change.
320
+ - **Every page of the set is in the shell**, and a set's pages open each other in the frame (P084).
321
+ Service workers never register.
322
+ - **The agent's side:** `lintFiles` and `admitFiles` before you take a version, `checkPage({ files
323
+ })` to run it, and the manual's Files section where a kind serves files. Show a set served: an
324
+ opaque frame has no origin to serve its files from.
325
+
326
+ ### The capability runtime: pages that are apps
327
+
328
+ 0.7 (P085–P090). A page reaches your services through one global, `porthole.use(name)`, for what
329
+ it declared when it was published and what its viewer's level allows. Porthole carries, checks
330
+ and gates the calls; you keep the services.
331
+
332
+ ```js
333
+ import { declareCapabilities, presets } from "@botiverse/porthole";
334
+
335
+ // 1. The kind's config offers the runtime and the host functions behind it.
336
+ const page = presets.artifact({
337
+ isolation: "domain", contentOrigins: [source], runtime: "1",
338
+ capabilities: { copyText: {}, openLink: {}, comments: {}, user: {}, artifact: {}, assets: {}, db: {} },
339
+ });
340
+
341
+ // 2. At publish: the artifact's declaration (omitted: carried forward; {}: cleared; an object: replaced).
342
+ const declared = declareCapabilities({ stored: artifact.declaration, given: body.capabilities, config: page });
343
+ if (!declared.ok) return problems(declared.problems); // [{ path: "capabilities.db.rules", message }]
344
+ await myStore.saveDeclaration(artifact.id, declared.declaration); // { capabilities, runtime: "1" }
345
+
346
+ // 3. The viewer's level, in your access (the issue's answer carries it to the display's bridge).
347
+ access: async (instance, viewer) =>
348
+ viewer && { viewer: viewer.id, level: await levelOf(viewer, instance), user: { id: viewer.publicId, name: viewer.name } },
349
+
350
+ // 4. Your services, as handlers (the page's calls arrive checked: declared, shaped, at level).
351
+ handlers: {
352
+ db: (args, { viewer, declared, instance, changed, signal }) => myApi.db(instance, viewer, args, declared?.rules, { changed, signal }),
353
+ artifact: (args, { viewer, instance }) => myApi.artifact(instance, viewer, args), // Refused("conflict") when base moved
354
+ assets: (args, { viewer, instance }) => myApi.assets(instance, viewer, args),
355
+ comments: ({ anchor }) => composer.open(anchor), // true if it opened
356
+ },
357
+ // 5. The mount: what this version declared, within what the artifact declares now; null for a
358
+ // page published before 0.7 (required under a runtime).
359
+ <PortholeView display="page" instance={instance}
360
+ declaration={version.declaration ? intersectDeclarations(version.declaration, artifact.declaration) : null} />
361
+ ```
362
+
363
+ - **Built-ins** (`clipboard`, `links`, `downloads`, `comments`) reach every page whose kind offers
364
+ them; everything else only a page that declared it. A page with no declaration (one published
365
+ before 0.7) gets the built-ins through `use` and 0.6's globals as before: give it a declaration
366
+ when it is next published.
367
+ - **Levels**: `view < interact < admin < owner`. Reads are `view`; `chat.send`, `data.call`,
368
+ `context.set` and db writes `interact`; `artifact.publish` and asset removal `admin`; uploads
369
+ `admin` unless you set `assets: { levels: { upload: "interact" } }` (then scripts and styles from
370
+ the library never run: P089). Raise any method in its config's `levels`. Without a viewer the
371
+ runtime's own are refused.
372
+ - **Your API is the wall.** The bridge refuses early, in your page; your handlers call your API as
373
+ the viewer, and it must check again, from its own session and its own stored declaration: never
374
+ trust `context.viewer` or `context.declared` for what your data allows (a page past the bridge
375
+ could forge them). `dbAccess(request, viewer, rules)` is the db rule set (another person's
376
+ `data/users/<id>` refused, `me` resolved), `atLeast(level, "admin")` for a publish. Hold every
377
+ write to an existing document to its `ifVersion` (updates and deletes too), apply a batch in
378
+ order against one state, and refuse a moved base or version with `new Refused("conflict")`;
379
+ check and admit the merged version as any (`checkFileSet`, `admitFiles`).
380
+ - **Per version**: store each version's declaration with it (`declareCapabilities` at its publish)
381
+ and mount a version with `intersectDeclarations(version's, current)`.
382
+ - **Who the page may know**: `Grant.user.id` is one path segment, never `me`; give
383
+ `pseudonymFor(secret, artifact, person)` where pages shouldn't link a person across artifacts.
384
+ - **Assets**: `createContentHost({ assets: (id, access) => myStore.asset(id, access) })` answers
385
+ `{ scope, artifact, name, size, sha256, trusted?, read }` for an id you made (32 random hex
386
+ characters, `ASSET_ID`); `/server` serves it at `/_blob/<id>` on that scope's origin only, to an
387
+ access for that artifact (a session, or a framed page's sealed address), after your check,
388
+ revalidated at each load. Store an upload's `trusted` (the bridge sets it: an admin's code where
389
+ uploaded code may run) and give it back: other code-typed assets are served as downloads. Pages
390
+ show assets with `assets.url(id)` (some engines' frames send no address a `/_blob/` load could
391
+ carry). `{ get, bearer: true }` serves by id alone, an explicit opt-in for public artifacts.
392
+ Refuse names that aren't assets (`assetNameProblem`).
393
+ - **Run the conformance cases** against your handlers (no browser):
394
+
395
+ ```js
396
+ import { defineRuntimeConformance } from "@botiverse/porthole/conformance";
397
+ for (const each of defineRuntimeConformance({
398
+ config: page, viewers, handlers: () => freshArtifactHandlers(), assets: () => assetStore,
399
+ // Your own API for the same artifact, signed in as `viewer` with that person's real session:
400
+ // the cases past the bridge then forge the context, as a page past it could.
401
+ api: (handlers, viewer) => apiAs(handlers, viewer),
402
+ })) {
403
+ test(each.name, () => each.run());
404
+ }
405
+ ```
406
+
407
+ - **The agent** declares capabilities in your publish tool (`capabilities: { db: {} }`) and reads
408
+ topic `capabilities` of the manual: declaring, levels, errors, where state goes, each one's types
409
+ (`types/runtime/v1/*.d.ts`, also in the package for a page's own TypeScript).
410
+
275
411
  ### The page
276
412
 
277
413
  ```js
@@ -569,11 +705,12 @@ prints each reason at the end; so does `--reporter=json`.
569
705
  | Import | What |
570
706
  | --- | --- |
571
707
  | `@botiverse/porthole` | `createHost`, `presets`, `defineDisplays`, `portholeClient`, `frameFallback`, `entryTarget`, `lintContent`, `admitContent`, `showTool`, `guideTool`, `checkTool`, `answerGuide`, `guideChanges`, `compile` |
708
+ | `@botiverse/porthole` (the runtime, 0.7) | `declareCapabilities`, `declarationProblems`, `checkDeclaration`, `dbAccess`, `atLeast`, `methodLevel`, `rosterOf`, `assetNameProblem`, `RUNTIME_CAPABILITIES`, `RUNTIME_TYPES`, `Refused` (`conflict`, `forbidden`, `too_large`); `types/runtime/v1/*.d.ts` |
572
709
  | `@botiverse/porthole/react` | `PortholeProvider`, `PortholeFrame`, `PortholeView`, `usePortholeLink`, `cssVariableTheme`, `useRunAgain` |
573
710
  | `@botiverse/porthole/server` | `createContentHost` (`routes`, `forget`), `contentHostFor`, `prefixedName`, `memoryTicketStore`, `d1TicketStore`, `upstreamHeaders`, `statusPage`, `conformancePage`, the callbacks' types |
574
711
  | `@botiverse/porthole/node` | `nodeServer`, `nodeHost`, `nodeProbe`, `toRequest`, `sendResponse` |
575
712
  | `@botiverse/porthole/check` | `checkPage`, `playwrightDriver`, `cdpDriver` (`CHECK_ORIGIN`, `CHECK_CONTENT_DOMAIN`: the names a driver of your own answers); `/check/page`, the check page's script (`checkPage` has it already) |
576
713
  | `@botiverse/porthole/mcp` | the MCP Apps adapter (views, the sandbox proxy) |
577
- | `@botiverse/porthole/conformance` | `defineHostConformance`, `conformanceProjects`, `onDemand`, `conformancePage`; `/conformance/reporter`, skip reasons |
714
+ | `@botiverse/porthole/conformance` | `defineHostConformance`, `conformanceProjects`, `onDemand`, `conformancePage`, `defineRuntimeConformance` (no browser); `/conformance/reporter`, skip reasons |
578
715
 
579
716
  The types' doc comments are the precise reference; DESIGN.md § "The host kit" is the long form.
@@ -16,6 +16,13 @@ Porthole renders **agent-drawn HTML plus a declared set of host functions.**
16
16
  needs** (origins it must reach), and its **guide entry** (how the manual
17
17
  describes it).
18
18
 
19
+ A page published as an artifact may be an app: under the **capability runtime** it reaches its
20
+ host through one global, `porthole.use(name)`, for the capabilities it declared and its viewer's
21
+ level allows. The runtime is how content reaches host functions, not new ones: each of its
22
+ methods is served by a host function the config declares, and the bridge alone decides each call
23
+ (the page's declaration, the viewer's level, the gates). The services behind them (a document
24
+ store, an asset library, versions, comments) are the host's.
25
+
19
26
  One capability list therefore drives three artifacts: the **bridge** (which
20
27
  functions the shell wires and the host handles), the **CSP** (what the sandbox
21
28
  may reach), and the **manual** (what the agent is told). This is why the config
@@ -84,7 +91,10 @@ Pure mechanism, no product policy, no host or vendor types.
84
91
  comes from the theme variables, never from a component vocabulary (P015).
85
92
  - **Serving.** For served modes, a request handler a host's backend mounts: it
86
93
  serves documents on their own origins with their CSP in headers, and turns a
87
- one-time ticket the host minted into a cookie of that origin only.
94
+ one-time ticket the host minted into a cookie of that origin only. A stored
95
+ version may be one page or a set of files: each file is looked up in the
96
+ version's manifest only, typed by Porthole's own table, and served under that
97
+ version's own address, so a page's relative addresses are its version's.
88
98
 
89
99
  ### Preset policy layer
90
100
 
@@ -179,6 +189,10 @@ transparent to the view and the host.
179
189
  The content is served as a real document at a URL on a separate registrable
180
190
  domain with its CSP in HTTP headers; the host embeds that URL in a frame whose
181
191
  `frame-ancestors` names the host. No code injection, and the shell is optional.
192
+ A page may come with files of its own (stylesheets, scripts, data, images, other
193
+ pages): they are served beside it, under its version's own address, and its CSP
194
+ opens that path and nothing else of its origin; every page of the set gets the
195
+ shell.
182
196
  Access is gated by a one-time ticket exchanged for a scoped cookie. Where the host
183
197
  holds the page and needs no stable origin, the shell writes it into an opaque
184
198
  frame instead.
@@ -208,7 +222,10 @@ only the declared content origins.
208
222
  says so.
209
223
 
210
224
  2. **Content ↔ the outside network.** Closed by default and opened only to the
211
- origins the config's capabilities declare. Two kinds of attacker matter:
225
+ origins the config's capabilities declare (and, for a served page with files,
226
+ its own version's path on its own origin, and its artifact's asset library at `/_blob/`: the
227
+ host's own server, P082, P089). Two
228
+ kinds of attacker matter:
212
229
  - *Attacking the host* (steal credentials, read other data, escape the
213
230
  sandbox): stopped by origin isolation — the content is a stranger to the
214
231
  host origin.
@@ -225,14 +242,21 @@ only the declared content origins.
225
242
  closed than its config says: an origin the config opens stays shut. On such
226
243
  a page prefer domain mode, whose frames inherit nothing (P058).
227
244
 
228
- 3. **Message boundary.** Every message crossing the frame is validated against a
245
+ 3. **Host's decision ↔ what a page may do.** Under the capability runtime a page reaches only the
246
+ built-ins and what it declared at publish (stored by the host, given to the mount), and each
247
+ method only for viewers at its level (`view < interact < admin < owner`), which the host's
248
+ access says. The bridge refuses before any handler; the host's own API checks again, since it
249
+ is its data's wall. A person's per-user data is reached by the host's id for them, never the
250
+ content's word.
251
+
252
+ 4. **Message boundary.** Every message crossing the frame is validated against a
229
253
  schema and checked for sender identity before use; the shell accepts messages
230
254
  only from its host, and the host only from its frame. What the frame says about
231
255
  itself (its size, its errors, an annotation's anchor and where it is) is the
232
256
  content's word even when the shell says it, since they share a realm: the host
233
257
  bounds it and uses it as a UI hint, never as a permission (P053).
234
258
 
235
- 4. **Host's decision ↔ content domain.** Authentication and authorization
259
+ 5. **Host's decision ↔ content domain.** Authentication and authorization
236
260
  *policy* are the host's; carrying the host's decision safely onto the content
237
261
  domain is Porthole's *mechanism*. The host decides who may open an instance
238
262
  before it calls `issue` (a viewer it knows, or a public link), and may decide
@@ -253,13 +277,18 @@ only the declared content origins.
253
277
  names are the default vocabulary.
254
278
  - **The person's clipboard** is the host's alone: content asks for a copy
255
279
  (`copyText`), the host performs it and shows what it copied (P051, P052).
280
+ - **The capability runtime** (`config.runtime`): a contract version's capabilities, each a
281
+ namespace of methods over host functions, with a versioned `.d.ts`; a host offers them through
282
+ its config and serves them through its handlers; an artifact's asset library is served by
283
+ `/server` from the host's store at `/_blob/<id>` on the artifact's origin.
256
284
  - **Annotations** (`annotate`): the host drives a select mode and marks anchors in
257
285
  the shell; anchors are W3C Web Annotation selectors a host stores with its own
258
286
  comments (P053).
259
287
  - **Served content.** A host plugs its own policy and infrastructure into `/server`:
260
288
  who may see what (`authorize`), where tickets live (`TicketStore`: memory, D1),
261
289
  how origins are named (`content.name`, other servers' `reserved` namespaces),
262
- and where apps and artifact versions come from (`upstream`, `artifacts`). It runs
290
+ and where apps and artifact versions come from (`upstream`, `artifacts`: a page, or a
291
+ manifest of files and their bytes), and which address means which version (`entry.at`). It runs
263
292
  on any runtime with web-standard `Request`/`Response` (Node, Workers).
264
293
 
265
294
  ## How a new protocol or platform plugs in