@botiverse/porthole 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. package/README.md +25 -0
  2. package/dist/bridge/bridge.d.ts +12 -4
  3. package/dist/bridge/bridge.js +62 -27
  4. package/dist/bridge/navigation.d.ts +6 -0
  5. package/dist/bridge/navigation.js +41 -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 +7 -0
  9. package/dist/check/check.d.ts +12 -3
  10. package/dist/check/check.js +54 -8
  11. package/dist/check/files.d.ts +26 -0
  12. package/dist/check/files.js +307 -0
  13. package/dist/check/lint.js +27 -10
  14. package/dist/check/page-source.js +1 -1
  15. package/dist/check/page.js +5 -0
  16. package/dist/check/tools.d.ts +23 -0
  17. package/dist/check/tools.js +25 -0
  18. package/dist/compile/policy.d.ts +15 -0
  19. package/dist/compile/policy.js +32 -0
  20. package/dist/config/capabilities.d.ts +5 -0
  21. package/dist/config/schema.d.ts +8 -0
  22. package/dist/config/validate.js +8 -1
  23. package/dist/conformance/harness-source.js +1 -1
  24. package/dist/files/paths.d.ts +99 -0
  25. package/dist/files/paths.js +263 -0
  26. package/dist/files/types.d.ts +24 -0
  27. package/dist/files/types.js +83 -0
  28. package/dist/guide/guide.js +25 -5
  29. package/dist/host/create-host.js +36 -4
  30. package/dist/host/types.d.ts +15 -2
  31. package/dist/index.d.ts +7 -3
  32. package/dist/index.js +10 -3
  33. package/dist/mcp/adapter.js +22 -7
  34. package/dist/protocol/adapter.d.ts +4 -0
  35. package/dist/protocol/mcp-apps.d.ts +12 -0
  36. package/dist/protocol/mcp-apps.js +12 -0
  37. package/dist/protocol/shell-adapter.js +18 -2
  38. package/dist/react/frame.d.ts +19 -4
  39. package/dist/react/frame.js +37 -9
  40. package/dist/server/files.d.ts +44 -0
  41. package/dist/server/files.js +244 -0
  42. package/dist/server/host.d.ts +38 -1
  43. package/dist/server/host.js +37 -2
  44. package/dist/server/index.d.ts +4 -2
  45. package/dist/server/index.js +4 -1
  46. package/dist/server/keys.d.ts +8 -0
  47. package/dist/server/keys.js +34 -0
  48. package/dist/server/server.js +287 -22
  49. package/dist/server/types.d.ts +49 -5
  50. package/dist/shell/document.d.ts +19 -0
  51. package/dist/shell/document.js +30 -0
  52. package/dist/shell/runtime.d.ts +2 -1
  53. package/dist/shell/runtime.js +117 -10
  54. package/docs/ADOPTING.md +95 -13
  55. package/docs/ARCHITECTURE.md +13 -3
  56. package/docs/DECISIONS.md +396 -4
  57. package/docs/DESIGN.md +43 -10
  58. package/package.json +1 -1
  59. package/src/bridge/bridge.ts +74 -23
  60. package/src/bridge/navigation.ts +46 -0
  61. package/src/bridge/refusal.ts +151 -0
  62. package/src/bridge/types.ts +12 -1
  63. package/src/check/check.ts +92 -14
  64. package/src/check/files.ts +384 -0
  65. package/src/check/lint.ts +29 -10
  66. package/src/check/page.ts +7 -0
  67. package/src/check/tools.ts +50 -0
  68. package/src/compile/policy.ts +38 -0
  69. package/src/config/capabilities.ts +5 -1
  70. package/src/config/schema.ts +8 -0
  71. package/src/config/validate.ts +8 -1
  72. package/src/files/paths.ts +323 -0
  73. package/src/files/types.ts +101 -0
  74. package/src/guide/guide.ts +38 -4
  75. package/src/host/create-host.ts +37 -4
  76. package/src/host/types.ts +13 -2
  77. package/src/index.ts +41 -0
  78. package/src/mcp/adapter.ts +26 -6
  79. package/src/protocol/adapter.ts +3 -1
  80. package/src/protocol/mcp-apps.ts +14 -0
  81. package/src/protocol/shell-adapter.ts +20 -2
  82. package/src/react/frame.tsx +53 -14
  83. package/src/server/files.ts +312 -0
  84. package/src/server/host.ts +72 -3
  85. package/src/server/index.ts +19 -0
  86. package/src/server/keys.ts +53 -0
  87. package/src/server/server.ts +353 -24
  88. package/src/server/types.ts +56 -4
  89. package/src/shell/document.ts +53 -0
  90. package/src/shell/runtime.ts +117 -10
