@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
@@ -32,7 +32,6 @@ import { watchDoor, type DoorWatch } from "./door.ts";
32
32
  import { outcomeOfRefusal } from "./locator.ts";
33
33
  import { STORAGE_USED_METHOD, type FrameSource } from "../isolation/types.ts";
34
34
  import { webPlatform } from "../platform/web.ts";
35
- import { TAKES } from "../platform/focus-guard.ts";
36
35
  import type { DoorSurface, Surface } from "../platform/types.ts";
37
36
  import type { AdapterConnection, ProtocolAdapter, ShellConnection } from "../protocol/adapter.ts";
38
37
  import {
@@ -75,7 +74,7 @@ export const REUSED_LOCATION =
75
74
 
76
75
  /** What the host is told when its platform makes no doors (P125): no served frame is made. */
77
76
  export const NO_DOOR_PLATFORM =
78
- "This platform makes no door frames (PlatformHost.createDoor, P125), so no served display that isn't nested is framed on it";
77
+ "This platform makes no door frames (PlatformHost.createDoor, P125), so no served display is framed on it";
79
78
 
80
79
  const BASE_KEYS = new Set(["hostContextChanged", "teardown", "close"]);
81
80
 
@@ -120,10 +119,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
120
119
  }
121
120
  // A url frame is someone else's app: no shell, no protocol, and its navigations are its own.
122
121
  const speaks = config.mode !== "url";
123
- const nested = config.nested === true;
124
122
  // A served display on its scope's origin, beside the scope's other content (P125): its door
125
123
  // says how loading went, before its frame is made.
126
- const hasDoor = config.isolation === "domain" && speaks && !nested;
124
+ const hasDoor = config.isolation === "domain" && speaks;
127
125
  const adapter = (options.adapter ?? shellAdapter) as ProtocolAdapter<C>;
128
126
  const platform = options.platform ?? webPlatform;
129
127
  const hostInfo = options.hostInfo ?? { name: "porthole", version: "0" };
@@ -381,23 +379,12 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
381
379
  return undefined;
382
380
  }
383
381
  };
384
- /**
385
- * Whether the person is known to have made no gesture just now (P105): the platform says the
386
- * page has no transient activation, or fails to say. Where it can't tell (undefined), as for
387
- * the gesture gate, a report passes.
388
- */
389
- const noGesture = (): boolean => {
390
- try {
391
- return surface?.userActivation() === false;
392
- } catch {
393
- return true;
394
- }
395
- };
396
382
  /**
397
383
  * Every box a report carries, clamped to the frame's viewport as it is now (P104): the page
398
384
  * places the host's own UI nowhere outside its frame. A mark's `documentRect` and the
399
385
  * document's `scroll` (P132) pass as they were checked: where a mark is in the document,
400
- * offscreen too, which a clamp would erase; the host clips what it draws from them.
386
+ * offscreen too, which a clamp would erase; the host clips what it draws from them. So does a
387
+ * pick's `pointDocument` (P150).
401
388
  */
402
389
  const withinFrame = (report: AnnotationReport): AnnotationReport => {
403
390
  const viewport = frameViewport();
@@ -432,7 +419,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
432
419
  /**
433
420
  * A report from the frame: checked, taken only while the host asked for it (a selection
434
421
  * only in select mode, results only for its own marks, a marker's click only for a mark it
435
- * shows with one, a count's or a draft's, within a gesture), then through the bridge's gates.
422
+ * shows with one, a count's or a draft's), then through the bridge's gates. No proof of a
423
+ * gesture is asked of a marker's click (0.16.0, P149): what a host opens for one takes no
424
+ * focus and does nothing by itself (THREAT_MODEL §6), and a page that says it unasked only
425
+ * shows that.
436
426
  */
437
427
  const onAnnotation = (raw: unknown, through: HostFunctionBridge) => {
438
428
  if (
@@ -536,13 +526,6 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
536
526
  if (!marks.some((mark) => mark.id === id && hasMarker(mark))) {
537
527
  return;
538
528
  }
539
- // A marker's real click gives the host's page transient activation (measured on all
540
- // three engines, P105); a click a page posts at load, on a timer or on a scroll has
541
- // none and is dropped. One posted on the person's own press in the content passes: the
542
- // host's view guards itself against that (THREAT_MODEL §6).
543
- if (noGesture()) {
544
- return;
545
- }
546
529
  break;
547
530
  }
548
531
  }
@@ -910,8 +893,6 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
910
893
  allow: compiled.allow,
911
894
  referrerPolicy: compiled.referrerPolicy,
912
895
  colorScheme: scheme,
913
- // A nested page's shell (P111): the config's word, never the frame's.
914
- ...(config.nested === true ? { nested: true } : {}),
915
896
  // An app reports no size: its frame fills the host's container, at least the minimum;
916
897
  // so does any display the host mounts to fill, or whose layout fills (P065): its
917
898
  // content scrolls itself.
@@ -939,34 +920,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
939
920
  })
