@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,95 @@
1
+ import type { ReactElement } from "react";
2
+ import type { CapabilityArgs } from "../config/capabilities.ts";
3
+
4
+ /**
5
+ * The default model context notice (P100): when content tells the agent something
6
+ * (`setModelContext`, MCP Apps' `ui/update-model-context`), the host's page shows the person all
7
+ * of it, outside every frame, before the host's handler has it: the text the agent reads at its
8
+ * next turn, in the content's words. One per display, the latest (an update replaces the last, as
9
+ * it does for the agent); it stays until the person hides it. Nothing in it is a question: the
10
+ * update has gone. All of it shows (after the review: the text box grows, never hiding a payload
11
+ * below blank lines, and says how many characters and lines it holds); the stack of displays
12
+ * scrolls within the window, so a later display never pushes an earlier one out of reach. A host replaces it by passing its own `show` (a chip by its composer, say); it
13
+ * styles it through the `porthole-context` class and data attributes.
14
+ */
15
+
16
+ export interface ContextUpdate {
17
+ /** The display's id and title, as the host named it. */
18
+ readonly displayId: string;
19
+ readonly title: string;
20
+ /** The update, whole: text blocks and structured content, as the bridge took them. */
21
+ readonly update: CapabilityArgs["setModelContext"];
22
+ }
23
+
24
+ export interface ContextNoticeProps {
25
+ /** The latest update of each display that sent one, in the order they came. */
26
+ readonly updates: readonly ContextUpdate[];
27
+ /** The person hid one display's notice (the agent still has its update). */
28
+ readonly onHide: (displayId: string) => void;
29
+ readonly className?: string;
30
+ }
31
+
32
+ /** How long an update is, in words: "412 characters, 3 lines". */
33
+ export function contextSize(text: string): string {
34
+ const lines = text === "" ? 0 : text.split("\n").length;
35
+ return `${text.length.toLocaleString("en-US")} characters, ${lines.toLocaleString("en-US")} ${lines === 1 ? "line" : "lines"}`;
36
+ }
37
+
38
+ /** What the person is shown of an update: its text blocks, then its structured content's JSON. */
39
+ export function contextText(update: CapabilityArgs["setModelContext"]): string {
40
+ const text = (update.content ?? []).map((block) => block.text).join("\n\n");
41
+ const structured =
42
+ update.structuredContent === undefined ? "" : JSON.stringify(update.structuredContent, null, 2);
43
+ return [text, structured].filter((part) => part !== "").join("\n\n");
44
+ }
45
+
46
+ const STYLE = `.porthole-context{position:fixed;right:16px;bottom:24px;z-index:2147483646;display:flex;flex-direction:column;gap:8px;width:min(380px,calc(100vw - 32px));max-height:calc(100vh - 48px);overflow-y:auto;overscroll-behavior:contain;font:inherit;font-size:.9em}
47
+ .porthole-context[hidden]{display:none}
48
+ .porthole-context>section{flex:none;color-scheme:light dark;color:CanvasText;background:Canvas;border:1px solid color-mix(in srgb,CanvasText 18%,transparent);border-radius:12px;padding:12px 14px;box-shadow:0 8px 28px rgb(0 0 0 / .25)}
49
+ .porthole-context p{margin:0 0 6px}
50
+ .porthole-context [data-porthole-source],.porthole-context [data-porthole-note],.porthole-context [data-porthole-context-size]{opacity:.72}
51
+ .porthole-context>[data-porthole-context-count]{flex:none;margin:0;padding:6px 12px;border-radius:8px;color-scheme:light dark;color:CanvasText;background:Canvas;border:1px solid color-mix(in srgb,CanvasText 18%,transparent)}
52
+ .porthole-context [data-porthole-context-size]{margin:6px 0 0}
53
+ .porthole-context pre{margin:0;white-space:pre-wrap;overflow-wrap:anywhere;padding:8px 10px;border-radius:8px;background:color-mix(in srgb,CanvasText 7%,transparent);font:12px/1.45 ui-monospace,SFMono-Regular,Menlo,monospace}
54
+ .porthole-context menu{display:flex;justify-content:flex-end;margin:8px 0 0;padding:0}
55
+ .porthole-context button{font:inherit;min-height:32px;padding:0 12px;border-radius:8px;border:1px solid color-mix(in srgb,CanvasText 25%,transparent);background:transparent;color:inherit;cursor:pointer}`;
56
+
57
+ export function ContextNotice({ updates, onHide, className }: ContextNoticeProps): ReactElement {
58
+ return (
59
+ <div
60
+ role="status"
61
+ aria-live="polite"
62
+ className={className === undefined ? "porthole-context" : `porthole-context ${className}`}
63
+ data-porthole-context=""
64
+ hidden={updates.length === 0}
65
+ >
66
+ <style>{STYLE}</style>
67
+ {updates.length > 1 ? (
68
+ <p data-porthole-context-count="">{`${updates.length} displays told the agent something: scroll to read them all.`}</p>
69
+ ) : null}
70
+ {updates.map((each) => {
71
+ const text = contextText(each.update);
72
+ return (
73
+ <section key={each.displayId} data-porthole-context-display={each.displayId}>
74
+ <p>
75
+ <strong>Context for the agent</strong>{" "}
76
+ <span data-porthole-source="">{`from “${each.title}”`}</span>
77
+ </p>
78
+ <p data-porthole-note="">
79
+ The agent reads this at its next turn. It is the content’s text, not yours.
80
+ </p>
81
+ <pre data-porthole-context-text="" tabIndex={0}>
82
+ {text}
83
+ </pre>
84
+ <p data-porthole-context-size="">{contextSize(text)}</p>
85
+ <menu>
86
+ <button type="button" data-porthole-hide="" onClick={() => onHide(each.displayId)}>
87
+ Hide
88
+ </button>
89
+ </menu>
90
+ </section>
91
+ );
92
+ })}
93
+ </div>
94
+ );
95
+ }
@@ -1,4 +1,5 @@
1
- import { useEffect, useId, useRef, useState, type ReactElement } from "react";
1
+ import { useEffect, useId, useMemo, useRef, useState, type ReactElement } from "react";
2
+ import { formatBounded, type TextLimits } from "../bridge/bounded-text.ts";
2
3
  import type { ConfirmRequest } from "../bridge/types.ts";
