@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
@@ -382,7 +382,7 @@ function gateWords(gates: readonly Gate[], effect: string): string {
382
382
  const sentences: string[] = [];
383
383
  if (gates.includes("consent")) {
384
384
  sentences.push(
385
- "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).",
385
+ "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).",
386
386
  );
387
387
  }
388
388
  if (gates.includes("confirm")) {
@@ -401,6 +401,20 @@ function gateWords(gates: readonly Gate[], effect: string): string {
401
401
  return sentences.join(" ");
402
402
  }
403
403
 
404
+ /**
405
+ * What a data refusal tells content (P080): the codes and the sentence, for the author to draw. With
406
+ * the shell's globals they are the error's own fields; without, the JSON-RPC error's data.
407
+ */
408
+ function refusalWords(c: Context, global: boolean): string {
409
+ const where = global
410
+ ? "The error's code says why"
411
+ : "A refusal is an error whose data is { code, message }; code says why";
412
+ 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(
413
+ / {2,}/gu,
414
+ " ",
415
+ );
416
+ }
417
+
404
418
  const ENTRIES: { readonly [N in CapabilityName]: (c: Context, gates: readonly Gate[]) => string } =
405
419
  {
406
420
  sendPrompt: (c, gates) =>
@@ -417,11 +431,11 @@ const ENTRIES: { readonly [N in CapabilityName]: (c: Context, gates: readonly Ga
417
431
  `- Tools: the MCP Apps request tools/call (with the App SDK, app.callServerTool). ${gateWords(gates, "the call")}`,
418
432
  readData: (c, gates) =>
419
433
  c.global("readData")
420
- ? `- 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.`
421
- : `- Data: the MCP Apps request resources/read (with the App SDK, app.readServerResource). ${gateWords(gates, "the request")}`,
434
+ ? `- 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)}`
435
+ : `- Data: the MCP Apps request resources/read (with the App SDK, app.readServerResource). ${gateWords(gates, "the request")} ${refusalWords(c, false)}`,
422
436
  subscribeData: (c, gates) =>
423
437
  c.global("subscribeData")
424
- ? `- 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.`
438
+ ? `- 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.`
425
439
  : `- 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")}`,
426
440
  setModelContext: (_c, gates) =>
427
441
  `- Context for the agent: the MCP Apps request ui/update-model-context (with the App SDK, app.updateModelContext). ${gateWords(gates, "it")}`,
@@ -8,7 +8,8 @@ import { annotateMode, checkMarks, parseReport } from "../annotate/validate.ts";
8
8
  import { createBridge, onceConsent, type BridgeEvent } from "../bridge/bridge.ts";
9
9
  import type { HostFunctionBridge } from "../bridge/types.ts";
10
10
  import { compile } from "../compile/compile.ts";
11
- import { declaredCapabilities } from "../compile/policy.ts";
11
+ import { declaredCapabilities, effectiveGates } from "../compile/policy.ts";
12
+ import { isRefused } from "../bridge/refusal.ts";
12
13
  import { capabilitySpec } from "../config/capabilities.ts";
13
14
  import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
14
15
  import { locateServed } from "./locate.ts";
@@ -79,10 +80,14 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
79
80
  compiled,
80
81
  mount(container: HTMLElement, mount: MountOptions): DisplayHandle<C> {
81
82
  const handlers = { ...options.handlers, ...mount.handlers };
83
+ // A host whose consent is a Refused refuses every consent-gated call before its handler:
84
+ // those need none (P080).
85
+ const refusesAll = isRefused(options.consent);
82
86
  const missing = declaredCapabilities(config).filter(
83
87
  (name) =>
84
88
  capabilitySpec(name).served === "handler" &&
85
- (handlers as Record<string, unknown>)[name] === undefined,
89
+ (handlers as Record<string, unknown>)[name] === undefined &&
90
+ !(refusesAll && effectiveGates(config, name).includes("consent")),
86
91
  );
87
92
  if (missing.length > 0) {
88
93
  throw new TypeError(`No handler for the declared capabilities: ${missing.join(", ")}`);
@@ -117,8 +122,12 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
117
122
  let destroyed = false;
118
123
  let restarts = 0;
119
124
  let generation = 0;
120
- // The viewer's answer for this display (P079): asked once, kept across its frames.
121
- const consent = options.consent === undefined ? undefined : onceConsent(options.consent);
125
+ // The viewer's answer for this display (P079): asked once, kept across its frames; or the
126
+ // host's refusal of them all (P080).
127
+ const consent =
128
+ options.consent === undefined || isRefused(options.consent)
129
+ ? options.consent
130
+ : onceConsent(options.consent);
122
131
  let abort: AbortController | null = null;
123
132
  let outcomeWatch: OutcomeWatch | null = null;
124
133
  let themeFrame: number | null = null;
@@ -291,6 +300,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
291
300
  });
292
301
  return;
293
302
  }
303
+ case "navigationBlocked":
304
+ emit("navigationBlocked", { url: event.url });
305
+ return;
294
306
  case "error":
295
307
  contentError(event.message);
296
308
  return;
package/src/host/types.ts CHANGED
@@ -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";
@@ -22,9 +23,11 @@ export interface HostOptions<C extends AdapterConnection = ShellConnection> {
22
23
  /**
23
24
  * Whether a display may make its `consent`-gated calls (read the viewer's data, P079): asked
24
25
  * once per display, before the first, and kept for the display's life (its reloads too).
25
- * Absent: those calls are refused.
26
+ * Absent: those calls are refused. A `Refused` instead of a function refuses every one with its
27
+ * reason, asking nothing, and those capabilities need no handler (a page where live data must
28
+ * not run, P080).
26
29
  */
27
- readonly consent?: Consent;
30
+ readonly consent?: Consent | Refused;
28
31
  /**
29
32
  * What the host last had for a resource (P079): a read of one the content subscribes to is
30
33
  * answered with it at once, marked stale, then with the handler's fresh result.
@@ -154,6 +157,14 @@ export interface DisplayEvents {
154
157
  readonly error: { readonly message: string; readonly source: "content" | "host" };
155
158
  /** The content navigated its frame away; the frame was started again from its content. */
156
159
  readonly navigated: undefined;
160
+ /**
161
+ * The shell stopped the content navigating its frame to `url` (P079, P080): the address whole,
162
+ * as the content gave it (its word: untrusted, may carry data in its query). Only where the
163
+ * config declares `reportError` (it counts as one of the run's reports), and only in frames with
164
+ * an origin of their own (served): an opaque frame's navigations get no events. A
165
+ * `contentError` follows, naming the address without its query or fragment.
166
+ */
167
+ readonly navigationBlocked: { readonly url: string };
157
168
  /** A call didn't run. */
158
169
  readonly refused: { readonly capability: CapabilityName; readonly refusal: Refusal };
159
170
  /** Too many declines: the display stops asking until it runs again. */
package/src/index.ts CHANGED
@@ -122,10 +122,19 @@ export {
122
122
  MCP_APPS_METHODS,
123
123
  MCP_APPS_PROTOCOL_VERSION,
124
124
  MCP_APPS_STYLE_VARIABLES,
125
+ NAVIGATION_BLOCKED_METHOD,
125
126
  PORTHOLE_STYLES,
126
127
  STALE_META,
127
128
  type HostContext,
128
129
  } from "./protocol/mcp-apps.ts";
130
+ // Why a call was refused, as content is told it, and the host's own refusals (P080).
131
+ export {
132
+ REFUSAL_CODES,
133
+ Refused,
134
+ isRefused,
135
+ type RefusalCode,
136
+ type RefusalReason,
137
+ } from "./bridge/refusal.ts";
129
138
  export type {
130
139
  CallContext,
131
140
  CallOptions,
@@ -14,8 +14,13 @@ import {
14
14
  MCP_APPS_PROTOCOL_VERSION,
15
15
  type HostContext,
16
16
  } from "../protocol/mcp-apps.ts";
17
- import { COPY_TEXT_METHOD, MCP_APPS_STYLE_VARIABLES } from "../protocol/mcp-apps.ts";
17
+ import {
18
+ COPY_TEXT_METHOD,
19
+ MCP_APPS_STYLE_VARIABLES,
20
+ NAVIGATION_BLOCKED_METHOD,
21
+ } from "../protocol/mcp-apps.ts";
18
22
  import { liveData } from "../protocol/live-data.ts";
23
+ import { reasonFor } from "../bridge/refusal.ts";
19
24
 
20
25
  /**
21
26
  * The MCP Apps adapter (P004, P007): the host side of the protocol for full MCP Apps views, written
@@ -190,12 +195,13 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
190
195
  refuse(request.id, JSON_RPC_ERRORS.internal, `${request.method} failed`);
191
196
  return;
192
197
  }
193
- reply(request, outcome, result);
198
+ reply(request, capability, outcome, result);
194
199
  }
195
200
 
196
201
  /** Answers a request with a capability's outcome. */
197
202
  function reply(
198
203
  request: JsonRpcRequest,
204
+ capability: CapabilityName,
199
205
  outcome: CallOutcome<unknown>,
200
206
  result: (value: unknown) => unknown,
201
207
  ): void {
@@ -204,8 +210,17 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
204
210
  } else if (outcome.refusal === "not-declared") {
205
211
  refuse(request.id, JSON_RPC_ERRORS.methodNotFound, `${request.method} isn't offered here`);
206
212
  } else {
207
- // The spec's "implementation-defined" error for a refused request.
208
- refuse(request.id, -32_000, `${request.method} refused (${outcome.refusal})`);
213
+ // The spec's "implementation-defined" error for a refused request, with why in its data
214
+ // (`{ code, message }`, P080).
215
+ send({
216
+ jsonrpc: "2.0",
217
+ id: request.id,
218
+ error: {
219
+ code: -32_000,
220
+ message: `${request.method} refused (${outcome.refusal})`,
221
+ data: reasonFor(capability, outcome),
222
+ },
223
+ });
209
224
  }
210
225
  }
211
226
 
@@ -275,7 +290,7 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
275
290
  invalid("needs a uri");
276
291
  return;
277
292
  }
278
- reply(request, await live.read(params.uri), (value) =>
293
+ reply(request, "readData", await live.read(params.uri), (value) =>
279
294
  isRecord(value) ? value : { contents: [] },
280
295
  );
281
296
  return;
@@ -298,7 +313,7 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
298
313
  answer(request.id, {});
299
314
  return;
300
315
  }
301
- reply(request, await live.subscribe(params.uri), () => ({}));
316
+ reply(request, "subscribeData", await live.subscribe(params.uri), () => ({}));
302
317
  return;
303
318
  case MCP_APPS_METHODS.updateModelContext:
304
319
  if (
@@ -388,6 +403,11 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
388
403
  });
389
404
  }
390
405
  return;
406
+ case NAVIGATION_BLOCKED_METHOD:
407
+ // The shell, hardening the view's frame, stopped a navigation (P080): an error report,
408
+ // with its address.
409
+ void bridge.call("reportError", { navigationBlocked: params.url });
410
+ return;
391
411
  case MCP_APPS_METHODS.requestTeardown:
392
412
  session.emit({ type: "teardown-requested" });
393
413
  return;
@@ -133,6 +133,13 @@ export const COPY_TEXT_METHOD = "porthole/copy-text";
133
133
  */
134
134
  export const STALE_META = "porthole/stale";
135
135
 
136
+ /**
137
+ * Porthole's own notification from the shell (P080): it cancelled a navigation of the frame to
138
+ * `{ url }` (P079). The content's word, sent only where `reportError` is declared, and counted as
139
+ * one of its reports; the host's adapter carries it into `reportError`.
140
+ */
141
+ export const NAVIGATION_BLOCKED_METHOD = "porthole/navigation-blocked";
142
+
136
143
  /** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
137
144
  export const SHELL_LOGGER = "porthole";
138
145
 
@@ -8,8 +8,10 @@ import {
8
8
  type JsonRpcRequest,
9
9
  type JsonRpcResponse,
10
10
  } from "./jsonrpc.ts";
11
+ import { reasonFor, type RefusalReason } from "../bridge/refusal.ts";
11
12
  import {
12
13
  COPY_TEXT_METHOD,
14
+ NAVIGATION_BLOCKED_METHOD,
13
15
  MCP_APPS_METHODS as M,
14
16
  MCP_APPS_PROTOCOL_VERSION,
15
17
  type HostContext,
@@ -67,7 +69,7 @@ const REQUESTS: Readonly<
67
69
  function answer(
68
70
  capability: CapabilityName,
69
71
  outcome: CallOutcome<unknown>,
70
- ): { result: unknown } | { error: { code: number; message: string } } {
72
+ ): { result: unknown } | { error: { code: number; message: string; data?: RefusalReason } } {
71
73
  const flagged =
72
74
  capability === "sendPrompt" ||
73
75
  capability === "openLink" ||
@@ -76,7 +78,14 @@ function answer(
76
78
  if (!outcome.ok) {
77
79
  return flagged
78
80
  ? { result: { isError: true } }
79
- : { error: { code: -32000, message: `Refused (${outcome.refusal})` } };
81
+ : {
82
+ // Why, in the error's data (`{ code, message }`, P080).
83
+ error: {
84
+ code: -32000,
85
+ message: `Refused (${outcome.refusal})`,
86
+ data: reasonFor(capability, outcome),
87
+ },
88
+ };
80
89
  }
81
90
  if (flagged) {
82
91
  return { result: outcome.value === true ? {} : { isError: true } };
@@ -236,6 +245,10 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
236
245
  });
237
246
  }
238
247
  return;
248
+ case NAVIGATION_BLOCKED_METHOD:
249
+ // The shell stopped a navigation (P080): an error report, with its address.
250
+ void bridge.call("reportError", { navigationBlocked: params.url });
251
+ return;
239
252
  case M.requestTeardown:
240
253
  session.emit({ type: "teardown-requested" });
241
254
  return;
@@ -27,6 +27,7 @@ import type {
27
27
  Proceed,
28
28
  Refusal,
29
29
  } from "../bridge/types.ts";
30
+ import { isRefused, reasonOf, Refused, type RefusalReason } from "../bridge/refusal.ts";
30
31
  import type { CapabilityName } from "../config/capabilities.ts";
31
32
  import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
32
33
  import { writeClipboard } from "../host/clipboard.ts";
@@ -65,6 +66,8 @@ interface PageState {
65
66
  readonly confirm?: Confirm;
66
67
  /** The provider's consent and cache (P079), read when a frame asks. */
67
68
  readonly consent?: Consent;
69
+ /** The provider's consent is a `Refused` (P080): its reason, by value. */
70
+ readonly refusesAll?: RefusalReason;
68
71
  readonly cached?: DataCache;
69
72
  readonly hostInfo?: { readonly name: string; readonly version: string };
70
73
  readonly nonce?: string;
@@ -127,9 +130,10 @@ export interface PortholeProviderProps {
127
130
  readonly confirm?: Confirm;
128
131
  /**
129
132
  * 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.
133
+ * asked once per display, before the first. Omitted: those calls are refused. A `Refused`
134
+ * refuses them all with its reason, and their handlers may be left out (P080).
131
135
  */
132
- readonly consent?: Consent;
136
+ readonly consent?: Consent | Refused;
133
137
  /** What the host last had for a resource, answered stale first (P079). */
134
138
  readonly cached?: DataCache;
135
139
  /** How the host names itself in the handshake. */
@@ -204,7 +208,15 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
204
208
  ownConsent.current = props.consent;
205
209
  ownCached.current = props.cached;
206
210
  });
207
- const consent = useCallback<Consent>((request) => ownConsent.current?.(request) ?? false, []);
211
+ const consent = useCallback<Consent>((request) => {
212
+ const given = ownConsent.current;
213
+ if (isRefused(given)) {
214
+ throw given;
215
+ }
216
+ return given?.(request) ?? false;
217
+ }, []);
218
+ // A Refused for every frame below, by value (an inline one starts nothing again).
219
+ const refusesAll = useByValue(isRefused(props.consent) ? reasonOf(props.consent) : undefined);
208
220
  const cached = useCallback<DataCache>((args, context) => ownCached.current?.(args, context), []);
209
221
  const consents = props.consent !== undefined;
210
222
  const caches = props.cached !== undefined;
@@ -284,6 +296,7 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
284
296
  confirm,
285
297
  copyText,
286
298
  ...(consents ? { consent } : {}),
299
+ ...(refusesAll === undefined ? {} : { refusesAll }),
287
300
  ...(caches ? { cached } : {}),
288
301
  ...(hostInfo === undefined ? {} : { hostInfo }),
289
302
  ...(locates ? { locate } : {}),
@@ -301,6 +314,7 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
301
314
  copyText,
302
315
  consents,
303
316
  consent,
317
+ refusesAll,
304
318
  caches,
305
319
  cached,
306
320
  hostInfo,
@@ -401,8 +415,11 @@ export interface PortholeFrameProps {
401
415
  readonly handlers?: CapabilityHandlers;
402
416
  /** Who confirms this frame's gated calls, over the provider's. */
403
417
  readonly confirm?: Confirm;
404
- /** Whether this frame may make its `consent`-gated calls, over the provider's (P079). */
405
- readonly consent?: Consent;
418
+ /**
419
+ * Whether this frame may make its `consent`-gated calls, over the provider's (P079). A `Refused`
420
+ * refuses them all with its reason, and their handlers may be left out (P080).
421
+ */
422
+ readonly consent?: Consent | Refused;
406
423
  /** This frame's data cache, over the provider's (P079). */
407
424
  readonly cached?: DataCache;
408
425
  /** Bump to run the content again from the start. */
@@ -436,6 +453,12 @@ export interface PortholeFrameProps {
436
453
  readonly onError?: (message: string, source: "content" | "host") => void;
437
454
  /** The content navigated its frame away; it was started again (or stopped, after a few). */
438
455
  readonly onNavigated?: () => void;
456
+ /**
457
+ * The shell stopped the content navigating its frame to `url` (P080): the address whole, the
458
+ * content's word. Served frames only, where the config declares `reportError`; `onContentError`
459
+ * hears it too, without the address's query.
460
+ */
461
+ readonly onNavigationBlocked?: (blocked: { readonly url: string }) => void;
439
462
  readonly onRefused?: (capability: CapabilityName, refusal: Refusal) => void;
440
463
  /** Too many declines: the display stops asking until it runs again. */
441
464
  readonly onMuted?: () => void;
@@ -642,6 +665,10 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
642
665
  const config = useByValue(frame.config);
643
666
  const instance = useByValue(frame.instance);
644
667
  const fills = config.mode === "url" || frame.fill === true || config.layout.kind === "fill";
668
+ // A consent that refuses everything (P080), this frame's or else the provider's, by value: a
669
+ // display made with it needs no data handlers, so a change makes the display again.
670
+ const ownRefusal = useByValue(isRefused(frame.consent) ? reasonOf(frame.consent) : undefined);
671
+ const refusesAll = frame.consent === undefined ? page.refusesAll : ownRefusal;
645
672
 
646
673
  // The latest props, read when the display calls back (never during render).
647
674
  const latest = useEffectEvent(() => frame);
@@ -691,6 +718,9 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
691
718
  case "navigated":
692
719
  frame.onNavigated?.();
693
720
  return;
721
+ case "navigationBlocked":
722
+ frame.onNavigationBlocked?.(detail as DisplayEvents["navigationBlocked"]);
723
+ return;
694
724
  case "refused": {
695
725
  const { capability, refusal } = detail as DisplayEvents["refused"];
696
726
  frame.onRefused?.(capability, refusal);
@@ -767,15 +797,22 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
767
797
  ),
768
798
  }
769
799
  : {}),
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
- : {}),
800
+ ...(refusesAll !== undefined
801
+ ? { consent: new Refused(refusesAll.code, refusesAll.message) }
802
+ : asksConsent
803
+ ? {
804
+ consent: (request: ConfirmRequest) => {
805
+ const given = latest().consent ?? pageConsent ?? (() => false);
806
+ if (isRefused(given)) {
807
+ throw given;
808
+ }
809
+ return given({
810
+ ...request,
811
+ display: { ...request.display, id: latest().displayId, title: latest().title },
812
+ });
813
+ },
814
+ }
815
+ : {}),
779
816
  ...(caches
780
817
  ? {
781
818
  cached: (args: { readonly uri: string }, context: CallContext) =>
@@ -805,6 +842,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
805
842
  "resize",
806
843
  "error",
807
844
  "navigated",
845
+ "navigationBlocked",
808
846
  "refused",
809
847
  "muted",
810
848
  "outcome",
@@ -839,6 +877,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
839
877
  pageConfirm,
840
878
  pageConsent,
841
879
  pageCached,
880
+ refusesAll,
842
881
  hostInfo,
843
882
  locate,
844
883
  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
  }