@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
@@ -1,5 +1,6 @@
1
1
  import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
- import { useEffect, useId, useRef, useState } from "react";
2
+ import { useEffect, useId, useMemo, useRef, useState } from "react";
3
+ import { formatBounded } from "../bridge/bounded-text.js";
3
4
  /**
4
5
  * The default confirmation dialog (P019): drawn by the host's page, outside every frame, as a
5
6
  * modal (the top layer covers the frames, so content can't draw over it or click it). It shows
@@ -11,7 +12,42 @@ import { useEffect, useId, useRef, useState } from "react";
11
12
  */
12
13
  /** How long the accept button ignores presses after the dialog opens. */
13
14
  export const ARM_DELAY_MS = 500;
14
- const json = (value) => JSON.stringify(value, null, 2) ?? "";
15
+ /**
16
+ * What a call carries, as JSON laid out, within bounds (P095): a frame's arguments come
17
+ * structured-cloned, so a cycle, a BigInt, or a graph billions of nodes long as a tree. Past the
18
+ * bounds the dialog says it shows only part.
19
+ */
20
+ const DIALOG_TEXT_LIMITS = { chars: 20_000, nodes: 2_000, depth: 24 };
21
+ function carried(heading, accept, value, before = "") {
22
+ const { text, whole } = formatBounded(value, DIALOG_TEXT_LIMITS, 2);
23
+ return {
24
+ heading,
25
+ accept,
26
+ detail: `${before}${text}`,
27
+ ...(whole ? {} : { note: "Only part of it is shown: it is more than this dialog shows." }),
28
+ };
29
+ }
30
+ /** How many of one kind of write the summary names before it counts the rest. */
31
+ const MOST_PATHS = 10;
32
+ /**
33
+ * A db change in a line (P094): the writes whose own gates asked for the yes, by kind ("Delete
34
+ * n/x, n/y; and 48 other writes."), or every write by kind where none of them asked (the host
35
+ * function's own confirmation); at most `MOST_PATHS` paths a kind, then a count.
36
+ */
37
+ function writesSummary(writes, askedBy) {
38
+ const asked = writes.filter((each) => askedBy.includes(each.op));
39
+ const lead = asked.length === 0 ? writes : asked;
40
+ const kinds = new Map();
41
+ for (const each of lead) {
42
+ kinds.set(each.op, [...(kinds.get(each.op) ?? []), each.path]);
43
+ }
44
+ const said = [...kinds]
45
+ .map(([op, paths]) => `${op} ${paths.slice(0, MOST_PATHS).join(", ")}${paths.length > MOST_PATHS ? ` and ${paths.length - MOST_PATHS} more` : ""}`)
46
+ .join("; ");
47
+ const others = writes.length - lead.length;
48
+ const text = `${said}${others === 0 ? "" : `; and ${others} other write${others === 1 ? "" : "s"}`}.`;
49
+ return text.charAt(0).toUpperCase() + text.slice(1);
50
+ }
15
51
  function words(request) {
16
52
  switch (request.capability) {
17
53
  case "sendPrompt":
@@ -32,33 +68,72 @@ function words(request) {
32
68
  };
33
69
  }
34
70
  case "downloadFile":
35
- return {
36
- heading: "Download this file?",
37
- accept: "Download",
38
- detail: json(request.args.contents),
39
- };
71
+ return carried("Download this file?", "Download", request.args.contents);
40
72
  case "callTool":
41
- return {
42
- heading: "Run this tool?",
43
- accept: "Run",
44
- detail: `${request.args.name}\n${json(request.args.arguments)}`,
45
- };
73
+ return carried("Run this tool?", "Run", request.args.arguments, `${request.args.name}\n`);
46
74
  case "setModelContext":
47
- return { heading: "Share this with the agent?", accept: "Share", detail: json(request.args) };
75
+ return carried("Share this with the agent?", "Share", request.args);
48
76
  case "readData":
49
77
  return { heading: "Let it read this?", accept: "Allow", detail: request.args.uri };
50
78
  case "subscribeData":
51
79
  return { heading: "Let it follow this?", accept: "Allow", detail: request.args.uri };
52
80
  case "copyText":
53
81
  return { heading: "Copy this text?", accept: "Copy", detail: request.args.text };
82
+ // The runtime's (P088, P089): the whole effect, as the page asked for it.
83
+ case "artifact":
84
+ return request.args.op === "publish"
85
+ ? {
86
+ heading: "Publish a new version of this page?",
87
+ accept: "Publish",
88
+ detail: Object.entries(request.args.files)
89
+ .map(([path, file]) => file === null
90
+ ? `${path}: removed`
91
+ : "text" in file
92
+ ? `${path}: ${file.text.length.toLocaleString("en-US")} characters`
93
+ : `${path}: ${Math.floor((file.base64.length * 3) / 4).toLocaleString("en-US")} bytes`)
94
+ .join("\n"),
95
+ note: `From version ${request.args.base}${request.args.label === undefined ? "" : `: ${request.args.label}`}.`,
96
+ }
97
+ : carried("Allow this?", "Allow", request.args);
98
+ case "assets":
99
+ return request.args.op === "upload"
100
+ ? {
101
+ heading: "Add this file to the page's library?",
102
+ accept: "Add",
103
+ detail: `${request.args.name} (${request.args.type}, ${request.args.size.toLocaleString("en-US")} bytes)`,
104
+ note: "Everyone who can see the page can load it.",
105
+ }
106
+ : request.args.op === "delete"
107
+ ? {
108
+ heading: "Remove this file from the page's library?",
109
+ accept: "Remove",
110
+ detail: request.args.id,
111
+ }
112
+ : carried("Allow this?", "Allow", request.args);
113
+ // The page's shared data (P088): a change leads with what asked for the yes (P094).
114
+ case "db": {
115
+ const args = request.args;
116
+ const writes = args.op === "batch"
117
+ ? args.writes
118
+ : args.op === "set" || args.op === "update" || args.op === "delete"
119
+ ? [args]
120
+ : null;
121
+ return writes === null
122
+ ? carried("Allow this?", "Allow", args)
123
+ : {
124
+ ...carried("Change this page's shared data?", "Change", args),
125
+ summary: writesSummary(writes, request.askedBy ?? []),
126
+ };
127
+ }
54
128
  default:
55
- return { heading: "Allow this?", accept: "Allow", detail: json(request.args) };
129
+ return carried("Allow this?", "Allow", request.args);
56
130
  }
