@botiverse/porthole 0.7.0 → 0.9.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 (166) hide show
  1. package/README.md +9 -2
  2. package/THIRD_PARTY_NOTICES.md +421 -0
  3. package/dist/annotate/types.d.ts +40 -4
  4. package/dist/annotate/types.js +6 -1
  5. package/dist/annotate/validate.d.ts +10 -0
  6. package/dist/annotate/validate.js +24 -1
  7. package/dist/bridge/bounded-text.d.ts +34 -0
  8. package/dist/bridge/bounded-text.js +188 -0
  9. package/dist/bridge/bridge.d.ts +25 -5
  10. package/dist/bridge/bridge.js +311 -73
  11. package/dist/bridge/json-data.d.ts +28 -0
  12. package/dist/bridge/json-data.js +86 -0
  13. package/dist/bridge/navigation.d.ts +5 -0
  14. package/dist/bridge/navigation.js +7 -0
  15. package/dist/bridge/refusal.js +1 -0
  16. package/dist/bridge/types.d.ts +32 -1
  17. package/dist/check/page-source.js +1 -1
  18. package/dist/check/page.js +2 -0
  19. package/dist/compile/compile.d.ts +6 -0
  20. package/dist/compile/compile.js +3 -1
  21. package/dist/compile/policy.d.ts +38 -2
  22. package/dist/compile/policy.js +122 -7
  23. package/dist/config/capabilities.d.ts +23 -4
  24. package/dist/config/capabilities.js +12 -2
  25. package/dist/config/schema.d.ts +11 -0
  26. package/dist/config/validate.d.ts +8 -2
  27. package/dist/config/validate.js +28 -6
  28. package/dist/config/warnings.d.ts +20 -0
  29. package/dist/config/warnings.js +25 -0
  30. package/dist/conformance/behavior.js +46 -1
  31. package/dist/conformance/cookies.d.ts +15 -0
  32. package/dist/conformance/cookies.js +80 -0
  33. package/dist/conformance/harness/page.d.ts +1 -0
  34. package/dist/conformance/harness/page.js +9 -2
  35. package/dist/conformance/harness-source.js +1 -1
  36. package/dist/conformance/host-kit.js +5 -1
  37. package/dist/conformance/index.d.ts +10 -0
  38. package/dist/conformance/limits.js +38 -1
  39. package/dist/conformance/runtime.js +10 -0
  40. package/dist/conformance/served.d.ts +2 -0
  41. package/dist/conformance/served.js +737 -4
  42. package/dist/files/paths.js +4 -0
  43. package/dist/guide/gates.d.ts +7 -1
  44. package/dist/guide/gates.js +12 -0
  45. package/dist/guide/guide.js +2 -2
  46. package/dist/guide/runtime.js +11 -3
  47. package/dist/host/create-host.js +81 -39
  48. package/dist/host/pages-of-set.d.ts +43 -0
  49. package/dist/host/pages-of-set.js +196 -0
  50. package/dist/host/types.d.ts +8 -1
  51. package/dist/index.d.ts +5 -4
  52. package/dist/index.js +3 -2
  53. package/dist/mcp/adapter.js +11 -15
  54. package/dist/node/index.d.ts +36 -4
  55. package/dist/node/index.js +402 -101
  56. package/dist/platform/types.d.ts +9 -0
  57. package/dist/platform/web.js +8 -0
  58. package/dist/presets/presets.d.ts +16 -8
  59. package/dist/presets/presets.js +39 -8
  60. package/dist/protocol/live-data.d.ts +6 -2
  61. package/dist/protocol/live-data.js +20 -1
  62. package/dist/protocol/mcp-apps.d.ts +13 -2
  63. package/dist/protocol/mcp-apps.js +10 -2
  64. package/dist/protocol/message-text.d.ts +8 -0
  65. package/dist/protocol/message-text.js +29 -0
  66. package/dist/protocol/runtime-calls.js +3 -0
  67. package/dist/protocol/shell-adapter.js +16 -22
  68. package/dist/react/context-notice.d.ts +32 -0
  69. package/dist/react/context-notice.js +28 -0
  70. package/dist/react/dialog.js +62 -18
  71. package/dist/react/frame.d.ts +18 -3
  72. package/dist/react/frame.js +79 -2
  73. package/dist/react/index.d.ts +2 -1
  74. package/dist/react/index.js +2 -1
  75. package/dist/runtime/contract.d.ts +9 -1
  76. package/dist/runtime/contract.js +31 -2
  77. package/dist/runtime/db.d.ts +41 -6
  78. package/dist/runtime/db.js +120 -16
  79. package/dist/runtime/declaration.d.ts +15 -1
  80. package/dist/runtime/declaration.js +184 -87
  81. package/dist/runtime/requests.js +27 -11
  82. package/dist/runtime/types.generated.js +1 -1
  83. package/dist/server/files.d.ts +5 -0
  84. package/dist/server/files.js +22 -7
  85. package/dist/server/host.d.ts +18 -1
  86. package/dist/server/host.js +132 -2
  87. package/dist/server/index.d.ts +1 -1
  88. package/dist/server/index.js +1 -1
  89. package/dist/server/peer.d.ts +4 -0
  90. package/dist/server/peer.js +19 -0
  91. package/dist/server/proxy.d.ts +6 -0
  92. package/dist/server/proxy.js +12 -3
  93. package/dist/server/server.js +113 -26
  94. package/dist/server/types.d.ts +6 -3
  95. package/dist/shell/annotate.d.ts +7 -2
  96. package/dist/shell/annotate.js +233 -15
  97. package/dist/shell/document.d.ts +8 -0
  98. package/dist/shell/document.js +3 -0
  99. package/dist/shell/runtime.js +361 -14
  100. package/docs/ADOPTING.md +119 -14
  101. package/docs/ARCHITECTURE.md +15 -4
  102. package/docs/DECISIONS.md +1610 -9
  103. package/docs/DESIGN.md +114 -30
  104. package/docs/THREAT_MODEL.md +652 -0
  105. package/package.json +14 -3
  106. package/src/annotate/types.ts +37 -5
  107. package/src/annotate/validate.ts +30 -1
  108. package/src/bridge/bounded-text.ts +240 -0
  109. package/src/bridge/bridge.ts +373 -84
  110. package/src/bridge/json-data.ts +95 -0
  111. package/src/bridge/navigation.ts +10 -0
  112. package/src/bridge/refusal.ts +1 -0
  113. package/src/bridge/types.ts +30 -1
  114. package/src/check/page.ts +2 -0
  115. package/src/compile/compile.ts +9 -1
  116. package/src/compile/policy.ts +130 -7
  117. package/src/config/capabilities.ts +22 -3
  118. package/src/config/schema.ts +11 -0
  119. package/src/config/validate.ts +43 -5
  120. package/src/config/warnings.ts +42 -0
  121. package/src/conformance/behavior.ts +54 -1
  122. package/src/conformance/cookies.ts +93 -0
  123. package/src/conformance/harness/page.ts +11 -2
  124. package/src/conformance/host-kit.ts +10 -1
  125. package/src/conformance/index.ts +10 -0
  126. package/src/conformance/limits.ts +39 -1
  127. package/src/conformance/runtime.ts +21 -0
  128. package/src/conformance/served.ts +888 -4
  129. package/src/files/paths.ts +4 -0
  130. package/src/guide/gates.ts +13 -1
  131. package/src/guide/guide.ts +3 -3
  132. package/src/guide/runtime.ts +12 -3
  133. package/src/host/create-host.ts +88 -38
  134. package/src/host/pages-of-set.ts +226 -0
  135. package/src/host/types.ts +15 -1
  136. package/src/index.ts +5 -0
  137. package/src/mcp/adapter.ts +16 -20
  138. package/src/node/index.ts +507 -116
  139. package/src/platform/types.ts +6 -0
  140. package/src/platform/web.ts +10 -0
  141. package/src/presets/presets.ts +60 -17
  142. package/src/protocol/live-data.ts +31 -3
  143. package/src/protocol/mcp-apps.ts +11 -2
  144. package/src/protocol/message-text.ts +36 -0
  145. package/src/protocol/runtime-calls.ts +3 -0
  146. package/src/protocol/shell-adapter.ts +27 -23
  147. package/src/react/context-notice.tsx +95 -0
  148. package/src/react/dialog.tsx +77 -17
  149. package/src/react/frame.tsx +107 -2
  150. package/src/react/index.ts +8 -1
  151. package/src/runtime/contract.ts +36 -2
  152. package/src/runtime/db.ts +140 -20
  153. package/src/runtime/declaration.ts +227 -89
  154. package/src/runtime/requests.ts +27 -11
  155. package/src/runtime/types.generated.ts +1 -1
  156. package/src/server/files.ts +29 -11
  157. package/src/server/host.ts +158 -3
  158. package/src/server/index.ts +1 -0
  159. package/src/server/peer.ts +21 -0
  160. package/src/server/proxy.ts +13 -3
  161. package/src/server/server.ts +139 -36
  162. package/src/server/types.ts +6 -3
  163. package/src/shell/annotate.ts +233 -15
  164. package/src/shell/document.ts +8 -0
  165. package/src/shell/runtime.ts +361 -14
  166. package/types/runtime/v1/context.d.ts +13 -2
