@botiverse/porthole 0.6.0 → 0.8.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 (208) hide show
  1. package/README.md +25 -2
  2. package/THIRD_PARTY_NOTICES.md +421 -0
  3. package/dist/bridge/bounded-text.d.ts +34 -0
  4. package/dist/bridge/bounded-text.js +188 -0
  5. package/dist/bridge/bridge.d.ts +38 -5
  6. package/dist/bridge/bridge.js +469 -39
  7. package/dist/bridge/json-data.d.ts +28 -0
  8. package/dist/bridge/json-data.js +86 -0
  9. package/dist/bridge/navigation.d.ts +5 -0
  10. package/dist/bridge/navigation.js +7 -0
  11. package/dist/bridge/refusal.d.ts +5 -1
  12. package/dist/bridge/refusal.js +17 -0
  13. package/dist/bridge/types.d.ts +73 -5
  14. package/dist/check/check.d.ts +7 -0
  15. package/dist/check/check.js +1 -0
  16. package/dist/check/instrument.d.ts +3 -0
  17. package/dist/check/lint.js +4 -2
  18. package/dist/check/page-source.js +1 -1
  19. package/dist/check/page.js +16 -0
  20. package/dist/check/tools.js +2 -3
  21. package/dist/compile/compile.d.ts +6 -0
  22. package/dist/compile/compile.js +3 -1
  23. package/dist/compile/policy.d.ts +55 -0
  24. package/dist/compile/policy.js +157 -0
  25. package/dist/config/capabilities.d.ts +85 -7
  26. package/dist/config/capabilities.js +32 -2
  27. package/dist/config/schema.d.ts +35 -0
  28. package/dist/config/validate.d.ts +9 -3
  29. package/dist/config/validate.js +92 -8
  30. package/dist/config/warnings.d.ts +20 -0
  31. package/dist/config/warnings.js +25 -0
  32. package/dist/conformance/behavior.js +46 -1
  33. package/dist/conformance/cookies.d.ts +15 -0
  34. package/dist/conformance/cookies.js +80 -0
  35. package/dist/conformance/harness/page.d.ts +1 -0
  36. package/dist/conformance/harness/page.js +9 -2
  37. package/dist/conformance/harness-source.js +1 -1
  38. package/dist/conformance/host-kit.js +5 -1
  39. package/dist/conformance/index.d.ts +11 -0
  40. package/dist/conformance/index.js +2 -0
  41. package/dist/conformance/limits.js +38 -1
  42. package/dist/conformance/runtime.d.ts +58 -0
  43. package/dist/conformance/runtime.js +324 -0
  44. package/dist/conformance/served.d.ts +2 -0
  45. package/dist/conformance/served.js +737 -4
  46. package/dist/files/paths.js +4 -0
  47. package/dist/guide/gates.d.ts +9 -0
  48. package/dist/guide/gates.js +31 -0
  49. package/dist/guide/guide.d.ts +2 -0
  50. package/dist/guide/guide.js +35 -33
  51. package/dist/guide/limits.js +4 -4
  52. package/dist/guide/runtime.d.ts +13 -0
  53. package/dist/guide/runtime.js +210 -0
  54. package/dist/host/create-host.js +73 -37
  55. package/dist/host/locate.js +8 -0
  56. package/dist/host/locator.js +7 -0
  57. package/dist/host/pages-of-set.d.ts +43 -0
  58. package/dist/host/pages-of-set.js +196 -0
  59. package/dist/host/types.d.ts +26 -1
  60. package/dist/index.d.ts +11 -4
  61. package/dist/index.js +11 -2
  62. package/dist/isolation/types.d.ts +8 -0
  63. package/dist/mcp/adapter.js +11 -15
  64. package/dist/node/index.d.ts +36 -4
  65. package/dist/node/index.js +402 -101
  66. package/dist/presets/presets.d.ts +22 -8
  67. package/dist/presets/presets.js +40 -8
  68. package/dist/protocol/live-data.d.ts +6 -2
  69. package/dist/protocol/live-data.js +20 -1
  70. package/dist/protocol/mcp-apps.d.ts +13 -2
  71. package/dist/protocol/mcp-apps.js +10 -2
  72. package/dist/protocol/message-text.d.ts +8 -0
  73. package/dist/protocol/message-text.js +29 -0
  74. package/dist/protocol/runtime-calls.d.ts +28 -0
  75. package/dist/protocol/runtime-calls.js +116 -0
  76. package/dist/protocol/shell-adapter.js +64 -25
  77. package/dist/react/context-notice.d.ts +32 -0
  78. package/dist/react/context-notice.js +28 -0
  79. package/dist/react/dialog.js +91 -16
  80. package/dist/react/frame.d.ts +25 -1
  81. package/dist/react/frame.js +85 -2
  82. package/dist/react/index.d.ts +2 -1
  83. package/dist/react/index.js +2 -1
  84. package/dist/runtime/contract.d.ts +201 -0
  85. package/dist/runtime/contract.js +245 -0
  86. package/dist/runtime/db.d.ts +188 -0
  87. package/dist/runtime/db.js +502 -0
  88. package/dist/runtime/declaration.d.ts +100 -0
  89. package/dist/runtime/declaration.js +363 -0
  90. package/dist/runtime/levels.d.ts +33 -0
  91. package/dist/runtime/levels.js +41 -0
  92. package/dist/runtime/requests.d.ts +125 -0
  93. package/dist/runtime/requests.js +215 -0
  94. package/dist/runtime/segments.d.ts +8 -0
  95. package/dist/runtime/segments.js +14 -0
  96. package/dist/runtime/types.generated.d.ts +1 -0
  97. package/dist/runtime/types.generated.js +19 -0
  98. package/dist/server/files.d.ts +19 -1
  99. package/dist/server/files.js +115 -6
  100. package/dist/server/host.d.ts +24 -2
  101. package/dist/server/host.js +137 -2
  102. package/dist/server/index.d.ts +3 -2
  103. package/dist/server/index.js +2 -1
  104. package/dist/server/peer.d.ts +4 -0
  105. package/dist/server/peer.js +19 -0
  106. package/dist/server/proxy.d.ts +6 -0
  107. package/dist/server/proxy.js +12 -3
  108. package/dist/server/pseudonym.d.ts +9 -0
  109. package/dist/server/pseudonym.js +20 -0
  110. package/dist/server/server.d.ts +0 -5
  111. package/dist/server/server.js +318 -52
  112. package/dist/server/types.d.ts +74 -2
  113. package/dist/shell/document.d.ts +16 -0
  114. package/dist/shell/document.js +19 -2
  115. package/dist/shell/legacy.d.ts +21 -0
  116. package/dist/shell/legacy.js +63 -0
  117. package/dist/shell/plan.d.ts +17 -1
  118. package/dist/shell/plan.js +13 -2
  119. package/dist/shell/runtime.js +390 -56
  120. package/dist/shell/use.d.ts +15 -0
  121. package/dist/shell/use.js +235 -0
  122. package/docs/ADOPTING.md +205 -15
  123. package/docs/ARCHITECTURE.md +34 -5
  124. package/docs/DECISIONS.md +1867 -11
  125. package/docs/DESIGN.md +137 -17
  126. package/docs/THREAT_MODEL.md +616 -0
  127. package/package.json +16 -3
  128. package/src/bridge/bounded-text.ts +240 -0
  129. package/src/bridge/bridge.ts +601 -51
  130. package/src/bridge/json-data.ts +95 -0
  131. package/src/bridge/navigation.ts +10 -0
  132. package/src/bridge/refusal.ts +17 -0
  133. package/src/bridge/types.ts +76 -5
  134. package/src/check/check.ts +8 -0
  135. package/src/check/instrument.ts +3 -0
  136. package/src/check/lint.ts +4 -2
  137. package/src/check/page.ts +16 -0
  138. package/src/check/tools.ts +2 -3
  139. package/src/compile/compile.ts +9 -1
  140. package/src/compile/policy.ts +177 -0
  141. package/src/config/capabilities.ts +71 -5
  142. package/src/config/schema.ts +35 -0
  143. package/src/config/validate.ts +141 -8
  144. package/src/config/warnings.ts +42 -0
  145. package/src/conformance/behavior.ts +54 -1
  146. package/src/conformance/cookies.ts +93 -0
  147. package/src/conformance/harness/page.ts +11 -2
  148. package/src/conformance/host-kit.ts +10 -1
  149. package/src/conformance/index.ts +17 -0
  150. package/src/conformance/limits.ts +39 -1
  151. package/src/conformance/runtime.ts +594 -0
  152. package/src/conformance/served.ts +888 -4
  153. package/src/files/paths.ts +4 -0
  154. package/src/guide/gates.ts +37 -0
  155. package/src/guide/guide.ts +61 -55
  156. package/src/guide/limits.ts +4 -4
  157. package/src/guide/runtime.ts +253 -0
  158. package/src/host/create-host.ts +88 -36
  159. package/src/host/locate.ts +10 -0
  160. package/src/host/locator.ts +11 -0
  161. package/src/host/pages-of-set.ts +226 -0
  162. package/src/host/types.ts +33 -1
  163. package/src/index.ts +94 -0
  164. package/src/isolation/types.ts +8 -0
  165. package/src/mcp/adapter.ts +16 -20
  166. package/src/node/index.ts +507 -116
  167. package/src/presets/presets.ts +67 -17
  168. package/src/protocol/live-data.ts +31 -3
  169. package/src/protocol/mcp-apps.ts +11 -2
  170. package/src/protocol/message-text.ts +36 -0
  171. package/src/protocol/runtime-calls.ts +141 -0
  172. package/src/protocol/shell-adapter.ts +79 -26
  173. package/src/react/context-notice.tsx +95 -0
  174. package/src/react/dialog.tsx +108 -15
  175. package/src/react/frame.tsx +120 -0
  176. package/src/react/index.ts +8 -1
  177. package/src/runtime/contract.ts +339 -0
  178. package/src/runtime/db.ts +650 -0
  179. package/src/runtime/declaration.ts +516 -0
  180. package/src/runtime/levels.ts +69 -0
  181. package/src/runtime/requests.ts +355 -0
  182. package/src/runtime/segments.ts +17 -0
  183. package/src/runtime/types.generated.ts +19 -0
  184. package/src/server/files.ts +138 -7
  185. package/src/server/host.ts +170 -3
  186. package/src/server/index.ts +4 -0
  187. package/src/server/peer.ts +21 -0
  188. package/src/server/proxy.ts +13 -3
  189. package/src/server/pseudonym.ts +21 -0
  190. package/src/server/server.ts +370 -57
  191. package/src/server/types.ts +73 -2
  192. package/src/shell/document.ts +29 -4
  193. package/src/shell/legacy.ts +64 -0
  194. package/src/shell/plan.ts +37 -3
  195. package/src/shell/runtime.ts +390 -56
  196. package/src/shell/use.ts +235 -0
  197. package/types/runtime/v1/artifact.d.ts +50 -0
  198. package/types/runtime/v1/assets.d.ts +43 -0
  199. package/types/runtime/v1/chat.d.ts +13 -0
  200. package/types/runtime/v1/clipboard.d.ts +14 -0
  201. package/types/runtime/v1/comments.d.ts +24 -0
  202. package/types/runtime/v1/context.d.ts +27 -0
  203. package/types/runtime/v1/data.d.ts +29 -0
  204. package/types/runtime/v1/db.d.ts +110 -0
  205. package/types/runtime/v1/downloads.d.ts +22 -0
  206. package/types/runtime/v1/links.d.ts +13 -0
  207. package/types/runtime/v1/porthole.d.ts +44 -0
  208. package/types/runtime/v1/user.d.ts +19 -0
