@botiverse/porthole 0.9.0 → 0.10.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.
@@ -224,8 +224,10 @@ export function servedTests(
224
224
  const display = await showMode(page, mode, instance(`${mode}-origin`));
225
225
  const frame = await display.frame();
226
226
  const origin = await frame.evaluate(() => window.origin);
227
- expect(origin).toBe(display.origin);
228
- expect(origin).not.toBe(new URL(page.url()).origin);
227
+ expect(origin, "probe: content runs on its own origin").toBe(display.origin);
228
+ expect(origin, "probe: content runs on the host's origin").not.toBe(
229
+ new URL(page.url()).origin,
230
+ );
229
231
  },
230
232
  );
231
233
 
@@ -235,7 +237,10 @@ export function servedTests(
235
237
  async ({ page }) => {
236
238
  const display = await showMode(page, mode, instance(`${mode}-reach`));
237
239
  await plantHostSecrets(page);
238
- expect(await reachIntoHost(await display.frame())).toEqual(CLOSED);
240
+ expect(
241
+ await reachIntoHost(await display.frame()),
242
+ "probe: content reached into the host",
243
+ ).toEqual(CLOSED);
239
244
  },
240
245
  );
241
246
 
@@ -267,8 +272,11 @@ export function servedTests(
267
272
  }, target);
268
273
  await frame.click("#porthole-probe-top");
269
274
  await page.waitForTimeout(SETTLE_MS);
270
- expect(page.url()).toBe(before);
271
- expect(await host.canaryHits(`${mode}-top`)).toBe(0);
275
+ expect(page.url(), "probe: the host's page stays").toBe(before);
276
+ expect(
277
+ await host.canaryHits(`${mode}-top`),
278
+ "probe: the navigation reached the canary",
279
+ ).toBe(0);
272
280
  },
273
281
  );
274
282
 
@@ -301,10 +309,16 @@ export function servedTests(
301
309
  }, target);
302
310
  await frame.click("#porthole-probe-popup");
303
311
  await page.waitForTimeout(SETTLE_MS);
304
- expect(programmatic).toBe(false);
305
- expect(await frame.evaluate(() => document.body.dataset.popup)).toBe("false");
306
- expect(opened).toHaveLength(0);
307
- expect(await host.canaryHits(`${mode}-popup`)).toBe(0);
312
+ expect(programmatic, "probe: a window opened on load").toBe(false);
313
+ expect(
314
+ await frame.evaluate(() => document.body.dataset.popup),
315
+ "probe: a window opened after a click",
316
+ ).toBe("false");
317
+ expect(opened, "probe: a window opened").toHaveLength(0);
318
+ expect(
319
+ await host.canaryHits(`${mode}-popup`),
320
+ "probe: the popup reached the canary",
321
+ ).toBe(0);
308
322
  },
309
323
  );
310
324
  }
@@ -322,10 +336,14 @@ export function servedTests(
322
336
  search: location.search,
323
337
  hash: location.hash,
324
338
  }));
325
- expect(seen.origin).toBe(display.origin);
326
- expect(seen.search).toMatch(/^(\?ticket=[^&]+)?$/u);
327
- expect(seen.hash).toBe("");
328
- expect(seen.origin).not.toBe(new URL(page.url()).origin);
339
+ expect(seen.origin, "probe: the frame's address is on its own origin").toBe(display.origin);
340
+ expect(seen.search, "probe: the frame's address carries more than the ticket").toMatch(
341
+ /^(\?ticket=[^&]+)?$/u,
342
+ );
343
+ expect(seen.hash, "probe: the frame's address carries a fragment").toBe("");
344
+ expect(seen.origin, "probe: the frame's address is the host's origin").not.toBe(
345
+ new URL(page.url()).origin,
346
+ );
329
347
  },
330
348
  );
331
349
 
@@ -346,8 +364,11 @@ export function servedTests(
346
364
  const other = await host.show(page, await host.shell("scope-b"), {
347
365
  content: SHELL_CONTENT,
348
366
  });
349
- expect(other.origin).not.toBe(first.origin);
350
- expect(await (await other.frame()).evaluate(() => localStorage.getItem("kept"))).toBeNull();
367
+ expect(other.origin, "probe: another scope shares the origin").not.toBe(first.origin);
368
+ expect(
369
+ await (await other.frame()).evaluate(() => localStorage.getItem("kept")),
370
+ "probe: another scope read the storage",
371
+ ).toBeNull();
351
372
  },