@@ -5,21 +5,26 @@
5
5
  * in one).
6
6
  *
7
7
  * The host drives it (`porthole/annotate.start|stop|show|focus|clear`) and it reports
8
- * (`porthole/annotate.selected|unselected|cancelled|anchored`):
8
+ * (`porthole/annotate.selected|unselected|cancelled|anchored|activated`):
9
9
  * - picking an element: the element under the pointer (or finger) is outlined with its name; a
10
10
  * click or tap picks it, and the content's own handlers never see that click; Escape cancels;
11
11
  * - selecting text: each selection that settles is reported, with where it is, and its clearing;
12
12
  * - marks: each anchor is found in the content as it is now (its CSS selector, its text where it
13
13
  * was, its text anywhere, its words with any spacing) and drawn over it, in a layer of the
14
14
  * shell's own (a closed shadow root), again whenever the content changes; what can't be found
15
- * is reported `orphaned`.
15
+ * is reported `orphaned`;
16
+ * - markers (P104): a mark with a count gets a small bubble with the number at its anchor's end;
17
+ * a click on it is reported (`activated`), and the content's own handlers never see it;
18
+ * - following: while a mark has a marker, once a scroll, a resize or a change of the content
19
+ * settles, the marks that moved since the host was last told are reported, at most once a
20
+ * second, so the host's own UI beside a mark can follow.
16
21
  *