@@ -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
@@ -11,8 +11,10 @@ export { hostOriginProblem, isHostOrigin } from "./isolation/served.ts";
11
11
  export { FRAME_STATUS_METHOD } from "./isolation/types.ts";
12
12
  export { LIBRARY_CDNS, presets, type PresetName, type LiveWidgetOptions, type PresetOptions, type UrlPresetOptions, } from "./presets/presets.ts";
13
13
  export { LIBRARY_PATH, VENDORED_LIBRARIES, libraryPath, licensePath, type VendoredLibrary, } from "./libraries/libraries.ts";
14
+ export { checkFileSet, DEFAULT_ENTRY, DEFAULT_MAX_FILE_BYTES, DEFAULT_MAX_FILES, DEFAULT_MAX_VERSION_BYTES, fileLimits, filePathProblem, lookupFile, requestFilePath, servesFiles, type FileLimits, type FileLookup, type FileSetProblem, } from "./files/paths.ts";
15
+ export { fileTypeOf, KNOWN_EXTENSIONS, UNKNOWN_TYPE, type FileRole, type FileType, } from "./files/types.ts";
14
16
  export { compile, type CompiledConfig } from "./compile/compile.ts";
15
- export { allEgressOrigins, anyHttps, declaredCapabilities, effectiveGates, egressOrigins, embedderCsp, embedderFrameSourcesOf, type CspDirective, type EgressKind, } from "./compile/policy.ts";
17
+ export { allEgressOrigins, anyHttps, declaredCapabilities, effectiveGates, egressOrigins, embedderCsp, embedderFrameSourcesOf, FILE_SET_DIRECTIVES, fileSetCspDirectives, INERT_FILE_CSP, type CspDirective, type EgressKind, } from "./compile/policy.ts";
16
18
  export { shellPlan, type ShellPlan } from "./shell/plan.ts";
17
19
  export type { ShellDocumentOptions } from "./shell/document.ts";
18
20
  export { generateGuide, generateToolDescription, type BuiltInTopic, type GuideTopic, } from "./guide/guide.ts";
