@botiverse/porthole 0.4.1 → 0.5.1

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 (77) hide show
  1. package/README.md +3 -1
  2. package/dist/bridge/bridge.d.ts +24 -2
  3. package/dist/bridge/bridge.js +102 -17
  4. package/dist/bridge/navigation.d.ts +11 -0
  5. package/dist/bridge/navigation.js +30 -0
  6. package/dist/bridge/refusal.d.ts +53 -0
  7. package/dist/bridge/refusal.js +121 -0
  8. package/dist/bridge/types.d.ts +51 -6
  9. package/dist/check/lint.js +2 -2
  10. package/dist/check/page-source.js +1 -1
  11. package/dist/check/page.js +10 -0
  12. package/dist/compile/policy.d.ts +5 -0
  13. package/dist/compile/policy.js +18 -1
  14. package/dist/config/capabilities.d.ts +30 -2
  15. package/dist/config/capabilities.js +13 -0
  16. package/dist/config/schema.d.ts +7 -0
  17. package/dist/config/validate.js +14 -3
  18. package/dist/conformance/harness/page.js +1 -0
  19. package/dist/conformance/harness-source.js +1 -1
  20. package/dist/displays/displays.d.ts +1 -1
  21. package/dist/guide/guide.js +58 -8
  22. package/dist/host/create-host.js +18 -3
  23. package/dist/host/types.d.ts +25 -1
  24. package/dist/index.d.ts +5 -3
  25. package/dist/index.js +4 -1
  26. package/dist/libraries/files.generated.d.ts +1 -0
  27. package/dist/libraries/files.generated.js +8 -0
  28. package/dist/libraries/libraries.d.ts +36 -0
  29. package/dist/libraries/libraries.js +40 -0
  30. package/dist/mcp/adapter.js +49 -5
  31. package/dist/presets/presets.d.ts +15 -0
  32. package/dist/presets/presets.js +27 -2
  33. package/dist/protocol/live-data.d.ts +27 -0
  34. package/dist/protocol/live-data.js +98 -0
  35. package/dist/protocol/mcp-apps.d.ts +15 -0
  36. package/dist/protocol/mcp-apps.js +17 -0
  37. package/dist/protocol/shell-adapter.js +49 -4
  38. package/dist/react/dialog.js +2 -0
  39. package/dist/react/frame.d.ts +30 -1
  40. package/dist/react/frame.js +63 -1
  41. package/dist/server/libraries.d.ts +7 -0
  42. package/dist/server/libraries.js +27 -0
  43. package/dist/server/server.js +2 -1
  44. package/dist/shell/runtime.d.ts +5 -1
  45. package/dist/shell/runtime.js +196 -6
  46. package/docs/ADOPTING.md +89 -3
  47. package/docs/DECISIONS.md +221 -0
  48. package/docs/DESIGN.md +28 -10
  49. package/package.json +3 -1
  50. package/src/bridge/bridge.ts +136 -16
  51. package/src/bridge/navigation.ts +34 -0
  52. package/src/bridge/refusal.ts +151 -0
  53. package/src/bridge/types.ts +57 -4
  54. package/src/check/lint.ts +2 -1
  55. package/src/check/page.ts +12 -0
  56. package/src/compile/policy.ts +19 -1
  57. package/src/config/capabilities.ts +26 -1
  58. package/src/config/schema.ts +7 -0
  59. package/src/config/validate.ts +21 -3
  60. package/src/conformance/harness/page.ts +1 -0
  61. package/src/displays/displays.ts +1 -1
  62. package/src/guide/guide.ts +71 -7
  63. package/src/host/create-host.ts +19 -3
  64. package/src/host/types.ts +23 -1
  65. package/src/index.ts +22 -0
  66. package/src/libraries/files.generated.ts +8 -0
  67. package/src/libraries/libraries.ts +64 -0
  68. package/src/mcp/adapter.ts +63 -5
  69. package/src/presets/presets.ts +46 -3
  70. package/src/protocol/live-data.ts +138 -0
  71. package/src/protocol/mcp-apps.ts +19 -0
  72. package/src/protocol/shell-adapter.ts +50 -5
  73. package/src/react/dialog.tsx +2 -0
  74. package/src/react/frame.tsx +93 -0
  75. package/src/server/libraries.ts +28 -0
  76. package/src/server/server.ts +2 -1
  77. package/src/shell/runtime.ts +196 -6
