@botiverse/porthole 0.13.0 → 0.14.1

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 (77) hide show
  1. package/CHANGELOG.md +770 -0
  2. package/dist/annotate/types.d.ts +36 -4
  3. package/dist/annotate/types.js +6 -0
  4. package/dist/annotate/validate.d.ts +2 -1
  5. package/dist/annotate/validate.js +30 -6
  6. package/dist/check/page-source.js +1 -1
  7. package/dist/compile/policy.d.ts +7 -0
  8. package/dist/compile/policy.js +13 -1
  9. package/dist/config/schema.d.ts +11 -0
  10. package/dist/config/validate.js +19 -0
  11. package/dist/conformance/harness-source.js +1 -1
  12. package/dist/displays/displays.js +3 -1
  13. package/dist/guide/limits.js +1 -1
  14. package/dist/host/create-host.d.ts +2 -0
  15. package/dist/host/create-host.js +78 -3
  16. package/dist/host/pass-on.d.ts +15 -0
  17. package/dist/host/pass-on.js +65 -0
  18. package/dist/host/types.d.ts +29 -0
  19. package/dist/index.d.ts +4 -1
  20. package/dist/index.js +4 -1
  21. package/dist/isolation/types.d.ts +8 -0
  22. package/dist/isolation/types.js +8 -0
  23. package/dist/platform/focus-guard.d.ts +71 -2
  24. package/dist/platform/focus-guard.js +187 -12
  25. package/dist/platform/types.d.ts +8 -1
  26. package/dist/platform/web.js +60 -4
  27. package/dist/presets/presets.d.ts +2 -0
  28. package/dist/presets/presets.js +1 -0
  29. package/dist/react/frame.d.ts +4 -3
  30. package/dist/server/files.js +19 -3
  31. package/dist/server/index.d.ts +1 -0
  32. package/dist/server/index.js +5 -0
  33. package/dist/server/naming.js +4 -0
  34. package/dist/server/nested.d.ts +59 -0
  35. package/dist/server/nested.js +96 -0
  36. package/dist/server/server.js +193 -23
  37. package/dist/server/types.d.ts +5 -0
  38. package/dist/shell/annotate.d.ts +4 -3
  39. package/dist/shell/annotate.js +179 -9
  40. package/dist/shell/frame.d.ts +45 -0
  41. package/dist/shell/frame.js +250 -0
  42. package/dist/shell/plan.js +2 -1
  43. package/dist/shell/runtime.d.ts +6 -0
  44. package/dist/shell/runtime.js +60 -15
  45. package/docs/ADOPTING.md +85 -2
  46. package/docs/ARCHITECTURE.md +28 -0
  47. package/docs/DECISIONS.md +416 -1
  48. package/docs/DESIGN.md +21 -4
  49. package/docs/THREAT_MODEL.md +102 -5
  50. package/package.json +6 -5
  51. package/src/annotate/types.ts +32 -4
  52. package/src/annotate/validate.ts +34 -8
  53. package/src/compile/policy.ts +14 -1
  54. package/src/config/schema.ts +11 -0
  55. package/src/config/validate.ts +23 -0
  56. package/src/displays/displays.ts +3 -1
  57. package/src/guide/limits.ts +1 -1
  58. package/src/host/create-host.ts +81 -4
  59. package/src/host/pass-on.ts +73 -0
  60. package/src/host/types.ts +27 -0
  61. package/src/index.ts +4 -1
  62. package/src/isolation/types.ts +12 -0
  63. package/src/platform/focus-guard.ts +258 -15
  64. package/src/platform/types.ts +8 -1
  65. package/src/platform/web.ts +81 -9
  66. package/src/presets/presets.ts +3 -0
  67. package/src/react/frame.tsx +4 -3
  68. package/src/server/files.ts +19 -3
  69. package/src/server/index.ts +14 -0
  70. package/src/server/naming.ts +4 -0
  71. package/src/server/nested.ts +116 -0
  72. package/src/server/server.ts +224 -21
  73. package/src/server/types.ts +5 -0
  74. package/src/shell/annotate.ts +179 -9
  75. package/src/shell/frame.ts +268 -0
  76. package/src/shell/plan.ts +2 -1
  77. package/src/shell/runtime.ts +61 -15
@@ -24,8 +24,10 @@ export function defineDisplays(kinds) {
24
24
  return presets.url({ ...kind.options, contentOrigins: [source] });
25
25
  }
26
26
  const options = kind.options ?? {};