@@ -0,0 +1,86 @@
1
+ /**
2
+ * JSON data, as a host function carries it to a host's handler and its dialog (P095, after the
3
+ * review): what `callTool`'s arguments, `setModelContext`'s content and a download's contents are
4
+ * in MCP, and what a host forwards to a server or a model as JSON. A frame's messages come
5
+ * structured-cloned, so they can hold what JSON can't say or says otherwise: a cycle, an object
6
+ * reached twice (a graph of 30 is 2^30 nodes as a tree), a BigInt, NaN, a boxed `String` (JSON
7
+ * writes its value; a handler gets an object), a Map, a typed array, a Date.
8
+ *
9
+ * Plain data only: null, booleans, finite numbers, strings, arrays and objects whose prototype is
10
+ * Object's or none, each object reached once (MCP's arguments are JSON: an object in two places is
11
+ * refused, the simple bound), at most `nodes` values (a field left `undefined`, allowed as JSON
12
+ * leaves it out, counts as one), `depth` levels, and `chars` characters of strings and keys
13
+ * together (after the re-review: neither a field without a value nor a long string is free).
14
+ * Each node is visited once: linear in what was sent, stopped at the budget. Never throws (a
15
+ * value whose read throws is no data).
16
+ */
17
+ /**
18
+ * A call's: as many values as one db document holds (P091), nested deeper than any real one, and
19
+ * 4 MiB of text.
20
+ */
21
+ export const JSON_DATA_LIMITS = { nodes: 100_000, depth: 64, chars: 4_194_304 };
22
+ export function isJsonData(value, limits = JSON_DATA_LIMITS) {
23
+ let nodes = limits.nodes;
24
+ let chars = limits.chars;
25
+ const seen = new WeakSet();
26
+ /** Takes `length` characters from the budget: whether it still holds. */
27
+ const text = (length) => {
28
+ chars -= length;
29
+ return chars >= 0;
30
+ };
31
+ function plain(each, depth) {
32
+ nodes -= 1;
33
+ if (nodes < 0 || depth > limits.depth) {
34
+ return false;
35
+ }
36
+ if (typeof each === "string") {
37
+ return text(each.length);
38
+ }
39
+ if (each === null || typeof each === "boolean") {
40
+ return true;
41
+ }
42
+ if (typeof each === "number") {
43
+ return Number.isFinite(each);
44
+ }
45
+ if (typeof each !== "object" || seen.has(each)) {
46
+ return false;
47
+ }
48
+ seen.add(each);
49
+ if (Array.isArray(each)) {
50
+ const list = each;
51
+ for (let index = 0; index < list.length; index += 1) {
52
+ if (!plain(list[index], depth + 1)) {
53
+ return false;
54
+ }
55
+ }
56
+ return true;
57
+ }
58
+ const proto = Object.getPrototypeOf(each);
59
+ if (proto !== Object.prototype && proto !== null) {
60
+ return false;
61
+ }
62
+ for (const key of Object.keys(each)) {
63
+ if (!text(key.length)) {
64
+ return false;
65
+ }
66
+ const field = each[key];
67
+ if (field === undefined) {
68
+ // No value, but a field: it counts.
69
+ nodes -= 1;
70
+ if (nodes < 0) {
71
+ return false;
72
+ }
73
+ }
74
+ else if (!plain(field, depth + 1)) {
75
+ return false;
76
+ }
77
+ }
78
+ return true;
79
+ }
80
+ try {
81
+ return plain(value, 0);
82
+ }
83
+ catch {
84
+ return false;
85
+ }
86
+ }
@@ -1,5 +1,10 @@
1
1
  import type { PortholeConfig } from "../config/schema.ts";