@@ -0,0 +1,34 @@
1
+ import type { PortholeConfig } from "../config/schema.ts";
2
+
3
+ /**
4
+ * A navigation the shell cancelled (P079), as the host is told it (P080): the address, whole, on
5
+ * the `navigationBlocked` event (the host's to keep), and a sentence for the content's errors
6
+ * (`contentError`, which a host may give the agent that wrote it) that names the address without
7
+ * its query or fragment, where a viewer's data would be.
8
+ */
9
+
10
+ /** An address without what could carry data: an http(s) one's origin and path, else its scheme. */
11
+ export function addressWithoutQuery(url: string): string {
12
+ let parsed: URL;
13
+ try {
14
+ parsed = new URL(url);
15
+ } catch {
16
+ return "another address";
17
+ }
18
+ if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
19
+ return `a ${parsed.protocol} address`;
20
+ }
21
+ const rest = parsed.search !== "" || parsed.hash !== "" ? "?…" : "";
22
+ return `${parsed.origin}${parsed.pathname}${rest}`;
23
+ }
24
+
25
+ /** What the content's errors say about a navigation the shell cancelled. */
26
+ export function blockedNavigationMessage(url: string, config: PortholeConfig): string {
27
+ const links =
28
+ config.capabilities.openLink === undefined
29
+ ? ""
30
+ : config.mode === "mcp-app"
31
+ ? " Open links with ui/open-link (a new tab)."
32
+ : " Open links with openLink(url) or an <a href> (a new tab).";
33
+ return `It tried to navigate its frame to ${addressWithoutQuery(url)}, and was stopped: content never leaves its page.${links}`;
34
+ }
@@ -0,0 +1,151 @@
1
+ import type { CapabilityName } from "../config/capabilities.ts";
2
+ import type { Refusal } from "./types.ts";
3
+
4
+ /**
5
+ * Why a call was refused, as content is told (P080): a code it can branch on and a sentence it can
6
+ * show the person viewing it. Carried in a refused request's JSON-RPC error, as its `data`; the
7
+ * shell's globals reject with an error that has both (`error.code`, `error.message`).
8
+ *
9
+ * - `consent_required`: the viewer hasn't allowed it yet (their answer is still to come).
10
+ * - `denied`: the viewer (or the person asked to confirm) said no.
11
+ * - `rate_limited`: too many calls this minute.
12
+ * - `not_allowed`: the host doesn't let this content have it, here or at all (a URI it doesn't
13
+ * serve, a page where data never runs).
14
+ * - `failed`: the host tried and couldn't.
15
+ */
16
+ export const REFUSAL_CODES = [
17
+ "consent_required",
18
+ "denied",
19
+ "rate_limited",
20
+ "not_allowed",
21
+ "failed",
22
+ ] as const;
23
+
24
+ export type RefusalCode = (typeof REFUSAL_CODES)[number];
25
+
26
+ /** What content is told about a refusal: the JSON-RPC error's `data`. */
27
+ export interface RefusalReason {
28
+ readonly code: RefusalCode;
29
+ /** A sentence for the person viewing the content: the host's, else Porthole's. */
30
+ readonly message: string;
31
+ }
32
+
33
+ /** The most a refusal's message carries to content. */
34
+ const MAX_MESSAGE = 500;
35
+
36
+ export function isRefusalCode(value: unknown): value is RefusalCode {
37
+ return typeof value === "string" && (REFUSAL_CODES as readonly string[]).includes(value);
38
+ }
39
+
40
+ /**
41
+ * A refusal the host gives, with the reason content is told (P080). Throw it from a handler (this
42
+ * URI isn't one you serve: `not_allowed`; the viewer didn't allow this kind of data: `denied`), or
43
+ * from a `consent` function (kept as the display's answer, as `false` is). Or pass one as
44
+ * `HostOptions.consent` itself: every `consent`-gated call is refused with it, and those
45
+ * capabilities need no handler (a page where data never runs).
46
+ *
47
+ * Any other error a handler throws is `failed` with Porthole's words: its message stays the host's.
48
+ */
49
+ export class Refused extends Error {
50
+ readonly code: RefusalCode;
51
+
52
+ /** `message`: a sentence for the viewer; absent, Porthole's for the code. */
53
+ constructor(code: RefusalCode, message?: string) {
54
+ if (!isRefusalCode(code)) {
55
+ throw new TypeError(`Refused: code must be one of ${REFUSAL_CODES.join(", ")}`);
56
+ }
57
+ super(message === undefined || message.trim() === "" ? DEFAULT_MESSAGES[code] : message);
58
+ this.name = "Refused";
59
+ this.code = code;
60
+ }
61
+ }
62
+
63
+ /**
64
+ * Whether `value` is a `Refused`: by class, or by shape where two copies of Porthole meet (a
65
+ * host's bundle and a library's).
66
+ */
67
+ export function isRefused(value: unknown): value is Refused {
68
+ return (
69
+ value instanceof Refused ||
70
+ (value instanceof Error &&
71
+ value.name === "Refused" &&
72
+ isRefusalCode((value as { code?: unknown }).code))
73
+ );
74
+ }
75
+
76
+ /** The reason a host's `Refused` gives content. */
77
+ export function reasonOf(refused: Refused): RefusalReason {
78
+ const message = refused.message.trim();
79
+ return {
80
+ code: refused.code,
81
+ message: (message === "" ? DEFAULT_MESSAGES[refused.code] : message).slice(0, MAX_MESSAGE),
82
+ };
83
+ }
84
+
85
+ /** Porthole's sentence for each code, where the host gave none. */
86
+ const DEFAULT_MESSAGES: { readonly [Code in RefusalCode]: string } = {
87
+ consent_required: "This needs your permission first.",
88
+ denied: "You didn't allow this.",
89
+ rate_limited: "Too many requests: try again in a minute.",
90
+ not_allowed: "This isn't available here.",
91
+ failed: "The app couldn't do this.",
92
+ };
93
+
94
+ /** Where a data capability's words differ: they name the data. */
95
+ const DATA_MESSAGES: { readonly [Code in RefusalCode]: string } = {
96
+ consent_required: "Reading this data needs your permission first.",
97
+ denied: "You didn't allow this to read your data.",
98
+ rate_limited: "Too many data requests: try again in a minute.",
99
+ not_allowed: "This data isn't available here.",
100
+ failed: "The app couldn't get this data.",
101
+ };
102
+
103
+ /** Each refusal's code, as content is told it. */
104
+ const CODES: { readonly [R in Refusal]: RefusalCode } = {
105
+ "not-declared": "not_allowed",
106
+ invalid: "not_allowed",
107
+ "no-user-activation": "not_allowed",
108
+ "no-confirm": "not_allowed",
109
+ declined: "denied",
110
+ redirected: "denied",
111
+ muted: "denied",
112
+ "no-consent": "not_allowed",
113
+ denied: "denied",
114
+ "rate-limited": "rate_limited",
115
+ failed: "failed",
116
+ };
117
+
118
+ /** Refusals whose own words say more than their code's. */
119
+ const OWN_MESSAGES: { readonly [R in Refusal]?: string } = {
120
+ "no-user-activation": "This needs a click.",
121
+ invalid: "The app can't take this request.",
122
+ muted: "You declined this too often: it isn't asked again until it runs again.",
123
+ };
124
+
125
+ /** What content is told about a refusal Porthole made (the host gave no `Refused`). */
126
+ export function defaultReason(capability: CapabilityName, refusal: Refusal): RefusalReason {
127
+ const code = CODES[refusal];
128
+ const data = capability === "readData" || capability === "subscribeData";
129
+ return {
130
+ code,
131
+ message: OWN_MESSAGES[refusal] ?? (data ? DATA_MESSAGES : DEFAULT_MESSAGES)[code],
132
+ };
133
+ }
134
+
135
+ /** What content is told about a refused call: the bridge's reason, else Porthole's for it. */
136
+ export function reasonFor(
137
+ capability: CapabilityName,
138
+ outcome: { readonly refusal: Refusal; readonly reason?: RefusalReason },
139
+ ): RefusalReason {
140
+ const reason = outcome.reason ?? defaultReason(capability, outcome.refusal);
141
+ return { code: reason.code, message: reason.message };
142
+ }
143
+
144
+ /** A consent function that failed (threw, rejected): not an answer, so asked again at the next. */
145
+ export function pendingReason(capability: CapabilityName): RefusalReason {
146
+ const data = capability === "readData" || capability === "subscribeData";
147
+ return {
148
+ code: "consent_required",
149
+ message: (data ? DATA_MESSAGES : DEFAULT_MESSAGES).consent_required,
150
+ };
151
+ }
@@ -5,6 +5,7 @@ import type {
5
5
  HandledCapability,
6
6
  } from "../config/capabilities.ts";
