@botiverse/porthole 0.15.3 → 0.16.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 (118) hide show
  1. package/CHANGELOG.md +70 -0
  2. package/dist/annotate/types.d.ts +15 -1
  3. package/dist/annotate/validate.js +19 -1
  4. package/dist/bridge/bridge.d.ts +1 -8
  5. package/dist/bridge/bridge.js +0 -7
  6. package/dist/bridge/types.d.ts +1 -1
  7. package/dist/check/page-source.js +1 -1
  8. package/dist/check/page.js +1 -1
  9. package/dist/compile/policy.d.ts +0 -7
  10. package/dist/compile/policy.js +1 -10
  11. package/dist/config/capabilities.d.ts +8 -14
  12. package/dist/config/capabilities.js +4 -5
  13. package/dist/config/schema.d.ts +2 -13
  14. package/dist/config/validate.js +0 -24
  15. package/dist/conformance/behavior.js +26 -37
  16. package/dist/conformance/clipboard.js +47 -1
  17. package/dist/conformance/harness-source.js +1 -1
  18. package/dist/displays/displays.js +1 -3
  19. package/dist/guide/limits.js +1 -1
  20. package/dist/guide/runtime.js +1 -1
  21. package/dist/host/create-host.d.ts +1 -1
  22. package/dist/host/create-host.js +8 -52
  23. package/dist/host/door.d.ts +1 -1
  24. package/dist/host/locate.d.ts +1 -1
  25. package/dist/host/locate.js +2 -2
  26. package/dist/host/outcome.d.ts +5 -12
  27. package/dist/host/outcome.js +8 -16
  28. package/dist/host/types.d.ts +6 -22
  29. package/dist/index.d.ts +2 -4
  30. package/dist/index.js +2 -4
  31. package/dist/isolation/served.d.ts +4 -14
  32. package/dist/isolation/served.js +7 -28
  33. package/dist/isolation/types.d.ts +2 -25
  34. package/dist/isolation/types.js +0 -23
  35. package/dist/platform/focus-field.d.ts +11 -0
  36. package/dist/platform/focus-field.js +18 -0
  37. package/dist/platform/types.d.ts +7 -23
  38. package/dist/platform/web.js +8 -106
  39. package/dist/presets/presets.d.ts +0 -2
  40. package/dist/presets/presets.js +0 -1
  41. package/dist/react/frame.d.ts +0 -8
  42. package/dist/react/frame.js +0 -4
  43. package/dist/runtime/contract.d.ts +2 -2
  44. package/dist/runtime/contract.js +2 -2
  45. package/dist/runtime/types.generated.js +6 -6
  46. package/dist/server/files.js +7 -23
  47. package/dist/server/host.d.ts +1 -1
  48. package/dist/server/index.d.ts +1 -1
  49. package/dist/server/index.js +4 -6
  50. package/dist/server/naming.js +1 -1
  51. package/dist/server/server.js +28 -166
  52. package/dist/server/types.d.ts +7 -7
  53. package/dist/shell/annotate.d.ts +3 -0
  54. package/dist/shell/annotate.js +15 -5
  55. package/dist/shell/plan.d.ts +0 -5
  56. package/dist/shell/plan.js +2 -4
  57. package/dist/shell/runtime.js +1 -268
  58. package/docs/ADOPTING.md +398 -1081
  59. package/docs/DECISIONS.md +172 -10
  60. package/docs/DESIGN.md +1114 -1388
  61. package/docs/PRINCIPLES.md +85 -1
  62. package/docs/THREAT_MODEL.md +658 -1127
  63. package/package.json +1 -1
  64. package/src/annotate/types.ts +12 -1
  65. package/src/annotate/validate.ts +23 -1
  66. package/src/bridge/bridge.ts +1 -17
  67. package/src/bridge/types.ts +1 -1
  68. package/src/check/page.ts +1 -1
  69. package/src/compile/policy.ts +1 -11
  70. package/src/config/capabilities.ts +8 -14
  71. package/src/config/schema.ts +2 -13
  72. package/src/config/validate.ts +0 -28
  73. package/src/conformance/behavior.ts +50 -52
  74. package/src/conformance/clipboard.ts +56 -1
  75. package/src/displays/displays.ts +1 -3
  76. package/src/guide/limits.ts +1 -1
  77. package/src/guide/runtime.ts +1 -1
  78. package/src/host/create-host.ts +8 -53
  79. package/src/host/door.ts +1 -1
  80. package/src/host/locate.ts +2 -2
  81. package/src/host/outcome.ts +8 -21
  82. package/src/host/types.ts +6 -20
  83. package/src/index.ts +2 -4
  84. package/src/isolation/served.ts +6 -34
  85. package/src/isolation/types.ts +2 -31
  86. package/src/platform/focus-field.ts +18 -0
  87. package/src/platform/types.ts +7 -22
  88. package/src/platform/web.ts +8 -129
  89. package/src/presets/presets.ts +0 -3
  90. package/src/react/frame.tsx +0 -10
  91. package/src/runtime/contract.ts +4 -4
  92. package/src/runtime/types.generated.ts +6 -6
  93. package/src/server/files.ts +4 -19
  94. package/src/server/host.ts +1 -1
  95. package/src/server/index.ts +4 -16
  96. package/src/server/naming.ts +1 -1
  97. package/src/server/server.ts +29 -189
  98. package/src/server/types.ts +7 -7
  99. package/src/shell/annotate.ts +15 -5
  100. package/src/shell/plan.ts +2 -9
  101. package/src/shell/runtime.ts +1 -268
  102. package/types/runtime/v1/artifact.d.ts +2 -3
  103. package/types/runtime/v1/assets.d.ts +1 -1
  104. package/types/runtime/v1/chat.d.ts +2 -2
  105. package/types/runtime/v1/comments.d.ts +1 -1
  106. package/types/runtime/v1/downloads.d.ts +2 -2
  107. package/types/runtime/v1/links.d.ts +2 -2
  108. package/dist/platform/focus-guard.d.ts +0 -288
  109. package/dist/platform/focus-guard.js +0 -838
  110. package/dist/server/nested.d.ts +0 -66
  111. package/dist/server/nested.js +0 -121
  112. package/dist/shell/frame.d.ts +0 -28
  113. package/dist/shell/frame.js +0 -407
  114. package/docs/ARCHITECTURE.md +0 -359
  115. package/docs/OBJECTIVES.md +0 -116
  116. package/src/platform/focus-guard.ts +0 -1114
  117. package/src/server/nested.ts +0 -157
  118. package/src/shell/frame.ts +0 -444