3
4
 
4
5
  /**
@@ -24,13 +25,62 @@ export interface ConfirmDialogProps {
24
25
  interface Words {
25
26
  readonly heading: string;
26
27
  readonly accept: string;
28
+ /**
29
+ * What asked for the yes, above the detail (which scrolls): a db batch's writes whose gates
30
+ * asked, however late in the batch they come (P094).
31
+ */
32
+ readonly summary?: string;
27
33
  /** What the person is shown in full. */
28
34
  readonly detail: string;
29
35
  /** A line under it (the link's host). */
30
36
  readonly note?: string;
31
37
  }
32
38
 
33
- const json = (value: unknown): string => JSON.stringify(value, null, 2) ?? "";
39
+ /**
40
+ * What a call carries, as JSON laid out, within bounds (P095): a frame's arguments come
41
+ * structured-cloned, so a cycle, a BigInt, or a graph billions of nodes long as a tree. Past the
42
+ * bounds the dialog says it shows only part.
43
+ */
44
+ const DIALOG_TEXT_LIMITS: TextLimits = { chars: 20_000, nodes: 2_000, depth: 24 };
45
+
46
+ function carried(heading: string, accept: string, value: unknown, before = ""): Words {
47
+ const { text, whole } = formatBounded(value, DIALOG_TEXT_LIMITS, 2);
48
+ return {
49
+ heading,
50
+ accept,
51
+ detail: `${before}${text}`,
52
+ ...(whole ? {} : { note: "Only part of it is shown: it is more than this dialog shows." }),
53
+ };
54
+ }
55
+
56
+ /** How many of one kind of write the summary names before it counts the rest. */
57
+ const MOST_PATHS = 10;
58
+
59
+ /**
60
+ * A db change in a line (P094): the writes whose own gates asked for the yes, by kind ("Delete
61
+ * n/x, n/y; and 48 other writes."), or every write by kind where none of them asked (the host
62
+ * function's own confirmation); at most `MOST_PATHS` paths a kind, then a count.
63
+ */
64
+ function writesSummary(
65
+ writes: readonly { readonly op: string; readonly path: string }[],
66
+ askedBy: readonly string[],
67
+ ): string {
68
+ const asked = writes.filter((each) => askedBy.includes(each.op));
69
+ const lead = asked.length === 0 ? writes : asked;
70
+ const kinds = new Map<string, string[]>();
71
+ for (const each of lead) {
72
+ kinds.set(each.op, [...(kinds.get(each.op) ?? []), each.path]);
73
+ }
74
+ const said = [...kinds]
75
+ .map(
76
+ ([op, paths]) =>
77
+ `${op} ${paths.slice(0, MOST_PATHS).join(", ")}${paths.length > MOST_PATHS ? ` and ${paths.length - MOST_PATHS} more` : ""}`,
78
+ )
79
+ .join("; ");
80
+ const others = writes.length - lead.length;
81
+ const text = `${said}${others === 0 ? "" : `; and ${others} other write${others === 1 ? "" : "s"}`}.`;
82
+ return text.charAt(0).toUpperCase() + text.slice(1);
83
+ }
34
84
 
