@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
@@ -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 {
@@ -78,7 +93,14 @@ export interface TicketRecord {
78
93
  * An entry code's (P068): the clean path it returns to, and the nonce of the browser that asked
79
94
  * (its cookie must come with the code). A ticket from `issue` has none.
80
95
  */
81
- readonly entry?: { readonly path: string; readonly nonce: string };
96
+ readonly entry?: {
97
+ readonly path: string;
98
+ readonly nonce: string;
99
+ /** A file set's version's own address (P081): the session serves every path under it. */
100
+ readonly base?: string;
101
+ /** Whether that address names this version and no other: its files are immutable there. */
102
+ readonly pinned?: boolean;
103
+ };
82
104
  }
83
105
 
84
106
  /** Where tickets live between `issue` and their one use. Default: in memory (one process). */
@@ -88,9 +110,92 @@ export interface TicketStore {
88
110
  take(id: string): Promise<TicketRecord | null>;
89
111
  }
90
112
 
113
+ /** One file of a version (P081), as the host stored it when the version was published. */
114
+ export interface StoredFile {
115
+ /** Its length, bytes. */
116
+ readonly size: number;
117
+ /** The SHA-256 of its bytes, lowercase hex: its strong ETag. */
118
+ readonly sha256: string;
119
+ /**
120
+ * The type it was published with, for the host's own use (a file list): never served. A file
121
+ * is served with the type Porthole's table gives its extension (`fileTypeOf`), never sniffed.
122
+ */
123
+ readonly type?: string;
124
+ }
125
+
126
+ /** A file's bytes, whole: `/server` cuts the range a request asks for. */
127
+ export type FileBody = Uint8Array | ReadableStream<Uint8Array>;
128
+
129
+ /**
130
+ * A version made of files (P081): a manifest, and the bytes of each file by its path. Paths
131
+ * follow `checkFileSet`'s rules (check them when the version is published); a request is looked
132
+ * up in `files` only, and `read` is asked only for a path in it.
133
+ */
134
+ export interface StoredFiles {
135
+ readonly files: Readonly<Record<string, StoredFile>>;
136
+ /** The page the version opens at: one of `files` (default `index.html`). */
137
+ readonly entry?: string;
138
+ /**
139
+ * A single-page app's routes: a navigation whose path finds no file answers the entry, where
140
+ * it would get the nearest `404.html` (default false). Subresources still 404.
141
+ */
142
+ readonly spa?: boolean;
143
+ /** The bytes of a file in `files`; null if they are gone (a 404). */
144
+ read(path: string): Promise<FileBody | null>;
145
+ }
146
+
147
+ /** A stored version: one page (`{ html }`, as in 0.5), or a set of files (P081). */
148
+ export type StoredVersion = { readonly html: string } | StoredFiles;
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.
167
+ */
168
+ readonly trusted?: boolean;
169
+ /** Its file name (its extension types it). */
170
+ readonly name: string;
171
+ readonly size: number;
172
+ /** The SHA-256 of its bytes, lowercase hex: its strong ETag. */
173
+ readonly sha256: string;
174
+ read(): Promise<FileBody | null>;
175
+ }
176
+
177
+ /**
178
+ * Where an artifact's assets are kept (P089): the host's library, by id. Ids are the host's, 32
179
+ * lowercase hex characters made at random (`ASSET_ID`): an asset's address is known only to those
180
+ * shown it; Porthole serves one only on its own scope's origin.
181
+ */
182
+ export interface AssetStore {
183
+ /**
184
+ * The asset, for `access` (who asks, for which artifact: the host decides, and its check runs
185
+ * after); null if it isn't there for them. `access` is null only in bearer mode.
186
+ */
187
+ get(id: string, access: Access | null): Promise<StoredAsset | null>;
188
+ /**
189
+ * Bearer mode, an explicit opt-in (after the review): serve an asset to anyone holding its id,
190
+ * with no access and no host check (a public artifact's library). Its id is then a capability:
191
+ * whoever saw it keeps it until the asset is removed.
192
+ */
193
+ readonly bearer?: boolean;
194
+ }
195
+
91
196
  /** Stored pages (artifact mode). Versions are immutable: a new page is a new version. */