57
131
  }
58
132
  const STYLE = `.porthole-confirm{color-scheme:light dark;color:CanvasText;background:Canvas;border:1px solid color-mix(in srgb,CanvasText 18%,transparent);border-radius:12px;padding:20px;width:min(440px,calc(100vw - 32px));font:inherit;box-shadow:0 12px 40px rgb(0 0 0 / .28)}
59
133
  .porthole-confirm::backdrop{background:rgb(0 0 0 / .4)}
60
134
  .porthole-confirm h2{font-size:1.05em;margin:0 0 4px}
61
135
  .porthole-confirm [data-porthole-source],.porthole-confirm [data-porthole-note]{opacity:.72;font-size:.9em;margin:0 0 12px}
136
+ .porthole-confirm [data-porthole-summary]{font-weight:600;overflow-wrap:anywhere;max-height:20vh;overflow:auto;margin:0 0 12px}
62
137
  .porthole-confirm [data-porthole-detail]{white-space:pre-wrap;overflow-wrap:anywhere;max-height:40vh;overflow:auto;padding:10px 12px;border-radius:8px;background:color-mix(in srgb,CanvasText 7%,transparent);margin:0 0 12px;font:inherit}
63
138
  .porthole-confirm menu{display:flex;justify-content:flex-end;gap:8px;margin:16px 0 0;padding:0}
64
139
  .porthole-confirm button{font:inherit;min-height:36px;padding:0 14px;border-radius:8px;border:1px solid color-mix(in srgb,CanvasText 25%,transparent);background:transparent;color:inherit;cursor:pointer}
@@ -88,13 +163,13 @@ export function ConfirmDialog({ request, onAnswer, className }) {
88
163
  const timer = setTimeout(() => setArmedFor(request), ARM_DELAY_MS);
89
164
  return () => clearTimeout(timer);
90
165
  }, [request]);
91
- const said = request === null ? null : words(request);
166
+ const said = useMemo(() => (request === null ? null : words(request)), [request]);
92
167
  return (_jsxs("dialog", { ref: dialog, className: className === undefined ? "porthole-confirm" : `porthole-confirm ${className}`, "aria-labelledby": heading, "data-porthole-confirm": request?.capability ?? "", onCancel: (event) => {
93
168
  event.preventDefault();
94
169
  if (request !== null) {
95
170
  onAnswer(false);
96
171
  }
97
- }, children: [_jsx("style", { children: STYLE }), said === null || request === null ? null : (_jsxs(_Fragment, { children: [_jsx("h2", { id: heading, children: said.heading }), _jsx("p", { "data-porthole-source": "", children: `From “${request.display.title}”` }), _jsx("div", { "data-porthole-detail": "", children: said.detail }), said.note === undefined ? null : _jsx("p", { "data-porthole-note": "", children: said.note }), _jsxs("menu", { children: [_jsx("button", { type: "button", ref: cancel, autoFocus: true, "data-porthole-cancel": "", onClick: () => onAnswer(false), children: "Cancel" }), _jsx("button", { type: "button", "data-porthole-accept": "", "data-armed": String(armed), onClick: () => {
172
+ }, children: [_jsx("style", { children: STYLE }), said === null || request === null ? null : (_jsxs(_Fragment, { children: [_jsx("h2", { id: heading, children: said.heading }), _jsx("p", { "data-porthole-source": "", children: `From “${request.display.title}”` }), said.summary === undefined ? null : _jsx("p", { "data-porthole-summary": "", children: said.summary }), _jsx("div", { "data-porthole-detail": "", children: said.detail }), said.note === undefined ? null : _jsx("p", { "data-porthole-note": "", children: said.note }), _jsxs("menu", { children: [_jsx("button", { type: "button", ref: cancel, autoFocus: true, "data-porthole-cancel": "", onClick: () => onAnswer(false), children: "Cancel" }), _jsx("button", { type: "button", "data-porthole-accept": "", "data-armed": String(armed), onClick: () => {
98
173
  if (armed) {
99
174
  onAnswer(true);
100
175
  }
@@ -1,6 +1,8 @@
1
+ import type { PageDeclaration } from "../runtime/declaration.ts";
2
+ import type { ViewerInfo } from "../runtime/levels.ts";
1
3
  import { type CSSProperties, type ReactElement, type ReactNode } from "react";
2
4
  import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
3
- import type { CapabilityHandler, CapabilityHandlers, Confirm, ConfirmRequest, Consent, DataCache, Refusal } from "../bridge/types.ts";
5
+ import type { CapabilityHandler, CapabilityHandlers, Confirm, ConfirmRequest, Consent, DataCache, Refusal, Show } from "../bridge/types.ts";
4
6
  import { Refused, type RefusalReason } from "../bridge/refusal.ts";
5
7
  import type { CapabilityName } from "../config/capabilities.ts";
6
8
  import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
@@ -38,6 +40,8 @@ interface PageState {
38
40
  readonly locate?: InstanceLocator["locate"];
39
41
  /** The default `copyText`: copies on the host's page and shows the toast (P052). */
40
42
  readonly copyText?: CapabilityHandler<"copyText">;
43
+ /** Who shows the person `show`-gated calls: the provider's own, or its notice (P100). */
44
+ readonly show?: Show;
41
45
  }
42
46
  /** The provider's page state, for the binding's other components (`PortholeView`). */
43
47
  export declare const PortholeContext: import("react").Context<PageState>;
@@ -89,6 +93,13 @@ export interface PortholeProviderProps {
89
93
  * refuses them all with its reason, and their handlers may be left out (P080).
90
94
  */
91
95
  readonly consent?: Consent | Refused;
96
+ /**
97
+ * Shows the person each `show`-gated call, outside every frame, before its handler has it
98
+ * (P100): by default, a frame's model context update (`setModelContext`), the content's text for
99
+ * the agent's next turn. Omitted: Porthole's `ContextNotice`. A host that shows it its own way (a
100
+ * chip by its composer) passes this; the update replaces the display's last.
101
+ */
102
+ readonly show?: Show;
92
103
  /** What the host last had for a resource, answered stale first (P079). */
93
104
  readonly cached?: DataCache;
94
105
  /** How the host names itself in the handshake. */
@@ -102,6 +113,8 @@ export interface PortholeProviderProps {
102
113
  readonly dialogClassName?: string;
103
114
  /** A class for the default copy toast, to restyle it. */
104
115
  readonly toastClassName?: string;
116
+ /** A class for the default model context notice, to restyle it. */
117
+ readonly contextClassName?: string;
105
118
  /**
106
119
  * The page's CSP nonce, where its `script-src` is nonce-based: opaque frames inherit the page's
107
120
  * policy, so their shell carries it (P054). `"auto"`: read from the page (a `<meta
