@botiverse/porthole 0.14.14 → 0.14.16

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.
@@ -81,7 +81,7 @@ export const WORD_LATE = String.raw`(at, now) => {
81
81
  * in one).
82
82
  *
83
83
  * The host drives it (`porthole/annotate.start|stop|show|focus|clear|track|clearSelection|focusMark`)
84
- * and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked`):
84
+ * and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked|selectionTracked`):
85
85
  * - picking an element: the element under the pointer (or finger) is outlined with its name; a
86
86
  * click or tap picks it, and the content's own handlers never see that click (unless the content
87
87
  * patched the DOM's built-ins, P105); Escape cancels (while selecting text too, P112);
@@ -107,7 +107,13 @@ export const WORD_LATE = String.raw`(at, now) => {
107
107
  * followed mark's (`tracked`) too, so a host places marks scrolled out of the frame, and keeps
108
108
  * them placed as the document scrolls, from one report and the followed mark's scroll;
109
109
  * - the last line (P133): where a selection or a mark's words end, in the document's coordinates
110
- * too (`lastLineDocumentRect`), so a host places its UI after them.
110
+ * too (`lastLineDocumentRect`), so a host places its UI after them;
111
+ * - the selection followed (P138): what the last `selected` reported (the element picked, or the
112
+ * words selected) is kept while the host follows the selection (`track` with `selection`) or said
113
+ * at `start` that it will (`keepSelection`, P140), and nothing is kept otherwise; while followed
114
+ * it is drawn in the layer and its boxes are reported as a followed mark's are
115
+ * (`selectionTracked`), with whether it is in view, or that it is gone; it takes no pointer, no
116
+ * focus and no key.
111
117
  *
112
118
  * It shares the realm with the content, which can interfere with all of it: the host takes its
113
119
  * reports as UI hints only.
@@ -128,6 +134,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
128
134
  activated: "porthole/annotate.activated",
129
135
  track: "porthole/annotate.track",
130
136
  tracked: "porthole/annotate.tracked",
137
+ selectionTracked: "porthole/annotate.selectionTracked",
131
138
  clearSelection: "porthole/annotate.clearSelection",
132
139
  focusMark: "porthole/annotate.focusMark",
133
140
  };
@@ -146,6 +153,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
146
153
  const elementRect = Element.prototype.getBoundingClientRect;
147
154
  const rangeRect = Range.prototype.getBoundingClientRect;
148
155
  const rangeRects = Range.prototype.getClientRects;
156
+ const cloneRange = Range.prototype.cloneRange;
149
157
  const setStart = Range.prototype.setStart;
150
158
  const setStartBefore = Range.prototype.setStartBefore;
151
159
  const compareBoundaryPoints = Range.prototype.compareBoundaryPoints;
@@ -402,7 +410,10 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
402
410
  // box of at least 44 by 44 px centred on its own (an invisible ::before; 100% is its padding
403
411
  // box, its border 1 px), so a tap a few px off still lands on the shell's layer. A marker is
404
412
  // a real button (P133): what a browser gives one is taken off, a ring says it has the focus.