352
373
  );
353
374
 
@@ -364,9 +385,10 @@ export function servedTests(
364
385
  ] as const) {
365
386
  const frame = await display.frame();
366
387
  await expect(frame.locator("#artifact")).toHaveText(`version ${version}`);
367
- expect(await frame.evaluate(() => document.documentElement.dataset.rtc)).toBe(
368
- "undefined",
369
- );
388
+ expect(
389
+ await frame.evaluate(() => document.documentElement.dataset.rtc),
390
+ "probe: the page ran before it was hardened",
391
+ ).toBe("undefined");
370
392
  }
371
393
  },
372
394
  );
@@ -383,8 +405,11 @@ export function servedTests(
383
405
  try {
384
406
  const other = await fresh.newPage();
385
407
  const again = await other.goto(location.url);
386
- expect(again?.status(), browserName).toBe(401);
387
- expect(await other.locator("#porthole-root").count()).toBe(0);
408
+ expect(again?.status(), `probe: ${browserName}`).toBe(401);
409
+ expect(
410
+ await other.locator("#porthole-root").count(),
411
+ "probe: a used ticket showed content",
412
+ ).toBe(0);
388
413
  } finally {
389
414
  await fresh.close();
390
415
  }
@@ -428,10 +453,10 @@ export function servedTests(
428
453
  (window as unknown as { portholeProbeStays?: boolean }).portholeProbeStays === true,
429
454
  )
430
455
  .catch(() => false);
431
- expect(stays, "another content origin: the frame's document stays").toBe(true);
432
- expect(new URL(frame.url()).origin, "another content origin").toBe(display.origin);
456
+ expect(stays, "probe: another content origin: the frame's document stays").toBe(true);
457
+ expect(new URL(frame.url()).origin, "probe: another content origin").toBe(display.origin);
433
458
  await away(outside);
434
- expect(await host.canaryHits("self-navigation"), "the outside site").toBe(0);
459
+ expect(await host.canaryHits("self-navigation"), "probe: the outside site").toBe(0);
435
460
  },
436
461
  );
437
462
 
@@ -518,15 +543,18 @@ export function servedTests(
518
543
  }, target);
519
544
  await press(page, "#porthole-probe-open");
520
545
  await page.waitForTimeout(SETTLE_MS);
521
- expect(programmatic, "on load").toBe(false);
522
- expect(await page.evaluate(() => document.body.dataset.popup), "after a click").toBe(
546
+ expect(programmatic, "probe: on load").toBe(false);
547
+ expect(await page.evaluate(() => document.body.dataset.popup), "probe: after a click").toBe(
523
548
  "false",
524
549
  );
525
- expect(["absent", "refused"], "picture-in-picture").toContain(
550
+ expect(["absent", "refused"], "probe: picture-in-picture").toContain(
526
551
  await page.evaluate(() => document.body.dataset.pip),
527
552
  );
528
- expect(opened, "a window opened").toEqual([]);
529
- expect(await host.canaryHits("tab-window-open")).toBe(0);
553
+ expect(opened, "probe: a window opened").toEqual([]);
554
+ expect(
555
+ await host.canaryHits("tab-window-open"),
556
+ "probe: the window reached the canary",
557
+ ).toBe(0);
530
558
  },
531
559
  );
532
560
 
@@ -580,12 +608,12 @@ export function servedTests(
580
608
  }, urls);
581
609
  await press(page, "#porthole-probe-escape");
582
610
  await page.waitForTimeout(SETTLE_MS);
583
- expect(opened, "a window opened").toEqual([]);
584
- expect(downloads, "a download started").toEqual([]);
585
- expect(dialogs, "a browser dialog showed").toEqual([]);
586
- expect(new URL(page.url()).pathname, "the page stays").not.toMatch(/canary/u);
611
+ expect(opened, "probe: a window opened").toEqual([]);
612
+ expect(downloads, "probe: a download started").toEqual([]);
613
+ expect(dialogs, "probe: a browser dialog showed").toEqual([]);
614
+ expect(new URL(page.url()).pathname, "probe: the page stays").not.toMatch(/canary/u);
587
615
  for (const kind of kinds) {
588
- expect(await host.canaryHits(`tab-${kind}`), kind).toBe(0);
616
+ expect(await host.canaryHits(`tab-${kind}`), `probe: ${kind}`).toBe(0);
589
617
  }