@@ -24,10 +24,8 @@ 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;
29
27
  return presets[kind.preset](source === null
30
- ? opaque
28
+ ? options
31
29
  : { ...options, ...kind.served, isolation: "domain", contentOrigins: [source] });
32
30
  };
33
31
  // Made once each: a page that asks every render gets the same objects.
@@ -139,7 +139,7 @@ export function manualLimits(config, network) {
139
139
  ? `an <iframe> of one of the ${it}'s own files (a relative src) or with srcdoc loads, set before it is added; other iframes, object, embed and frame are removed`
140
140
  : "an <iframe> with srcdoc loads, set before it is added; other iframes, object, embed and frame are removed";
141
141
  add("shell", `document.write and document.open throw; ${frames}; 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)" : ""}.`);
142
- add("storage", config.isolation === "opaque" || config.nested === true
142
+ add("storage", config.isolation === "opaque"
143
143
  ? `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.`
144
144
  : config.storage?.scope !== undefined
145
145
  ? `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.`
@@ -48,7 +48,7 @@ const CALLS = {
48
48
  /** What each host function does, in a phrase, for its line. */
49
49
  const WHAT = {
50
50
  user: () => "who is viewing: { id, name, level }, as the app says",
51
- comments: () => "opens the app's comment composer at a place the page names (a stable name like slide-3 or refs/a.md#L12, a label, the quoted text), optionally starting with a draft (at most 2,000 characters of visible text, lines and tabs fine, no zero-width characters, joiners only between two letters (Persian's or Hindi's are fine; an emoji joined with U+200D is refused; ❤️ is fine), no bidi or tag characters, line or paragraph separators, or runs of blanks; e.g. a button's \"Approved\" or a checklist to fill in); the person edits and posts it in the app, or doesn't. Call it from a click in the page. True if it opened. Write-only: a page never reads comments, and never posts one",
51
+ comments: () => "opens the app's comment composer at a place the page names (a stable name like slide-3 or refs/a.md#L12, a label, the quoted text), optionally starting with a draft (at most 2,000 characters of visible text, lines and tabs fine, no zero-width characters, joiners only between two letters (Persian's or Hindi's are fine; an emoji joined with U+200D is refused; ❤️ is fine), no bidi or tag characters, line or paragraph separators, or runs of blanks; e.g. a button's \"Approved\" or a checklist to fill in); the person edits and posts it in the app, or doesn't. True if it opened. Write-only: a page never reads comments, and never posts one",
52
52
  copyText: () => `copies text to the person's clipboard (at most ${MAX_COPY_CHARS.toLocaleString("en-US")} characters), and the app shows them what was copied; nothing else in the page can write the clipboard. True if copied`,
53
53
  openLink: () => "opens an http(s) link outside the page; a click on an <a href> does the same. True if it opened",
54
54
  downloadFile: () => "hands the person a file to save (<a download> doesn't work here). True if it started",
@@ -10,7 +10,7 @@ export declare const NO_DOOR = "A served display needs a door from issue (FrameL
10
10
  */
11
11
  export declare const REUSED_LOCATION = "The locator gave this run a location an earlier run of this display already used (P125): its tickets are taken, so its door answers that the link has been used. A locator must issue anew for every run (InstanceLocator.locate is called for each one)";
12
12
  /** What the host is told when its platform makes no doors (P125): no served frame is made. */
13
- export declare const NO_DOOR_PLATFORM = "This platform makes no door frames (PlatformHost.createDoor, P125), so no served display that isn't nested is framed on it";
13
+ export declare const NO_DOOR_PLATFORM = "This platform makes no door frames (PlatformHost.createDoor, P125), so no served display is framed on it";
14
14
  /** The most `tracked` reports a second the host takes (P112): one per animation frame at 60 Hz. */
15
15
  export declare const TRACKED_PER_SECOND = 60;
16
16
  /**
@@ -16,7 +16,6 @@ import { watchDoor } from "./door.js";
16
16
  import { outcomeOfRefusal } from "./locator.js";
17
17
  import { STORAGE_USED_METHOD } from "../isolation/types.js";
18
18
  import { webPlatform } from "../platform/web.js";
19
- import { TAKES } from "../platform/focus-guard.js";
20
19
  import { MCP_APPS_STYLE_VARIABLES, PORTHOLE_STYLES, } from "../protocol/mcp-apps.js";
21
20
  import { shellAdapter } from "../protocol/shell-adapter.js";
22
21
  import { resolveTheme } from "../theme/variables.js";
@@ -35,7 +34,7 @@ export const NO_DOOR = "A served display needs a door from issue (FrameLocation.
35
34
  */
36
35
  export const REUSED_LOCATION = "The locator gave this run a location an earlier run of this display already used (P125): its tickets are taken, so its door answers that the link has been used. A locator must issue anew for every run (InstanceLocator.locate is called for each one)";
37
36
  /** What the host is told when its platform makes no doors (P125): no served frame is made. */
38
- export const NO_DOOR_PLATFORM = "This platform makes no door frames (PlatformHost.createDoor, P125), so no served display that isn't nested is framed on it";
37
+ export const NO_DOOR_PLATFORM = "This platform makes no door frames (PlatformHost.createDoor, P125), so no served display is framed on it";
39
38
  const BASE_KEYS = new Set(["hostContextChanged", "teardown", "close"]);
40
39
  /** The frame's annotation reports, by method. */
41
40
  const REPORTS = {
@@ -68,10 +67,9 @@ export function createHost(config, options = {}) {
68
67
  }
69
68
  // A url frame is someone else's app: no shell, no protocol, and its navigations are its own.
70
69
  const speaks = config.mode !== "url";
71
- const nested = config.nested === true;
72
70
  // A served display on its scope's origin, beside the scope's other content (P125): its door
73
71
  // says how loading went, before its frame is made.
74
- const hasDoor = config.isolation === "domain" && speaks && !nested;
72
+ const hasDoor = config.isolation === "domain" && speaks;
75
73
  const adapter = (options.adapter ?? shellAdapter);
76
74
  const platform = options.platform ?? webPlatform;
77
75
  const hostInfo = options.hostInfo ?? { name: "porthole", version: "0" };
@@ -306,24 +304,12 @@ export function createHost(config, options = {}) {
306
304
  return undefined;
307
305
  }
308
306
  };
309
- /**
310
- * Whether the person is known to have made no gesture just now (P105): the platform says the
311
- * page has no transient activation, or fails to say. Where it can't tell (undefined), as for
312
- * the gesture gate, a report passes.
313
- */
314
- const noGesture = () => {
315
- try {
316
- return surface?.userActivation() === false;
317
- }
318
- catch {
319
- return true;
320
- }
321
- };
322
307
  /**
323
308
  * Every box a report carries, clamped to the frame's viewport as it is now (P104): the page
324
309
  * places the host's own UI nowhere outside its frame. A mark's `documentRect` and the
325
310
  * document's `scroll` (P132) pass as they were checked: where a mark is in the document,
326
- * offscreen too, which a clamp would erase; the host clips what it draws from them.
311
+ * offscreen too, which a clamp would erase; the host clips what it draws from them. So does a
312
+ * pick's `pointDocument` (P150).
327
313
  */
328
314
  const withinFrame = (report) => {
329
315
  const viewport = frameViewport();
@@ -356,7 +342,10 @@ export function createHost(config, options = {}) {
356
342
  /**
357
343
  * A report from the frame: checked, taken only while the host asked for it (a selection
358
344
  * only in select mode, results only for its own marks, a marker's click only for a mark it
359
- * shows with one, a count's or a draft's, within a gesture), then through the bridge's gates.
345
+ * shows with one, a count's or a draft's), then through the bridge's gates. No proof of a
346
+ * gesture is asked of a marker's click (0.16.0, P149): what a host opens for one takes no
347
+ * focus and does nothing by itself (THREAT_MODEL §6), and a page that says it unasked only
348
+ * shows that.
360
349
  */
361
350
  const onAnnotation = (raw, through) => {
362
351
  if (!isRecord(raw) ||
@@ -456,13 +445,6 @@ export function createHost(config, options = {}) {
456
445
  if (!marks.some((mark) => mark.id === id && hasMarker(mark))) {
457
446
  return;
458
447
  }
459
- // A marker's real click gives the host's page transient activation (measured on all
460
- // three engines, P105); a click a page posts at load, on a timer or on a scroll has
461
- // none and is dropped. One posted on the person's own press in the content passes: the
462
- // host's view guards itself against that (THREAT_MODEL §6).
463
- if (noGesture()) {
464
- return;
465
- }
466
448
  break;
467
449
  }
468
450
  }
@@ -816,8 +798,6 @@ export function createHost(config, options = {}) {
816
798
  allow: compiled.allow,
817
799
  referrerPolicy: compiled.referrerPolicy,
818
800
  colorScheme: scheme,
819
- // A nested page's shell (P111): the config's word, never the frame's.
820
- ...(config.nested === true ? { nested: true } : {}),
821
801
  // An app reports no size: its frame fills the host's container, at least the minimum;
822
802
  // so does any display the host mounts to fill, or whose layout fills (P065): its
823
803
  // content scrolls itself.
@@ -844,32 +824,10 @@ export function createHost(config, options = {}) {
844
824
  })
845
825
  : framed;
846
826
  surface = created;
847
- // The focus guard undid a move of the keyboard into this frame (P109): heard each time,
848
- // and a frame that keeps taking it is stopped, as one that keeps navigating away is.
849
- const takes = [];
850
- created.onFocusTaken?.(({ typing, failed }) => {
851
- const at = Date.now();
852
- // While the person typed, or a take-back that failed (the keys then go to the frame and
853
- // the page sees no typing): either counts toward the first rule.
854
- takes.push({ at, counts: typing || failed });
855
- const within = (ms) => takes.filter((take) => at - take.at <= ms);
856
- emit("focusTaken", { typing });
857
- if (surface === created &&
858
- (within(TAKES.typing.withinMs).filter((take) => take.counts).length >=
859
- TAKES.typing.most ||
860
- within(TAKES.any.withinMs).length >= TAKES.any.most)) {
861
- stop();
862
- contentError("The content kept taking the keyboard from the page; it was stopped.");
863
- }
864
- while (takes.length > 0 && at - takes[0].at > TAKES.typing.withinMs) {
865
- takes.shift();
866
- }
867
- });
868
827
  const watch = watchOutcome({
869
828
  surface: created,
870
829
  source,
871
830
  speaks,
872
- nested,
873
831
  timeoutMs: timeLeft,
874
832
  onOutcome: (outcome) => emit("outcome", outcome),
875
833
  // A frame status from the content (P124): never shown, the host's to hear.
@@ -902,8 +860,6 @@ export function createHost(config, options = {}) {
902
860
  ...(options.show === undefined ? {} : { show: options.show }),
903
861
  ...(options.cached === undefined ? {} : { cached: options.cached }),
904
862
  userActivation: () => created.userActivation(),
905
- // The person in this frame (P109): the page's focus in it, after the focus guard.
906
- focused: () => created.focused?.(),
907
863
  onEvent: onBridge,
908
864
  ...(declaration === null ? {} : { declaration }),
909
865
  ...(viewer === undefined ? {} : { viewer }),
@@ -1,7 +1,7 @@
1
1
  import type { DoorSurface } from "../platform/types.ts";
2
2
  import type { FrameOutcome } from "./types.ts";
3
3
  /**
4
- * A served display's door (P125). A served display that isn't nested (a served shell, a page, a
4
+ * A served display's door (P125). A served display (a served shell, a page, a
5
5
  * view through the sandbox proxy) is framed on its scope's origin, where the scope's other displays
6
6
  * run content with `allow-same-origin`: one of them reaches a new document there before its first
7
7
  * script runs, so nothing its frame says, and nothing its silence suggests, is Porthole's word.
@@ -3,6 +3,6 @@ import type { FrameSource, InstanceLocator, InstanceRef } from "../isolation/typ
3
3
  /**
4
4
  * Where a served frame (domain or external isolation) loads from: the host's locator answers, and
5
5
  * `checkFrameLocation` checks the answer (one of the config's content origins, never the host's
6
- * own site; a nested page's on a shell's own label, P121) before any frame is made.
6
+ * own site) before any frame is made.
7
7
  */
8
8
  export declare function locateServed(locator: InstanceLocator, instance: InstanceRef, config: PortholeConfig, hostOrigin: string, signal?: AbortSignal): Promise<FrameSource>;
@@ -3,11 +3,11 @@ import { parseViewer } from "../runtime/levels.js";
3
3
  /**
4
4
  * Where a served frame (domain or external isolation) loads from: the host's locator answers, and
5
5
  * `checkFrameLocation` checks the answer (one of the config's content origins, never the host's
6
- * own site; a nested page's on a shell's own label, P121) before any frame is made.
6
+ * own site) before any frame is made.
7
7
  */
8
8
  export async function locateServed(locator, instance, config, hostOrigin, signal) {
9
9
  const location = await locator.locate(instance, signal);
10
- checkFrameLocation(location, config.contentOrigins, hostOrigin, config.nested === true);
10
+ checkFrameLocation(location, config.contentOrigins, hostOrigin);
11
11
  // The host's access, as its backend answered (P087): a viewer that doesn't parse is the host's
12
12
  // error, never no viewer (after the review: a mount's own would take its place).
13
13
  const viewer = location.viewer === undefined ? null : parseViewer(location.viewer);
@@ -23,10 +23,9 @@ import type { FrameBlock, FrameOutcome } from "./types.ts";
23
23
  *
24
24
  * - An opaque frame's only document is the host's own shell, with the content in it: no page of
25
25
  * Porthole's server ever loads there, so its every frame status is the content's.
26
- * - A frame that speaks (a served shell, a view through the sandbox proxy, a nested page's shell)
26
+ * - A frame that speaks (a served shell, a view through the sandbox proxy)
27
27
  * says Porthole's own word first in every document that holds content, before any of the
28
- * content's code runs: the shell's hello, the proxy's ready (a nested page's own runtime's hello
29
- * reaches the host before anything its page says, through its shell). A status page says
28
+ * content's code runs: the shell's hello, the proxy's ready. A status page says
30
29
  * nothing but its frame status. So a frame status is taken only before anything else was heard
31
30
  * from the frame in this run: from its first document, which then was a page of Porthole's.
32
31
  * After that, it came from the content (or from a later document, which in a display without
@@ -34,9 +33,9 @@ import type { FrameBlock, FrameOutcome } from "./types.ts";
34
33
  * That holds against the display's own content, not against another display's (P125): a
35
34
  * scope's displays share its origin, and one that runs reaches a new document of another's
36
35
  * before that document's first script, where it can speak first, or stop or rewrite it so it
37
- * says nothing. So the rule holds only where no content runs on the frame's origin: a nested
38
- * page's shell, on a label of its own (P114).
39
- * - A served display that isn't nested (a served shell, a page, a view through the sandbox proxy)
36
+ * says nothing. So the rule holds only where no content runs on the frame's origin, and no
37
+ * served frame is such a place (the nested shell that was, P114, went in 0.16.0: P149).
38
+ * - A served display (a served shell, a page, a view through the sandbox proxy)
40
39
  * takes no frame status from its frame at all, and infers nothing from its silence (a load and
41
40
  * no word is a timeout, never `framing`): its door said how loading went before the frame was
42
41
  * made (P125, `watchDoor`), from an opaque frame of the host's that no content can reach.
@@ -68,12 +67,6 @@ export declare function watchOutcome(options: {
68
67
  readonly source: FrameSource;
69
68
  /** Whether the frame speaks for itself (a shell or a view): then its handshake is the proof. */
70
69
  readonly speaks: boolean;
71
- /**
72
- * The config nests its pages (P111): the frame holds Porthole's shell, on a label no content
73
- * runs on, whose first word may be a frame status. Any other served frame that speaks takes
74
- * none: its door told (P125).
75
- */
76
- readonly nested?: boolean;
77
70
  readonly timeoutMs: number;
78
71
  readonly onOutcome: (outcome: FrameOutcome) => void;
79
72
  /** A frame status that wasn't taken, once a run (P124): the host's to hear, never shown. */
@@ -21,10 +21,9 @@ import { FRAME_STATUS_METHOD } from "../isolation/types.js";
21
21
  *
22
22
  * - An opaque frame's only document is the host's own shell, with the content in it: no page of
23
23
  * Porthole's server ever loads there, so its every frame status is the content's.
24
- * - A frame that speaks (a served shell, a view through the sandbox proxy, a nested page's shell)
24
+ * - A frame that speaks (a served shell, a view through the sandbox proxy)
25
25
  * says Porthole's own word first in every document that holds content, before any of the
26
- * content's code runs: the shell's hello, the proxy's ready (a nested page's own runtime's hello
27
- * reaches the host before anything its page says, through its shell). A status page says
26
+ * content's code runs: the shell's hello, the proxy's ready. A status page says
28
27
  * nothing but its frame status. So a frame status is taken only before anything else was heard
29
28
  * from the frame in this run: from its first document, which then was a page of Porthole's.
30
29
  * After that, it came from the content (or from a later document, which in a display without
@@ -32,9 +31,9 @@ import { FRAME_STATUS_METHOD } from "../isolation/types.js";
32
31
  * That holds against the display's own content, not against another display's (P125): a
33
32
  * scope's displays share its origin, and one that runs reaches a new document of another's
34
33
  * before that document's first script, where it can speak first, or stop or rewrite it so it
35
- * says nothing. So the rule holds only where no content runs on the frame's origin: a nested
36
- * page's shell, on a label of its own (P114).
37
- * - A served display that isn't nested (a served shell, a page, a view through the sandbox proxy)
34
+ * says nothing. So the rule holds only where no content runs on the frame's origin, and no
35
+ * served frame is such a place (the nested shell that was, P114, went in 0.16.0: P149).
36
+ * - A served display (a served shell, a page, a view through the sandbox proxy)
38
37
  * takes no frame status from its frame at all, and infers nothing from its silence (a load and
39
38
  * no word is a timeout, never `framing`): its door said how loading went before the frame was
40
39
  * made (P125, `watchDoor`), from an opaque frame of the host's that no content can reach.
@@ -96,7 +95,6 @@ const namesFrameStatus = (data) => data !== null &&
96
95
  export const UNTRUSTED_FRAME_STATUS = "A frame status (porthole/notifications/frame-status) came from the frame's content, not from a page of Porthole's server: not taken (P124)";
97
96
  export function watchOutcome(options) {
98
97
  const { surface, source, speaks } = options;
99
- const nested = options.nested === true;
100
98
  const reports = source.kind === "url" && source.reports === true;
101
99
  // The first outcome; after a load, only a later block (a status page, access revoked) is told.
102
100
  let decided = null;
@@ -137,7 +135,7 @@ export function watchOutcome(options) {
137
135
  }
138
136
  };
139
137
  // Whether a frame status may be the word of a page of Porthole's (P124, P125, above).
140
- const mayBePorthole = () => source.kind === "url" && (!speaks || (nested && !spoke));
138
+ const mayBePorthole = () => source.kind === "url" && !speaks;
141
139
  const unlisten = surface.transport.listen((data) => {
142
140
  heard = true;
143
141
  if (!namesFrameStatus(data)) {
@@ -184,16 +182,10 @@ export function watchOutcome(options) {
184
182
  return;
185
183
  }
186
184
  if (speaks) {
187
- // A served shell or view says something before its first load ends; a nested page's shell
188
- // that never did never ran. Any other served frame's silence tells nothing (P125). (An
185
+ // A served frame's silence tells nothing (P125): its door said how loading went. (An
189
186
  // opaque srcdoc frame always runs: its handshake decides.)
190
187
  if (source.kind === "url") {
191
- if (nested) {
192
- neverRan();
193
- }
194
- else {
195
- silent();
196
- }
188
+ silent();
197
189
  }
198
190
  return;
199
191
  }
@@ -124,12 +124,12 @@ export type HostErrorKind =
124
124
  /**
125
125
  * A frame status (`porthole/notifications/frame-status`) the host didn't take, since it came
126
126
  * from the frame's content, not from a page of Porthole's server (P124): never shown, never an
127
- * outcome. Told once a run. A served display that isn't nested takes none from its frame at
127
+ * outcome. Told once a run. A served display takes none from its frame at
128
128
  * all: its door says how loading went (P125).
129
129
  */
130
130
  | "frame-status"
131
131
  /**
132
- * A served display that has a door (P125: a served shell, a page that isn't nested, the sandbox
132
+ * A served display that has a door (P125: a served shell, a page, the sandbox
133
133
  * proxy) was located without one: the server is older than the host (upgrade it first), or a
134
134
  * locator dropped `FrameLocation.door`. The display shows, but no frame status is taken, so a
135
135
  * block is told as a timeout. Told once a mount.
@@ -224,19 +224,9 @@ export interface DisplayEvents {
224
224
  };
225
225
  /** Too many declines: the display stops asking until it runs again. */
226
226
  readonly muted: undefined;
227
- /**
228
- * The content moved the keyboard into its frame from one of the page's text fields without the
229
- * person (no press on the frame, no Tab, P109), and focus went back where it was; `typing`: the
230
- * person had pressed a key on the page within the last second. The content's doing. Three while
231
- * typing within 10 s, or five within 2 s, stop the display (`contentError` says so; `reload()`
232
- * runs it again).
233
- */
234
- readonly focusTaken: {
235
- readonly typing: boolean;
236
- };
237
227
  /**
238
228
  * Whether the page touched `localStorage` or `sessionStorage` (the in-memory stand-in of a frame
239
- * without storage of its own: opaque, or a nested page, P111): once per run, `used: true` when
229
+ * without storage of its own: an opaque one): once per run, `used: true` when
240
230
  * the page first did, else `used: false` as the run ends. Never what it kept: for a host to count
241
231
  * the pages that would need storage.
242
232
  */
@@ -353,9 +343,7 @@ export interface AnnotationControls {
353
343
  * comes of it. Nothing happens, and nothing throws, for an id no mark with a marker is shown
354
344
  * under, or if the frame has no such marker now (its words are gone, elements are being picked):
355
345
  * the display's own `focus()` isn't used, so the frame takes no focus for a marker it hasn't got.
356
- * Call it once the view is closed: from one of the page's text fields that still has focus, the
357
- * move is the frame's own to the focus guard, undone and counted (P109). The page can take the
358
- * focus back at once. Not kept for a frame that runs later.
346
+ * The page can take the focus back at once. Not kept for a frame that runs later.
359
347
  *
360
348
  * On a calm page it lands at once, from anywhere on the host's page. While the frame is finding
361
349
  * its marks (a `show` just sent, the content just changed) it waits, and is then dropped unless
@@ -363,8 +351,7 @@ export interface AnnotationControls {
363
351
  * it (its page is busy) is held to the same test (P137), so a word that comes late takes no
364
352
  * keyboard from a person who moved on. Nothing says it was dropped: if the frame isn't your page's
365
353
  * `document.activeElement` soon after and the person hasn't moved on, call `focus()` and then
366
- * `focusMark(id)` again. On a nested page only `focus()` reaches the page (P136): the frame's own
367
- * `focus()` stops at its shell, and a second call that waits is dropped.
354
+ * `focusMark(id)` again.
368
355
  */
369
356
  focusMark(id: string): void;
370
357
  }
@@ -384,10 +371,7 @@ export interface DisplayControls {
384
371
  readonly find: FindControls;
385
372
  /** Runs the content again from the start, in a new frame. */
386
373
  reload(): void;
387
- /**
388
- * Moves focus into the display's frame, as the host's own move: from one of the page's text
389
- * fields, a frame's own `focus()` is taken for the content's and undone (P109).
390
- */
374
+ /** Moves focus into the display's frame. */
391
375
  focus(): void;
392
376
  /** Tears the view down and removes the frame. */
393
377
  destroy(): void;
package/dist/index.d.ts CHANGED
@@ -9,9 +9,7 @@ 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, 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";
12
+ export { FRAME_STATUS_METHOD, STORAGE_USED_METHOD } from "./isolation/types.ts";
15
13
  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";
16
14
  export { VIEWER_LEVELS, atLeast, isViewerLevel, parseViewer, type ViewerInfo, type ViewerLevel, } from "./runtime/levels.ts";
17
15
  export { checkDeclaration, declarationProblems, declareCapabilities, declaredMatch, intersectDeclarations, tryIntersectDeclarations, type CapabilityDeclaration, type DeclarationProblem, type DeclaredCapability, type DeclaredData, type DeclaredDb, type PageDeclaration, } from "./runtime/declaration.ts";
@@ -38,7 +36,7 @@ export { REFUSAL_CODES, Refused, isRefused, type RefusalCode, type RefusalReason
38
36
  export type { CallContext, CallOptions, CallOutcome, CapabilityHandler, CapabilityHandlers, Confirm, ConfirmAnswer, ConfirmDisplay, ConfirmRequest, Consent, DataCache, Proceed, HostFunctionBridge, Refusal, Show, SubscriptionContext, DbContext, } from "./bridge/types.ts";
39
37
  export { createHost } from "./host/create-host.ts";
40
38
  export { mayPassOn } from "./host/pass-on.ts";
41
- export { focusField } from "./platform/focus-guard.ts";
39
+ export { focusField } from "./platform/focus-field.ts";
42
40
  export { entryTarget, frameFallback, portholeClient, type ContentClientMeta, type FrameFallback, type PortholeClient, type PortholeClientOptions, } from "./host/client.ts";
43
41
  export { defineDisplays, type DisplayKind, type Displays } from "./displays/displays.ts";
44
42
  export { fragmentOf, lintContent, type Finding, type LintRule } from "./check/lint.ts";
package/dist/index.js CHANGED
@@ -9,9 +9,7 @@ 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, 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";
12
+ export { FRAME_STATUS_METHOD, STORAGE_USED_METHOD } from "./isolation/types.js";
15
13
  // The capability runtime (P085-P090): its contract, levels, a page's declaration, its services'
16
14
  // shapes. Hosts implement the services; Porthole carries, checks and gates the calls.
17
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, } from "./runtime/contract.js";
@@ -39,7 +37,7 @@ export { COPY_TEXT_METHOD, MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS
39
37
  export { REFUSAL_CODES, Refused, isRefused, } from "./bridge/refusal.js";
40
38
  export { createHost } from "./host/create-host.js";
41
39
  export { mayPassOn } from "./host/pass-on.js";
42
- export { focusField } from "./platform/focus-guard.js";
40
+ export { focusField } from "./platform/focus-field.js";
43
41
  // The client half of the host kit, and the display registry (P072).
44
42
  export { entryTarget, frameFallback, portholeClient, } from "./host/client.js";
45
43
  export { defineDisplays } from "./displays/displays.js";
@@ -7,19 +7,11 @@ interface ParsedOrigin {
7
7
  /** `scheme://host[:port]`, lowercase, nothing else; null for anything that isn't exactly that. */
8
8
  export declare function parseOrigin(origin: string): ParsedOrigin | null;
9
9
  /**
10
- * The start of every label Porthole serves for itself on a content domain (P114): no host's naming
11
- * may make one (`content.name` is refused one, and `prefixedName` won't take the prefix).
10
+ * The start of every label Porthole keeps for itself on a content domain (its health label;
11
+ * until 0.16.0 a nested page's shell's, P114): no host's naming may make one (`content.name` is
12
+ * refused one, and `prefixedName` won't take the prefix), and no display is served on one.
12
13
  */
13
14
  export declare const PORTHOLE_LABEL_PREFIX = "porthole-";
14
- /** Whether a label is a nested page's shell's own (P114, `nestedLabelOf`'s form). */
15
- export declare const isNestedLabel: (label: string) => boolean;
16
- /**
17
- * Whether `origin` is on a nested page's shell's own label (P114): its host's first label is one.
18
- * The shell runs nowhere else (P121): the host's mount, the shell itself and `/server`'s helpers
19
- * each refuse any other origin, so a content Worker of a host's own can't put it beside other
20
- * content by mistake.
21
- */
22
- export declare function onNestedLabel(origin: string): boolean;
23
15
  /** Whether `origin` is an exact origin (`https://host[:port]`, lowercase, no path). */
24
16
  export declare function isExactOrigin(origin: unknown): origin is string;
25
17
  /**
@@ -68,7 +60,5 @@ export declare function originMatchesSource(origin: string, source: string): boo
68
60
  * names, and it is not of the host's own site (a same-site frame with `allow-same-origin` could
69
61
  * reach cookies and storage the host shares with its site).
70
62
  */
71
- export declare function checkFrameLocation(location: FrameLocation, contentOrigins: readonly string[], hostOrigin: string,
72
- /** The config nests its pages (P111): the location must be on a shell's own label (P121). */
73
- nested?: boolean): void;
63
+ export declare function checkFrameLocation(location: FrameLocation, contentOrigins: readonly string[], hostOrigin: string): void;
74
64
  export {};
@@ -17,23 +17,11 @@ export function parseOrigin(origin) {
17
17
  return { scheme, host, port: port ?? DEFAULT_PORTS[scheme] ?? "" };
18
18
  }
19
19
  /**
20
- * The start of every label Porthole serves for itself on a content domain (P114): no host's naming
21
- * may make one (`content.name` is refused one, and `prefixedName` won't take the prefix).
20
+ * The start of every label Porthole keeps for itself on a content domain (its health label;
21
+ * until 0.16.0 a nested page's shell's, P114): no host's naming may make one (`content.name` is
22
+ * refused one, and `prefixedName` won't take the prefix), and no display is served on one.
22
23
  */
23
24
  export const PORTHOLE_LABEL_PREFIX = "porthole-";
24
- const NESTED_LABEL = /^porthole-[a-z2-7]{24}$/u;
25
- /** Whether a label is a nested page's shell's own (P114, `nestedLabelOf`'s form). */
26
- export const isNestedLabel = (label) => NESTED_LABEL.test(label);
27
- /**
28
- * Whether `origin` is on a nested page's shell's own label (P114): its host's first label is one.
29
- * The shell runs nowhere else (P121): the host's mount, the shell itself and `/server`'s helpers
30
- * each refuse any other origin, so a content Worker of a host's own can't put it beside other
31
- * content by mistake.
32
- */
33
- export function onNestedLabel(origin) {
34
- const parsed = parseOrigin(origin);
35
- return parsed !== null && isNestedLabel(parsed.host.split(".")[0] ?? "");
36
- }
37
25
  /** Whether `origin` is an exact origin (`https://host[:port]`, lowercase, no path). */
38
26
  export function isExactOrigin(origin) {
39
27
  return typeof origin === "string" && parseOrigin(origin) !== null;
@@ -191,9 +179,7 @@ export function originMatchesSource(origin, source) {
191
179
  * names, and it is not of the host's own site (a same-site frame with `allow-same-origin` could
192
180
  * reach cookies and storage the host shares with its site).
193
181
  */
194
- export function checkFrameLocation(location, contentOrigins, hostOrigin,
195
- /** The config nests its pages (P111): the location must be on a shell's own label (P121). */
196
- nested = false) {
182
+ export function checkFrameLocation(location, contentOrigins, hostOrigin) {
197
183
  const origin = parseOrigin(location.origin);
198
184
  let url;
199
185
  try {
@@ -210,11 +196,8 @@ nested = false) {
210
196
  if (!contentOrigins.some((source) => originMatchesSource(location.origin, source))) {
211
197
  throw new TypeError(`The located origin ${location.origin} is not one of the config's content origins`);
212
198
  }
213
- if (nested && !onNestedLabel(location.origin)) {
214
- throw new TypeError(`The located origin ${location.origin} isn't a nested page's own: its shell is served on a label of its own alone (${PORTHOLE_LABEL_PREFIX}<24 base32>, nestedLabelOf(label), P114), never beside other content`);
215
- }
216
199
  if (location.door !== undefined) {
217
- checkDoor(location.door, location.origin, nested);
200
+ checkDoor(location.door, location.origin);
218
201
  }
219
202
  const host = parseOrigin(hostOrigin);
220
203
  if (host !== null && maybeSameSite(origin.host, host.host)) {
@@ -222,18 +205,14 @@ nested = false) {
222
205
  }
223
206
  }
224
207
  /**
225
- * A location's door (P125): on the location's own origin, at Porthole's door path, never for a
226
- * nested page (its shell's label serves no door: its first document is Porthole's own, P114).
208
+ * A location's door (P125): on the location's own origin, at Porthole's door path.
227
209
  * Named by its origin only in what is thrown: the door's address carries a ticket.
228
210
  */
229
- function checkDoor(door, origin, nested) {
211
+ function checkDoor(door, origin) {
230
212
  const url = door !== null && typeof door === "object" ? door.url : undefined;
231
213
  if (typeof url !== "string") {
232
214
  throw new TypeError("The located door is not { url }");
233
215
  }
234
- if (nested) {
235
- throw new TypeError("A nested page is located with no door: its shell is Porthole's own first document (P125)");
236
- }
237
216
  let parsed;
238
217
  try {
239
218
  parsed = new URL(url);
@@ -80,8 +80,8 @@ export interface FrameLocation {
80
80
  * The display's door (P125): a page of Porthole's on the same origin, at
81
81
  * `/__porthole/door/<instance key>?ticket=<its own ticket>`, that says how loading went before
82
82
  * any content is framed. The host frames it opaque and hidden, and takes its one frame status
83
- * (`open`, or `blocked` and why); then frames `url`. Given for a served shell, a page that isn't
84
- * nested and the sandbox proxy: content of the scope runs on their origin, so no frame status
83
+ * (`open`, or `blocked` and why); then frames `url`. Given for a served shell, a page and the
84
+ * sandbox proxy: content of the scope runs on their origin, so no frame status
85
85
  * from their own frame is ever Porthole's. A host that is given none for one of them takes no
86
86
  * frame status at all (a load that shows nothing is a timeout) and says so (`hostError` kind
87
87
  * `door`). A custom locator passes it on as it came.
@@ -94,29 +94,6 @@ export interface FrameLocation {
94
94
  export declare const DOOR_PATH = "/__porthole/door/";
95
95
  /** The message a served page sends its host about loading (own-prefixed, P040). */
96
96
  export declare const FRAME_STATUS_METHOD = "porthole/notifications/frame-status";
97
- /** A nested page's shell's report of its own state to the host (P111). */
98
- export declare const SHELL_STATE_METHOD = "porthole/shell/state";
99
- /** A nested page's shell's heartbeat, every 50 ms while it runs (P111, after its review). */
100
- export declare const SHELL_BEAT_METHOD = "porthole/shell/beat";
101
- /**
102
- * The host's ask to a nested page's shell (P120): look now, and say what it saw in a state report
103
- * that names the ask (`asked`). The host asks as it hears focus move into the frame.
104
- */
105
- export declare const SHELL_LOOK_METHOD = "porthole/shell/look";
106
- /**
107
- * The host's word to a nested page's shell (P136) that it moved the focus into the frame: pass it on
108
- * to the page, in this task, not in the focus event (where the shell's move doesn't take). Sent by
109
- * `display.focus()` alone; a page has no way to say it.
110
- */
111
- export declare const SHELL_FOCUS_METHOD = "porthole/shell/focus";
112
- /**
113
- * A nested page's shell's word to its page's runtime (P148): one `MessagePort`, sent at each load
114
- * of the page's frame, over which the runtime tells the shell each real press in the page. The
115
- * runtime takes the first one alone, before any content runs, and no content ever holds it.
116
- */
117
- export declare const SHELL_PRESS_PORT_METHOD = "porthole/shell/press-port";
118
- /** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
119
- export declare const SHELL_METHOD_PREFIX = "porthole/shell/";
120
97
  /** A page's word that it used storage, once per load (P111): never a key or a value. */
121
98
  export declare const STORAGE_USED_METHOD = "porthole/storage-used";
122
99
  /**
@@ -2,28 +2,5 @@
2
2
  export const DOOR_PATH = "/__porthole/door/";
3
3
  /** The message a served page sends its host about loading (own-prefixed, P040). */
4
4
  export const FRAME_STATUS_METHOD = "porthole/notifications/frame-status";
5
- /** A nested page's shell's report of its own state to the host (P111). */
6
- export const SHELL_STATE_METHOD = "porthole/shell/state";
7
- /** A nested page's shell's heartbeat, every 50 ms while it runs (P111, after its review). */
8
- export const SHELL_BEAT_METHOD = "porthole/shell/beat";
9
- /**
10
- * The host's ask to a nested page's shell (P120): look now, and say what it saw in a state report
11
- * that names the ask (`asked`). The host asks as it hears focus move into the frame.
12
- */
13
- export const SHELL_LOOK_METHOD = "porthole/shell/look";
14
- /**
15
- * The host's word to a nested page's shell (P136) that it moved the focus into the frame: pass it on
16
- * to the page, in this task, not in the focus event (where the shell's move doesn't take). Sent by
17
- * `display.focus()` alone; a page has no way to say it.
18
- */
19
- export const SHELL_FOCUS_METHOD = "porthole/shell/focus";
20
- /**
21
- * A nested page's shell's word to its page's runtime (P148): one `MessagePort`, sent at each load
22
- * of the page's frame, over which the runtime tells the shell each real press in the page. The
23
- * runtime takes the first one alone, before any content runs, and no content ever holds it.
24
- */
25
- export const SHELL_PRESS_PORT_METHOD = "porthole/shell/press-port";
26
- /** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
27
- export const SHELL_METHOD_PREFIX = "porthole/shell/";
28
5
  /** A page's word that it used storage, once per load (P111): never a key or a value. */
29
6
  export const STORAGE_USED_METHOD = "porthole/storage-used";
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Moves focus into one of the host page's own text fields (a composer that opens beside a
3
+ * display): `field.focus()` for a host to call instead. Firefox doesn't move focus out of a frame
4
+ * that holds it with a gesture of the person's, and takes it back on its own blur (measured: the
5
+ * keys then go on to the frame); so where a frame of the page holds the focus, it is blurred
6
+ * first. Elsewhere it is `field.focus()`.
7
+ *
8
+ * Nothing watches what happens next: until 0.16.0 a focus guard did, and counted a frame that
9
+ * took the focus back toward stopping its display (P109, removed by P149).
10
+ */
11
+ export declare function focusField(field: HTMLElement): void;