@@ -145,6 +158,17 @@ export interface PortholeFrameProps {
145
158
  * shows, for its confirmations only, never sent to the frame (P077).
146
159
  */
147
160
  readonly instance?: InstanceRef;
161
+ /**
162
+ * What the page declared (P086), as the host stored it with the artifact: the capabilities it
163
+ * reaches through `porthole.use`, and its pinned runtime. By value: a change makes the display
164
+ * again.
165
+ */
166
+ readonly declaration?: PageDeclaration;
167
+ /**
168
+ * Who is viewing (P087), for an opaque frame or one whose issue gave none. By value: a change
169
+ * makes the display again.
170
+ */
171
+ readonly viewer?: ViewerInfo;
148
172
  /** The color scheme it shows in. Default: the provider's `scheme`, else light. */
149
173
  readonly scheme?: ColorScheme;
150
174
  /** The host's live values for the config's theme variables (from its design tokens). */
@@ -4,6 +4,7 @@ import { isRefused, reasonOf, Refused } from "../bridge/refusal.js";
4
4
  import { writeClipboard } from "../host/clipboard.js";
5
5
  import { createHost } from "../host/create-host.js";
6
6
  import { ConfirmDialog } from "./dialog.js";
7
+ import { ContextNotice } from "./context-notice.js";
7
8
  import { createLiveFrames } from "./live.js";
8
9
  import { CopyToast } from "./toast.js";
9
10
  /**
@@ -12,6 +13,9 @@ import { CopyToast } from "./toast.js";
12
13
  * display mounts it when it nears the screen, streams its content, flips its theme, and remembers
13
14
  * its height. All the isolation is the core's (`createHost`); this is mounting and lifecycle.
14
15
  */
16
+ /** Why a model context update didn't go: it was never drawn (the review of P100). */
17
+ const REPLACED_UNSEEN = "a later update of this display replaced it before the person saw it";
18
+ const HIDDEN_UNSEEN = "the person hid this display's notice before the update was drawn";
15
19
  /** How far off screen a frame starts (and keeps) running. */
16
20
  const NEAR_SCREEN = "800px 0px";
17
21
  /** The height a display holds before it has reported its own. */
@@ -84,6 +88,67 @@ export function PortholeProvider(props) {
84
88
  return copied;
85
89
  }, []);