7
7
  import type { InstanceRef } from "../isolation/types.ts";
8
+ import type { RefusalReason } from "./refusal.ts";
8
9
 
9
10
  /**
10
11
  * The host-function bridge (ARCHITECTURE § Framework layer): carries a capability call from the
@@ -23,12 +24,43 @@ export interface CallContext {
23
24
 
24
25
  export type CapabilityHandler<N extends CapabilityName> = (
25
26
  args: CapabilityArgs[N],
26
- context: CallContext,
27
+ context: N extends "subscribeData" ? SubscriptionContext : CallContext,
27
28
  ) => CapabilityResults[N] | Promise<CapabilityResults[N]>;
28
29
 
30
+ /**
31
+ * A subscription's context (`subscribeData`, P079): how the host tells the content its resource
32
+ * changed, and when to stop.
33
+ */
34
+ export interface SubscriptionContext extends CallContext {
35
+ /**
36
+ * The resource changed: the content is told (`notifications/resources/updated`) and reads it
37
+ * again. Pass the new `resources/read` result to answer that read without another call to
38
+ * `readData`.
39
+ */
40
+ readonly changed: (result?: unknown) => void;
41
+ /** Aborted when the content unsubscribes, its frame stops, or the display is destroyed. */
42
+ readonly signal: AbortSignal;
43
+ }
44
+
29
45
  /** The host's handlers: one for each declared capability served by a handler. */
