@botiverse/porthole 0.6.0 → 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 (145) hide show
  1. package/README.md +16 -0
  2. package/dist/bridge/bridge.d.ts +13 -0
  3. package/dist/bridge/bridge.js +200 -8
  4. package/dist/bridge/refusal.d.ts +5 -1
  5. package/dist/bridge/refusal.js +16 -0
  6. package/dist/bridge/types.d.ts +41 -4
  7. package/dist/check/check.d.ts +7 -0
  8. package/dist/check/check.js +1 -0
  9. package/dist/check/instrument.d.ts +3 -0
  10. package/dist/check/lint.js +4 -2
  11. package/dist/check/page-source.js +1 -1
  12. package/dist/check/page.js +14 -0
  13. package/dist/check/tools.js +2 -3
  14. package/dist/compile/policy.d.ts +19 -0
  15. package/dist/compile/policy.js +42 -0
  16. package/dist/config/capabilities.d.ts +62 -3
  17. package/dist/config/capabilities.js +20 -0
  18. package/dist/config/schema.d.ts +24 -0
  19. package/dist/config/validate.d.ts +1 -1
  20. package/dist/config/validate.js +66 -4
  21. package/dist/conformance/harness-source.js +1 -1
  22. package/dist/conformance/index.d.ts +1 -0
  23. package/dist/conformance/index.js +2 -0
  24. package/dist/conformance/runtime.d.ts +58 -0
  25. package/dist/conformance/runtime.js +314 -0
  26. package/dist/guide/gates.d.ts +3 -0
  27. package/dist/guide/gates.js +19 -0
  28. package/dist/guide/guide.d.ts +2 -0
  29. package/dist/guide/guide.js +34 -32
  30. package/dist/guide/limits.js +4 -4
  31. package/dist/guide/runtime.d.ts +13 -0
  32. package/dist/guide/runtime.js +202 -0
  33. package/dist/host/create-host.js +24 -0
  34. package/dist/host/locate.js +8 -0
  35. package/dist/host/locator.js +7 -0
  36. package/dist/host/types.d.ts +18 -0
  37. package/dist/index.d.ts +8 -2
  38. package/dist/index.js +9 -1
  39. package/dist/isolation/types.d.ts +8 -0
  40. package/dist/presets/presets.d.ts +6 -0
  41. package/dist/presets/presets.js +1 -0
  42. package/dist/protocol/runtime-calls.d.ts +28 -0
  43. package/dist/protocol/runtime-calls.js +113 -0
  44. package/dist/protocol/shell-adapter.js +48 -3
  45. package/dist/react/dialog.js +31 -0
  46. package/dist/react/frame.d.ts +13 -0
  47. package/dist/react/frame.js +6 -0
  48. package/dist/runtime/contract.d.ts +193 -0
  49. package/dist/runtime/contract.js +216 -0
  50. package/dist/runtime/db.d.ts +153 -0
  51. package/dist/runtime/db.js +398 -0
  52. package/dist/runtime/declaration.d.ts +86 -0
  53. package/dist/runtime/declaration.js +266 -0
  54. package/dist/runtime/levels.d.ts +33 -0
  55. package/dist/runtime/levels.js +41 -0
  56. package/dist/runtime/requests.d.ts +125 -0
  57. package/dist/runtime/requests.js +199 -0
  58. package/dist/runtime/segments.d.ts +8 -0
  59. package/dist/runtime/segments.js +14 -0
  60. package/dist/runtime/types.generated.d.ts +1 -0
  61. package/dist/runtime/types.generated.js +19 -0
  62. package/dist/server/files.d.ts +14 -1
  63. package/dist/server/files.js +97 -3
  64. package/dist/server/host.d.ts +6 -1
  65. package/dist/server/host.js +5 -0
  66. package/dist/server/index.d.ts +2 -1
  67. package/dist/server/index.js +1 -0
  68. package/dist/server/pseudonym.d.ts +9 -0
  69. package/dist/server/pseudonym.js +20 -0
  70. package/dist/server/server.d.ts +0 -5
  71. package/dist/server/server.js +214 -35
  72. package/dist/server/types.d.ts +69 -0
  73. package/dist/shell/document.d.ts +8 -0
  74. package/dist/shell/document.js +16 -2
  75. package/dist/shell/legacy.d.ts +21 -0
  76. package/dist/shell/legacy.js +63 -0
  77. package/dist/shell/plan.d.ts +17 -1
  78. package/dist/shell/plan.js +13 -2
  79. package/dist/shell/runtime.js +29 -42
  80. package/dist/shell/use.d.ts +15 -0
  81. package/dist/shell/use.js +235 -0
  82. package/docs/ADOPTING.md +91 -6
  83. package/docs/ARCHITECTURE.md +22 -3
  84. package/docs/DECISIONS.md +415 -6
  85. package/docs/DESIGN.md +66 -0
  86. package/package.json +3 -1
  87. package/src/bridge/bridge.ts +273 -12
  88. package/src/bridge/refusal.ts +16 -0
  89. package/src/bridge/types.ts +46 -4
  90. package/src/check/check.ts +8 -0
  91. package/src/check/instrument.ts +3 -0
  92. package/src/check/lint.ts +4 -2
  93. package/src/check/page.ts +14 -0
  94. package/src/check/tools.ts +2 -3
  95. package/src/compile/policy.ts +54 -0
  96. package/src/config/capabilities.ts +49 -2
  97. package/src/config/schema.ts +24 -0
  98. package/src/config/validate.ts +99 -4
  99. package/src/conformance/index.ts +7 -0
  100. package/src/conformance/runtime.ts +573 -0
  101. package/src/guide/gates.ts +25 -0
  102. package/src/guide/guide.ts +59 -53
  103. package/src/guide/limits.ts +4 -4
  104. package/src/guide/runtime.ts +244 -0
  105. package/src/host/create-host.ts +34 -0
  106. package/src/host/locate.ts +10 -0
  107. package/src/host/locator.ts +11 -0
  108. package/src/host/types.ts +18 -0
  109. package/src/index.ts +89 -0
  110. package/src/isolation/types.ts +8 -0
  111. package/src/presets/presets.ts +7 -0
  112. package/src/protocol/runtime-calls.ts +138 -0
  113. package/src/protocol/shell-adapter.ts +52 -3
  114. package/src/react/dialog.tsx +33 -0
  115. package/src/react/frame.tsx +19 -0
  116. package/src/runtime/contract.ts +305 -0
  117. package/src/runtime/db.ts +530 -0
  118. package/src/runtime/declaration.ts +378 -0
  119. package/src/runtime/levels.ts +69 -0
  120. package/src/runtime/requests.ts +339 -0
  121. package/src/runtime/segments.ts +17 -0
  122. package/src/runtime/types.generated.ts +19 -0
  123. package/src/server/files.ts +117 -4
  124. package/src/server/host.ts +12 -0
  125. package/src/server/index.ts +3 -0
  126. package/src/server/pseudonym.ts +21 -0
  127. package/src/server/server.ts +247 -37
  128. package/src/server/types.ts +68 -0
  129. package/src/shell/document.ts +21 -4
  130. package/src/shell/legacy.ts +64 -0
  131. package/src/shell/plan.ts +37 -3
  132. package/src/shell/runtime.ts +29 -42
  133. package/src/shell/use.ts +235 -0
  134. package/types/runtime/v1/artifact.d.ts +50 -0
  135. package/types/runtime/v1/assets.d.ts +43 -0
  136. package/types/runtime/v1/chat.d.ts +13 -0
  137. package/types/runtime/v1/clipboard.d.ts +14 -0
  138. package/types/runtime/v1/comments.d.ts +24 -0
  139. package/types/runtime/v1/context.d.ts +16 -0
  140. package/types/runtime/v1/data.d.ts +29 -0
  141. package/types/runtime/v1/db.d.ts +110 -0
  142. package/types/runtime/v1/downloads.d.ts +22 -0
  143. package/types/runtime/v1/links.d.ts +13 -0
  144. package/types/runtime/v1/porthole.d.ts +44 -0
  145. 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
  export interface ContentDomain {
5
6
  /**
@@ -57,6 +58,23 @@ export type Grant = ({
57
58
  * url-mode app's every request, rides on.
58
59
  */
59
60
  readonly sessionSeconds?: number;
61
+ /**
62
+ * The viewer's level on this instance (P087), as the host decided it now: carried in the
63
+ * issue's answer (`FrameLocation.viewer`) to the display's bridge, which checks each runtime
64
+ * method's level against it. Never in the ticket or the cookie, never shown to content but by
65
+ * the `user` capability.
66
+ */
67
+ readonly level?: ViewerLevel;
68
+ /**
69
+ * Who the viewer is to pages that declare `user` (P087): the host's public id for them (whose
70
+ * per-user data, `data/users/<id>`, the page reaches: one path segment, never `me`) and a name.
71
+ * Never `viewer`, unless the host means it to be seen; `pseudonymFor(secret, artifact, person)`
72
+ * gives an id per artifact, so pages can't link a person across artifacts. Only with `level`.
73
+ */
74
+ readonly user?: {
75
+ readonly id: string;
76
+ readonly name?: string;
77
+ };
60
78
  };
