@botiverse/porthole 0.6.0 → 0.8.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 (208) hide show
  1. package/README.md +25 -2
  2. package/THIRD_PARTY_NOTICES.md +421 -0
  3. package/dist/bridge/bounded-text.d.ts +34 -0
  4. package/dist/bridge/bounded-text.js +188 -0
  5. package/dist/bridge/bridge.d.ts +38 -5
  6. package/dist/bridge/bridge.js +469 -39
  7. package/dist/bridge/json-data.d.ts +28 -0
  8. package/dist/bridge/json-data.js +86 -0
  9. package/dist/bridge/navigation.d.ts +5 -0
  10. package/dist/bridge/navigation.js +7 -0
  11. package/dist/bridge/refusal.d.ts +5 -1
  12. package/dist/bridge/refusal.js +17 -0
  13. package/dist/bridge/types.d.ts +73 -5
  14. package/dist/check/check.d.ts +7 -0
  15. package/dist/check/check.js +1 -0
  16. package/dist/check/instrument.d.ts +3 -0
  17. package/dist/check/lint.js +4 -2
  18. package/dist/check/page-source.js +1 -1
  19. package/dist/check/page.js +16 -0
  20. package/dist/check/tools.js +2 -3
  21. package/dist/compile/compile.d.ts +6 -0
  22. package/dist/compile/compile.js +3 -1
  23. package/dist/compile/policy.d.ts +55 -0
  24. package/dist/compile/policy.js +157 -0
  25. package/dist/config/capabilities.d.ts +85 -7
  26. package/dist/config/capabilities.js +32 -2
  27. package/dist/config/schema.d.ts +35 -0
  28. package/dist/config/validate.d.ts +9 -3
  29. package/dist/config/validate.js +92 -8
  30. package/dist/config/warnings.d.ts +20 -0
  31. package/dist/config/warnings.js +25 -0
  32. package/dist/conformance/behavior.js +46 -1
  33. package/dist/conformance/cookies.d.ts +15 -0
  34. package/dist/conformance/cookies.js +80 -0
  35. package/dist/conformance/harness/page.d.ts +1 -0
  36. package/dist/conformance/harness/page.js +9 -2
  37. package/dist/conformance/harness-source.js +1 -1
  38. package/dist/conformance/host-kit.js +5 -1
  39. package/dist/conformance/index.d.ts +11 -0
  40. package/dist/conformance/index.js +2 -0
  41. package/dist/conformance/limits.js +38 -1
  42. package/dist/conformance/runtime.d.ts +58 -0
  43. package/dist/conformance/runtime.js +324 -0
  44. package/dist/conformance/served.d.ts +2 -0
  45. package/dist/conformance/served.js +737 -4
  46. package/dist/files/paths.js +4 -0
  47. package/dist/guide/gates.d.ts +9 -0
  48. package/dist/guide/gates.js +31 -0
  49. package/dist/guide/guide.d.ts +2 -0
  50. package/dist/guide/guide.js +35 -33
  51. package/dist/guide/limits.js +4 -4
  52. package/dist/guide/runtime.d.ts +13 -0
  53. package/dist/guide/runtime.js +210 -0
  54. package/dist/host/create-host.js +73 -37
  55. package/dist/host/locate.js +8 -0
  56. package/dist/host/locator.js +7 -0
  57. package/dist/host/pages-of-set.d.ts +43 -0
  58. package/dist/host/pages-of-set.js +196 -0
  59. package/dist/host/types.d.ts +26 -1
  60. package/dist/index.d.ts +11 -4
  61. package/dist/index.js +11 -2
  62. package/dist/isolation/types.d.ts +8 -0
  63. package/dist/mcp/adapter.js +11 -15
  64. package/dist/node/index.d.ts +36 -4
  65. package/dist/node/index.js +402 -101
  66. package/dist/presets/presets.d.ts +22 -8
  67. package/dist/presets/presets.js +40 -8
  68. package/dist/protocol/live-data.d.ts +6 -2
  69. package/dist/protocol/live-data.js +20 -1
  70. package/dist/protocol/mcp-apps.d.ts +13 -2
  71. package/dist/protocol/mcp-apps.js +10 -2
  72. package/dist/protocol/message-text.d.ts +8 -0
  73. package/dist/protocol/message-text.js +29 -0
  74. package/dist/protocol/runtime-calls.d.ts +28 -0
  75. package/dist/protocol/runtime-calls.js +116 -0
  76. package/dist/protocol/shell-adapter.js +64 -25
  77. package/dist/react/context-notice.d.ts +32 -0
  78. package/dist/react/context-notice.js +28 -0
  79. package/dist/react/dialog.js +91 -16
  80. package/dist/react/frame.d.ts +25 -1
  81. package/dist/react/frame.js +85 -2
  82. package/dist/react/index.d.ts +2 -1
  83. package/dist/react/index.js +2 -1
  84. package/dist/runtime/contract.d.ts +201 -0
  85. package/dist/runtime/contract.js +245 -0
  86. package/dist/runtime/db.d.ts +188 -0
  87. package/dist/runtime/db.js +502 -0
  88. package/dist/runtime/declaration.d.ts +100 -0
  89. package/dist/runtime/declaration.js +363 -0
  90. package/dist/runtime/levels.d.ts +33 -0
  91. package/dist/runtime/levels.js +41 -0
  92. package/dist/runtime/requests.d.ts +125 -0
  93. package/dist/runtime/requests.js +215 -0
  94. package/dist/runtime/segments.d.ts +8 -0
  95. package/dist/runtime/segments.js +14 -0
  96. package/dist/runtime/types.generated.d.ts +1 -0
  97. package/dist/runtime/types.generated.js +19 -0
  98. package/dist/server/files.d.ts +19 -1
  99. package/dist/server/files.js +115 -6
  100. package/dist/server/host.d.ts +24 -2
  101. package/dist/server/host.js +137 -2
  102. package/dist/server/index.d.ts +3 -2
  103. package/dist/server/index.js +2 -1
  104. package/dist/server/peer.d.ts +4 -0
  105. package/dist/server/peer.js +19 -0
  106. package/dist/server/proxy.d.ts +6 -0
  107. package/dist/server/proxy.js +12 -3
  108. package/dist/server/pseudonym.d.ts +9 -0
  109. package/dist/server/pseudonym.js +20 -0
  110. package/dist/server/server.d.ts +0 -5
  111. package/dist/server/server.js +318 -52
  112. package/dist/server/types.d.ts +74 -2
  113. package/dist/shell/document.d.ts +16 -0
  114. package/dist/shell/document.js +19 -2
  115. package/dist/shell/legacy.d.ts +21 -0
  116. package/dist/shell/legacy.js +63 -0
  117. package/dist/shell/plan.d.ts +17 -1
  118. package/dist/shell/plan.js +13 -2
  119. package/dist/shell/runtime.js +390 -56
  120. package/dist/shell/use.d.ts +15 -0
  121. package/dist/shell/use.js +235 -0
  122. package/docs/ADOPTING.md +205 -15
  123. package/docs/ARCHITECTURE.md +34 -5
  124. package/docs/DECISIONS.md +1867 -11
  125. package/docs/DESIGN.md +137 -17
  126. package/docs/THREAT_MODEL.md +616 -0
  127. package/package.json +16 -3
  128. package/src/bridge/bounded-text.ts +240 -0
  129. package/src/bridge/bridge.ts +601 -51
  130. package/src/bridge/json-data.ts +95 -0
  131. package/src/bridge/navigation.ts +10 -0
  132. package/src/bridge/refusal.ts +17 -0
  133. package/src/bridge/types.ts +76 -5
  134. package/src/check/check.ts +8 -0
  135. package/src/check/instrument.ts +3 -0
  136. package/src/check/lint.ts +4 -2
  137. package/src/check/page.ts +16 -0
  138. package/src/check/tools.ts +2 -3
  139. package/src/compile/compile.ts +9 -1
  140. package/src/compile/policy.ts +177 -0
  141. package/src/config/capabilities.ts +71 -5
  142. package/src/config/schema.ts +35 -0
  143. package/src/config/validate.ts +141 -8
  144. package/src/config/warnings.ts +42 -0
  145. package/src/conformance/behavior.ts +54 -1
  146. package/src/conformance/cookies.ts +93 -0
  147. package/src/conformance/harness/page.ts +11 -2
  148. package/src/conformance/host-kit.ts +10 -1
  149. package/src/conformance/index.ts +17 -0
  150. package/src/conformance/limits.ts +39 -1
  151. package/src/conformance/runtime.ts +594 -0
  152. package/src/conformance/served.ts +888 -4
  153. package/src/files/paths.ts +4 -0
  154. package/src/guide/gates.ts +37 -0
  155. package/src/guide/guide.ts +61 -55
  156. package/src/guide/limits.ts +4 -4
  157. package/src/guide/runtime.ts +253 -0
  158. package/src/host/create-host.ts +88 -36
  159. package/src/host/locate.ts +10 -0
  160. package/src/host/locator.ts +11 -0
  161. package/src/host/pages-of-set.ts +226 -0
  162. package/src/host/types.ts +33 -1
  163. package/src/index.ts +94 -0
  164. package/src/isolation/types.ts +8 -0
  165. package/src/mcp/adapter.ts +16 -20
  166. package/src/node/index.ts +507 -116
  167. package/src/presets/presets.ts +67 -17
  168. package/src/protocol/live-data.ts +31 -3
  169. package/src/protocol/mcp-apps.ts +11 -2
  170. package/src/protocol/message-text.ts +36 -0
  171. package/src/protocol/runtime-calls.ts +141 -0
  172. package/src/protocol/shell-adapter.ts +79 -26
  173. package/src/react/context-notice.tsx +95 -0
  174. package/src/react/dialog.tsx +108 -15
  175. package/src/react/frame.tsx +120 -0
  176. package/src/react/index.ts +8 -1
  177. package/src/runtime/contract.ts +339 -0
  178. package/src/runtime/db.ts +650 -0
  179. package/src/runtime/declaration.ts +516 -0
  180. package/src/runtime/levels.ts +69 -0
  181. package/src/runtime/requests.ts +355 -0
  182. package/src/runtime/segments.ts +17 -0
  183. package/src/runtime/types.generated.ts +19 -0
  184. package/src/server/files.ts +138 -7
  185. package/src/server/host.ts +170 -3
  186. package/src/server/index.ts +4 -0
  187. package/src/server/peer.ts +21 -0
  188. package/src/server/proxy.ts +13 -3
  189. package/src/server/pseudonym.ts +21 -0
  190. package/src/server/server.ts +370 -57
  191. package/src/server/types.ts +73 -2
  192. package/src/shell/document.ts +29 -4
  193. package/src/shell/legacy.ts +64 -0
  194. package/src/shell/plan.ts +37 -3
  195. package/src/shell/runtime.ts +390 -56
  196. package/src/shell/use.ts +235 -0
  197. package/types/runtime/v1/artifact.d.ts +50 -0
  198. package/types/runtime/v1/assets.d.ts +43 -0
  199. package/types/runtime/v1/chat.d.ts +13 -0
  200. package/types/runtime/v1/clipboard.d.ts +14 -0
  201. package/types/runtime/v1/comments.d.ts +24 -0
  202. package/types/runtime/v1/context.d.ts +27 -0
  203. package/types/runtime/v1/data.d.ts +29 -0
  204. package/types/runtime/v1/db.d.ts +110 -0
  205. package/types/runtime/v1/downloads.d.ts +22 -0
  206. package/types/runtime/v1/links.d.ts +13 -0
  207. package/types/runtime/v1/porthole.d.ts +44 -0
  208. package/types/runtime/v1/user.d.ts +19 -0