405
- 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)}.mark.draft{box-sizing:border-box;background:rgba(250,204,21,.08);box-shadow:none;border-bottom:2px dashed rgba(202,138,4,.95)}.mark.draft.active{background:rgba(250,204,21,.16);box-shadow:0 0 0 2px rgba(234,179,8,.45);border-bottom-width:3px}.mark.element.draft{background:rgba(250,204,21,.04);border-bottom:0;outline-style:dashed}.mark.element.draft.active{background:rgba(250,204,21,.08);box-shadow:none;outline-style:dashed}.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;appearance:none;-webkit-appearance:none}.marker:focus-visible{outline:2px solid #2563eb;outline-offset:1px}.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.compact{padding:0 4px}.marker.draft{border:1px dashed rgb(202,138,4);background:#fffdf5;color:#a16207;box-shadow:0 1px 2px rgba(0,0,0,.2)}.marker.draft:hover{background:#fef9e7}.marker.draft.active{background:#fef3c7;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.2)}.marker.inert,[data-placing]>.marker{pointer-events:none}.touch>.marker::before{content:'';position:absolute;left:50%;top:50%;width:max(100% + 2px,44px);height:max(100% + 2px,44px);transform:translate(-50%,-50%)}.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}";
413
+ // The selection the host follows (P138) is drawn as what is picked is: an element in the
414
+ // picking outline, a little lighter and without its name; words with a light fill and a line
415
+ // under them, in the same blue, apart from the marks' yellow (no comment is there yet).
416
+ 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)}.mark.draft{box-sizing:border-box;background:rgba(250,204,21,.08);box-shadow:none;border-bottom:2px dashed rgba(202,138,4,.95)}.mark.draft.active{background:rgba(250,204,21,.16);box-shadow:0 0 0 2px rgba(234,179,8,.45);border-bottom-width:3px}.mark.element.draft{background:rgba(250,204,21,.04);border-bottom:0;outline-style:dashed}.mark.element.draft.active{background:rgba(250,204,21,.08);box-shadow:none;outline-style:dashed}.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;appearance:none;-webkit-appearance:none}.marker:focus-visible{outline:2px solid #2563eb;outline-offset:1px}.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.compact{padding:0 4px}.marker.draft{border:1px dashed rgb(202,138,4);background:#fffdf5;color:#a16207;box-shadow:0 1px 2px rgba(0,0,0,.2)}.marker.draft:hover{background:#fef9e7}.marker.draft.active{background:#fef3c7;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.2)}.marker.inert,[data-placing]>.marker{pointer-events:none}.touch>.marker::before{content:'';position:absolute;left:50%;top:50%;width:max(100% + 2px,44px);height:max(100% + 2px,44px);transform:translate(-50%,-50%)}.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)}.held{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.06)}.held.text{outline:0;border-radius:2px;background:rgba(37,99,235,.12);box-shadow:inset 0 -2px 0 #2563eb}.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}";
406
417
  // Inline and important: the content's own style sheets can't hide, shrink or move it by
407
418
  // accident. Set again at each draw, since its scripts can rewrite it (narrowing only: the
408
419
  // content can still cover the layer, or move it with its ancestors, P104). Clipped, where an
@@ -428,6 +439,36 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
428
439
 
429
440
  let mode = { elements: false, text: false, hold: false };
430
441
  let hover = null;
442
+ // The selection last reported as selected (P138): its anchor, and what it is in the page (the
443
+ // element picked, or a copy of the selection's range, which the page's changes keep up to
444
+ // date and which stays when the page's own selection goes). Followed while the host asks
445
+ // (track with selection), and drawn then. Each new selected replaces it. Kept only while the
446
+ // host follows the selection, or said at its last start that it will (keepSelection, P140):
447
+ // for any other host nothing is kept, as before P138.
448
+ let held = null;
449
+ let followingSelection = false;
450
+ let keeping = false;
451
+ const keeps = () => followingSelection || keeping;
452
+ // What the host was last told of it: "attached", "orphaned", or null (nothing yet).
453
+ let heldTold = null;
454
+ const heldGone = (found) => (found.range ? found.range.collapsed || !found.range.startContainer.isConnected : !found.element.isConnected);
455
+ const heldShown = () => followingSelection && held !== null && heldTold !== "orphaned" && !heldGone(held.found);
456
+ // The element just picked (P138, Tenny's review): for a host that will follow it
457
+ // (keepSelection, P140), it keeps its outline after selected, so there is no gap before the
458
+ // host follows it, and the follow's highlight takes over where it does. For any other host
459
+ // the outline goes with the pick, as before P138. Until the follow comes it ends as a
460
+ // selection does: the next pick or selection, the host's clearSelection, a mode started or
461
+ // stopped, clear, Escape, or the element leaving the page. Not unselected: a selection made
462
+ // after the pick has already ended it as it was reported, so the one unselected can clear is
463
+ // one from before, which the pick's own click takes away when text is selected too.
464
+ let picked = null;
465
+ const endPick = () => {
466
+ if (picked !== null) {
467
+ picked = null;
468
+ redraw();
469
+ }
470
+ };
471
+ const pickShown = () => picked !== null && !followingSelection && picked.isConnected;
431
472
  let marks = [];
432
473
  // The markers as last drawn, for a click to find: { id, element }. Each mark keeps its
433
474
  // marker's node across draws, so a press that spans a redraw ends on the node it began on.
@@ -818,7 +859,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
818
859
  return boxes;
819
860
  };
