@botiverse/porthole 0.14.13 → 0.14.15

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,5 +1,5 @@
1
1
  import { ANNOTATE_METHODS, } from "../annotate/types.js";
2
- import { annotateMode, checkMarks, clampRect, hasMarker, parseReport, } from "../annotate/validate.js";
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";
5
5
  import { createBridge, onceConsent, } from "../bridge/bridge.js";
@@ -45,6 +45,7 @@ const REPORTS = {
45
45
  [ANNOTATE_METHODS.anchored]: "anchored",
46
46
  [ANNOTATE_METHODS.activated]: "activated",
47
47
  [ANNOTATE_METHODS.tracked]: "tracked",
48
+ [ANNOTATE_METHODS.selectionTracked]: "selectionTracked",
48
49
  };
49
50
  /** What the frame says of find in page unasked (P131), by method. */
50
51
  const FIND_REPORTS = {
@@ -164,8 +165,11 @@ export function createHost(config, options = {}) {
164
165
  let annotating = null;
165
166
  let marks = [];
166
167
  let activeMark = null;
167
- // The mark the host follows (P112), and when it took each `tracked` in the last second.
168
+ // The mark the host follows (P112), or whether it follows the selection instead (P138), and
169
+ // when it took each `tracked` or `selectionTracked` in the last second: one followed thing
170
+ // at a time, one rate for both.
168
171
  let tracking = null;
172
+ let trackingSelection = false;
169
173
  const trackedTimes = [];
170
174
  // Find in page (P131): the query shown (for the content it was asked of only: a new run or
171
175
  // other content forgets it), whether the host takes the shortcut (kept for every frame the
@@ -275,6 +279,10 @@ export function createHost(config, options = {}) {
275
279
  if (tracking !== null) {
276
280
  toFrame(ANNOTATE_METHODS.track, { id: tracking });
277
281
  }
282
+ // A new frame has no selection: it answers `orphaned` (P138).
283
+ if (trackingSelection) {
284
+ toFrame(ANNOTATE_METHODS.track, { id: null, selection: true });
285
+ }
278
286
  };
279
287
  /**
280
288
  * The frame's viewport as the platform tells it now; undefined where it can't (no
@@ -324,6 +332,16 @@ export function createHost(config, options = {}) {
324
332
  case "activated":
325
333
  case "tracked":
326
334
  return { ...report, rect: clampRect(report.rect, viewport) };
335
+ case "selectionTracked":
336
+ // In view only where the page says so and its box, as the host reads the viewport,
337
+ // reaches into it (P138): a box the clamp puts on an edge is never in view.
338
+ return report.state === "orphaned"
339
+ ? report
340
+ : {
341
+ ...report,
342
+ rect: clampRect(report.rect, viewport),
343
+ inView: report.inView && inViewport(report.rect, viewport),
344
+ };
327
345
  case "anchored":
328
346
  return {
329
347
  ...report,
@@ -376,6 +394,23 @@ export function createHost(config, options = {}) {
376
394
  emit("annotation", withinFrame(report));
377
395
  return;
378
396
  }
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.
399
+ if (report.type === "selectionTracked") {
400
+ if (!trackingSelection) {
401
+ return;
402
+ }
403
+ const at = Date.now();
404
+ while (trackedTimes.length > 0 && at - trackedTimes[0] >= 1_000) {
405
+ trackedTimes.shift();
406
+ }
407
+ if (trackedTimes.length >= TRACKED_PER_SECOND) {
408
+ return;
409
+ }
410
+ trackedTimes.push(at);
411
+ emit("annotation", withinFrame(report));
412
+ return;
413
+ }
379
414
  switch (report.type) {
380
415
  case "selected": {
381
416
  const kind = report.anchor.kind;
@@ -540,6 +575,7 @@ export function createHost(config, options = {}) {
540
575
  if (activeMark !== null && !marks.some((mark) => mark.id === activeMark)) {
541
576
  activeMark = null;
542
577
  }
578
+ // A followed selection (P138) isn't a mark: a show leaves it.
543
579
  if (tracking !== null && !marks.some((mark) => mark.id === tracking)) {
544
580
  tracking = null;
545
581
  toFrame(ANNOTATE_METHODS.track, { id: null });
@@ -557,12 +593,22 @@ export function createHost(config, options = {}) {
557
593
  activeMark = id;
558
594
  toFrame(ANNOTATE_METHODS.focus, { id });
559
595
  },
560
- track(id) {
596
+ track(target) {
561
597
  needsAnnotate("track");
598
+ // The selection (P138), under `id: null`: an older shell follows nothing.
599
+ if (followsSelection(target)) {
600
+ tracking = null;
601
+ trackingSelection = true;
602
+ trackedTimes.length = 0;
603
+ toFrame(ANNOTATE_METHODS.track, { id: null, selection: true });
604
+ return;
605
+ }
606
+ const id = target;
562
607
  if (id !== null && !marks.some((mark) => mark.id === id)) {
563
608
  throw new TypeError(`annotations.track: no mark ${JSON.stringify(id)} is shown`);
564
609
  }
565
610
  tracking = id;
611
+ trackingSelection = false;
566
612
  trackedTimes.length = 0;
567
613
  toFrame(ANNOTATE_METHODS.track, { id });
568
614
  },
@@ -571,6 +617,7 @@ export function createHost(config, options = {}) {
571
617
  marks = [];
572
618
  activeMark = null;
573
619
  tracking = null;
620
+ trackingSelection = false;
574
621
  toFrame(ANNOTATE_METHODS.clear, {});
575
622
  },
576
623
  clearSelection() {
@@ -581,9 +628,10 @@ export function createHost(config, options = {}) {
581
628
  focusMark(id) {
582
629
  // Host → frame only, and kept for no later frame (P134). A mark that has gone, or has no
583
630
  // marker, is nothing to ask for, and no fault: the host's card closed with the mark's.
631
+ // Stamped as it is sent: a frame judges by that how old the word is as it takes it (P137).
584
632
  needsAnnotate("focusMark");
585
633
  if (marks.some((mark) => mark.id === id && hasMarker(mark))) {
586
- toFrame(ANNOTATE_METHODS.focusMark, { id });
634
+ toFrame(ANNOTATE_METHODS.focusMark, { id, at: Date.now() });
587
635
  }
588
636
  },
589
637
  };
@@ -1,4 +1,4 @@
1
- import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
1
+ import type { AnnotateMode, AnnotationMark, AnnotationReport, AnnotationTrackTarget } from "../annotate/types.ts";
2
2
  import type { FindOptions, FindResult } from "../find/types.ts";
3
3
  import type { Refused } from "../bridge/refusal.ts";
4
4
  import type { Confirm, CapabilityHandlers, Consent, DataCache, Refusal, Show } from "../bridge/types.ts";
@@ -315,8 +315,22 @@ export interface AnnotationControls {
315
315
  * Throws for an id no shown mark has; a `show` without it, or `clear`, stops it. From a newer
316
316
  * shell (P132) each also carries the mark's `documentRect` and the document's `scroll`, so
317
317
  * following one mark tells how far the document scrolled, for every mark placed by `documentRect`.
318
+ *
319
+ * `{ selection: true }` (P138) follows the selection the frame last reported as `selected` (the
320
+ * element picked, or the words selected) instead, for a composer that stays beside it: the frame
321
+ * highlights it while it is followed (an element in the outline it had while it was picked) and
322
+ * reports `{ type: "selectionTracked", ... }` with the same boxes as `tracked` and `inView`, or
323
+ * `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)`
325
+ * or `clear` (comment posted, composer dismissed, Escape in it), and the highlight with it. A
326
+ * newer shell answers at its next animation frame; an older one sends nothing (it reads the
327
+ * 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).
318
332
  */
319
- track(id: string | null): void;
333
+ track(target: AnnotationTrackTarget): void;
320
334
  /** Removes every mark. */
321
335
  clear(): void;
322
336
  /**
@@ -338,11 +352,12 @@ export interface AnnotationControls {
338
352
  *
339
353
  * On a calm page it lands at once, from anywhere on the host's page. While the frame is finding
340
354
  * its marks (a `show` just sent, the content just changed) it waits, and is then dropped unless
341
- * the focus is in the frame by then (P135), so a word that comes late takes no keyboard from a
342
- * person who moved on. Nothing says it was dropped: if the frame isn't your page's
355
+ * the focus is in the frame by then (P135). One the frame takes more than 100 ms after you sent
356
+ * it (its page is busy) is held to the same test (P137), so a word that comes late takes no
357
+ * keyboard from a person who moved on. Nothing says it was dropped: if the frame isn't your page's
343
358
  * `document.activeElement` soon after and the person hasn't moved on, call `focus()` and then
344
- * `focusMark(id)` again. Known gap: on a nested page that had the focus, `focus()` doesn't bring
345
- * it back into the page, so a second call that waits is dropped too (ADOPTING).
359
+ * `focusMark(id)` again. On a nested page only `focus()` reaches the page (P136): the frame's own
360
+ * `focus()` stops at its shell, and a second call that waits is dropped.
346
361
  */
347
362
  focusMark(id: string): void;
348
363
  }
package/dist/index.d.ts CHANGED
@@ -47,7 +47,7 @@ export { admitContent, admitFiles, type AdmitFilesResult, answerGuide, checkTool
47
47
  export { writeClipboard } from "./host/clipboard.ts";
48
48
  export { httpLocator, LocateError, servedOrOpaque, type HttpLocatorOptions, type ServedMeta, } from "./host/locator.ts";
49
49
  export type { AnnotationControls, FindControls, DisplayControls, DisplayEvents, FrameBlock, FrameOutcome, DisplayHandle, HostOptions, MountOptions, PortholeHost, } from "./host/types.ts";
50
- export { ANNOTATE_METHODS, ANNOTATION_LIMITS, type AnchorResult, type AnchorState, type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type AnnotationMarkKind, type AnnotationRect, type AnnotationReport, type AnnotationScroll, type AnnotationSelector, type CssSelector, type TextPositionSelector, type TextQuoteSelector, } from "./annotate/types.ts";
50
+ export { ANNOTATE_METHODS, ANNOTATION_LIMITS, type AnchorResult, type AnchorState, type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type AnnotationMarkKind, type AnnotationRect, type AnnotationReport, type AnnotationScroll, type AnnotationSelector, type AnnotationTrackTarget, type CssSelector, type TextPositionSelector, type TextQuoteSelector, } from "./annotate/types.ts";
51
51
  export { parseAnchor, parseRect, parseReport, parseScroll } from "./annotate/validate.ts";
52
52
  export { FIND_LIMITS, FIND_METHODS, type FindDirection, type FindOptions, type FindReport, type FindResult, } from "./find/types.ts";
53
53
  export { parseFindReport, parseFindResult } from "./find/validate.ts";
@@ -103,6 +103,12 @@ export declare const SHELL_BEAT_METHOD = "porthole/shell/beat";
103
103
  * that names the ask (`asked`). The host asks as it hears focus move into the frame.
104
104
  */
105
105
  export declare const SHELL_LOOK_METHOD = "porthole/shell/look";
106
+ /**
107
+ * The host's word to a nested page's shell (P136) that it moved the focus into the frame: pass it on
108
+ * to the page, in this task, not in the focus event (where the shell's move doesn't take). Sent by
109
+ * `display.focus()` alone; a page has no way to say it.
110
+ */
111
+ export declare const SHELL_FOCUS_METHOD = "porthole/shell/focus";
106
112
  /** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
107
113
  export declare const SHELL_METHOD_PREFIX = "porthole/shell/";
108
114
  /** A page's word that it used storage, once per load (P111): never a key or a value. */
@@ -11,6 +11,12 @@ export const SHELL_BEAT_METHOD = "porthole/shell/beat";
11
11
  * that names the ask (`asked`). The host asks as it hears focus move into the frame.
12
12
  */
13
13
  export const SHELL_LOOK_METHOD = "porthole/shell/look";
14
+ /**
15
+ * The host's word to a nested page's shell (P136) that it moved the focus into the frame: pass it on
16
+ * to the page, in this task, not in the focus event (where the shell's move doesn't take). Sent by
17
+ * `display.focus()` alone; a page has no way to say it.
18
+ */
19
+ export const SHELL_FOCUS_METHOD = "porthole/shell/focus";
14
20
  /** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
15
21
  export const SHELL_METHOD_PREFIX = "porthole/shell/";
16
22
  /** A page's word that it used storage, once per load (P111): never a key or a value. */
@@ -1,5 +1,5 @@
1
1
  import { DOOR_SANDBOX_TOKENS } from "../compile/policy.js";
2
- import { SHELL_BEAT_METHOD, SHELL_LOOK_METHOD, SHELL_METHOD_PREFIX, SHELL_STATE_METHOD, } from "../isolation/types.js";
2
+ import { SHELL_BEAT_METHOD, SHELL_FOCUS_METHOD, SHELL_LOOK_METHOD, SHELL_METHOD_PREFIX, SHELL_STATE_METHOD, } from "../isolation/types.js";
3
3
  import { postMessageTransport } from "../transport/post-message.js";
4
4
  import { focusGuard } from "./focus-guard.js";
5
5
  /** A shell's own message (P111), by its namespace. */
@@ -169,6 +169,11 @@ export const webPlatform = {
169
169
  },
170
170
  focus() {
171
171
  guard.focus(frame);
172
+ // A nested page (P136): the move stops at its shell on every engine, one way or another,
173
+ // and only the shell can pass it on. Only a move that landed: the shell asks no more of it.
174
+ if (nested && view.document.activeElement === frame) {
175
+ opened.send({ jsonrpc: "2.0", method: SHELL_FOCUS_METHOD });
176
+ }
172
177
  },
173
178
  onLoad(listener) {
174
179
  loaded.add(listener);
@@ -159,7 +159,8 @@ export interface PortholeFrameHandle {
159
159
  * once Escape closed your own view of that mark. Nothing happens for an id with no marker, or
160
160
  * while no display runs. A config without `annotate`: `onHostError`, kind `"annotations"`. While
161
161
  * the frame is finding its marks it waits, and is dropped unless the focus is in the frame by
162
- * then (P135): call it again after your own move of the focus into the frame.
162
+ * then (P135), and so is one a busy page takes late (P137): call it again after your own move of
163
+ * the focus into the frame.
163
164
  */
164
165
  focusMark(id: string): void;
165
166
  /**
@@ -337,6 +338,17 @@ export interface PortholeFrameProps {
337
338
  * stop the following, as the core's `show` does; it starts again once they have it back.
338
339
  */
339
340
  readonly trackedAnnotation?: string | null;
341
+ /**
342
+ * Follow the selection instead (`annotations.track({ selection: true })`, P138): while true, the
343
+ * element the person picked, or the words they selected, as the last `selected` reported them, is
344
+ * highlighted in the frame and `onAnnotation` gets `{ type: "selectionTracked", ... }` as it moves
345
+ * (the boxes `tracked` has, and `inView`; or `state: "orphaned"` while it isn't in the page), for
346
+ * a composer that stays beside it. It takes `trackedAnnotation`'s place while true (one followed
347
+ * thing at a time); false, or leaving it out, ends it and its highlight (the comment posted, the
348
+ * composer dismissed, Escape in it), and `trackedAnnotation`'s mark is followed again. Until a
349
+ * `selectionTracked` comes, place by `selected`'s boxes: an older shell sends none.
350
+ */
351
+ readonly trackedSelection?: boolean;
340
352
  /** The display's imperative calls (`PortholeFrameHandle`, P118): React 19's `ref` prop. */
341
353
  readonly ref?: Ref<PortholeFrameHandle>;
342
354
  /**
@@ -439,7 +439,8 @@ export function PortholeFrame(props) {
439
439
  function Mount({ frame, page, running, findFor, initialHeightPx, placeholder, run, }) {
440
440
  const holder = useRef(null);
441
441
  const handle = useRef(null);
442
- // The mark the display follows now, as the core keeps it (P118), and the prop as last seen.
442
+ // The mark the display follows now, or the selection (P138), as the core keeps it (P118), and
443
+ // the props as last seen.
443
444
  const following = useRef(null);
444
445
  const asked = useRef(null);
445
446
  const [ready, setReady] = useState(false);
@@ -649,9 +650,10 @@ function Mount({ frame, page, running, findFor, initialHeightPx, placeholder, ru
649
650
  if (config.capabilities.annotate !== undefined) {
650
651
  applyAnnotations(display, first);
651
652
  }
652
- // The followed mark, once the marks are shown; without `annotate`, the core's error.
653
+ // The followed mark or selection, once the marks are shown; without `annotate`, the core's
654
+ // error.
653
655
  following.current = null;
654
- const wanted = first.trackedAnnotation ?? null;
656
+ const wanted = followedOf(first);
655
657
  asked.current = wanted;
656
658
  if (wanted !== null) {
657
659
  attempt(() => {
@@ -730,47 +732,52 @@ function Mount({ frame, page, running, findFor, initialHeightPx, placeholder, ru
730
732
  const mode = annotating === undefined || annotating === null
731
733
  ? ""
732
734
  : JSON.stringify([annotating.elements ?? true, annotating.text ?? true]);
733
- useEffect(() => {
734
- const display = handle.current;
735
- if (!annotates || display === null) {
736
- return;
737
- }
738
- const wanted = mode === "" ? null : JSON.parse(mode);
739
- attempt(() => wanted === null
740
- ? display.annotations.stop()
741
- : display.annotations.start({ elements: wanted[0], text: wanted[1] }), latest());
742
- }, [annotates, mode]);
743
735
  useEffect(() => {
744
736
  const display = handle.current;
745
737
  if (annotates && display !== null) {
746
738
  attempt(() => {
747
739
  display.annotations.show(annotations ?? []);
748
- // A show without the followed mark stops the following (the core's own).
749
- if (following.current !== null && !shown(annotations, following.current)) {
740
+ // A show without the followed mark stops the following (the core's own); the selection
741
+ // stays followed (P138).
742
+ if (typeof following.current === "string" && !shown(annotations, following.current)) {
750
743
  following.current = null;
751
744
  }
752
745
  }, latest());
753
746
  }
754
747
  }, [annotates, annotations]);
755
- // The followed mark follows its prop (after the marks above, so the two can change together).
756
- const trackedAnnotation = frame.trackedAnnotation ?? null;
748
+ // The followed mark, or the selection (P138), follows its props (after the marks above, so the
749
+ // two can change together).
750
+ const followed = followedOf(frame);
757
751
  useEffect(() => {
758
752
  const display = handle.current;
759
- const changed = trackedAnnotation !== asked.current;
760
- asked.current = trackedAnnotation;
761
- if (display === null || trackedAnnotation === following.current) {
753
+ const changed = followed !== asked.current;
754
+ asked.current = followed;
755
+ if (display === null || followed === following.current) {
762
756
  return;
763
757
  }
764
758
  // Its mark was taken off (the error, if any, was told when the prop said it): followed again
765
759
  // once the marks have it back.
766
- if (!changed && trackedAnnotation !== null && !shown(annotations, trackedAnnotation)) {
760
+ if (!changed && typeof followed === "string" && !shown(annotations, followed)) {
767
761
  return;
768
762
  }
769
763
  attempt(() => {
770
- display.annotations.track(trackedAnnotation);
771
- following.current = trackedAnnotation;
764
+ display.annotations.track(followed);
765
+ following.current = followed;
772
766
  }, latest());
773
- }, [trackedAnnotation, annotations]);
767
+ }, [followed, annotations]);
768
+ // The mode follows its prop, after the following above (P138, Tenny's review): a host that
769
+ // follows the selection and ends picking in one render has the frame follow it first, so the
770
+ // pick's outline goes straight to the follow's highlight, never through the stop's gap.
771
+ useEffect(() => {
772
+ const display = handle.current;
773
+ if (!annotates || display === null) {
774
+ return;
775
+ }
776
+ const wanted = mode === "" ? null : JSON.parse(mode);
777
+ attempt(() => wanted === null
778
+ ? display.annotations.stop()
779
+ : display.annotations.start({ elements: wanted[0], text: wanted[1] }), latest());
780
+ }, [annotates, mode]);
774
781
  useEffect(() => {
775
782
  const display = handle.current;
776
783
  const id = focusOf(latest().focusedAnnotation);
@@ -865,6 +872,12 @@ function useByValue(value) {
865
872
  const key = value === undefined ? "" : JSON.stringify(value);
866
873
  return useMemo(() => (key === "" ? undefined : JSON.parse(key)), [key]);
867
874
  }
875
+ /** What a display follows (P118, P138): a mark's id, the selection (this one object), or nothing. */
876
+ const SELECTION = Object.freeze({ selection: true });
877
+ /** What the props ask to follow: the selection while `trackedSelection`, else the mark, if any. */
878
+ function followedOf(frame) {
879
+ return frame.trackedSelection === true ? SELECTION : (frame.trackedAnnotation ?? null);
880
+ }
868
881
  /** Whether `marks` has a mark `id`. */
869
882
  function shown(marks, id) {
870
883
  return (marks ?? []).some((mark) => mark.id === id);
@@ -16,6 +16,16 @@ export declare const MARKER_HIT: string;
16
16
  * `alt`) what follows the tag in the label. An element with neither has no words.
17
17
  */
18
18
  export declare const MARKER_NAME: string;
19
+ /**
20
+ * Whether a host's `focusMark` is too old to land unasked (P137): `at` is the host's `Date.now()` as
21
+ * it sent the word, `now` the shell's, kept before content runs. Both read the one wall clock of
22
+ * this machine, the only clock two realms share (`performance.now()` counts from each one's own
23
+ * start). No number is an older host's word, which can't be known fresh. A word from ahead of the
24
+ * clock has the same bound behind it: two processes can read the clock a little apart, and past
25
+ * that the clock was set back, and the age says nothing. Comparisons only, nothing a page can
26
+ * patch, and a word that makes no number (`NaN`, `Infinity`) passes neither test.
27
+ */
28
+ export declare const WORD_LATE: string;
19
29
  /**
20
30
  * The shell's annotation runtime (P053), spliced into the shell's runtime (`__ANNOTATE__`) when
21
31
  * the config declares `annotate`, so it runs before any content does, with the DOM's own
@@ -23,7 +33,7 @@ export declare const MARKER_NAME: string;
23
33
  * in one).
24
34
  *
25
35
  * The host drives it (`porthole/annotate.start|stop|show|focus|clear|track|clearSelection|focusMark`)
26
- * and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked`):
36
+ * and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked|selectionTracked`):
27
37
  * - picking an element: the element under the pointer (or finger) is outlined with its name; a
28
38
  * click or tap picks it, and the content's own handlers never see that click (unless the content
29
39
  * patched the DOM's built-ins, P105); Escape cancels (while selecting text too, P112);
@@ -39,8 +49,8 @@ export declare const MARKER_NAME: string;
39
49
  * focus on it (P133), is reported (`activated`), and the content's own handlers never see it; a
40
50
  * draft is drawn apart, a dashed line and a hollow bubble with no number, and has a marker with
41
51
  * or without a count; the host's `focusMark` (P134) puts the focus on a marker that is there, and
42
- * tells nothing back; one that had to wait for the marks lands only if the focus is still in this
43
- * document (P135);
52
+ * tells nothing back; one that had to wait for the marks (P135), or that this document took late
53
+ * (P137), lands only if the focus is in this document by then;
44
54
  * - following: while a mark has a marker, once a scroll, a resize or a change of the content
45
55
  * settles, the marks that moved since the host was last told are reported, at most once a
46
56
  * second, so the host's own UI beside a mark can follow;
@@ -49,7 +59,11 @@ export declare const MARKER_NAME: string;
49
59
  * followed mark's (`tracked`) too, so a host places marks scrolled out of the frame, and keeps
50
60
  * them placed as the document scrolls, from one report and the followed mark's scroll;
51
61
  * - the last line (P133): where a selection or a mark's words end, in the document's coordinates
52
- * too (`lastLineDocumentRect`), so a host places its UI after them.
62
+ * too (`lastLineDocumentRect`), so a host places its UI after them;
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.
53
67
  *
54
68
  * It shares the realm with the content, which can interfere with all of it: the host takes its
55
69
  * reports as UI hints only.