61
79
  export interface TicketRecord {
62
80
  readonly instance: InstanceRef;
@@ -122,6 +140,50 @@ export interface StoredFiles {
122
140
  export type StoredVersion = {
123
141
  readonly html: string;
124
142
  } | StoredFiles;
143
+ /**
144
+ * One asset of an artifact's library (P089), as the host stored it: served at `/_blob/<id>` on
145
+ * the origin of `scope`, and nowhere else. Its type is Porthole's for `name`'s extension, never
146
+ * the uploader's; it is never served as a page.
147
+ */
148
+ export interface StoredAsset {
149
+ /** The storage scope whose origin serves it (the artifact's). */
150
+ readonly scope: string;
151
+ /**
152
+ * The artifact whose library holds it (`ServedDocument`'s `id`, after the review): served only
153
+ * to an access for that artifact, never another one sharing the scope.
154
+ */
155
+ readonly artifact: string;
156
+ /**
157
+ * Whether it may run as code (P089, after the review): a script, stylesheet or WebAssembly an
158
+ * admin uploaded where uploaded code may run (the upload's `trusted`). Any other code-typed
159
+ * asset is served as a download, whatever the config says now.
160
+ */
161
+ readonly trusted?: boolean;
162
+ /** Its file name (its extension types it). */
163
+ readonly name: string;
164
+ readonly size: number;
165
+ /** The SHA-256 of its bytes, lowercase hex: its strong ETag. */
166
+ readonly sha256: string;
167
+ read(): Promise<FileBody | null>;
168
+ }
169
+ /**
170
+ * Where an artifact's assets are kept (P089): the host's library, by id. Ids are the host's, 32
171
+ * lowercase hex characters made at random (`ASSET_ID`): an asset's address is known only to those
172
+ * shown it; Porthole serves one only on its own scope's origin.
173
+ */
174
+ export interface AssetStore {
175
+ /**
176
+ * The asset, for `access` (who asks, for which artifact: the host decides, and its check runs
177
+ * after); null if it isn't there for them. `access` is null only in bearer mode.
178
+ */
179
+ get(id: string, access: Access | null): Promise<StoredAsset | null>;
180
+ /**
181
+ * Bearer mode, an explicit opt-in (after the review): serve an asset to anyone holding its id,
182
+ * with no access and no host check (a public artifact's library). Its id is then a capability:
183
+ * whoever saw it keeps it until the asset is removed.
184
+ */
185
+ readonly bearer?: boolean;
186
+ }
125
187
  /** Stored pages (artifact mode). Versions are immutable: a new page is a new version. */
126
188
  export interface ArtifactStore {
127
189
  get(id: string, version: string): Promise<StoredVersion | null>;
@@ -188,6 +250,13 @@ export interface ServerOptions {
188
250
  */
189
251
  readonly configs: Readonly<Record<string, PortholeConfig>>;
190
252
  readonly artifacts?: ArtifactStore;
253
+ /**
254
+ * Artifacts' asset libraries (P089): `/_blob/<id>` on each content origin, for a request that
255
+ * carries an access to the asset's own artifact (a frame's sealed files' address as its
256
+ * `Referer`, or a session cookie), after the host's check. Absent: `/_blob/` is a clean address
257
+ * like any other.
258
+ */
259
+ readonly assets?: AssetStore;
191
260
  readonly tickets?: TicketStore;
192
261
  /** Url mode: where an external instance's requests go once let in. Absent: nothing serves them. */
193
262
  readonly upstream?: Upstream;
@@ -32,6 +32,8 @@ export interface ShellDocumentOptions {
32
32
  * (`https://a-x.example-usercontent.com/v/3/`). The shell lets the frame navigate to the set's
33
33
  * other pages there, and to nothing else.
34
34
  */
35
+ /** `same-origin`: the document's loads tell its own origin its address (P091); else none. */
36
+ readonly referrer?: "same-origin";
35
37
  readonly files?: {
36
38
  readonly base: string;
37
39
  /**
@@ -51,4 +53,10 @@ export interface ShellDocumentOptions {
51
53
  * The frame's document: its policy first, then the base styles, an empty root, and the runtime.
52
54
  * A given `document` travels in the runtime's plan, as data.
53
55
  */
56
+ /**
57
+ * The shell's runtime for a plan, before its plan goes in: annotations where declared, 0.6's
58
+ * globals (the legacy path, P085) for what the config declares, and the capability runtime where
59
+ * the config has one.
60
+ */
61
+ export declare function composedRuntime(plan: ShellPlan): string;
54
62
  export declare function shellDocument(plan: ShellPlan, csp: string, options: ShellDocumentOptions): string;
@@ -1,6 +1,8 @@
1
1
  import { hostOriginProblem } from "../isolation/served.js";
2
2
  import { ANNOTATE_RUNTIME } from "./annotate.js";
3
+ import { LEGACY_GLOBALS_RUNTIME } from "./legacy.js";
3
4
  import { SHELL_RUNTIME } from "./runtime.js";
5
+ import { USE_RUNTIME } from "./use.js";
4
6
  /** A file set's base: an absolute http(s) URL that ends in `/`, no query or fragment. */
5
7
  function filesBaseOk(base) {
6
8
  try {
@@ -62,6 +64,16 @@ body {
62
64
  * The frame's document: its policy first, then the base styles, an empty root, and the runtime.
63
65
  * A given `document` travels in the runtime's plan, as data.
64
66
  */
67
+ /**
68
+ * The shell's runtime for a plan, before its plan goes in: annotations where declared, 0.6's
69
+ * globals (the legacy path, P085) for what the config declares, and the capability runtime where
70
+ * the config has one.
71
+ */
72
+ export function composedRuntime(plan) {
73
+ return SHELL_RUNTIME.replace("__ANNOTATE__", () => plan.capabilities.annotate === undefined ? "" : ANNOTATE_RUNTIME)
74
+ .replace("__LEGACY__", () => LEGACY_GLOBALS_RUNTIME)
75
+ .replace("__RUNTIME__", () => (plan.runtime === undefined ? "" : USE_RUNTIME));
76
+ }
65
77
  export function shellDocument(plan, csp, options) {
66
78
  for (const origin of options.origins) {
67
79
  const problem = hostOriginProblem(origin);
@@ -82,7 +94,7 @@ export function shellDocument(plan, csp, options) {
82
94
  const nonce = options.nonce === undefined ? "" : ` nonce="${options.nonce}"`;
83
95
  // The annotation runtime only where it is declared; spliced in before the plan, which may carry
84
96
  // any text (a document) and must not be searched.
85
- const runtime = SHELL_RUNTIME.replace("__ANNOTATE__", () => plan.capabilities.annotate === undefined ? "" : ANNOTATE_RUNTIME).replace("__PLAN__", () => scriptJson({
97
+ const runtime = composedRuntime(plan).replace("__PLAN__", () => scriptJson({
86
98
  ...plan,
87
99
  origins: options.origins,
88
100
  ...(options.document === undefined ? {} : { document: options.document }),
@@ -101,7 +113,9 @@ export function shellDocument(plan, csp, options) {
101
113
  options.cspMeta === false
102
114
  ? null
103
115
  : `<meta http-equiv="Content-Security-Policy" content="${escapeAttribute(csp)}">`,
104
- '<meta name="referrer" content="no-referrer">',
116
+ // A framed page of files whose config serves assets says its sealed address to its own
117
+ // origin only, which its asset loads carry (P091); every other document says nothing.
118
+ `<meta name="referrer" content="${options.referrer === "same-origin" ? "same-origin" : "no-referrer"}">`,
105
119
  // Off for good: an engine may prefetch names it sees in links, outside the CSP.
106
120
  '<meta http-equiv="x-dns-prefetch-control" content="off">',
107
121
  ].filter((line) => line !== null);
@@ -0,0 +1,21 @@
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 declare const LEGACY_GLOBALS_RUNTIME: string;
14
+ /** The globals the legacy path defines, by the capability that defines each. */
15
+ export declare const LEGACY_GLOBALS: {
16
+ readonly sendPrompt: "sendPrompt";
17
+ readonly copyText: "copyText";
18
+ readonly openLink: "openLink";
19
+ readonly readData: "readData";
20
+ readonly subscribeData: "subscribeData";
21
+ };
@@ -0,0 +1,63 @@
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
+ /** The globals the legacy path defines, by the capability that defines each. */
57
+ export const LEGACY_GLOBALS = {
58
+ sendPrompt: "sendPrompt",
59
+ copyText: "copyText",
60
+ openLink: "openLink",
61
+ readData: "readData",
62
+ subscribeData: "subscribeData",
63
+ };
@@ -1,5 +1,6 @@
1
1
  import { type CapabilityName } from "../config/capabilities.ts";
2
2
  import type { PortholeConfig } from "../config/schema.ts";
3
+ import { type RuntimeVersion } from "../runtime/contract.ts";
3
4
  /**
4
5
  * What the shell wires, derived from the config: the JSON the shell's runtime is given. The
5
6
  * agreement test reads it against the CSP and the manual, so it lists everything the shell
@@ -20,8 +21,23 @@ export interface ShellPlan {
20
21
  readonly userActivation: boolean;
21
22
  };
22
23
  };
23
- /** The globals the shell defines on `window` (sugar over the protocol's requests). */
24
+ /**
25
+ * The globals the shell defines on `window` and the manual teaches: `porthole` where the config
26
+ * has the capability runtime (P085), else 0.6's (sugar over the protocol's requests).
27
+ */
24
28
  readonly globals: readonly string[];
29
+ /**
30
+ * 0.6's globals the shell still defines under the runtime, for pages written before it (the
31
+ * legacy path, `shell/legacy.ts`), which the manual no longer teaches. Empty without a runtime.
32
+ */
33
+ readonly legacyGlobals: readonly string[];
34
+ /** The capability runtime's contract version, where the config has one (`porthole.use`). */
35
+ readonly runtime?: RuntimeVersion;
36
+ /**
37
+ * The runtime methods whose own gates want a gesture (`capability.method`: `artifact.publish`,
38
+ * `assets.delete`): the shell refuses them without one, as it does a host function's.
39
+ */
40
+ readonly methodActivation?: readonly string[];
25
41
  /** The theme variables the shell applies; it drops any other name the host sends. */
26
42
  readonly themeVariables: readonly string[];
27
43
  /** The window event fired after a theme change. */
@@ -1,6 +1,7 @@
1
1
  import { MAX_COPY_CHARS, capabilitySpec } from "../config/capabilities.js";
2
2
  import { declaredCapabilities, effectiveGates } from "../compile/policy.js";
3
3
  import { MCP_APPS_PROTOCOL_VERSION } from "../protocol/mcp-apps.js";
4
+ import { RUNTIME_GLOBAL, methodGates, offeredCapabilities, runtimeCapability, } from "../runtime/contract.js";
4
5
  export function shellPlan(config) {
5
6
  if (config.mode === "url") {
6
7
  return null;
@@ -13,17 +14,27 @@ export function shellPlan(config) {
13
14
  userActivation: effectiveGates(config, name).includes("user-activation"),
14
15
  };
15
16
  }
16
- const globals = protocol === "shell"
17
+ const legacy = protocol === "shell"
17
18
  ? declared.flatMap((name) => {
18
19
  const spec = capabilitySpec(name);
19
20
  return spec.global === undefined ? [] : [spec.global];
20
21
  })
21
22
  : [];
23
+ const runtime = protocol === "shell" ? config.runtime : undefined;
22
24
  return {
23
25
  protocol,
24
26
  content: config.mode === "artifact" ? "document" : "fragment",
25
27
  capabilities,
26
- globals,
28
+ globals: runtime === undefined ? legacy : [RUNTIME_GLOBAL],
29
+ legacyGlobals: runtime === undefined ? [] : legacy,
30
+ ...(runtime === undefined
31
+ ? {}
32
+ : {
33
+ runtime,
34
+ methodActivation: offeredCapabilities(config).flatMap((family) => Object.keys(runtimeCapability(family).methods)
35
+ .filter((method) => methodGates(config, family, method).includes("user-activation"))
36
+ .map((method) => `${family}.${method}`)),
37
+ }),
27
38
  themeVariables: Object.keys(config.theme.variables),
28
39
  themeEvent: config.theme.event,
29
40
  themeDocuments: config.theme.documents ?? "declared",
@@ -359,7 +359,7 @@ export const SHELL_RUNTIME = String.raw `(() => {
359
359
  // the person makes (their keys, their menu) copies their selection as the browser makes it: no
360
360
  // copy or cut listener of the content's runs, so none can swap what goes on the clipboard.
361
361
  const noClipboard = function () {
362
- return Promise.reject(new DOMException("Content can't use the clipboard here" + (declared("copyText") ? ": call copyText(text) from a click" : ""), "NotAllowedError"));
362
+ return Promise.reject(new DOMException("Content can't use the clipboard here" + (declared("copyText") ? (plan.runtime ? ': call (await porthole.use("clipboard")).copy(text) from a click' : ": call copyText(text) from a click") : ""), "NotAllowedError"));
363
363
  };
364
364
  if (typeof Clipboard === "function") {
365
365
  for (const name of ["write", "writeText", "read", "readText"]) {
@@ -799,41 +799,6 @@ export const SHELL_RUNTIME = String.raw `(() => {
799
799
  return !(capability && capability.userActivation) || !activation || activation.isActive;
800
800
  };
801
801
  const refuse = (message) => Promise.reject(new Error(message));
802
- if (declared("sendPrompt")) {
803
- lock(window, "sendPrompt", (text) => {
804
- if (!gestured("sendPrompt")) {
805
- return refuse("sendPrompt needs a click: call it from a button's handler");
806
- }
807
- const words = String(text);
808
- if (words.trim() === "" || words.length > plan.maxPromptChars) {
809
- return refuse("sendPrompt takes 1 to " + plan.maxPromptChars + " characters");
810
- }
811
- return request("ui/message", { role: "user", content: [{ type: "text", text: words }] }).then(
812
- (result) => !(result && result.isError),
813
- );
814
- });
815
- }
816
- if (declared("copyText")) {
817
- lock(window, "copyText", (text) => {
818
- if (!gestured("copyText")) {
819
- return refuse("copyText needs a click: call it from a button's handler");
820
- }
821
- const words = String(text);
822
- if (words === "" || words.length > plan.maxCopyChars) {
823
- return refuse("copyText takes 1 to " + plan.maxCopyChars + " characters");
824
- }
825
- return request("porthole/copy-text", { text: words }).then((result) => !(result && result.isError));
826
- });
827
- }
828
- if (declared("openLink")) {
829
- lock(window, "openLink", (url) => {
830
- if (!gestured("openLink")) {
831
- return refuse("openLink needs a click: call it from a link's or button's handler");
832
- }
833
- return request("ui/open-link", { url: String(url) }).then((result) => !(result && result.isError));
834
- });
835
- }
836
-
837
802
  // Data (P079): readData reads a resource the host names, subscribeData follows one, through
838
803
  // MCP's resources/* requests, which the host gates (the viewer's consent, a rate). A value is the
839
804
  // first content's: JSON parsed when it says it is JSON, else its text.
@@ -857,9 +822,10 @@ export const SHELL_RUNTIME = String.raw `(() => {
857
822
  const later = (error) => setTimeout(() => {
858
823
  throw error;
859
824
  });
860
- if (declared("readData")) {
861
- lock(window, "readData", (uri) => request("resources/read", { uri: String(uri) }).then(valueOf));
862
- }
825
+ // Reads a resource (readData, the runtime's data.read).
826
+ const readValue = (uri) => request("resources/read", { uri: String(uri) }).then(valueOf);
827
+ // Follows one (subscribeData, the runtime's data.subscribe), where the config declares it.
828
+ let follow = null;
863
829
  if (declared("subscribeData")) {
864
830
  // One subscription per URI, however many follow it; a read at a time, one more if it changed
865
831
  // meanwhile; a late follower gets the last value at once.
@@ -913,7 +879,7 @@ export const SHELL_RUNTIME = String.raw `(() => {
913
879
  refresh(entry);
914
880
  }
915
881
  };
916
- lock(window, "subscribeData", (uri, onData, onError) => {
882
+ follow = (uri, onData, onError) => {
917
883
  if (typeof onData !== "function") {
918
884
  throw new TypeError("subscribeData(uri, onData, onError): onData must be a function");
919
885
  }
@@ -957,9 +923,19 @@ export const SHELL_RUNTIME = String.raw `(() => {
957
923
  request("resources/unsubscribe", { uri: key }).catch(() => {});
958
924
  }
959
925
  };
960
- });
926
+ };
961
927
  }
962
928
 
929
+
930
+ // The capability runtime's hooks (P085): the host's offer from the handshake (null: no host
931
+ // answered), and a watch's updates. The runtime, where the config has one, takes them.
932
+ let runtimeOffer = (_offer) => {};
933
+ let runtimeEvent = (_params) => {};
934
+
935
+ __LEGACY__
936
+
937
+ __RUNTIME__
938
+
963
939
  window.addEventListener("error", (event) => {
964
940
  const error = event.error;
965
941
  const where = event.lineno ? " (line " + event.lineno + ")" : "";
@@ -1150,6 +1126,9 @@ export const SHELL_RUNTIME = String.raw `(() => {
1150
1126
  resourceUpdated(params.uri);
1151
1127
  }
1152
1128
  break;
1129
+ case "porthole/event":
1130
+ runtimeEvent(params);
1131
+ break;
1153
1132
  case "ui/resource-teardown":
1154
1133
  case "ping":
1155
1134
  if (data.id !== undefined) {
@@ -1177,7 +1156,12 @@ export const SHELL_RUNTIME = String.raw `(() => {
1177
1156
  let initialized = false;
1178
1157
  let tries = 0;
1179
1158
  const initialize = () => {
1180
- if (initialized || tries >= 40) {
1159
+ if (initialized) {
1160
+ return;
1161
+ }
1162
+ if (tries >= 40) {
1163
+ // No host answered: the runtime has nothing to offer.
1164
+ runtimeOffer(null);
1181
1165
  return;
1182
1166
  }
1183
1167
  tries += 1;
@@ -1190,6 +1174,9 @@ export const SHELL_RUNTIME = String.raw `(() => {
1190
1174
  return;
1191
1175
  }
1192
1176
  initialized = true;
1177
+ const capabilities = result && result.hostCapabilities;
1178
+ const experimental = capabilities && capabilities.experimental;
1179
+ runtimeOffer(experimental && typeof experimental === "object" ? experimental["porthole/runtime"] : null);
1193
1180
  applyTheme(result && result.hostContext);
1194
1181
  notify("ui/notifications/initialized", {});
1195
1182
  schedule();
@@ -0,0 +1,15 @@
1
+ /**
2
+ * The capability runtime in the frame (P085), spliced into the shell's runtime (`__RUNTIME__`)
3
+ * where the config has one (`config.runtime`). Content gets one global, `porthole`, whose only
4
+ * member is `use(name)`: a promise of a frozen namespace of the capability's methods, or null when
5
+ * the capability isn't there for this page (not offered, not declared, no host): the reasons are
6
+ * indistinguishable. Permission problems come at call time, as a rejected promise whose error has
7
+ * a stable `code` (P080, P087) and a sentence to show.
8
+ *
9
+ * The host's offer comes in the handshake (MCP Apps' experimental host capabilities,
10
+ * `porthole/runtime`): which capabilities, which methods. Calls go as `porthole/call` (own-prefixed,
11
+ * P002), `data.read` and `data.subscribe` as MCP's own resource requests (the cache and the
12
+ * subscriptions of P079); a watch's updates come as `porthole/event`. The host's bridge decides
13
+ * every call: nothing here is a wall, since it shares the content's realm.
14
+ */
15
+ export declare const USE_RUNTIME: string;