820
861
  const draw = () => {
821
- if (marks.length === 0 && hover === null && layer === null) {
862
+ if (marks.length === 0 && hover === null && layer === null && !heldShown() && !pickShown()) {
822
863
  return;
823
864
  }
824
865
  const root = ensureLayer();
@@ -913,6 +954,24 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
913
954
  }
914
955
  }
915
956
  const outlines = [];
957
+ // The followed selection (P138), under the picking outline: no pointer, no focus, no name;
958
+ // before the host follows it, the element just picked, drawn the same way.
959
+ if (picked !== null && !picked.isConnected) {
960
+ picked = null;
961
+ }
962
+ const lit = heldShown() ? held.found : pickShown() ? { element: picked } : null;
963
+ if (lit !== null) {
964
+ const rects = lit.range ? Array.from(rangeRects.call(lit.range)).slice(0, LIMIT.boxes) : [elementRect.call(lit.element)];
965
+ for (const rect of rects) {
966
+ if (rect.width === 0 && rect.height === 0) {
967
+ continue;
968
+ }
969
+ const each = createElement.call(document, "div");
970
+ each.className = lit.range ? "held text" : "held";
971
+ each.style.cssText = "left:" + rect.left + "px;top:" + rect.top + "px;width:" + rect.width + "px;height:" + rect.height + "px";
972
+ outlines.push(each);
973
+ }
974
+ }
916
975
  if (hover !== null && hover.isConnected) {
917
976
  const rect = elementRect.call(hover);
918
977
  const outline = createElement.call(document, "div");
@@ -958,9 +1017,17 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
958
1017
  let trackedBox = null;
959
1018
  let trackedAt = 0;
960
1019
  let trackFrame = 0;
1020
+ // The followed selection's viewport as last told (P138): a frame made smaller can leave it
1021
+ // out of view without moving it.
1022
+ let trackedView = null;
961
1023
  const trackTick = () => {
962
1024
  trackFrame = 0;
963
- if (tracking === null) {
1025
+ if (tracking === null && !followingSelection) {
1026
+ return;
1027
+ }
1028
+ if (followingSelection) {
1029
+ followHeld();
1030
+ trackFrame = nextFrame(trackTick);
964
1031
  return;
965
1032
  }
966
1033
  const mark = marks.find((each) => each.id === tracking);
@@ -979,12 +1046,84 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
979
1046
  }
980
1047
  trackFrame = nextFrame(trackTick);
981
1048
  };
982
- const track = (id) => {
1049
+ // The followed selection (P138), as a followed mark is, and on its clock: where it is at each
1050
+ // animation frame where it moved, or the viewport changed size, with whether any of it is in
1051
+ // the viewport; orphaned once while it isn't in the page (a page that took the element out,
1052
+ // a re-render, the words gone), found again by its anchor at most twice a second meanwhile.
1053
+ // Geometry only: its anchor and words went with selected. Reads boxes, nothing else: no
1054
+ // focus, no selection, no listener.
1055
+ const followHeld = () => {
1056
+ const now = performance.now();
1057
+ if (held !== null && heldGone(held.found) && now - held.tried >= 500) {
1058
+ held.tried = now;
1059
+ let found = null;
1060
+ try {
1061
+ found = find(held.anchor, textIndex());
1062
+ } catch (_) {
1063
+ found = null;
1064
+ }
1065
+ if (found !== null && !heldGone(found)) {
1066
+ held.found = found;
1067
+ }
1068
+ }
1069
+ if (held === null || heldGone(held.found)) {
1070
+ if (heldTold !== "orphaned") {
1071
+ heldTold = "orphaned";
1072
+ trackedBox = null;
1073
+ tell(M.selectionTracked, { state: "orphaned" });
1074
+ redraw();
1075
+ }
1076
+ return;
1077
+ }
1078
+ const rect = box(rectOf(held.found));
1079
+ const root = document.documentElement;
1080
+ const view = { width: root ? root.clientWidth : 0, height: root ? root.clientHeight : 0 };
1081
+ const resized = trackedView === null || trackedView.width !== view.width || trackedView.height !== view.height;
1082
+ if ((heldTold !== "attached" || resized || apart(trackedBox, rect)) && now - trackedAt >= 16) {
1083
+ heldTold = "attached";
1084
+ trackedBox = rect;
1085
+ trackedView = view;
1086
+ trackedAt = now;
1087
+ const scroll = scrollOf();
1088
+ const lastLineDocumentRect = lastLineOf(held.found, scroll);
1089
+ const inView = rect.x < view.width && rect.x + rect.width > 0 && rect.y < view.height && rect.y + rect.height > 0;
1090
+ tell(M.selectionTracked, Object.assign({ state: "attached", rect, documentRect: inDocument(rect, scroll), scroll, inView }, lastLineDocumentRect === null ? {} : { lastLineDocumentRect }));
1091
+ // The highlight goes with it (a layout change moves it without a scroll).
1092
+ redraw();
1093
+ }
1094
+ };
1095
+ // A mark, the selection (P138), or nothing: one at a time, each replacing the last.
1096
+ const track = (id, selection) => {
1097
+ const was = heldShown() || pickShown();
983
1098
  tracking = typeof id === "string" ? id : null;
1099
+ followingSelection = tracking === null && selection === true;
1100
+ // The follow's highlight takes the pick's outline over, in this draw (Tenny's review).
1101
+ if (followingSelection) {
1102
+ picked = null;
1103
+ }
1104
+ // Its end lets the selection go, unless the host said it follows it again (P140).
1105
+ if (!keeps()) {
1106
+ held = null;
1107
+ }
984
1108
  trackedBox = null;
985
- if (tracking !== null && trackFrame === 0) {
1109
+ trackedView = null;
1110
+ heldTold = null;
1111
+ if ((tracking !== null || followingSelection) && trackFrame === 0) {
986
1112
  trackFrame = nextFrame(trackTick);
987
1113
  }
1114
+ if (heldShown() || pickShown() || was) {
1115
+ draw();
1116
+ }
1117
+ };
1118
+ // A new selected (P138): what is followed, if the selection is, from the next frame on; kept
1119
+ // only for a host that follows it or will (P140).
1120
+ const holdSelected = (anchor, found) => {
1121
+ held = keeps() ? { anchor, found, tried: 0 } : null;
1122
+ if (followingSelection) {
1123
+ trackedBox = null;
1124
+ heldTold = null;
1125
+ redraw();
1126
+ }
988
1127
  };
989
1128
 
990
1129
  // Where each found mark starts in the document, in order (P112): its place in a list the host
@@ -1187,9 +1326,11 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1187
1326
  sent += 1;
1188
1327
  }
1189
1328
  }
1329
+ // Not while the host follows the selection (P138, Tenny's review): its reports carry where
1330
+ // it is; a scroll after the following ends is re-sent as before.
1190
1331
  if (selectionScrolled) {
1191
1332
  selectionScrolled = false;
1192
- if (reportSelection(true)) {
1333
+ if (!followingSelection && reportSelection(true)) {
1193
1334
  sent += 1;
1194
1335
  }
1195
1336
  }
@@ -1459,6 +1600,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1459
1600
  const stop = () => {
1460
1601
  mode = { elements: false, text: false };
1461
1602
  hover = null;
1603
+ picked = null;
1462
1604
  reported = null;
1463
1605
  reportedBox = null;
1464
1606
  setCursor(false);
@@ -1526,6 +1668,9 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1526
1668
  return;
1527
1669
  }
1528
1670
  swallowUntil = performance.now() + 2000;
1671
+ holdSelected(anchor, { element });
1672
+ picked = keeping && !followingSelection ? element : null;
1673
+ redraw();
1529
1674
  tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
1530
1675
  }, HOLD_MS),