35
85
  function words(request: ConfirmRequest): Words {
36
86
  switch (request.capability) {
@@ -51,27 +101,68 @@ function words(request: ConfirmRequest): Words {
51
101
  };
52
102
  }
53
103
  case "downloadFile":
54
- return {
55
- heading: "Download this file?",
56
- accept: "Download",
57
- detail: json(request.args.contents),
58
- };
104
+ return carried("Download this file?", "Download", request.args.contents);
59
105
  case "callTool":
60
- return {
61
- heading: "Run this tool?",
62
- accept: "Run",
63
- detail: `${request.args.name}\n${json(request.args.arguments)}`,
64
- };
106
+ return carried("Run this tool?", "Run", request.args.arguments, `${request.args.name}\n`);
65
107
  case "setModelContext":
66
- return { heading: "Share this with the agent?", accept: "Share", detail: json(request.args) };
108
+ return carried("Share this with the agent?", "Share", request.args);
67
109
  case "readData":
68
110
  return { heading: "Let it read this?", accept: "Allow", detail: request.args.uri };
69
111
  case "subscribeData":
70
112
  return { heading: "Let it follow this?", accept: "Allow", detail: request.args.uri };
71
113
  case "copyText":
72
114
  return { heading: "Copy this text?", accept: "Copy", detail: request.args.text };
115
+ // The runtime's (P088, P089): the whole effect, as the page asked for it.
116
+ case "artifact":
117
+ return request.args.op === "publish"
118
+ ? {
119
+ heading: "Publish a new version of this page?",
120
+ accept: "Publish",
121
+ detail: Object.entries(request.args.files)
122
+ .map(([path, file]) =>
123
+ file === null
124
+ ? `${path}: removed`
125
+ : "text" in file
126
+ ? `${path}: ${file.text.length.toLocaleString("en-US")} characters`
127
+ : `${path}: ${Math.floor((file.base64.length * 3) / 4).toLocaleString("en-US")} bytes`,
128
+ )
129
+ .join("\n"),
130
+ note: `From version ${request.args.base}${request.args.label === undefined ? "" : `: ${request.args.label}`}.`,
131
+ }
132
+ : carried("Allow this?", "Allow", request.args);
133
+ case "assets":
134
+ return request.args.op === "upload"
135
+ ? {
136
+ heading: "Add this file to the page's library?",
137
+ accept: "Add",
138
+ detail: `${request.args.name} (${request.args.type}, ${request.args.size.toLocaleString("en-US")} bytes)`,
139
+ note: "Everyone who can see the page can load it.",
140
+ }
141
+ : request.args.op === "delete"
142
+ ? {
143
+ heading: "Remove this file from the page's library?",
144
+ accept: "Remove",
145
+ detail: request.args.id,
146
+ }
147
+ : carried("Allow this?", "Allow", request.args);
148
+ // The page's shared data (P088): a change leads with what asked for the yes (P094).
149
+ case "db": {
150
+ const args = request.args;
151
+ const writes =
152
+ args.op === "batch"
153
+ ? args.writes
154
+ : args.op === "set" || args.op === "update" || args.op === "delete"
155
+ ? [args]
156
+ : null;
157
+ return writes === null
158
+ ? carried("Allow this?", "Allow", args)
159
+ : {
160
+ ...carried("Change this page's shared data?", "Change", args),
161
+ summary: writesSummary(writes, request.askedBy ?? []),
162
+ };
163
+ }
73
164
  default:
74
- return { heading: "Allow this?", accept: "Allow", detail: json(request.args) };
165
+ return carried("Allow this?", "Allow", request.args);
75
166
  }
76
167
  }
77
168
 