590
618
  },
591
619
  );
@@ -639,8 +667,11 @@ export function servedTests(
639
667
  const away = await host.canary("tab-opener");
640
668
  await clickAway(tab, `${away}?d=secret`, "opener");
641
669
  await page.waitForTimeout(SETTLE_MS);
642
- expect(page.url(), "the opener stays").toBe("about:blank");
643
- expect(await host.canaryHits("tab-opener")).toBe(0);
670
+ expect(page.url(), "probe: the opener stays").toBe("about:blank");
671
+ expect(
672
+ await host.canaryHits("tab-opener"),
673
+ "probe: the opener's navigation reached the canary",
674
+ ).toBe(0);
644
675
  },
645
676
  );
646
677
 
@@ -831,7 +862,7 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
831
862
  }
832
863
  expect(
833
864
  tab.url(),
834
- `a ${name === "blob" ? "blob: document" : "outside site"} by ${how}: the tab stays`,
865
+ `probe: a ${name === "blob" ? "blob: document" : "outside site"} by ${how}: the tab stays`,
835
866
  ).toBe(here);
836
867
  await tab.close();
837
868
  }
@@ -842,7 +873,7 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
842
873
  ways.map(async (how) => [how, await host.canaryHits(`tab-nav-${how}`)] as const),
843
874
  )
844
875
  ).filter(([, hits]) => hits > 0);
845
- expect(heard, "the outside site heard these").toEqual([]);
876
+ expect(heard, "probe: the outside site heard these").toEqual([]);
846
877
  },
847
878
  );
848
879
 
@@ -924,7 +955,7 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
924
955
  [how, canaries[how] ?? ""] as const,
925
956
  );
926
957
  await tab.waitForTimeout(SETTLE_MS);
927
- expect(tab.url(), `${how}: the tab stays`).toBe(here);
958
+ expect(tab.url(), `probe: ${how}: the tab stays`).toBe(here);
928
959
  await tab.close();
929
960
  }
930
961
  await page.waitForTimeout(SETTLE_MS);
@@ -933,7 +964,7 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
933
964
  ways.map(async (how) => [how, await host.canaryHits(`tab-links-${how}`)] as const),
934
965
  )
935
966
  ).filter(([, hits]) => hits > 0);
936
- expect(heard, "the outside site heard these").toEqual([]);
967
+ expect(heard, "probe: the outside site heard these").toEqual([]);
937
968
  // Still as before: a fragment link jumps; a link content cancels goes nowhere.
938
969
  const tab = await freshTab();