1531
1676
  };
@@ -1573,6 +1718,10 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1573
1718
  mode = { elements: false, text: mode.text };
1574
1719
  hover = null;
1575
1720
  setCursor(false);
1721
+ holdSelected(anchor, { element });
1722
+ // Its outline stays (P138), now without its name, until the host follows it or it ends;
1723
+ // only for a host that will follow it (P140): for any other it goes with the pick.
1724
+ picked = keeping && !followingSelection ? element : null;
1576
1725
  draw();
1577
1726
  tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
1578
1727
  }, true);
@@ -1580,6 +1729,8 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1580
1729
  if (event.key !== "Escape") {
1581
1730
  return;
1582
1731
  }
1732
+ // The person wants out: a pick's outline goes (P138). The key is untouched by it.
1733
+ endPick();
1583
1734
  if (mode.elements) {
1584
1735
  event.preventDefault();
1585
1736
  event.stopImmediatePropagation();
@@ -1633,6 +1784,8 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1633
1784
  }
1634
1785
  reported = key;
1635
1786
  reportedBox = rect;
1787
+ holdSelected(anchor, { range: cloneRange.call(range) });
1788
+ endPick();
1636
1789
  tell(M.selected, Object.assign({ anchor, rect }, placeOf({ range })));
1637
1790
  return true;
