@botiverse/porthole 0.4.0 → 0.5.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 (73) hide show
  1. package/README.md +3 -1
  2. package/dist/bridge/bridge.d.ts +16 -2
  3. package/dist/bridge/bridge.js +65 -12
  4. package/dist/bridge/types.d.ts +44 -6
  5. package/dist/check/lint.js +2 -2
  6. package/dist/check/page-source.js +1 -1
  7. package/dist/check/page.js +5 -0
  8. package/dist/compile/policy.d.ts +5 -0
  9. package/dist/compile/policy.js +18 -1
  10. package/dist/config/capabilities.d.ts +25 -2
  11. package/dist/config/capabilities.js +13 -0
  12. package/dist/config/schema.d.ts +7 -0
  13. package/dist/config/validate.js +14 -3
  14. package/dist/conformance/harness/page.js +1 -0
  15. package/dist/conformance/harness-source.js +1 -1
  16. package/dist/displays/displays.d.ts +1 -1
  17. package/dist/guide/guide.js +48 -8
  18. package/dist/host/create-host.js +5 -1
  19. package/dist/host/types.d.ts +12 -1
  20. package/dist/index.d.ts +4 -3
  21. package/dist/index.js +2 -1
  22. package/dist/libraries/files.generated.d.ts +1 -0
  23. package/dist/libraries/files.generated.js +8 -0
  24. package/dist/libraries/libraries.d.ts +36 -0
  25. package/dist/libraries/libraries.js +40 -0
  26. package/dist/mcp/adapter.js +31 -2
  27. package/dist/presets/presets.d.ts +15 -0
  28. package/dist/presets/presets.js +27 -2
  29. package/dist/protocol/live-data.d.ts +27 -0
  30. package/dist/protocol/live-data.js +98 -0
  31. package/dist/protocol/mcp-apps.d.ts +9 -0
  32. package/dist/protocol/mcp-apps.js +11 -0
  33. package/dist/protocol/shell-adapter.js +35 -2
  34. package/dist/react/dialog.js +2 -0
  35. package/dist/react/frame.d.ts +15 -1
  36. package/dist/react/frame.js +35 -1
  37. package/dist/server/libraries.d.ts +7 -0
  38. package/dist/server/libraries.js +27 -0
  39. package/dist/server/server.js +2 -1
  40. package/dist/shell/annotate.js +4 -1
  41. package/dist/shell/runtime.d.ts +5 -1
  42. package/dist/shell/runtime.js +165 -1
  43. package/docs/ADOPTING.md +57 -1
  44. package/docs/DECISIONS.md +129 -0
  45. package/docs/DESIGN.md +19 -6
  46. package/package.json +3 -1
  47. package/src/bridge/bridge.ts +85 -13
  48. package/src/bridge/types.ts +45 -3
  49. package/src/check/lint.ts +2 -1
  50. package/src/check/page.ts +5 -0
  51. package/src/compile/policy.ts +19 -1
  52. package/src/config/capabilities.ts +21 -0
  53. package/src/config/schema.ts +7 -0
  54. package/src/config/validate.ts +21 -3
  55. package/src/conformance/harness/page.ts +1 -0
  56. package/src/displays/displays.ts +1 -1
  57. package/src/guide/guide.ts +57 -7
  58. package/src/host/create-host.ts +5 -1
  59. package/src/host/types.ts +12 -1
  60. package/src/index.ts +13 -0
  61. package/src/libraries/files.generated.ts +8 -0
  62. package/src/libraries/libraries.ts +64 -0
  63. package/src/mcp/adapter.ts +40 -2
  64. package/src/presets/presets.ts +46 -3
  65. package/src/protocol/live-data.ts +138 -0
  66. package/src/protocol/mcp-apps.ts +12 -0
  67. package/src/protocol/shell-adapter.ts +35 -3
  68. package/src/react/dialog.tsx +2 -0
  69. package/src/react/frame.tsx +54 -0
  70. package/src/server/libraries.ts +28 -0
  71. package/src/server/server.ts +2 -1
  72. package/src/shell/annotate.ts +4 -1
  73. package/src/shell/runtime.ts +165 -1