86
90
  const closeNotice = useCallback(() => setNotice(null), []);
91
+ // The default show (P100): each display's latest model context update, in the notice, outside
92
+ // every frame; the host's own `show` replaces it.
93
+ const [contexts, setContexts] = useState([]);
94
+ // Each show waiting for its own update to be on the page (after the review: React may draw two
95
+ // updates of a display in one render, the latest only). The number orders a display's shows.
96
+ const unseen = useRef([]);
97
+ const latest = useRef(new Map());
98
+ const sequence = useRef(0);
99
+ useLayoutEffect(() => {
100
+ unseen.current = unseen.current.filter((each) => {
101
+ const drawn = contexts.find((one) => one.displayId === each.entry.displayId);
102
+ if (drawn === each.entry) {
103
+ each.resolve();
104
+ return false;
105
+ }
106
+ // A later update of the display replaced it before it was drawn: never seen, never sent.
107
+ if ((latest.current.get(each.entry.displayId) ?? 0) > each.seq) {
108
+ each.reject(new Error(REPLACED_UNSEEN));
109
+ return false;
110
+ }
111
+ return true;
112
+ });
113
+ }, [contexts]);
114
+ const ownShow = useRef(props.show);
115
+ useLayoutEffect(() => {
116
+ ownShow.current = props.show;
117
+ });
118
+ const show = useCallback((request) => {
119
+ if (ownShow.current !== undefined) {
120
+ return ownShow.current(request);
121
+ }
122
+ if (request.capability !== "setModelContext") {
123
+ // The notice words model context only: anything else it would show unworded, so it isn't
124
+ // shown, and doesn't go (fail closed).
125
+ throw new Error(`Porthole's notice shows model context only, not ${request.capability}`);
126
+ }
127
+ const entry = {
128
+ displayId: request.display.id,
129
+ title: request.display.title,
130
+ update: request.args,
131
+ };
132
+ sequence.current += 1;
133
+ const seq = sequence.current;
134
+ latest.current.set(entry.displayId, seq);
135
+ // The call goes once this very update is on the page, so the handler never has it first.
136
+ return new Promise((resolve, reject) => {
137
+ unseen.current.push({ entry, seq, resolve, reject });
138
+ setContexts((each) => [...each.filter((one) => one.displayId !== entry.displayId), entry]);
139
+ });
140
+ }, []);
141
+ const hideContext = useCallback((displayId) => {
142
+ // Hidden by the person: an update of the display not drawn yet never will be.
143
+ unseen.current = unseen.current.filter((each) => {
144
+ if (each.entry.displayId !== displayId) {
145
+ return true;
146
+ }
147
+ each.reject(new Error(HIDDEN_UNSEEN));
148
+ return false;
149
+ });
150
+ setContexts((each) => each.filter((one) => one.displayId !== displayId));
151
+ }, []);
87
152
  // Compared by value, and read when used: an inline hostInfo or locator doesn't start every