17
22
  * It shares the realm with the content, which can interfere with all of it: the host takes its
18
23
  * reports as UI hints only.
19
24
  */
20
25
  export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
21
26
  (() => {
22
- const LIMIT = { exact: 4000, quote: 300, context: 32, label: 120, css: 1000, marks: 500, boxes: 200 };
27
+ const LIMIT = { exact: 4000, quote: 300, context: 32, label: 120, css: 1000, marks: 500, boxes: 200, count: 999 };
23
28
  const M = {
24
29
  start: "porthole/annotate.start",
25
30
  stop: "porthole/annotate.stop",
@@ -30,6 +35,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
30
35
  unselected: "porthole/annotate.unselected",
31
36
  cancelled: "porthole/annotate.cancelled",
32
37
  anchored: "porthole/annotate.anchored",
38
+ activated: "porthole/annotate.activated",
33
39
  };
34
40
  // The DOM's own functions, taken before content runs.
35
41
  const elementFromPoint = Document.prototype.elementFromPoint;
@@ -37,11 +43,13 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
37
43
  const createRange = Document.prototype.createRange;
38
44
  const createTreeWalker = Document.prototype.createTreeWalker;
39
45
  const createElement = Document.prototype.createElement;
46
+ const createElementNS = Document.prototype.createElementNS;
40
47
  const selectionOf = Document.prototype.getSelection;
41
48
  const elementRect = Element.prototype.getBoundingClientRect;
42
49
  const rangeRect = Range.prototype.getBoundingClientRect;
43
50
  const rangeRects = Range.prototype.getClientRects;
44
51
  const attachShadow = Element.prototype.attachShadow;
52
+ const getAttribute = Element.prototype.getAttribute;
45
53
  const post = window.parent.postMessage.bind(window.parent);
46
54
  const tell = (method, params) => {
47
55
  if (window.parent !== window) {
@@ -191,7 +199,13 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
191
199
  for (const each of classes) {
192
200
  name += "." + each;
193
201
  }
194
- const words = squash(element.textContent || "").slice(0, 40);
202
+ // An element without words (an image, an icon button, a chart) is named by what it says it is.
203
+ let words = squash(element.textContent || "");
204
+ for (const attribute of ["alt", "aria-label", "title"]) {
205
+ if (words) break;
206
+ words = squash(getAttribute.call(element, attribute) || "");
207
+ }
208
+ words = words.slice(0, 40);
195
209
  return (words ? name + " " + words : name).slice(0, LIMIT.label);
196
210
  };
197
211
  const quoteOf = (index, start, end) => {
@@ -343,16 +357,24 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
343
357
  // Marks lie over the content's text, so their fill is light (the text under them keeps its
344
358
  // contrast, on a light page and a dark one alike) and an underline or outline says where
345
359
  // they are; the active one and a flash add a ring around it, not more fill over its words.
346
- const STYLE = ".mark{position:absolute;border-radius:2px;background:rgba(250,204,21,.18);box-shadow:inset 0 -2px 0 rgba(234,179,8,.95)}.mark.element{background:rgba(250,204,21,.07);box-shadow:none;outline:2px solid rgba(234,179,8,.9);outline-offset:1px}.mark.active{background:rgba(250,204,21,.26);box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 2px rgba(234,179,8,.45)}.mark.element.active{background:rgba(250,204,21,.12);box-shadow:none;outline-width:3px}.mark.flash{animation:flash 1.8s ease-out}@keyframes flash{from{box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 6px rgba(250,204,21,.6)}}.hover{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.12)}.tag{position:absolute;max-width:70vw;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:12px/18px ui-monospace,SFMono-Regular,Menlo,monospace;padding:0 6px;border-radius:4px;background:#1e293b;color:#fff}";
360
+ // An element's mark with a marker is quieter (a thin line): the marker says what it is.
361
+ // A marker is a small bubble with a number, drawn in its own colors and font (only what the
362
+ // layer inherits from the page could reach it, so each of those is set here).
363
+ const STYLE = ".mark{position:absolute;border-radius:2px;background:rgba(250,204,21,.18);box-shadow:inset 0 -2px 0 rgba(234,179,8,.95)}.mark.element{background:rgba(250,204,21,.07);box-shadow:none;outline:2px solid rgba(234,179,8,.9);outline-offset:1px}.mark.active{background:rgba(250,204,21,.26);box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 2px rgba(234,179,8,.45)}.mark.element.active{background:rgba(250,204,21,.12);box-shadow:none;outline-width:3px}.mark.element.quiet{background:rgba(250,204,21,.05);outline:1px solid rgba(234,179,8,.6);outline-offset:2px}.mark.element.quiet.active{background:rgba(250,204,21,.1);outline:2px solid rgba(234,179,8,.9)}.marker{position:absolute;box-sizing:border-box;height:18px;min-width:18px;display:flex;align-items:center;justify-content:center;gap:3px;margin:0;padding:0 5px;border:1px solid rgba(161,98,7,.6);border-radius:9px 9px 9px 2px;background:#fde68a;color:#422006;box-shadow:0 1px 2px rgba(0,0,0,.3);font:600 11px/16px system-ui,-apple-system,Segoe UI,Roboto,sans-serif;font-style:normal;letter-spacing:0;word-spacing:0;text-transform:none;text-indent:0;text-shadow:none;direction:ltr;writing-mode:horizontal-tb;white-space:nowrap;user-select:none;-webkit-user-select:none;cursor:pointer;pointer-events:auto}.marker:hover{background:#fcd34d}.marker.active{background:#facc15;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.3)}.marker.inert{pointer-events:none}.marker svg{display:block;width:11px;height:11px;flex:none}.mark.flash{animation:flash 1.8s ease-out}@keyframes flash{from{box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 6px rgba(250,204,21,.6)}}.hover{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.12)}.tag{position:absolute;max-width:70vw;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:12px/18px ui-monospace,SFMono-Regular,Menlo,monospace;padding:0 6px;border-radius:4px;background:#1e293b;color:#fff}";
364
+ // Inline and important: the content's own style sheets can't hide, shrink or move it by
365
+ // accident. Set again at each draw, since its scripts can rewrite it (narrowing only: the
366
+ // content can still cover the layer, or move it with its ancestors, P104).
367
+ const LAYER_STYLE = "position:fixed!important;inset:0!important;width:auto!important;height:auto!important;min-width:0!important;min-height:0!important;max-width:none!important;max-height:none!important;display:block!important;visibility:visible!important;opacity:1!important;pointer-events:none!important;z-index:2147483647!important;overflow:hidden!important;margin:0!important;padding:0!important;border:0!important;background:none!important;transform:none!important;scale:none!important;translate:none!important;rotate:none!important;zoom:1!important;clip-path:none!important;mask:none!important;filter:none!important;content-visibility:visible!important;contain:none!important";
347
368
  const ensureLayer = () => {
348
369
  if (layer === null) {
349
370
  layer = createElement.call(document, "div");
350
371
  layer.setAttribute("aria-hidden", "true");
351
372
  layer.setAttribute("data-porthole-annotations", "");
352
- // Inline and important: the content's own styles can't hide or move it by accident.
353
- layer.style.cssText = "position:fixed!important;inset:0!important;display:block!important;visibility:visible!important;opacity:1!important;pointer-events:none!important;z-index:2147483647!important;overflow:hidden!important;margin:0!important;padding:0!important;border:0!important;background:none!important;transform:none!important";
354
373
  shadow = attachShadow.call(layer, { mode: "closed" });
355
374
  }
375
+ if (layer.style.cssText !== LAYER_STYLE) {
376
+ layer.style.cssText = LAYER_STYLE;
377
+ }
356
378
  if (!layer.isConnected) {
357
379
  document.documentElement.appendChild(layer);
358
380
  }
@@ -362,6 +384,68 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
362
384
  let mode = { elements: false, text: false };
363
385
  let hover = null;
364
386
  let marks = [];
387
+ // The markers as last drawn, for a click to find: { id, element }. Each mark keeps its
388
+ // marker's node across draws, so a press that spans a redraw ends on the node it began on.
389
+ let markers = [];
390
+ const markerNodes = new Map();
391
+ const MARKER_HEIGHT = 18;
392
+ const SVG = "http://www.w3.org/2000/svg";
393
+ const markerOf = (mark, rects, overlaps) => {
394
+ let at = null;
395
+ for (let i = rects.length - 1; i >= 0 && at === null; i -= 1) {
396
+ if (rects[i].width !== 0 || rects[i].height !== 0) {
397
+ at = rects[i];
398
+ }
399
+ }
400
+ if (at === null) {
401
+ return null;
402
+ }
403
+ const label = mark.count === 0 ? "" : mark.count > 99 ? "99+" : String(mark.count);
404
+ // Its size, near enough to place it: the padding and the glyph, then the number.
405
+ const width = Math.max(MARKER_HEIGHT, 23 + (label === "" ? 0 : 3 + label.length * 7));
406
+ const room = document.documentElement.clientWidth || window.innerWidth;
407
+ // At the end of a text anchor's last line, raised; on an element's top right corner.
408
+ let left = mark.found.range ? at.right + 2 : at.right - width / 2;
409
+ let top = at.top - MARKER_HEIGHT / 2 - (mark.found.range ? 3 : 0);
410
+ // Not cut off at the frame's top while its anchor is in view; with its anchor as it goes.
411
+ if (top < 2) {
412
+ top = Math.min(2, at.bottom - MARKER_HEIGHT);
413
+ }
414
+ // Two marks ending in one place: the later marker goes beside the earlier one.
415
+ for (let tries = 0; tries < 20; tries += 1) {
416
+ const hit = overlaps.filter((other) => Math.abs(other.top - top) < MARKER_HEIGHT && left < other.left + other.width + 2 && other.left < left + width + 2)[0];
417
+ if (!hit) {
418
+ break;
419
+ }
420
+ left = hit.left + hit.width + 2;
421
+ }
422
+ left = Math.max(2, Math.min(left, room - width - 2));
423
+ overlaps.push({ left, top, width });
424
+ const kept = markerNodes.get(mark.id);
425
+ const marker = kept ? kept.element : createElement.call(document, "div");
426
+ marker.className = "marker" + (mark.id === active ? " active" : "") + (mode.elements ? " inert" : "");
427
+ marker.style.cssText = "left:" + left + "px;top:" + top + "px";
428
+ markers.push({ id: mark.id, element: marker });
429
+ if (kept && kept.label === label) {
430
+ return marker;
431
+ }
432
+ markerNodes.set(mark.id, { element: marker, label });
433
+ marker.replaceChildren();
434
+ const glyph = createElementNS.call(document, SVG, "svg");
435
+ glyph.setAttribute("viewBox", "0 0 16 16");
436
+ glyph.setAttribute("aria-hidden", "true");
437
+ const path = createElementNS.call(document, SVG, "path");
438
+ path.setAttribute("fill", "currentColor");
439
+ path.setAttribute("d", "M3 2h10a2 2 0 0 1 2 2v6a2 2 0 0 1-2 2H8l-4 3v-3H3a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2z");
440
+ glyph.appendChild(path);
441
+ marker.appendChild(glyph);
442
+ if (label !== "") {
443
+ const number = createElement.call(document, "span");
444
+ number.textContent = label;
445
+ marker.appendChild(number);
446
+ }
447
+ return marker;
448
+ };
365
449
  let active = null;
366
450
  let flashing = null;
367
451
  let flashUntil = 0;
@@ -378,6 +462,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
378
462
  style.textContent = STYLE;
379
463
  parts.push(style);
380
464
  const flashOn = Date.now() < flashUntil;
465
+ // Markers go over every mark, in the order of the marks.
466
+ const badges = [];
467
+ const overlaps = [];
468
+ markers = [];
381
469
  for (const mark of marks) {
382
470
  if (mark.found === null) {
383
471
  continue;
@@ -388,10 +476,24 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
388
476
  continue;
389
477
  }
390
478
  const each = createElement.call(document, "div");
391
- each.className = "mark " + (mark.found.range ? "text" : "element") + (mark.id === active ? " active" : "") + (flashOn && mark.id === flashing ? " flash" : "");
479
+ each.className = "mark " + (mark.found.range ? "text" : "element") + (mark.count === null ? "" : " quiet") + (mark.id === active ? " active" : "") + (flashOn && mark.id === flashing ? " flash" : "");
392
480
  each.style.cssText = "left:" + rect.left + "px;top:" + rect.top + "px;width:" + rect.width + "px;height:" + rect.height + "px";
393
481
  parts.push(each);
394
482
  }
483
+ if (mark.count !== null) {
484
+ const marker = markerOf(mark, rects, overlaps);
485
+ if (marker !== null) {
486
+ badges.push(marker);
487
+ }
488
+ }
489
+ }
490
+ for (const marker of badges) {
491
+ parts.push(marker);
492
+ }
493
+ for (const id of Array.from(markerNodes.keys())) {
494
+ if (!markers.some((each) => each.id === id)) {
495
+ markerNodes.delete(id);
496
+ }
395
497
  }
396
498
  if (hover !== null && hover.isConnected) {
397
499
  const rect = elementRect.call(hover);
@@ -418,8 +520,31 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
418
520
  };
419
521
 
420
522
  const resultOf = (mark) => (mark.found === null ? { id: mark.id, state: "orphaned" } : { id: mark.id, state: "attached", rect: box(rectOf(mark.found)) });
421
- // Finds every mark again; tells the host every result (after show) or only when one changed.
422
- const anchorAll = (all) => {
523
+ // What the host was last told of each mark (mark.told), so a settle tells only what moved.
524
+ const moved = (mark, result) => {
525
+ const told = mark.told;
526
+ if (!told || told.state !== result.state) {
527
+ return true;
528
+ }
529
+ if (result.state !== "attached") {
530
+ return false;
531
+ }
532
+ const a = told.rect;
533
+ const b = result.rect;
534
+ return Math.abs(a.x - b.x) > 0.5 || Math.abs(a.y - b.y) > 0.5 || Math.abs(a.width - b.width) > 0.5 || Math.abs(a.height - b.height) > 0.5;
535
+ };
536
+ const report = (pairs) => {
537
+ if (pairs.length > 0) {
538
+ for (const pair of pairs) {
539
+ pair.mark.told = pair.result;
540
+ }
541
+ tell(M.anchored, { results: pairs.map((pair) => pair.result) });
542
+ }
543
+ };
544
+ const resultsOf = (only) => marks.map((mark) => ({ mark, result: resultOf(mark) })).filter((pair) => !only || moved(pair.mark, pair.result));
545
+ // Finds every mark again; tells the host every result (after show, or when a state changed),
546
+ // only the marks that moved (once the content is quiet), or nothing.
547
+ const anchorAll = (all, quiet) => {
423
548
  const index = textIndex();
424
549
  let changed = false;
425
550
  for (const mark of marks) {
@@ -437,7 +562,9 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
437
562
  mark.state = state;
438
563
  }
439
564
  if (all || changed) {
440
- tell(M.anchored, { results: marks.map(resultOf) });
565
+ report(resultsOf(false));
566
+ } else if (quiet) {
567
+ follow();
441
568
  }
442
569
  draw();
443
570
  };
@@ -469,18 +596,25 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
469
596
  deadline = now + 1000;
470
597
  }
471
598
  clearTimeout(anchorTimer);
599
+ // A run that waited its whole pause found the content quiet; one cut short by the deadline
600
+ // didn't, and tells only states (what moved is told once it is quiet).
601
+ const wait = Math.max(0, Math.min(150, deadline - now));
472
602
  anchorTimer = setTimeout(() => {
473
603
  anchorTimer = 0;
474
604
  deadline = 0;
475
605
  const every = reportAll;
476
606
  reportAll = false;
477
- anchorAll(every);
607
+ anchorAll(every, wait === 150);
608
+ if (wait !== 150) {
609
+ // Cut short by the deadline: what moved is told once the content has been quiet.
610
+ settle();
611
+ }
478
612
  if (pendingFocus !== null) {
479
613
  const id = pendingFocus;
480
614
  pendingFocus = null;
481
615
  focus(id);
482
616
  }
483
- }, Math.max(0, Math.min(150, deadline - now)));
617
+ }, wait);
484
618
  };
485
619
  new MutationObserver((records) => {
486
620
  if (marks.length === 0) {
@@ -496,6 +630,51 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
496
630
  }).observe(document, { childList: true, subtree: true, characterData: true });
497
631
  window.addEventListener("resize", redraw);
498
632
  window.addEventListener("scroll", redraw, true);
633
+ // Once a scroll, a resize or a run of changes has settled, the marks that moved since the host
634
+ // was last told, in one report (P104), while any mark has a marker (a host without markers
635
+ // hears what it heard before), and at most one a second, the latest: the reports share the
636
+ // bridge's 120 a minute with the person's selections and clicks. While marks are being
637
+ // found again, that run tells it instead.
638
+ const FOLLOW_EVERY = 1000;
639
+ let settleTimer = 0;
640
+ let followTimer = 0;
641
+ let followed = 0;
642
+ const sendFollow = () => {
643
+ if (marks.length === 0 || settling()) {
644
+ return;
645
+ }
646
+ const pairs = resultsOf(true);
647
+ if (pairs.length > 0) {
648
+ followed = Date.now();
649
+ report(pairs);
650
+ }
651
+ };
652
+ const follow = () => {
653
+ if (followTimer !== 0 || !marks.some((mark) => mark.count !== null)) {
654
+ return;
655
+ }
656
+ const wait = followed + FOLLOW_EVERY - Date.now();
657
+ if (wait <= 0) {
658
+ sendFollow();
659
+ return;
660
+ }
661
+ followTimer = setTimeout(() => {
662
+ followTimer = 0;
663
+ sendFollow();
664
+ }, wait);
665
+ };
666
+ const settle = () => {
667
+ if (marks.length === 0) {
668
+ return;
669
+ }
670
+ clearTimeout(settleTimer);
671
+ settleTimer = setTimeout(() => {
672
+ settleTimer = 0;
673
+ follow();
674
+ }, 150);
675
+ };
676
+ window.addEventListener("resize", settle);
677
+ window.addEventListener("scroll", settle, true);
499
678
 
500
679
  const focus = (id) => {
501
680
  const mark = marks.filter((each) => each.id === id)[0];
@@ -519,8 +698,47 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
519
698
  setTimeout(redraw, 1850);
520
699
  }
521
700
  draw();
522
- tell(M.anchored, { results: [resultOf(mark)] });
701
+ report([{ mark, result: resultOf(mark) }]);
702
+ };
703
+
704
+ // A marker's click (P104). The layer takes no pointer but on its markers, so a press whose
705
+ // target is the layer is on a marker: the content's handlers never see it (this listener
706
+ // runs before any of theirs), nor does what lies under it, and a click is reported. No tab
707
+ // stop, by choice: it would join the page's focus order, which the content controls, and the
708
+ // layer is hidden from assistive technology; the host's own list of marks is the keyboard way.
709
+ const markerAt = (x, y) => {
710
+ for (let i = markers.length - 1; i >= 0; i -= 1) {
711
+ const rect = elementRect.call(markers[i].element);
712
+ if (x >= rect.left && x <= rect.right && y >= rect.top && y <= rect.bottom) {
713
+ return markers[i];
714
+ }
715
+ }
716
+ return null;
717
+ };
718
+ const onMarker = (event) => {
719
+ if (layer === null || event.target !== layer) {
720
+ return;
721
+ }
722
+ event.stopImmediatePropagation();
723
+ // No focus moves, no selection changes, no menu; a touch still makes its click.
724
+ if (CANCELLED[event.type] === 1) {
725
+ event.preventDefault();
726
+ }
727
+ if (event.type === "click" && event.isTrusted && event.button === 0) {
728
+ const hit = markerAt(event.clientX, event.clientY);
729
+ if (hit !== null && marks.some((mark) => mark.id === hit.id)) {
730
+ tell(M.activated, { id: hit.id, rect: box(elementRect.call(hit.element)) });
731
+ }
732
+ }
523
733
  };
734
+ // The pointer moving over a marker is stopped too. Narrowing only: the content still sees
735
+ // the pointer leave its own element for the layer (relatedTarget), the layer's :hover and
736
+ // :active, and the frame's user activation, so it can tell a marker was pressed, and
737
+ // roughly where; it can't act on or cancel the click.
738
+ const CANCELLED = { mousedown: 1, mouseup: 1, click: 1, dblclick: 1, auxclick: 1, contextmenu: 1 };
739
+ for (const type of ["pointerdown", "pointerup", "pointercancel", "mousedown", "mouseup", "click", "dblclick", "auxclick", "contextmenu", "touchstart", "touchend", "touchcancel", "pointerover", "pointerout", "pointerenter", "pointerleave", "pointermove", "mouseover", "mouseout", "mouseenter", "mouseleave", "mousemove"]) {
740
+ window.addEventListener(type, onMarker, true);
741
+ }
524
742
 
525
743
  // Picking an element: what is under the pointer, never the page itself or the shell's layer.
526
744
  let cursor = null;
@@ -677,7 +895,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
677
895
  marks = (Array.isArray(params.marks) ? params.marks : [])
678
896
  .slice(0, LIMIT.marks)
679
897
  .filter((mark) => mark && typeof mark.id === "string" && mark.anchor && Array.isArray(mark.anchor.selectors))
680
- .map((mark) => ({ id: mark.id, anchor: mark.anchor, found: null, state: null }));
898
+ .map((mark) => ({ id: mark.id, anchor: mark.anchor, count: typeof mark.count === "number" && mark.count >= 0 && mark.count <= LIMIT.count && Math.floor(mark.count) === mark.count ? mark.count : null, found: null, state: null, told: null }));
681
899
  if (typeof params.active === "string") {
682
900
  active = params.active;
683
901
  }
@@ -47,6 +47,14 @@ export interface ShellDocumentOptions {
47
47
  * renews it before then, at `<base>__porthole/renew`, and moves the page there.
48
48
  */
49
49
  readonly expires?: number;
50
+ /**
51
+ * The artifact version the files are (P098): the shell names it in its notices, and the host
52
+ * takes a notice only for the version it mounted. Not secret; the content can read it.
53
+ */
54
+ readonly set?: {
55
+ readonly id: string;
56
+ readonly version: string;
57
+ };
50
58
  };
51
59
  }
52
60
  /**
@@ -105,6 +105,9 @@ export function shellDocument(plan, csp, options) {
105
105
  base: options.files.base,
106
106
  ...(options.files.address === undefined ? {} : { address: options.files.address }),
107
107
  ...(options.files.expires === undefined ? {} : { expires: options.files.expires }),
108
+ ...(options.files.set === undefined
109
+ ? {}
110
+ : { set: { id: options.files.set.id, version: options.files.set.version } }),
108
111
  },
109
112
  }),
110
113
  }));