939
970
  await tab.evaluate(() => {
@@ -1037,11 +1068,11 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
1037
1068
  const said = JSON.parse(
1038
1069
  await page.evaluate(() => document.body.dataset.devices ?? "{}"),
1039
1070
  ) as Record<string, string>;
1040
- expect(said.location, "location").toBe("denied 1");
1071
+ expect(said.location, "probe: location").toBe("denied 1");
1041
1072
  // No stream, however it is refused: a machine without a camera says NotFoundError even
1042
1073
  // where the policy would refuse (measured: Chromium, the header alone).
1043
- expect(said.media, "camera and microphone").not.toBe("granted");
1044
- expect(["rejected", "absent"], "full screen").toContain(said.fullscreen);
1074
+ expect(said.media, "probe: camera and microphone").not.toBe("granted");
1075
+ expect(["rejected", "absent"], "probe: full screen").toContain(said.fullscreen);
1045
1076
  if (warnings.length > 0) {
1046
1077
  info?.annotations.push({
1047
1078
  type: "measured",
@@ -1169,9 +1200,12 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
1169
1200
  document.body.append(button);
1170
1201
  }, canary);
1171
1202
  await press(page, "#porthole-probe-prompts");
1203
+ // A prompt the page may show waits for the person, and its report never comes: the
1204
+ // probe's verdict (P096), as much as one refused too late.
1172
1205
  await expect
1173
1206
  .poll(() => page.evaluate(() => document.body.dataset.prompts ?? ""), {
1174
1207
  timeout: 10_000,
1208
+ message: "probe: a prompt was shown and waited, instead of being refused at once",
1175
1209
  })
1176
1210
  .not.toBe("");
1177
1211
  const said = JSON.parse(
@@ -1179,17 +1213,17 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
1179
1213
  ) as Record<string, string | boolean>;
1180
1214
  const atOnce = (value: unknown) =>
1181
1215
  value === "absent" || (typeof value === "string" && /^refused \w+ at once$/u.test(value));
1182
- expect(atOnce(said.passkey), `a passkey: ${String(said.passkey)}`).toBe(true);
1183
- expect(atOnce(said.payment), `a payment: ${String(said.payment)}`).toBe(true);
1184
- expect(atOnce(said.share), `a share: ${String(said.share)}`).toBe(true);
1185
- expect(atOnce(said.applePay), `Apple Pay: ${String(said.applePay)}`).toBe(true);
1216
+ expect(atOnce(said.passkey), `probe: a passkey: ${String(said.passkey)}`).toBe(true);
1217
+ expect(atOnce(said.payment), `probe: a payment: ${String(said.payment)}`).toBe(true);
1218
+ expect(atOnce(said.share), `probe: a share: ${String(said.share)}`).toBe(true);
1219
+ expect(atOnce(said.applePay), `probe: Apple Pay: ${String(said.applePay)}`).toBe(true);
1186
1220
  expect(
1187
1221
  said.video === "absent" || String(said.video).startsWith("refused"),
1188
- `a video's full screen: ${String(said.video)}`,
1222
+ `probe: a video's full screen: ${String(said.video)}`,
1189
1223
  ).toBe(true);
1190
- expect(said.shown, "a video in full screen").toBe(false);
1224
+ expect(said.shown, "probe: a video in full screen").toBe(false);
1191
1225
  await page.waitForTimeout(SETTLE_MS);
1192
- expect(await host.canaryHits("tab-payment"), "the payment method's address").toBe(0);
1226
+ expect(await host.canaryHits("tab-payment"), "probe: the payment method's address").toBe(0);
1193
1227
  },
1194
1228
  );
1195
1229
 
@@ -1215,8 +1249,10 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
1215
1249
  setTimeout(() => resolve(unreachable), 3_000),
1216
1250
  ),
1217
1251
  ]);
1218
- expect(shown.root).toBe(false);
1219
- expect(shown.origin).not.toBe(location.origin);
1252
+ expect(shown.root, "probe: a foreign origin framed the content").toBe(false);
1253
+ expect(shown.origin, "probe: a foreign origin framed the content's origin").not.toBe(
1254
+ location.origin,
1255
+ );
1220
1256
  }
1221
1257
  },
1222
1258
  );
@@ -1266,8 +1302,8 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
1266
1302
  return { fetched, policy: policies.find((policy) => /connect-src/u.test(policy)) ?? "" };
1267
1303
  }, urls);
1268
1304
  await page.waitForTimeout(SETTLE_MS);
1269
- expect(seen.fetched).toBe("blocked");
1270
- expect(seen.policy, "a CSP applied to the document").not.toBe("");
1305
+ expect(seen.fetched, "probe: the fetch got out").toBe("blocked");
1306
+ expect(seen.policy, "probe: a CSP applied to the document").not.toBe("");
1271
1307
  const sources = new Map(
1272
1308
  seen.policy
1273
1309
  .split(";")
@@ -1276,10 +1312,10 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
1276
1312
  );
1277
1313
  // What runs or talks never opens to any site (P059), whatever the config.
1278
1314
  for (const name of ["script-src", "style-src", "connect-src", "frame-src", "default-src"]) {
1279
- expect(sources.get(name) ?? [], `${name} opens no scheme`).not.toContain("https:");
1315
+ expect(sources.get(name) ?? [], `probe: ${name} opens no scheme`).not.toContain("https:");
1280
1316
  }
1281
1317
  for (const kind of ["fetch", "script", "style", "frame"] as const) {
1282
- expect(await host.canaryHits(`egress-${kind}`), kind).toBe(0);
1318
+ expect(await host.canaryHits(`egress-${kind}`), `probe: ${kind}`).toBe(0);
1283
1319
  }