88
153
  // frame again on each render.
89
154
  const hostInfo = useByValue(props.hostInfo);
@@ -131,6 +196,7 @@ export function PortholeProvider(props) {
131
196
  heights,
132
197
  confirm,
133
198
  copyText,
199
+ show,
134
200
  ...(consents ? { consent } : {}),
135
201
  ...(refusesAll === undefined ? {} : { refusesAll }),
136
202
  ...(caches ? { cached } : {}),
@@ -147,6 +213,7 @@ export function PortholeProvider(props) {
147
213
  heights,
148
214
  confirm,
149
215
  copyText,
216
+ show,
150
217
  consents,
151
218
  consent,
152
219
  refusesAll,
@@ -187,7 +254,7 @@ export function PortholeProvider(props) {
187
254
  }
188
255
  current?.resolve(accepted ? "accepted" : "declined");
189
256
  setQueue((waiting) => waiting.slice(1));
190
- } })) : null, props.notify !== undefined ? null : (_jsx(CopyToast, { notice: notice, ...(props.toastClassName === undefined ? {} : { className: props.toastClassName }), onClose: closeNotice, onCopy: (failed) => {
257
+ } })) : null, props.show !== undefined ? null : (_jsx(ContextNotice, { updates: contexts, onHide: hideContext, ...(props.contextClassName === undefined ? {} : { className: props.contextClassName }) })), props.notify !== undefined ? null : (_jsx(CopyToast, { notice: notice, ...(props.toastClassName === undefined ? {} : { className: props.toastClassName }), onClose: closeNotice, onCopy: (failed) => {
191
258
  // A click on the host's own page: the write has the gesture it needs now.
192
259
  void writeClipboard(failed.text, globalThis.document).then((copied) => setNotice({ ...failed, copied }));
193
260
  } }))] }));
@@ -292,6 +359,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
292
359
  // By value: a config or instance made inline (each render) is the same display.
293
360
  const config = useByValue(frame.config);
294
361
  const instance = useByValue(frame.instance);
362
+ const declaration = useByValue(frame.declaration);
363
+ const viewer = useByValue(frame.viewer);
295
364
  const fills = config.mode === "url" || frame.fill === true || config.layout.kind === "fill";
296
365
  // A consent that refuses everything (P080), this frame's or else the provider's, by value: a
297
366
  // display made with it needs no data handlers, so a change makes the display again.
@@ -303,7 +372,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
303
372
  // value) re-themes the running display, never makes it again (#9, P074). What a display is
304
373
  // made with comes from the provider's stable parts below.
305
374
  const latestPage = useEffectEvent(() => page);
306
- const { handlers: pageHandlers, copyText: pageCopyText, confirm: pageConfirm, consent: pageConsent, cached: pageCached, hostInfo, locate, nonce, } = page;
375
+ const { handlers: pageHandlers, copyText: pageCopyText, confirm: pageConfirm, consent: pageConsent, show: pageShow, cached: pageCached, hostInfo, locate, nonce, } = page;
307
376
  const notify = useEffectEvent((event, detail) => {
308
377
  switch (event) {
309
378
  case "initialized":
@@ -420,6 +489,15 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
420
489
  },
421
490
  }
422
491
  : {}),
492
+ // Shown as the latest props name the display (P100).
493
+ ...(pageShow === undefined
494
+ ? {}
495
+ : {
496
+ show: (request) => pageShow({
497
+ ...request,
498
+ display: { ...request.display, id: latest().displayId, title: latest().title },
499
+ }),
500
+ }),
423
501
  ...(caches
424
502
  ? {
425
503
  cached: (args, context) => (latest().cached ?? pageCached)?.(args, named(context)),
@@ -436,6 +514,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
436
514
  initialHeightPx: startHeight,
437
515
  ...(view === undefined ? {} : { document: view }),
438
516
  ...(instance === undefined ? {} : { instance }),
517
+ ...(declaration === undefined ? {} : { declaration }),
518
+ ...(viewer === undefined ? {} : { viewer }),
439
519
  ...(fills ? { fill: true } : {}),
440
520
  });
441
521
  }
@@ -477,12 +557,15 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
477
557
  config,
478
558
  view,
479
559
  instance,
560
+ declaration,
561
+ viewer,
480
562
  startHeight,
481
563
  fills,
482
564
  pageHandlers,
483
565
  pageCopyText,
484
566
  pageConfirm,
485
567
  pageConsent,
568
+ pageShow,
486
569
  pageCached,
487
570
  refusesAll,
488
571
  hostInfo,