@@ -79,6 +170,7 @@ const STYLE = `.porthole-confirm{color-scheme:light dark;color:CanvasText;backgr
79
170
  .porthole-confirm::backdrop{background:rgb(0 0 0 / .4)}
80
171
  .porthole-confirm h2{font-size:1.05em;margin:0 0 4px}
81
172
  .porthole-confirm [data-porthole-source],.porthole-confirm [data-porthole-note]{opacity:.72;font-size:.9em;margin:0 0 12px}
173
+ .porthole-confirm [data-porthole-summary]{font-weight:600;overflow-wrap:anywhere;max-height:20vh;overflow:auto;margin:0 0 12px}
82
174
  .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}
83
175
  .porthole-confirm menu{display:flex;justify-content:flex-end;gap:8px;margin:16px 0 0;padding:0}
84
176
  .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}
@@ -111,7 +203,7 @@ export function ConfirmDialog({ request, onAnswer, className }: ConfirmDialogPro
111
203
  return () => clearTimeout(timer);
112
204
  }, [request]);
113
205
 
114
- const said = request === null ? null : words(request);
206
+ const said = useMemo(() => (request === null ? null : words(request)), [request]);
115
207
  return (
116
208
  <dialog
117
209
  ref={dialog}
@@ -130,6 +222,7 @@ export function ConfirmDialog({ request, onAnswer, className }: ConfirmDialogPro
130
222
  <>
131
223
  <h2 id={heading}>{said.heading}</h2>
132
224
  <p data-porthole-source="">{`From “${request.display.title}”`}</p>
225
+ {said.summary === undefined ? null : <p data-porthole-summary="">{said.summary}</p>}
133
226
  <div data-porthole-detail="">{said.detail}</div>
134
227
  {said.note === undefined ? null : <p data-porthole-note="">{said.note}</p>}
135
228
  <menu>
@@ -1,3 +1,5 @@
1
+ import type { PageDeclaration } from "../runtime/declaration.ts";
2
+ import type { ViewerInfo } from "../runtime/levels.ts";
1
3
  import {
2
4
  createContext,
3
5
  useCallback,
@@ -26,6 +28,7 @@ import type {
26
28
  DataCache,
27
29
  Proceed,
28
30
  Refusal,
31
+ Show,
29
32
  } from "../bridge/types.ts";
30
33
  import { isRefused, reasonOf, Refused, type RefusalReason } from "../bridge/refusal.ts";
31
34
  import type { CapabilityName } from "../config/capabilities.ts";
@@ -35,6 +38,7 @@ import { createHost } from "../host/create-host.ts";
35
38
  import type { DisplayEvents, DisplayHandle, FrameOutcome, HostErrorKind } from "../host/types.ts";
36
39
  import type { InstanceLocator, InstanceRef } from "../isolation/types.ts";
37
40
  import { ConfirmDialog } from "./dialog.tsx";
41
+ import { ContextNotice, type ContextUpdate } from "./context-notice.tsx";
38
42
  import { createLiveFrames, type FrameState, type LiveFrames } from "./live.ts";
39
43
  import { CopyToast, type CopyNotice } from "./toast.tsx";
40
44
  import type { PortholeClient } from "../host/client.ts";
@@ -46,6 +50,10 @@ import type { PortholeClient } from "../host/client.ts";
46
50
  * its height. All the isolation is the core's (`createHost`); this is mounting and lifecycle.
47
51
  */
48
52
 
53
+ /** Why a model context update didn't go: it was never drawn (the review of P100). */
54
+ const REPLACED_UNSEEN = "a later update of this display replaced it before the person saw it";
55
+ const HIDDEN_UNSEEN = "the person hid this display's notice before the update was drawn";
56
+
49
57
  /** How far off screen a frame starts (and keeps) running. */
50
58
  const NEAR_SCREEN = "800px 0px";
51
59
  /** The height a display holds before it has reported its own. */
@@ -75,6 +83,8 @@ interface PageState {
75
83
  readonly locate?: InstanceLocator["locate"];
76
84
  /** The default `copyText`: copies on the host's page and shows the toast (P052). */
77
85
  readonly copyText?: CapabilityHandler<"copyText">;
86
+ /** Who shows the person `show`-gated calls: the provider's own, or its notice (P100). */
87
+ readonly show?: Show;
78
88
  }
79
89
 
80
90
  /** Without a provider: one registry for the page, and no one to confirm (gated calls refused). */
@@ -134,6 +144,13 @@ export interface PortholeProviderProps {
134
144
  * refuses them all with its reason, and their handlers may be left out (P080).
135
145
  */
136
146
  readonly consent?: Consent | Refused;
147
+ /**
148
+ * Shows the person each `show`-gated call, outside every frame, before its handler has it
149
+ * (P100): by default, a frame's model context update (`setModelContext`), the content's text for
150
+ * the agent's next turn. Omitted: Porthole's `ContextNotice`. A host that shows it its own way (a
151
+ * chip by its composer) passes this; the update replaces the display's last.
152
+ */
153
+ readonly show?: Show;
137
154
  /** What the host last had for a resource, answered stale first (P079). */
138
155
  readonly cached?: DataCache;
139
156
  /** How the host names itself in the handshake. */
@@ -144,6 +161,8 @@ export interface PortholeProviderProps {
144
161
  readonly dialogClassName?: string;
145
162
  /** A class for the default copy toast, to restyle it. */
146
163
  readonly toastClassName?: string;
164
+ /** A class for the default model context notice, to restyle it. */
165
+ readonly contextClassName?: string;
147
166
  /**
148
167
  * The page's CSP nonce, where its `script-src` is nonce-based: opaque frames inherit the page's
149
168
  * policy, so their shell carries it (P054). `"auto"`: read from the page (a `<meta