1638
1791
  };
@@ -1643,6 +1796,10 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1643
1796
  }
1644
1797
  });
1645
1798
  window.addEventListener("scroll", () => {
1799
+ // Not while the host follows the selection (P138, Tenny's review).
1800
+ if (followingSelection) {
1801
+ return;
1802
+ }
1646
1803
  if (reported !== null) {
1647
1804
  selectionScrolled = true;
1648
1805
  settle();
@@ -1661,7 +1818,15 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1661
1818
  switch (data.method) {
1662
1819
  case M.start:
1663
1820
  mode = { elements: params.elements === true, text: params.text === true, hold: params.elements === "hold" };
1821
+ // Whether the host will follow what is selected (P140): only then is it kept before
1822
+ // the host follows it. A stop leaves it, so a stop sent as the composer opens doesn't
1823
+ // take the selection away before the follow comes.
1824
+ keeping = params.keepSelection === true;
1825
+ if (!keeps()) {
1826
+ held = null;
1827
+ }
1664
1828
  hover = null;
1829
+ picked = null;
1665
1830
  reported = null;
1666
1831
  reportedBox = null;
1667
1832
  setCursor(mode.elements);
@@ -1693,18 +1858,19 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1693
1858
  focus(String(params.id));
1694
1859
  break;
1695
1860
  case M.track:
1696
- track(params.id);
1861
+ track(params.id, params.selection === true);
1697
1862
  break;
1698
1863
  case M.clearSelection: {
1699
1864
  // The host used the person's selection (P115): it goes, and with it what the shell
1700
1865
  // held of it (a report waiting to settle, the one last told, a scroll's follow-up), so
1701
1866
  // nothing is told back: the host knows, and the selectionchange this makes finds
1702
- // nothing to report. Marks, a pick and the mode stay as they are. With nothing
1703
- // selected, nothing changes.
1867
+ // nothing to report. Marks, a pick and the mode stay as they are, but a pick's outline
1868
+ // goes (P138). With nothing selected, nothing changes.
1704
1869
  cancelLater(selectionTimer);
1705
1870
  selectionTimer = 0;
1706
1871
  reported = null;
1707
1872
  reportedBox = null;
1873
+ endPick();
1708
1874
  selectionScrolled = false;
1709
1875
  const selection = selectionOf.call(document);
1710
1876
  if (selection !== null) {
@@ -1717,6 +1883,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1717
1883
  break;
1718
1884
  case M.clear:
1719
1885
  track(null);
1886
+ picked = null;
1720
1887
  pendingFocus = null;
1721
1888
  pendingMarker = null;
1722
1889
  marks = [];
@@ -92,6 +92,43 @@ export const ONCE = String.raw`(passesAsIs, toText) => (value) => {
92
92
  return text;
93
93
  }`;
94
94
 
95
+ /**
96
+ * The shell's handshake with its host (P085, P139), spliced into the runtime as
97
+ * `HANDSHAKE(topLevel, ask, answered, none, later)`. On a tab of its own (`topLevel`: the window is
98
+ * its own top, so its parent is itself and no host can hear it) there is no host to ask: `none()`
99
+ * at once, and nothing is asked. In a frame it asks (`ask()`, a promise of the host's answer) up to
100
+ * 40 times, 250 ms apart (`later(run, ms)`), since the host may start listening after the shell
101
+ * runs; the first answer is taken (`answered(result)`), once. After the 40th try with no answer,
102
+ * `none()`; an answer that comes later still is taken.
103
+ */
104
+ export const HANDSHAKE = String.raw`(topLevel, ask, answered, none, later) => {
105
+ if (topLevel === true) {
106
+ none();
107
+ return;
108
+ }
109
+ let initialized = false;
110
+ let tries = 0;
111
+ const initialize = () => {
112
+ if (initialized) {
113
+ return;
114
+ }
115
+ if (tries >= 40) {
116
+ none();
117
+ return;
118
+ }
119
+ tries += 1;
120
+ ask().then((result) => {
121
+ if (initialized) {
122
+ return;
123
+ }
124
+ initialized = true;
125
+ answered(result);
126
+ }, () => {});
127
+ later(initialize, 250);
128
+ };
129
+ initialize();
130
+ }`;
131
+
95
132
  /**
96
133
  * The shell's runtime: the code that runs first in the frame, before any content. Plain ES2020,
97
134
  * no imports and no build step, so every engine (a browser frame now, a native web view later)
@@ -155,6 +192,9 @@ export const SHELL_RUNTIME = String.raw`(() => {
155
192
  // such name goes on the shell's own script element (data-porthole-unfixed, for a test or a
156
193
  // person to see) and, once the shell can speak, to the host as an error report.
157
194
  const shellScript = document.currentScript;
195
+ // The platform's own, kept before the shell's guards wrap it: the shell marks the document's root
196
+ // with it (data-porthole-host, P139).
197
+ const setAttributeOfShell = Element.prototype.setAttribute;
158
198
  const unfixed = [];
159
199
  let tellUnfixed = (_name) => {};
160
200
  const lock = (target, name, value) => {
@@ -2232,36 +2272,43 @@ export const SHELL_RUNTIME = String.raw`(() => {
2232
2272
  whenLoaded(() => void render({ html: plan.document }));
2233
2273
  }
2234
2274
 
2235
- // Ask until answered: the host may start listening after this runs.
2236
- let initialized = false;
2237
- let tries = 0;
2238
- const initialize = () => {
2239
- if (initialized) {
2240
- return;
2241
- }
2242
- if (tries >= 40) {
2243
- // No host answered: the runtime has nothing to offer.
2244
- runtimeOffer(null);
2245
- return;
2246
- }
2247
- tries += 1;
2248
- request("ui/initialize", {
2249
- protocolVersion: plan.protocolVersion,
2250
- appInfo: { name: "porthole-shell", version: "1" },
2251
- appCapabilities: {},
2252
- }).then((result) => {
2253
- if (initialized) {
2254
- return;
2255
- }
2256
- initialized = true;
2275
+ // The handshake (HANDSHAKE, P085): asked until answered, since the host may start listening
2276
+ // after this runs; on a tab of its own, not asked at all (P139): its parent is itself, so no host
2277
+ // hears it, and the runtime has nothing to offer from the start. How it ended goes on the
2278
+ // document's root element (data-porthole-host: "answered", or "none" where no host answered), for
2279
+ // a test, a person or a tool that shoots the page to see (P139): not on the shell's own script,
2280
+ // which a whole document's render takes out with the body it replaces, while the root stays (the
2281
+ // render adds the page's own attributes to it and removes none). The page's own word, never a
2282
+ // gate, set through the platform's setAttribute kept before the guards (setAttributeOfShell).
2283
+ const shellRoot = document.documentElement;
2284
+ const settled = (how) => {
2285
+ try {
2286
+ callOf(setAttributeOfShell, shellRoot, ["data-porthole-host", how]);
2287
+ } catch (_) {}
2288
+ };
2289
+ const handshake = ${HANDSHAKE};
2290
+ handshake(
2291
+ window.top === window,
2292
+ () =>
2293
+ request("ui/initialize", {
2294
+ protocolVersion: plan.protocolVersion,
2295
+ appInfo: { name: "porthole-shell", version: "1" },
2296
+ appCapabilities: {},
2297
+ }),
2298
+ (result) => {
2299
+ settled("answered");
2257
2300
  const capabilities = result && result.hostCapabilities;
2258
2301
  const experimental = capabilities && capabilities.experimental;
2259
2302
  runtimeOffer(experimental && typeof experimental === "object" ? experimental["porthole/runtime"] : null);
2260
2303
  applyTheme(result && result.hostContext);
2261
2304
  notify("ui/notifications/initialized", {});
2262
2305
  schedule();
2263
- }, () => {});
2264
- setTimeout(initialize, 250);
2265
- };
2266
- initialize();
2306
+ },
2307
+ () => {
2308
+ // No host answered (or none can): the runtime has nothing to offer.
2309
+ settled("none");
2310
+ runtimeOffer(null);
2311
+ },
2312
+ (run, ms) => setTimeout(run, ms),
2313
+ );
2267
2314
  })();`;