@botiverse/porthole 0.14.15 → 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.
@@ -1,4 +1,4 @@
1
- import { ANNOTATE_METHODS, } from "../annotate/types.js";
1
+ import { ANNOTATE_METHODS } from "../annotate/types.js";
2
2
  import { annotateMode, checkMarks, clampRect, followsSelection, hasMarker, inViewport, parseReport, } from "../annotate/validate.js";
3
3
  import { FIND_LIMITS, FIND_METHODS } from "../find/types.js";
4
4
  import { blankQuery, checkFindQuery, parseFindReport, parseFindResult } from "../find/validate.js";
@@ -370,6 +370,12 @@ export function createHost(config, options = {}) {
370
370
  if (type === undefined) {
371
371
  return;
372
372
  }
373
+ // The followed selection (P138) only while the host follows it, and dropped unread
374
+ // otherwise (P140): a host that doesn't follow it takes it as 0.14.14 took a method it
375
+ // didn't know, so a malformed one is no refusal either.
376
+ if (type === "selectionTracked" && !trackingSelection) {
377
+ return;
378
+ }
373
379
  let report = parseReport({ ...(isRecord(raw.params) ? raw.params : {}), type });
374
380
  if (report === null) {
375
381
  void through.call("annotate", null);
@@ -394,12 +400,9 @@ export function createHost(config, options = {}) {
394
400
  emit("annotation", withinFrame(report));
395
401
  return;
396
402
  }
397
- // The followed selection (P138): only while the host follows it, on the same 60 a second
398
- // (one followed thing at a time), past the bridge's rate as the followed mark's.
403
+ // The followed selection (P138): only while the host follows it (above), on the same 60 a
404
+ // second (one followed thing at a time), past the bridge's rate as the followed mark's.
399
405
  if (report.type === "selectionTracked") {
400
- if (!trackingSelection) {
401
- return;
402
- }
403
406
  const at = Date.now();
404
407
  while (trackedTimes.length > 0 && at - trackedTimes[0] >= 1_000) {
405
408
  trackedTimes.shift();
@@ -420,7 +423,7 @@ export function createHost(config, options = {}) {
420
423
  }
421
424
  // A pick ends with it; holding a block (P112) lasts until the host stops it.
422
425
  if (kind === "element" && annotating.elements === true) {
423
- annotating = annotating.text ? { elements: false, text: true } : null;
426
+ annotating = annotating.text ? { ...annotating, elements: false } : null;
424
427
  }
425
428
  break;
426
429
  }
@@ -436,7 +439,7 @@ export function createHost(config, options = {}) {
436
439
  return;
437
440
  }
438
441
  if (annotating.elements === true) {
439
- annotating = annotating.text ? { elements: false, text: true } : null;
442
+ annotating = annotating.text ? { ...annotating, elements: false } : null;
440
443
  }
441
444
  break;
442
445
  case "anchored": {
@@ -301,7 +301,11 @@ export interface FindControls {
301
301
  * given to every frame the display runs (a reload, a navigation recovered from).
302
302
  */
303
303
  export interface AnnotationControls {
304
- /** Lets the person point at elements, select text, or both (default both). */
304
+ /**
305
+ * Lets the person point at elements, select text, or both (default both). With
306
+ * `keepSelection: true` (P140) the frame keeps what is selected for `track({ selection: true })`;
307
+ * without it, nothing is kept and a pick's outline goes with the pick.
308
+ */
305
309
  start(mode?: AnnotateMode): void;
306
310
  stop(): void;
307
311
  /** Marks these anchors (replacing the marks before); the frame reports where they are. */
@@ -321,14 +325,17 @@ export interface AnnotationControls {
321
325
  * highlights it while it is followed (an element in the outline it had while it was picked) and
322
326
  * reports `{ type: "selectionTracked", ... }` with the same boxes as `tracked` and `inView`, or
323
327
  * `state: "orphaned"` while it isn't in the page; at most 60 a second together with `tracked`.
324
- * A `show` leaves it, and `stop` (or a pick ending) too: it ends with `track(null)`, `track(id)`
328
+ * The frame keeps a selection to follow only for a host that said so at `start`
329
+ * (`keepSelection`, P140), or one that already follows the selection as it is made: without
330
+ * either, a follow asked after `selected` has nothing to follow and answers `orphaned`. A `show`
331
+ * leaves it, and `stop` (or a pick ending) too: it ends with `track(null)`, `track(id)`
325
332
  * or `clear` (comment posted, composer dismissed, Escape in it), and the highlight with it. A
326
333
  * newer shell answers at its next animation frame; an older one sends nothing (it reads the
327
334
  * message as `track(null)`), so until a `selectionTracked` comes, place by `selected`'s boxes.
328
- * Kept for a frame that runs later, which has no selection: it answers `orphaned`. The element
329
- * just picked stays outlined until then, so call it before a `start` or `stop` sent with it (a
330
- * stop ends that outline); while followed, `selected` isn't re-sent after a scroll (Tenny's
331
- * review).
335
+ * Kept for a frame that runs later, which has no selection: it answers `orphaned`. Under
336
+ * `keepSelection` the element just picked stays outlined until then, so call it before a `start`
337
+ * or `stop` sent with it (a stop ends that outline); while followed, `selected` isn't re-sent
338
+ * after a scroll (Tenny's review).
332
339
  */
333
340
  track(target: AnnotationTrackTarget): void;
334
341
  /** Removes every mark. */
@@ -311,7 +311,8 @@ export interface PortholeFrameProps {
311
311
  /**
312
312
  * Annotations, where the config declares `annotate` (P053): what the person may point at now
313
313
  * (elements, text, or both), or null to stop. A picked element ends element picking: set it
314
- * again to pick again.
314
+ * again to pick again. `keepSelection` is set for you on a start made while `trackedSelection` is
315
+ * given (P140).
315
316
  */
316
317
  readonly annotating?: AnnotateMode | null;
317
318
  /**
@@ -347,6 +348,13 @@ export interface PortholeFrameProps {
347
348
  * thing at a time); false, or leaving it out, ends it and its highlight (the comment posted, the
348
349
  * composer dismissed, Escape in it), and `trackedAnnotation`'s mark is followed again. Until a
349
350
  * `selectionTracked` comes, place by `selected`'s boxes: an older shell sends none.
351
+ *
352
+ * Give it from the first render, `false` until the composer opens (P140): each start of
353
+ * `annotating` made while it is given carries `keepSelection`, so the frame keeps what is picked
354
+ * or selected (and the picked element outlined) for the follow. It is read as a mode starts:
355
+ * giving it, or leaving it out, later restarts nothing, and counts from the next start. Left out
356
+ * when the mode started, the frame keeps nothing, and a follow asked after the pick has nothing
357
+ * to follow (`orphaned`).
350
358
  */
351
359
  readonly trackedSelection?: boolean;
352
360
  /** The display's imperative calls (`PortholeFrameHandle`, P118): React 19's `ref` prop. */
@@ -729,9 +729,17 @@ function Mount({ frame, page, running, findFor, initialHeightPx, placeholder, ru
729
729
  : JSON.stringify([focusedAnnotation]);
730
730
  // By value: the same marks given again don't mark them again.
731
731
  const annotations = useByValue(frame.annotations);
732
+ // The mode, by value: what the person may point at, and the host's own `keepSelection`. Not
733
+ // whether `trackedSelection` is given (P140, Ferryman's review): that is read at each start, so
734
+ // a composer's prop that appears or goes restarts no mode (which would turn a pick that ended
735
+ // back on, for the person's next click to pick again).
732
736
  const mode = annotating === undefined || annotating === null
733
737
  ? ""
734
- : JSON.stringify([annotating.elements ?? true, annotating.text ?? true]);
738
+ : JSON.stringify([
739
+ annotating.elements ?? true,
740
+ annotating.text ?? true,
741
+ annotating.keepSelection === true,
742
+ ]);
735
743
  useEffect(() => {
736
744
  const display = handle.current;
737
745
  if (annotates && display !== null) {
@@ -776,7 +784,11 @@ function Mount({ frame, page, running, findFor, initialHeightPx, placeholder, ru
776
784
  const wanted = mode === "" ? null : JSON.parse(mode);
777
785
  attempt(() => wanted === null
778
786
  ? display.annotations.stop()
779
- : display.annotations.start({ elements: wanted[0], text: wanted[1] }), latest());
787
+ : display.annotations.start({
788
+ elements: wanted[0],
789
+ text: wanted[1],
790
+ ...(wanted[2] || keepsSelection(latest()) ? { keepSelection: true } : {}),
791
+ }), latest());
780
792
  }, [annotates, mode]);
781
793
  useEffect(() => {
782
794
  const display = handle.current;
@@ -859,7 +871,7 @@ function applyAnnotations(display, frame) {
859
871
  display.annotations.focus(focused);
860
872
  }
861
873
  if (frame.annotating !== undefined && frame.annotating !== null) {
862
- display.annotations.start(frame.annotating);
874
+ display.annotations.start(keepsSelection(frame) ? { ...frame.annotating, keepSelection: true } : frame.annotating);
863
875
  }
864
876
  }, frame);
865
877
  }
@@ -872,6 +884,14 @@ function useByValue(value) {
872
884
  const key = value === undefined ? "" : JSON.stringify(value);
873
885
  return useMemo(() => (key === "" ? undefined : JSON.parse(key)), [key]);
874
886
  }
887
+ /**
888
+ * Whether a start keeps what is selected for a follow (P140): while `trackedSelection` is given
889
+ * (true or false), or the host's own `keepSelection` says so. Read at each start, never a reason
890
+ * for one.
891
+ */
892
+ function keepsSelection(frame) {
893
+ return frame.annotating?.keepSelection === true || frame.trackedSelection !== undefined;
894
+ }
875
895
  /** What a display follows (P118, P138): a mark's id, the selection (this one object), or nothing. */
876
896
  const SELECTION = Object.freeze({ selection: true });
877
897
  /** What the props ask to follow: the selection while `trackedSelection`, else the mark, if any. */
@@ -61,9 +61,11 @@ export declare const WORD_LATE: string;
61
61
  * - the last line (P133): where a selection or a mark's words end, in the document's coordinates
62
62
  * too (`lastLineDocumentRect`), so a host places its UI after them;
63
63
  * - the selection followed (P138): what the last `selected` reported (the element picked, or the
64
- * words selected) is kept, and while the host follows it (`track` with `selection`) it is drawn
65
- * in the layer and its boxes are reported as a followed mark's are (`selectionTracked`), with
66
- * whether it is in view, or that it is gone; it takes no pointer, no focus and no key.
64
+ * words selected) is kept while the host follows the selection (`track` with `selection`) or said
65
+ * at `start` that it will (`keepSelection`, P140), and nothing is kept otherwise; while followed
66
+ * it is drawn in the layer and its boxes are reported as a followed mark's are
67
+ * (`selectionTracked`), with whether it is in view, or that it is gone; it takes no pointer, no
68
+ * focus and no key.
67
69
  *
68
70
  * It shares the realm with the content, which can interfere with all of it: the host takes its
69
71
  * reports as UI hints only.
@@ -105,9 +105,11 @@ export const WORD_LATE = String.raw `(at, now) => {
105
105
  * - the last line (P133): where a selection or a mark's words end, in the document's coordinates
106
106
  * too (`lastLineDocumentRect`), so a host places its UI after them;
107
107
  * - the selection followed (P138): what the last `selected` reported (the element picked, or the
108
- * words selected) is kept, and while the host follows it (`track` with `selection`) it is drawn
109
- * in the layer and its boxes are reported as a followed mark's are (`selectionTracked`), with
110
- * whether it is in view, or that it is gone; it takes no pointer, no focus and no key.
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.
111
113
  *
112
114
  * It shares the realm with the content, which can interfere with all of it: the host takes its
113
115
  * reports as UI hints only.
@@ -436,20 +438,25 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
436
438
  // The selection last reported as selected (P138): its anchor, and what it is in the page (the
437
439
  // element picked, or a copy of the selection's range, which the page's changes keep up to
438
440
  // date and which stays when the page's own selection goes). Followed while the host asks
439
- // (track with selection), and drawn then. Each new selected replaces it.
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.
440
444
  let held = null;
441
445
  let followingSelection = false;
446
+ let keeping = false;
447
+ const keeps = () => followingSelection || keeping;
442
448
  // What the host was last told of it: "attached", "orphaned", or null (nothing yet).
443
449
  let heldTold = null;
444
450
  const heldGone = (found) => (found.range ? found.range.collapsed || !found.range.startContainer.isConnected : !found.element.isConnected);
445
451
  const heldShown = () => followingSelection && held !== null && heldTold !== "orphaned" && !heldGone(held.found);
446
- // The element just picked (P138, Tenny's review): it keeps its outline after selected, so
447
- // there is no gap before the host follows it, and the follow's highlight takes over where it
448
- // does. Without a follow (an older host) it ends as a selection does: the next pick or
449
- // selection, the host's clearSelection, a mode started or stopped, clear, Escape, or the
450
- // element leaving the page. Not unselected: a selection made after the pick has already
451
- // ended it as it was reported, so the one unselected can clear is one from before, which
452
- // the pick's own click takes away when text is selected too.
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.
453
460
  let picked = null;
454
461
  const endPick = () => {
455
462
  if (picked !== null) {
@@ -1090,6 +1097,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1090
1097
  if (followingSelection) {
1091
1098
  picked = null;
1092
1099
  }
1100
+ // Its end lets the selection go, unless the host said it follows it again (P140).
1101
+ if (!keeps()) {
1102
+ held = null;
1103
+ }
1093
1104
  trackedBox = null;
1094
1105
  trackedView = null;
1095
1106
  heldTold = null;
@@ -1100,9 +1111,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1100
1111
  draw();
1101
1112
  }
1102
1113
  };
1103
- // A new selected (P138): what is followed, if the selection is, from the next frame on.
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).
1104
1116
  const holdSelected = (anchor, found) => {
1105
- held = { anchor, found, tried: 0 };
1117
+ held = keeps() ? { anchor, found, tried: 0 } : null;
1106
1118
  if (followingSelection) {
1107
1119
  trackedBox = null;
1108
1120
  heldTold = null;
@@ -1653,7 +1665,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1653
1665
  }
1654
1666
  swallowUntil = performance.now() + 2000;
1655
1667
  holdSelected(anchor, { element });
1656
- picked = followingSelection ? null : element;
1668
+ picked = keeping && !followingSelection ? element : null;
1657
1669
  redraw();
1658
1670
  tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
1659
1671
  }, HOLD_MS),
@@ -1703,8 +1715,9 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1703
1715
  hover = null;
1704
1716
  setCursor(false);
1705
1717
  holdSelected(anchor, { element });
1706
- // Its outline stays (P138), now without its name, until the host follows it or it ends.
1707
- picked = followingSelection ? null : 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;
1708
1721
  draw();
1709
1722
  tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
1710
1723
  }, true);
@@ -1801,6 +1814,13 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1801
1814
  switch (data.method) {
1802
1815
  case M.start:
1803
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
+ }
1804
1824
  hover = null;
1805
1825
  picked = null;
1806
1826
  reported = null;
@@ -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
@@ -290,7 +290,8 @@ composer.onClose(() => display.annotations.clearSelection());
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
292
  stops), `trackedSelection` (true while your composer is open: the selection is followed in the
293
- mark's place, P138), every report through `onAnnotation` (`tracked` and `selectionTracked` too). The selection is cleared through a
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
294
295
  ref, which holds `clearSelection()` only (a `PortholeFrameHandle`; never the display, whose life
295
296
  is the binding's); with no display running it does nothing. Errors the core's calls throw (an id
296
297
  no shown mark has, a config without `annotate`) reach `onHostError`, kind `"annotations"`.
@@ -437,30 +438,38 @@ composer.onClose(() => display.annotations.clearSelection());
437
438
  composer.openAt(frame, clipToFrame(at), report.anchor); // the frame's px: clip them, then add its position
438
439
  });
439
440
  ```
440
- - **A composer that stays beside what it is for** (P138): `selected` comes once for a pick (and
441
- for words again only once a scroll settles), and a pick's outline goes with it. Follow the
442
- selection while your composer is open, `annotations.track({ selection: true })` (React:
443
- `trackedSelection`), and the frame highlights it (a picked element in the picking outline) and
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
444
448
  reports `selectionTracked` as `tracked` reports a mark: at most 60 a second, its `rect` clamped,
445
449
  `documentRect`, `lastLineDocumentRect` and `scroll` as above, and `inView`, so you hide the
446
450
  composer (and show your own marker at the frame's edge, from `documentRect` and `scroll`, clipped)
447
451
  while it is out of view. `state: "orphaned"`: it isn't in the page now (a re-render took it out;
448
- a reload); keep the person's words, it may be found again. It follows the latest `selected`, so a
449
- new pick or selection moves it. One thing is followed at a time: it takes a followed mark's
450
- place, and `track(null)`, a mark's id or `clear` ends it, the highlight with it. End it on every
451
- close (posted, dismissed, Escape in your composer: the frame's own Escape doesn't end it), as you
452
- clear the selection: the page reads when it starts and ends, so an end on every close says nothing
453
- of what came of it. The composer moves at the page's word: guard it as below, armed again each
454
- time it moves or shows again. An older shell sends nothing (and draws nothing): place by
455
- `selected` until the first `selectionTracked`, which a newer one sends at its next animation
456
- frame. A newer shell keeps the picked element outlined from the pick on, so there is no gap
457
- before the follow's highlight; ask for the follow before a `start` or `stop` you send as the
458
- composer opens (React orders them so), or the stop ends that outline a moment before the follow
459
- draws it again. Without a follow the outline ends as a selection does (the next pick, Escape,
460
- `clearSelection`, `start`, `stop`, `clear`). While you follow the selection, `selected` isn't
461
- re-sent after a scroll: read where it is from `selectionTracked`.
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.
462
470
 
463
471
  ```js
472
+ display.annotations.start({ elements: true, text: true, keepSelection: true });
464
473
  display.on("annotation", (report) => {
465
474
  if (report.type === "selected") {
466
475
  composer.openBeside(frame, report.rect, report.anchor); // as before: an older shell stops here