@botiverse/porthole 0.5.0 → 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 (42) hide show
  1. package/dist/bridge/bridge.d.ts +12 -4
  2. package/dist/bridge/bridge.js +58 -26
  3. package/dist/bridge/navigation.d.ts +11 -0
  4. package/dist/bridge/navigation.js +30 -0
  5. package/dist/bridge/refusal.d.ts +53 -0
  6. package/dist/bridge/refusal.js +121 -0
  7. package/dist/bridge/types.d.ts +7 -0
  8. package/dist/check/page-source.js +1 -1
  9. package/dist/check/page.js +5 -0
  10. package/dist/config/capabilities.d.ts +5 -0
  11. package/dist/conformance/harness-source.js +1 -1
  12. package/dist/guide/guide.js +14 -4
  13. package/dist/host/create-host.js +15 -4
  14. package/dist/host/types.d.ts +15 -2
  15. package/dist/index.d.ts +2 -1
  16. package/dist/index.js +3 -1
  17. package/dist/mcp/adapter.js +22 -7
  18. package/dist/protocol/mcp-apps.d.ts +6 -0
  19. package/dist/protocol/mcp-apps.js +6 -0
  20. package/dist/protocol/shell-adapter.js +14 -2
  21. package/dist/react/frame.d.ts +19 -4
  22. package/dist/react/frame.js +37 -9
  23. package/dist/shell/runtime.js +34 -8
  24. package/docs/ADOPTING.md +39 -9
  25. package/docs/DECISIONS.md +92 -0
  26. package/docs/DESIGN.md +12 -7
  27. package/package.json +1 -1
  28. package/src/bridge/bridge.ts +70 -22
  29. package/src/bridge/navigation.ts +34 -0
  30. package/src/bridge/refusal.ts +151 -0
  31. package/src/bridge/types.ts +12 -1
  32. package/src/check/page.ts +7 -0
  33. package/src/config/capabilities.ts +5 -1
  34. package/src/guide/guide.ts +18 -4
  35. package/src/host/create-host.ts +16 -4
  36. package/src/host/types.ts +13 -2
  37. package/src/index.ts +9 -0
  38. package/src/mcp/adapter.ts +26 -6
  39. package/src/protocol/mcp-apps.ts +7 -0
  40. package/src/protocol/shell-adapter.ts +15 -2
  41. package/src/react/frame.tsx +53 -14
  42. package/src/shell/runtime.ts +34 -8