30
46
  export type CapabilityHandlers = { readonly [N in HandledCapability]?: CapabilityHandler<N> };
31
47
 
48
+ /**
49
+ * Asked once per display before its first call of a `consent`-gated capability (P079): may this
50
+ * content have them (read the viewer's data)? The request is that first call. A host remembers
51
+ * the answer where it likes (per viewer, per widget); Porthole keeps it for the display's life.
52
+ * `false` is a no (content is told `denied`); a thrown `Refused` is a no with its reason, kept
53
+ * the same way (P080); anything else it throws is no answer yet (`consent_required`), and the next
54
+ * call asks again.
55
+ */
56
+ export type Consent = (request: ConfirmRequest) => boolean | Promise<boolean>;
57
+
58
+ /**
59
+ * What the host last had for a resource (P079), answered at once, marked stale, to a read of a
60
+ * resource the content subscribes to; the fresh result follows as an update. Undefined: none.
61
+ */
62
+ export type DataCache = (args: CapabilityArgs["readData"], context: CallContext) => unknown;
63
+
32
64
  /**
33
65
  * The display a confirmation is for, as the host named it: its id and title, and the instance the
34
66
  * host gave it, served or opaque (P076, P077), so a host can word its dialog from its own records.
@@ -87,13 +119,34 @@ export type Refusal =
87
119
  | "redirected"
88
120
  /** The display was muted after too many declines (until it runs again). */
