@botiverse/porthole 0.15.2 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (109) hide show
  1. package/CHANGELOG.md +89 -0
  2. package/dist/bridge/bridge.d.ts +1 -8
  3. package/dist/bridge/bridge.js +0 -7
  4. package/dist/check/page-source.js +1 -1
  5. package/dist/check/page.js +1 -1
  6. package/dist/compile/policy.d.ts +0 -7
  7. package/dist/compile/policy.js +1 -10
  8. package/dist/config/capabilities.d.ts +8 -14
  9. package/dist/config/capabilities.js +4 -5
  10. package/dist/config/schema.d.ts +2 -13
  11. package/dist/config/validate.js +0 -24
  12. package/dist/conformance/behavior.js +26 -37
  13. package/dist/conformance/clipboard.js +47 -1
  14. package/dist/conformance/harness-source.js +1 -1
  15. package/dist/displays/displays.js +1 -3
  16. package/dist/guide/limits.js +1 -1
  17. package/dist/guide/runtime.js +1 -1
  18. package/dist/host/create-host.d.ts +1 -1
  19. package/dist/host/create-host.js +6 -51
  20. package/dist/host/door.d.ts +1 -1
  21. package/dist/host/locate.d.ts +1 -1
  22. package/dist/host/locate.js +2 -2
  23. package/dist/host/outcome.d.ts +5 -12
  24. package/dist/host/outcome.js +8 -16
  25. package/dist/host/types.d.ts +6 -22
  26. package/dist/index.d.ts +2 -4
  27. package/dist/index.js +2 -4
  28. package/dist/isolation/served.d.ts +9 -14
  29. package/dist/isolation/served.js +17 -31
  30. package/dist/isolation/types.d.ts +2 -19
  31. package/dist/isolation/types.js +0 -17
  32. package/dist/platform/focus-field.d.ts +11 -0
  33. package/dist/platform/focus-field.js +18 -0
  34. package/dist/platform/types.d.ts +6 -22
  35. package/dist/platform/web.js +8 -98
  36. package/dist/presets/presets.d.ts +0 -2
  37. package/dist/presets/presets.js +0 -1
  38. package/dist/react/frame.d.ts +0 -8
  39. package/dist/react/frame.js +0 -4
  40. package/dist/runtime/contract.d.ts +2 -2
  41. package/dist/runtime/contract.js +2 -2
  42. package/dist/runtime/types.generated.js +6 -6
  43. package/dist/server/files.js +7 -23
  44. package/dist/server/host.d.ts +1 -1
  45. package/dist/server/index.d.ts +1 -1
  46. package/dist/server/index.js +4 -6
  47. package/dist/server/naming.js +1 -1
  48. package/dist/server/pages.d.ts +9 -2
  49. package/dist/server/pages.js +28 -8
  50. package/dist/server/server.js +28 -166
  51. package/dist/server/types.d.ts +7 -7
  52. package/dist/shell/plan.js +2 -2
  53. package/dist/shell/runtime.js +1 -9
  54. package/docs/ADOPTING.md +42 -135
  55. package/docs/ARCHITECTURE.md +0 -33
  56. package/docs/DECISIONS.md +296 -9
  57. package/docs/DESIGN.md +27 -50
  58. package/docs/THREAT_MODEL.md +140 -242
  59. package/package.json +1 -1
  60. package/src/bridge/bridge.ts +1 -17
  61. package/src/check/page.ts +1 -1
  62. package/src/compile/policy.ts +1 -11
  63. package/src/config/capabilities.ts +8 -14
  64. package/src/config/schema.ts +2 -13
  65. package/src/config/validate.ts +0 -28
  66. package/src/conformance/behavior.ts +50 -52
  67. package/src/conformance/clipboard.ts +56 -1
  68. package/src/displays/displays.ts +1 -3
  69. package/src/guide/limits.ts +1 -1
  70. package/src/guide/runtime.ts +1 -1
  71. package/src/host/create-host.ts +6 -52
  72. package/src/host/door.ts +1 -1
  73. package/src/host/locate.ts +2 -2
  74. package/src/host/outcome.ts +8 -21
  75. package/src/host/types.ts +6 -20
  76. package/src/index.ts +2 -4
  77. package/src/isolation/served.ts +18 -37
  78. package/src/isolation/types.ts +2 -24
  79. package/src/platform/focus-field.ts +18 -0
  80. package/src/platform/types.ts +6 -21
  81. package/src/platform/web.ts +8 -116
  82. package/src/presets/presets.ts +0 -3
  83. package/src/react/frame.tsx +0 -10
  84. package/src/runtime/contract.ts +4 -4
  85. package/src/runtime/types.generated.ts +6 -6
  86. package/src/server/files.ts +4 -19
  87. package/src/server/host.ts +1 -1
  88. package/src/server/index.ts +4 -16
  89. package/src/server/naming.ts +1 -1
  90. package/src/server/pages.ts +38 -12
  91. package/src/server/server.ts +29 -189
  92. package/src/server/types.ts +7 -7
  93. package/src/shell/plan.ts +2 -2
  94. package/src/shell/runtime.ts +1 -9
  95. package/types/runtime/v1/artifact.d.ts +2 -3
  96. package/types/runtime/v1/assets.d.ts +1 -1
  97. package/types/runtime/v1/chat.d.ts +2 -2
  98. package/types/runtime/v1/comments.d.ts +1 -1
  99. package/types/runtime/v1/downloads.d.ts +2 -2
  100. package/types/runtime/v1/links.d.ts +2 -2
  101. package/dist/platform/focus-guard.d.ts +0 -252
  102. package/dist/platform/focus-guard.js +0 -764
  103. package/dist/server/nested.d.ts +0 -66
  104. package/dist/server/nested.js +0 -120
  105. package/dist/shell/frame.d.ts +0 -28
  106. package/dist/shell/frame.js +0 -338
  107. package/src/platform/focus-guard.ts +0 -999
  108. package/src/server/nested.ts +0 -156
  109. package/src/shell/frame.ts +0 -371
