@botiverse/porthole 0.14.14 → 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() {
@@ -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
  /**
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";
@@ -338,6 +338,17 @@ export interface PortholeFrameProps {
338
338
  * stop the following, as the core's `show` does; it starts again once they have it back.
339
339
  */
340
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;
341
352
  /** The display's imperative calls (`PortholeFrameHandle`, P118): React 19's `ref` prop. */
342
353
  readonly ref?: Ref<PortholeFrameHandle>;
343
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);
@@ -33,7 +33,7 @@ export declare const WORD_LATE: string;
33
33
  * in one).
34
34
  *
35
35
  * The host drives it (`porthole/annotate.start|stop|show|focus|clear|track|clearSelection|focusMark`)
36
- * and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked`):
36
+ * and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked|selectionTracked`):
37
37
  * - picking an element: the element under the pointer (or finger) is outlined with its name; a
38
38
  * click or tap picks it, and the content's own handlers never see that click (unless the content
39
39
  * patched the DOM's built-ins, P105); Escape cancels (while selecting text too, P112);
@@ -59,7 +59,11 @@ export declare const WORD_LATE: string;
59
59
  * followed mark's (`tracked`) too, so a host places marks scrolled out of the frame, and keeps
60
60
  * them placed as the document scrolls, from one report and the followed mark's scroll;
61
61
  * - the last line (P133): where a selection or a mark's words end, in the document's coordinates
62
- * 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.
63
67
  *
64
68
  * It shares the realm with the content, which can interfere with all of it: the host takes its
65
69
  * reports as UI hints only.
@@ -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,11 @@ 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, 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.
107
111
  *
108
112
  * It shares the realm with the content, which can interfere with all of it: the host takes its
109
113
  * reports as UI hints only.
@@ -124,6 +128,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
124
128
  activated: "porthole/annotate.activated",
125
129
  track: "porthole/annotate.track",
126
130
  tracked: "porthole/annotate.tracked",
131
+ selectionTracked: "porthole/annotate.selectionTracked",
127
132
  clearSelection: "porthole/annotate.clearSelection",
128
133
  focusMark: "porthole/annotate.focusMark",
129
134
  };
@@ -142,6 +147,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
142
147
  const elementRect = Element.prototype.getBoundingClientRect;
143
148
  const rangeRect = Range.prototype.getBoundingClientRect;
144
149
  const rangeRects = Range.prototype.getClientRects;
150
+ const cloneRange = Range.prototype.cloneRange;
145
151
  const setStart = Range.prototype.setStart;
146
152
  const setStartBefore = Range.prototype.setStartBefore;
147
153
  const compareBoundaryPoints = Range.prototype.compareBoundaryPoints;
@@ -398,7 +404,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
398
404
  // box of at least 44 by 44 px centred on its own (an invisible ::before; 100% is its padding
399
405
  // box, its border 1 px), so a tap a few px off still lands on the shell's layer. A marker is
400
406
  // 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}";
407
+ // The selection the host follows (P138) is drawn as what is picked is: an element in the
408
+ // picking outline, a little lighter and without its name; words with a light fill and a line
409
+ // under them, in the same blue, apart from the marks' yellow (no comment is there yet).
410
+ 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
411
  // Inline and important: the content's own style sheets can't hide, shrink or move it by
403
412
  // accident. Set again at each draw, since its scripts can rewrite it (narrowing only: the
404
413
  // content can still cover the layer, or move it with its ancestors, P104). Clipped, where an
@@ -424,6 +433,31 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
424
433
 
425
434
  let mode = { elements: false, text: false, hold: false };
426
435
  let hover = null;
436
+ // The selection last reported as selected (P138): its anchor, and what it is in the page (the
437
+ // element picked, or a copy of the selection's range, which the page's changes keep up to
438
+ // 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.
440
+ let held = null;
441
+ let followingSelection = false;
442
+ // What the host was last told of it: "attached", "orphaned", or null (nothing yet).
443
+ let heldTold = null;
444
+ const heldGone = (found) => (found.range ? found.range.collapsed || !found.range.startContainer.isConnected : !found.element.isConnected);
445
+ 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.
453
+ let picked = null;
454
+ const endPick = () => {
455
+ if (picked !== null) {
456
+ picked = null;
457
+ redraw();
458
+ }
459
+ };
460
+ const pickShown = () => picked !== null && !followingSelection && picked.isConnected;
427
461
  let marks = [];
428
462
  // The markers as last drawn, for a click to find: { id, element }. Each mark keeps its
429
463
  // marker's node across draws, so a press that spans a redraw ends on the node it began on.
@@ -814,7 +848,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
814
848
  return boxes;
815
849
  };
816
850
  const draw = () => {
817
- if (marks.length === 0 && hover === null && layer === null) {
851
+ if (marks.length === 0 && hover === null && layer === null && !heldShown() && !pickShown()) {
818
852
  return;
819
853
  }
820
854
  const root = ensureLayer();
@@ -909,6 +943,24 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
909
943
  }
910
944
  }
911
945
  const outlines = [];