89
121
  | "muted"
122
+ /** It is `consent`-gated and there is no `consent` function. */
123
+ | "no-consent"
124
+ /** The host's `consent` said no (for this display's life). */
125
+ | "denied"
90
126
  | "rate-limited"
91
127
  /** The host's handler threw or rejected. */
92
128
  | "failed";
93
129
 
94
130
  export type CallOutcome<T> =
95
- | { readonly ok: true; readonly value: T }
96
- | { readonly ok: false; readonly refusal: Refusal; readonly message?: string };
131
+ /** `stale`: a `readData` answered from the host's cache (`DataCache`). */
132
+ | { readonly ok: true; readonly value: T; readonly stale?: true }
133
+ | {
134
+ readonly ok: false;
135
+ readonly refusal: Refusal;
136
+ /** What the host's handler threw: the host's own words, never sent to content. */
137
+ readonly message?: string;
138
+ /** What content is told (P080): the host's `Refused`, else Porthole's for the refusal. */
139
+ readonly reason?: RefusalReason;
140
+ };
141
+
142
+ /** What an adapter adds to a call, beyond what the content sent. */
143
+ export interface CallOptions {
144
+ readonly userActivated?: boolean;
145
+ /** `subscribeData`: the subscription's channel back and its end (`SubscriptionContext`). */
146
+ readonly subscription?: Pick<SubscriptionContext, "changed" | "signal">;
147
+ /** `readData`: the host's cache may answer, marked stale (the content subscribes to it). */
148
+ readonly stale?: boolean;
149
+ }
97
150
 
98
151
  /** What adapters call; one per display. */
99
152
  export interface HostFunctionBridge {
@@ -101,7 +154,7 @@ export interface HostFunctionBridge {
101
154
  call<N extends CapabilityName>(
102
155
  capability: N,
103
156
  args: unknown,
104
- options?: { readonly userActivated?: boolean },
157
+ options?: CallOptions,
105
158
  ): Promise<CallOutcome<CapabilityResults[N]>>;
106
159
  declared(capability: CapabilityName): boolean;
107
160
  }
package/src/check/lint.ts CHANGED
@@ -3,6 +3,7 @@ import {
3
3
  declaredCapabilities,
4
4
  egressOrigins,
5
5
  type EgressKind,
6
+ librarySources,
6
7
  } from "../compile/policy.ts";
7
8
  import type { PortholeConfig } from "../config/schema.ts";
8
9
  import { sizeWords } from "../guide/limits.ts";
@@ -217,7 +218,7 @@ export function lintContent(config: PortholeConfig, content: string): Finding[]
217
218
  add(
218
219
  "egress",
219
220
  "warning",
220
- `Nothing loads from ${origin} here (${kind}): ${kind === "script" || kind === "style" ? "write it inline, or use a library from an allowed CDN" : kind === "connect" ? "the content can't call it; work from data in the content" : "put it inline as a data: URL"}.`,
221
+ `Nothing loads from ${origin} here (${kind}): ${kind === "script" && librarySources(config).length > 0 ? "write it inline, or use one of the libraries served here (the manual's Libraries)" : kind === "script" || kind === "style" ? "write it inline, or use a library from an allowed CDN" : kind === "connect" && config.capabilities.readData !== undefined ? "the content can't call it; read the app's data with readData" : kind === "connect" ? "the content can't call it; work from data in the content" : "put it inline as a data: URL"}.`,
221
222
  match.index,
222
223
  );
223
224
  }
package/src/check/page.ts CHANGED
@@ -4,6 +4,7 @@ import {
4
4
  isCapabilityName,
5
5
  type HandledCapability,
6
6
  } from "../config/capabilities.ts";
7
+ import { addressWithoutQuery } from "../bridge/navigation.ts";
7
8
  import { createHost } from "../host/create-host.ts";