@@ -238,6 +257,69 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
238
257
  return copied;
239
258
  }, []);
240
259
  const closeNotice = useCallback(() => setNotice(null), []);
260
+ // The default show (P100): each display's latest model context update, in the notice, outside
261
+ // every frame; the host's own `show` replaces it.
262
+ const [contexts, setContexts] = useState<readonly ContextUpdate[]>([]);
263
+ // Each show waiting for its own update to be on the page (after the review: React may draw two
264
+ // updates of a display in one render, the latest only). The number orders a display's shows.
265
+ const unseen = useRef<
266
+ { entry: ContextUpdate; seq: number; resolve: () => void; reject: (error: Error) => void }[]
267
+ >([]);
268
+ const latest = useRef(new Map<string, number>());
269
+ const sequence = useRef(0);
270
+ useLayoutEffect(() => {
271
+ unseen.current = unseen.current.filter((each) => {
272
+ const drawn = contexts.find((one) => one.displayId === each.entry.displayId);
273
+ if (drawn === each.entry) {
274
+ each.resolve();
275
+ return false;
276
+ }
277
+ // A later update of the display replaced it before it was drawn: never seen, never sent.
278
+ if ((latest.current.get(each.entry.displayId) ?? 0) > each.seq) {
279
+ each.reject(new Error(REPLACED_UNSEEN));
280
+ return false;
281
+ }
282
+ return true;
283
+ });
284
+ }, [contexts]);
285
+ const ownShow = useRef(props.show);
286
+ useLayoutEffect(() => {
287
+ ownShow.current = props.show;
288
+ });
289
+ const show = useCallback<Show>((request) => {
290
+ if (ownShow.current !== undefined) {
291
+ return ownShow.current(request);
292
+ }
293
+ if (request.capability !== "setModelContext") {
294
+ // The notice words model context only: anything else it would show unworded, so it isn't
295
+ // shown, and doesn't go (fail closed).
296
+ throw new Error(`Porthole's notice shows model context only, not ${request.capability}`);
297
+ }
298
+ const entry: ContextUpdate = {
299
+ displayId: request.display.id,
300
+ title: request.display.title,
301
+ update: request.args,
302
+ };
303
+ sequence.current += 1;
304
+ const seq = sequence.current;
305
+ latest.current.set(entry.displayId, seq);
306
+ // The call goes once this very update is on the page, so the handler never has it first.
307
+ return new Promise<void>((resolve, reject) => {
308
+ unseen.current.push({ entry, seq, resolve, reject });
309
+ setContexts((each) => [...each.filter((one) => one.displayId !== entry.displayId), entry]);
310
+ });
311
+ }, []);
312
+ const hideContext = useCallback((displayId: string) => {
313
+ // Hidden by the person: an update of the display not drawn yet never will be.
314
+ unseen.current = unseen.current.filter((each) => {
315
+ if (each.entry.displayId !== displayId) {
316
+ return true;
317
+ }
318
+ each.reject(new Error(HIDDEN_UNSEEN));
319
+ return false;
320
+ });
321
+ setContexts((each) => each.filter((one) => one.displayId !== displayId));
322
+ }, []);
241
323
  // Compared by value, and read when used: an inline hostInfo or locator doesn't start every
242
324
  // frame again on each render.
243
325
  const hostInfo = useByValue(props.hostInfo);
@@ -295,6 +377,7 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
295
377
  heights,
296
378
  confirm,
297
379
  copyText,
380
+ show,
298
381
  ...(consents ? { consent } : {}),
299
382
  ...(refusesAll === undefined ? {} : { refusesAll }),