2
2
  export declare const withoutSealedAddresses: (text: string) => string;
3
+ /**
4
+ * `text`, at most `max` characters (S05, P095): a cut inside a sealed address's access drops what
5
+ * of it is left, so a text cut before it is scrubbed tells no part of one.
6
+ */
7
+ export declare const cutText: (text: string, max: number) => string;
3
8
  /** An address without what could carry data: an http(s) one's origin and path, else its scheme. */
4
9
  export declare function addressWithoutQuery(url: string): string;
5
10
  /** What the content's errors say about a navigation the shell cancelled. */
@@ -10,6 +10,13 @@
10
10
  */
11
11
  const SEALED = /(?:https?:\/\/[^\s"'<>/]+)?\/__porthole\/f\/[A-Za-z0-9_-]{20,}\//gu;
12
12
  export const withoutSealedAddresses = (text) => text.replace(SEALED, "./");
13
+ /** A sealed address's access, cut off by the end of the text: no longer one `SEALED` matches. */
14
+ const UNFINISHED = /\/__porthole\/f\/[A-Za-z0-9_-]*$/u;
15
+ /**
16
+ * `text`, at most `max` characters (S05, P095): a cut inside a sealed address's access drops what
17
+ * of it is left, so a text cut before it is scrubbed tells no part of one.
18
+ */
19
+ export const cutText = (text, max) => text.length <= max ? text : text.slice(0, max).replace(UNFINISHED, "");
13
20
  /** An address without what could carry data: an http(s) one's origin and path, else its scheme. */
14
21
  export function addressWithoutQuery(url) {
15
22
  // A page's own file (P084), as the shell names it: its path, without query or fragment.
@@ -11,8 +11,12 @@ import type { Refusal } from "./types.ts";
11
11
  * - `not_allowed`: the host doesn't let this content have it, here or at all (a URI it doesn't
12
12
  * serve, a page where data never runs).
13
13
  * - `failed`: the host tried and couldn't.
14
+ * - `forbidden` (P087): the person viewing it may see the content but not do this (their level).
15
+ * - `conflict` (P088): what it changes moved since it was read (a document's version, the
16
+ * artifact's base): read it again, then write.
17
+ * - `too_large` (P088): more than a limit (a document, a batch, an upload, a publish).
14
18
  */
15
- export declare const REFUSAL_CODES: readonly ["consent_required", "denied", "rate_limited", "not_allowed", "failed"];
19
+ export declare const REFUSAL_CODES: readonly ["consent_required", "denied", "rate_limited", "not_allowed", "failed", "forbidden", "conflict", "too_large"];
16
20
  export type RefusalCode = (typeof REFUSAL_CODES)[number];
17
21
  /** What content is told about a refusal: the JSON-RPC error's `data`. */
18
22
  export interface RefusalReason {
@@ -9,6 +9,10 @@
9
9
  * - `not_allowed`: the host doesn't let this content have it, here or at all (a URI it doesn't
10
10
  * serve, a page where data never runs).
11
11
  * - `failed`: the host tried and couldn't.
12
+ * - `forbidden` (P087): the person viewing it may see the content but not do this (their level).
13
+ * - `conflict` (P088): what it changes moved since it was read (a document's version, the
14
+ * artifact's base): read it again, then write.
15
+ * - `too_large` (P088): more than a limit (a document, a batch, an upload, a publish).
12
16
  */
13
17
  export const REFUSAL_CODES = [
14
18
  "consent_required",
@@ -16,6 +20,9 @@ export const REFUSAL_CODES = [
16
20
  "rate_limited",
17
21
  "not_allowed",
18
22
  "failed",
23
+ "forbidden",
24
+ "conflict",
25
+ "too_large",
19
26
  ];
20
27
  /** The most a refusal's message carries to content. */
21
28
  const MAX_MESSAGE = 500;
@@ -68,6 +75,9 @@ const DEFAULT_MESSAGES = {
68
75
  rate_limited: "Too many requests: try again in a minute.",
69
76
  not_allowed: "This isn't available here.",
70
77
  failed: "The app couldn't do this.",
78
+ forbidden: "You don't have permission to do this here.",
79
+ conflict: "This changed since it was read: read it again, then try again.",
80
+ too_large: "This is too large.",
71
81
  };
72
82
  /** Where a data capability's words differ: they name the data. */
73
83
  const DATA_MESSAGES = {
@@ -76,6 +86,9 @@ const DATA_MESSAGES = {
76
86
  rate_limited: "Too many data requests: try again in a minute.",
77
87
  not_allowed: "This data isn't available here.",
78
88
  failed: "The app couldn't get this data.",
89
+ forbidden: "You don't have permission to read this data.",
90
+ conflict: DEFAULT_MESSAGES.conflict,
91
+ too_large: DEFAULT_MESSAGES.too_large,
79
92
  };
80
93
  /** Each refusal's code, as content is told it. */
81
94
  const CODES = {
@@ -87,9 +100,13 @@ const CODES = {
87
100
  redirected: "denied",
88
101
  muted: "denied",
89
102
  "no-consent": "not_allowed",
103
+ "no-show": "not_allowed",
90
104
  denied: "denied",
91
105
  "rate-limited": "rate_limited",
92
106
  failed: "failed",
107
+ undeclared: "not_allowed",
108
+ level: "forbidden",
109
+ "too-large": "too_large",
93
110
  };
94
111
  /** Refusals whose own words say more than their code's. */
95
112
  const OWN_MESSAGES = {
@@ -1,5 +1,8 @@
1
1
  import type { CapabilityArgs, CapabilityName, CapabilityResults, HandledCapability } from "../config/capabilities.ts";
2
2
  import type { InstanceRef } from "../isolation/types.ts";
3
+ import type { RuntimeCapabilityName } from "../runtime/contract.ts";
4
+ import type { DeclaredData, DeclaredDb } from "../runtime/declaration.ts";
5
+ import type { ViewerInfo } from "../runtime/levels.ts";
3
6
  import type { RefusalReason } from "./refusal.ts";
4
7
  /**
5
8
  * The host-function bridge (ARCHITECTURE § Framework layer): carries a capability call from the
@@ -13,11 +16,24 @@ export interface CallContext {
13
16
  /** The display's title, as the host gave it (never the content's words). */
14
17
  readonly title: string;
15
18
  readonly capability: CapabilityName;
19
+ /** The instance the host gave the display (which artifact, which version), if any. */
20
+ readonly instance?: InstanceRef;
21
+ /**
22
+ * Who is viewing, as the host said (P087): the bridge already checked the method's level
23
+ * against it. A host's own API checks again: it is its data's wall.
24
+ */
25
+ readonly viewer?: ViewerInfo;
26
+ /**
27
+ * The page's declaration for this capability (P086): its levels, `data`'s resources and tools,
28
+ * `db`'s rules (the fields of the one it is).
29
+ */
30
+ readonly declared?: DeclaredData & DeclaredDb;
16
31
  }
17
- export type CapabilityHandler<N extends CapabilityName> = (args: CapabilityArgs[N], context: N extends "subscribeData" ? SubscriptionContext : CallContext) => CapabilityResults[N] | Promise<CapabilityResults[N]>;
32
+ export type CapabilityHandler<N extends CapabilityName> = (args: CapabilityArgs[N], context: N extends "subscribeData" ? SubscriptionContext : N extends "db" ? DbContext : CallContext) => CapabilityResults[N] | Promise<CapabilityResults[N]>;
18
33
  /**
19
- * A subscription's context (`subscribeData`, P079): how the host tells the content its resource
20
- * changed, and when to stop.
34
+ * A subscription's context (`subscribeData`, P079; a `db` watch, P088): how the host tells the
35
+ * content its resource changed, and when to stop. A `db` watch's `changed` takes the new state
36
+ * (a snapshot, or a collection's `{ docs }`), which goes to the content as it is.
21
37
  */
22
38
  export interface SubscriptionContext extends CallContext {
23
39
  /**
@@ -29,6 +45,8 @@ export interface SubscriptionContext extends CallContext {
29
45
  /** Aborted when the content unsubscribes, its frame stops, or the display is destroyed. */
30
46
  readonly signal: AbortSignal;
31
47
  }
48
+ /** A `db` call's context: a watch's (`op: "watch"`) carries its channel back and its end. */
49
+ export type DbContext = CallContext & Partial<Pick<SubscriptionContext, "changed" | "signal">>;
32
50
  /** The host's handlers: one for each declared capability served by a handler. */
33
51
  export type CapabilityHandlers = {
34
52
  readonly [N in HandledCapability]?: CapabilityHandler<N>;
@@ -63,6 +81,13 @@ export type ConfirmRequest = {
63
81
  readonly capability: N;
64
82
  readonly args: CapabilityArgs[N];
65
83
  readonly display: ConfirmDisplay;
84
+ /**
85
+ * A confirmation only (never a consent's request): the runtime methods whose own gates
86
+ * (`CapabilityConfig.methodGates`, the contract's) asked for it, of those the call runs (P094):
87
+ * a db batch's writes' ops that need a yes, so a dialog can lead with them. Absent where only
88
+ * the host function's own gates ask.
89
+ */
90
+ readonly askedBy?: readonly string[];
66
91
  };
67
92
  }[CapabilityName];
68
93
  /**
@@ -78,6 +103,17 @@ export type ConfirmAnswer = boolean | "accepted" | "declined" | "redirected";
78
103
  * its own "yes" button, rather than resolving the promise and letting the effect run after.
79
104
  */
80
105
  export type Proceed = () => void;
106
+ /**
107
+ * Puts a call's whole effect in front of the person, outside every frame (the `show` gate, P100):
108
+ * a `setModelContext` update's text and structured content, which the model reads at its next
109
+ * turns. It asks nothing; the call goes once it returns (or its promise resolves), so it resolves
110
+ * only once this very update is visible: drawn, not queued behind a render (after the review). An
111
+ * update the person never saw, because a later one of the display replaced it first, rejects:
112
+ * the call doesn't go. One that throws or rejects stops the call: nobody saw it. Each update
113
+ * replaces the display's last (MCP Apps: the host sends the model the last one), so a surface
114
+ * shows the latest per display.
115
+ */
116
+ export type Show = (request: ConfirmRequest) => void | Promise<void>;
81
117
  /**
82
118
  * Asks a person. Resolves with their answer. The host's UI, or the React binding's default
83
119
  * dialog; drawn outside the frame, never inside it. `proceed` (optional to use) runs the effect
@@ -102,10 +138,25 @@ export type Refusal =
102
138
  | "muted"
103
139
  /** It is `consent`-gated and there is no `consent` function. */
104
140
  | "no-consent"
141
+ /** It is `show`-gated and there is no `show` function: nobody could see it (P100). */
142
+ | "no-show"
105
143
  /** The host's `consent` said no (for this display's life). */
106
144
  | "denied" | "rate-limited"
107
- /** The host's handler threw or rejected. */
108
- | "failed";
145
+ /** The host's handler threw or rejected (or its `show` did: nobody saw the call, P100). */
146
+ | "failed"
147
+ /**
148
+ * The display's page declared capabilities and not this one (P086): a built-in needs none, any
149
+ * other is reachable only by a page that declared it (and only the resources and tools it named).
150
+ */
151
+ | "undeclared"
152
+ /**
153
+ * The viewer's level doesn't reach the method's (P087), or the call reaches data that isn't
154
+ * theirs (another person's `data/users/<id>`); or the host gave the display no viewer, which a
155
+ * runtime capability needs.
156
+ */
157
+ | "level"
158
+ /** Past a limit: a document, a batch, an upload, a publish (P088). */
159
+ | "too-large";
109
160
  export type CallOutcome<T> =
110
161
  /** `stale`: a `readData` answered from the host's cache (`DataCache`). */
111
162
  {
@@ -127,10 +178,27 @@ export interface CallOptions {
127
178
  readonly subscription?: Pick<SubscriptionContext, "changed" | "signal">;
128
179
  /** `readData`: the host's cache may answer, marked stale (the content subscribes to it). */
129
180
  readonly stale?: boolean;
181
+ /**
182
+ * `readData`: a result the host already gave for this read (a subscription's `changed(result)`,
183
+ * the fresh read after a stale answer), and the URI it was given for. It answers the read after
184
+ * every gate a read has, without the handler or the cache (P094: a kept result is never a way
185
+ * past the read's gates); a `uri` that isn't the read's is refused (`invalid`). Ignored for any
186
+ * capability but `readData`.
187
+ */
188
+ readonly held?: {
189
+ readonly uri: string;
190
+ readonly value: unknown;
191
+ };
130
192
  }
131
193
  /** What adapters call; one per display. */
132
194
  export interface HostFunctionBridge {
133
195
  /** Validates `args` for `capability`, applies its gates, then runs the host's handler. */
134
196
  call<N extends CapabilityName>(capability: N, args: unknown, options?: CallOptions): Promise<CallOutcome<CapabilityResults[N]>>;
135
197
  declared(capability: CapabilityName): boolean;
198
+ /**
199
+ * What the runtime offers this display (P085): each runtime capability it may `use`, with its
200
+ * methods. Empty without `config.runtime`. The same whatever the viewer's level: levels refuse
201
+ * at call time.
202
+ */
203
+ roster(): Readonly<Partial<Record<RuntimeCapabilityName, readonly string[]>>>;
136
204
  }
@@ -1,3 +1,4 @@
1
+ import type { PageDeclaration } from "../runtime/declaration.ts";
1
2
  import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
2
3
  import { type FileContents, type FileFinding } from "./files.ts";
3
4
  import { type CheckCall } from "./instrument.ts";
@@ -43,6 +44,12 @@ export interface CheckOptions {
43
44
  readonly files?: FileContents;
44
45
  /** The page a set opens at (default `index.html`). */
45
46
  readonly entry?: string;
47
+ /**
48
+ * Under a runtime (P085): what the page declares (default null: a page with none, so a
49
+ * declared capability is null in the check, as in a preview). Its calls are answered as a
50
+ * declining host answers, by a view-level viewer.
51
+ */
52
+ readonly declaration?: PageDeclaration | null;
46
53
  readonly driver: CheckDriver;
47
54
  /** Widths, px. Default: the manual's phone and desktop widths (`config.layout`). */
48
55
  readonly widths?: readonly number[];
@@ -141,6 +141,7 @@ export async function checkPage(options) {
141
141
  content,
142
142
  scriptLines,
143
143
  ...(instance === undefined ? {} : { instance }),
144
+ ...(options.declaration === undefined ? {} : { declaration: options.declaration }),
144
145
  widthPx: width,
145
146
  ...(fills ? { heightPx: 700 } : {}),
146
147
  scheme,
@@ -1,3 +1,4 @@
1
+ import type { PageDeclaration } from "../runtime/declaration.ts";
1
2
  import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
2
3
  import type { InstanceRef } from "../isolation/types.ts";
3
4
  /**
@@ -12,6 +13,8 @@ export interface CheckRunSpec {
12
13
  readonly scriptLines: readonly number[];
13
14
  /** A served config's instance (located through the check's own server), else opaque. */
14
15
  readonly instance?: InstanceRef;
16
+ /** Under a runtime: the page's declaration (null: none). */
17
+ readonly declaration?: PageDeclaration | null;
15
18
  readonly widthPx: number;
16
19
  readonly heightPx?: number;
17
20
  readonly scheme: ColorScheme;
@@ -109,7 +109,9 @@ export function lintContent(config, content) {
109
109
  const clipboard = /\bnavigator\s*\.\s*clipboard\b|\bexecCommand\s*\(\s*["'](?:copy|cut)["']/u.exec(content);
110
110
  if (clipboard !== null) {
111
111
  add("clipboard", "warning", declared.has("copyText")
112
- ? "The clipboard is closed to content: a copy button calls copyText(text) from its click."
112
+ ? config.runtime === undefined
113
+ ? "The clipboard is closed to content: a copy button calls copyText(text) from its click."
114
+ : 'The clipboard is closed to content: a copy button calls (await porthole.use("clipboard")).copy(text) from its click.'
113
115
  : "The clipboard is closed to content: copying from a button doesn't work here.", clipboard.index);
114
116
  }
115
117
  const dialog = /(?:^|[^.\w$])(?:window\s*\.\s*)?(alert|confirm|prompt)\s*\(/u.exec(content);
@@ -139,7 +141,7 @@ export function lintContent(config, content) {
139
141
  egressOrigins(config, kind).some((source) => source === origin || originMatchesSource(origin, source));
140
142
  if (!open && !reported.has(`${kind} ${origin}`)) {
141
143
  reported.add(`${kind} ${origin}`);
142
- add("egress", "warning", `Nothing loads from ${origin} here (${kind}): ${kind === "script" && librarySources(config).length > 0 ? "write it inline, or use one of the libraries served here (the manual's Libraries)" : kind === "script" || kind === "style" ? "write it inline, or use a library from an allowed CDN" : kind === "connect" && config.capabilities.readData !== undefined ? "the content can't call it; read the app's data with readData" : kind === "connect" ? "the content can't call it; work from data in the content" : "put it inline as a data: URL"}.`, match.index);
144
+ add("egress", "warning", `Nothing loads from ${origin} here (${kind}): ${kind === "script" && librarySources(config).length > 0 ? "write it inline, or use one of the libraries served here (the manual's Libraries)" : kind === "script" || kind === "style" ? "write it inline, or use a library from an allowed CDN" : kind === "connect" && config.capabilities.readData !== undefined ? `the content can't call it; read the app's data with ${config.runtime === undefined ? "readData" : "data.read"}` : kind === "connect" ? "the content can't call it; work from data in the content" : "put it inline as a data: URL"}.`, match.index);
143
145
  }
144
146
  const own = OWN_CDN.find((each) => each.host.test(address));
145
147
  if (own !== undefined && kind === "script" && !own.pinned.test(new URL(address).pathname)) {