92
197
  export interface ArtifactStore {
93
- get(id: string, version: string): Promise<{ readonly html: string } | null>;
198
+ get(id: string, version: string): Promise<StoredVersion | null>;
94
199
  }
95
200
 
96
201
  /** What a request's cookie lets in: one instance, for one viewer, on one origin, until a time. */
@@ -160,6 +265,13 @@ export interface ServerOptions {
160
265
  */
161
266
  readonly configs: Readonly<Record<string, PortholeConfig>>;
162
267
  readonly artifacts?: ArtifactStore;
268
+ /**
269
+ * Artifacts' asset libraries (P089): `/_blob/<id>` on each content origin, for a request that
270
+ * carries an access to the asset's own artifact (a frame's sealed files' address as its
271
+ * `Referer`, or a session cookie), after the host's check. Absent: `/_blob/` is a clean address
272
+ * like any other.
273
+ */
274
+ readonly assets?: AssetStore;
163
275
  readonly tickets?: TicketStore;
164
276
  /** Url mode: where an external instance's requests go once let in. Absent: nothing serves them. */
165
277
  readonly upstream?: Upstream;
@@ -227,7 +339,15 @@ export interface PortholeServer {
227
339
  entryState(token: string): EntryState | null;
228
340
  /**
229
341
  * Once the host decided (its authorize route): a one-time code for `instance`, which must be
230
- * served on the state's label, and the URL that redeems it there (`/__porthole/entry`).
342
+ * served on the state's label, and the URL that redeems it there (`/__porthole/entry`). With an
343
+ * `address` (a file set's, P081: `entry.at`'s `base` and `file`), the session it buys serves
344
+ * every path under `base`, and the redeem goes to `base` + `file` when the state's path isn't
345
+ * under it (a "latest" address goes to the version's own).
231
346
  */
232
- enterBy(state: EntryState, instance: InstanceRef, grant: Grant): Promise<string>;
347
+ enterBy(
348
+ state: EntryState,
349
+ instance: InstanceRef,
350
+ grant: Grant,
351
+ address?: { readonly base: string; readonly file?: string; readonly pinned?: boolean },
352
+ ): Promise<string>;
233
353
  }
@@ -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 {
@@ -31,6 +33,43 @@ export interface ShellDocumentOptions {
31
33
  * every script the shell runs for the content. The frame can read it.
32
34
  */
33
35
  readonly nonce?: string;
36
+ /**
37
+ * A page that comes with files (P081, P084): the absolute URL its version's files are under
38
+ * (`https://a-x.example-usercontent.com/v/3/`). The shell lets the frame navigate to the set's
39
+ * other pages there, and to nothing else.
40
+ */
41
+ /** `same-origin`: the document's loads tell its own origin its address (P091); else none. */
42
+ readonly referrer?: "same-origin";
43
+ readonly files?: {
44
+ readonly base: string;
45
+ /**
46
+ * The page's own address under `base`, where the request's isn't it (a ticket's answer, P083):
47
+ * the shell puts it in the frame's history first, before anything loads, so the page's
48
+ * relative addresses are its files' and the spent ticket leaves the address.
49
+ */
50
+ readonly address?: string;
51
+ /**
52
+ * When a sealed address stops opening the page's files on its own (epoch ms, P083): the shell
53
+ * renews it before then, at `<base>__porthole/renew`, and moves the page there.
54
+ */
55
+ readonly expires?: number;
56
+ };
57
+ }
58
+
59
+ /** A file set's base: an absolute http(s) URL that ends in `/`, no query or fragment. */
60
+ function filesBaseOk(base: string): boolean {
61
+ try {
62
+ const url = new URL(base);
63
+ return (
64
+ (url.protocol === "https:" || url.protocol === "http:") &&
65
+ url.href === base &&
66
+ base.endsWith("/") &&
67
+ url.search === "" &&
68
+ url.hash === ""
69
+ );
70
+ } catch {
71
+ return false;
72
+ }
34
73
  }
35
74
 
36
75
  /** A CSP nonce: base64 or base64url characters, 8 to 256 of them. */
@@ -88,6 +127,19 @@ body {
88
127
  * The frame's document: its policy first, then the base styles, an empty root, and the runtime.
89
128
  * A given `document` travels in the runtime's plan, as data.
90
129
  */
130
+ /**
131
+ * The shell's runtime for a plan, before its plan goes in: annotations where declared, 0.6's
132
+ * globals (the legacy path, P085) for what the config declares, and the capability runtime where
133
+ * the config has one.
134
+ */
135
+ export function composedRuntime(plan: ShellPlan): string {
136
+ return SHELL_RUNTIME.replace("__ANNOTATE__", () =>
137
+ plan.capabilities.annotate === undefined ? "" : ANNOTATE_RUNTIME,
138
+ )
139
+ .replace("__LEGACY__", () => LEGACY_GLOBALS_RUNTIME)
140
+ .replace("__RUNTIME__", () => (plan.runtime === undefined ? "" : USE_RUNTIME));
141
+ }
142
+
91
143
  export function shellDocument(plan: ShellPlan, csp: string, options: ShellDocumentOptions): string {
92
144
  for (const origin of options.origins) {
93
145
  const problem = hostOriginProblem(origin);
@@ -98,16 +150,32 @@ export function shellDocument(plan: ShellPlan, csp: string, options: ShellDocume
98
150
  if (options.nonce !== undefined && !NONCE.test(options.nonce)) {
99
151
  throw new TypeError("shellDocument: a nonce is 8 to 256 base64 characters");
100
152
  }
153
+ if (options.files !== undefined && !filesBaseOk(options.files.base)) {
154
+ throw new TypeError("shellDocument: files.base is an http(s) URL ending in /, with no query");
155
+ }
156
+ if (
157
+ options.files?.address !== undefined &&
158
+ (!options.files.address.startsWith(options.files.base) || /[?#]/u.test(options.files.address))
159
+ ) {
160
+ throw new TypeError("shellDocument: files.address is under files.base, with no query");
161
+ }
101
162
  const nonce = options.nonce === undefined ? "" : ` nonce="${options.nonce}"`;
102
163
  // The annotation runtime only where it is declared; spliced in before the plan, which may carry
103
164
  // any text (a document) and must not be searched.
104
- const runtime = SHELL_RUNTIME.replace("__ANNOTATE__", () =>
105
- plan.capabilities.annotate === undefined ? "" : ANNOTATE_RUNTIME,
106
- ).replace("__PLAN__", () =>
165
+ const runtime = composedRuntime(plan).replace("__PLAN__", () =>
107
166
  scriptJson({
108
167
  ...plan,
109
168
  origins: options.origins,
110
169
  ...(options.document === undefined ? {} : { document: options.document }),
170
+ ...(options.files === undefined
171
+ ? {}
172
+ : {
173
+ files: {
174
+ base: options.files.base,
175
+ ...(options.files.address === undefined ? {} : { address: options.files.address }),
176
+ ...(options.files.expires === undefined ? {} : { expires: options.files.expires }),
177
+ },
178
+ }),
111
179
  }),
112
180
  );
113
181
  const head = [
@@ -115,7 +183,9 @@ export function shellDocument(plan: ShellPlan, csp: string, options: ShellDocume
115
183
  options.cspMeta === false
116
184
  ? null
117
185
  : `<meta http-equiv="Content-Security-Policy" content="${escapeAttribute(csp)}">`,
118
- '<meta name="referrer" content="no-referrer">',
186
+ // A framed page of files whose config serves assets says its sealed address to its own
187
+ // origin only, which its asset loads carry (P091); every other document says nothing.
188
+ `<meta name="referrer" content="${options.referrer === "same-origin" ? "same-origin" : "no-referrer"}">`,
119
189
  // Off for good: an engine may prefetch names it sees in links, outside the CSP.
120
190
  '<meta http-equiv="x-dns-prefetch-control" content="off">',
121
191
  ].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",