8
9
  import type { PlatformHost } from "../platform/types.ts";
9
10
  import { webPlatform } from "../platform/web.ts";
@@ -35,6 +36,9 @@ const DECLINED: { readonly [N in HandledCapability]: () => unknown } = {
35
36
  readData: () => {
36
37
  throw new Error("The host declined the read");
37
38
  },
39
+ subscribeData: () => {
40
+ throw new Error("The host declined the subscription");
41
+ },
38
42
  };
39
43
 
40
44
  /**
@@ -166,6 +170,8 @@ const check = {
166
170
  handlers: declining(Object.keys(spec.config.capabilities), calls),
167
171
  platform: NOBODY,
168
172
  confirm: () => Promise.resolve("declined"),
173
+ // A viewer who doesn't allow a live widget their data (P079): its calls are refused.
174
+ consent: () => false,
169
175
  // A served config's instance, issued by the check's own server on this page's origin.
170
176
  locator: {
171
177
  locate: async (instance) =>
@@ -204,6 +210,12 @@ const check = {
204
210
  calls.push({ capability, outcome: refusal });
205
211
  }
206
212
  });
213
+ // A navigation the shell stopped (P080): the content tried to leave its page.
214
+ display.on("navigationBlocked", ({ url }) => {
215
+ run.data.errors.push(
216
+ `It tried to navigate its frame to ${addressWithoutQuery(url)}, and was stopped: content never leaves its page`,
217
+ );
218
+ });
207
219
  display.on("outcome", (outcome) => {
208
220
  run.data.outcome = outcome.state === "blocked" ? `blocked: ${outcome.reason}` : outcome.state;
209
221
  });
@@ -1,5 +1,6 @@
1
1
  import { CAPABILITIES, type CapabilityName, type Gate } from "../config/capabilities.ts";
2
2
  import type { PortholeConfig } from "../config/schema.ts";
3
+ import { LIBRARY_PATH } from "../libraries/libraries.ts";
3
4
 
4
5
  /**
5
6
  * The frame's policies, derived from the config: its CSP (in the shell's `<meta>` for opaque
@@ -46,6 +47,16 @@ export function allEgressOrigins(config: PortholeConfig): string[] {
46
47
  return unique(kinds.flatMap((kind) => egressOrigins(config, kind)));
47
48
  }
48
49
 
50
+ /**
51
+ * Where Porthole's vendored libraries load from (`egress.libraries`, P079): their path on the
52
+ * content origins, so the frame's own, path-limited (nothing else served there runs as a script).
53
+ */
54
+ export function librarySources(config: PortholeConfig): string[] {
55
+ return config.egress.libraries === true && config.isolation === "domain"
56
+ ? config.contentOrigins.map((origin) => `${origin}${LIBRARY_PATH}`)
57
+ : [];
58
+ }
59
+
49
60
  const list = (sources: readonly string[]): string[] =>
50
61
  sources.length === 0 ? ["'none'"] : [...sources];
51
62
 