@@ -22,13 +24,15 @@ export type { FrameLocation, FrameSource, InstanceLocator, InstanceRef, ServedDo
22
24
  export type { PlatformHost, Surface, SurfaceSpec } from "./platform/types.ts";
23
25
  export type { Transport } from "./transport/types.ts";
24
26
  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";
27
+ export { COPY_TEXT_METHOD, MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS_STYLE_VARIABLES, NAVIGATING_METHOD, NAVIGATION_BLOCKED_METHOD, PORTHOLE_STYLES, STALE_META, type HostContext, } from "./protocol/mcp-apps.ts";
28
+ export { REFUSAL_CODES, Refused, isRefused, type RefusalCode, type RefusalReason, } from "./bridge/refusal.ts";
26
29
  export type { CallContext, CallOptions, CallOutcome, CapabilityHandler, CapabilityHandlers, Confirm, ConfirmAnswer, ConfirmDisplay, ConfirmRequest, Consent, DataCache, Proceed, HostFunctionBridge, Refusal, SubscriptionContext, } from "./bridge/types.ts";
27
30
  export { createHost } from "./host/create-host.ts";
28
31
  export { entryTarget, frameFallback, portholeClient, type ContentClientMeta, type FrameFallback, type PortholeClient, type PortholeClientOptions, } from "./host/client.ts";
29
32
  export { defineDisplays, type DisplayKind, type Displays } from "./displays/displays.ts";
30
33
  export { fragmentOf, lintContent, type Finding, type LintRule } from "./check/lint.ts";
31
- export { admitContent, answerGuide, checkTool, guideChanges, guideTool, guideTopics, showTool, type AdmitResult, type JsonSchema, type ToolDefinition, } from "./check/tools.ts";
34
+ export { lintFiles, type FileContents, type FileFinding } from "./check/files.ts";
35
+ export { admitContent, admitFiles, type AdmitFilesResult, answerGuide, checkTool, guideChanges, guideTool, guideTopics, showTool, type AdmitResult, type JsonSchema, type ToolDefinition, } from "./check/tools.ts";
32
36
  export { writeClipboard } from "./host/clipboard.ts";
33
37
  export { httpLocator, LocateError, servedOrOpaque, type HttpLocatorOptions, type ServedMeta, } from "./host/locator.ts";
34
38
  export type { AnnotationControls, DisplayControls, DisplayEvents, FrameBlock, FrameOutcome, DisplayHandle, HostOptions, MountOptions, PortholeHost, } from "./host/types.ts";
package/dist/index.js CHANGED
@@ -12,22 +12,29 @@ export { FRAME_STATUS_METHOD } from "./isolation/types.js";
12
12
  // Presets.
13
13
  export { LIBRARY_CDNS, presets, } from "./presets/presets.js";
14
14
  export { LIBRARY_PATH, VENDORED_LIBRARIES, libraryPath, licensePath, } from "./libraries/libraries.js";
15
+ // A version made of files (P081): the rules its paths follow, its limits and its types.
16
+ export { checkFileSet, DEFAULT_ENTRY, DEFAULT_MAX_FILE_BYTES, DEFAULT_MAX_FILES, DEFAULT_MAX_VERSION_BYTES, fileLimits, filePathProblem, lookupFile, requestFilePath, servesFiles, } from "./files/paths.js";
17
+ export { fileTypeOf, KNOWN_EXTENSIONS, UNKNOWN_TYPE, } from "./files/types.js";
15
18
  // The compiler.
16
19
  export { compile } from "./compile/compile.js";
17
- export { allEgressOrigins, anyHttps, declaredCapabilities, effectiveGates, egressOrigins, embedderCsp, embedderFrameSourcesOf, } from "./compile/policy.js";
20
+ export { allEgressOrigins, anyHttps, declaredCapabilities, effectiveGates, egressOrigins, embedderCsp, embedderFrameSourcesOf, FILE_SET_DIRECTIVES, fileSetCspDirectives, INERT_FILE_CSP, } from "./compile/policy.js";
18
21
  export { shellPlan } from "./shell/plan.js";
19
22
  export { generateGuide, generateToolDescription, } from "./guide/guide.js";
20
23
  export { GUIDE_EXAMPLES } from "./guide/examples.js";
21
24
  // Theme.
22
25
  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";
26
+ export { COPY_TEXT_METHOD, MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS_STYLE_VARIABLES, NAVIGATING_METHOD, NAVIGATION_BLOCKED_METHOD, PORTHOLE_STYLES, STALE_META, } from "./protocol/mcp-apps.js";
27
+ // Why a call was refused, as content is told it, and the host's own refusals (P080).
28
+ export { REFUSAL_CODES, Refused, isRefused, } from "./bridge/refusal.js";
24
29
  export { createHost } from "./host/create-host.js";
25
30
  // The client half of the host kit, and the display registry (P072).
26
31
  export { entryTarget, frameFallback, portholeClient, } from "./host/client.js";
27
32
  export { defineDisplays } from "./displays/displays.js";
28
33
  // The agent's side: what content can be told without running it, and its tools (P073).
29
34
  export { fragmentOf, lintContent } from "./check/lint.js";
30
- export { admitContent, answerGuide, checkTool, guideChanges, guideTool, guideTopics, showTool, } from "./check/tools.js";
35
+ // A page that comes with files (P081): its lint, without running it.
36
+ export { lintFiles } from "./check/files.js";
37
+ export { admitContent, admitFiles, answerGuide, checkTool, guideChanges, guideTool, guideTopics, showTool, } from "./check/tools.js";
31
38
  export { writeClipboard } from "./host/clipboard.js";
32
39
  export { httpLocator, LocateError, servedOrOpaque, } from "./host/locator.js";
33
40
  // Annotations (P053): anchors, what a frame reports, and the host's checks on both.
@@ -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;
@@ -47,6 +47,10 @@ export type AdapterEvent =
47
47
  /** The view asked to be closed. */
48
48
  | {
49
49
  readonly type: "teardown-requested";
50
+ }
51
+ /** A page that came with files is opening another page of its set in the frame (P084). */
52
+ | {
53
+ readonly type: "navigating";
50
54
  };
51
55
  /** What the framework drives on every adapter. Adapters add their protocol's own operations. */
52
56
  export interface AdapterConnection {
@@ -61,6 +61,18 @@ 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";
70
+ /**
71
+ * Porthole's own notification from the shell (P084): a page that came with files is opening
72
+ * another page of its set, `{ url }`, in the frame. The host takes the frame's next load for that
73
+ * page rather than for content that left (P031). The content's word: it only spares a restart.
74
+ */
75
+ export declare const NAVIGATING_METHOD = "porthole/navigating";
64
76
  /** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
65
77
  export declare const SHELL_LOGGER = "porthole";
66
78
  /**
@@ -111,5 +111,17 @@ 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";
120
+ /**
121
+ * Porthole's own notification from the shell (P084): a page that came with files is opening
122
+ * another page of its set, `{ url }`, in the frame. The host takes the frame's next load for that
123
+ * page rather than for content that left (P031). The content's word: it only spares a restart.
124
+ */
125
+ export const NAVIGATING_METHOD = "porthole/navigating";
114
126
  /** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
115
127
  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, NAVIGATING_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,14 @@ 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;
215
+ case NAVIGATING_METHOD:
216
+ // Another page of the set opens in the frame (P084): its next load is that page.
217
+ session.emit({ type: "navigating" });
218
+ return;
203
219
  case M.requestTeardown:
204
220
  session.emit({ type: "teardown-requested" });
205
221
  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,
@@ -0,0 +1,44 @@
1
+ import type { CompiledConfig } from "../compile/compile.ts";
2
+ import type { StoredFiles } from "./types.ts";
3
+ /**
4
+ * Serving a version made of files (P081, P082): each path looked up in its manifest only, each
5
+ * answer typed by Porthole's table, with `nosniff`, its CSP in a header, its cache rule and a
6
+ * strong ETag; pages in the shell, ranges for the rest.
7
+ */
8
+ export interface FileServing {
9
+ readonly request: Request;
10
+ readonly set: StoredFiles;
11
+ /** The request's path below the base, as the URL has it (percent-encoded). */
12
+ readonly rest: string;
13
+ /** The search part, kept on a redirect. */
14
+ readonly search: string;
15
+ /** The version's own address on its origin: a path ending in `/`. */
16
+ readonly base: string;
17
+ readonly origin: string;
18
+ /**
19
+ * Whether `base` names this version and no other (a pinned address, a frame's): its files are
20
+ * immutable there. Else they are revalidated (an address that may mean another version later).
21
+ */
22
+ readonly pinned: boolean;
23
+ /** The CSP source the version's files load from (P082): its path on the origin. */
24
+ readonly source: string;
25
+ readonly compiled: CompiledConfig;
26
+ readonly hostOrigins: readonly string[];
27
+ readonly frameAncestors: string;
28
+ /**
29
+ * A ticket's answer (P083): the entry, served at the ticket's address, never stored; its shell
30
+ * moves the frame to the entry's own address under `base` before anything loads, and renews
31
+ * that address before it ends (`expires`, epoch ms).
32
+ */
33
+ readonly ticket?: {
34
+ readonly expires: number;
35
+ };
36
+ }
37
+ /** Whether the request is a page loading (a navigation), not a subresource. */
38
+ export declare function isNavigation(request: Request): boolean;
39
+ /**
40
+ * Whether the request is a running page's own load: from its own origin (`Sec-Fetch-Site`, which
41
+ * only a browser sets and no page can change), and not a navigation.
42
+ */
43
+ export declare const ownLoad: (request: Request) => boolean;
44
+ export declare function serveFile(serving: FileServing): Promise<Response>;