@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.
@@ -77,7 +77,7 @@ export const WORD_LATE = String.raw `(at, now) => {
77
77
  * in one).
78
78
  *
79
79
  * The host drives it (`porthole/annotate.start|stop|show|focus|clear|track|clearSelection|focusMark`)
80
- * and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked`):
80
+ * and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked|selectionTracked`):
81
81
  * - picking an element: the element under the pointer (or finger) is outlined with its name; a
82
82
  * click or tap picks it, and the content's own handlers never see that click (unless the content
83
83
  * patched the DOM's built-ins, P105); Escape cancels (while selecting text too, P112);
@@ -103,7 +103,13 @@ export const WORD_LATE = String.raw `(at, now) => {
103
103
  * followed mark's (`tracked`) too, so a host places marks scrolled out of the frame, and keeps
104
104
  * them placed as the document scrolls, from one report and the followed mark's scroll;
105
105
  * - the last line (P133): where a selection or a mark's words end, in the document's coordinates
106
- * too (`lastLineDocumentRect`), so a host places its UI after them.
106
+ * too (`lastLineDocumentRect`), so a host places its UI after them;
107
+ * - the selection followed (P138): what the last `selected` reported (the element picked, or the
108
+ * words selected) is kept while the host follows the selection (`track` with `selection`) or said
109
+ * at `start` that it will (`keepSelection`, P140), and nothing is kept otherwise; while followed
110
+ * it is drawn in the layer and its boxes are reported as a followed mark's are
111
+ * (`selectionTracked`), with whether it is in view, or that it is gone; it takes no pointer, no
112
+ * focus and no key.
107
113
  *
108
114
  * It shares the realm with the content, which can interfere with all of it: the host takes its
109
115
  * reports as UI hints only.
@@ -124,6 +130,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
124
130
  activated: "porthole/annotate.activated",
125
131
  track: "porthole/annotate.track",
126
132
  tracked: "porthole/annotate.tracked",
133
+ selectionTracked: "porthole/annotate.selectionTracked",
127
134
  clearSelection: "porthole/annotate.clearSelection",
128
135
  focusMark: "porthole/annotate.focusMark",
129
136
  };
@@ -142,6 +149,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
142
149
  const elementRect = Element.prototype.getBoundingClientRect;
143
150
  const rangeRect = Range.prototype.getBoundingClientRect;
144
151
  const rangeRects = Range.prototype.getClientRects;
152
+ const cloneRange = Range.prototype.cloneRange;
145
153
  const setStart = Range.prototype.setStart;
146
154
  const setStartBefore = Range.prototype.setStartBefore;
147
155
  const compareBoundaryPoints = Range.prototype.compareBoundaryPoints;
@@ -398,7 +406,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
398
406
  // box of at least 44 by 44 px centred on its own (an invisible ::before; 100% is its padding
399
407
  // box, its border 1 px), so a tap a few px off still lands on the shell's layer. A marker is
400
408
  // a real button (P133): what a browser gives one is taken off, a ring says it has the focus.
401
- 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}";
409
+ // The selection the host follows (P138) is drawn as what is picked is: an element in the
410
+ // picking outline, a little lighter and without its name; words with a light fill and a line
411
+ // under them, in the same blue, apart from the marks' yellow (no comment is there yet).
412
+ 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}";
402
413
  // Inline and important: the content's own style sheets can't hide, shrink or move it by
403
414
  // accident. Set again at each draw, since its scripts can rewrite it (narrowing only: the
404
415
  // content can still cover the layer, or move it with its ancestors, P104). Clipped, where an
@@ -424,6 +435,36 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
424
435
 
425
436
  let mode = { elements: false, text: false, hold: false };
426
437
  let hover = null;