@@ -65,7 +76,14 @@ export function frameCspDirectives(config: PortholeConfig): CspDirective[] {
65
76
  const https = (kind: "img" | "media" | "font") => (anyHttps(config, kind) ? ["https:"] : []);
66
77
  return [
67
78
  ["default-src", "'none'"],
68
- ["script-src", "'unsafe-inline'", "'unsafe-eval'", "blob:", ...origins("script")],
79
+ [
80
+ "script-src",
81
+ "'unsafe-inline'",
82
+ "'unsafe-eval'",
83
+ "blob:",
84
+ ...origins("script"),
85
+ ...librarySources(config),
86
+ ],
69
87
  ["style-src", "'unsafe-inline'", ...origins("style")],
70
88
  ["font-src", "data:", ...https("font"), ...origins("font")],
71
89
  ["img-src", "data:", "blob:", ...https("img"), ...origins("img")],
@@ -16,6 +16,7 @@ export const CAPABILITY_NAMES = [
16
16
  "downloadFile",
17
17
  "callTool",
18
18
  "readData",
19
+ "subscribeData",
19
20
  "setModelContext",
20
21
  "reportError",
21
22
  "resize",
@@ -34,10 +35,15 @@ export type CapabilityName = (typeof CAPABILITY_NAMES)[number];
34
35
  * - `confirm`: the host's `confirm` function shows a person the call's whole effect, and the call
35
36
  * goes only if they accept. No `confirm` function means the call is refused (fail closed).
36
37
  * - `rateLimit`: at most `perMinute` calls per display per minute; the rest are refused.
38
+ * - `consent` (P079): the host's `consent` function is asked once per display, before the first
39
+ * call of any of its consent-gated capabilities, whether this content may have them (a viewer
40
+ * allowing a widget to read their data). A no refuses every such call for the display's life;
41
+ * no `consent` function refuses them all (fail closed).
37
42
  */
38
43
  export type Gate =
39
44
  | "user-activation"
40
45
  | "confirm"
46
+ | "consent"
41
47
  | { readonly rateLimit: { readonly perMinute: number } };
42
48
 
43
49
  export interface CapabilitySpec {
@@ -86,8 +92,20 @@ export const CAPABILITIES = {
86
92
  readData: {
87
93
  defaultGates: [rate(120)],
88
94
  served: "handler",
95
+ global: "readData",
89
96
  request: { method: "resources/read", sdk: "app.readServerResource" },
90
97
  },
98
+ /**
99
+ * Live data (P079): content subscribes to a resource and the host tells it when it changed
100
+ * (MCP `resources/subscribe`, `resources/unsubscribe`, `notifications/resources/updated`);
101
+ * it then reads it again (`readData`, which it needs). The App SDK has no method for it.
102
+ */
103
+ subscribeData: {
104
+ defaultGates: [rate(60)],
105
+ served: "handler",
106
+ global: "subscribeData",
107
+ request: { method: "resources/subscribe" },
108
+ },
91
109
  setModelContext: {
92
110
  defaultGates: [rate(30)],
93
111
  served: "handler",
@@ -124,11 +142,16 @@ export interface CapabilityArgs {
124
142
  readonly arguments: Readonly<Record<string, unknown>>;
125
143
  };
126
144
  readonly readData: { readonly uri: string };
145
+ readonly subscribeData: { readonly uri: string };
127
146
  readonly setModelContext: {
128
147
  readonly content?: readonly unknown[];
129
148
  readonly structuredContent?: Readonly<Record<string, unknown>>;
130
149
  };
131
- readonly reportError: { readonly message: string };
150
+ /**
151
+ * `navigationBlocked`: the address a navigation of the frame went to when the shell cancelled it
152
+ * (P080), the content's word; `message` is then Porthole's, which names it without its query.
153
+ */
154
+ readonly reportError: { readonly message: string; readonly navigationBlocked?: string };
132
155
  readonly resize: { readonly height: number; readonly width?: number };
133
156
  readonly copyText: { readonly text: string };
134
157
  /** What the frame reported, once checked (`AnnotationReport`). */
@@ -144,7 +167,9 @@ export interface CapabilityResults {
144
167
  /** Whether the download started. */
145
168
  readonly downloadFile: boolean;
146
169
  readonly callTool: unknown;
170
+ /** An MCP `resources/read` result (`{ contents }`), as the host answers it. */
147
171
  readonly readData: unknown;
172
+ readonly subscribeData: undefined;
148
173
  readonly setModelContext: undefined;
149
174
  readonly reportError: undefined;
150
175
  readonly resize: undefined;
@@ -67,6 +67,13 @@ export interface EgressConfig {
67
67
  * address and a visit signal reach any site, and data can leave in the URL.
68
68
  */
69
69
  readonly anyHttps?: readonly PassiveKind[];
70
+ /**
71
+ * Porthole's own copies of a few libraries (`VENDORED_LIBRARIES`: Chart.js, D3), served from the
72
+ * frame's own origin under `/__porthole/lib/` (P079): domain isolation only. They open no
73
+ * channel out: the requests reach the content server, which serves fixed files, so a display
74
+ * with no network of its own (`presets.liveWidget`) still draws charts.
75
+ */
76
+ readonly libraries?: boolean;
70
77
  }
71
78
 
72
79
  /** What `EgressConfig.anyHttps` may open: content that runs nothing (P059). */
@@ -258,12 +258,12 @@ function positive(value: unknown, path: string, max = Number.MAX_SAFE_INTEGER):
258
258
  }
259
259
 
260
260
  function gate(value: unknown, path: string): asserts value is Gate {
261
- if (value === "user-activation" || value === "confirm") {
261
+ if (value === "user-activation" || value === "confirm" || value === "consent") {
262
262
  return;
263
263
  }
264
264
  const limit = isObject(value) && isObject(value.rateLimit) ? value.rateLimit : null;
265
265
  if (limit === null || Object.keys(value as object).length !== 1) {
266
- fail(path, 'must be "user-activation", "confirm" or { rateLimit: { perMinute } }');
266
+ fail(path, 'must be "user-activation", "confirm", "consent" or { rateLimit: { perMinute } }');
267
267
  return;
268
268
  }
269
269
  only(limit, ["perMinute"], `${path}.rateLimit`);
@@ -335,7 +335,7 @@ export function validateConfig(input: unknown): PortholeConfig {
335
335
 
336
336
  const egress = object(config.egress, "config.egress");
337
337
  const kinds = ["connect", "script", "style", "img", "font", "media"];
338
- only(egress, [...kinds, "anyHttps"], "config.egress");
338
+ only(egress, [...kinds, "anyHttps", "libraries"], "config.egress");
339
339
  for (const kind of kinds) {
340
340
  sources(egress[kind], `config.egress.${kind}`);
341
341
  }
@@ -356,6 +356,24 @@ export function validateConfig(input: unknown): PortholeConfig {
356
356
  }
357
357
  }
358
358
 
359
+ if (egress.libraries !== undefined) {
360
+ if (typeof egress.libraries !== "boolean") {
361
+ fail("config.egress.libraries", "must be true or false");
362
+ }
363
+ if (egress.libraries && config.isolation !== "domain") {
364
+ fail(
365
+ "config.egress.libraries",
366
+ "Porthole's libraries are served from the frame's own origin: domain isolation only",
367
+ );
368
+ }
369
+ }
370
+ if (capabilities.subscribeData !== undefined && capabilities.readData === undefined) {
371
+ fail(
372
+ "config.capabilities.subscribeData",
373
+ "needs readData: content reads a resource again when it is told it changed",
374
+ );
375
+ }
376
+
359
377
  const theme = object(config.theme, "config.theme");
360
378
  only(theme, ["variables", "event", "documents"], "config.theme");
361
379
  if (
@@ -84,6 +84,7 @@ function recorder(calls: RecordedCall[]): CapabilityHandlers {
84
84
  downloadFile: record("downloadFile", true),
85
85
  callTool: record("callTool", { content: [] }),
86
86
  readData: record("readData", { contents: [] }),
87
+ subscribeData: record("subscribeData", undefined),
87
88
  setModelContext: record("setModelContext", undefined),
88
89
  copyText: record("copyText", true),
89
90
  };
@@ -22,7 +22,7 @@ import { presets, type PresetOptions, type UrlPresetOptions } from "../presets/p
22
22
 
23
23
  export type DisplayKind =
24
24
  | {
25
- readonly preset: "inlineWidget" | "artifact" | "mcpApp";
25
+ readonly preset: "inlineWidget" | "liveWidget" | "artifact" | "mcpApp";
26
26
  readonly options?: PresetOptions;
27
27
  /** Options added when served on content origins (domain isolation): storage, egress. */
28
28
  readonly served?: Omit<PresetOptions, "isolation" | "contentOrigins">;