@@ -218,7 +218,7 @@ function chart(c) {
218
218
  function gateWords(gates, effect) {
219
219
  const sentences = [];
220
220
  if (gates.includes("consent")) {
221
- sentences.push("The first data call asks the person to allow it; if they don't, every one fails (show that the data isn't allowed, not an error).");
221
+ sentences.push("The first data call asks the person to allow it; if they don't, every one fails with code denied (show that the data isn't allowed, not an error).");
222
222
  }
223
223
  if (gates.includes("confirm")) {
224
224
  sentences.push(`The app shows the person ${effect} first, and nothing happens unless they confirm.`);
@@ -233,6 +233,16 @@ function gateWords(gates, effect) {
233
233
  }
234
234
  return sentences.join(" ");
235
235
  }
236
+ /**
237
+ * What a data refusal tells content (P080): the codes and the sentence, for the author to draw. With
238
+ * the shell's globals they are the error's own fields; without, the JSON-RPC error's data.
239
+ */
240
+ function refusalWords(c, global) {
241
+ const where = global
242
+ ? "The error's code says why"
243
+ : "A refusal is an error whose data is { code, message }; code says why";
244
+ return `${where}: consent_required (not allowed yet), denied (the person said no), rate_limited, not_allowed (not here: some places show the ${c.noun} without data) or failed; ${global ? "its" : ""} message is a sentence for the person. Draw the ${c.noun} without that data, with that sentence where it would be; don't retry in a loop.`.replace(/ {2,}/gu, " ");
245
+ }
236
246
  const ENTRIES = {
237
247
  sendPrompt: (c, gates) => c.global("sendPrompt")
238
248
  ? `- sendPrompt(text): asks to send text to you as the person's message (at most ${c.config.limits.maxPromptChars.toLocaleString("en-US")} characters). Use it for "explain this point", "try these settings". ${gateWords(gates, "the whole text")} It returns a promise: true if it was sent.`
@@ -243,10 +253,10 @@ const ENTRIES = {
243
253
  downloadFile: (_c, gates) => `- Downloads: the MCP Apps request ui/download-file (with the App SDK, app.downloadFile). ${gateWords(gates, "the file")}`,
244
254
  callTool: (_c, gates) => `- Tools: the MCP Apps request tools/call (with the App SDK, app.callServerTool). ${gateWords(gates, "the call")}`,
245
255
  readData: (c, gates) => c.global("readData")
246
- ? `- readData(uri): reads the app's data at uri (a resource the app names), as the person viewing the ${c.noun} may see it, and returns a promise of it: JSON parsed, else text. ${gateWords(gates, "the request")} It rejects when the app refuses or fails: draw the ${c.noun} without that data, saying why.`
247
- : `- Data: the MCP Apps request resources/read (with the App SDK, app.readServerResource). ${gateWords(gates, "the request")}`,
256
+ ? `- readData(uri): reads the app's data at uri (a resource the app names), as the person viewing the ${c.noun} may see it, and returns a promise of it: JSON parsed, else text. ${gateWords(gates, "the request")} It rejects when the app refuses or fails. ${refusalWords(c, true)}`
257
+ : `- Data: the MCP Apps request resources/read (with the App SDK, app.readServerResource). ${gateWords(gates, "the request")} ${refusalWords(c, false)}`,
248
258
  subscribeData: (c, gates) => c.global("subscribeData")
249
- ? `- subscribeData(uri, onData, onError): keeps the ${c.noun} current. It calls onData(value, { stale }) with the data at uri now, and again each time it changes; the first value may be the app's last copy (stale: true), with the current one right after. It returns a function that stops it. onError(error) hears a refusal. ${gateWords(gates, "the request")} Draw from onData every time; don't poll.`
259
+ ? `- subscribeData(uri, onData, onError): keeps the ${c.noun} current. It calls onData(value, { stale }) with the data at uri now, and again each time it changes; the first value may be the app's last copy (stale: true), with the current one right after. It returns a function that stops it. onError(error) hears a refusal, with the same code and message as readData's. ${gateWords(gates, "the request")} Draw from onData every time; don't poll.`
250
260
  : `- Live data: the MCP request resources/subscribe with { uri }; the app then sends notifications/resources/updated with { uri } each time it changes: read it again (resources/read). resources/unsubscribe stops it. ${gateWords(gates, "the request")}`,
251
261
  setModelContext: (_c, gates) => `- Context for the agent: the MCP Apps request ui/update-model-context (with the App SDK, app.updateModelContext). ${gateWords(gates, "it")}`,
252
262
  copyText: (c, gates) => c.global("copyText")
@@ -2,7 +2,8 @@ import { ANNOTATE_METHODS, } from "../annotate/types.js";
2
2
  import { annotateMode, checkMarks, parseReport } from "../annotate/validate.js";
3
3
  import { createBridge, onceConsent } from "../bridge/bridge.js";
4
4
  import { compile } from "../compile/compile.js";
5
- import { declaredCapabilities } from "../compile/policy.js";
5
+ import { declaredCapabilities, effectiveGates } from "../compile/policy.js";
6
+ import { isRefused } from "../bridge/refusal.js";
6
7
  import { capabilitySpec } from "../config/capabilities.js";
7
8
  import { locateServed } from "./locate.js";
8
9
  import { watchOutcome } from "./outcome.js";
@@ -43,8 +44,12 @@ export function createHost(config, options = {}) {
43
44
  compiled,
44
45
  mount(container, mount) {
45
46
  const handlers = { ...options.handlers, ...mount.handlers };
47
+ // A host whose consent is a Refused refuses every consent-gated call before its handler:
48
+ // those need none (P080).
49
+ const refusesAll = isRefused(options.consent);
46
50
  const missing = declaredCapabilities(config).filter((name) => capabilitySpec(name).served === "handler" &&
47
- handlers[name] === undefined);
51
+ handlers[name] === undefined &&
52
+ !(refusesAll && effectiveGates(config, name).includes("consent")));
48
53
  if (missing.length > 0) {
49
54
  throw new TypeError(`No handler for the declared capabilities: ${missing.join(", ")}`);
50
55
  }
@@ -76,8 +81,11 @@ export function createHost(config, options = {}) {
76
81
  let destroyed = false;
77
82
  let restarts = 0;
78
83
  let generation = 0;
79
- // The viewer's answer for this display (P079): asked once, kept across its frames.
80
- const consent = options.consent === undefined ? undefined : onceConsent(options.consent);
84
+ // The viewer's answer for this display (P079): asked once, kept across its frames; or the
85
+ // host's refusal of them all (P080).
86
+ const consent = options.consent === undefined || isRefused(options.consent)
87
+ ? options.consent
88
+ : onceConsent(options.consent);
81
89
  let abort = null;
82
90
  let outcomeWatch = null;
83
91
  let themeFrame = null;
@@ -241,6 +249,9 @@ export function createHost(config, options = {}) {
241
249
  });
242
250
  return;
243
251
  }
252
+ case "navigationBlocked":
253
+ emit("navigationBlocked", { url: event.url });
254
+ return;
244
255
  case "error":
245
256
  contentError(event.message);
246
257
  return;
@@ -1,4 +1,5 @@
1
1
  import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
2
+ import type { Refused } from "../bridge/refusal.ts";
2
3
  import type { Confirm, CapabilityHandlers, Consent, DataCache, Refusal } from "../bridge/types.ts";
3
4
  import type { CompiledConfig } from "../compile/compile.ts";
4
5
  import type { CapabilityName } from "../config/capabilities.ts";
@@ -20,9 +21,11 @@ export interface HostOptions<C extends AdapterConnection = ShellConnection> {
20
21
  /**
21
22
  * Whether a display may make its `consent`-gated calls (read the viewer's data, P079): asked
22
23
  * once per display, before the first, and kept for the display's life (its reloads too).
23
- * Absent: those calls are refused.
24
+ * Absent: those calls are refused. A `Refused` instead of a function refuses every one with its
25
+ * reason, asking nothing, and those capabilities need no handler (a page where live data must
26
+ * not run, P080).
24
27
  */
25
- readonly consent?: Consent;
28
+ readonly consent?: Consent | Refused;
26
29
  /**
27
30
  * What the host last had for a resource (P079): a read of one the content subscribes to is
28
31
  * answered with it at once, marked stale, then with the handler's fresh result.
@@ -160,6 +163,16 @@ export interface DisplayEvents {
160
163
  };
161
164
  /** The content navigated its frame away; the frame was started again from its content. */
162
165
  readonly navigated: undefined;
166
+ /**
167
+ * The shell stopped the content navigating its frame to `url` (P079, P080): the address whole,
168
+ * as the content gave it (its word: untrusted, may carry data in its query). Only where the
169
+ * config declares `reportError` (it counts as one of the run's reports), and only in frames with
170
+ * an origin of their own (served): an opaque frame's navigations get no events. A
171
+ * `contentError` follows, naming the address without its query or fragment.
172
+ */
173
+ readonly navigationBlocked: {
174
+ readonly url: string;
175
+ };
163
176
  /** A call didn't run. */
164
177
  readonly refused: {
165
178
  readonly capability: CapabilityName;
package/dist/index.d.ts CHANGED
@@ -22,7 +22,8 @@ export type { FrameLocation, FrameSource, InstanceLocator, InstanceRef, ServedDo
22
22
  export type { PlatformHost, Surface, SurfaceSpec } from "./platform/types.ts";
23
23
  export type { Transport } from "./transport/types.ts";
24
24
  export type { AdapterConnection, AdapterEvent, AdapterSession, ProtocolAdapter, ShellConnection, } from "./protocol/adapter.ts";
25
- export { COPY_TEXT_METHOD, MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS_STYLE_VARIABLES, PORTHOLE_STYLES, STALE_META, type HostContext, } from "./protocol/mcp-apps.ts";
25
+ export { COPY_TEXT_METHOD, MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS_STYLE_VARIABLES, NAVIGATION_BLOCKED_METHOD, PORTHOLE_STYLES, STALE_META, type HostContext, } from "./protocol/mcp-apps.ts";
26
+ export { REFUSAL_CODES, Refused, isRefused, type RefusalCode, type RefusalReason, } from "./bridge/refusal.ts";
26
27
  export type { CallContext, CallOptions, CallOutcome, CapabilityHandler, CapabilityHandlers, Confirm, ConfirmAnswer, ConfirmDisplay, ConfirmRequest, Consent, DataCache, Proceed, HostFunctionBridge, Refusal, SubscriptionContext, } from "./bridge/types.ts";
27
28
  export { createHost } from "./host/create-host.ts";
28
29
  export { entryTarget, frameFallback, portholeClient, type ContentClientMeta, type FrameFallback, type PortholeClient, type PortholeClientOptions, } from "./host/client.ts";
package/dist/index.js CHANGED
@@ -20,7 +20,9 @@ export { generateGuide, generateToolDescription, } from "./guide/guide.js";
20
20
  export { GUIDE_EXAMPLES } from "./guide/examples.js";
21
21
  // Theme.
22
22
  export { CHART_PALETTE, DEFAULT_THEME, DEFAULT_THEME_EVENT, DEFAULT_THEME_VARIABLES, resolveTheme, themeDefault, } from "./theme/variables.js";
23
- export { COPY_TEXT_METHOD, MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS_STYLE_VARIABLES, PORTHOLE_STYLES, STALE_META, } from "./protocol/mcp-apps.js";
23
+ export { COPY_TEXT_METHOD, MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS_STYLE_VARIABLES, NAVIGATION_BLOCKED_METHOD, PORTHOLE_STYLES, STALE_META, } from "./protocol/mcp-apps.js";
24
+ // Why a call was refused, as content is told it, and the host's own refusals (P080).
25
+ export { REFUSAL_CODES, Refused, isRefused, } from "./bridge/refusal.js";
24
26
  export { createHost } from "./host/create-host.js";
25
27
  // The client half of the host kit, and the display registry (P072).
26
28
  export { entryTarget, frameFallback, portholeClient, } from "./host/client.js";
@@ -1,8 +1,9 @@
1
1
  import { egressOrigins } from "../compile/policy.js";
2
2
  import { JSON_RPC_ERRORS, parseJsonRpc, } from "../protocol/jsonrpc.js";
3
3
  import { MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, } from "../protocol/mcp-apps.js";
4
- import { COPY_TEXT_METHOD, MCP_APPS_STYLE_VARIABLES } from "../protocol/mcp-apps.js";
4
+ import { COPY_TEXT_METHOD, MCP_APPS_STYLE_VARIABLES, NAVIGATION_BLOCKED_METHOD, } from "../protocol/mcp-apps.js";
5
5
  import { liveData } from "../protocol/live-data.js";
6
+ import { reasonFor } from "../bridge/refusal.js";
6
7
  const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
7
8
  /** Levels of `notifications/message` that are errors: they go to the host as `reportError`. */
8
9
  const ERROR_LEVELS = new Set(["error", "critical", "alert", "emergency"]);
@@ -111,10 +112,10 @@ function connect(session, options) {
111
112
  refuse(request.id, JSON_RPC_ERRORS.internal, `${request.method} failed`);
112
113
  return;
113
114
  }
114
- reply(request, outcome, result);
115
+ reply(request, capability, outcome, result);
115
116
  }
116
117
  /** Answers a request with a capability's outcome. */
117
- function reply(request, outcome, result) {
118
+ function reply(request, capability, outcome, result) {
118
119
  if (outcome.ok) {
119
120
  answer(request.id, result(outcome.value));
120
121
  }
@@ -122,8 +123,17 @@ function connect(session, options) {
122
123
  refuse(request.id, JSON_RPC_ERRORS.methodNotFound, `${request.method} isn't offered here`);
123
124
  }
124
125
  else {
125
- // The spec's "implementation-defined" error for a refused request.
126
- refuse(request.id, -32_000, `${request.method} refused (${outcome.refusal})`);
126
+ // The spec's "implementation-defined" error for a refused request, with why in its data
127
+ // (`{ code, message }`, P080).
128
+ send({
129
+ jsonrpc: "2.0",
130
+ id: request.id,
131
+ error: {
132
+ code: -32_000,
133
+ message: `${request.method} refused (${outcome.refusal})`,
134
+ data: reasonFor(capability, outcome),
135
+ },
136
+ });
127
137
  }
128
138
  }
129
139
  /** `{}` when a host function did it, `{ isError: true }` when it said it couldn't. */
@@ -179,7 +189,7 @@ function connect(session, options) {
179
189
  invalid("needs a uri");
180
190
  return;
181
191
  }
182
- reply(request, await live.read(params.uri), (value) => isRecord(value) ? value : { contents: [] });
192
+ reply(request, "readData", await live.read(params.uri), (value) => isRecord(value) ? value : { contents: [] });
183
193
  return;
184
194
  case MCP_APPS_METHODS.subscribeResource:
185
195
  case MCP_APPS_METHODS.unsubscribeResource:
@@ -196,7 +206,7 @@ function connect(session, options) {
196
206
  answer(request.id, {});
197
207
  return;
198
208
  }
199
- reply(request, await live.subscribe(params.uri), () => ({}));
209
+ reply(request, "subscribeData", await live.subscribe(params.uri), () => ({}));
200
210
  return;
201
211
  case MCP_APPS_METHODS.updateModelContext:
202
212
  if ((params.content !== undefined && !Array.isArray(params.content)) ||
@@ -274,6 +284,11 @@ function connect(session, options) {
274
284
  });
275
285
  }
276
286
  return;
287
+ case NAVIGATION_BLOCKED_METHOD:
288
+ // The shell, hardening the view's frame, stopped a navigation (P080): an error report,
289
+ // with its address.
290
+ void bridge.call("reportError", { navigationBlocked: params.url });
291
+ return;
277
292
  case MCP_APPS_METHODS.requestTeardown:
278
293
  session.emit({ type: "teardown-requested" });
279
294
  return;
@@ -61,6 +61,12 @@ export declare const COPY_TEXT_METHOD = "porthole/copy-text";
61
61
  * subscribes to.
62
62
  */
63
63
  export declare const STALE_META = "porthole/stale";
64
+ /**
65
+ * Porthole's own notification from the shell (P080): it cancelled a navigation of the frame to
66
+ * `{ url }` (P079). The content's word, sent only where `reportError` is declared, and counted as
67
+ * one of its reports; the host's adapter carries it into `reportError`.
68
+ */
69
+ export declare const NAVIGATION_BLOCKED_METHOD = "porthole/navigation-blocked";
64
70
  /** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
65
71
  export declare const SHELL_LOGGER = "porthole";
66
72
  /**
@@ -111,5 +111,11 @@ export const COPY_TEXT_METHOD = "porthole/copy-text";
111
111
  * subscribes to.
112
112
  */
113
113
  export const STALE_META = "porthole/stale";
114
+ /**
115
+ * Porthole's own notification from the shell (P080): it cancelled a navigation of the frame to
116
+ * `{ url }` (P079). The content's word, sent only where `reportError` is declared, and counted as
117
+ * one of its reports; the host's adapter carries it into `reportError`.
118
+ */
119
+ export const NAVIGATION_BLOCKED_METHOD = "porthole/navigation-blocked";
114
120
  /** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
115
121
  export const SHELL_LOGGER = "porthole";
@@ -1,5 +1,6 @@
1
1
  import { JSON_RPC_ERRORS, parseJsonRpc, } from "./jsonrpc.js";
2
- import { COPY_TEXT_METHOD, MCP_APPS_METHODS as M, MCP_APPS_PROTOCOL_VERSION, } from "./mcp-apps.js";
2
+ import { reasonFor } from "../bridge/refusal.js";
3
+ import { COPY_TEXT_METHOD, NAVIGATION_BLOCKED_METHOD, MCP_APPS_METHODS as M, MCP_APPS_PROTOCOL_VERSION, } from "./mcp-apps.js";
3
4
  import { liveData } from "./live-data.js";
4
5
  /**
5
6
  * The core's adapter: the host side of the MCP Apps subset the shell speaks, which content using
@@ -52,7 +53,14 @@ function answer(capability, outcome) {
52
53
  if (!outcome.ok) {
53
54
  return flagged
54
55
  ? { result: { isError: true } }
55
- : { error: { code: -32000, message: `Refused (${outcome.refusal})` } };
56
+ : {
57
+ // Why, in the error's data (`{ code, message }`, P080).
58
+ error: {
59
+ code: -32000,
60
+ message: `Refused (${outcome.refusal})`,
61
+ data: reasonFor(capability, outcome),
62
+ },
63
+ };
56
64
  }
57
65
  if (flagged) {
58
66
  return { result: outcome.value === true ? {} : { isError: true } };
@@ -200,6 +208,10 @@ export const shellAdapter = {
200
208
  });
201
209
  }
202
210
  return;
211
+ case NAVIGATION_BLOCKED_METHOD:
212
+ // The shell stopped a navigation (P080): an error report, with its address.
213
+ void bridge.call("reportError", { navigationBlocked: params.url });
214
+ return;
203
215
  case M.requestTeardown:
204
216
  session.emit({ type: "teardown-requested" });
205
217
  return;
@@ -1,6 +1,7 @@
1
1
  import { type CSSProperties, type ReactElement, type ReactNode } from "react";
2
2
  import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
3
3
  import type { CapabilityHandler, CapabilityHandlers, Confirm, ConfirmRequest, Consent, DataCache, Refusal } from "../bridge/types.ts";
4
+ import { Refused, type RefusalReason } from "../bridge/refusal.ts";
4
5
  import type { CapabilityName } from "../config/capabilities.ts";
5
6
  import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
6
7
  import type { FrameOutcome, HostErrorKind } from "../host/types.ts";
@@ -25,6 +26,8 @@ interface PageState {
25
26
  readonly confirm?: Confirm;
26
27
  /** The provider's consent and cache (P079), read when a frame asks. */
27
28
  readonly consent?: Consent;
29
+ /** The provider's consent is a `Refused` (P080): its reason, by value. */
30
+ readonly refusesAll?: RefusalReason;
28
31
  readonly cached?: DataCache;
29
32
  readonly hostInfo?: {
30
33
  readonly name: string;
@@ -82,9 +85,10 @@ export interface PortholeProviderProps {
82
85
  readonly confirm?: Confirm;
83
86
  /**
84
87
  * Whether a frame below may make its `consent`-gated calls (read the viewer's data, P079):
85
- * asked once per display, before the first. Omitted: those calls are refused.
88
+ * asked once per display, before the first. Omitted: those calls are refused. A `Refused`
89
+ * refuses them all with its reason, and their handlers may be left out (P080).
86
90
  */
87
- readonly consent?: Consent;
91
+ readonly consent?: Consent | Refused;
88
92
  /** What the host last had for a resource, answered stale first (P079). */
89
93
  readonly cached?: DataCache;
90
94
  /** How the host names itself in the handshake. */
@@ -149,8 +153,11 @@ export interface PortholeFrameProps {
149
153
  readonly handlers?: CapabilityHandlers;
150
154
  /** Who confirms this frame's gated calls, over the provider's. */
151
155
  readonly confirm?: Confirm;
152
- /** Whether this frame may make its `consent`-gated calls, over the provider's (P079). */
153
- readonly consent?: Consent;
156
+ /**
157
+ * Whether this frame may make its `consent`-gated calls, over the provider's (P079). A `Refused`
158
+ * refuses them all with its reason, and their handlers may be left out (P080).
159
+ */
160
+ readonly consent?: Consent | Refused;
154
161
  /** This frame's data cache, over the provider's (P079). */
155
162
  readonly cached?: DataCache;
156
163
  /** Bump to run the content again from the start. */
@@ -187,6 +194,14 @@ export interface PortholeFrameProps {
187
194
  readonly onError?: (message: string, source: "content" | "host") => void;
188
195
  /** The content navigated its frame away; it was started again (or stopped, after a few). */
189
196
  readonly onNavigated?: () => void;
197
+ /**
198
+ * The shell stopped the content navigating its frame to `url` (P080): the address whole, the
199
+ * content's word. Served frames only, where the config declares `reportError`; `onContentError`
200
+ * hears it too, without the address's query.
201
+ */
202
+ readonly onNavigationBlocked?: (blocked: {
203
+ readonly url: string;
204
+ }) => void;
190
205
  readonly onRefused?: (capability: CapabilityName, refusal: Refusal) => void;
191
206
  /** Too many declines: the display stops asking until it runs again. */
192
207
  readonly onMuted?: () => void;
@@ -1,5 +1,6 @@
1
1
  import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
2
  import { createContext, useCallback, useContext, useEffect, useEffectEvent, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
3
+ import { isRefused, reasonOf, Refused } from "../bridge/refusal.js";
3
4
  import { writeClipboard } from "../host/clipboard.js";
4
5
  import { createHost } from "../host/create-host.js";
5
6
  import { ConfirmDialog } from "./dialog.js";
@@ -52,7 +53,15 @@ export function PortholeProvider(props) {
52
53
  ownConsent.current = props.consent;
53
54
  ownCached.current = props.cached;
54
55
  });
55
- const consent = useCallback((request) => ownConsent.current?.(request) ?? false, []);
56
+ const consent = useCallback((request) => {
57
+ const given = ownConsent.current;
58
+ if (isRefused(given)) {
59
+ throw given;
60
+ }
61
+ return given?.(request) ?? false;
62
+ }, []);
63
+ // A Refused for every frame below, by value (an inline one starts nothing again).
64
+ const refusesAll = useByValue(isRefused(props.consent) ? reasonOf(props.consent) : undefined);
56
65
  const cached = useCallback((args, context) => ownCached.current?.(args, context), []);
57
66
  const consents = props.consent !== undefined;
58
67
  const caches = props.cached !== undefined;
@@ -123,6 +132,7 @@ export function PortholeProvider(props) {
123
132
  confirm,
124
133
  copyText,
125
134
  ...(consents ? { consent } : {}),
135
+ ...(refusesAll === undefined ? {} : { refusesAll }),
126
136
  ...(caches ? { cached } : {}),
127
137
  ...(hostInfo === undefined ? {} : { hostInfo }),
128
138
  ...(locates ? { locate } : {}),
@@ -139,6 +149,7 @@ export function PortholeProvider(props) {
139
149
  copyText,
140
150
  consents,
141
151
  consent,
152
+ refusesAll,
142
153
  caches,
143
154
  cached,
144
155
  hostInfo,
@@ -282,6 +293,10 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
282
293
  const config = useByValue(frame.config);
283
294
  const instance = useByValue(frame.instance);
284
295
  const fills = config.mode === "url" || frame.fill === true || config.layout.kind === "fill";
296
+ // A consent that refuses everything (P080), this frame's or else the provider's, by value: a
297
+ // display made with it needs no data handlers, so a change makes the display again.
298
+ const ownRefusal = useByValue(isRefused(frame.consent) ? reasonOf(frame.consent) : undefined);
299
+ const refusesAll = frame.consent === undefined ? page.refusesAll : ownRefusal;
285
300
  // The latest props, read when the display calls back (never during render).
286
301
  const latest = useEffectEvent(() => frame);
287
302
  // The provider's scheme and theme, read when used: a flip or a new themeKey (a new context
@@ -320,6 +335,9 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
320
335
  case "navigated":
321
336
  frame.onNavigated?.();
322
337
  return;
338
+ case "navigationBlocked":
339
+ frame.onNavigationBlocked?.(detail);
340
+ return;
323
341
  case "refused": {
324
342
  const { capability, refusal } = detail;
325
343
  frame.onRefused?.(capability, refusal);
@@ -386,14 +404,22 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
386
404
  }, proceed),
387
405
  }
388
406
  : {}),
389
- ...(asksConsent
390
- ? {
391
- consent: (request) => (latest().consent ?? pageConsent ?? (() => false))({
392
- ...request,
393
- display: { ...request.display, id: latest().displayId, title: latest().title },
394
- }),
395
- }
396
- : {}),
407
+ ...(refusesAll !== undefined
408
+ ? { consent: new Refused(refusesAll.code, refusesAll.message) }
409
+ : asksConsent
410
+ ? {
411
+ consent: (request) => {
412
+ const given = latest().consent ?? pageConsent ?? (() => false);
413
+ if (isRefused(given)) {
414
+ throw given;
415
+ }
416
+ return given({
417
+ ...request,
418
+ display: { ...request.display, id: latest().displayId, title: latest().title },
419
+ });
420
+ },
421
+ }
422
+ : {}),
397
423
  ...(caches
398
424
  ? {
399
425
  cached: (args, context) => (latest().cached ?? pageCached)?.(args, named(context)),
@@ -423,6 +449,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
423
449
  "resize",
424
450
  "error",
425
451
  "navigated",
452
+ "navigationBlocked",
426
453
  "refused",
427
454
  "muted",
428
455
  "outcome",
@@ -457,6 +484,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
457
484
  pageConfirm,
458
485
  pageConsent,
459
486
  pageCached,
487
+ refusesAll,
460
488
  hostInfo,
461
489
  locate,
462
490
  nonce,
@@ -85,7 +85,9 @@ export const SHELL_RUNTIME = String.raw `(() => {
85
85
  // own getters, kept now, so content can neither stop it nor lie to it. Same-document ones (an
86
86
  // anchor) go on, and so do reloads: the same address, on the frame's own origin (or none, in a
87
87
  // srcdoc frame), which history can change only within that origin. The host's own (a new
88
- // frame) are none of this document's.
88
+ // frame) are none of this document's. Each one stopped is told to the host (P080), as an error
89
+ // report: below, once the shell can speak.
90
+ let navigationBlocked = (_url) => {};
89
91
  const navigationApi = window.navigation;
90
92
  const getterOf = (proto, name) => {
91
93
  const descriptor = proto ? Object.getOwnPropertyDescriptor(proto, name) : undefined;
@@ -94,13 +96,17 @@ export const SHELL_RUNTIME = String.raw `(() => {
94
96
  const navigateProto = typeof NavigateEvent === "function" ? NavigateEvent.prototype : null;
95
97
  const destinationOf = getterOf(navigateProto, "destination");
96
98
  const navigationTypeOf = getterOf(navigateProto, "navigationType");
97
- const sameDocumentOf = getterOf(typeof NavigationDestination === "function" ? NavigationDestination.prototype : null, "sameDocument");
99
+ const destinationProto = typeof NavigationDestination === "function" ? NavigationDestination.prototype : null;
100
+ const sameDocumentOf = getterOf(destinationProto, "sameDocument");
101
+ const urlOf = getterOf(destinationProto, "url");
98
102
  const preventNavigation = Event.prototype.preventDefault;
99
103
  const applyOf = Reflect.apply;
100
104
  if (navigationApi && typeof navigationApi.addEventListener === "function" && destinationOf !== null && sameDocumentOf !== null && navigationTypeOf !== null) {
101
105
  navigationApi.addEventListener("navigate", (event) => {
102
- if (!applyOf(sameDocumentOf, applyOf(destinationOf, event, []), []) && applyOf(navigationTypeOf, event, []) !== "reload") {
106
+ const destination = applyOf(destinationOf, event, []);
107
+ if (!applyOf(sameDocumentOf, destination, []) && applyOf(navigationTypeOf, event, []) !== "reload") {
103
108
  applyOf(preventNavigation, event, []);
109
+ navigationBlocked(urlOf === null ? "" : String(applyOf(urlOf, destination, [])));
104
110
  }
105
111
  }, true);
106
112
  }
@@ -475,13 +481,27 @@ export const SHELL_RUNTIME = String.raw `(() => {
475
481
  reported += 1;
476
482
  send({ method: "notifications/message", params: { level: "error", logger: "porthole", data: String(message).slice(0, 2000) } });
477
483
  };
478
- const send = (message) => {
479
- if (plan.protocol === "shell" && window.parent !== window) {
480
- // Nothing secret is ever said from here, so any parent may hear it; what it hears is the
481
- // content's word, which the host gates before it acts on it.
484
+ // Nothing secret is ever said from here, so any parent may hear it; what it hears is the
485
+ // content's word, which the host gates before it acts on it.
486
+ const post = (message) => {
487
+ if (window.parent !== window) {
482
488
  window.parent.postMessage(Object.assign({ jsonrpc: "2.0" }, message), "*");
483
489
  }
484
490
  };
491
+ const send = (message) => {
492
+ if (plan.protocol === "shell") {
493
+ post(message);
494
+ }
495
+ };
496
+ // A navigation the guard above stopped (P080): one of the run's error reports, told even where
497
+ // the content speaks for itself (an MCP Apps view), in Porthole's own notification.
498
+ navigationBlocked = (url) => {
499
+ if (!declared("reportError") || reported >= plan.maxErrorReports || url === "") {
500
+ return;
501
+ }
502
+ reported += 1;
503
+ post({ method: "porthole/navigation-blocked", params: { url: url.slice(0, 4096) } });
504
+ };
485
505
 
486
506
  // A parsed tree's scripts are held (each replaced by a numbered marker) and run later, in order,
487
507
  // as the page's parser would run them: each made again, live, in its marker's place, and each
@@ -1020,7 +1040,13 @@ export const SHELL_RUNTIME = String.raw `(() => {
1020
1040
  if (waiting !== undefined) {
1021
1041
  pending.delete(data.id);
1022
1042
  if (data.error) {
1023
- waiting.reject(new Error(String(data.error.message || "refused")));
1043
+ // A refusal says why (P080): its code, and a sentence to show the person.
1044
+ const why = data.error.data !== null && typeof data.error.data === "object" ? data.error.data : {};
1045
+ const error = new Error(String(typeof why.message === "string" && why.message !== "" ? why.message : data.error.message || "refused"));
1046
+ if (typeof why.code === "string") {
1047
+ error.code = why.code;
1048
+ }
1049
+ waiting.reject(error);
1024
1050
  } else {
1025
1051
  waiting.resolve(data.result);
1026
1052
  }
package/docs/ADOPTING.md CHANGED
@@ -94,7 +94,7 @@ Its only way out is your host: `readData` (MCP `resources/read`) and `subscribeD
94
94
  `resources/subscribe`, `resources/unsubscribe`, `notifications/resources/updated`).
95
95
 
96
96
  ```js
97
- import { defineDisplays } from "@botiverse/porthole";
97
+ import { defineDisplays, Refused } from "@botiverse/porthole";
98
98
 
99
99
  export const displays = defineDisplays({
100
100
  // No egress option exists for it; served, it loads Porthole's Chart.js and D3 from its origin.
@@ -104,10 +104,14 @@ export const displays = defineDisplays({
104
104
  createHost(displays.configFor(instance, contentSource), {
105
105
  locator,
106
106
  handlers: {
107
- // As the viewer: your own access rules, never the author's. Return MCP's read result.
108
- readData: async ({ uri }, { displayId }) => ({
109
- contents: [{ uri, mimeType: "application/json", text: JSON.stringify(await load(uri)) }],
110
- }),
107
+ // As the viewer: your own access rules, never the author's. Return MCP's read result; refuse
108
+ // what you don't serve with a Refused, whose code and sentence the widget shows (P080).
109
+ readData: async ({ uri }, { displayId }) => {
110
+ if (!servedUri(uri)) throw new Refused("not_allowed", "This widget can read issues only.");
111
+ return {
112
+ contents: [{ uri, mimeType: "application/json", text: JSON.stringify(await load(uri)) }],
113
+ };
114
+ },
111
115
  // Call changed() when it changes (the content reads it again), or changed(result) to send it.
112
116
  subscribeData: ({ uri }, { changed, signal }) => {
113
117
  const stop = realtime.on(uri, () => changed());
@@ -125,12 +129,37 @@ createHost(displays.configFor(instance, contentSource), {
125
129
  - **Your handlers decide what a URI may name.** Answer only the resources you mean widgets to read
126
130
  (a whitelist of URI shapes), with the viewer's rights. The content's URI is its word.
127
131
  - **Consent is your UI.** Without a `consent` function every data call is refused (fail closed).
128
- React: `PortholeProvider` and `PortholeFrame` take `consent` and `cached`.
132
+ React: `PortholeProvider` and `PortholeFrame` take `consent` and `cached`. A consent function
133
+ that throws a `Refused` gives that answer, kept like `false`; anything else it throws is no
134
+ answer yet (the next call asks again).
135
+ - **A page where data must not run** (beside a frame that reaches the network, below): pass a
136
+ `Refused` as `consent` and no data handlers. Every data call is refused with it, nothing is asked,
137
+ and the widget shows your sentence:
138
+
139
+ ```js
140
+ createHost(displays.configFor(instance, contentSource), {
141
+ locator,
142
+ consent: new Refused("not_allowed", "Live data shows on the dashboard."),
143
+ });
144
+ ```
145
+
146
+ Any other capability you declare still needs its handler.
147
+ - **Refusals tell the widget why** (P080). A refused call's JSON-RPC error carries
148
+ `data: { code, message }`; the shell's `readData` rejects (and `subscribeData`'s `onError` is
149
+ called) with an `Error` whose `code` and `message` are those. `code` is `consent_required` (no
150
+ answer yet), `denied` (the viewer said no), `rate_limited`, `not_allowed` (not here, or not this
151
+ URI) or `failed` (your handler threw); `message` is your `Refused`'s sentence, else Porthole's.
152
+ The manual tells the agent to draw the widget without the data, with that sentence. A handler's
153
+ other errors are `failed` in Porthole's words: their messages stay yours.
129
154
  - **Rates stay gates**: 120 reads and 60 subscriptions a minute per display by default; change them
130
155
  with the capability's `gates` (keep `"consent"` in the list).
131
156
  - **Your page's CSP**: send `displays.embedderCsp(source, …)` (`frame-src` of your content origins
132
157
  and the authorize route, nothing else). It keeps a frame from navigating to an outside site; the
133
- shell keeps a served frame from navigating to another content origin (P079).
158
+ shell keeps a served frame from navigating to another content origin (P079), and tells you:
159
+ `display.on("navigationBlocked", ({ url }) => …)` (React `onNavigationBlocked`) gets the address
160
+ whole, and `contentError` a sentence naming it without its query, for the agent (P080). Only
161
+ where the config declares `reportError`, and only served frames: an opaque frame's navigations
162
+ get no events (you hear `navigated` when one replaces its document).
134
163
  - **Keep live widgets off pages with frames that reach the network.** A frame can `postMessage` any
135
164
  frame on its page, and nothing in it can stop that: a url-mode app (a dev server's preview) or an
136
165
  `anyHttps` display beside a live widget could be handed what it read. Displays with closed egress
@@ -400,8 +429,9 @@ in the config also has the manual name them). The descriptions are the manual's
400
429
  warnings with the result. `refuseOn: "never"` only warns.
401
430
  - **`guideChanges(from, to)`** is the notice for the agent when a kind flips between served and
402
431
  opaque (null when its manual reads the same).
403
- - **`errors: "agent"`** sends what content throws (and what the sandbox blocks) back to the agent
404
- once people see it: listen for `contentError` and pass it on.
432
+ - **`errors: "agent"`** sends what content throws (and what the sandbox blocks, and a navigation
433
+ the shell stopped, P080) back to the agent once people see it: listen for `contentError` and pass
434
+ it on.
405
435
 
406
436
  ### Checking a page before people see it
407
437