@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
@@ -5,10 +5,16 @@ import {
5
5
  type AnnotationReport,
6
6
  } from "../annotate/types.ts";
7
7
  import { annotateMode, checkMarks, parseReport } from "../annotate/validate.ts";
8
- import { createBridge, onceConsent, type BridgeEvent } from "../bridge/bridge.ts";
8
+ import {
9
+ createBridge,
10
+ onceConsent,
11
+ type BridgeEvent,
12
+ type DisplayBridge,
13
+ } from "../bridge/bridge.ts";
9
14
  import type { HostFunctionBridge } from "../bridge/types.ts";
10
15
  import { compile } from "../compile/compile.ts";
11
16
  import { servesFiles } from "../files/paths.ts";
17
+ import { pagesOfSet } from "./pages-of-set.ts";
12
18
  import { declaredCapabilities, effectiveGates } from "../compile/policy.ts";
13
19
  import { isRefused } from "../bridge/refusal.ts";
14
20
  import { capabilitySpec } from "../config/capabilities.ts";
@@ -26,6 +32,8 @@ import {
26
32
  } from "../protocol/mcp-apps.ts";
27
33
  import { shellAdapter } from "../protocol/shell-adapter.ts";
28
34
  import { resolveTheme } from "../theme/variables.ts";
35
+ import { checkDeclaration } from "../runtime/declaration.ts";
36
+ import { parseViewer } from "../runtime/levels.ts";
29
37
  import type {
30
38
  AnnotationControls,
31
39
  HostErrorKind,
@@ -39,8 +47,6 @@ import type {
39
47
  /** How long a display may take to load before its outcome is a timeout, by default. */
40
48
  const DEFAULT_LOAD_TIMEOUT_MS = 15_000;
41
49
 
42
- /** How long a set's page said its next load is another of its pages (P084), ms. */
43
- const PAGE_OF_SET_MS = 10_000;
44
50
  /** How many times a display is started again after its content navigated its frame away. */
45
51
  const MAX_RESTARTS = 3;
46
52
 
@@ -98,6 +104,33 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
98
104
  if (config.isolation !== "opaque" && mount.instance === undefined) {
99
105
  throw new TypeError(`${config.isolation} isolation needs MountOptions.instance`);
100
106
  }
107
+ // The page's declaration and the viewer (P086, P087): the host's records, checked once.
108
+ // Under a runtime every mount says what its page declared, or null for a page published
109
+ // before 0.7, which then has 0.6's surface (after the review: never by omission).
110
+ if (config.runtime !== undefined && mount.declaration === undefined) {
111
+ throw new TypeError(
112
+ "Under config.runtime a mount needs MountOptions.declaration: the page's stored declaration, or null for a page published before 0.7",
113
+ );
114
+ }
115
+ if (
116
+ config.runtime === undefined &&
117
+ mount.declaration !== undefined &&
118
+ mount.declaration !== null
119
+ ) {
120
+ throw new TypeError(
121
+ "MountOptions.declaration needs config.runtime: nothing would hold the page to it",
122
+ );
123
+ }
124
+ const declaration =
125
+ mount.declaration === undefined || mount.declaration === null
126
+ ? null
127
+ : checkDeclaration(mount.declaration, config);
128
+ const mountViewer = mount.viewer === undefined ? null : parseViewer(mount.viewer);
129
+ if (mount.viewer !== undefined && mountViewer === null) {
130
+ throw new TypeError(
131
+ "MountOptions.viewer is { level: view | interact | admin | owner, id?, name? }",
132
+ );
133
+ }
101
134
 
102
135
  const listeners = new Map<keyof DisplayEvents, Set<(detail: never) => void>>();
103
136
  const emit = <E extends keyof DisplayEvents>(event: E, detail: DisplayEvents[E]) => {
@@ -122,10 +155,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
122
155
  let height = mount.initialHeightPx ?? 0;
123
156
  let surface: Surface | null = null;
124
157
  let connection: C | null = null;
158
+ let bridge: DisplayBridge | null = null;
125
159
  let destroyed = false;
126
160
  let restarts = 0;
127
- // Until when the frame's next load is another page of its own set, as its content said (P084).
128
- let pageOfSetUntil = 0;
129
161
  let generation = 0;
130
162
  // The viewer's answer for this display (P079): asked once, kept across its frames; or the
131
163
  // host's refusal of them all (P080).
@@ -165,7 +197,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
165
197
  * A report from the frame: checked, taken only while the host asked for it (a selection
166
198
  * only in select mode, results only for its own marks), then through the bridge's gates.
167
199
  */
168
- const onAnnotation = (raw: unknown, bridge: HostFunctionBridge) => {
200
+ const onAnnotation = (raw: unknown, through: HostFunctionBridge) => {
169
201
  if (
170
202
  !isRecord(raw) ||
171
203
  raw.jsonrpc !== "2.0" ||
@@ -174,13 +206,14 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
174
206
  ) {
175
207
  return;
176
208
  }
177
- const type = REPORTS[raw.method];
209
+ // Its own entries only: `constructor` or `toString` is no report (P095).
210
+ const type = Object.hasOwn(REPORTS, raw.method) ? REPORTS[raw.method] : undefined;
178
211
  if (type === undefined) {
179
212
  return;
180
213
  }
181
214
  let report = parseReport({ ...(isRecord(raw.params) ? raw.params : {}), type });
182
215
  if (report === null) {
183
- void bridge.call("annotate", null);
216
+ void through.call("annotate", null);
184
217
  return;
185
218
  }
186
219
  switch (report.type) {
@@ -218,7 +251,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
218
251
  break;
219
252
  }
220
253
  }
221
- void bridge.call("annotate", report);
254
+ void through.call("annotate", report);
222
255
  };
223
256
  const needsAnnotate = (operation: string) => {
224
257
  if (!annotates) {
@@ -324,8 +357,11 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
324
357
  };
325
358
 
326
359
  const stop = () => {
360
+ // The run's bridge refuses what still waits for a confirmation: a yes to it runs nothing
361
+ // (P095, after the review), and the next run's bridge starts its count again.
362
+ bridge?.close();
363
+ bridge = null;
327
364
  handshaken = false;
328
- pageOfSetUntil = 0;
329
365
  abort?.abort();
330
366
  abort = null;
331
367
  outcomeWatch?.stop();
@@ -337,7 +373,17 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
337
373
  };
338
374
 
339
375
  const start = (source: FrameSource) => {
340
- const created = platform.createSurface(container, {
376
+ const navigatedAway = () => {
377
+ emit("navigated", undefined);
378
+ if (restarts < MAX_RESTARTS) {
379
+ restarts += 1;
380
+ run();
381
+ } else {
382
+ stop();
383
+ contentError("The content kept navigating its frame away; it was stopped.");
384
+ }
385
+ };
386
+ const framed = platform.createSurface(container, {
341
387
  source,
342
388
  title: mount.title,
343
389
  sandbox: compiled.sandbox,
@@ -351,6 +397,25 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
351
397
  ? { initialHeightPx: height }
352
398
  : { fill: true, initialHeightPx: config.limits.minHeightPx }),
353
399
  });
400
+ // A frame that speaks: another page of the content's own set (P084) is the same content,
401
+ // still connected (the new page's shell says hello again on the same transport); any other
402
+ // load after the first is the content navigating away (P031), and the display starts
403
+ // again. `pagesOfSet` tells them apart at each load (P098): what a new page says before
404
+ // its load is delivered as it comes, as P084 had it; from a load no notice explained until
405
+ // a notice for the mounted version comes, nothing the frame says reaches the display. A
406
+ // url-mode app's frame navigates as the app does (its entry page, then the app): never
407
+ // started again.
408
+ const mounted = mount.instance?.document;
409
+ const created = speaks
410
+ ? pagesOfSet({
411
+ surface: framed,
412
+ set:
413
+ servesFiles(config) && mounted?.kind === "artifact"
414
+ ? { id: mounted.id, version: mounted.version }
415
+ : null,
416
+ away: navigatedAway,
417
+ })
418
+ : framed;
354
419
  surface = created;
355
420
  const watch = watchOutcome({
356
421
  surface: created,
@@ -371,7 +436,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
371
436
  });
372
437
  return;
373
438
  }
374
- const bridge = createBridge({
439
+ // The host's access at issue says who is viewing (P087); else the mount's word.
440
+ const viewer =
441
+ (source.kind === "url" ? source.viewer : undefined) ?? mountViewer ?? undefined;
442
+ const opening = createBridge({
375
443
  config,
376
444
  display: {
377
445
  id: mount.displayId,
@@ -381,27 +449,28 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
381
449
  handlers,
382
450
  ...(options.confirm === undefined ? {} : { confirm: options.confirm }),
383
451
  ...(consent === undefined ? {} : { consent }),
452
+ ...(options.show === undefined ? {} : { show: options.show }),
384
453
  ...(options.cached === undefined ? {} : { cached: options.cached }),
385
454
  userActivation: () => created.userActivation(),
386
455
  onEvent: onBridge,
456
+ ...(declaration === null ? {} : { declaration }),
457
+ ...(viewer === undefined ? {} : { viewer }),
387
458
  });
388
459
  if (annotates) {
389
- created.transport.listen((raw) => onAnnotation(raw, bridge));
460
+ created.transport.listen((raw) => onAnnotation(raw, opening));
390
461
  }
462
+ bridge = opening;
391
463
  const opened = adapter.connect({
392
464
  display: { id: mount.displayId, title: mount.title },
393
465
  compiled,
394
466
  transport: created.transport,
395
- bridge,
467
+ bridge: opening,
396
468
  hostInfo,
397
469
  hostContext,
398
470
  emit: (event) => {
399
471
  if (event.type === "navigating") {
400
- // Only a display whose pages may come with files (P084), for the next load only, and
401
- // only soon: content can't bank it to skip a restart later (P031).
402
- if (servesFiles(config)) {
403
- pageOfSetUntil = Date.now() + PAGE_OF_SET_MS;
404
- }
472
+ // Which loads are the set's own pages is the frame's surface's to tell (P084, P098:
473
+ // `pagesOfSet`, from the frame's own words before any of them reach this display).
405
474
  return;
406
475
  }
407
476
  if (event.type === "initialized") {
@@ -419,23 +488,6 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
419
488
  for (const [name, args] of replay) {
420
489
  (opened as unknown as Record<string, (...each: unknown[]) => unknown>)[name]?.(...args);
421
490
  }
422
- created.onNavigated(() => {
423
- // Another page of the content's own set (P084): the same content, still connected (the
424
- // new page's shell says hello again on the same transport). Not a restart.
425
- const ofSet = pageOfSetUntil > Date.now();
426
- pageOfSetUntil = 0;
427
- if (ofSet) {
428
- return;
429
- }
430
- emit("navigated", undefined);
431
- if (restarts < MAX_RESTARTS) {
432
- restarts += 1;
433
- run();
434
- } else {
435
- stop();
436
- contentError("The content kept navigating its frame away; it was stopped.");
437
- }
438
- });
439
491
  };
440
492
 
441
493
  const run = () => {
@@ -1,6 +1,7 @@
1
1
  import type { PortholeConfig } from "../config/schema.ts";
2
2
  import { checkFrameLocation } from "../isolation/served.ts";
3
3
  import type { FrameSource, InstanceLocator, InstanceRef } from "../isolation/types.ts";
4
+ import { parseViewer } from "../runtime/levels.ts";
4
5
 
5
6
  /**
6
7
  * Where a served frame (domain or external isolation) loads from: the host's locator answers, and
@@ -16,10 +17,19 @@ export async function locateServed(
16
17
  ): Promise<FrameSource> {
17
18
  const location = await locator.locate(instance, signal);
18
19
  checkFrameLocation(location, config.contentOrigins, hostOrigin);
20
+ // The host's access, as its backend answered (P087): a viewer that doesn't parse is the host's
21
+ // error, never no viewer (after the review: a mount's own would take its place).
22
+ const viewer = location.viewer === undefined ? null : parseViewer(location.viewer);
23
+ if (location.viewer !== undefined && viewer === null) {
24
+ throw new TypeError(
25
+ "The host's location names a viewer that isn't one: { level: view | interact | admin | owner, id?: one path segment, name? }",
26
+ );
27
+ }
19
28
  return {
20
29
  kind: "url",
21
30
  url: new URL(location.url).href,
22
31
  origin: location.origin,
23
32
  ...(location.reports === true ? { reports: true } : {}),
33
+ ...(viewer === null ? {} : { viewer }),
24
34
  };
25
35
  }
@@ -1,3 +1,4 @@
1
+ import { parseViewer } from "../runtime/levels.ts";
1
2
  import type { PortholeConfig } from "../config/schema.ts";
2
3
  import type { FrameLocation, InstanceLocator } from "../isolation/types.ts";
3
4
 
@@ -77,10 +78,20 @@ export function httpLocator(url: string, options: HttpLocatorOptions = {}): Inst
77
78
  "bad-location",
78
79
  );
79
80
  }
81
+ // Who is viewing, as the app's access decided (P087); one that doesn't parse is an error.
82
+ const viewer = data.viewer === undefined ? null : parseViewer(data.viewer);
83
+ if (data.viewer !== undefined && viewer === null) {
84
+ throw new LocateError(
85
+ "The app's issue endpoint named a viewer that isn't one",
86
+ response.status,
87
+ "bad-location",
88
+ );
89
+ }
80
90
  return {
81
91
  url: data.url,
82
92
  origin: data.origin,
83
93
  ...(typeof data.reports === "boolean" ? { reports: data.reports } : {}),
94
+ ...(viewer === null ? {} : { viewer }),
84
95
  } satisfies FrameLocation;
85
96
  },
86
97
  };
@@ -0,0 +1,226 @@
1
+ import { MCP_APPS_METHODS, NAVIGATING_METHOD } from "../protocol/mcp-apps.ts";
2
+ import type { JsonRpcMessage } from "../protocol/jsonrpc.ts";
3
+ import type { Surface } from "../platform/types.ts";
4
+
5
+ /** How long a set's page said its next load is another of its pages (P084), ms. */
6
+ export const PAGE_OF_SET_MS = 10_000;
7
+
8
+ /**
9
+ * How long a load no page has announced waits for its notice before the display starts again, in
10
+ * a display whose pages may come with files (P098), ms. The notice can come after the load: on
11
+ * Chromium a cross-process `postMessage` is forwarded from a task of the sending document's, so
12
+ * the leaving page's notice can arrive after the next page's load or, when the navigation commits
13
+ * first, never; the arriving page says so too, and its word can come after its own load.
14
+ */
15
+ export const LATE_NOTICE_MS = 2_000;
16
+
17
+ /** The most messages held each way while a load waits (P098); past them, the display starts again. */
18
+ export const HELD_MOST = 1_000;
19
+
20
+ /** The artifact version a display mounted: the only set whose pages its notices may name. */
21
+ export interface FileSetRef {
22
+ readonly id: string;
23
+ readonly version: string;
24
+ }
25
+
26
+ interface Notice {
27
+ readonly url: string;
28
+ readonly arrived: boolean;
29
+ /** Whether it names the mounted version (`ok`), another (`other`), or none (a shell before P098). */
30
+ readonly set: "ok" | "other" | "none";
31
+ }
32
+
33
+ const isRecord = (value: unknown): value is Record<string, unknown> =>
34
+ value !== null && typeof value === "object" && !Array.isArray(value);
35
+
36
+ function noticeOf(raw: unknown, mounted: FileSetRef): Notice | null {
37
+ if (!isRecord(raw) || raw.jsonrpc !== "2.0" || raw.method !== NAVIGATING_METHOD || "id" in raw) {
38
+ return null;
39
+ }
40
+ const params = isRecord(raw.params) ? raw.params : {};
41
+ const named = params.set;
42
+ return {
43
+ url: typeof params.url === "string" ? params.url : "",
44
+ arrived: params.arrived === true,
45
+ set:
46
+ named === undefined
47
+ ? "none"
48
+ : isRecord(named) && named.id === mounted.id && named.version === mounted.version
49
+ ? "ok"
50
+ : "other",
51
+ };
52
+ }
53
+
54
+ const isHello = (raw: unknown): boolean =>
55
+ isRecord(raw) && raw.method === MCP_APPS_METHODS.initialize && "id" in raw;
56
+
57
+ /**
58
+ * Which of a frame's loads are another page of its own set (P084, P098), for a display whose
59
+ * pages may come with files; every other display passes `set: null`, and each load after the
60
+ * first is the content navigating away (P031).
61
+ *
62
+ * A notice (`porthole/navigating`, from the frame's window and content origin: the transport
63
+ * takes nothing else) names a page and the version its files are. The leaving page's notice is
64
+ * taken for the next load within `PAGE_OF_SET_MS`; the arriving page's (`arrived`) too, or for the
65
+ * load it came after. A load no notice explained waits `LATE_NOTICE_MS`, holding the frame
66
+ * (`HELD_MOST` messages each way at most; past them, started again): nothing it says reaches the
67
+ * display (no call is answered, no report taken), nothing is sent to it, and once the wait is
68
+ * over without a notice for the
69
+ * mounted version, the display starts again. A notice for another version, or the new page's
70
+ * hello before any notice, ends the wait at once: started again. Only a notice naming the mounted
71
+ * version ends a wait without a restart; one from a shell before P098 (no version) can only be
72
+ * taken for a load still to come, as before.
73
+ *
74
+ * Returns the surface the display uses: the same, its transport held while a load waits.
75
+ */
76
+ export function pagesOfSet(options: {
77
+ readonly surface: Surface;
78
+ readonly set: FileSetRef | null;
79
+ /** The frame left its content: start the display again. */
80
+ readonly away: () => void;
81
+ }): Surface {
82
+ const { surface, set, away } = options;
83
+ if (set === null) {
84
+ surface.onNavigated(away);
85
+ return surface;
86
+ }
87
+ const raw = surface.transport;
88
+ // Taken for the next load until then, as that page.
89
+ let grantUntil = 0;
90
+ let grantFor = "";
91
+ // The page the frame's last load was taken as: a late copy of its notice is no new one.
92
+ let current: string | null = null;
93
+ // Loads waiting for their notice, and what the frame said and was sent meanwhile.
94
+ let waiting = 0;
95
+ let timer: ReturnType<typeof setTimeout> | null = null;
96
+ const heard: unknown[] = [];
97
+ const unsent: JsonRpcMessage[] = [];
98
+ const listeners = new Set<(message: unknown) => void>();
99
+ let closed = false;
100
+
101
+ const deliver = (message: unknown) => {
102
+ for (const listener of listeners) {
103
+ listener(message);
104
+ }
105
+ };
106
+ const settle = () => {
107
+ if (timer !== null) {
108
+ clearTimeout(timer);
109
+ timer = null;
110
+ }
111
+ };
112
+ const leave = () => {
113
+ settle();
114
+ waiting = 0;
115
+ heard.length = 0;
116
+ unsent.length = 0;
117
+ away();
118
+ };
119
+ const taken = (url: string) => {
120
+ current = url;
121
+ waiting -= 1;
122
+ if (waiting > 0) {
123
+ return;
124
+ }
125
+ settle();
126
+ for (const message of unsent.splice(0)) {
127
+ raw.send(message);
128
+ }
129
+ for (const message of heard.splice(0)) {
130
+ deliver(message);
131
+ }
132
+ };
133
+
134
+ raw.listen((message) => {
135
+ if (closed) {
136
+ return;
137
+ }
138
+ const notice = noticeOf(message, set);
139
+ if (notice !== null) {
140
+ if (notice.set === "other" || (notice.arrived && notice.set !== "ok")) {
141
+ // Another version's page, or one that won't say which: never this display's.
142
+ if (waiting > 0) {
143
+ leave();
144
+ }
145
+ return;
146
+ }
147
+ if (waiting === 0 && notice.url === current) {
148
+ // A late copy for the page the frame is on (its leaving page's, or its own): no new page.
149
+ return;
150
+ }
151
+ if (waiting > 0) {
152
+ if (notice.set === "ok") {
153
+ taken(notice.url);
154
+ }
155
+ } else {
156
+ // Either page's notice, for the next load within P084's ten seconds: the host hears the
157
+ // frame's load only once its images and modules have loaded, which can be seconds after
158
+ // the arriving page spoke (after the review of P098).
159
+ grantUntil = Date.now() + PAGE_OF_SET_MS;
160
+ grantFor = notice.url;
161
+ }
162
+ } else if (waiting > 0 && isHello(message)) {
163
+ // A page that greets the host before saying it is one of the set's isn't.
164
+ leave();
165
+ return;
166
+ }
167
+ if (waiting > 0) {
168
+ if (heard.length >= HELD_MOST) {
169
+ // A page that floods the host while it waits isn't one of the set's.
170
+ leave();
171
+ return;
172
+ }
173
+ heard.push(message);
174
+ } else {
175
+ deliver(message);
176
+ }
177
+ });
178
+
179
+ surface.onNavigated(() => {
180
+ if (grantUntil > Date.now()) {
181
+ grantUntil = 0;
182
+ current = grantFor;
183
+ return;
184
+ }
185
+ grantUntil = 0;
186
+ waiting += 1;
187
+ // From the first load that waits: more loads don't put the restart off.
188
+ if (timer === null) {
189
+ timer = setTimeout(leave, LATE_NOTICE_MS);
190
+ }
191
+ });
192
+
193
+ return {
194
+ ...surface,
195
+ transport: {
196
+ send(message) {
197
+ if (waiting > 0) {
198
+ if (unsent.length >= HELD_MOST) {
199
+ leave();
200
+ return;
201
+ }
202
+ unsent.push(message);
203
+ } else {
204
+ raw.send(message);
205
+ }
206
+ },
207
+ listen(listener) {
208
+ listeners.add(listener);
209
+ return () => listeners.delete(listener);
210
+ },
211
+ close() {
212
+ closed = true;
213
+ listeners.clear();
214
+ raw.close();
215
+ },
216
+ },
217
+ destroy() {
218
+ closed = true;
219
+ settle();
220
+ heard.length = 0;
221
+ unsent.length = 0;
222
+ listeners.clear();
223
+ surface.destroy();
224
+ },
225
+ };
226
+ }
package/src/host/types.ts CHANGED
@@ -1,6 +1,13 @@
1
1
  import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
2
2
  import type { Refused } from "../bridge/refusal.ts";
3
- import type { Confirm, CapabilityHandlers, Consent, DataCache, Refusal } from "../bridge/types.ts";
3
+ import type {
4
+ Confirm,
5
+ CapabilityHandlers,
6
+ Consent,
7
+ DataCache,
8
+ Refusal,
9
+ Show,
10
+ } from "../bridge/types.ts";
4
11
  import type { CompiledConfig } from "../compile/compile.ts";
5
12
  import type { CapabilityName } from "../config/capabilities.ts";
6
13
  import type { ColorScheme } from "../config/schema.ts";
@@ -8,6 +15,8 @@ import type { InstanceLocator, InstanceRef } from "../isolation/types.ts";
8
15
  import type { PlatformHost } from "../platform/types.ts";
9
16
  import type { AdapterConnection, ProtocolAdapter, ShellConnection } from "../protocol/adapter.ts";
10
17
  import type { HostContext } from "../protocol/mcp-apps.ts";
18
+ import type { PageDeclaration } from "../runtime/declaration.ts";
19
+ import type { ViewerInfo } from "../runtime/levels.ts";
11
20
 
12
21
  /**
13
22
  * The host-side API (framework-agnostic; the web platform by default). A host compiles a config
@@ -28,6 +37,13 @@ export interface HostOptions<C extends AdapterConnection = ShellConnection> {
28
37
  * not run, P080).
29
38
  */
30
39
  readonly consent?: Consent | Refused;
40
+ /**
41
+ * Puts a `show`-gated call in front of the person, outside the frame, before its handler has it
42
+ * (P100): by default, every `setModelContext` update, the content's text for the model's next
43
+ * turns ("this content updated the agent's context: …", the latest per display). Absent: those
44
+ * calls are refused.
45
+ */
46
+ readonly show?: Show;
31
47
  /**
32
48
  * What the host last had for a resource (P079): a read of one the content subscribes to is
33
49
  * answered with it at once, marked stale, then with the handler's fresh result.
@@ -75,6 +91,22 @@ export interface MountOptions {
75
91
  readonly document?: string;
76
92
  /** The height to start at, before the content reports its own. */
77
93
  readonly initialHeightPx?: number;
94
+ /**
95
+ * What the page declared (P086), as the host stored it with the artifact at publish
96
+ * (`declareCapabilities`): its capabilities, and the runtime contract it is pinned to. The
97
+ * bridge holds the page to it; a page reaches only the built-ins and what it declared. Required
98
+ * under `config.runtime` (after the review): `null` says the page was published before 0.7 and
99
+ * has 0.6's surface (built-ins through `porthole.use`, 0.6's globals and requests as before).
100
+ * Checked against the config at mount (a `TypeError` for one that doesn't fit). For a version
101
+ * older than the artifact's current one, `intersectDeclarations(version's, current)`.
102
+ */
103
+ readonly declaration?: PageDeclaration | null;
104
+ /**
105
+ * Who is viewing (P087): their level, and for `user` their public id and name. A served
106
+ * display's issue answer (`FrameLocation.viewer`, from the host's access) takes precedence.
107
+ * Absent everywhere: 0.6's functions run as before; the runtime's own are refused.
108
+ */
109
+ readonly viewer?: ViewerInfo;
78
110
  /**
79
111
  * Fill the container (give it a height) instead of taking the content's height.
80
112
  *