@@ -0,0 +1,64 @@
1
+ /**
2
+ * Porthole's vendored libraries (P079): a small fixed set, pinned, copied byte for byte from their
3
+ * npm packages when Porthole is built (`scripts/vendor-libraries.ts`), and served by `/server` on
4
+ * every content origin under `LIBRARY_PATH`. A config that sets `egress.libraries` loads scripts
5
+ * from there (its own origin) and the manual teaches the lines below; nothing else is fetched.
6
+ *
7
+ * A path, once released, keeps serving the same bytes: a new version is a new path beside it.
8
+ */
9
+
10
+ /** Where the libraries are served on a content origin (inside Porthole's reserved prefix). */
11
+ export const LIBRARY_PATH = "/__porthole/lib/";
12
+
13
+ export interface VendoredLibrary {
14
+ /** What the manual calls it. */
15
+ readonly title: string;
16
+ /** The npm package. */
17
+ readonly name: string;
18
+ /** Its exact version (published at least two weeks before it was vendored). */
19
+ readonly version: string;
20
+ /** The file served, as a path inside the package (a classic script: it defines `global`). */
21
+ readonly file: string;
22
+ /** The global the script defines. */
23
+ readonly global: string;
24
+ /** Its license (SPDX), and the package's license file, served beside it. */
25
+ readonly license: string;
26
+ readonly licenseFile: string;
27
+ /** What it is for, for the manual. */
28
+ readonly use: string;
29
+ }
30
+
31
+ /**
32
+ * What agent-made widgets reach for most: Chart.js for charts, D3 for anything drawn from data
33
+ * (scales, axes, shapes, time and number formats). Both run as classic scripts.
34
+ */
35
+ export const VENDORED_LIBRARIES: readonly VendoredLibrary[] = [
36
+ {
37
+ title: "Chart.js",
38
+ name: "chart.js",
39
+ version: "4.5.1",
40
+ file: "dist/chart.umd.min.js",
41
+ global: "Chart",
42
+ license: "MIT",
43
+ licenseFile: "LICENSE.md",
44
+ use: "charts",
45
+ },
46
+ {
47
+ title: "D3",
48
+ name: "d3",
49
+ version: "7.9.0",
50
+ file: "dist/d3.min.js",
51
+ global: "d3",
52
+ license: "ISC",
53
+ licenseFile: "LICENSE",
54
+ use: "scales, axes, shapes, time and number formats",
55
+ },
56
+ ];
57
+
58
+ /** Where a library's file is served, on the frame's own origin. */
59
+ export const libraryPath = (library: VendoredLibrary): string =>
60
+ `${LIBRARY_PATH}${library.name}@${library.version}/${library.file}`;
61
+
62
+ /** Where its license is served, beside it. */
63
+ export const licensePath = (library: VendoredLibrary): string =>
64
+ `${LIBRARY_PATH}${library.name}@${library.version}/${library.licenseFile}`;
@@ -15,6 +15,7 @@ import {
15
15
  type HostContext,
16
16
  } from "../protocol/mcp-apps.ts";
17
17
  import { COPY_TEXT_METHOD, MCP_APPS_STYLE_VARIABLES } from "../protocol/mcp-apps.ts";
18
+ import { liveData } from "../protocol/live-data.ts";
18
19
 