1284
1320
  // Images and media: closed, unless the config opened them to any https site (P059);
1285
1321
  // then, the canary being an https site, an image reaches it, as the config means.
@@ -1299,10 +1335,10 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
1299
1335
  "the image, as the config opens it",
1300
1336
  ).toBeGreaterThan(0);
1301
1337
  } else {
1302
- expect(await host.canaryHits("egress-img"), "img").toBe(0);
1338
+ expect(await host.canaryHits("egress-img"), "probe: img").toBe(0);
1303
1339
  }
1304
1340
  if (!https("media")) {
1305
- expect(await host.canaryHits("egress-media"), "media").toBe(0);
1341
+ expect(await host.canaryHits("egress-media"), "probe: media").toBe(0);
1306
1342
  }
1307
1343
  },
1308
1344
  );
@@ -1330,11 +1366,18 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
1330
1366
  await expect
1331
1367
  .poll(async () => methodsOf(await display.received()))
1332
1368
  .toContain(MCP_APPS_METHODS.initialize);
1333
- await expect(frame.locator("html")).toHaveAttribute("data-fetch", "blocked");
1369
+ await expect(
1370
+ frame.locator("html"),
1371
+ "probe: the view's undeclared fetch got out",
1372
+ ).toHaveAttribute("data-fetch", "blocked");
1334
1373
  expect(
1335
1374
  await frame.evaluate(() => [window.origin, document.documentElement.dataset.rtc]),
1375
+ "probe: the view runs hardened on its own origin",
1336
1376
  ).toEqual([display.origin, "undefined"]);
1337
- expect(await host.canaryHits("proxy-undeclared")).toBe(0);
1377
+ expect(
1378
+ await host.canaryHits("proxy-undeclared"),
1379
+ "probe: the undeclared fetch reached the canary",
1380
+ ).toBe(0);
1338
1381
  },
1339
1382
  );
1340
1383
 
@@ -1350,7 +1393,10 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
1350
1393
  resourceReady('<p id="view">Not from the host.</p>'),
1351
1394
  );
1352
1395
  await page.waitForTimeout(SETTLE_MS);
1353
- expect(await frame.locator("#view").count()).toBe(0);
1396
+ expect(
1397
+ await frame.locator("#view").count(),
1398
+ "probe: the proxy took a view not from its host",
1399
+ ).toBe(0);
1354
1400
  },
1355
1401
  );
1356
1402
 
@@ -1383,9 +1429,10 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
1383
1429
  const other = await fresh.newPage();
1384
1430
  const bare = await other.goto(`${location.origin}/`);
1385
1431
  const away = new URL(other.url()).origin !== location.origin;
1386
- expect(bare?.status() === 401 || away, `ended at ${other.url()}`).toBe(true);
1432
+ expect(bare?.status() === 401 || away, `probe: ended at ${other.url()}`).toBe(true);
1387
1433
  expect(
1388
1434
  await other.evaluate(() => document.documentElement.dataset.app ?? null),
1435
+ "probe: the app ran without its ticket's cookie",
1389
1436
  ).toBeNull();
1390
1437
  } finally {
1391
1438
  await fresh.close();
@@ -1470,7 +1517,7 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
1470
1517
  const b = await host.show(page, await host.app("url-siblings-b"));
1471
1518
  const frameB = await b.frame();
1472
1519
  await ready(frameB);
1473
- expect(await load(frameB, script), "another app's frame loading it").toBe("error");
1520
+ expect(await load(frameB, script), "probe: another app's frame loading it").toBe("error");
1474
1521
  }
1475
1522
  // Each on a tab of its own, in one browser.
1476
1523
  const c = await host.locate(await host.app("url-siblings-c"));
@@ -1483,7 +1530,9 @@ navigator.mediaDevices && navigator.mediaDevices.getUserMedia({ video: true }).t
1483
1530
  expect(await load(tab.mainFrame(), script), "the app's own load").toBe("load");
1484
1531
  await tab.goto(d.url);
1485
1532
  await ready(tab.mainFrame());