438
+ // The selection last reported as selected (P138): its anchor, and what it is in the page (the
439
+ // element picked, or a copy of the selection's range, which the page's changes keep up to
440
+ // date and which stays when the page's own selection goes). Followed while the host asks
441
+ // (track with selection), and drawn then. Each new selected replaces it. Kept only while the
442
+ // host follows the selection, or said at its last start that it will (keepSelection, P140):
443
+ // for any other host nothing is kept, as before P138.
444
+ let held = null;
445
+ let followingSelection = false;
446
+ let keeping = false;
447
+ const keeps = () => followingSelection || keeping;
448
+ // What the host was last told of it: "attached", "orphaned", or null (nothing yet).
449
+ let heldTold = null;
450
+ const heldGone = (found) => (found.range ? found.range.collapsed || !found.range.startContainer.isConnected : !found.element.isConnected);
451
+ const heldShown = () => followingSelection && held !== null && heldTold !== "orphaned" && !heldGone(held.found);
452
+ // The element just picked (P138, Tenny's review): for a host that will follow it
453
+ // (keepSelection, P140), it keeps its outline after selected, so there is no gap before the
454
+ // host follows it, and the follow's highlight takes over where it does. For any other host
455
+ // the outline goes with the pick, as before P138. Until the follow comes it ends as a
456
+ // selection does: the next pick or selection, the host's clearSelection, a mode started or
457
+ // stopped, clear, Escape, or the element leaving the page. Not unselected: a selection made
458
+ // after the pick has already ended it as it was reported, so the one unselected can clear is
459
+ // one from before, which the pick's own click takes away when text is selected too.
460
+ let picked = null;
461
+ const endPick = () => {
462
+ if (picked !== null) {
463
+ picked = null;
464
+ redraw();
465
+ }
466
+ };
467
+ const pickShown = () => picked !== null && !followingSelection && picked.isConnected;
427
468
  let marks = [];
428
469
  // The markers as last drawn, for a click to find: { id, element }. Each mark keeps its
429
470
  // marker's node across draws, so a press that spans a redraw ends on the node it began on.
@@ -814,7 +855,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
814
855
  return boxes;
815
856
  };
816
857
  const draw = () => {
817
- if (marks.length === 0 && hover === null && layer === null) {
858
+ if (marks.length === 0 && hover === null && layer === null && !heldShown() && !pickShown()) {
818
859
  return;
819
860
  }
820
861
  const root = ensureLayer();
@@ -909,6 +950,24 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
909
950
  }
910
951
  }
911
952
  const outlines = [];