940
921
  : framed;
941
922
  surface = created;
942
- // The focus guard undid a move of the keyboard into this frame (P109): heard each time,
943
- // and a frame that keeps taking it is stopped, as one that keeps navigating away is.
944
- const takes: { at: number; counts: boolean }[] = [];
945
- created.onFocusTaken?.(({ typing, failed }) => {
946
- const at = Date.now();
947
- // While the person typed, or a take-back that failed (the keys then go to the frame and
948
- // the page sees no typing): either counts toward the first rule.
949
- takes.push({ at, counts: typing || failed });
950
- const within = (ms: number) => takes.filter((take) => at - take.at <= ms);
951
- emit("focusTaken", { typing });
952
- if (
953
- surface === created &&
954
- (within(TAKES.typing.withinMs).filter((take) => take.counts).length >=
955
- TAKES.typing.most ||
956
- within(TAKES.any.withinMs).length >= TAKES.any.most)
957
- ) {
958
- stop();
959
- contentError("The content kept taking the keyboard from the page; it was stopped.");
960
- }
961
- while (takes.length > 0 && at - (takes[0] as { at: number }).at > TAKES.typing.withinMs) {
962
- takes.shift();
963
- }
964
- });
965
923
  const watch = watchOutcome({
966
924
  surface: created,
967
925
  source,
968
926
  speaks,
969
- nested,
970
927
  timeoutMs: timeLeft,
971
928
  onOutcome: (outcome) => emit("outcome", outcome),
972
929
  // A frame status from the content (P124): never shown, the host's to hear.
@@ -1000,8 +957,6 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
1000
957
  ...(options.show === undefined ? {} : { show: options.show }),
1001
958
  ...(options.cached === undefined ? {} : { cached: options.cached }),
1002
959
  userActivation: () => created.userActivation(),
1003
- // The person in this frame (P109): the page's focus in it, after the focus guard.
1004
- focused: () => created.focused?.(),
1005
960
  onEvent: onBridge,
1006
961
  ...(declaration === null ? {} : { declaration }),
1007
962
  ...(viewer === undefined ? {} : { viewer }),
package/src/host/door.ts CHANGED
@@ -3,7 +3,7 @@ import { parseFrameStatus, SETTLE_MS } from "./outcome.ts";
3
3
  import type { FrameOutcome } from "./types.ts";
4
4
 
5
5
  /**
6
- * A served display's door (P125). A served display that isn't nested (a served shell, a page, a
6
+ * A served display's door (P125). A served display (a served shell, a page, a
7
7
  * view through the sandbox proxy) is framed on its scope's origin, where the scope's other displays
8
8
  * run content with `allow-same-origin`: one of them reaches a new document there before its first
9
9
  * script runs, so nothing its frame says, and nothing its silence suggests, is Porthole's word.
@@ -6,7 +6,7 @@ import { parseViewer } from "../runtime/levels.ts";
6
6
  /**
7
7
  * Where a served frame (domain or external isolation) loads from: the host's locator answers, and
8
8
  * `checkFrameLocation` checks the answer (one of the config's content origins, never the host's
9
- * own site; a nested page's on a shell's own label, P121) before any frame is made.
9
+ * own site) before any frame is made.
10
10
  */
11
11
  export async function locateServed(
12
12
  locator: InstanceLocator,
@@ -16,7 +16,7 @@ export async function locateServed(
16
16
  signal?: AbortSignal,
17
17
  ): Promise<FrameSource> {
18
18
  const location = await locator.locate(instance, signal);
19
- checkFrameLocation(location, config.contentOrigins, hostOrigin, config.nested === true);
19
+ checkFrameLocation(location, config.contentOrigins, hostOrigin);
20
20
  // The host's access, as its backend answered (P087): a viewer that doesn't parse is the host's
21
21
  // error, never no viewer (after the review: a mount's own would take its place).
22
22
  const viewer = location.viewer === undefined ? null : parseViewer(location.viewer);
@@ -24,10 +24,9 @@ import type { FrameBlock, FrameOutcome } from "./types.ts";
24
24
  *
25
25
  * - An opaque frame's only document is the host's own shell, with the content in it: no page of
26
26
  * Porthole's server ever loads there, so its every frame status is the content's.
27
- * - A frame that speaks (a served shell, a view through the sandbox proxy, a nested page's shell)
27
+ * - A frame that speaks (a served shell, a view through the sandbox proxy)
28
28
  * says Porthole's own word first in every document that holds content, before any of the
29
- * content's code runs: the shell's hello, the proxy's ready (a nested page's own runtime's hello
30
- * reaches the host before anything its page says, through its shell). A status page says
29
+ * content's code runs: the shell's hello, the proxy's ready. A status page says
31
30
  * nothing but its frame status. So a frame status is taken only before anything else was heard
32
31
  * from the frame in this run: from its first document, which then was a page of Porthole's.
33
32
  * After that, it came from the content (or from a later document, which in a display without
@@ -35,9 +34,9 @@ import type { FrameBlock, FrameOutcome } from "./types.ts";
35
34
  * That holds against the display's own content, not against another display's (P125): a
36
35
  * scope's displays share its origin, and one that runs reaches a new document of another's
37
36
  * before that document's first script, where it can speak first, or stop or rewrite it so it
38
- * says nothing. So the rule holds only where no content runs on the frame's origin: a nested
39
- * page's shell, on a label of its own (P114).
40
- * - A served display that isn't nested (a served shell, a page, a view through the sandbox proxy)
37
+ * says nothing. So the rule holds only where no content runs on the frame's origin, and no
38
+ * served frame is such a place (the nested shell that was, P114, went in 0.16.0: P149).
39
+ * - A served display (a served shell, a page, a view through the sandbox proxy)
41
40
  * takes no frame status from its frame at all, and infers nothing from its silence (a load and
42
41
  * no word is a timeout, never `framing`): its door said how loading went before the frame was
43
42
  * made (P125, `watchDoor`), from an opaque frame of the host's that no content can reach.
@@ -129,19 +128,12 @@ export function watchOutcome(options: {
129
128
  readonly source: FrameSource;
130
129
  /** Whether the frame speaks for itself (a shell or a view): then its handshake is the proof. */
131
130
  readonly speaks: boolean;
132
- /**
133
- * The config nests its pages (P111): the frame holds Porthole's shell, on a label no content
134
- * runs on, whose first word may be a frame status. Any other served frame that speaks takes
135
- * none: its door told (P125).
136
- */
137
- readonly nested?: boolean;
138
131
  readonly timeoutMs: number;
139
132
  readonly onOutcome: (outcome: FrameOutcome) => void;
140
133
  /** A frame status that wasn't taken, once a run (P124): the host's to hear, never shown. */
141
134
  readonly refused?: (message: string) => void;
142
135
  }): OutcomeWatch {
143
136
  const { surface, source, speaks } = options;
144
- const nested = options.nested === true;
145
137
  const reports = source.kind === "url" && source.reports === true;
146
138
  // The first outcome; after a load, only a later block (a status page, access revoked) is told.
147
139
  let decided: FrameOutcome["state"] | null = null;
@@ -181,7 +173,7 @@ export function watchOutcome(options: {
181
173
  }
182
174
  };
183
175
  // Whether a frame status may be the word of a page of Porthole's (P124, P125, above).
184
- const mayBePorthole = () => source.kind === "url" && (!speaks || (nested && !spoke));
176
+ const mayBePorthole = () => source.kind === "url" && !speaks;
185
177
  const unlisten = surface.transport.listen((data) => {
186
178
  heard = true;
187
179
  if (!namesFrameStatus(data)) {
@@ -229,15 +221,10 @@ export function watchOutcome(options: {
229
221
  return;
230
222
  }
231
223
  if (speaks) {
232
- // A served shell or view says something before its first load ends; a nested page's shell
233
- // that never did never ran. Any other served frame's silence tells nothing (P125). (An
224
+ // A served frame's silence tells nothing (P125): its door said how loading went. (An
234
225
  // opaque srcdoc frame always runs: its handshake decides.)
235
226
  if (source.kind === "url") {
236
- if (nested) {
237
- neverRan();
238
- } else {
239
- silent();
240
- }
227
+ silent();
241
228
  }
242
229
  return;
243
230
  }
package/src/host/types.ts CHANGED
@@ -137,12 +137,12 @@ export type HostErrorKind =
137
137
  /**
138
138
  * A frame status (`porthole/notifications/frame-status`) the host didn't take, since it came
139
139
  * from the frame's content, not from a page of Porthole's server (P124): never shown, never an
140
- * outcome. Told once a run. A served display that isn't nested takes none from its frame at
140
+ * outcome. Told once a run. A served display takes none from its frame at
141
141
  * all: its door says how loading went (P125).
142
142
  */
143
143
  | "frame-status"
144
144
  /**
145
- * A served display that has a door (P125: a served shell, a page that isn't nested, the sandbox
145
+ * A served display that has a door (P125: a served shell, a page, the sandbox
146
146
  * proxy) was located without one: the server is older than the host (upgrade it first), or a
147
147
  * locator dropped `FrameLocation.door`. The display shows, but no frame status is taken, so a
148
148
  * block is told as a timeout. Told once a mount.
@@ -225,17 +225,9 @@ export interface DisplayEvents {
225
225
  readonly refused: { readonly capability: CapabilityName; readonly refusal: Refusal };
226
226
  /** Too many declines: the display stops asking until it runs again. */
227
227
  readonly muted: undefined;
228
- /**
229
- * The content moved the keyboard into its frame from one of the page's text fields without the
230
- * person (no press on the frame, no Tab, P109), and focus went back where it was; `typing`: the
231
- * person had pressed a key on the page within the last second. The content's doing. Three while
232
- * typing within 10 s, or five within 2 s, stop the display (`contentError` says so; `reload()`
233
- * runs it again).
234
- */
235
- readonly focusTaken: { readonly typing: boolean };
236
228
  /**
237
229
  * Whether the page touched `localStorage` or `sessionStorage` (the in-memory stand-in of a frame
238
- * without storage of its own: opaque, or a nested page, P111): once per run, `used: true` when
230
+ * without storage of its own: an opaque one): once per run, `used: true` when
239
231
  * the page first did, else `used: false` as the run ends. Never what it kept: for a host to count
240
232
  * the pages that would need storage.
241
233
  */
@@ -352,9 +344,7 @@ export interface AnnotationControls {
352
344
  * comes of it. Nothing happens, and nothing throws, for an id no mark with a marker is shown
353
345
  * under, or if the frame has no such marker now (its words are gone, elements are being picked):
354
346
  * the display's own `focus()` isn't used, so the frame takes no focus for a marker it hasn't got.
355
- * Call it once the view is closed: from one of the page's text fields that still has focus, the
356
- * move is the frame's own to the focus guard, undone and counted (P109). The page can take the
357
- * focus back at once. Not kept for a frame that runs later.
347
+ * The page can take the focus back at once. Not kept for a frame that runs later.
358
348
  *
359
349
  * On a calm page it lands at once, from anywhere on the host's page. While the frame is finding
360
350
  * its marks (a `show` just sent, the content just changed) it waits, and is then dropped unless
@@ -362,8 +352,7 @@ export interface AnnotationControls {
362
352
  * it (its page is busy) is held to the same test (P137), so a word that comes late takes no
363
353
  * keyboard from a person who moved on. Nothing says it was dropped: if the frame isn't your page's
364
354
  * `document.activeElement` soon after and the person hasn't moved on, call `focus()` and then
365
- * `focusMark(id)` again. On a nested page only `focus()` reaches the page (P136): the frame's own
366
- * `focus()` stops at its shell, and a second call that waits is dropped.
355
+ * `focusMark(id)` again.
367
356
  */
368
357
  focusMark(id: string): void;
369
358
  }
@@ -387,10 +376,7 @@ export interface DisplayControls {
387
376
  readonly find: FindControls;
388
377
  /** Runs the content again from the start, in a new frame. */
389
378
  reload(): void;
390
- /**
391
- * Moves focus into the display's frame, as the host's own move: from one of the page's text
392
- * fields, a frame's own `focus()` is taken for the content's and undone (P109).
393
- */
379
+ /** Moves focus into the display's frame. */
394
380
  focus(): void;
395
381
  /** Tears the view down and removes the frame. */
396
382
  destroy(): void;
package/src/index.ts CHANGED
@@ -50,9 +50,7 @@ export {
50
50
  type UrlSandboxExtra,
51
51
  } from "./config/schema.ts";
52
52
  export { hostOriginProblem, isHostOrigin } from "./isolation/served.ts";
53
- export { FRAME_STATUS_METHOD, SHELL_STATE_METHOD, STORAGE_USED_METHOD } from "./isolation/types.ts";
54
- export { PAGE_SANDBOX_TOKENS } from "./compile/policy.ts";
55
- export { SHELL_GESTURE_MS } from "./platform/focus-guard.ts";
53
+ export { FRAME_STATUS_METHOD, STORAGE_USED_METHOD } from "./isolation/types.ts";
56
54
 
57
55
  // The capability runtime (P085-P090): its contract, levels, a page's declaration, its services'
58
56
  // shapes. Hosts implement the services; Porthole carries, checks and gates the calls.
@@ -279,7 +277,7 @@ export type {
279
277
  } from "./bridge/types.ts";
280
278
  export { createHost } from "./host/create-host.ts";
281
279
  export { mayPassOn } from "./host/pass-on.ts";
282
- export { focusField } from "./platform/focus-guard.ts";
280
+ export { focusField } from "./platform/focus-field.ts";
283
281
  // The client half of the host kit, and the display registry (P072).
284
282
  export {
285
283
  entryTarget,
@@ -28,27 +28,12 @@ export function parseOrigin(origin: string): ParsedOrigin | null {
28
28
  }
29
29
 
30
30
  /**
31
- * The start of every label Porthole serves for itself on a content domain (P114): no host's naming
32
- * may make one (`content.name` is refused one, and `prefixedName` won't take the prefix).
31
+ * The start of every label Porthole keeps for itself on a content domain (its health label;
32
+ * until 0.16.0 a nested page's shell's, P114): no host's naming may make one (`content.name` is
33
+ * refused one, and `prefixedName` won't take the prefix), and no display is served on one.
33
34
  */
34
35
  export const PORTHOLE_LABEL_PREFIX = "porthole-";
35
36
 
36
- const NESTED_LABEL = /^porthole-[a-z2-7]{24}$/u;
37
-
38
- /** Whether a label is a nested page's shell's own (P114, `nestedLabelOf`'s form). */
39
- export const isNestedLabel = (label: string): boolean => NESTED_LABEL.test(label);
40
-
41
- /**
42
- * Whether `origin` is on a nested page's shell's own label (P114): its host's first label is one.
43
- * The shell runs nowhere else (P121): the host's mount, the shell itself and `/server`'s helpers
44
- * each refuse any other origin, so a content Worker of a host's own can't put it beside other
45
- * content by mistake.
46
- */
47
- export function onNestedLabel(origin: string): boolean {
48
- const parsed = parseOrigin(origin);
49
- return parsed !== null && isNestedLabel(parsed.host.split(".")[0] ?? "");
50
- }
51
-
52
37
  /** Whether `origin` is an exact origin (`https://host[:port]`, lowercase, no path). */
53
38
  export function isExactOrigin(origin: unknown): origin is string {
54
39
  return typeof origin === "string" && parseOrigin(origin) !== null;
@@ -232,8 +217,6 @@ export function checkFrameLocation(
232
217
  location: FrameLocation,
233
218
  contentOrigins: readonly string[],
234
219
  hostOrigin: string,
235
- /** The config nests its pages (P111): the location must be on a shell's own label (P121). */
236
- nested = false,
237
220
  ): void {
238
221
  const origin = parseOrigin(location.origin);
239
222
  let url: URL;
@@ -253,13 +236,8 @@ export function checkFrameLocation(
253
236
  `The located origin ${location.origin} is not one of the config's content origins`,
254
237
  );
255
238
  }
256
- if (nested && !onNestedLabel(location.origin)) {
257
- throw new TypeError(
258
- `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`,
259
- );
260
- }
261
239
  if (location.door !== undefined) {
262
- checkDoor(location.door, location.origin, nested);
240
+ checkDoor(location.door, location.origin);
263
241
  }
264
242
  const host = parseOrigin(hostOrigin);
265
243
  if (host !== null && maybeSameSite(origin.host, host.host)) {
@@ -270,21 +248,15 @@ export function checkFrameLocation(
270
248
  }
271
249
 
272
250
  /**
273
- * A location's door (P125): on the location's own origin, at Porthole's door path, never for a
274
- * nested page (its shell's label serves no door: its first document is Porthole's own, P114).
251
+ * A location's door (P125): on the location's own origin, at Porthole's door path.
275
252
  * Named by its origin only in what is thrown: the door's address carries a ticket.
276
253
  */
277
- function checkDoor(door: unknown, origin: string, nested: boolean): void {
254
+ function checkDoor(door: unknown, origin: string): void {
278
255
  const url =
279
256
  door !== null && typeof door === "object" ? (door as { url?: unknown }).url : undefined;
280
257
  if (typeof url !== "string") {
281
258
  throw new TypeError("The located door is not { url }");
282
259
  }
283
- if (nested) {
284
- throw new TypeError(
285
- "A nested page is located with no door: its shell is Porthole's own first document (P125)",
286
- );
287
- }
288
260
  let parsed: URL;
289
261
  try {
290
262
  parsed = new URL(url);
@@ -73,8 +73,8 @@ export interface FrameLocation {
73
73
  * The display's door (P125): a page of Porthole's on the same origin, at
74
74
  * `/__porthole/door/<instance key>?ticket=<its own ticket>`, that says how loading went before
75
75
  * any content is framed. The host frames it opaque and hidden, and takes its one frame status
76
- * (`open`, or `blocked` and why); then frames `url`. Given for a served shell, a page that isn't
77
- * nested and the sandbox proxy: content of the scope runs on their origin, so no frame status
76
+ * (`open`, or `blocked` and why); then frames `url`. Given for a served shell, a page and the
77
+ * sandbox proxy: content of the scope runs on their origin, so no frame status
78
78
  * from their own frame is ever Porthole's. A host that is given none for one of them takes no
79
79
  * frame status at all (a load that shows nothing is a timeout) and says so (`hostError` kind
80
80
  * `door`). A custom locator passes it on as it came.
@@ -88,35 +88,6 @@ export const DOOR_PATH = "/__porthole/door/";
88
88
  /** The message a served page sends its host about loading (own-prefixed, P040). */
89
89
  export const FRAME_STATUS_METHOD = "porthole/notifications/frame-status";
90
90
 
91
- /** A nested page's shell's report of its own state to the host (P111). */
92
- export const SHELL_STATE_METHOD = "porthole/shell/state";
93
-
94
- /** A nested page's shell's heartbeat, every 50 ms while it runs (P111, after its review). */
95
- export const SHELL_BEAT_METHOD = "porthole/shell/beat";
96
-
97
- /**
98
- * The host's ask to a nested page's shell (P120): look now, and say what it saw in a state report
99
- * that names the ask (`asked`). The host asks as it hears focus move into the frame.
100
- */
101
- export const SHELL_LOOK_METHOD = "porthole/shell/look";
102
-
103
- /**
104
- * The host's word to a nested page's shell (P136) that it moved the focus into the frame: pass it on
105
- * to the page, in this task, not in the focus event (where the shell's move doesn't take). Sent by
106
- * `display.focus()` alone; a page has no way to say it.
107
- */
108
- export const SHELL_FOCUS_METHOD = "porthole/shell/focus";
109
-
110
- /**
111
- * A nested page's shell's word to its page's runtime (P148): one `MessagePort`, sent at each load
112
- * of the page's frame, over which the runtime tells the shell each real press in the page. The
113
- * runtime takes the first one alone, before any content runs, and no content ever holds it.
114
- */
115
- export const SHELL_PRESS_PORT_METHOD = "porthole/shell/press-port";
116
-
117
- /** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
118
- export const SHELL_METHOD_PREFIX = "porthole/shell/";
119
-
120
91
  /** A page's word that it used storage, once per load (P111): never a key or a value. */
121
92
  export const STORAGE_USED_METHOD = "porthole/storage-used";
122
93
 
@@ -0,0 +1,18 @@
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 function focusField(field: HTMLElement): void {
12
+ const holder = field.ownerDocument.activeElement;
13
+ const view = field.ownerDocument.defaultView;
14
+ if (view !== null && holder instanceof view.HTMLIFrameElement) {
15
+ holder.blur();
16
+ }
17
+ field.focus({ preventScroll: true });
18
+ }
@@ -3,7 +3,7 @@ import type { FrameSource } from "../isolation/types.ts";
3
3
  import type { Transport } from "../transport/types.ts";
4
4
 
5
5
  /**
6
- * The platform-host seam (ARCHITECTURE § Platform hosts): what owns the isolation primitive and
6
+ * The platform-host seam (DESIGN.md § Platform hosts): what owns the isolation primitive and
7
7
  * the transport. The web's is an `<iframe>` with `postMessage`; a native web view is another
8
8
  * implementation of the same interface, not a fork.
9
9
  */
@@ -24,12 +24,6 @@ export interface SurfaceSpec {
24
24
  readonly fill?: boolean;
25
25
  /** The height to start at (a remembered height, so a frame mounting again doesn't jump). */
26
26
  readonly initialHeightPx: number;
27
- /**
28
- * The frame holds a nested page's shell (P111): the host's config says so, never the frame. What
29
- * the shell says of itself (`porthole/shell/state`) decides moves of focus into it and the
30
- * gesture its page's calls need; nothing else in that namespace reaches the transport.
31
- */
32
- readonly nested?: boolean;
33
27
  }
34
28
 
35
29
  /** One isolated frame. */
@@ -42,7 +36,7 @@ export interface Surface {
42
36
  /**
43
37
  * Whether the embedding page has transient user activation now (a gesture in the frame
44
38
  * activates its ancestors), or undefined where the platform can't tell. The gesture gate reads
45
- * it, and so does a marker's click (P105): false, or a throw, drops it.
39
+ * it (`copyText`'s by default, and any a host's config adds).
46
40
  */
47
41
  userActivation(): boolean | undefined;
48
42
  /**
@@ -53,22 +47,13 @@ export interface Surface {
53
47
  */
54
48
  viewport?(): { readonly width: number; readonly height: number } | undefined;
55
49
  /**
56
- * Whether the embedding page's focus is in this frame now, once the platform's focus guard
57
- * judged any move into it (P109); undefined, or absent, where the platform can't tell. A gesture
58
- * gate that asks for the person in the calling frame (`comments`) reads it: false refuses. A
59
- * nested page's frame (P111) is the person's too while its shell saw their gesture just now.
50
+ * Whether the embedding page's keyboard focus is in this frame now, as its document says;
51
+ * undefined, or absent, where the platform can't tell. The find shortcut reads it (P131: a
52
+ * frame that says the shortcut was pressed while the focus is elsewhere is not believed). No
53
+ * word on who put the focus there: a frame may take it by itself (P149).
60
54
  */
61
55
  focused?(): boolean | undefined;
62
- /**
63
- * Each time the content moved the keyboard into its frame from one of the embedding page's text
64
- * fields without the person (no press on the frame, no Tab) and the platform gave focus back
65
- * (P109): whether the person was typing then (a key within the last second), and whether focus
66
- * failed to go back (the frame kept it or took it again). Absent where the platform has no guard.
67
- */
68
- onFocusTaken?(
69
- listener: (take: { readonly typing: boolean; readonly failed: boolean }) => void,
70
- ): () => void;
71
- /** The host moves focus into the frame itself: the guard takes it as the person's (P109). */
56
+ /** The host moves focus into the frame itself. */
72
57
  focus?(): void;
73
58
  /**
74
59
  * The frame loaded a document other than the one it was given: the content navigated it. The