27
+ // Nesting (P111) is a served page's: an opaque frame has nothing to nest.
28
+ const { nested: _nested, ...opaque } = options;
27
29
  return presets[kind.preset](source === null
28
- ? options
30
+ ? opaque
29
31
  : { ...options, ...kind.served, isolation: "domain", contentOrigins: [source] });
30
32
  };
31
33
  // Made once each: a page that asks every render gets the same objects.
@@ -132,7 +132,7 @@ export function manualLimits(config, network) {
132
132
  ? `The ${it}'s address is about:srcdoc: it has no query string or hash to read.`
133
133
  : `The ${it}'s address is its own (with Porthole's one-time ticket), never the app's: read no parameters from it.`);
134
134
  add("shell", `document.write and document.open throw; nested frames (iframe, object, embed) are removed; full screen and the clipboard are closed${globals.has("copyText") ? " (copy buttons call copyText)" : config.runtime !== undefined && declared.has("copyText") ? " (copy buttons call clipboard.copy)" : ""}.`);
135
- add("storage", config.isolation === "opaque"
135
+ add("storage", config.isolation === "opaque" || config.nested === true
136
136
  ? `State isn't saved: localStorage works but lasts only while the ${it} is on screen, and a reload or another device starts fresh. Keep what matters in the ${it}'s code.`
137
137
  : config.storage?.scope !== undefined
138
138
  ? `localStorage is kept for ${config.storage.scope}, in this browser; another browser or device starts fresh. Reads and writes can throw (private windows, strict settings): wrap them in try/catch and keep only what can be lost.`
@@ -1,6 +1,8 @@
1
1
  import type { PortholeConfig } from "../config/schema.ts";
2
2
  import type { AdapterConnection, ShellConnection } from "../protocol/adapter.ts";
3
3
  import type { HostOptions, PortholeHost } from "./types.ts";
4
+ /** The most `tracked` reports a second the host takes (P112): one per animation frame at 60 Hz. */
5
+ export declare const TRACKED_PER_SECOND = 60;
4
6
  /**
5
7
  * Compiles `config` once and returns a host that mounts displays under it. Throws a `ConfigError`
6
8
  * for a bad config.
@@ -8,7 +8,9 @@ import { declaredCapabilities, effectiveGates } from "../compile/policy.js";
8
8
  import { isRefused } from "../bridge/refusal.js";
9
9
  import { capabilitySpec } from "../config/capabilities.js";
10
10
  import { locateServed } from "./locate.js";
11
+ import { mayPassOn } from "./pass-on.js";
11
12
  import { watchOutcome } from "./outcome.js";
13
+ import { STORAGE_USED_METHOD } from "../isolation/types.js";
12
14
  import { webPlatform } from "../platform/web.js";
13
15
  import { TAKES } from "../platform/focus-guard.js";
14
16
  import { MCP_APPS_STYLE_VARIABLES, PORTHOLE_STYLES, } from "../protocol/mcp-apps.js";
@@ -28,7 +30,10 @@ const REPORTS = {
28
30
  [ANNOTATE_METHODS.cancelled]: "cancelled",
29
31
  [ANNOTATE_METHODS.anchored]: "anchored",
30
32
  [ANNOTATE_METHODS.activated]: "activated",
33
+ [ANNOTATE_METHODS.tracked]: "tracked",
31
34
  };
35
+ /** The most `tracked` reports a second the host takes (P112): one per animation frame at 60 Hz. */
36
+ export const TRACKED_PER_SECOND = 60;
32
37
  const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
33
38
  const STANDARD = new Set(MCP_APPS_STYLE_VARIABLES);
34
39
  /**
@@ -48,6 +53,7 @@ export function createHost(config, options = {}) {
48
53
  const hostInfo = options.hostInfo ?? { name: "porthole", version: "0" };
49
54
  return {
50
55
  compiled,
56
+ mayPassOn: (declaration) => mayPassOn(config, declaration),
51
57
  mount(container, mount) {
52
58
  const handlers = { ...options.handlers, ...mount.handlers };
53
59
  // A host whose consent is a Refused refuses every consent-gated call before its handler:
@@ -122,7 +128,11 @@ export function createHost(config, options = {}) {
122
128
  let annotating = null;
123
129
  let marks = [];
124
130
  let activeMark = null;
131
+ // The mark the host follows (P112), and when it took each `tracked` in the last second.
132
+ let tracking = null;
133
+ const trackedTimes = [];
125
134
  let handshaken = false;
135
+ let storageTold = false;
126
136
  const toFrame = (method, params) => {
127
137
  if (handshaken && surface !== null) {
128
138
  surface.transport.send({ jsonrpc: "2.0", method, params });
@@ -138,6 +148,9 @@ export function createHost(config, options = {}) {
138
148
  if (annotating !== null) {
139
149
  toFrame(ANNOTATE_METHODS.start, { ...annotating });
140
150
  }
151
+ if (tracking !== null) {
152
+ toFrame(ANNOTATE_METHODS.track, { id: tracking });
153
+ }
141
154
  };
142
155
  /**
143
156
  * The frame's viewport as the platform tells it now; undefined where it can't (no
@@ -183,6 +196,7 @@ export function createHost(config, options = {}) {
183
196
  switch (report.type) {
184
197
  case "selected":
185
198
  case "activated":
199
+ case "tracked":
186
200
  return { ...report, rect: clampRect(report.rect, viewport) };
187
201
  case "anchored":
188
202
  return {
@@ -217,6 +231,25 @@ export function createHost(config, options = {}) {
217
231
  void through.call("annotate", null);
218
232
  return;
219
233
  }
234
+ // The followed mark's box (P112): the mark the host follows and no other, while it is
235
+ // shown, at most 60 a second; past the bridge's rate for reports, which a card that follows
236
+ // its mark at every frame would spend at once.
237
+ if (report.type === "tracked") {
238
+ const { id } = report;
239
+ if (id !== tracking || !marks.some((mark) => mark.id === id)) {
240
+ return;
241
+ }
242
+ const at = Date.now();
243
+ while (trackedTimes.length > 0 && at - trackedTimes[0] >= 1_000) {
244
+ trackedTimes.shift();
245
+ }
246
+ if (trackedTimes.length >= TRACKED_PER_SECOND) {
247
+ return;
248
+ }
249
+ trackedTimes.push(at);
250
+ emit("annotation", withinFrame(report));
251
+ return;
252
+ }
220
253
  switch (report.type) {
221
254
  case "selected": {
222
255
  const kind = report.anchor.kind;
@@ -224,7 +257,8 @@ export function createHost(config, options = {}) {
224
257
  !(kind === "element" ? annotating.elements : annotating.text)) {
225
258
  return;
226
259
  }
227
- if (kind === "element") {
260
+ // A pick ends with it; holding a block (P112) lasts until the host stops it.
261
+ if (kind === "element" && annotating.elements === true) {
228
262
  annotating = annotating.text ? { elements: false, text: true } : null;
229
263
  }
230
264
  break;
@@ -235,10 +269,14 @@ export function createHost(config, options = {}) {
235
269
  }
236
270
  break;
237
271
  case "cancelled":
238
- if (annotating?.elements !== true) {
272
+ // While the host asked for a pick or for text (P112: Escape while selecting text);
273
+ // a pick ends with it, text selection is the host's to stop.
274
+ if (annotating === null) {
239
275
  return;
240
276
  }
241
- annotating = annotating.text ? { elements: false, text: true } : null;
277
+ if (annotating.elements === true) {
278
+ annotating = annotating.text ? { elements: false, text: true } : null;
279
+ }
242
280
  break;
243
281
  case "anchored": {
244
282
  const known = new Set(marks.map((mark) => mark.id));
@@ -288,6 +326,10 @@ export function createHost(config, options = {}) {
288
326
  if (activeMark !== null && !marks.some((mark) => mark.id === activeMark)) {
289
327
  activeMark = null;
290
328
  }
329
+ if (tracking !== null && !marks.some((mark) => mark.id === tracking)) {
330
+ tracking = null;
331
+ toFrame(ANNOTATE_METHODS.track, { id: null });
332
+ }
291
333
  toFrame(ANNOTATE_METHODS.show, {
292
334
  marks,
293
335
  ...(activeMark === null ? {} : { active: activeMark }),
@@ -301,12 +343,27 @@ export function createHost(config, options = {}) {
301
343
  activeMark = id;
302
344
  toFrame(ANNOTATE_METHODS.focus, { id });
303
345
  },
346
+ track(id) {
347
+ needsAnnotate("track");
348
+ if (id !== null && !marks.some((mark) => mark.id === id)) {
349
+ throw new TypeError(`annotations.track: no mark ${JSON.stringify(id)} is shown`);
350
+ }
351
+ tracking = id;
352
+ trackedTimes.length = 0;
353
+ toFrame(ANNOTATE_METHODS.track, { id });
354
+ },
304
355
  clear() {
305
356
  needsAnnotate("clear");
306
357
  marks = [];
307
358
  activeMark = null;
359
+ tracking = null;
308
360
  toFrame(ANNOTATE_METHODS.clear, {});
309
361
  },
362
+ clearSelection() {
363
+ // Host → frame only, and kept for no later frame (P115).
364
+ needsAnnotate("clearSelection");
365
+ toFrame(ANNOTATE_METHODS.clearSelection, {});
366
+ },
310
367
  };
311
368
  const hostContext = () => {
312
369
  const width = container.getBoundingClientRect().width;
@@ -364,6 +421,11 @@ export function createHost(config, options = {}) {
364
421
  }
365
422
  };
366
423
  const stop = () => {
424
+ // A run that ran a page with storage of its own making and never heard it used: no (P111).
425
+ if (bridge !== null && handshaken && !storageTold && compiled.shell?.storage === "memory") {
426
+ emit("storage", { used: false });
427
+ }
428
+ storageTold = false;
367
429
  // The run's bridge refuses what still waits for a confirmation: a yes to it runs nothing
368
430
  // (P095, after the review), and the next run's bridge starts its count again.
369
431
  bridge?.close();
@@ -397,6 +459,8 @@ export function createHost(config, options = {}) {
397
459
  allow: compiled.allow,
398
460
  referrerPolicy: compiled.referrerPolicy,
399
461
  colorScheme: scheme,
462
+ // A nested page's shell (P111): the config's word, never the frame's.
463
+ ...(config.nested === true ? { nested: true } : {}),
400
464
  // An app reports no size: its frame fills the host's container, at least the minimum;
401
465
  // so does any display the host mounts to fill, or whose layout fills (P065): its
402
466
  // content scrolls itself.
@@ -487,6 +551,17 @@ export function createHost(config, options = {}) {
487
551
  if (annotates) {
488
552
  created.transport.listen((raw) => onAnnotation(raw, opening));
489
553
  }
554
+ // Whether the page used storage (P111): once per run, the page's word (a count, no more).
555
+ created.transport.listen((raw) => {
556
+ if (!storageTold &&
557
+ isRecord(raw) &&
558
+ raw.jsonrpc === "2.0" &&
559
+ raw.method === STORAGE_USED_METHOD &&
560
+ !("id" in raw)) {
561
+ storageTold = true;
562
+ emit("storage", { used: true });
563
+ }
564
+ });
490
565
  bridge = opening;
491
566
  const opened = adapter.connect({
492
567
  display: { id: mount.displayId, title: mount.title },
@@ -0,0 +1,15 @@
1
+ import type { PortholeConfig } from "../config/schema.ts";
2
+ import type { PageDeclaration } from "../runtime/declaration.ts";
3
+ /**
4
+ * Whether a page shown under `config` with `declaration` may pass on what it is given (P112: a
5
+ * person's draft, which a host shows a page only where it can't). It may when it can reach one of
6
+ * the host functions that carry what it puts in them to others (`CARRIERS`; `reportError` where
7
+ * errors go to the agent), or the network beyond the library CDNs (`LIBRARY_CDNS`): any https site
8
+ * (`anyHttps`), or an origin the host (or a capability) added for connections, scripts, styles,
9
+ * images, fonts or media. A library CDN serves published packages by their path, and its logs are
10
+ * its operator's, not the page author's: not counted. A page reaches a host function the config
11
+ * declares: under the runtime with a declaration, only through a built-in family or one it
12
+ * declared (one no family serves, wherever the config declares it); without a declaration (a page from before 0.7), or without the runtime, every one, as
13
+ * 0.6's globals. The host's rule made checkable: "a page with a channel gets no drafts".
14
+ */
15
+ export declare function mayPassOn(config: PortholeConfig, declaration: PageDeclaration | null): boolean;
@@ -0,0 +1,65 @@
1
+ import { egressOrigins } from "../compile/policy.js";
2
+ import { LIBRARY_CDNS } from "../presets/presets.js";
3
+ import { familyOf, runtimeCapability } from "../runtime/contract.js";
4
+ /** Every kind a page reaches the network by. */
5
+ const KINDS = ["connect", "script", "style", "img", "font", "media"];
6
+ /**
7
+ * The host functions that carry what a page puts in them to someone other than the person viewing
8
+ * it (P112, after the review, porthole#54): stores others read (`db`, a new version through
9
+ * `artifact`, the asset library through `assets`), a URL the person opens (`openLink`), the agent's
10
+ * conversation and context (`sendPrompt`, `setModelContext`), and the host's data services, which
11
+ * may be someone else's (`callTool`, `readData`, `subscribeData`: their arguments are the page's).
12
+ * Not here: the person's own clipboard and disk (`copyText`, `downloadFile`), the host's own UI
13
+ * (`annotate`, `resize`, `comments`: the composer is the person's, under the host's duties), and
14
+ * what only reads (`user`). `reportError` is one where the config sends errors to the agent.
15
+ */
16
+ const CARRIERS = [
17
+ "db",
18
+ "artifact",
19
+ "assets",
20
+ "openLink",
21
+ "sendPrompt",
22
+ "setModelContext",
23
+ "callTool",
24
+ "readData",
25
+ "subscribeData",
26
+ ];
27
+ /**
28
+ * Whether a page shown under `config` with `declaration` may pass on what it is given (P112: a
29
+ * person's draft, which a host shows a page only where it can't). It may when it can reach one of
30
+ * the host functions that carry what it puts in them to others (`CARRIERS`; `reportError` where
31
+ * errors go to the agent), or the network beyond the library CDNs (`LIBRARY_CDNS`): any https site
32
+ * (`anyHttps`), or an origin the host (or a capability) added for connections, scripts, styles,
33
+ * images, fonts or media. A library CDN serves published packages by their path, and its logs are
34
+ * its operator's, not the page author's: not counted. A page reaches a host function the config
35
+ * declares: under the runtime with a declaration, only through a built-in family or one it
36
+ * declared (one no family serves, wherever the config declares it); without a declaration (a page from before 0.7), or without the runtime, every one, as
37
+ * 0.6's globals. The host's rule made checkable: "a page with a channel gets no drafts".
38
+ */
39
+ export function mayPassOn(config, declaration) {
40
+ const declared = (declaration?.capabilities ?? {});
41
+ const reaches = (name) => {
42
+ if (config.capabilities[name] === undefined) {
43
+ return false;
44
+ }
45
+ if (config.runtime === undefined || declaration === null) {
46
+ return true;
47
+ }
48
+ // One no runtime family serves (`reportError`: the shell reports what the page throws) is
49
+ // the page's wherever the config declares it.
50
+ const family = familyOf(name);
51
+ return (family === null ||
52
+ runtimeCapability(family.name).builtIn ||
53
+ declared[family.name] !== undefined);
54
+ };
55
+ if (CARRIERS.some(reaches) || (config.errors === "agent" && reaches("reportError"))) {
56
+ return true;
57
+ }
58
+ if ((config.egress.anyHttps ?? []).length > 0) {
59
+ return true;
60
+ }
61
+ return KINDS.some((kind) => {
62
+ const cdns = new Set(LIBRARY_CDNS[kind] ?? []);
63
+ return egressOrigins(config, kind).some((origin) => !cdns.has(origin));
64
+ });
65
+ }
@@ -215,6 +215,15 @@ export interface DisplayEvents {
215
215
  readonly focusTaken: {
216
216
  readonly typing: boolean;
217
217
  };
218
+ /**
219
+ * Whether the page touched `localStorage` or `sessionStorage` (the in-memory stand-in of a frame
220
+ * without storage of its own: opaque, or a nested page, P111): once per run, `used: true` when
221
+ * the page first did, else `used: false` as the run ends. Never what it kept: for a host to count
222
+ * the pages that would need storage.
223
+ */
224
+ readonly storage: {
225
+ readonly used: boolean;
226
+ };
218
227
  /**
219
228
  * What the frame reported about annotations (`annotate`, P053), checked and taken only while
220
229
  * the host asked for it: a selection, its clearing, a cancelled pick, where marks are. The
@@ -234,8 +243,22 @@ export interface AnnotationControls {
234
243
  show(marks: readonly AnnotationMark[]): void;
235
244
  /** Brings a mark into view in the frame and makes it the active one. */
236
245
  focus(id: string): void;
246
+ /**
247
+ * Follows one shown mark (P112): while it moves (a scroll, a layout change) the display reports
248
+ * `{ type: "tracked", id, rect }` at most once per animation frame (60 a second), its box clamped
249
+ * to the frame, for that mark only; `null` stops. One at a time: a new id replaces the last.
250
+ * Throws for an id no shown mark has; a `show` without it, or `clear`, stops it.
251
+ */
252
+ track(id: string | null): void;
237
253
  /** Removes every mark. */
238
254
  clear(): void;
255
+ /**
256
+ * Takes the page's text selection away (P115), its highlight with it: for when the host has
257
+ * used it (a comment posted, a draft added). No `unselected` follows; marks (posted and drafts),
258
+ * the mode and a followed mark stay as they are. Nothing selected: nothing happens. Not kept for
259
+ * a frame that runs later (it has no selection to clear).
260
+ */
261
+ clearSelection(): void;
239
262
  }
240
263
  export interface DisplayControls {
241
264
  readonly displayId: string;
@@ -268,4 +291,10 @@ export interface PortholeHost<C extends AdapterConnection = ShellConnection> {
268
291
  * none (here or in the host's options), so a manual never teaches a function nobody serves.
269
292
  */
270
293
  mount(container: HTMLElement, options: MountOptions): DisplayHandle<C>;
294
+ /**
295
+ * Whether a page with `declaration` may pass on what it is given (`mayPassOn`, P112): true where
296
+ * it can store what others read (`db` and `user`) or reaches the network beyond the library CDNs.
297
+ * A host shows such a page none of a person's drafts.
298
+ */
299
+ mayPassOn(declaration: PageDeclaration | null): boolean;
271
300
  }
package/dist/index.d.ts CHANGED
@@ -9,7 +9,9 @@ export { BUILT_IN_TOPICS, ConfigError, isOriginSource, originSourceProblem, vali
9
9
  export { configWarnings, type ConfigWarning } from "./config/warnings.ts";
10
10
  export { URL_PERMISSIONS, URL_SANDBOX_EXTRAS, type UrlPermission, type UrlSandboxExtra, } from "./config/schema.ts";
11
11
  export { hostOriginProblem, isHostOrigin } from "./isolation/served.ts";
12
- export { FRAME_STATUS_METHOD } from "./isolation/types.ts";
12
+ export { FRAME_STATUS_METHOD, SHELL_STATE_METHOD, STORAGE_USED_METHOD } from "./isolation/types.ts";
13
+ export { PAGE_SANDBOX_TOKENS } from "./compile/policy.ts";
14
+ export { SHELL_GESTURE_MS } from "./platform/focus-guard.ts";
13
15
  export { RUNTIME_CALL_METHOD, RUNTIME_CAPABILITIES, RUNTIME_CAPABILITY_NAMES, RUNTIME_EVENT_METHOD, RUNTIME_EXPERIMENTAL_KEY, RUNTIME_GLOBAL, RUNTIME_HOST_FUNCTIONS, RUNTIME_UNWATCH_METHOD, RUNTIME_VERSION, RUNTIME_VERSIONS, familyOf, isRuntimeCapabilityName, methodGates, isRuntimeVersion, methodLevel, offeredCapabilities, rosterOf, type RuntimeCapability, type RuntimeCapabilityName, type RuntimeMethod, type RuntimeVersion, } from "./runtime/contract.ts";
14
16
  export { VIEWER_LEVELS, atLeast, isViewerLevel, parseViewer, type ViewerInfo, type ViewerLevel, } from "./runtime/levels.ts";
15
17
  export { checkDeclaration, declarationProblems, declareCapabilities, declaredMatch, intersectDeclarations, tryIntersectDeclarations, type CapabilityDeclaration, type DeclarationProblem, type DeclaredCapability, type DeclaredData, type DeclaredDb, type PageDeclaration, } from "./runtime/declaration.ts";
@@ -35,6 +37,7 @@ export { COPY_TEXT_METHOD, MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS
35
37
  export { REFUSAL_CODES, Refused, isRefused, type RefusalCode, type RefusalReason, } from "./bridge/refusal.ts";
36
38
  export type { CallContext, CallOptions, CallOutcome, CapabilityHandler, CapabilityHandlers, Confirm, ConfirmAnswer, ConfirmDisplay, ConfirmRequest, Consent, DataCache, Proceed, HostFunctionBridge, Refusal, Show, SubscriptionContext, DbContext, } from "./bridge/types.ts";
37
39
  export { createHost } from "./host/create-host.ts";
40
+ export { mayPassOn } from "./host/pass-on.ts";
38
41
  export { focusField } from "./platform/focus-guard.ts";
39
42
  export { entryTarget, frameFallback, portholeClient, type ContentClientMeta, type FrameFallback, type PortholeClient, type PortholeClientOptions, } from "./host/client.ts";
40
43
  export { defineDisplays, type DisplayKind, type Displays } from "./displays/displays.ts";
package/dist/index.js CHANGED
@@ -9,7 +9,9 @@ export { BUILT_IN_TOPICS, ConfigError, isOriginSource, originSourceProblem, vali
9
9
  export { configWarnings } from "./config/warnings.js";
10
10
  export { URL_PERMISSIONS, URL_SANDBOX_EXTRAS, } from "./config/schema.js";
11
11
  export { hostOriginProblem, isHostOrigin } from "./isolation/served.js";
12
- export { FRAME_STATUS_METHOD } from "./isolation/types.js";
12
+ export { FRAME_STATUS_METHOD, SHELL_STATE_METHOD, STORAGE_USED_METHOD } from "./isolation/types.js";
13
+ export { PAGE_SANDBOX_TOKENS } from "./compile/policy.js";
14
+ export { SHELL_GESTURE_MS } from "./platform/focus-guard.js";
13
15
  // The capability runtime (P085-P090): its contract, levels, a page's declaration, its services'
14
16
  // shapes. Hosts implement the services; Porthole carries, checks and gates the calls.
15
17
  export { RUNTIME_CALL_METHOD, RUNTIME_CAPABILITIES, RUNTIME_CAPABILITY_NAMES, RUNTIME_EVENT_METHOD, RUNTIME_EXPERIMENTAL_KEY, RUNTIME_GLOBAL, RUNTIME_HOST_FUNCTIONS, RUNTIME_UNWATCH_METHOD, RUNTIME_VERSION, RUNTIME_VERSIONS, familyOf, isRuntimeCapabilityName, methodGates, isRuntimeVersion, methodLevel, offeredCapabilities, rosterOf, } from "./runtime/contract.js";
@@ -36,6 +38,7 @@ export { COPY_TEXT_METHOD, MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS
36
38
  // Why a call was refused, as content is told it, and the host's own refusals (P080).
37
39
  export { REFUSAL_CODES, Refused, isRefused, } from "./bridge/refusal.js";
38
40
  export { createHost } from "./host/create-host.js";
41
+ export { mayPassOn } from "./host/pass-on.js";
39
42
  export { focusField } from "./platform/focus-guard.js";
40
43
  // The client half of the host kit, and the display registry (P072).
41
44
  export { entryTarget, frameFallback, portholeClient, } from "./host/client.js";
@@ -79,6 +79,14 @@ export interface FrameLocation {
79
79
  }
80
80
  /** The message a served page sends its host about loading (own-prefixed, P040). */
81
81
  export declare const FRAME_STATUS_METHOD = "porthole/notifications/frame-status";
82
+ /** A nested page's shell's report of its own state to the host (P111). */
83
+ export declare const SHELL_STATE_METHOD = "porthole/shell/state";
84
+ /** A nested page's shell's heartbeat, every 50 ms while it runs (P111, after its review). */
85
+ export declare const SHELL_BEAT_METHOD = "porthole/shell/beat";
86
+ /** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
87
+ export declare const SHELL_METHOD_PREFIX = "porthole/shell/";
88
+ /** A page's word that it used storage, once per load (P111): never a key or a value. */
89
+ export declare const STORAGE_USED_METHOD = "porthole/storage-used";
82
90
  /**
83
91
  * Turns an instance into the URL its frame loads. Implemented by the host, usually by asking its
84
92
  * own backend (which authenticates the viewer and calls `PortholeServer.issue`). Called on every
@@ -1,2 +1,10 @@
1
1
  /** The message a served page sends its host about loading (own-prefixed, P040). */
2
2
  export const FRAME_STATUS_METHOD = "porthole/notifications/frame-status";
3
+ /** A nested page's shell's report of its own state to the host (P111). */
4
+ export const SHELL_STATE_METHOD = "porthole/shell/state";
5
+ /** A nested page's shell's heartbeat, every 50 ms while it runs (P111, after its review). */
6
+ export const SHELL_BEAT_METHOD = "porthole/shell/beat";
7
+ /** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
8
+ export const SHELL_METHOD_PREFIX = "porthole/shell/";
9
+ /** A page's word that it used storage, once per load (P111): never a key or a value. */
10
+ export const STORAGE_USED_METHOD = "porthole/storage-used";
@@ -60,6 +60,45 @@ export declare const TAKES: {
60
60
  readonly withinMs: 2000;
61
61
  };
62
62
  };
63
+ /**
64
+ * A nested page's shell (P111) says its own activation turned on: a press or key of the person's
65
+ * in that page (activation goes up to ancestors, never down, so nothing on the host's page turns
66
+ * it on). A move of focus into the frame within this long of it, with no press or key on the
67
+ * host's page since, is the person's; so is a `comments.open` the page sends within it.
68
+ */
69
+ export declare const SHELL_GESTURE_MS = 1000;
70
+ /**
71
+ * How long a move into a nested page's frame waits for its shell's word before it is taken for
72
+ * the page's: the shell says what it saw at its next animation frame, after the host's page
73
+ * already heard the move. A shell that says nothing in time (gone, stalled) has its frame's move
74
+ * taken back, as any page's.
75
+ */
76
+ export declare const SHELL_WAIT_MS = 500;
77
+ /**
78
+ * A shell's word that came this long before the host's page heard the move is about that move
79
+ * (the shell's frame can come first); one from before then is about an earlier one.
80
+ */
81
+ export declare const SHELL_EARLY_MS = 150;
82
+ /**
83
+ * A shell that went this long without a look, or without a word to the host (its heartbeat is every
84
+ * 50 ms), was stalled (P111, after its review): where the page shares the shell's thread (WebKit,
85
+ * Firefox), a page that holds it from its own click handler pushes the moment the shell sees its
86
+ * activation turn on past the person's next keys on the host's page. An activation it saw then is
87
+ * uncertain: it is no one's gesture until it lapses.
88
+ */
89
+ export declare const SHELL_STALL_MS = 100;
90
+ /** What a nested page's shell last said (P111), on the host's clock. */
91
+ export interface ShellWord {
92
+ /** Whether its engine tells activation at all (`navigator.userActivation`). */
93
+ readonly supported: boolean;
94
+ /** When its activation last turned on; -Infinity if it hasn't, or is off. */
95
+ readonly activatedAt: number;
96
+ /** Whether it last said the page's focus is in it, and when it last said focus came in. */
97
+ readonly focused: boolean;
98
+ readonly focusedAt: number;
99
+ /** Its activation turned on while it was stalled: uncertain until it goes off (`SHELL_STALL_MS`). */
100
+ readonly uncertain?: boolean;
101
+ }
63
102
  /** One move of the keyboard the guard undid. */
64
103
  export interface FocusTake {
65
104
  /** The person pressed a key on the host's page within the last second. */
@@ -96,6 +135,14 @@ export interface FocusMove {
96
135
  readonly activation: boolean | undefined;
97
136
  /** The host moved focus into the frame itself (`DisplayHandle.focus()`), just now. */
98
137
  readonly hostMoved: boolean;
138
+ /**
139
+ * A nested page's frame (P111): what its shell said, and when the host's page last had a
140
+ * trusted press or key of its own. Absent for any other frame.
141
+ */
142
+ readonly shell?: {
143
+ readonly word: ShellWord;
144
+ readonly hostInputAt: number;
145
+ };
99
146
  }
100
147
  /**
101
148
  * Whether the person moved focus into the frame themselves:
@@ -115,12 +162,34 @@ export interface FocusMove {
115
162
  * Anything else is the page's: focus goes back.
116
163
  */
117
164
  export declare function personMoved(move: FocusMove): boolean;
165
+ /**
166
+ * Whether a nested page's shell saw the person's gesture just now (P111): its activation turned on
167
+ * within `SHELL_GESTURE_MS`, after the host's page's last trusted press or key.
168
+ */
169
+ export declare function shellGesture(word: ShellWord, hostInputAt: number, now: number): boolean;
118
170
  /** Whether `element` takes the person's typed text: a text field, a text area, an editable region. */
119
171
  export declare function takesText(element: Element | null): element is HTMLElement;
120
172
  /** One page's guard, shared by every display's frame on it. */
121
173
  export interface FocusGuard {
122
- /** Guards `frame`: `taken` hears each move into it that was undone. */
123
- add(frame: HTMLIFrameElement, taken: (take: FocusTake) => void): () => void;
174
+ /**
175
+ * Guards `frame`: `taken` hears each move into it that was undone. `nested`: it holds a nested
176
+ * page's shell (P111), whose word (`shell`) decides the moves into it.
177
+ */
178
+ add(frame: HTMLIFrameElement, taken: (take: FocusTake) => void, options?: {
179
+ readonly nested?: boolean;
180
+ }): () => void;
181
+ /** What a nested page's shell said (P111): its activation, its focus. */
182
+ shell(frame: HTMLIFrameElement, said: {
183
+ readonly supported: boolean;
184
+ readonly ago: number | null;
185
+ readonly focused: boolean;
186
+ /** How long the shell went without a look before this one (its own clock). */
187
+ readonly gap: number;
188
+ }): void;
189
+ /** A nested page's shell's heartbeat (P111): it is looking. */
190
+ beat(frame: HTMLIFrameElement): void;
191
+ /** Whether a nested page's shell saw the person's gesture just now (`shellGesture`). */
192
+ gesture(frame: HTMLIFrameElement): boolean;
124
193
  /** The host moves focus into `frame` itself. */
125
194
  focus(frame: HTMLIFrameElement): void;
126
195
  /**