@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
package/src/index.ts CHANGED
@@ -50,6 +50,90 @@ export {
50
50
  export { hostOriginProblem, isHostOrigin } from "./isolation/served.ts";
51
51
  export { FRAME_STATUS_METHOD } from "./isolation/types.ts";
52
52
 
53
+ // The capability runtime (P085-P090): its contract, levels, a page's declaration, its services'
54
+ // shapes. Hosts implement the services; Porthole carries, checks and gates the calls.
55
+ export {
56
+ RUNTIME_CALL_METHOD,
57
+ RUNTIME_CAPABILITIES,
58
+ RUNTIME_CAPABILITY_NAMES,
59
+ RUNTIME_EVENT_METHOD,
60
+ RUNTIME_EXPERIMENTAL_KEY,
61
+ RUNTIME_GLOBAL,
62
+ RUNTIME_HOST_FUNCTIONS,
63
+ RUNTIME_UNWATCH_METHOD,
64
+ RUNTIME_VERSION,
65
+ RUNTIME_VERSIONS,
66
+ familyOf,
67
+ isRuntimeCapabilityName,
68
+ methodGates,
69
+ isRuntimeVersion,
70
+ methodLevel,
71
+ offeredCapabilities,
72
+ rosterOf,
73
+ type RuntimeCapability,
74
+ type RuntimeCapabilityName,
75
+ type RuntimeMethod,
76
+ type RuntimeVersion,
77
+ } from "./runtime/contract.ts";
78
+ export {
79
+ VIEWER_LEVELS,
80
+ atLeast,
81
+ isViewerLevel,
82
+ parseViewer,
83
+ type ViewerInfo,
84
+ type ViewerLevel,
85
+ } from "./runtime/levels.ts";
86
+ export {
87
+ checkDeclaration,
88
+ declarationProblems,
89
+ declareCapabilities,
90
+ declaredMatch,
91
+ intersectDeclarations,
92
+ type CapabilityDeclaration,
93
+ type DeclarationProblem,
94
+ type DeclaredCapability,
95
+ type DeclaredData,
96
+ type DeclaredDb,
97
+ type PageDeclaration,
98
+ } from "./runtime/declaration.ts";
99
+ export {
100
+ DB_LIMITS,
101
+ DB_USERS_PREFIX,
102
+ dbAccess,
103
+ isDbSegment,
104
+ isPlainJson,
105
+ withMe,
106
+ dbRulesProblem,
107
+ parseDbRequest,
108
+ type DbData,
109
+ type DbRequest,
110
+ type DbResult,
111
+ type DbRules,
112
+ type DbSnapshot,
113
+ type DbValue,
114
+ type DbWhere,
115
+ type DbWrite,
116
+ } from "./runtime/db.ts";
117
+ export {
118
+ ASSET_ID,
119
+ ASSET_PATH,
120
+ MAX_PUBLISH_FILES,
121
+ assetNameProblem,
122
+ assetUrl,
123
+ isCodeAsset,
124
+ type ArtifactInfo,
125
+ type ArtifactRequest,
126
+ type AssetInfo,
127
+ type AssetRequest,
128
+ type CommentAnchor,
129
+ type CommentRequest,
130
+ type DownloadedFile,
131
+ type PublishedFile,
132
+ type PublishedVersion,
133
+ type UserInfo,
134
+ } from "./runtime/requests.ts";
135
+ export { RUNTIME_TYPES } from "./runtime/types.generated.ts";
136
+
53
137
  // Presets.
54
138
  export {
55
139
  LIBRARY_CDNS,
@@ -101,6 +185,10 @@ export {
101
185
  egressOrigins,
102
186
  embedderCsp,
103
187
  embedderFrameSourcesOf,
188
+ ASSET_CODE_DIRECTIVES,
189
+ ASSET_DIRECTIVES,
190
+ assetCodeRuns,
191
+ assetCspDirectives,
104
192
  FILE_SET_DIRECTIVES,
105
193
  fileSetCspDirectives,
106
194
  INERT_FILE_CSP,
@@ -179,6 +267,7 @@ export type {
179
267
  HostFunctionBridge,
180
268
  Refusal,
181
269
  SubscriptionContext,
270
+ DbContext,
182
271
  } from "./bridge/types.ts";
183
272
  export { createHost } from "./host/create-host.ts";
184
273
  // The client half of the host kit, and the display registry (P072).
@@ -12,6 +12,7 @@
12
12
  * one host app.
13
13
  */
14
14
  import type { EgressConfig } from "../config/schema.ts";
15
+ import type { ViewerInfo } from "../runtime/levels.ts";
15
16
 
16
17
  /**
17
18
  * Which document a served frame loads. `preset` names the config it is served under (the server's
@@ -63,6 +64,11 @@ export interface FrameLocation {
63
64
  * one that loaded. A host's own gateway may send the same message without this.
64
65
  */
65
66
  readonly reports?: boolean;
67
+ /**
68
+ * Who is viewing, as the host's access decided at issue (P087: `Grant.level`, `Grant.user`):
69
+ * the display's bridge checks each runtime method's level against it.
70
+ */
71
+ readonly viewer?: ViewerInfo;
66
72
  }
67
73
 
68
74
  /** The message a served page sends its host about loading (own-prefixed, P040). */
@@ -88,4 +94,6 @@ export type FrameSource =
88
94
  readonly url: string;
89
95
  readonly origin: string;
90
96
  readonly reports?: boolean;
97
+ /** The issue's viewer (`FrameLocation.viewer`), for the display's bridge. */
98
+ readonly viewer?: ViewerInfo;
91
99
  };
@@ -1,3 +1,4 @@
1
+ import type { RuntimeVersion } from "../runtime/contract.ts";
1
2
  import type { CapabilityName } from "../config/capabilities.ts";
2
3
  import type {
3
4
  CapabilityConfig,
@@ -50,6 +51,11 @@ export interface PresetOptions {
50
51
  readonly storage?: StorageConfig;
51
52
  /** Where the content's errors go (`PortholeConfig.errors`); `none` drops `reportError`. */
52
53
  readonly errors?: "agent" | "host" | "none";
54
+ /**
55
+ * The capability runtime (P085): content reaches capabilities through `porthole.use`, and may
56
+ * be offered the runtime's own (`user`, `comments`, `artifact`, `assets`, `db`).
57
+ */
58
+ readonly runtime?: RuntimeVersion;
53
59
  }
54
60
 
55
61
  /**
@@ -207,6 +213,7 @@ function build(
207
213
  embedder: options.embedder ?? {},
208
214
  ...(options.storage === undefined ? {} : { storage: options.storage }),
209
215
  ...(options.errors === undefined ? {} : { errors: options.errors }),
216
+ ...(options.runtime === undefined ? {} : { runtime: options.runtime }),
210
217
  });
211
218
  }
212
219
 
@@ -0,0 +1,138 @@
1
+ import type { CallOutcome, HostFunctionBridge } from "../bridge/types.ts";
2
+ import { reasonFor, type RefusalReason } from "../bridge/refusal.ts";
3
+ import type { CapabilityName } from "../config/capabilities.ts";
4
+ import {
5
+ RUNTIME_CAPABILITIES,
6
+ RUNTIME_EVENT_METHOD,
7
+ isRuntimeCapabilityName,
8
+ type RuntimeMethod,
9
+ } from "../runtime/contract.ts";
10
+ import { DB_LIMITS } from "../runtime/db.ts";
11
+ import { downloadContents } from "../runtime/requests.ts";
12
+
13
+ /**
14
+ * The host side of the capability runtime's calls (P085): `porthole/call` with `{ capability,
15
+ * method, args }` (and `watch`, a frame-chosen id, for a subscription), each turned into the host
16
+ * function that serves it and passed through the bridge, which alone decides; `porthole/unwatch`
17
+ * ends a watch. A watch's updates go to the frame as `porthole/event` with `{ watch, data }`.
18
+ */
19
+
20
+ const isRecord = (value: unknown): value is Record<string, unknown> =>
21
+ value !== null && typeof value === "object" && !Array.isArray(value);
22
+
23
+ /** A runtime call as the host function that serves it gets it, or null for none. */
24
+ export function runtimeCall(
25
+ capability: unknown,
26
+ method: unknown,
27
+ args: unknown,
28
+ ): { readonly serves: CapabilityName; readonly args: unknown; readonly watch: boolean } | null {
29
+ if (!isRuntimeCapabilityName(capability) || typeof method !== "string") {
30
+ return null;
31
+ }
32
+ const methods: Readonly<Record<string, RuntimeMethod>> = RUNTIME_CAPABILITIES[capability].methods;
33
+ const spec = Object.hasOwn(methods, method) ? methods[method] : undefined;
34
+ // `data.subscribe` is MCP's own subscription (resources/subscribe, P079), not a runtime call.
35
+ if (spec === undefined || spec.serves === "subscribeData") {
36
+ return null;
37
+ }
38
+ const given = isRecord(args) ? args : {};
39
+ const watch = spec.watch === true;
40
+ switch (spec.serves) {
41
+ case "downloadFile":
42
+ return {
43
+ serves: spec.serves,
44
+ args: { contents: downloadContents(given.file) ?? undefined },
45
+ watch,
46
+ };
47
+ case "callTool":
48
+ return { serves: spec.serves, args: { name: given.name, arguments: given.arguments }, watch };
49
+ case "readData":
50
+ return { serves: spec.serves, args: { uri: given.uri }, watch };
51
+ case "artifact":
52
+ case "assets":
53
+ case "db":
54
+ // One host function serves several methods: the method is its `op`.
55
+ return { serves: spec.serves, args: { ...given, op: method }, watch };
56
+ default:
57
+ return { serves: spec.serves, args: given, watch };
58
+ }
59
+ }
60
+
61
+ type Answer =
62
+ | { readonly result: unknown }
63
+ | { readonly error: { code: number; message: string; data?: RefusalReason } };
64
+
65
+ /** A runtime call's outcome, as the frame hears it: its value, or why it was refused (P080). */
66
+ export function runtimeAnswer(serves: CapabilityName, outcome: CallOutcome<unknown>): Answer {
67
+ if (!outcome.ok) {
68
+ return {
69
+ error: {
70
+ code: -32000,
71
+ message: `Refused (${outcome.refusal})`,
72
+ data: reasonFor(serves, outcome),
73
+ },
74
+ };
75
+ }
76
+ return { result: { value: outcome.value ?? null } };
77
+ }
78
+
79
+ const refused = (reason: RefusalReason): Answer => ({
80
+ error: { code: -32000, message: `Refused (${reason.code})`, data: reason },
81
+ });
82
+
83
+ /** One frame's runtime calls: its watches, and their end. */
84
+ export function runtimeCalls(
85
+ bridge: HostFunctionBridge,
86
+ notify: (method: string, params: Record<string, unknown>) => void,
87
+ ) {
88
+ const watches = new Map<string, AbortController>();
89
+ return {
90
+ async call(params: Record<string, unknown>): Promise<Answer> {
91
+ const mapped = runtimeCall(params.capability, params.method, params.args);
92
+ if (mapped === null) {
93
+ return refused({ code: "not_allowed", message: "This isn't available here." });
94
+ }
95
+ if (!mapped.watch) {
96
+ return runtimeAnswer(mapped.serves, await bridge.call(mapped.serves, mapped.args));
97
+ }
98
+ const id = params.watch;
99
+ if (typeof id !== "string" || !/^[\w-]{1,64}$/u.test(id) || watches.has(id)) {
100
+ return refused({ code: "not_allowed", message: "The app can't take this request." });
101
+ }
102
+ if (watches.size >= DB_LIMITS.maxWatches) {
103
+ return refused({ code: "too_large", message: "Too many things followed at once." });
104
+ }
105
+ const controller = new AbortController();
106
+ watches.set(id, controller);
107
+ const outcome = await bridge.call(mapped.serves, mapped.args, {
108
+ subscription: {
109
+ changed: (data?: unknown) => {
110
+ if (!controller.signal.aborted) {
111
+ notify(RUNTIME_EVENT_METHOD, { watch: id, data: data ?? null });
112
+ }
113
+ },
114
+ signal: controller.signal,
115
+ },
116
+ });
117
+ if (!outcome.ok) {
118
+ controller.abort();
119
+ watches.delete(id);
120
+ }
121
+ return outcome.ok ? { result: { value: null } } : runtimeAnswer(mapped.serves, outcome);
122
+ },
123
+ /** The frame stopped following (never gated). */
124
+ unwatch(params: Record<string, unknown>): void {
125
+ const id = params.watch;
126
+ if (typeof id === "string") {
127
+ watches.get(id)?.abort();
128
+ watches.delete(id);
129
+ }
130
+ },
131
+ close(): void {
132
+ for (const controller of watches.values()) {
133
+ controller.abort();
134
+ }
135
+ watches.clear();
136
+ },
137
+ };
138
+ }
@@ -18,6 +18,12 @@ import {
18
18
  type HostContext,
19
19
  } from "./mcp-apps.ts";
20
20
  import { liveData } from "./live-data.ts";
21
+ import { runtimeCalls } from "./runtime-calls.ts";
22
+ import {
23
+ RUNTIME_CALL_METHOD,
24
+ RUNTIME_EXPERIMENTAL_KEY,
25
+ RUNTIME_UNWATCH_METHOD,
26
+ } from "../runtime/contract.ts";
21
27
 
22
28
  /**
23
29
  * The core's adapter: the host side of the MCP Apps subset the shell speaks, which content using
@@ -143,7 +149,20 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
143
149
  transport.send({ jsonrpc: "2.0", method, params });
144
150
 
145
151
  // Live data (P079): reads, subscriptions and the host's updates, through the bridge.
146
- const live = liveData(bridge, (uri) => notify(M.resourceUpdated, { uri }));
152
+ let live = liveData(bridge, (uri) => notify(M.resourceUpdated, { uri }));
153
+ // The capability runtime (P085), where the config has one: its calls and watches.
154
+ const runtime = session.compiled.config.runtime;
155
+ let calls = runtimeCalls(bridge, notify);
156
+ // A new page on the same transport (another of the set's pages, P084; or a reload that says
157
+ // hello again) starts with nothing followed: the last page's watches and subscriptions end,
158
+ // so it never hears their updates or their refusals (after the review).
159
+ let greeted = false;
160
+ const forget = () => {
161
+ calls.close();
162
+ calls = runtimeCalls(bridge, notify);
163
+ live.close();
164
+ live = liveData(bridge, (uri) => notify(M.resourceUpdated, { uri }));
165
+ };
147
166
 
148
167
  const flush = () => {
149
168
  if (!initialized || closed || content === null || sentWhole) {
@@ -163,11 +182,28 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
163
182
  const onRequest = async (request: JsonRpcRequest) => {
164
183
  const params = request.params ?? {};
165
184
  if (request.method === M.initialize) {
185
+ if (greeted) {
186
+ forget();
187
+ }
188
+ greeted = true;
166
189
  respond(request.id, {
167
190
  result: {
168
191
  protocolVersion: MCP_APPS_PROTOCOL_VERSION,
169
192
  hostInfo: session.hostInfo,
170
- hostCapabilities: hostCapabilities((name) => bridge.declared(name)),
193
+ hostCapabilities: {
194
+ ...hostCapabilities((name) => bridge.declared(name)),
195
+ // What this display's page may `use`, in MCP Apps' extension point (P085).
196
+ ...(runtime === undefined
197
+ ? {}
198
+ : {
199
+ experimental: {
200
+ [RUNTIME_EXPERIMENTAL_KEY]: {
201
+ version: runtime,
202
+ capabilities: bridge.roster(),
203
+ },
204
+ },
205
+ }),
206
+ },
171
207
  hostContext: session.hostContext(),
172
208
  },
173
209
  });
@@ -209,6 +245,13 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
209
245
  }
210
246
  return;
211
247
  }
248
+ if (request.method === RUNTIME_CALL_METHOD && runtime !== undefined) {
249
+ const answered = await calls.call(params);
250
+ if (!closed) {
251
+ respond(request.id, answered);
252
+ }
253
+ return;
254
+ }
212
255
  const mapped = REQUESTS[request.method];
213
256
  if (mapped === undefined) {
214
257
  respond(request.id, {
@@ -250,8 +293,13 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
250
293
  // The shell stopped a navigation (P080): an error report, with its address.
251
294
  void bridge.call("reportError", { navigationBlocked: params.url });
252
295
  return;
296
+ case RUNTIME_UNWATCH_METHOD:
297
+ calls.unwatch(params);
298
+ return;
253
299
  case NAVIGATING_METHOD:
254
- // Another page of the set opens in the frame (P084): its next load is that page.
300
+ // Another page of the set opens in the frame (P084): its next load is that page, which
301
+ // follows nothing yet.
302
+ forget();
255
303
  session.emit({ type: "navigating" });
256
304
  return;
257
305
  case M.requestTeardown:
@@ -314,6 +362,7 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
314
362
  stop();
315
363
  pending.clear();
316
364
  live.close();
365
+ calls.close();
317
366
  },
318
367
  };
319
368
  },
@@ -70,6 +70,39 @@ function words(request: ConfirmRequest): Words {
70
70
  return { heading: "Let it follow this?", accept: "Allow", detail: request.args.uri };
71
71
  case "copyText":
72
72
  return { heading: "Copy this text?", accept: "Copy", detail: request.args.text };
73
+ // The runtime's (P088, P089): the whole effect, as the page asked for it.
74
+ case "artifact":
75
+ return request.args.op === "publish"
76
+ ? {
77
+ heading: "Publish a new version of this page?",
78
+ accept: "Publish",
79
+ detail: Object.entries(request.args.files)
80
+ .map(([path, file]) =>
81
+ file === null
82
+ ? `${path}: removed`
83
+ : "text" in file
84
+ ? `${path}: ${file.text.length.toLocaleString("en-US")} characters`
85
+ : `${path}: ${Math.floor((file.base64.length * 3) / 4).toLocaleString("en-US")} bytes`,
86
+ )
87
+ .join("\n"),
88
+ note: `From version ${request.args.base}${request.args.label === undefined ? "" : `: ${request.args.label}`}.`,
89
+ }
90
+ : { heading: "Allow this?", accept: "Allow", detail: json(request.args) };
91
+ case "assets":
92
+ return request.args.op === "upload"
93
+ ? {
94
+ heading: "Add this file to the page's library?",
95
+ accept: "Add",
96
+ detail: `${request.args.name} (${request.args.type}, ${request.args.size.toLocaleString("en-US")} bytes)`,
97
+ note: "Everyone who can see the page can load it.",
98
+ }
99
+ : request.args.op === "delete"
100
+ ? {
101
+ heading: "Remove this file from the page's library?",
102
+ accept: "Remove",
103
+ detail: request.args.id,
104
+ }
105
+ : { heading: "Allow this?", accept: "Allow", detail: json(request.args) };
73
106
  default:
74
107
  return { heading: "Allow this?", accept: "Allow", detail: json(request.args) };
75
108
  }
@@ -1,3 +1,5 @@
1
+ import type { PageDeclaration } from "../runtime/declaration.ts";
2
+ import type { ViewerInfo } from "../runtime/levels.ts";
1
3
  import {
2
4
  createContext,
3
5
  useCallback,
@@ -407,6 +409,17 @@ export interface PortholeFrameProps {
407
409
  * shows, for its confirmations only, never sent to the frame (P077).
408
410
  */
409
411
  readonly instance?: InstanceRef;
412
+ /**
413
+ * What the page declared (P086), as the host stored it with the artifact: the capabilities it
414
+ * reaches through `porthole.use`, and its pinned runtime. By value: a change makes the display
415
+ * again.
416
+ */
417
+ readonly declaration?: PageDeclaration;
418
+ /**
419
+ * Who is viewing (P087), for an opaque frame or one whose issue gave none. By value: a change
420
+ * makes the display again.
421
+ */
422
+ readonly viewer?: ViewerInfo;
410
423
  /** The color scheme it shows in. Default: the provider's `scheme`, else light. */
411
424
  readonly scheme?: ColorScheme;
412
425
  /** The host's live values for the config's theme variables (from its design tokens). */
@@ -664,6 +677,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
664
677
  // By value: a config or instance made inline (each render) is the same display.
665
678
  const config = useByValue(frame.config);
666
679
  const instance = useByValue(frame.instance);
680
+ const declaration = useByValue(frame.declaration);
681
+ const viewer = useByValue(frame.viewer);
667
682
  const fills = config.mode === "url" || frame.fill === true || config.layout.kind === "fill";
668
683
  // A consent that refuses everything (P080), this frame's or else the provider's, by value: a
669
684
  // display made with it needs no data handlers, so a change makes the display again.
@@ -830,6 +845,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
830
845
  initialHeightPx: startHeight,
831
846
  ...(view === undefined ? {} : { document: view }),
832
847
  ...(instance === undefined ? {} : { instance }),
848
+ ...(declaration === undefined ? {} : { declaration }),
849
+ ...(viewer === undefined ? {} : { viewer }),
833
850
  ...(fills ? { fill: true } : {}),
834
851
  });
835
852
  } catch (error) {
@@ -870,6 +887,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
870
887
  config,
871
888
  view,
872
889
  instance,
890
+ declaration,
891
+ viewer,
873
892
  startHeight,
874
893
  fills,
875
894
  pageHandlers,