300
383
  ...(caches ? { cached } : {}),
@@ -312,6 +395,7 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
312
395
  heights,
313
396
  confirm,
314
397
  copyText,
398
+ show,
315
399
  consents,
316
400
  consent,
317
401
  refusesAll,
@@ -364,6 +448,13 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
364
448
  }}
365
449
  />
366
450
  ) : null}
451
+ {props.show !== undefined ? null : (
452
+ <ContextNotice
453
+ updates={contexts}
454
+ onHide={hideContext}
455
+ {...(props.contextClassName === undefined ? {} : { className: props.contextClassName })}
456
+ />
457
+ )}
367
458
  {props.notify !== undefined ? null : (
368
459
  <CopyToast
369
460
  notice={notice}
@@ -407,6 +498,17 @@ export interface PortholeFrameProps {
407
498
  * shows, for its confirmations only, never sent to the frame (P077).
408
499
  */
409
500
  readonly instance?: InstanceRef;
501
+ /**
502
+ * What the page declared (P086), as the host stored it with the artifact: the capabilities it
503
+ * reaches through `porthole.use`, and its pinned runtime. By value: a change makes the display
504
+ * again.
505
+ */
506
+ readonly declaration?: PageDeclaration;
507
+ /**
508
+ * Who is viewing (P087), for an opaque frame or one whose issue gave none. By value: a change
509
+ * makes the display again.
510
+ */
511
+ readonly viewer?: ViewerInfo;
410
512
  /** The color scheme it shows in. Default: the provider's `scheme`, else light. */
411
513
  readonly scheme?: ColorScheme;
412
514
  /** The host's live values for the config's theme variables (from its design tokens). */
@@ -664,6 +766,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
664
766
  // By value: a config or instance made inline (each render) is the same display.
665
767
  const config = useByValue(frame.config);
666
768
  const instance = useByValue(frame.instance);
769
+ const declaration = useByValue(frame.declaration);
770
+ const viewer = useByValue(frame.viewer);
667
771
  const fills = config.mode === "url" || frame.fill === true || config.layout.kind === "fill";
668
772
  // A consent that refuses everything (P080), this frame's or else the provider's, by value: a
669
773
  // display made with it needs no data handlers, so a change makes the display again.
@@ -681,6 +785,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
681
785
  copyText: pageCopyText,
682
786
  confirm: pageConfirm,
683
787
  consent: pageConsent,
788
+ show: pageShow,
684
789
  cached: pageCached,
685
790
  hostInfo,
686
791
  locate,
@@ -813,6 +918,16 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
813
918
  },
814
919
  }
815
920
  : {}),
921
+ // Shown as the latest props name the display (P100).
922
+ ...(pageShow === undefined
923
+ ? {}
924
+ : {
925
+ show: (request: ConfirmRequest) =>
926
+ pageShow({
927
+ ...request,
928
+ display: { ...request.display, id: latest().displayId, title: latest().title },
929
+ }),
930
+ }),
816
931
  ...(caches
817
932
  ? {
818
933
  cached: (args: { readonly uri: string }, context: CallContext) =>
@@ -830,6 +945,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
830
945
  initialHeightPx: startHeight,
831
946
  ...(view === undefined ? {} : { document: view }),
832
947
  ...(instance === undefined ? {} : { instance }),
948
+ ...(declaration === undefined ? {} : { declaration }),
949
+ ...(viewer === undefined ? {} : { viewer }),
833
950
  ...(fills ? { fill: true } : {}),
834
951
  });
835
952
  } catch (error) {
@@ -870,12 +987,15 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
870
987
  config,
871
988
  view,
872
989
  instance,
990
+ declaration,
991
+ viewer,
873
992
  startHeight,
874
993
  fills,
875
994
  pageHandlers,
876
995
  pageCopyText,
877
996
  pageConfirm,
878
997
  pageConsent,
998
+ pageShow,
879
999
  pageCached,
880
1000
  refusesAll,
881
1001
  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} />
@@ -18,6 +18,13 @@ export {
18
18
  type PortholeProviderProps,
19
19
  } from "./frame.tsx";
20
20
  export { ARM_DELAY_MS, ConfirmDialog, type ConfirmDialogProps } from "./dialog.tsx";
21
+ export {
22
+ ContextNotice,
23
+ contextSize,
24
+ contextText,
25
+ type ContextNoticeProps,
26
+ type ContextUpdate,
27
+ } from "./context-notice.tsx";
21
28
  export {
22
29
  cssVariableTheme,
23
30
  PortholeView,