953
+ // The followed selection (P138), under the picking outline: no pointer, no focus, no name;
954
+ // before the host follows it, the element just picked, drawn the same way.
955
+ if (picked !== null && !picked.isConnected) {
956
+ picked = null;
957
+ }
958
+ const lit = heldShown() ? held.found : pickShown() ? { element: picked } : null;
959
+ if (lit !== null) {
960
+ const rects = lit.range ? Array.from(rangeRects.call(lit.range)).slice(0, LIMIT.boxes) : [elementRect.call(lit.element)];
961
+ for (const rect of rects) {
962
+ if (rect.width === 0 && rect.height === 0) {
963
+ continue;
964
+ }
965
+ const each = createElement.call(document, "div");
966
+ each.className = lit.range ? "held text" : "held";
967
+ each.style.cssText = "left:" + rect.left + "px;top:" + rect.top + "px;width:" + rect.width + "px;height:" + rect.height + "px";
968
+ outlines.push(each);
969
+ }
970
+ }
912
971
  if (hover !== null && hover.isConnected) {
913
972
  const rect = elementRect.call(hover);
914
973
  const outline = createElement.call(document, "div");
@@ -954,9 +1013,17 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
954
1013
  let trackedBox = null;
955
1014
  let trackedAt = 0;
956
1015
  let trackFrame = 0;
1016
+ // The followed selection's viewport as last told (P138): a frame made smaller can leave it
1017
+ // out of view without moving it.
1018
+ let trackedView = null;
957
1019
  const trackTick = () => {
958
1020
  trackFrame = 0;
959
- if (tracking === null) {
1021
+ if (tracking === null && !followingSelection) {
1022
+ return;
1023
+ }
1024
+ if (followingSelection) {
1025
+ followHeld();
1026
+ trackFrame = nextFrame(trackTick);
960
1027
  return;
961
1028
  }
962
1029
  const mark = marks.find((each) => each.id === tracking);
@@ -975,12 +1042,84 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
975
1042
  }
976
1043
  trackFrame = nextFrame(trackTick);
977
1044
  };
978
- const track = (id) => {
1045
+ // The followed selection (P138), as a followed mark is, and on its clock: where it is at each
1046
+ // animation frame where it moved, or the viewport changed size, with whether any of it is in
1047
+ // the viewport; orphaned once while it isn't in the page (a page that took the element out,
1048
+ // a re-render, the words gone), found again by its anchor at most twice a second meanwhile.
1049
+ // Geometry only: its anchor and words went with selected. Reads boxes, nothing else: no
1050
+ // focus, no selection, no listener.
1051
+ const followHeld = () => {
1052
+ const now = performance.now();
1053
+ if (held !== null && heldGone(held.found) && now - held.tried >= 500) {
1054
+ held.tried = now;
1055
+ let found = null;
1056
+ try {
1057
+ found = find(held.anchor, textIndex());
1058
+ } catch (_) {
1059
+ found = null;
1060
+ }
1061
+ if (found !== null && !heldGone(found)) {
1062
+ held.found = found;
1063
+ }
1064
+ }
1065
+ if (held === null || heldGone(held.found)) {
1066
+ if (heldTold !== "orphaned") {
1067
+ heldTold = "orphaned";
1068
+ trackedBox = null;
1069
+ tell(M.selectionTracked, { state: "orphaned" });
1070
+ redraw();
1071
+ }
1072
+ return;
1073
+ }
1074
+ const rect = box(rectOf(held.found));
1075
+ const root = document.documentElement;
1076
+ const view = { width: root ? root.clientWidth : 0, height: root ? root.clientHeight : 0 };
1077
+ const resized = trackedView === null || trackedView.width !== view.width || trackedView.height !== view.height;
1078
+ if ((heldTold !== "attached" || resized || apart(trackedBox, rect)) && now - trackedAt >= 16) {
1079
+ heldTold = "attached";
1080
+ trackedBox = rect;
1081
+ trackedView = view;
1082
+ trackedAt = now;
1083
+ const scroll = scrollOf();
1084
+ const lastLineDocumentRect = lastLineOf(held.found, scroll);
1085
+ const inView = rect.x < view.width && rect.x + rect.width > 0 && rect.y < view.height && rect.y + rect.height > 0;
1086
+ tell(M.selectionTracked, Object.assign({ state: "attached", rect, documentRect: inDocument(rect, scroll), scroll, inView }, lastLineDocumentRect === null ? {} : { lastLineDocumentRect }));
1087
+ // The highlight goes with it (a layout change moves it without a scroll).
1088
+ redraw();
1089
+ }
1090
+ };
1091
+ // A mark, the selection (P138), or nothing: one at a time, each replacing the last.
1092
+ const track = (id, selection) => {
1093
+ const was = heldShown() || pickShown();
979
1094
  tracking = typeof id === "string" ? id : null;
1095
+ followingSelection = tracking === null && selection === true;
1096
+ // The follow's highlight takes the pick's outline over, in this draw (Tenny's review).
1097
+ if (followingSelection) {
1098
+ picked = null;
1099
+ }
1100
+ // Its end lets the selection go, unless the host said it follows it again (P140).
1101
+ if (!keeps()) {
1102
+ held = null;
1103
+ }
980
1104
  trackedBox = null;
981
- if (tracking !== null && trackFrame === 0) {
1105
+ trackedView = null;
1106
+ heldTold = null;
1107
+ if ((tracking !== null || followingSelection) && trackFrame === 0) {
982
1108
  trackFrame = nextFrame(trackTick);
983
1109
  }
1110
+ if (heldShown() || pickShown() || was) {
1111
+ draw();
1112
+ }
1113
+ };
1114
+ // A new selected (P138): what is followed, if the selection is, from the next frame on; kept
1115
+ // only for a host that follows it or will (P140).
1116
+ const holdSelected = (anchor, found) => {
1117
+ held = keeps() ? { anchor, found, tried: 0 } : null;
1118
+ if (followingSelection) {
1119
+ trackedBox = null;
1120
+ heldTold = null;
1121
+ redraw();
1122
+ }
984
1123
  };
985
1124
 
986
1125
  // Where each found mark starts in the document, in order (P112): its place in a list the host
@@ -1183,9 +1322,11 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1183
1322
  sent += 1;
1184
1323
  }
1185
1324
  }
1325
+ // Not while the host follows the selection (P138, Tenny's review): its reports carry where
1326
+ // it is; a scroll after the following ends is re-sent as before.
1186
1327
  if (selectionScrolled) {
1187
1328
  selectionScrolled = false;
1188
- if (reportSelection(true)) {
1329
+ if (!followingSelection && reportSelection(true)) {
1189
1330
  sent += 1;
1190
1331
  }
1191
1332
  }
@@ -1455,6 +1596,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1455
1596
  const stop = () => {
1456
1597
  mode = { elements: false, text: false };
1457
1598
  hover = null;
1599
+ picked = null;
1458
1600
  reported = null;
1459
1601
  reportedBox = null;
1460
1602
  setCursor(false);
@@ -1522,6 +1664,9 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1522
1664
  return;
1523
1665
  }
1524
1666
  swallowUntil = performance.now() + 2000;
1667
+ holdSelected(anchor, { element });
1668
+ picked = keeping && !followingSelection ? element : null;
1669
+ redraw();
1525
1670
  tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
1526
1671
  }, HOLD_MS),