946
+ // The followed selection (P138), under the picking outline: no pointer, no focus, no name;
947
+ // before the host follows it, the element just picked, drawn the same way.
948
+ if (picked !== null && !picked.isConnected) {
949
+ picked = null;
950
+ }
951
+ const lit = heldShown() ? held.found : pickShown() ? { element: picked } : null;
952
+ if (lit !== null) {
953
+ const rects = lit.range ? Array.from(rangeRects.call(lit.range)).slice(0, LIMIT.boxes) : [elementRect.call(lit.element)];
954
+ for (const rect of rects) {
955
+ if (rect.width === 0 && rect.height === 0) {
956
+ continue;
957
+ }
958
+ const each = createElement.call(document, "div");
959
+ each.className = lit.range ? "held text" : "held";
960
+ each.style.cssText = "left:" + rect.left + "px;top:" + rect.top + "px;width:" + rect.width + "px;height:" + rect.height + "px";
961
+ outlines.push(each);
962
+ }
963
+ }
912
964
  if (hover !== null && hover.isConnected) {
913
965
  const rect = elementRect.call(hover);
914
966
  const outline = createElement.call(document, "div");
@@ -954,9 +1006,17 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
954
1006
  let trackedBox = null;
955
1007
  let trackedAt = 0;
956
1008
  let trackFrame = 0;
1009
+ // The followed selection's viewport as last told (P138): a frame made smaller can leave it
1010
+ // out of view without moving it.
1011
+ let trackedView = null;
957
1012
  const trackTick = () => {
958
1013
  trackFrame = 0;
959
- if (tracking === null) {
1014
+ if (tracking === null && !followingSelection) {
1015
+ return;
1016
+ }
1017
+ if (followingSelection) {
1018
+ followHeld();
1019
+ trackFrame = nextFrame(trackTick);
960
1020
  return;
961
1021
  }
962
1022
  const mark = marks.find((each) => each.id === tracking);
@@ -975,12 +1035,79 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
975
1035
  }
976
1036
  trackFrame = nextFrame(trackTick);
977
1037
  };
978
- const track = (id) => {
1038
+ // The followed selection (P138), as a followed mark is, and on its clock: where it is at each
1039
+ // animation frame where it moved, or the viewport changed size, with whether any of it is in
1040
+ // the viewport; orphaned once while it isn't in the page (a page that took the element out,
1041
+ // a re-render, the words gone), found again by its anchor at most twice a second meanwhile.
1042
+ // Geometry only: its anchor and words went with selected. Reads boxes, nothing else: no
1043
+ // focus, no selection, no listener.
1044
+ const followHeld = () => {
1045
+ const now = performance.now();
1046
+ if (held !== null && heldGone(held.found) && now - held.tried >= 500) {
1047
+ held.tried = now;
1048
+ let found = null;
1049
+ try {
1050
+ found = find(held.anchor, textIndex());
1051
+ } catch (_) {
1052
+ found = null;
1053
+ }
1054
+ if (found !== null && !heldGone(found)) {
1055
+ held.found = found;
1056
+ }
1057
+ }
1058
+ if (held === null || heldGone(held.found)) {
1059
+ if (heldTold !== "orphaned") {
1060
+ heldTold = "orphaned";
1061
+ trackedBox = null;
1062
+ tell(M.selectionTracked, { state: "orphaned" });
1063
+ redraw();
1064
+ }
1065
+ return;
1066
+ }
1067
+ const rect = box(rectOf(held.found));
1068
+ const root = document.documentElement;
1069
+ const view = { width: root ? root.clientWidth : 0, height: root ? root.clientHeight : 0 };
1070
+ const resized = trackedView === null || trackedView.width !== view.width || trackedView.height !== view.height;
1071
+ if ((heldTold !== "attached" || resized || apart(trackedBox, rect)) && now - trackedAt >= 16) {
1072
+ heldTold = "attached";
1073
+ trackedBox = rect;
1074
+ trackedView = view;
1075
+ trackedAt = now;
1076
+ const scroll = scrollOf();
1077
+ const lastLineDocumentRect = lastLineOf(held.found, scroll);
1078
+ const inView = rect.x < view.width && rect.x + rect.width > 0 && rect.y < view.height && rect.y + rect.height > 0;
1079
+ tell(M.selectionTracked, Object.assign({ state: "attached", rect, documentRect: inDocument(rect, scroll), scroll, inView }, lastLineDocumentRect === null ? {} : { lastLineDocumentRect }));
1080
+ // The highlight goes with it (a layout change moves it without a scroll).
1081
+ redraw();
1082
+ }
1083
+ };
1084
+ // A mark, the selection (P138), or nothing: one at a time, each replacing the last.
1085
+ const track = (id, selection) => {
1086
+ const was = heldShown() || pickShown();
979
1087
  tracking = typeof id === "string" ? id : null;
1088
+ followingSelection = tracking === null && selection === true;
1089
+ // The follow's highlight takes the pick's outline over, in this draw (Tenny's review).
1090
+ if (followingSelection) {
1091
+ picked = null;
1092
+ }
980
1093
  trackedBox = null;
981
- if (tracking !== null && trackFrame === 0) {
1094
+ trackedView = null;
1095
+ heldTold = null;
1096
+ if ((tracking !== null || followingSelection) && trackFrame === 0) {
982
1097
  trackFrame = nextFrame(trackTick);
983
1098
  }
1099
+ if (heldShown() || pickShown() || was) {
1100
+ draw();
1101
+ }
1102
+ };
1103
+ // A new selected (P138): what is followed, if the selection is, from the next frame on.
1104
+ const holdSelected = (anchor, found) => {
1105
+ held = { anchor, found, tried: 0 };
1106
+ if (followingSelection) {
1107
+ trackedBox = null;
1108
+ heldTold = null;
1109
+ redraw();
1110
+ }
984
1111
  };
985
1112
 
986
1113
  // Where each found mark starts in the document, in order (P112): its place in a list the host
@@ -1183,9 +1310,11 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1183
1310
  sent += 1;
1184
1311
  }
1185
1312
  }
1313
+ // Not while the host follows the selection (P138, Tenny's review): its reports carry where
1314
+ // it is; a scroll after the following ends is re-sent as before.
1186
1315
  if (selectionScrolled) {
1187
1316
  selectionScrolled = false;
1188
- if (reportSelection(true)) {
1317
+ if (!followingSelection && reportSelection(true)) {
1189
1318
  sent += 1;
1190
1319
  }
1191
1320
  }
@@ -1455,6 +1584,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1455
1584
  const stop = () => {
1456
1585
  mode = { elements: false, text: false };
1457
1586
  hover = null;
1587
+ picked = null;
1458
1588
  reported = null;
1459
1589
  reportedBox = null;
1460
1590
  setCursor(false);
@@ -1522,6 +1652,9 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1522
1652
  return;
1523
1653
  }
1524
1654
  swallowUntil = performance.now() + 2000;
1655
+ holdSelected(anchor, { element });
1656
+ picked = followingSelection ? null : element;
1657
+ redraw();
1525
1658
  tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
1526
1659
  }, HOLD_MS),