@@ -1,5 +1,6 @@
1
1
  import type { PortholeConfig } from "../config/schema.ts";
2
2
  import type { FrameLocation, InstanceRef } from "../isolation/types.ts";
3
+ import type { ViewerLevel } from "../runtime/levels.ts";
3
4
  import type { Naming } from "./naming.ts";
4
5
 
5
6
  export interface ContentDomain {
@@ -62,6 +63,20 @@ export type Grant = (
62
63
  * url-mode app's every request, rides on.
63
64
  */
64
65
  readonly sessionSeconds?: number;
66
+ /**
67
+ * The viewer's level on this instance (P087), as the host decided it now: carried in the
68
+ * issue's answer (`FrameLocation.viewer`) to the display's bridge, which checks each runtime
69
+ * method's level against it. Never in the ticket or the cookie, never shown to content but by
70
+ * the `user` capability.
71
+ */
72
+ readonly level?: ViewerLevel;
73
+ /**
74
+ * Who the viewer is to pages that declare `user` (P087): the host's public id for them (whose
75
+ * per-user data, `data/users/<id>`, the page reaches: one path segment, never `me`) and a name.
76
+ * Never `viewer`, unless the host means it to be seen; `pseudonymFor(secret, artifact, person)`
77
+ * gives an id per artifact, so pages can't link a person across artifacts. Only with `level`.
78
+ */
79
+ readonly user?: { readonly id: string; readonly name?: string };
65
80
  };
66
81
 
67
82
  export interface TicketRecord {
@@ -132,6 +147,54 @@ export interface StoredFiles {
132
147
  /** A stored version: one page (`{ html }`, as in 0.5), or a set of files (P081). */
133
148
  export type StoredVersion = { readonly html: string } | StoredFiles;
134
149
 
150
+ /**
151
+ * One asset of an artifact's library (P089), as the host stored it: served at `/_blob/<id>` on
152
+ * the origin of `scope`, and nowhere else. Its type is Porthole's for `name`'s extension, never
153
+ * the uploader's; it is never served as a page.
154
+ */
155
+ export interface StoredAsset {
156
+ /** The storage scope whose origin serves it (the artifact's). */
157
+ readonly scope: string;
158
+ /**
159
+ * The artifact whose library holds it (`ServedDocument`'s `id`, after the review): served only
160
+ * to an access for that artifact, never another one sharing the scope.
161
+ */
162
+ readonly artifact: string;
163
+ /**
164
+ * Whether it may run as code (P089, after the review): a script, stylesheet or WebAssembly an
165
+ * admin uploaded where uploaded code may run (the upload's `trusted`). Any other code-typed
166
+ * asset is served as a download, whatever the config says now; a trusted one too, once the
167
+ * config no longer lets uploaded code run (P103: asked at every request; in bearer mode, every
168
+ * artifact config the server has must).
169
+ */
170
+ readonly trusted?: boolean;
171
+ /** Its file name (its extension types it). */
172
+ readonly name: string;
173
+ readonly size: number;
174
+ /** The SHA-256 of its bytes, lowercase hex: its strong ETag. */
175
+ readonly sha256: string;
176
+ read(): Promise<FileBody | null>;
177
+ }
178
+
179
+ /**
180
+ * Where an artifact's assets are kept (P089): the host's library, by id. Ids are the host's, 32
181
+ * lowercase hex characters made at random (`ASSET_ID`): an asset's address is known only to those
182
+ * shown it; Porthole serves one only on its own scope's origin.
183
+ */
184
+ export interface AssetStore {
185
+ /**
186
+ * The asset, for `access` (who asks, for which artifact: the host decides, and its check runs
187
+ * after); null if it isn't there for them. `access` is null only in bearer mode.
188
+ */
189
+ get(id: string, access: Access | null): Promise<StoredAsset | null>;
190
+ /**
191
+ * Bearer mode, an explicit opt-in (after the review): serve an asset to anyone holding its id,
192
+ * with no access and no host check (a public artifact's library). Its id is then a capability:
193
+ * whoever saw it keeps it until the asset is removed.
194
+ */
195
+ readonly bearer?: boolean;
196
+ }
197
+
135
198
  /** Stored pages (artifact mode). Versions are immutable: a new page is a new version. */
136
199
  export interface ArtifactStore {
137
200
  get(id: string, version: string): Promise<StoredVersion | null>;
@@ -204,6 +267,13 @@ export interface ServerOptions {
204
267
  */
205
268
  readonly configs: Readonly<Record<string, PortholeConfig>>;
206
269
  readonly artifacts?: ArtifactStore;
270
+ /**
271
+ * Artifacts' asset libraries (P089): `/_blob/<id>` on each content origin, for a request that
272
+ * carries an access to the asset's own artifact (a frame's sealed files' address as its
273
+ * `Referer`, or a session cookie), after the host's check. Absent: `/_blob/` is a clean address
274
+ * like any other.
275
+ */
276
+ readonly assets?: AssetStore;
207
277
  readonly tickets?: TicketStore;
208
278
  /** Url mode: where an external instance's requests go once let in. Absent: nothing serves them. */
209
279
  readonly upstream?: Upstream;
@@ -254,8 +324,9 @@ export interface PortholeServer {
254
324
  issue(instance: InstanceRef, grant: Grant): Promise<FrameLocation>;
255
325
  /**
256
326
  * The access a request's cookie carries for a url-mode app on the request's origin, or null
257
- * (no good cookie, or the host's check denies it): for a host's own WebSocket upgrade path,
258
- * which a fetch-style handler can't take.
327
+ * (no good cookie, an `Origin` or `Sec-Fetch-Site` of another origin's (P101), or the host's
328
+ * check denies it): for a host's own WebSocket upgrade path, which a fetch-style handler can't
329
+ * take.
259
330
  */
260
331
  access(request: Request): Promise<Access | null>;
261
332
  /** The frame source every content origin matches (`https://*.example-usercontent.com`). */
@@ -1,6 +1,8 @@
1
1
  import { hostOriginProblem } from "../isolation/served.ts";
2
2
  import { ANNOTATE_RUNTIME } from "./annotate.ts";
3
+ import { LEGACY_GLOBALS_RUNTIME } from "./legacy.ts";
3
4
  import { SHELL_RUNTIME } from "./runtime.ts";
5
+ import { USE_RUNTIME } from "./use.ts";
4
6
  import type { ShellPlan } from "./plan.ts";
5
7
 
6
8
  export interface ShellDocumentOptions {
@@ -36,6 +38,8 @@ export interface ShellDocumentOptions {
36
38
  * (`https://a-x.example-usercontent.com/v/3/`). The shell lets the frame navigate to the set's
37
39
  * other pages there, and to nothing else.
38
40
  */
41
+ /** `same-origin`: the document's loads tell its own origin its address (P091); else none. */
42
+ readonly referrer?: "same-origin";
39
43
  readonly files?: {
40
44
  readonly base: string;
41
45
  /**
@@ -49,6 +53,11 @@ export interface ShellDocumentOptions {
49
53
  * renews it before then, at `<base>__porthole/renew`, and moves the page there.
50
54
  */
51
55
  readonly expires?: number;
56
+ /**
57
+ * The artifact version the files are (P098): the shell names it in its notices, and the host
58
+ * takes a notice only for the version it mounted. Not secret; the content can read it.
59
+ */
60
+ readonly set?: { readonly id: string; readonly version: string };
52
61
  };
53
62
  }
54
63
 
@@ -123,6 +132,19 @@ body {
123
132
  * The frame's document: its policy first, then the base styles, an empty root, and the runtime.
124
133
  * A given `document` travels in the runtime's plan, as data.
125
134
  */
135
+ /**
136
+ * The shell's runtime for a plan, before its plan goes in: annotations where declared, 0.6's
137
+ * globals (the legacy path, P085) for what the config declares, and the capability runtime where
138
+ * the config has one.
139
+ */
140
+ export function composedRuntime(plan: ShellPlan): string {
141
+ return SHELL_RUNTIME.replace("__ANNOTATE__", () =>
142
+ plan.capabilities.annotate === undefined ? "" : ANNOTATE_RUNTIME,
143
+ )
144
+ .replace("__LEGACY__", () => LEGACY_GLOBALS_RUNTIME)
145
+ .replace("__RUNTIME__", () => (plan.runtime === undefined ? "" : USE_RUNTIME));
146
+ }
147
+
126
148
  export function shellDocument(plan: ShellPlan, csp: string, options: ShellDocumentOptions): string {
127
149
  for (const origin of options.origins) {
128
150
  const problem = hostOriginProblem(origin);
@@ -145,9 +167,7 @@ export function shellDocument(plan: ShellPlan, csp: string, options: ShellDocume
145
167
  const nonce = options.nonce === undefined ? "" : ` nonce="${options.nonce}"`;
146
168
  // The annotation runtime only where it is declared; spliced in before the plan, which may carry
147
169
  // any text (a document) and must not be searched.
148
- const runtime = SHELL_RUNTIME.replace("__ANNOTATE__", () =>
149
- plan.capabilities.annotate === undefined ? "" : ANNOTATE_RUNTIME,
150
- ).replace("__PLAN__", () =>
170
+ const runtime = composedRuntime(plan).replace("__PLAN__", () =>
151
171
  scriptJson({
152
172
  ...plan,
153
173
  origins: options.origins,
@@ -159,6 +179,9 @@ export function shellDocument(plan: ShellPlan, csp: string, options: ShellDocume
159
179
  base: options.files.base,
160
180
  ...(options.files.address === undefined ? {} : { address: options.files.address }),
161
181
  ...(options.files.expires === undefined ? {} : { expires: options.files.expires }),
182
+ ...(options.files.set === undefined
183
+ ? {}
184
+ : { set: { id: options.files.set.id, version: options.files.set.version } }),
162
185
  },
163
186
  }),
164
187
  }),
@@ -168,7 +191,9 @@ export function shellDocument(plan: ShellPlan, csp: string, options: ShellDocume
168
191
  options.cspMeta === false
169
192
  ? null
170
193
  : `<meta http-equiv="Content-Security-Policy" content="${escapeAttribute(csp)}">`,
171
- '<meta name="referrer" content="no-referrer">',
194
+ // A framed page of files whose config serves assets says its sealed address to its own
195
+ // origin only, which its asset loads carry (P091); every other document says nothing.
196
+ `<meta name="referrer" content="${options.referrer === "same-origin" ? "same-origin" : "no-referrer"}">`,
172
197
  // Off for good: an engine may prefetch names it sees in links, outside the CSP.
173
198
  '<meta http-equiv="x-dns-prefetch-control" content="off">',
174
199
  ].filter((line) => line !== null);
@@ -0,0 +1,64 @@
1
+ /**
2
+ * The legacy path (P085): the globals pages written for Porthole 0.5 and 0.6 call
3
+ * (`sendPrompt`, `copyText`, `openLink`, `readData`, `subscribeData`), spliced into the shell's
4
+ * runtime (`__LEGACY__`) for each capability the config declares, as before. A page written for the
5
+ * capability runtime reaches the same host functions through `porthole.use` instead; the bridge
6
+ * gates both paths alike, and holds a page that declared capabilities to its declaration on
7
+ * either (P086).
8
+ *
9
+ * Since 0.7.0. Remove when no host serves a page written before it (hosts migrate their stored
10
+ * pages' calls to `porthole.use`); until then the manual teaches these only where the config has
11
+ * no runtime.
12
+ */
13
+ export const LEGACY_GLOBALS_RUNTIME = String.raw`
14
+ if (declared("sendPrompt")) {
15
+ lock(window, "sendPrompt", (text) => {
16
+ if (!gestured("sendPrompt")) {
17
+ return refuse("sendPrompt needs a click: call it from a button's handler");
18
+ }
19
+ const words = String(text);
20
+ if (words.trim() === "" || words.length > plan.maxPromptChars) {
21
+ return refuse("sendPrompt takes 1 to " + plan.maxPromptChars + " characters");
22
+ }
23
+ return request("ui/message", { role: "user", content: [{ type: "text", text: words }] }).then(
24
+ (result) => !(result && result.isError),
25
+ );
26
+ });
27
+ }
28
+ if (declared("copyText")) {
29
+ lock(window, "copyText", (text) => {
30
+ if (!gestured("copyText")) {
31
+ return refuse("copyText needs a click: call it from a button's handler");
32
+ }
33
+ const words = String(text);
34
+ if (words === "" || words.length > plan.maxCopyChars) {
35
+ return refuse("copyText takes 1 to " + plan.maxCopyChars + " characters");
36
+ }
37
+ return request("porthole/copy-text", { text: words }).then((result) => !(result && result.isError));
38
+ });
39
+ }
40
+ if (declared("openLink")) {
41
+ lock(window, "openLink", (url) => {
42
+ if (!gestured("openLink")) {
43
+ return refuse("openLink needs a click: call it from a link's or button's handler");
44
+ }
45
+ return request("ui/open-link", { url: String(url) }).then((result) => !(result && result.isError));
46
+ });
47
+ }
48
+
49
+ if (declared("readData")) {
50
+ lock(window, "readData", readValue);
51
+ }
52
+ if (follow !== null) {
53
+ lock(window, "subscribeData", follow);
54
+ }
55
+ `;
56
+
57
+ /** The globals the legacy path defines, by the capability that defines each. */
58
+ export const LEGACY_GLOBALS = {
59
+ sendPrompt: "sendPrompt",
60
+ copyText: "copyText",
61
+ openLink: "openLink",
62
+ readData: "readData",
63
+ subscribeData: "subscribeData",
64
+ } as const;
package/src/shell/plan.ts CHANGED
@@ -2,6 +2,13 @@ import { MAX_COPY_CHARS, capabilitySpec, type CapabilityName } from "../config/c
2
2
  import type { PortholeConfig } from "../config/schema.ts";
3
3
  import { declaredCapabilities, effectiveGates } from "../compile/policy.ts";
4
4
  import { MCP_APPS_PROTOCOL_VERSION } from "../protocol/mcp-apps.ts";
5
+ import {
6
+ RUNTIME_GLOBAL,
7
+ methodGates,
8
+ offeredCapabilities,
9
+ runtimeCapability,
10
+ type RuntimeVersion,
11
+ } from "../runtime/contract.ts";
5
12
 
6
13
  /**
7
14
  * What the shell wires, derived from the config: the JSON the shell's runtime is given. The
@@ -19,8 +26,23 @@ export interface ShellPlan {
19
26
  readonly content: "fragment" | "document";
20
27
  /** Each declared capability, and whether the shell refuses a call made without a gesture. */
21
28
  readonly capabilities: { readonly [N in CapabilityName]?: { readonly userActivation: boolean } };
22
- /** The globals the shell defines on `window` (sugar over the protocol's requests). */
29
+ /**
30
+ * The globals the shell defines on `window` and the manual teaches: `porthole` where the config
31
+ * has the capability runtime (P085), else 0.6's (sugar over the protocol's requests).
32
+ */
23
33
  readonly globals: readonly string[];
34
+ /**
35
+ * 0.6's globals the shell still defines under the runtime, for pages written before it (the
36
+ * legacy path, `shell/legacy.ts`), which the manual no longer teaches. Empty without a runtime.
37
+ */
38
+ readonly legacyGlobals: readonly string[];
39
+ /** The capability runtime's contract version, where the config has one (`porthole.use`). */
40
+ readonly runtime?: RuntimeVersion;
41
+ /**
42
+ * The runtime methods whose own gates want a gesture (`capability.method`: `artifact.publish`,
43
+ * `assets.delete`): the shell refuses them without one, as it does a host function's.
44
+ */
45
+ readonly methodActivation?: readonly string[];
24
46
  /** The theme variables the shell applies; it drops any other name the host sends. */
25
47
  readonly themeVariables: readonly string[];
26
48
  /** The window event fired after a theme change. */
@@ -48,18 +70,30 @@ export function shellPlan(config: PortholeConfig): ShellPlan | null {
48
70
  userActivation: effectiveGates(config, name).includes("user-activation"),
49
71
  };
50
72
  }
51
- const globals =
73
+ const legacy =
52
74
  protocol === "shell"
53
75
  ? declared.flatMap((name) => {
54
76
  const spec = capabilitySpec(name);
55
77
  return spec.global === undefined ? [] : [spec.global];
56
78
  })
57
79
  : [];
80
+ const runtime = protocol === "shell" ? config.runtime : undefined;
58
81
  return {
59
82
  protocol,
60
83
  content: config.mode === "artifact" ? "document" : "fragment",
61
84
  capabilities,
62
- globals,
85
+ globals: runtime === undefined ? legacy : [RUNTIME_GLOBAL],
86
+ legacyGlobals: runtime === undefined ? [] : legacy,
87
+ ...(runtime === undefined
88
+ ? {}
89
+ : {
90
+ runtime,
91
+ methodActivation: offeredCapabilities(config).flatMap((family) =>
92
+ Object.keys(runtimeCapability(family).methods)
93
+ .filter((method) => methodGates(config, family, method).includes("user-activation"))
94
+ .map((method) => `${family}.${method}`),
95
+ ),
96
+ }),
63
97
  themeVariables: Object.keys(config.theme.variables),
64
98
  themeEvent: config.theme.event,
65
99
  themeDocuments: config.theme.documents ?? "declared",