19
20
  /**
20
21
  * The MCP Apps adapter (P004, P007): the host side of the protocol for full MCP Apps views, written
@@ -131,6 +132,10 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
131
132
  }
132
133
  };
133
134
  const answer = (id: JsonRpcId, result: unknown): void => send({ jsonrpc: "2.0", id, result });
135
+ // Live data (P079): reads, subscriptions and the host's updates, through the bridge.
136
+ const live = liveData(bridge, (uri) => notify(MCP_APPS_METHODS.resourceUpdated, { uri }), {
137
+ userActivated: hostActivation,
138
+ });
134
139
  const refuse = (id: JsonRpcId, code: number, message: string): void =>
135
140
  send({ jsonrpc: "2.0", id, error: { code, message } });
136
141
 
@@ -150,7 +155,9 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
150
155
  ...(declared("openLink") ? { openLinks: {} } : {}),
151
156
  ...(declared("downloadFile") ? { downloadFile: {} } : {}),
152
157
  ...(declared("callTool") ? { serverTools: {} } : {}),
153
- ...(declared("readData") ? { serverResources: {} } : {}),
158
+ ...(declared("readData")
159
+ ? { serverResources: declared("subscribeData") ? { subscribe: true } : {} }
160
+ : {}),
154
161
  ...(declared("sendPrompt") ? { message: { text: {} } } : {}),
155
162
  ...(declared("setModelContext")
156
163
  ? { updateModelContext: { text: {}, structuredContent: {} } }
@@ -183,6 +190,15 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
183
190
  refuse(request.id, JSON_RPC_ERRORS.internal, `${request.method} failed`);
184
191
  return;
185
192
  }
193
+ reply(request, outcome, result);
194
+ }
195
+
196
+ /** Answers a request with a capability's outcome. */
197
+ function reply(
198
+ request: JsonRpcRequest,
199
+ outcome: CallOutcome<unknown>,
200
+ result: (value: unknown) => unknown,
201
+ ): void {
186
202
  if (outcome.ok) {
187
203
  answer(request.id, result(outcome.value));
188
204
  } else if (outcome.refusal === "not-declared") {
@@ -259,10 +275,31 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
259
275
  invalid("needs a uri");
260
276
  return;
261
277
  }
262
- await call(request, "readData", { uri: params.uri }, (value) =>
278
+ reply(request, await live.read(params.uri), (value) =>
263
279
  isRecord(value) ? value : { contents: [] },
264
280
  );
265
281
  return;
282
+ case MCP_APPS_METHODS.subscribeResource:
283
+ case MCP_APPS_METHODS.unsubscribeResource:
284
+ if (!bridge.declared("subscribeData")) {
285
+ refuse(
286
+ request.id,
287
+ JSON_RPC_ERRORS.methodNotFound,
288
+ `${request.method} isn't offered here`,
289
+ );
290
+ return;
291
+ }
292
+ if (typeof params.uri !== "string") {
293
+ invalid("needs a uri");
294
+ return;
295
+ }
296
+ if (request.method === MCP_APPS_METHODS.unsubscribeResource) {
297
+ live.unsubscribe(params.uri);
298
+ answer(request.id, {});
299
+ return;
300
+ }
301
+ reply(request, await live.subscribe(params.uri), () => ({}));
302
+ return;
266
303
  case MCP_APPS_METHODS.updateModelContext:
267
304
  if (
268
305
  (params.content !== undefined && !Array.isArray(params.content)) ||
@@ -404,6 +441,7 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
404
441
  },
405
442
  close() {
406
443
  closed = true;
444
+ live.close();
407
445
  unlisten();
408
446
  queue = [];
409
447
  for (const waiting of pending.values()) {
@@ -14,7 +14,7 @@ import type {
14
14
  UrlPermission,
15
15
  UrlSandboxExtra,
16
16
  } from "../config/schema.ts";
17
- import { validateConfig } from "../config/validate.ts";
17
+ import { ConfigError, validateConfig } from "../config/validate.ts";
18
18
  import { DEFAULT_THEME_EVENT, DEFAULT_THEME_VARIABLES } from "../theme/variables.ts";
19
19
 
20
20
  /**
@@ -52,6 +52,12 @@ export interface PresetOptions {
52
52
  readonly errors?: "agent" | "host" | "none";
53
53
  }
54
54
 
55
+ /**
56
+ * The live widget's options (P079): a widget's, less egress, which stays closed (Porthole's own
57
+ * libraries come with domain isolation). A host adds capabilities, or changes the data ones' gates.
58
+ */
59
+ export type LiveWidgetOptions = Omit<PresetOptions, "egress">;
60
+
55
61
  /** The url preset's options: where the app is served, and the embedding page's extra frames. */
56
62
  export interface UrlPresetOptions {
57
63
  readonly contentOrigins: readonly string[];
@@ -137,6 +143,9 @@ const mergeEgress = (base: EgressConfig, extra: EgressConfig | undefined): Egres
137
143
  if (passive.length > 0) {
138
144
  merged.anyHttps = passive;
139
145
  }
146
+ if (base.libraries === true || extra?.libraries === true) {
147
+ merged.libraries = true;
148
+ }
140
149
  return merged;
141
150
  };
142
151
 
@@ -157,11 +166,16 @@ function themeVariables(
157
166
 
158
167
  function build(
159
168
  mode: PortholeConfig["mode"],
160
- defaults: { readonly limits?: Partial<Limits> },
169
+ defaults: {
170
+ readonly limits?: Partial<Limits>;
171
+ readonly capabilities?: CapabilityMap;
172
+ readonly egress?: EgressConfig;
173
+ },
161
174
  options: PresetOptions,
162
175
  ): PortholeConfig {
163
176
  const capabilities: { -readonly [N in CapabilityName]?: CapabilityConfig } = {
164
177
  ...BASE_CAPABILITIES,
178
+ ...defaults.capabilities,
165
179
  };
166
180
  if (options.errors === "none") {
167
181
  delete capabilities.reportError;
@@ -180,7 +194,7 @@ function build(
180
194
  mode,
181
195
  isolation: options.isolation ?? "opaque",
182
196
  capabilities,
183
- egress: mergeEgress({}, options.egress),
197
+ egress: mergeEgress(defaults.egress ?? {}, options.egress),
184
198
  theme: {
185
199
  variables: themeVariables(options.theme?.variables),
186
200
  event: options.theme?.event ?? DEFAULT_THEME_EVENT,
@@ -203,6 +217,35 @@ export const presets = {
203
217
  */
204
218
  inlineWidget: (options: PresetOptions = {}): PortholeConfig => build("inline", {}, options),
205
219
 
220
+ /**
221
+ * A widget that shows its host's data, live, and has no network of its own (P079): an inline
222
+ * widget whose egress stays closed (no option opens it). It reads the host's data (`readData`,
223
+ * MCP `resources/read`) and subscribes to it (`subscribeData`, `resources/subscribe`), each
224
+ * behind the viewer's consent (the host's `consent`, asked once per display) and a rate. In
225
+ * domain isolation its scripts load from Porthole's own libraries on its origin
226
+ * (`egress.libraries`: Chart.js, D3), and nowhere else. A host adds what any widget may have (a
227
+ * link, a copy button), or changes the data capabilities' gates.
228
+ */
229
+ liveWidget: (options: LiveWidgetOptions = {}): PortholeConfig => {
230
+ if ((options as PresetOptions).egress !== undefined) {
231
+ throw new ConfigError(
232
+ "options.egress",
233
+ "a live widget has no network of its own: its egress stays closed (P079)",
234
+ );
235
+ }
236
+ return build(
237
+ "inline",
238
+ {
239
+ capabilities: {
240
+ readData: { gates: ["consent", { rateLimit: { perMinute: 120 } }] },
241
+ subscribeData: { gates: ["consent", { rateLimit: { perMinute: 60 } }] },
242
+ },
243
+ egress: options.isolation === "domain" ? { libraries: true } : {},
244
+ },
245
+ options,
246
+ );
247
+ },
248
+
206
249
  /**
207
250
  * A whole HTML page: written into an opaque frame by the shell where the host has the page, or
208
251
  * served on its own origin (`isolation: "domain"`). A document scrolls inside past a shorter cap.
@@ -0,0 +1,138 @@
1
+ import type { CallOutcome, HostFunctionBridge } from "../bridge/types.ts";
2
+ import { STALE_META } from "./mcp-apps.ts";
3
+
4
+ /**
5
+ * Live data for one frame (P079), as both adapters speak it (MCP `resources/read`,
6
+ * `resources/subscribe`, `resources/unsubscribe`, `notifications/resources/updated`): the frame's
7
+ * subscriptions by URI, each ended by its controller, and a fresh result the host gave for one
8
+ * (pushed through `changed(result)`, or read after a stale answer), kept for the frame's next read
9
+ * of it. Every call goes through the bridge, which gates it; the adapter only says what to send.
10
+ */
11
+ export interface LiveData {
12
+ /** A read: a fresh result kept for it, else the host's (its cache first, when subscribed). */
13
+ read(uri: unknown): Promise<CallOutcome<unknown>>;
14
+ /** Starts the host's subscription; a second for a URI is a no-op. */
15
+ subscribe(uri: unknown): Promise<CallOutcome<undefined>>;
16
+ /** Ends one: never gated, it stops what the host was doing for this frame. */
17
+ unsubscribe(uri: unknown): void;
18
+ /** The frame is gone: every subscription ends. */
19
+ close(): void;
20
+ }
21
+
22
+ /** Where MCP results carry their metadata. */
23
+ const META = "_meta";
24
+
25
+ /** A `resources/read` result marked as the host's cached copy (`STALE_META`). */
26
+ export function markedStale(value: unknown): unknown {
27
+ const result =
28
+ value !== null && typeof value === "object" ? (value as Record<string, unknown>) : {};
29
+ const given = result[META];
30
+ const meta =
31
+ given !== null && typeof given === "object" ? (given as Record<string, unknown>) : {};
32
+ return { ...result, [META]: { ...meta, [STALE_META]: true } };
33
+ }
34
+
35
+ /**
36
+ * `updated(uri)` sends the frame `notifications/resources/updated`; it is called only for a URI
37
+ * the frame subscribes to.
38
+ */
39
+ export function liveData(
40
+ bridge: HostFunctionBridge,
41
+ updated: (uri: string) => void,
42
+ options: { readonly userActivated?: () => boolean | undefined } = {},
43
+ ): LiveData {
44
+ const subscriptions = new Map<string, AbortController>();
45
+ const fresh = new Map<string, unknown>();
46
+ let closed = false;
47
+ const tell = (uri: string) => {
48
+ if (!closed && subscriptions.has(uri)) {
49
+ updated(uri);
50
+ }
51
+ };
52
+ const activation = () => {
53
+ const userActivated = options.userActivated?.();
54
+ return userActivated === undefined ? {} : { userActivated };
55
+ };
56
+ const end = (uri: string) => {
57
+ subscriptions.get(uri)?.abort();
58
+ subscriptions.delete(uri);
59
+ fresh.delete(uri);
60
+ };
61
+
62
+ return {
63
+ async read(uri) {
64
+ if (typeof uri === "string" && fresh.has(uri)) {
65
+ const value = fresh.get(uri);
66
+ fresh.delete(uri);
67
+ return { ok: true, value };
68
+ }
69
+ const subscribed = typeof uri === "string" && subscriptions.has(uri);
70
+ const outcome = await bridge.call(
71
+ "readData",
72
+ { uri },
73
+ { ...activation(), stale: subscribed },
74
+ );
75
+ if (!outcome.ok || outcome.stale !== true || typeof uri !== "string") {
76
+ return outcome;
77
+ }
78
+ // Answered from the host's cache: the fresh result, for the frame's next read, is told once
79
+ // it is here.
80
+ void bridge.call("readData", { uri }, activation()).then((next) => {
81
+ if (next.ok && !closed && subscriptions.has(uri)) {
82
+ fresh.set(uri, next.value);
83
+ tell(uri);
84
+ }
85
+ });
86
+ return { ok: true, value: markedStale(outcome.value) };
87
+ },
88
+
89
+ async subscribe(uri) {
90
+ if (typeof uri === "string" && subscriptions.has(uri)) {
91
+ return { ok: true, value: undefined };
92
+ }
93
+ const controller = new AbortController();
94
+ if (typeof uri === "string") {
95
+ subscriptions.set(uri, controller);
96
+ }
97
+ const outcome = await bridge.call(
98
+ "subscribeData",
99
+ { uri },
100
+ {
101
+ ...activation(),
102
+ subscription: {
103
+ signal: controller.signal,
104
+ changed: (result?: unknown) => {
105
+ if (controller.signal.aborted || closed || typeof uri !== "string") {
106
+ return;
107
+ }
108
+ if (result !== undefined) {
109
+ fresh.set(uri, result);
110
+ }
111
+ tell(uri);
112
+ },
113
+ },
114
+ },
115
+ );
116
+ if (!outcome.ok) {
117
+ controller.abort();
118
+ if (typeof uri === "string" && subscriptions.get(uri) === controller) {
119
+ subscriptions.delete(uri);
120
+ }
121
+ }
122
+ return outcome;
123
+ },
124
+
125
+ unsubscribe(uri) {
126
+ if (typeof uri === "string") {
127
+ end(uri);
128
+ }
129
+ },
130
+
131
+ close() {
132
+ closed = true;
133
+ for (const uri of subscriptions.keys()) {
134
+ end(uri);
135
+ }
136
+ },
137
+ };
138
+ }
@@ -17,6 +17,10 @@ export const MCP_APPS_METHODS = {
17
17
  updateModelContext: "ui/update-model-context",
18
18
  callTool: "tools/call",
19
19
  readResource: "resources/read",
20
+ // MCP's own resource subscriptions (P079), which MCP Apps doesn't list: the view is the host's
21
+ // MCP client here, as for resources/read.
22
+ subscribeResource: "resources/subscribe",
23
+ unsubscribeResource: "resources/unsubscribe",
20
24
  // View → host notifications.
21
25
  initialized: "ui/notifications/initialized",
22
26
  sizeChanged: "ui/notifications/size-changed",
@@ -28,6 +32,7 @@ export const MCP_APPS_METHODS = {
28
32
  toolResult: "ui/notifications/tool-result",
29
33
  toolCancelled: "ui/notifications/tool-cancelled",
30
34
  hostContextChanged: "ui/notifications/host-context-changed",
35
+ resourceUpdated: "notifications/resources/updated",
31
36
  // Host → view requests.
32
37
  resourceTeardown: "ui/resource-teardown",
33
38
  // Sandbox proxy (a second origin that relays between host and view).
@@ -121,6 +126,13 @@ export const PORTHOLE_STYLES = "porthole/styles";
121
126
  */
122
127
  export const COPY_TEXT_METHOD = "porthole/copy-text";
123
128
 
129
+ /**
130
+ * The `_meta` key that marks a `resources/read` result as the host's cached copy (P079): stale,
131
+ * with the fresh one to follow as `notifications/resources/updated`. Only for a resource the view
132
+ * subscribes to.
133
+ */
134
+ export const STALE_META = "porthole/stale";
135
+
124
136
  /** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
125
137
  export const SHELL_LOGGER = "porthole";
126
138
 
@@ -14,6 +14,7 @@ import {
14
14
  MCP_APPS_PROTOCOL_VERSION,
15
15
  type HostContext,
16
16
  } from "./mcp-apps.ts";
17
+ import { liveData } from "./live-data.ts";
17
18
 
18
19
  /**
19
20
  * The core's adapter: the host side of the MCP Apps subset the shell speaks, which content using
@@ -56,7 +57,6 @@ const REQUESTS: Readonly<
56
57
  capability: "callTool",
57
58
  args: (params) => ({ name: params.name, arguments: params.arguments }),
58
59
  },
59
- [M.readResource]: { capability: "readData", args: (params) => ({ uri: params.uri }) },
60
60
  [M.updateModelContext]: {
61
61
  capability: "setModelContext",
62
62
  args: (params) => ({ content: params.content, structuredContent: params.structuredContent }),
@@ -102,7 +102,8 @@ export function hostCapabilities(
102
102
  offered.serverTools = {};
103
103
  }
104
104
  if (declared("readData")) {
105
- offered.serverResources = {};
105
+ // MCP's own flag for resources/subscribe (P079), in the field that mirrors MCP's capability.
106
+ offered.serverResources = declared("subscribeData") ? { subscribe: true } : {};
106
107
  }
107
108
  if (declared("setModelContext")) {
108
109
  offered.updateModelContext = { text: {} };
@@ -124,7 +125,6 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
124
125
  let sentWhole = false;
125
126
  let nextId = 1;
126
127
  const pending = new Map<JsonRpcId, (response: JsonRpcResponse) => void>();
127
-
128
128
  const respond = (
129
129
  id: JsonRpcId,
130
130
  body: { result: unknown } | { error: { code: number; message: string } },
@@ -132,6 +132,9 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
132
132
  const notify = (method: string, params: Record<string, unknown>) =>
133
133
  transport.send({ jsonrpc: "2.0", method, params });
134
134
 
135
+ // Live data (P079): reads, subscriptions and the host's updates, through the bridge.
136
+ const live = liveData(bridge, (uri) => notify(M.resourceUpdated, { uri }));
137
+
135
138
  const flush = () => {
136
139
  if (!initialized || closed || content === null || sentWhole) {
137
140
  return;
@@ -168,6 +171,34 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
168
171
  respond(request.id, { result: { mode: "inline" } });
169
172
  return;
170
173
  }
174
+ if (request.method === M.readResource) {
175
+ const outcome = await live.read(params.uri);
176
+ if (!closed) {
177
+ respond(request.id, answer("readData", outcome));
178
+ }
179
+ return;
180
+ }
181
+ if (request.method === M.subscribeResource || request.method === M.unsubscribeResource) {
182
+ if (!bridge.declared("subscribeData")) {
183
+ respond(request.id, {
184
+ error: {
185
+ code: JSON_RPC_ERRORS.methodNotFound,
186
+ message: `${request.method} isn't offered here`,
187
+ },
188
+ });
189
+ return;
190
+ }
191
+ if (request.method === M.subscribeResource) {
192
+ const outcome = await live.subscribe(params.uri);
193
+ if (!closed) {
194
+ respond(request.id, outcome.ok ? { result: {} } : answer("subscribeData", outcome));
195
+ }
196
+ } else {
197
+ live.unsubscribe(params.uri);
198
+ respond(request.id, { result: {} });
199
+ }
200
+ return;
201
+ }
171
202
  const mapped = REQUESTS[request.method];
172
203
  if (mapped === undefined) {
173
204
  respond(request.id, {
@@ -264,6 +295,7 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
264
295
  closed = true;
265
296
  stop();
266
297
  pending.clear();
298
+ live.close();
267
299
  },
268
300
  };
269
301
  },
@@ -66,6 +66,8 @@ function words(request: ConfirmRequest): Words {
66
66
  return { heading: "Share this with the agent?", accept: "Share", detail: json(request.args) };
67
67
  case "readData":
68
68
  return { heading: "Let it read this?", accept: "Allow", detail: request.args.uri };
69
+ case "subscribeData":
70
+ return { heading: "Let it follow this?", accept: "Allow", detail: request.args.uri };
69
71
  case "copyText":
70
72
  return { heading: "Copy this text?", accept: "Copy", detail: request.args.text };
71
73
  default:
@@ -22,6 +22,8 @@ import type {
22
22
  Confirm,
23
23
  ConfirmAnswer,
24
24
  ConfirmRequest,
25
+ Consent,
26
+ DataCache,
25
27
  Proceed,
26
28
  Refusal,
27
29
  } from "../bridge/types.ts";
@@ -61,6 +63,9 @@ interface PageState {
61
63
  /** Heights displays reported, by display id: a frame mounting again starts at its last. */
62
64
  readonly heights: Map<string, number>;
63
65
  readonly confirm?: Confirm;
66
+ /** The provider's consent and cache (P079), read when a frame asks. */
67
+ readonly consent?: Consent;
68
+ readonly cached?: DataCache;
64
69
  readonly hostInfo?: { readonly name: string; readonly version: string };
65
70
  readonly nonce?: string;
66
71
  /** The provider's locator, read when a frame locates (so an inline one restarts nothing). */
@@ -120,6 +125,13 @@ export interface PortholeProviderProps {
120
125
  * Pass your own function to replace it.
121
126
  */
122
127
  readonly confirm?: Confirm;
128
+ /**
129
+ * Whether a frame below may make its `consent`-gated calls (read the viewer's data, P079):
130
+ * asked once per display, before the first. Omitted: those calls are refused.
131
+ */
132
+ readonly consent?: Consent;
133
+ /** What the host last had for a resource, answered stale first (P079). */
134
+ readonly cached?: DataCache;
123
135
  /** How the host names itself in the handshake. */
124
136
  readonly hostInfo?: { readonly name: string; readonly version: string };
125
137
  /** Where domain and external frames load from (see `InstanceLocator`). */
@@ -185,6 +197,17 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
185
197
  ),
186
198
  [],
187
199
  );
200
+ // The host's consent and cache as of the last render (P079), read when a frame asks.
201
+ const ownConsent = useRef(props.consent);
202
+ const ownCached = useRef(props.cached);
203
+ useLayoutEffect(() => {
204
+ ownConsent.current = props.consent;
205
+ ownCached.current = props.cached;
206
+ });
207
+ const consent = useCallback<Consent>((request) => ownConsent.current?.(request) ?? false, []);
208
+ const cached = useCallback<DataCache>((args, context) => ownCached.current?.(args, context), []);
209
+ const consents = props.consent !== undefined;
210
+ const caches = props.cached !== undefined;
188
211
  // The default copyText: the host's page writes the clipboard (in the frame's click, which
189
212
  // activated this page too) and shows the person what went on it, or offers to copy it.
190
213
  const [notice, setNotice] = useState<CopyNotice | null>(null);
@@ -260,6 +283,8 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
260
283
  heights,
261
284
  confirm,
262
285
  copyText,
286
+ ...(consents ? { consent } : {}),
287
+ ...(caches ? { cached } : {}),
263
288
  ...(hostInfo === undefined ? {} : { hostInfo }),
264
289
  ...(locates ? { locate } : {}),
265
290
  ...(nonce === undefined ? {} : { nonce }),
@@ -274,6 +299,10 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
274
299
  heights,
275
300
  confirm,
276
301
  copyText,
302
+ consents,
303
+ consent,
304
+ caches,
305
+ cached,
277
306
  hostInfo,
278
307
  locates,
279
308
  locate,
@@ -372,6 +401,10 @@ export interface PortholeFrameProps {
372
401
  readonly handlers?: CapabilityHandlers;
373
402
  /** Who confirms this frame's gated calls, over the provider's. */
374
403
  readonly confirm?: Confirm;
404
+ /** Whether this frame may make its `consent`-gated calls, over the provider's (P079). */
405
+ readonly consent?: Consent;
406
+ /** This frame's data cache, over the provider's (P079). */
407
+ readonly cached?: DataCache;
375
408
  /** Bump to run the content again from the start. */
376
409
  readonly generation?: number;
377
410
  /** Run at once, without waiting to near the screen (it still counts toward the page's most). */
@@ -620,6 +653,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
620
653
  handlers: pageHandlers,
621
654
  copyText: pageCopyText,
622
655
  confirm: pageConfirm,
656
+ consent: pageConsent,
657
+ cached: pageCached,
623
658
  hostInfo,
624
659
  locate,
625
660
  nonce,
@@ -710,6 +745,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
710
745
  }
711
746
  }
712
747
  const asks = first.confirm !== undefined || pageConfirm !== undefined;
748
+ const asksConsent = first.consent !== undefined || pageConsent !== undefined;
749
+ const caches = first.cached !== undefined || pageCached !== undefined;
713
750
  let display: DisplayHandle;
714
751
  try {
715
752
  display = createHost(config, {
@@ -730,6 +767,21 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
730
767
  ),
731
768
  }
732
769
  : {}),
770
+ ...(asksConsent
771
+ ? {
772
+ consent: (request: ConfirmRequest) =>
773
+ (latest().consent ?? pageConsent ?? (() => false))({
774
+ ...request,
775
+ display: { ...request.display, id: latest().displayId, title: latest().title },
776
+ }),
777
+ }
778
+ : {}),
779
+ ...(caches
780
+ ? {
781
+ cached: (args: { readonly uri: string }, context: CallContext) =>
782
+ (latest().cached ?? pageCached)?.(args, named(context)),
783
+ }
784
+ : {}),
733
785
  theme: (each) => (latest().theme ?? latestPage().theme)?.(each) ?? {},
734
786
  ...(hostInfo === undefined ? {} : { hostInfo }),
735
787
  ...(locate === undefined ? {} : { locator: { locate } }),
@@ -785,6 +837,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
785
837
  pageHandlers,
786
838
  pageCopyText,
787
839
  pageConfirm,
840
+ pageConsent,
841
+ pageCached,
788
842
  hostInfo,
789
843
  locate,
790
844
  nonce,
@@ -0,0 +1,28 @@
1
+ import { LIBRARY_FILES } from "../libraries/files.generated.ts";
2
+ import { LIBRARY_PATH } from "../libraries/libraries.ts";
3
+
4
+ /**
5
+ * Porthole's vendored libraries (P079), as every content origin serves them under `LIBRARY_PATH`:
6
+ * fixed files, the same for everyone, so no ticket or cookie is asked for and they may be cached
7
+ * for good (a path's bytes never change). Same-site only: content origins load them, no one else.
8
+ * Null for any other path (the reserved prefix's 404 answers it).
9
+ */
10
+ export function libraryFile(pathname: string, method: string): Response | null {
11
+ if (!pathname.startsWith(LIBRARY_PATH) || (method !== "GET" && method !== "HEAD")) {
12
+ return null;
13
+ }
14
+ const body = Object.hasOwn(LIBRARY_FILES, pathname) ? LIBRARY_FILES[pathname] : undefined;
15
+ if (body === undefined) {
16
+ return null;
17
+ }
18
+ return new Response(method === "HEAD" ? null : body, {
19
+ headers: {
20
+ "content-type": pathname.endsWith(".js")
21
+ ? "text/javascript; charset=utf-8"
22
+ : "text/plain; charset=utf-8",
23
+ "cache-control": "public, max-age=31536000, immutable",
24
+ "cross-origin-resource-policy": "same-site",
25
+ "x-content-type-options": "nosniff",
26
+ },
27
+ });
28
+ }
@@ -12,6 +12,7 @@ import { base32, createKeys, newTicket, ticketId } from "./keys.ts";
12
12
  import { randomBytes } from "./crypto.ts";
13
13
  import { isHostLabel, reservedLabels } from "./naming.ts";
14
14
  import { enterPage, pageScript, SESSION_PATH, statusPage } from "./pages.ts";
15
+ import { libraryFile } from "./libraries.ts";
15
16
  import type { FrameBlock } from "../host/types.ts";
16
17
  import { memoryTicketStore } from "./tickets.ts";
17
18
  import type {
@@ -1156,7 +1157,7 @@ export function createServer(options: ServerOptions): PortholeServer {
1156
1157
  if (url.pathname === ENTRY_PATH && authorizeUrl !== null) {
1157
1158
  return await redeem(request, url, label);
1158
1159
  }
1159
- const script = pageScript(url.pathname);
1160
+ const script = pageScript(url.pathname) ?? libraryFile(url.pathname, method);
1160
1161
  if (script !== null) {
1161
1162
  return script;
1162
1163
  }