1527
1660
  };
@@ -1569,6 +1702,9 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1569
1702
  mode = { elements: false, text: mode.text };
1570
1703
  hover = null;
1571
1704
  setCursor(false);
1705
+ 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;
1572
1708
  draw();
1573
1709
  tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
1574
1710
  }, true);
@@ -1576,6 +1712,8 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1576
1712
  if (event.key !== "Escape") {
1577
1713
  return;
1578
1714
  }
1715
+ // The person wants out: a pick's outline goes (P138). The key is untouched by it.
1716
+ endPick();
1579
1717
  if (mode.elements) {
1580
1718
  event.preventDefault();
1581
1719
  event.stopImmediatePropagation();
@@ -1629,6 +1767,8 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1629
1767
  }
1630
1768
  reported = key;
1631
1769
  reportedBox = rect;
1770
+ holdSelected(anchor, { range: cloneRange.call(range) });
1771
+ endPick();
1632
1772
  tell(M.selected, Object.assign({ anchor, rect }, placeOf({ range })));
1633
1773
  return true;
1634
1774
  };
@@ -1639,6 +1779,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1639
1779
  }
1640
1780
  });
1641
1781
  window.addEventListener("scroll", () => {
1782
+ // Not while the host follows the selection (P138, Tenny's review).
1783
+ if (followingSelection) {
1784
+ return;
1785
+ }
1642
1786
  if (reported !== null) {
1643
1787
  selectionScrolled = true;
1644
1788
  settle();
@@ -1658,6 +1802,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1658
1802
  case M.start:
1659
1803
  mode = { elements: params.elements === true, text: params.text === true, hold: params.elements === "hold" };
1660
1804
  hover = null;
1805
+ picked = null;
1661
1806
  reported = null;
1662
1807
  reportedBox = null;
1663
1808
  setCursor(mode.elements);
@@ -1689,18 +1834,19 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1689
1834
  focus(String(params.id));
1690
1835
  break;
1691
1836
  case M.track:
1692
- track(params.id);
1837
+ track(params.id, params.selection === true);
1693
1838
  break;
1694
1839
  case M.clearSelection: {
1695
1840
  // The host used the person's selection (P115): it goes, and with it what the shell
1696
1841
  // held of it (a report waiting to settle, the one last told, a scroll's follow-up), so
1697
1842
  // 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.
1843
+ // nothing to report. Marks, a pick and the mode stay as they are, but a pick's outline
1844
+ // goes (P138). With nothing selected, nothing changes.
1700
1845
  cancelLater(selectionTimer);
1701
1846
  selectionTimer = 0;
1702
1847
  reported = null;
1703
1848
  reportedBox = null;
1849
+ endPick();
1704
1850
  selectionScrolled = false;
1705
1851
  const selection = selectionOf.call(document);
1706
1852
  if (selection !== null) {
@@ -1713,6 +1859,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1713
1859
  break;
1714
1860
  case M.clear:
1715
1861
  track(null);
1862
+ picked = null;
1716
1863
  pendingFocus = null;
1717
1864
  pendingMarker = null;
1718
1865
  marks = [];