@@ -2,7 +2,7 @@
2
2
  * `@botiverse/porthole/react`: the thin React binding (TSX: a host's bundler compiles it, or the
3
3
  * package's `dist`). Peer: `react` (19.2+, for `useEffectEvent`).
4
4
  *
5
- * <PortholeProvider> // per page: live-frame cap, heights, the dialog, the copy toast
5
+ * <PortholeProvider> // per page: live-frame cap, heights, the dialog, the copy toast, the context notice
6
6
  * <PortholeFrame config={widgetConfig} displayId={id} title={title} scheme={scheme}
7
7
  * content={code} partial={streaming} handlers={{ sendPrompt, openLink }}
8
8
  * theme={tokensFor} onError={report} />
@@ -10,6 +10,7 @@
10
10
  */
11
11
  export { PLACEHOLDER_HEIGHT_PX, PortholeFrame, PortholeProvider, type PlaceholderProps, type PortholeFrameProps, type ConfirmActions, type PortholeProviderProps, } from "./frame.tsx";
12
12
  export { ARM_DELAY_MS, ConfirmDialog, type ConfirmDialogProps } from "./dialog.tsx";
13
+ export { ContextNotice, contextSize, contextText, type ContextNoticeProps, type ContextUpdate, } from "./context-notice.tsx";
13
14
  export { cssVariableTheme, PortholeView, usePortholeLink, useRunAgain, type PortholeFallbackProps, type PortholeViewProps, } from "./view.tsx";
14
15
  export { CopyToast, TOAST_CHARS, TOAST_MS, clipped, type CopyNotice, type CopyToastProps, } from "./toast.tsx";
15
16
  export { admitFrame, createLiveFrames, type FrameState, type LiveFrames } from "./live.ts";
@@ -2,7 +2,7 @@
2
2
  * `@botiverse/porthole/react`: the thin React binding (TSX: a host's bundler compiles it, or the
3
3
  * package's `dist`). Peer: `react` (19.2+, for `useEffectEvent`).
4
4
  *
5
- * <PortholeProvider> // per page: live-frame cap, heights, the dialog, the copy toast
5
+ * <PortholeProvider> // per page: live-frame cap, heights, the dialog, the copy toast, the context notice
6
6
  * <PortholeFrame config={widgetConfig} displayId={id} title={title} scheme={scheme}
7
7
  * content={code} partial={streaming} handlers={{ sendPrompt, openLink }}
8
8
  * theme={tokensFor} onError={report} />
@@ -10,6 +10,7 @@
10
10
  */
11
11
  export { PLACEHOLDER_HEIGHT_PX, PortholeFrame, PortholeProvider, } from "./frame.js";
12
12
  export { ARM_DELAY_MS, ConfirmDialog } from "./dialog.js";
13
+ export { ContextNotice, contextSize, contextText, } from "./context-notice.js";
13
14
  export { cssVariableTheme, PortholeView, usePortholeLink, useRunAgain, } from "./view.js";
14
15
  export { CopyToast, TOAST_CHARS, TOAST_MS, clipped, } from "./toast.js";
15
16
  export { admitFrame, createLiveFrames } from "./live.js";
@@ -0,0 +1,201 @@
1
+ import type { CapabilityName, Gate } from "../config/capabilities.ts";
2
+ import type { PortholeConfig } from "../config/schema.ts";
3
+ import { type ViewerLevel } from "./levels.ts";
4
+ /**
5
+ * The capability runtime's contract (P085): what a page reaches through its one global,
6
+ * `porthole.use(name)`, by contract version. A version is pinned per artifact when it is published
7
+ * (`declareCapabilities`) and served as pinned, so a page keeps the API it was written against.
8
+ *
9
+ * Each runtime capability is a namespace of methods; each method is served by one of the config's
10
+ * host functions (PRINCIPLE 4: the config still says what the host offers, with its gates), needs
11
+ * a viewer level (P087), and is either a call or a watch (a subscription). A built-in is reachable
12
+ * by any page whose host offers it; every other one only by a page that declared it (P086).
13
+ */
14
+ /** The contract versions this Porthole serves. */
15
+ export declare const RUNTIME_VERSIONS: readonly ["1"];
16
+ export type RuntimeVersion = (typeof RUNTIME_VERSIONS)[number];
17
+ /** The version a declaration is pinned to unless its author asks for another. */
18
+ export declare const RUNTIME_VERSION: RuntimeVersion;
19
+ export declare function isRuntimeVersion(value: unknown): value is RuntimeVersion;
20
+ /** The one global the shell defines for the runtime, with `use` its only member. */
21
+ export declare const RUNTIME_GLOBAL = "porthole";
22
+ /** Where the host's roster goes in the handshake: MCP Apps' experimental host capabilities. */
23
+ export declare const RUNTIME_EXPERIMENTAL_KEY = "porthole/runtime";
24
+ /** A runtime call (own-prefixed, P002): `{ capability, method, args }`. */
25
+ export declare const RUNTIME_CALL_METHOD = "porthole/call";
26
+ /** A watch's end, frame to host (a notification, never gated): `{ watch }`. */
27
+ export declare const RUNTIME_UNWATCH_METHOD = "porthole/unwatch";
28
+ /** A watch's update, host to frame: `{ watch, data }`. */
29
+ export declare const RUNTIME_EVENT_METHOD = "porthole/event";
30
+ export interface RuntimeMethod {
31
+ /** The config's host function that serves it: declared there, gated as it says. */
32
+ readonly serves: CapabilityName;
33
+ /** The least level that may call it, unless the host's config or the page's says more. */
34
+ readonly level: ViewerLevel;
35
+ /** The least a host's config may set it to (`CapabilityConfig.levels`). */
36
+ readonly floor: ViewerLevel;
37
+ /** A subscription: the content passes callbacks and gets a function that stops it. */
38
+ readonly watch?: true;
39
+ /**
40
+ * Gates of its own, over its host function's (after the review, P088): what changes the
41
+ * artifact for everyone needs the person's click and their yes. A host's config may replace
42
+ * them (`CapabilityConfig.methodGates`).
43
+ */
44
+ readonly gates?: readonly Gate[];
45
+ }
46
+ export interface RuntimeCapability {
47
+ /**
48
+ * Built in (P086): any page whose host offers it may use it without declaring it: the effect is
49
+ * the host's own UI, shown to the person (a copy, a link, a download, the comment composer).
50
+ */
51
+ readonly builtIn: boolean;
52
+ readonly methods: Readonly<Record<string, RuntimeMethod>>;
53
+ }
54
+ /** Contract 1's capabilities, by the name a page passes to `use`. */
55
+ export declare const RUNTIME_CAPABILITIES: {
56
+ /** Who is viewing: `{ id, name, level }`, as the host says. Declared: the page learns who. */
57
+ readonly user: {
58
+ readonly builtIn: false;
59
+ readonly methods: {
60
+ readonly get: RuntimeMethod;
61
+ };
62
+ };
63
+ /** Opens the host's comment composer at an anchor the page names. Write-only (P090). */
64
+ readonly comments: {
65
+ readonly builtIn: true;
66
+ readonly methods: {
67
+ readonly open: RuntimeMethod;
68
+ };
69
+ };
70
+ /** Copies text, done and shown by the host (P051, P052). */
71
+ readonly clipboard: {
72
+ readonly builtIn: true;
73
+ readonly methods: {
74
+ readonly copy: RuntimeMethod;
75
+ };
76
+ };
77
+ /** Opens an http(s) link outside the frame. */
78
+ readonly links: {
79
+ readonly builtIn: true;
80
+ readonly methods: {
81
+ readonly open: RuntimeMethod;
82
+ };
83
+ };
84
+ /** Hands the person a file to save. */
85
+ readonly downloads: {
86
+ readonly builtIn: true;
87
+ readonly methods: {
88
+ readonly save: RuntimeMethod;
89
+ };
90
+ };
91
+ /** Sends text to the agent as the person's message. */
92
+ readonly chat: {
93
+ readonly builtIn: false;
94
+ readonly methods: {
95
+ readonly send: RuntimeMethod;
96
+ };
97
+ };
98
+ /** The host's data (MCP resources and tools, P079): read, follow, call. */
99
+ readonly data: {
100
+ readonly builtIn: false;
101
+ readonly methods: {
102
+ readonly read: RuntimeMethod;
103
+ readonly subscribe: RuntimeMethod;
104
+ readonly call: RuntimeMethod;
105
+ };
106
+ };
107
+ /** Context for the agent's next turns. */
108
+ readonly context: {
109
+ readonly builtIn: false;
110
+ readonly methods: {
111
+ readonly set: RuntimeMethod;
112
+ };
113
+ };
114
+ /** This artifact itself: its current version, and a new version of it (P088). */
115
+ readonly artifact: {
116
+ readonly builtIn: false;
117
+ readonly methods: {
118
+ readonly get: RuntimeMethod;
119
+ readonly publish: RuntimeMethod;
120
+ };
121
+ };
122
+ /** The artifact's asset library, served at `/_blob/<id>` (P089). */
123
+ readonly assets: {
124
+ readonly builtIn: false;
125
+ readonly methods: {
126
+ readonly list: RuntimeMethod;
127
+ readonly url: RuntimeMethod;
128
+ readonly upload: RuntimeMethod;
129
+ readonly delete: RuntimeMethod;
130
+ };
131
+ };
132
+ /** The artifact's shared document store (P088). */
133
+ readonly db: {
134
+ readonly builtIn: false;
135
+ readonly methods: {
136
+ readonly get: RuntimeMethod;
137
+ readonly query: RuntimeMethod;
138
+ readonly watch: RuntimeMethod;
139
+ readonly set: RuntimeMethod;
140
+ readonly update: RuntimeMethod;
141
+ readonly delete: RuntimeMethod;
142
+ readonly batch: RuntimeMethod;
143
+ };
144
+ };
145
+ };
146
+ export type RuntimeCapabilityName = keyof typeof RUNTIME_CAPABILITIES;
147
+ export declare const RUNTIME_CAPABILITY_NAMES: readonly RuntimeCapabilityName[];
148
+ export declare function isRuntimeCapabilityName(value: unknown): value is RuntimeCapabilityName;
149
+ /** A runtime capability's spec, as the general shape. */
150
+ export declare function runtimeCapability(name: RuntimeCapabilityName): RuntimeCapability;
151
+ /** The host functions the runtime added in contract 1 (P085): the config needs `runtime` for them. */
152
+ export declare const RUNTIME_HOST_FUNCTIONS: readonly CapabilityName[];
153
+ /**
154
+ * Where a host function sits in the runtime: its capability and the methods it serves. Null for
155
+ * the shell's own (`resize`, `reportError`, `annotate`), which content never calls by name.
156
+ */
157
+ export declare function familyOf(serves: CapabilityName): {
158
+ readonly name: RuntimeCapabilityName;
159
+ readonly methods: readonly string[];
160
+ } | null;
161
+ /**
162
+ * The runtime method a host function's validated call is: the `op` of one that serves several
163
+ * (`artifact`, `assets`, `db`), else its one method.
164
+ */
165
+ export declare function methodOf(serves: CapabilityName, args: unknown): string | null;
166
+ /**
167
+ * The runtime methods a validated call runs, each as often as it runs it: its own, and for a db
168
+ * batch each of its writes' (`set`, `update`, `delete`), for a db watch the read it repeats (`get`
169
+ * for a document, `query` for a collection). Each one's level and gates apply to the call (P091
170
+ * item 4 for levels, P094 for gates): a batch is its writes, a watch its read.
171
+ */
172
+ export declare function methodsOfCall(serves: CapabilityName, args: unknown): readonly string[];
173
+ /**
174
+ * Whether a config's asset uploads are its admins' alone (`assets.upload` at admin or above,
175
+ * P089): only then may scripts and styles an admin uploaded run from the library. Never where
176
+ * the config serves no assets (P103: a config that dropped them runs nothing of its library).
177
+ */
178
+ export declare function assetCodeRuns(config: PortholeConfig): boolean;
179
+ /**
180
+ * A runtime method's own gates (after the review): the config's (`CapabilityConfig.methodGates`),
181
+ * else the contract's; an upload where uploaded code may run is confirmed (P089).
182
+ */
183
+ export declare function methodGates(config: PortholeConfig, family: RuntimeCapabilityName, name: string): readonly Gate[];
184
+ /** What a page declared for one capability, as far as levels go (P086). */
185
+ export interface DeclaredLevels {
186
+ readonly levels?: Readonly<Record<string, ViewerLevel>>;
187
+ }
188
+ /**
189
+ * The least level that may call `family.method` (P087): the contract's, or the host's config
190
+ * (`CapabilityConfig.levels`, no lower than the floor), raised by the page's declaration.
191
+ */
192
+ export declare function methodLevel(config: PortholeConfig, family: RuntimeCapabilityName, name: string, declared?: DeclaredLevels): ViewerLevel | null;
193
+ /**
194
+ * What the host offers a display (P085): each runtime capability the config serves at least one
195
+ * method of (with those methods), reachable when it is built in or the page declared it. Without
196
+ * `config.runtime`, nothing: the display is 0.6's. `declared` is the page's declaration's names;
197
+ * absent, the page declared nothing (built-ins only).
198
+ */
199
+ export declare function rosterOf(config: PortholeConfig, declared?: readonly string[]): Readonly<Partial<Record<RuntimeCapabilityName, readonly string[]>>>;
200
+ /** The capabilities a config offers to pages that declare them (for the manual and `declareCapabilities`). */
201
+ export declare function offeredCapabilities(config: PortholeConfig): RuntimeCapabilityName[];