1486
- expect(await load(tab.mainFrame(), script), "another app's tab loading it").toBe("error");
1533
+ expect(await load(tab.mainFrame(), script), "probe: another app's tab loading it").toBe(
1534
+ "error",
1535
+ );
1487
1536
  } finally {
1488
1537
  await tab.close();
1489
1538
  }
@@ -194,12 +194,45 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
194
194
  toFrame(ANNOTATE_METHODS.start, { ...annotating });
195
195
  }
196
196
  };
197
+ /**
198
+ * The frame's viewport as the platform tells it now; undefined where it can't (no
199
+ * `viewport`, or one that answers no size or throws, P105): every box is then nothing at the
200
+ * frame's corner, and nothing throws out of the frame's listener.
201
+ */
202
+ const frameViewport = (): { width: number; height: number } | undefined => {
203
+ try {
204
+ const viewport: unknown = surface?.viewport?.();
205
+ if (viewport === null || typeof viewport !== "object") {
206
+ return undefined;
207
+ }
208
+ const size = viewport as { width?: unknown; height?: unknown };
209
+ const across = size.width;
210
+ const down = size.height;
211
+ return typeof across === "number" && typeof down === "number"
212
+ ? { width: across, height: down }
213
+ : undefined;
214
+ } catch {
215
+ return undefined;
216
+ }
217
+ };
218
+ /**
219
+ * Whether the person is known to have made no gesture just now (P105): the platform says the
220
+ * page has no transient activation, or fails to say. Where it can't tell (undefined), as for
221
+ * the gesture gate, a report passes.
222
+ */
223
+ const noGesture = (): boolean => {
224
+ try {
225
+ return surface?.userActivation() === false;
226
+ } catch {
227
+ return true;
228
+ }
229
+ };
197
230
  /**
198
231
  * Every box a report carries, clamped to the frame's viewport as it is now (P104): the page
199
232
  * places the host's own UI nowhere outside its frame.
200
233
  */
201
234
  const withinFrame = (report: AnnotationReport): AnnotationReport => {
202
- const viewport = surface?.viewport?.();
235
+ const viewport = frameViewport();
203
236
  switch (report.type) {
204
237
  case "selected":
205
238
  case "activated":
@@ -220,7 +253,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
220
253
  /**
221
254
  * A report from the frame: checked, taken only while the host asked for it (a selection
222
255
  * only in select mode, results only for its own marks, a marker's click only for a mark it
223
- * shows with one), then through the bridge's gates.
256
+ * shows with one, within a gesture), then through the bridge's gates.
224
257
  */
225
258
  const onAnnotation = (raw: unknown, through: HostFunctionBridge) => {
226
259
  if (
@@ -280,6 +313,13 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
280
313
  if (!marks.some((mark) => mark.id === id && mark.count !== undefined)) {
281
314
  return;
282
315
  }
316
+ // A marker's real click gives the host's page transient activation (measured on all
317
+ // three engines, P105); a click a page posts at load, on a timer or on a scroll has
318
+ // none and is dropped. One posted on the person's own press in the content passes: the
319
+ // host's view guards itself against that (THREAT_MODEL §6).
320
+ if (noGesture()) {
321
+ return;
322
+ }
283
323
  break;
284
324
  }
285
325
  }
@@ -35,13 +35,15 @@ export interface Surface {
35
35
  setColorScheme(scheme: ColorScheme): void;
36
36
  /**
37
37
  * Whether the embedding page has transient user activation now (a gesture in the frame
38
- * activates its ancestors), or undefined where the platform can't tell.
38
+ * activates its ancestors), or undefined where the platform can't tell. The gesture gate reads
39
+ * it, and so does a marker's click (P105): false, or a throw, drops it.
39
40
  */
40
41
  userActivation(): boolean | undefined;
41
42
  /**
42
43
  * The frame's viewport now, CSS px (its content box): what a box the frame reports is clamped
43
44
  * to (P104). Undefined, or absent, where the platform can't tell: every reported box is then
44
- * clamped to nothing, at the frame's corner.
45
+ * clamped to nothing, at the frame's corner, as it is for an answer that isn't a size, or a
46
+ * throw (P105).
45
47
  */
46
48
  viewport?(): { readonly width: number; readonly height: number } | undefined;
47
49
  /**