1527
1672
  };
@@ -1569,6 +1714,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1569
1714
  mode = { elements: false, text: mode.text };
1570
1715
  hover = null;
1571
1716
  setCursor(false);
1717
+ holdSelected(anchor, { element });
1718
+ // Its outline stays (P138), now without its name, until the host follows it or it ends;
1719
+ // only for a host that will follow it (P140): for any other it goes with the pick.
1720
+ picked = keeping && !followingSelection ? element : null;
1572
1721
  draw();
1573
1722
  tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
1574
1723
  }, true);
@@ -1576,6 +1725,8 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1576
1725
  if (event.key !== "Escape") {
1577
1726
  return;
1578
1727
  }
1728
+ // The person wants out: a pick's outline goes (P138). The key is untouched by it.
1729
+ endPick();
1579
1730
  if (mode.elements) {
1580
1731
  event.preventDefault();
1581
1732
  event.stopImmediatePropagation();
@@ -1629,6 +1780,8 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1629
1780
  }
1630
1781
  reported = key;
1631
1782
  reportedBox = rect;
1783
+ holdSelected(anchor, { range: cloneRange.call(range) });
1784
+ endPick();
1632
1785
  tell(M.selected, Object.assign({ anchor, rect }, placeOf({ range })));
1633
1786
  return true;
1634
1787
  };
@@ -1639,6 +1792,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1639
1792
  }
1640
1793
  });