@@ -45,7 +45,7 @@ const NOBODY = {
45
45
  return { ...surface, userActivation: () => false };
46
46
  },
47
47
  // A served display's door (P125), as the web platform makes it: a platform without doors frames
48
- // no served display that isn't nested.
48
+ // no served display.
49
49
  createDoor: (container, spec) => webPlatform.createDoor(container, spec),
50
50
  };
51
51
  /** A handler for each host function the config declares: it notes the call and answers no. */
@@ -96,13 +96,6 @@ export declare function sandboxTokens(config: PortholeConfig): string[];
96
96
  * own documents, and opaque content is never served. Never in a `<meta>` (browsers ignore it there).
97
97
  */
98
98
  export declare function servedSandboxDirective(config: PortholeConfig): CspDirective | null;
99
- /**
100
- * A nested page's sandbox (P111): its frame's attribute, set by Porthole's shell, and its own CSP
101
- * header's, so it is an opaque origin in the shell's child frame and on a tab of its own. Scripts
102
- * only: never `allow-same-origin`, which would give the page its served origin, the shell's, and
103
- * so the shell's realm (a test holds every sandbox Porthole writes to this).
104
- */
105
- export declare const PAGE_SANDBOX_TOKENS: readonly string[];
106
99
  /**
107
100
  * A served display's door's sandbox (P125): its frame's attribute, which the host writes, and its
108
101
  * answer's CSP header's. Scripts only: an opaque origin, a new one each time, that no content of
@@ -188,8 +188,6 @@ export function sandboxTokens(config) {
188
188
  case "opaque":
189
189
  return ["allow-scripts"];
190
190
  case "domain":
191
- // Nested (P111), this frame holds Porthole's shell, on a label of its own where no content
192
- // runs with this origin (P114), and the page is the shell's child (`PAGE_SANDBOX_TOKENS`).
193
191
  return ["allow-scripts", "allow-same-origin"];
194
192
  case "external":
195
193
  // The host may add a documented few (popups, modals, downloads), never top navigation.
@@ -210,15 +208,8 @@ export function servedSandboxDirective(config) {
210
208
  if (config.isolation !== "domain") {
211
209
  return null;
212
210
  }
213
- return ["sandbox", ...(config.nested === true ? PAGE_SANDBOX_TOKENS : sandboxTokens(config))];
211
+ return ["sandbox", ...sandboxTokens(config)];
214
212
  }
215
- /**
216
- * A nested page's sandbox (P111): its frame's attribute, set by Porthole's shell, and its own CSP
217
- * header's, so it is an opaque origin in the shell's child frame and on a tab of its own. Scripts
218
- * only: never `allow-same-origin`, which would give the page its served origin, the shell's, and
219
- * so the shell's realm (a test holds every sandbox Porthole writes to this).
220
- */
221
- export const PAGE_SANDBOX_TOKENS = ["allow-scripts"];
222
213
  /**
223
214
  * A served display's door's sandbox (P125): its frame's attribute, which the host writes, and its
224
215
  * answer's CSP header's. Scripts only: an opaque origin, a new one each time, that no content of
@@ -22,8 +22,10 @@ export type CapabilityName = (typeof CAPABILITY_NAMES)[number];
22
22
  * propagates to, and which lasts 5 s after any gesture anywhere on the host's page: a click on
23
23
  * the host's own UI, or the person typing in its own composer, counts. So it stops calls made on
24
24
  * load, or on a timer while nobody does anything; it is not proof that the gesture was in this
25
- * frame, nor of intent. Where a capability needs that (`comments`, P109: its draft goes into
26
- * the person's composer), the host also asks that its page's focus be in the calling frame.
25
+ * frame, nor of intent. Since 0.16.0 (P149) only `copyText` has it by default: nothing else
26
+ * stands between a page and the person's clipboard. Every other call either shows the person
27
+ * its whole effect first (`confirm`) or opens something of the host's that does nothing by
28
+ * itself (`comments`), and a guess at who pressed what refused real presses.
27
29
  * - `confirm`: the host's `confirm` function shows a person the call's whole effect, and the call
28
30
  * goes only if they accept. No `confirm` function means the call is refused (fail closed).
29
31
  * - `rateLimit`: at most `perMinute` calls per display per minute; the rest are refused.
@@ -59,13 +61,6 @@ export interface CapabilitySpec {
59
61
  readonly method: string;
60
62
  readonly sdk?: string;
61
63
  };
62
- /**
63
- * Its `user-activation` gate also needs the person in the calling frame (P109): the host page's
64
- * focus in that frame, which a press on it or a Tab into it gives and the focus guard keeps from
65
- * a frame's own `focus()`. Activation alone lasts 5 s after any gesture on the host's page,
66
- * typing in its own composer included.
67
- */
68
- readonly inFrame?: true;
69
64
  }