1641
1794
  window.addEventListener("scroll", () => {
1795
+ // Not while the host follows the selection (P138, Tenny's review).
1796
+ if (followingSelection) {
1797
+ return;
1798
+ }
1642
1799
  if (reported !== null) {
1643
1800
  selectionScrolled = true;
1644
1801
  settle();
@@ -1657,7 +1814,15 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1657
1814
  switch (data.method) {
1658
1815
  case M.start:
1659
1816
  mode = { elements: params.elements === true, text: params.text === true, hold: params.elements === "hold" };
1817
+ // Whether the host will follow what is selected (P140): only then is it kept before
1818
+ // the host follows it. A stop leaves it, so a stop sent as the composer opens doesn't
1819
+ // take the selection away before the follow comes.
1820
+ keeping = params.keepSelection === true;
1821
+ if (!keeps()) {
1822
+ held = null;
1823
+ }
1660
1824
  hover = null;
1825
+ picked = null;
1661
1826
  reported = null;
1662
1827
  reportedBox = null;
1663
1828
  setCursor(mode.elements);
@@ -1689,18 +1854,19 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1689
1854
  focus(String(params.id));
1690
1855
  break;
1691
1856
  case M.track:
1692
- track(params.id);
1857
+ track(params.id, params.selection === true);
1693
1858
  break;
1694
1859
  case M.clearSelection: {
1695
1860
  // The host used the person's selection (P115): it goes, and with it what the shell
1696
1861
  // held of it (a report waiting to settle, the one last told, a scroll's follow-up), so
1697
1862
  // nothing is told back: the host knows, and the selectionchange this makes finds
1698
- // nothing to report. Marks, a pick and the mode stay as they are. With nothing
1699
- // selected, nothing changes.
1863
+ // nothing to report. Marks, a pick and the mode stay as they are, but a pick's outline
1864
+ // goes (P138). With nothing selected, nothing changes.
1700
1865
  cancelLater(selectionTimer);
1701
1866
  selectionTimer = 0;
1702
1867
  reported = null;
1703
1868
  reportedBox = null;
1869
+ endPick();
1704
1870
  selectionScrolled = false;
1705
1871
  const selection = selectionOf.call(document);
1706
1872
  if (selection !== null) {
@@ -1713,6 +1879,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1713
1879
  break;
1714
1880
  case M.clear:
1715
1881
  track(null);
1882
+ picked = null;
1716
1883
  pendingFocus = null;
1717
1884
  pendingMarker = null;
1718
1885
  marks = [];
@@ -29,6 +29,16 @@ export declare const PASSES_AS_IS: string;
29
29
  * and nothing is forwarded): fail closed.
30
30
  */
31
31
  export declare const ONCE: string;
32
+ /**
33
+ * The shell's handshake with its host (P085, P139), spliced into the runtime as
34
+ * `HANDSHAKE(topLevel, ask, answered, none, later)`. On a tab of its own (`topLevel`: the window is
35
+ * its own top, so its parent is itself and no host can hear it) there is no host to ask: `none()`
36
+ * at once, and nothing is asked. In a frame it asks (`ask()`, a promise of the host's answer) up to
37
+ * 40 times, 250 ms apart (`later(run, ms)`), since the host may start listening after the shell
38
+ * runs; the first answer is taken (`answered(result)`), once. After the 40th try with no answer,
39
+ * `none()`; an answer that comes later still is taken.
40
+ */
41
+ export declare const HANDSHAKE: string;
32
42
  /**
33
43
  * The shell's runtime: the code that runs first in the frame, before any content. Plain ES2020,
34
44
  * no imports and no build step, so every engine (a browser frame now, a native web view later)
@@ -88,6 +88,42 @@ export const ONCE = String.raw `(passesAsIs, toText) => (value) => {
88
88
  }
89
89
  return text;
90
90
  }`;
91
+ /**
92
+ * The shell's handshake with its host (P085, P139), spliced into the runtime as
93
+ * `HANDSHAKE(topLevel, ask, answered, none, later)`. On a tab of its own (`topLevel`: the window is
94
+ * its own top, so its parent is itself and no host can hear it) there is no host to ask: `none()`
95
+ * at once, and nothing is asked. In a frame it asks (`ask()`, a promise of the host's answer) up to
96
+ * 40 times, 250 ms apart (`later(run, ms)`), since the host may start listening after the shell
97
+ * runs; the first answer is taken (`answered(result)`), once. After the 40th try with no answer,
98
+ * `none()`; an answer that comes later still is taken.
99
+ */
100
+ export const HANDSHAKE = String.raw `(topLevel, ask, answered, none, later) => {
101
+ if (topLevel === true) {
102
+ none();
103
+ return;
104
+ }
105
+ let initialized = false;
106
+ let tries = 0;
107
+ const initialize = () => {
108
+ if (initialized) {
109
+ return;
110
+ }
111
+ if (tries >= 40) {
112
+ none();
113
+ return;
114
+ }
115
+ tries += 1;
116
+ ask().then((result) => {
117
+ if (initialized) {
118
+ return;
119
+ }
120
+ initialized = true;
121
+ answered(result);
122
+ }, () => {});
123
+ later(initialize, 250);
124
+ };
125
+ initialize();
126
+ }`;
91
127
  /**
92
128
  * The shell's runtime: the code that runs first in the frame, before any content. Plain ES2020,
93
129
  * no imports and no build step, so every engine (a browser frame now, a native web view later)
@@ -151,6 +187,9 @@ export const SHELL_RUNTIME = String.raw `(() => {
151
187
  // such name goes on the shell's own script element (data-porthole-unfixed, for a test or a
152
188
  // person to see) and, once the shell can speak, to the host as an error report.
153
189
  const shellScript = document.currentScript;
190
+ // The platform's own, kept before the shell's guards wrap it: the shell marks the document's root
191
+ // with it (data-porthole-host, P139).
192
+ const setAttributeOfShell = Element.prototype.setAttribute;
154
193
  const unfixed = [];
155
194
  let tellUnfixed = (_name) => {};
156
195
  const lock = (target, name, value) => {
@@ -2228,36 +2267,43 @@ export const SHELL_RUNTIME = String.raw `(() => {
2228
2267
  whenLoaded(() => void render({ html: plan.document }));
2229
2268
  }
2230
2269
 
2231
- // Ask until answered: the host may start listening after this runs.
2232
- let initialized = false;
2233
- let tries = 0;
2234
- const initialize = () => {
2235
- if (initialized) {
2236
- return;
2237
- }
2238
- if (tries >= 40) {
2239
- // No host answered: the runtime has nothing to offer.
2240
- runtimeOffer(null);
2241
- return;
2242
- }
2243
- tries += 1;
2244
- request("ui/initialize", {
2245
- protocolVersion: plan.protocolVersion,
2246
- appInfo: { name: "porthole-shell", version: "1" },
2247
- appCapabilities: {},
2248
- }).then((result) => {
2249
- if (initialized) {
2250
- return;
2251
- }
2252
- initialized = true;
2270
+ // The handshake (HANDSHAKE, P085): asked until answered, since the host may start listening
2271
+ // after this runs; on a tab of its own, not asked at all (P139): its parent is itself, so no host
2272
+ // hears it, and the runtime has nothing to offer from the start. How it ended goes on the
2273
+ // document's root element (data-porthole-host: "answered", or "none" where no host answered), for
2274
+ // a test, a person or a tool that shoots the page to see (P139): not on the shell's own script,
2275
+ // which a whole document's render takes out with the body it replaces, while the root stays (the
2276
+ // render adds the page's own attributes to it and removes none). The page's own word, never a
2277
+ // gate, set through the platform's setAttribute kept before the guards (setAttributeOfShell).
2278
+ const shellRoot = document.documentElement;
2279
+ const settled = (how) => {
2280
+ try {
2281
+ callOf(setAttributeOfShell, shellRoot, ["data-porthole-host", how]);
2282
+ } catch (_) {}
2283
+ };
2284
+ const handshake = ${HANDSHAKE};
2285
+ handshake(
2286
+ window.top === window,
2287
+ () =>
2288
+ request("ui/initialize", {
2289
+ protocolVersion: plan.protocolVersion,
2290
+ appInfo: { name: "porthole-shell", version: "1" },
2291
+ appCapabilities: {},
2292
+ }),
2293
+ (result) => {
2294
+ settled("answered");
2253
2295
  const capabilities = result && result.hostCapabilities;
2254
2296
  const experimental = capabilities && capabilities.experimental;
2255
2297
  runtimeOffer(experimental && typeof experimental === "object" ? experimental["porthole/runtime"] : null);
2256
2298
  applyTheme(result && result.hostContext);
2257
2299
  notify("ui/notifications/initialized", {});
2258
2300
  schedule();
2259
- }, () => {});
2260
- setTimeout(initialize, 250);
2261
- };
2262
- initialize();
2301
+ },
2302
+ () => {
2303
+ // No host answered (or none can): the runtime has nothing to offer.
2304
+ settled("none");
2305
+ runtimeOffer(null);
2306
+ },
2307
+ (run, ms) => setTimeout(run, ms),
2308
+ );
2263
2309
  })();`;
package/docs/ADOPTING.md CHANGED
@@ -289,7 +289,9 @@ composer.onClose(() => display.annotations.clearSelection());
289
289
 
290
290
  - **React** (P118): `PortholeFrame` and `PortholeView` take the same as props: `annotating`,
291
291
  `annotations`, `focusedAnnotation` and `trackedAnnotation` (the mark to follow, by value; `null`
292
- stops), every report through `onAnnotation` (`tracked` too). The selection is cleared through a
292
+ stops), `trackedSelection` (true while your composer is open: the selection is followed in the
293
+ mark's place, P138; give it from the first render, `false` until then, so the mode starts with
294
+ `keepSelection`, P140: it is read as the mode starts, and giving it later restarts nothing), every report through `onAnnotation` (`tracked` and `selectionTracked` too). The selection is cleared through a
293
295
  ref, which holds `clearSelection()` only (a `PortholeFrameHandle`; never the display, whose life
294
296
  is the binding's); with no display running it does nothing. Errors the core's calls throw (an id
295
297
  no shown mark has, a config without `annotate`) reach `onHostError`, kind `"annotations"`.
@@ -436,6 +438,53 @@ composer.onClose(() => display.annotations.clearSelection());
436
438
  composer.openAt(frame, clipToFrame(at), report.anchor); // the frame's px: clip them, then add its position
437
439
  });
438
440
  ```
441
+ - **A composer that stays beside what it is for** (P138, P140): `selected` comes once for a pick
442
+ (and for words again only once a scroll settles), and by default a pick's outline goes with it
443
+ and the frame keeps nothing of it. To follow it, start with `keepSelection: true`
444
+ (`annotations.start({ elements: true, keepSelection: true })`; React does it while you give
445
+ `trackedSelection`), so the frame keeps what is picked or selected, then follow the selection
446
+ while your composer is open, `annotations.track({ selection: true })` (React:
447
+ `trackedSelection`). The frame highlights it (a picked element in the picking outline) and
448
+ reports `selectionTracked` as `tracked` reports a mark: at most 60 a second, its `rect` clamped,
449
+ `documentRect`, `lastLineDocumentRect` and `scroll` as above, and `inView`, so you hide the
450
+ composer (and show your own marker at the frame's edge, from `documentRect` and `scroll`, clipped)
451
+ while it is out of view. `state: "orphaned"`: it isn't in the page now (a re-render took it out;
452
+ a reload); keep the person's words, it may be found again. Without `keepSelection`, a follow
453
+ asked after `selected` has nothing to follow and answers `orphaned`; one asked before the pick
454
+ follows each selection made while it lasts. It follows the latest `selected`, so a new pick or
455
+ selection moves it. One thing is followed at a time: it takes a followed mark's place, and
456
+ `track(null)`, a mark's id or `clear` ends it, the highlight with it. End it on every close
457
+ (posted, dismissed, Escape in your composer: the frame's own Escape doesn't end it), as you
458
+ clear the selection: the page reads when it starts and ends, so an end on every close says
459
+ nothing of what came of it. The composer moves at the page's word: guard it as below, armed
460
+ again each time it moves or shows again. An older shell sends nothing (and draws nothing): place
461
+ by `selected` until the first `selectionTracked`, which a newer one sends at its next animation
462
+ frame. Under `keepSelection` a newer shell keeps the picked element outlined from the pick on,
463
+ so there is no gap before the follow's highlight; ask for the follow before a `start` or `stop`
464
+ you send as the composer opens (React orders them so), or the stop ends that outline a moment
465
+ before the follow draws it again. Until the follow comes, the outline ends as a selection does
466
+ (the next pick, Escape, `clearSelection`, `start`, `stop`, `clear`). Without `keepSelection` the
467
+ outline goes with the pick, as before 0.14.15. While you follow the selection, `selected` isn't
468
+ re-sent after a scroll: read where it is from `selectionTracked`; and while you don't, a
469
+ `selectionTracked` from the page is dropped unread.
470
+
471
+ ```js
472
+ display.annotations.start({ elements: true, text: true, keepSelection: true });
473
+ display.on("annotation", (report) => {
474
+ if (report.type === "selected") {
475
+ composer.openBeside(frame, report.rect, report.anchor); // as before: an older shell stops here
476
+ display.annotations.track({ selection: true });
477
+ }
478
+ if (report.type !== "selectionTracked") return;
479
+ if (report.state === "orphaned") return composer.detach(); // keep its words
480
+ if (!report.inView) return composer.collapseToMarker(report.documentRect, report.scroll);
481
+ if (composer.moveBeside(frame, report.rect) > 4) composerGuard.placed();
482
+ });
483
+ composer.onClose(() => {
484
+ display.annotations.track(null); // or the open card's mark: track(cardId)
485
+ display.annotations.clearSelection();
486
+ });
487
+ ```
439
488
  - **The keyboard** (P133): each marker is a button in the frame's Tab order, after the page's own
440
489
  stops, in reading order, named for what it is (`3 comments on "the words"`, from the `count` and
441
490
  the anchor's words, without an element's tag, P134; in English, whatever your UI's language). The