70
65
  /** The most text one `copyText` call carries. */
71
66
  export declare const MAX_COPY_CHARS = 20000;
@@ -76,7 +71,7 @@ export declare const MAX_COPY_CHARS = 20000;
76
71
  export declare const MAX_CONTEXT_CHARS = 20000;
77
72
  export declare const CAPABILITIES: {
78
73
  readonly sendPrompt: {
79
- readonly defaultGates: readonly ["user-activation", "confirm"];
74
+ readonly defaultGates: readonly ["confirm", Gate];
80
75
  readonly served: "handler";
81
76
  readonly global: "sendPrompt";
82
77
  readonly request: {
@@ -85,7 +80,7 @@ export declare const CAPABILITIES: {
85
80
  };
86
81
  };
87
82
  readonly openLink: {
88
- readonly defaultGates: readonly ["user-activation", "confirm"];
83
+ readonly defaultGates: readonly ["confirm", Gate];
89
84
  readonly served: "handler";
90
85
  readonly global: "openLink";
91
86
  readonly request: {
@@ -94,7 +89,7 @@ export declare const CAPABILITIES: {
94
89
  };
95
90
  };
96
91
  readonly downloadFile: {
97
- readonly defaultGates: readonly ["user-activation", "confirm"];
92
+ readonly defaultGates: readonly ["confirm", Gate];
98
93
  readonly served: "handler";
99
94
  readonly request: {
100
95
  readonly method: "ui/download-file";
@@ -192,12 +187,11 @@ export declare const CAPABILITIES: {
192
187
  };
193
188
  /** Opens the host's comment composer at the page's anchor (P090): write-only. */
194
189
  readonly comments: {
195
- readonly defaultGates: readonly ["user-activation", Gate];
190
+ readonly defaultGates: readonly [Gate];
196
191
  readonly served: "handler";
197
192
  readonly request: {
198
193
  readonly method: "porthole/call";
199
194
  };
200
- readonly inFrame: true;
201
195
  };
202
196
  /** This artifact's current version, and a new version of it, base-checked (P088). */
203
197
  readonly artifact: {
@@ -37,19 +37,19 @@ export const MAX_COPY_CHARS = 20_000;
37
37
  export const MAX_CONTEXT_CHARS = 20_000;
38
38
  export const CAPABILITIES = {
39
39
  sendPrompt: {
40
- defaultGates: ["user-activation", "confirm"],
40
+ defaultGates: ["confirm", rate(30)],
41
41
  served: "handler",
42
42
  global: "sendPrompt",
43
43
  request: { method: "ui/message", sdk: "app.sendMessage" },
44
44
  },
45
45
  openLink: {
46
- defaultGates: ["user-activation", "confirm"],
46
+ defaultGates: ["confirm", rate(30)],
47
47
  served: "handler",
48
48
  global: "openLink",
49
49
  request: { method: "ui/open-link", sdk: "app.openLink" },
50
50
  },
51
51
  downloadFile: {
52
- defaultGates: ["user-activation", "confirm"],
52
+ defaultGates: ["confirm", rate(30)],
53
53
  served: "handler",
54
54
  request: { method: "ui/download-file", sdk: "app.downloadFile" },
55
55
  },
@@ -114,10 +114,9 @@ export const CAPABILITIES = {
114
114
  user: { defaultGates: [rate(60)], served: "viewer", request: { method: "porthole/call" } },
115
115
  /** Opens the host's comment composer at the page's anchor (P090): write-only. */
116
116
  comments: {
117
- defaultGates: ["user-activation", rate(30)],
117
+ defaultGates: [rate(30)],
118
118
  served: "handler",
119
119
  request: { method: "porthole/call" },
120
- inFrame: true,
121
120
  },
122
121
  /** This artifact's current version, and a new version of it, base-checked (P088). */
123
122
  artifact: { defaultGates: [rate(10)], served: "handler", request: { method: "porthole/call" } },
@@ -238,17 +238,6 @@ export interface PortholeConfig {
238
238
  * `db`). Absent: 0.6's frames, globals and manual, exactly.
239
239
  */
240
240
  readonly runtime?: RuntimeVersion;
241
- /**
242
- * Domain isolation, artifact pages (P111): the address the host frames serves Porthole's shell
243
- * alone, a document of Porthole's own with no content in it, and the page runs in a child frame
244
- * of the shell's, sandboxed without `allow-same-origin` (an opaque origin), served from the same
245
- * origin at its files' sealed address. The shell is then a realm the page can't reach, above the
246
- * page's frame: it relays the page's messages, and tells the host when its own transient
247
- * activation turns on (a press in the page activates its ancestors only), which is how the host
248
- * knows the person, not the page, moved the keyboard into the frame or opened a comment. The
249
- * page has no storage of its own (an in-memory stand-in) and fetches nothing with a cookie.
250
- */
251
- readonly nested?: true;
252
241
  /**
253
242
  * Which nested frames content may make (P128). `none` (default, and absent): the shell removes
254
243
  * every frame-like element content adds, and the CSP's `frame-src` is `'none'`. `own`: an
@@ -258,8 +247,8 @@ export interface PortholeConfig {
258
247
  * A weakening, opted into: a child frame is a realm of its own, where the shell's WebRTC
259
248
  * removal, clipboard guards and navigation cancel never ran (a page of the set framed there has
260
249
  * its own shell; a `srcdoc` frame, or the `about:blank` a new frame starts as, has none), so
261
- * content reaches WebRTC and the clipboard's events there. Not for url mode, a live widget
262
- * (no network of its own, P079) or a nested page (P111).
250
+ * content reaches WebRTC and the clipboard's events there. Not for url mode or a live widget
251
+ * (no network of its own, P079).
263
252
  */
264
253
  readonly nestedFrames?: "none" | "own";
265
254
  }
@@ -270,7 +270,6 @@ export function validateConfig(input, options = {}) {
270
270
  "storage",
271
271
  "errors",
272
272
  "runtime",
273
- "nested",
274
273
  "nestedFrames",
275
274
  ], "config");
276
275
  if (!MODES.includes(config.mode)) {
@@ -546,24 +545,6 @@ export function validateConfig(input, options = {}) {
546
545
  fail("config.storage.shared", 'must be a short lowercase noun ("conversation")');
547
546
  }
548
547
  }
549
- if (config.nested !== undefined) {
550
- if (config.nested !== true) {
551
- fail("config.nested", "must be true, or left out");
552
- }
553
- if (config.isolation !== "domain" || config.mode !== "artifact") {
554
- fail("config.nested", "nests artifact pages served on their own origin (domain isolation)");
555
- }
556
- // The page's origin is opaque (P111): nothing of the content origin's own is its.
557
- if (config.storage !== undefined) {
558
- fail("config.nested", "a nested page keeps no storage: drop config.storage");
559
- }
560
- if (capabilities.assets !== undefined) {
561
- fail("config.nested", "a nested page can't load its asset library (/_blob/) yet: drop assets");
562
- }
563
- if (isObject(config.egress) && config.egress.libraries === true) {
564
- fail("config.nested", "a nested page can't load Porthole's libraries from its origin yet");
565
- }
566
- }
567
548
  // A page's own nested frames (P128): opted into, never a default.
568
549
  if (config.nestedFrames !== undefined) {
569
550
  if (config.nestedFrames !== "none" && config.nestedFrames !== "own") {
@@ -572,11 +553,6 @@ export function validateConfig(input, options = {}) {
572
553
  if (config.nestedFrames === "own" && config.mode === "url") {
573
554
  fail("config.nestedFrames", "url mode has no shell: its app's frames are its own");
574
555
  }
575
- // A nested page's frames have an opaque ancestor, which no frame-ancestors source matches:
576
- // none of its own files would load in one. Not measured yet.
577
- if (config.nestedFrames === "own" && config.nested === true) {
578
- fail("config.nestedFrames", 'a nested page (P111) has no "own" frames yet: leave it out');
579
- }
580
556
  }
581
557
  if (config.errors !== undefined) {
582
558
  if (config.errors !== "agent" && config.errors !== "host" && config.errors !== "none") {
@@ -34,22 +34,6 @@ async function refusals(display) {
34
34
  async function click(display, selector) {
35
35
  await (await display.frame()).locator(selector).click();
36
36
  }
37
- /**
38
- * Lets any user activation the test harness gave the host page lapse: Playwright's own
39
- * evaluations count as gestures in some engines, and Chromium keeps one for 5 s. Between this and
40
- * the next raw input, the test must not evaluate anything in the page.
41
- */
42
- const ACTIVATION_LAPSE_MS = 6_000;
43
- /** A click by raw mouse input at `selector`'s center, after any harness activation has lapsed. */
44
- async function clickAfterLapse(context, display, selector) {
45
- const frame = await display.frame();
46
- const box = await frame.locator(selector).boundingBox();
47
- if (box === null) {
48
- throw new Error(`${selector} is not on screen`);
49
- }
50
- await context.page.waitForTimeout(ACTIVATION_LAPSE_MS);
51
- await context.page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);
52
- }
53
37
  /**
54
38
  * The attribute `name` of the frame's body, once set. Where it is a gate's answer to the content,
55
39
  * `verdict` is the probe's: an answer that never comes (a call left waiting on a gate that should
@@ -96,8 +80,12 @@ const PROMPT_CONTENT = `<button id="ask">Explain March</button>
96
80
  (error) => (document.body.dataset.result = "refused: " + error.message),
97
81
  );
98
82
  });
83
+ </script>`;
84
+ /** A prompt asked as the page loads, with no click anywhere. */
85
+ const PROMPT_ON_LOAD = `<p>Asks on load</p>
86
+ <script>
99
87
  sendPrompt("asked on load").then(
100
- () => (document.body.dataset.onload = "sent"),
88
+ (sent) => (document.body.dataset.onload = String(sent)),
101
89
  (error) => (document.body.dataset.onload = "refused: " + error.message),
102
90
  );
103
91
  </script>`;
@@ -355,20 +343,22 @@ export const BEHAVIOR_PROBES = [
355
343
  },
356
344
  // ── 12: the host-function gates ────────────────────────────────────────────────────────────
357
345
  {
358
- id: "12.prompt-gesture-confirm",
346
+ id: "12.prompt-confirm",
359
347
  item: 12,
360
- title: "sendPrompt needs a click and the person's yes; a no sends nothing",
348
+ title: "sendPrompt needs the person's yes, from a click or not; a no sends nothing",
361
349
  async run(context) {
350
+ // No proof of a click is asked (0.16.0, P149): a prompt made as the page loads is the
351
+ // person's to answer like any other, and their no sends nothing.
352
+ const loading = await context.launch({ config: prompts(), content: PROMPT_ON_LOAD });
353
+ const unasked = await answered(loading, false, "probe: the person was asked about a prompt made on load");
354
+ expect(unasked, "probe: the person was asked about the whole prompt").toMatchObject({
355
+ capability: "sendPrompt",
356
+ args: { text: "asked on load" },
357
+ });
358
+ expect(await bodyData(loading, "onload", "probe: the content is told a declined prompt wasn't sent"), "probe: the content is told a declined prompt wasn't sent").toBe("false");
359
+ expect(await loading.calls(), "probe: a declined prompt reached the host's handler").toEqual([]);
362
360
  const display = await context.launch({ config: prompts(), content: PROMPT_CONTENT });
363
- expect(await bodyData(display, "onload", "probe: a call made on load is refused by the shell"), "probe: a call made on load is refused by the shell").toContain("needs a click");
364
- expect(await display.calls(), "probe: a call made on load reached the host's handler").toEqual([]);
365
- // The host's own check needs the frame's click to reach the host page (activation
366
- // propagates to ancestors): measured with raw input, after the harness's activation lapsed.
367
- await clickAfterLapse(context, display, "#ask");
368
- await context.page.waitForTimeout(500);
369
- const refused = await refusals(display);
370
- context.measured(`${context.engine}: a click in the frame ${refused.includes("sendPrompt:no-user-activation") ? "does not reach" : "reaches"} the host page's user activation`);
371
- expect(refused, "the frame's click didn't count as a gesture on the host page").toEqual([]);
361
+ await click(display, "#ask");
372
362
  const declined = await answered(display, false, "probe: the person was asked about the prompt");
373
363
  expect(declined, "probe: the person was asked about the whole prompt").toMatchObject({
374
364
  capability: "sendPrompt",
@@ -388,7 +378,7 @@ export const BEHAVIOR_PROBES = [
388
378
  {
389
379
  id: "12.raw-message",
390
380
  item: 12,
391
- title: "a prompt sent around the shell (raw ui/message, no click) is refused by the host",
381
+ title: "a prompt sent around the shell (raw ui/message, no click) is the person's to answer too; a no sends nothing",
392
382
  async run(context) {
393
383
  const display = await context.launch({
394
384
  config: prompts(),
@@ -396,17 +386,16 @@ export const BEHAVIOR_PROBES = [
396
386
  addEventListener("message", (event) => {
397
387
  if (event.data && event.data.id === "raw-1") document.body.dataset.answer = JSON.stringify(event.data.result ?? event.data.error);
398
388
  });
399
- // Late enough that no harness gesture is still active on the host page.
400
- setTimeout(() => parent.postMessage({ jsonrpc: "2.0", id: "raw-1", method: "ui/message", params: { role: "user", content: [{ type: "text", text: "sent around the shell" }] } }, "*"), ${ACTIVATION_LAPSE_MS});
389
+ parent.postMessage({ jsonrpc: "2.0", id: "raw-1", method: "ui/message", params: { role: "user", content: [{ type: "text", text: "sent around the shell" }] } }, "*");
401
390
  </script>`,
402
391
  });
403
- // Nothing is evaluated in the page until the message has been answered.
404
- await context.page.waitForTimeout(ACTIVATION_LAPSE_MS + 1_500);
405
- expect(await bodyData(display, "answer", "probe: a raw ui/message without a click is refused"), "probe: a raw ui/message without a click is refused").toBe(JSON.stringify({ isError: true }));
392
+ const asked = await answered(display, false, "probe: the person was asked about a raw ui/message");
393
+ expect(asked, "probe: the person was asked about the whole prompt").toMatchObject({
394
+ capability: "sendPrompt",
395
+ args: { text: "sent around the shell" },
396
+ });
397
+ expect(await bodyData(display, "answer", "probe: a declined raw ui/message is answered as not sent"), "probe: a declined raw ui/message is answered as not sent").toBe(JSON.stringify({ isError: true }));
406
398
  expect(await display.calls(), "probe: a raw ui/message reached the host's handler").toEqual([]);
407
- expect(await refusals(display), "probe: the host refused it for no user activation").toEqual([
408
- "sendPrompt:no-user-activation",
409
- ]);
410
399
  },
411
400
  },
412
401
  {
@@ -43,6 +43,16 @@ async function pasted(page) {
43
43
  await settle(200);
44
44
  return page.evaluate(() => document.getElementById("porthole-oracle-paste").value);
45
45
  }
46
+ /**
47
+ * Lets any user activation the test harness gave the host page lapse: Playwright's own
48
+ * evaluations count as gestures in some engines, and Chromium keeps one for 5 s. Between this and
49
+ * the next raw input, the test must not evaluate anything in the page.
50
+ */
51
+ const ACTIVATION_LAPSE_MS = 6_000;
52
+ /** The refusals the display reported, by capability. */
53
+ async function refusals(display) {
54
+ return (await display.events()).flatMap((event) => event.type === "refused" ? [`${event.detail.capability}:${event.detail.refusal}`] : []);
55
+ }
46
56
  /** Clicks `selector` in the display (a real click: the user activation a person gives). */
47
57
  async function click(display, selector) {
48
58
  await (await display.frame()).locator(selector).click();
@@ -164,9 +174,45 @@ export const CLIPBOARD_PROBES = [
164
174
  </script>`,
165
175
  });
166
176
  expect(await bodyData(display, "onload", "probe: copyText without a click is refused"), "probe: copyText without a click is refused").toMatch(/^refused/u);
167
- await click(display, "#copy");
177
+ // The host's own check needs the frame's click to reach the host page (activation
178
+ // propagates to ancestors): measured with raw input, after the harness's activation lapsed.
179
+ const frame = await display.frame();
180
+ const box = await frame.locator("#copy").boundingBox();
181
+ if (box === null) {
182
+ throw new Error("#copy is not on screen");
183
+ }
184
+ await context.page.waitForTimeout(ACTIVATION_LAPSE_MS);
185
+ await context.page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);
186
+ await context.page.waitForTimeout(500);
187
+ const refused = await refusals(display);
188
+ context.measured(`${context.engine}: a click in the frame ${refused.includes("copyText:no-user-activation") ? "does not reach" : "reaches"} the host page's user activation`);
189
+ expect(refused, "the frame's click didn't count as a gesture on the host page").toEqual([]);
168
190
  expect(await bodyData(display, "result")).toBe("true");
169
191
  expect(await display.calls(), "probe: only the click's whole text reached the host's handler").toEqual([{ capability: "copyText", args: { text: "npm test -- --run" } }]);
170
192
  },
171
193
  },
194
+ {
195
+ id: "12.raw-copy",
196
+ item: 12,
197
+ title: "a copy sent around the shell (raw porthole/copy-text, no click) is refused by the host",
198
+ async run(context) {
199
+ const display = await context.launch({
200
+ config: inline({ capabilities: { copyText: {} } }),
201
+ content: `<script>
202
+ addEventListener("message", (event) => {
203
+ if (event.data && event.data.id === "raw-1") document.body.dataset.answer = JSON.stringify(event.data.result ?? event.data.error);
204
+ });
205
+ // Late enough that no harness gesture is still active on the host page.
206
+ setTimeout(() => parent.postMessage({ jsonrpc: "2.0", id: "raw-1", method: "porthole/copy-text", params: { text: "copied around the shell" } }, "*"), ${ACTIVATION_LAPSE_MS});
207
+ </script>`,
208
+ });
209
+ // Nothing is evaluated in the page until the message has been answered.
210
+ await context.page.waitForTimeout(ACTIVATION_LAPSE_MS + 1_500);
211
+ expect(await bodyData(display, "answer", "probe: a raw copy without a click is refused"), "probe: a raw copy without a click is refused").toBe(JSON.stringify({ isError: true }));
212
+ expect(await display.calls(), "probe: a raw copy reached the host's handler").toEqual([]);
213
+ expect(await refusals(display), "probe: the host refused it for no user activation").toEqual([
214
+ "copyText:no-user-activation",
215
+ ]);
216
+ },
217
+ },
172
218
  ];