@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.
@@ -8,7 +8,9 @@ import {
8
8
  annotateMode,
9
9
  checkMarks,
10
10
  clampRect,
11
+ followsSelection,
11
12
  hasMarker,
13
+ inViewport,
12
14
  parseReport,
13
15
  } from "../annotate/validate.ts";
14
16
  import { FIND_LIMITS, FIND_METHODS, type FindReport, type FindResult } from "../find/types.ts";
@@ -89,6 +91,7 @@ const REPORTS: Readonly<Record<string, AnnotationReport["type"]>> = {
89
91
  [ANNOTATE_METHODS.anchored]: "anchored",
90
92
  [ANNOTATE_METHODS.activated]: "activated",
91
93
  [ANNOTATE_METHODS.tracked]: "tracked",
94
+ [ANNOTATE_METHODS.selectionTracked]: "selectionTracked",
92
95
  };
93
96
 
94
97
  /** What the frame says of find in page unasked (P131), by method. */
@@ -234,8 +237,11 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
234
237
  let annotating: Required<AnnotateMode> | null = null;
235
238
  let marks: AnnotationMark[] = [];
236
239
  let activeMark: string | null = null;
237
- // The mark the host follows (P112), and when it took each `tracked` in the last second.
240
+ // The mark the host follows (P112), or whether it follows the selection instead (P138), and
241
+ // when it took each `tracked` or `selectionTracked` in the last second: one followed thing
242
+ // at a time, one rate for both.
238
243
  let tracking: string | null = null;
244
+ let trackingSelection = false;
239
245
  const trackedTimes: number[] = [];
240
246
  // Find in page (P131): the query shown (for the content it was asked of only: a new run or
241
247
  // other content forgets it), whether the host takes the shortcut (kept for every frame the
@@ -353,6 +359,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
353
359
  if (tracking !== null) {
354
360
  toFrame(ANNOTATE_METHODS.track, { id: tracking });
355
361
  }
362
+ // A new frame has no selection: it answers `orphaned` (P138).
363
+ if (trackingSelection) {
364
+ toFrame(ANNOTATE_METHODS.track, { id: null, selection: true });
365
+ }
356
366
  };
357
367
  /**
358
368
  * The frame's viewport as the platform tells it now; undefined where it can't (no
@@ -400,6 +410,16 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
400
410
  case "activated":
401
411
  case "tracked":
402
412
  return { ...report, rect: clampRect(report.rect, viewport) };
413
+ case "selectionTracked":
414
+ // In view only where the page says so and its box, as the host reads the viewport,
415
+ // reaches into it (P138): a box the clamp puts on an edge is never in view.
416
+ return report.state === "orphaned"
417
+ ? report
418
+ : {
419
+ ...report,
420
+ rect: clampRect(report.rect, viewport),
421
+ inView: report.inView && inViewport(report.rect, viewport),
422
+ };
403
423
  case "anchored":
404
424
  return {
405
425
  ...report,
@@ -456,6 +476,23 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
456
476
  emit("annotation", withinFrame(report));
457
477
  return;
458
478
  }
479
+ // The followed selection (P138): only while the host follows it, on the same 60 a second
480
+ // (one followed thing at a time), past the bridge's rate as the followed mark's.
481
+ if (report.type === "selectionTracked") {
482
+ if (!trackingSelection) {
483
+ return;
484
+ }
485
+ const at = Date.now();
486
+ while (trackedTimes.length > 0 && at - (trackedTimes[0] as number) >= 1_000) {
487
+ trackedTimes.shift();
488
+ }
489
+ if (trackedTimes.length >= TRACKED_PER_SECOND) {
490
+ return;
491
+ }
492
+ trackedTimes.push(at);
493
+ emit("annotation", withinFrame(report));
494
+ return;
495
+ }
459
496
  switch (report.type) {
460
497
  case "selected": {
461
498
  const kind = report.anchor.kind;
@@ -626,6 +663,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
626
663
  if (activeMark !== null && !marks.some((mark) => mark.id === activeMark)) {
627
664
  activeMark = null;
628
665
  }
666
+ // A followed selection (P138) isn't a mark: a show leaves it.
629
667
  if (tracking !== null && !marks.some((mark) => mark.id === tracking)) {
630
668
  tracking = null;
631
669
  toFrame(ANNOTATE_METHODS.track, { id: null });
@@ -643,12 +681,22 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
643
681
  activeMark = id;
644
682
  toFrame(ANNOTATE_METHODS.focus, { id });
645
683
  },
646
- track(id) {
684
+ track(target) {
647
685
  needsAnnotate("track");
686
+ // The selection (P138), under `id: null`: an older shell follows nothing.
687
+ if (followsSelection(target)) {
688
+ tracking = null;
689
+ trackingSelection = true;
690
+ trackedTimes.length = 0;
691
+ toFrame(ANNOTATE_METHODS.track, { id: null, selection: true });
692
+ return;
693
+ }
694
+ const id = target;
648
695
  if (id !== null && !marks.some((mark) => mark.id === id)) {
649
696
  throw new TypeError(`annotations.track: no mark ${JSON.stringify(id)} is shown`);
650
697
  }
651
698
  tracking = id;
699
+ trackingSelection = false;
652
700
  trackedTimes.length = 0;
653
701
  toFrame(ANNOTATE_METHODS.track, { id });
654
702
  },
@@ -657,6 +705,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
657
705
  marks = [];
658
706
  activeMark = null;
659
707
  tracking = null;
708
+ trackingSelection = false;
660
709
  toFrame(ANNOTATE_METHODS.clear, {});
661
710
  },
662
711
  clearSelection() {
package/src/host/types.ts CHANGED
@@ -1,4 +1,9 @@
1
- import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
1
+ import type {
2
+ AnnotateMode,
3
+ AnnotationMark,
4
+ AnnotationReport,
5
+ AnnotationTrackTarget,
6
+ } from "../annotate/types.ts";
2
7
  import type { FindOptions, FindResult } from "../find/types.ts";
3
8
  import type { Refused } from "../bridge/refusal.ts";
4
9
  import type {
@@ -309,8 +314,22 @@ export interface AnnotationControls {
309
314
  * Throws for an id no shown mark has; a `show` without it, or `clear`, stops it. From a newer
310
315
  * shell (P132) each also carries the mark's `documentRect` and the document's `scroll`, so
311
316
  * following one mark tells how far the document scrolled, for every mark placed by `documentRect`.
317
+ *
318
+ * `{ selection: true }` (P138) follows the selection the frame last reported as `selected` (the
319
+ * element picked, or the words selected) instead, for a composer that stays beside it: the frame
320
+ * highlights it while it is followed (an element in the outline it had while it was picked) and
321
+ * reports `{ type: "selectionTracked", ... }` with the same boxes as `tracked` and `inView`, or
322
+ * `state: "orphaned"` while it isn't in the page; at most 60 a second together with `tracked`.
323
+ * A `show` leaves it, and `stop` (or a pick ending) too: it ends with `track(null)`, `track(id)`
324
+ * or `clear` (comment posted, composer dismissed, Escape in it), and the highlight with it. A
325
+ * newer shell answers at its next animation frame; an older one sends nothing (it reads the
326
+ * message as `track(null)`), so until a `selectionTracked` comes, place by `selected`'s boxes.
327
+ * Kept for a frame that runs later, which has no selection: it answers `orphaned`. The element
328
+ * just picked stays outlined until then, so call it before a `start` or `stop` sent with it (a
329
+ * stop ends that outline); while followed, `selected` isn't re-sent after a scroll (Tenny's
330
+ * review).
312
331
  */
313
- track(id: string | null): void;
332
+ track(target: AnnotationTrackTarget): void;
314
333
  /** Removes every mark. */
315
334
  clear(): void;
316
335
  /**
package/src/index.ts CHANGED
@@ -344,6 +344,7 @@ export {
344
344
  type AnnotationReport,
345
345
  type AnnotationScroll,
346
346
  type AnnotationSelector,
347
+ type AnnotationTrackTarget,
347
348
  type CssSelector,
348
349
  type TextPositionSelector,
349
350
  type TextQuoteSelector,
@@ -707,6 +707,17 @@ export interface PortholeFrameProps {
707
707
  * stop the following, as the core's `show` does; it starts again once they have it back.
708
708
  */
709
709
  readonly trackedAnnotation?: string | null;
710
+ /**
711
+ * Follow the selection instead (`annotations.track({ selection: true })`, P138): while true, the
712
+ * element the person picked, or the words they selected, as the last `selected` reported them, is
713
+ * highlighted in the frame and `onAnnotation` gets `{ type: "selectionTracked", ... }` as it moves
714
+ * (the boxes `tracked` has, and `inView`; or `state: "orphaned"` while it isn't in the page), for
715
+ * a composer that stays beside it. It takes `trackedAnnotation`'s place while true (one followed
716
+ * thing at a time); false, or leaving it out, ends it and its highlight (the comment posted, the
717
+ * composer dismissed, Escape in it), and `trackedAnnotation`'s mark is followed again. Until a
718
+ * `selectionTracked` comes, place by `selected`'s boxes: an older shell sends none.
719
+ */
720
+ readonly trackedSelection?: boolean;
710
721
  /** The display's imperative calls (`PortholeFrameHandle`, P118): React 19's `ref` prop. */
711
722
  readonly ref?: Ref<PortholeFrameHandle>;
712
723
  /**
@@ -966,9 +977,10 @@ function Mount({
966
977
  }: MountProps): ReactElement {
967
978
  const holder = useRef<HTMLDivElement>(null);
968
979
  const handle = useRef<DisplayHandle | null>(null);
969
- // The mark the display follows now, as the core keeps it (P118), and the prop as last seen.
970
- const following = useRef<string | null>(null);
971
- const asked = useRef<string | null>(null);
980
+ // The mark the display follows now, or the selection (P138), as the core keeps it (P118), and
981
+ // the props as last seen.
982
+ const following = useRef<Followed>(null);
983
+ const asked = useRef<Followed>(null);
972
984
  const [ready, setReady] = useState(false);
973
985
  // The height this display started at: later reports don't make it start again.
974
986
  const [startHeight] = useState(initialHeightPx);
@@ -1199,9 +1211,10 @@ function Mount({
1199
1211
  if (config.capabilities.annotate !== undefined) {
1200
1212
  applyAnnotations(display, first);
1201
1213
  }
1202
- // The followed mark, once the marks are shown; without `annotate`, the core's error.
1214
+ // The followed mark or selection, once the marks are shown; without `annotate`, the core's
1215
+ // error.
1203
1216
  following.current = null;
1204
- const wanted = first.trackedAnnotation ?? null;
1217
+ const wanted = followedOf(first);
1205
1218
  asked.current = wanted;
1206
1219
  if (wanted !== null) {
1207
1220
  attempt(() => {
@@ -1283,51 +1296,56 @@ function Mount({
1283
1296
  annotating === undefined || annotating === null
1284
1297
  ? ""
1285
1298
  : JSON.stringify([annotating.elements ?? true, annotating.text ?? true]);
1286
- useEffect(() => {
1287
- const display = handle.current;
1288
- if (!annotates || display === null) {
1289
- return;
1290
- }
1291
- const wanted = mode === "" ? null : (JSON.parse(mode) as [boolean, boolean]);
1292
- attempt(
1293
- () =>
1294
- wanted === null
1295
- ? display.annotations.stop()
1296
- : display.annotations.start({ elements: wanted[0], text: wanted[1] }),
1297
- latest(),
1298
- );
1299
- }, [annotates, mode]);
1300
1299
  useEffect(() => {
1301
1300
  const display = handle.current;
1302
1301
  if (annotates && display !== null) {
1303
1302
  attempt(() => {
1304
1303
  display.annotations.show(annotations ?? []);
1305
- // A show without the followed mark stops the following (the core's own).
1306
- if (following.current !== null && !shown(annotations, following.current)) {
1304
+ // A show without the followed mark stops the following (the core's own); the selection
1305
+ // stays followed (P138).
1306
+ if (typeof following.current === "string" && !shown(annotations, following.current)) {
1307
1307
  following.current = null;
1308
1308
  }
1309
1309
  }, latest());
1310
1310
  }
1311
1311
  }, [annotates, annotations]);
1312
- // The followed mark follows its prop (after the marks above, so the two can change together).
1313
- const trackedAnnotation = frame.trackedAnnotation ?? null;
1312
+ // The followed mark, or the selection (P138), follows its props (after the marks above, so the
1313
+ // two can change together).
1314
+ const followed = followedOf(frame);
1314
1315
  useEffect(() => {
1315
1316
  const display = handle.current;
1316
- const changed = trackedAnnotation !== asked.current;
1317
- asked.current = trackedAnnotation;
1318
- if (display === null || trackedAnnotation === following.current) {
1317
+ const changed = followed !== asked.current;
1318
+ asked.current = followed;
1319
+ if (display === null || followed === following.current) {
1319
1320
  return;
1320
1321
  }
1321
1322
  // Its mark was taken off (the error, if any, was told when the prop said it): followed again
1322
1323
  // once the marks have it back.
1323
- if (!changed && trackedAnnotation !== null && !shown(annotations, trackedAnnotation)) {
1324
+ if (!changed && typeof followed === "string" && !shown(annotations, followed)) {
1324
1325
  return;
1325
1326
  }
1326
1327
  attempt(() => {
1327
- display.annotations.track(trackedAnnotation);
1328
- following.current = trackedAnnotation;
1328
+ display.annotations.track(followed);
1329
+ following.current = followed;
1329
1330
  }, latest());
1330
- }, [trackedAnnotation, annotations]);
1331
+ }, [followed, annotations]);
1332
+ // The mode follows its prop, after the following above (P138, Tenny's review): a host that
1333
+ // follows the selection and ends picking in one render has the frame follow it first, so the
1334
+ // pick's outline goes straight to the follow's highlight, never through the stop's gap.
1335
+ useEffect(() => {
1336
+ const display = handle.current;
1337
+ if (!annotates || display === null) {
1338
+ return;
1339
+ }
1340
+ const wanted = mode === "" ? null : (JSON.parse(mode) as [boolean, boolean]);
1341
+ attempt(
1342
+ () =>
1343
+ wanted === null
1344
+ ? display.annotations.stop()
1345
+ : display.annotations.start({ elements: wanted[0], text: wanted[1] }),
1346
+ latest(),
1347
+ );
1348
+ }, [annotates, mode]);
1331
1349
  useEffect(() => {
1332
1350
  const display = handle.current;
1333
1351
  const id = focusOf(latest().focusedAnnotation);
@@ -1439,6 +1457,15 @@ function useByValue<T>(value: T): T {
1439
1457
  return useMemo(() => (key === "" ? undefined : JSON.parse(key)) as T, [key]);
1440
1458
  }
1441
1459
 
1460
+ /** What a display follows (P118, P138): a mark's id, the selection (this one object), or nothing. */
1461
+ const SELECTION = Object.freeze({ selection: true } as const);
1462
+ type Followed = string | typeof SELECTION | null;
1463
+
1464
+ /** What the props ask to follow: the selection while `trackedSelection`, else the mark, if any. */
1465
+ function followedOf(frame: PortholeFrameProps): Followed {
1466
+ return frame.trackedSelection === true ? SELECTION : (frame.trackedAnnotation ?? null);
1467
+ }
1468
+
1442
1469
  /** Whether `marks` has a mark `id`. */
1443
1470
  function shown(marks: readonly AnnotationMark[] | undefined, id: string): boolean {
1444
1471
  return (marks ?? []).some((mark) => mark.id === id);
@@ -81,7 +81,7 @@ export const WORD_LATE = String.raw`(at, now) => {
81
81
  * in one).
82
82
  *
83
83
  * The host drives it (`porthole/annotate.start|stop|show|focus|clear|track|clearSelection|focusMark`)
84
- * and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked`):
84
+ * and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked|selectionTracked`):
85
85
  * - picking an element: the element under the pointer (or finger) is outlined with its name; a
86
86
  * click or tap picks it, and the content's own handlers never see that click (unless the content
87
87
  * patched the DOM's built-ins, P105); Escape cancels (while selecting text too, P112);
@@ -107,7 +107,11 @@ export const WORD_LATE = String.raw`(at, now) => {
107
107
  * followed mark's (`tracked`) too, so a host places marks scrolled out of the frame, and keeps
108
108
  * them placed as the document scrolls, from one report and the followed mark's scroll;
109
109
  * - the last line (P133): where a selection or a mark's words end, in the document's coordinates
110
- * too (`lastLineDocumentRect`), so a host places its UI after them.
110
+ * too (`lastLineDocumentRect`), so a host places its UI after them;
111
+ * - the selection followed (P138): what the last `selected` reported (the element picked, or the
112
+ * words selected) is kept, and while the host follows it (`track` with `selection`) it is drawn
113
+ * in the layer and its boxes are reported as a followed mark's are (`selectionTracked`), with
114
+ * whether it is in view, or that it is gone; it takes no pointer, no focus and no key.
111
115
  *
112
116
  * It shares the realm with the content, which can interfere with all of it: the host takes its
113
117
  * reports as UI hints only.
@@ -128,6 +132,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
128
132
  activated: "porthole/annotate.activated",
129
133
  track: "porthole/annotate.track",
130
134
  tracked: "porthole/annotate.tracked",
135
+ selectionTracked: "porthole/annotate.selectionTracked",
131
136
  clearSelection: "porthole/annotate.clearSelection",
132
137
  focusMark: "porthole/annotate.focusMark",
133
138
  };
@@ -146,6 +151,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
146
151
  const elementRect = Element.prototype.getBoundingClientRect;
147
152
  const rangeRect = Range.prototype.getBoundingClientRect;
148
153
  const rangeRects = Range.prototype.getClientRects;
154
+ const cloneRange = Range.prototype.cloneRange;
149
155
  const setStart = Range.prototype.setStart;
150
156
  const setStartBefore = Range.prototype.setStartBefore;
151
157
  const compareBoundaryPoints = Range.prototype.compareBoundaryPoints;
@@ -402,7 +408,10 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
402
408
  // box of at least 44 by 44 px centred on its own (an invisible ::before; 100% is its padding
403
409
  // box, its border 1 px), so a tap a few px off still lands on the shell's layer. A marker is
404
410
  // a real button (P133): what a browser gives one is taken off, a ring says it has the focus.
405
- const STYLE = ".mark{position:absolute;border-radius:2px;background:rgba(250,204,21,.18);box-shadow:inset 0 -2px 0 rgba(234,179,8,.95)}.mark.element{background:rgba(250,204,21,.07);box-shadow:none;outline:2px solid rgba(234,179,8,.9);outline-offset:1px}.mark.active{background:rgba(250,204,21,.26);box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 2px rgba(234,179,8,.45)}.mark.element.active{background:rgba(250,204,21,.12);box-shadow:none;outline-width:3px}.mark.element.quiet{background:rgba(250,204,21,.05);outline:1px solid rgba(234,179,8,.6);outline-offset:2px}.mark.element.quiet.active{background:rgba(250,204,21,.1);outline:2px solid rgba(234,179,8,.9)}.mark.draft{box-sizing:border-box;background:rgba(250,204,21,.08);box-shadow:none;border-bottom:2px dashed rgba(202,138,4,.95)}.mark.draft.active{background:rgba(250,204,21,.16);box-shadow:0 0 0 2px rgba(234,179,8,.45);border-bottom-width:3px}.mark.element.draft{background:rgba(250,204,21,.04);border-bottom:0;outline-style:dashed}.mark.element.draft.active{background:rgba(250,204,21,.08);box-shadow:none;outline-style:dashed}.marker{position:absolute;box-sizing:border-box;height:18px;min-width:18px;display:flex;align-items:center;justify-content:center;gap:3px;margin:0;padding:0 5px;border:1px solid rgba(161,98,7,.6);border-radius:9px 9px 9px 2px;background:#fde68a;color:#422006;box-shadow:0 1px 2px rgba(0,0,0,.3);font:600 11px/16px system-ui,-apple-system,Segoe UI,Roboto,sans-serif;font-style:normal;letter-spacing:0;word-spacing:0;text-transform:none;text-indent:0;text-shadow:none;direction:ltr;writing-mode:horizontal-tb;white-space:nowrap;user-select:none;-webkit-user-select:none;cursor:pointer;pointer-events:auto;appearance:none;-webkit-appearance:none}.marker:focus-visible{outline:2px solid #2563eb;outline-offset:1px}.marker:hover{background:#fcd34d}.marker.active{background:#facc15;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.3)}.marker.compact{padding:0 4px}.marker.draft{border:1px dashed rgb(202,138,4);background:#fffdf5;color:#a16207;box-shadow:0 1px 2px rgba(0,0,0,.2)}.marker.draft:hover{background:#fef9e7}.marker.draft.active{background:#fef3c7;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.2)}.marker.inert,[data-placing]>.marker{pointer-events:none}.touch>.marker::before{content:'';position:absolute;left:50%;top:50%;width:max(100% + 2px,44px);height:max(100% + 2px,44px);transform:translate(-50%,-50%)}.marker svg{display:block;width:11px;height:11px;flex:none}.mark.flash{animation:flash 1.8s ease-out}@keyframes flash{from{box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 6px rgba(250,204,21,.6)}}.hover{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.12)}.tag{position:absolute;max-width:70vw;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:12px/18px ui-monospace,SFMono-Regular,Menlo,monospace;padding:0 6px;border-radius:4px;background:#1e293b;color:#fff}";
411
+ // The selection the host follows (P138) is drawn as what is picked is: an element in the
412
+ // picking outline, a little lighter and without its name; words with a light fill and a line
413
+ // under them, in the same blue, apart from the marks' yellow (no comment is there yet).
414
+ const STYLE = ".mark{position:absolute;border-radius:2px;background:rgba(250,204,21,.18);box-shadow:inset 0 -2px 0 rgba(234,179,8,.95)}.mark.element{background:rgba(250,204,21,.07);box-shadow:none;outline:2px solid rgba(234,179,8,.9);outline-offset:1px}.mark.active{background:rgba(250,204,21,.26);box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 2px rgba(234,179,8,.45)}.mark.element.active{background:rgba(250,204,21,.12);box-shadow:none;outline-width:3px}.mark.element.quiet{background:rgba(250,204,21,.05);outline:1px solid rgba(234,179,8,.6);outline-offset:2px}.mark.element.quiet.active{background:rgba(250,204,21,.1);outline:2px solid rgba(234,179,8,.9)}.mark.draft{box-sizing:border-box;background:rgba(250,204,21,.08);box-shadow:none;border-bottom:2px dashed rgba(202,138,4,.95)}.mark.draft.active{background:rgba(250,204,21,.16);box-shadow:0 0 0 2px rgba(234,179,8,.45);border-bottom-width:3px}.mark.element.draft{background:rgba(250,204,21,.04);border-bottom:0;outline-style:dashed}.mark.element.draft.active{background:rgba(250,204,21,.08);box-shadow:none;outline-style:dashed}.marker{position:absolute;box-sizing:border-box;height:18px;min-width:18px;display:flex;align-items:center;justify-content:center;gap:3px;margin:0;padding:0 5px;border:1px solid rgba(161,98,7,.6);border-radius:9px 9px 9px 2px;background:#fde68a;color:#422006;box-shadow:0 1px 2px rgba(0,0,0,.3);font:600 11px/16px system-ui,-apple-system,Segoe UI,Roboto,sans-serif;font-style:normal;letter-spacing:0;word-spacing:0;text-transform:none;text-indent:0;text-shadow:none;direction:ltr;writing-mode:horizontal-tb;white-space:nowrap;user-select:none;-webkit-user-select:none;cursor:pointer;pointer-events:auto;appearance:none;-webkit-appearance:none}.marker:focus-visible{outline:2px solid #2563eb;outline-offset:1px}.marker:hover{background:#fcd34d}.marker.active{background:#facc15;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.3)}.marker.compact{padding:0 4px}.marker.draft{border:1px dashed rgb(202,138,4);background:#fffdf5;color:#a16207;box-shadow:0 1px 2px rgba(0,0,0,.2)}.marker.draft:hover{background:#fef9e7}.marker.draft.active{background:#fef3c7;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.2)}.marker.inert,[data-placing]>.marker{pointer-events:none}.touch>.marker::before{content:'';position:absolute;left:50%;top:50%;width:max(100% + 2px,44px);height:max(100% + 2px,44px);transform:translate(-50%,-50%)}.marker svg{display:block;width:11px;height:11px;flex:none}.mark.flash{animation:flash 1.8s ease-out}@keyframes flash{from{box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 6px rgba(250,204,21,.6)}}.hover{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.12)}.held{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.06)}.held.text{outline:0;border-radius:2px;background:rgba(37,99,235,.12);box-shadow:inset 0 -2px 0 #2563eb}.tag{position:absolute;max-width:70vw;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:12px/18px ui-monospace,SFMono-Regular,Menlo,monospace;padding:0 6px;border-radius:4px;background:#1e293b;color:#fff}";
406
415
  // Inline and important: the content's own style sheets can't hide, shrink or move it by
407
416
  // accident. Set again at each draw, since its scripts can rewrite it (narrowing only: the
408
417
  // content can still cover the layer, or move it with its ancestors, P104). Clipped, where an
@@ -428,6 +437,31 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
428
437
 
429
438
  let mode = { elements: false, text: false, hold: false };
430
439
  let hover = null;
440
+ // The selection last reported as selected (P138): its anchor, and what it is in the page (the
441
+ // element picked, or a copy of the selection's range, which the page's changes keep up to
442
+ // date and which stays when the page's own selection goes). Followed while the host asks
443
+ // (track with selection), and drawn then. Each new selected replaces it.
444
+ let held = null;
445
+ let followingSelection = false;
446
+ // What the host was last told of it: "attached", "orphaned", or null (nothing yet).
447
+ let heldTold = null;
448
+ const heldGone = (found) => (found.range ? found.range.collapsed || !found.range.startContainer.isConnected : !found.element.isConnected);
449
+ const heldShown = () => followingSelection && held !== null && heldTold !== "orphaned" && !heldGone(held.found);
450
+ // The element just picked (P138, Tenny's review): it keeps its outline after selected, so
451
+ // there is no gap before the host follows it, and the follow's highlight takes over where it
452
+ // does. Without a follow (an older host) it ends as a selection does: the next pick or
453
+ // selection, the host's clearSelection, a mode started or stopped, clear, Escape, or the
454
+ // element leaving the page. Not unselected: a selection made after the pick has already
455
+ // ended it as it was reported, so the one unselected can clear is one from before, which
456
+ // the pick's own click takes away when text is selected too.
457
+ let picked = null;
458
+ const endPick = () => {
459
+ if (picked !== null) {
460
+ picked = null;
461
+ redraw();
462
+ }
463
+ };
464
+ const pickShown = () => picked !== null && !followingSelection && picked.isConnected;
431
465
  let marks = [];
432
466
  // The markers as last drawn, for a click to find: { id, element }. Each mark keeps its
433
467
  // marker's node across draws, so a press that spans a redraw ends on the node it began on.
@@ -818,7 +852,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
818
852
  return boxes;
819
853
  };
820
854
  const draw = () => {
821
- if (marks.length === 0 && hover === null && layer === null) {
855
+ if (marks.length === 0 && hover === null && layer === null && !heldShown() && !pickShown()) {
822
856
  return;
823
857
  }
824
858
  const root = ensureLayer();
@@ -913,6 +947,24 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
913
947
  }
914
948
  }
915
949
  const outlines = [];
950
+ // The followed selection (P138), under the picking outline: no pointer, no focus, no name;
951
+ // before the host follows it, the element just picked, drawn the same way.
952
+ if (picked !== null && !picked.isConnected) {
953
+ picked = null;
954
+ }
955
+ const lit = heldShown() ? held.found : pickShown() ? { element: picked } : null;
956
+ if (lit !== null) {
957
+ const rects = lit.range ? Array.from(rangeRects.call(lit.range)).slice(0, LIMIT.boxes) : [elementRect.call(lit.element)];
958
+ for (const rect of rects) {
959
+ if (rect.width === 0 && rect.height === 0) {
960
+ continue;
961
+ }
962
+ const each = createElement.call(document, "div");
963
+ each.className = lit.range ? "held text" : "held";
964
+ each.style.cssText = "left:" + rect.left + "px;top:" + rect.top + "px;width:" + rect.width + "px;height:" + rect.height + "px";
965
+ outlines.push(each);
966
+ }
967
+ }
916
968
  if (hover !== null && hover.isConnected) {
917
969
  const rect = elementRect.call(hover);
918
970
  const outline = createElement.call(document, "div");
@@ -958,9 +1010,17 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
958
1010
  let trackedBox = null;
959
1011
  let trackedAt = 0;
960
1012
  let trackFrame = 0;
1013
+ // The followed selection's viewport as last told (P138): a frame made smaller can leave it
1014
+ // out of view without moving it.
1015
+ let trackedView = null;
961
1016
  const trackTick = () => {
962
1017
  trackFrame = 0;
963
- if (tracking === null) {
1018
+ if (tracking === null && !followingSelection) {
1019
+ return;
1020
+ }
1021
+ if (followingSelection) {
1022
+ followHeld();
1023
+ trackFrame = nextFrame(trackTick);
964
1024
  return;
965
1025
  }
966
1026
  const mark = marks.find((each) => each.id === tracking);
@@ -979,12 +1039,79 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
979
1039
  }
980
1040
  trackFrame = nextFrame(trackTick);
981
1041
  };
982
- const track = (id) => {
1042
+ // The followed selection (P138), as a followed mark is, and on its clock: where it is at each
1043
+ // animation frame where it moved, or the viewport changed size, with whether any of it is in
1044
+ // the viewport; orphaned once while it isn't in the page (a page that took the element out,
1045
+ // a re-render, the words gone), found again by its anchor at most twice a second meanwhile.
1046
+ // Geometry only: its anchor and words went with selected. Reads boxes, nothing else: no
1047
+ // focus, no selection, no listener.
1048
+ const followHeld = () => {
1049
+ const now = performance.now();
1050
+ if (held !== null && heldGone(held.found) && now - held.tried >= 500) {
1051
+ held.tried = now;
1052
+ let found = null;
1053
+ try {
1054
+ found = find(held.anchor, textIndex());
1055
+ } catch (_) {
1056
+ found = null;
1057
+ }
1058
+ if (found !== null && !heldGone(found)) {
1059
+ held.found = found;
1060
+ }
1061
+ }
1062
+ if (held === null || heldGone(held.found)) {
1063
+ if (heldTold !== "orphaned") {
1064
+ heldTold = "orphaned";
1065
+ trackedBox = null;
1066
+ tell(M.selectionTracked, { state: "orphaned" });
1067
+ redraw();
1068
+ }
1069
+ return;
1070
+ }
1071
+ const rect = box(rectOf(held.found));
1072
+ const root = document.documentElement;
1073
+ const view = { width: root ? root.clientWidth : 0, height: root ? root.clientHeight : 0 };
1074
+ const resized = trackedView === null || trackedView.width !== view.width || trackedView.height !== view.height;
1075
+ if ((heldTold !== "attached" || resized || apart(trackedBox, rect)) && now - trackedAt >= 16) {
1076
+ heldTold = "attached";
1077
+ trackedBox = rect;
1078
+ trackedView = view;
1079
+ trackedAt = now;
1080
+ const scroll = scrollOf();
1081
+ const lastLineDocumentRect = lastLineOf(held.found, scroll);
1082
+ const inView = rect.x < view.width && rect.x + rect.width > 0 && rect.y < view.height && rect.y + rect.height > 0;
1083
+ tell(M.selectionTracked, Object.assign({ state: "attached", rect, documentRect: inDocument(rect, scroll), scroll, inView }, lastLineDocumentRect === null ? {} : { lastLineDocumentRect }));
1084
+ // The highlight goes with it (a layout change moves it without a scroll).
1085
+ redraw();
1086
+ }
1087
+ };
1088
+ // A mark, the selection (P138), or nothing: one at a time, each replacing the last.
1089
+ const track = (id, selection) => {
1090
+ const was = heldShown() || pickShown();
983
1091
  tracking = typeof id === "string" ? id : null;
1092
+ followingSelection = tracking === null && selection === true;
1093
+ // The follow's highlight takes the pick's outline over, in this draw (Tenny's review).
1094
+ if (followingSelection) {
1095
+ picked = null;
1096
+ }
984
1097
  trackedBox = null;
985
- if (tracking !== null && trackFrame === 0) {
1098
+ trackedView = null;
1099
+ heldTold = null;
1100
+ if ((tracking !== null || followingSelection) && trackFrame === 0) {
986
1101
  trackFrame = nextFrame(trackTick);
987
1102
  }
1103
+ if (heldShown() || pickShown() || was) {
1104
+ draw();
1105
+ }
1106
+ };
1107
+ // A new selected (P138): what is followed, if the selection is, from the next frame on.
1108
+ const holdSelected = (anchor, found) => {
1109
+ held = { anchor, found, tried: 0 };
1110
+ if (followingSelection) {
1111
+ trackedBox = null;
1112
+ heldTold = null;
1113
+ redraw();
1114
+ }
988
1115
  };
989
1116
 
990
1117
  // Where each found mark starts in the document, in order (P112): its place in a list the host
@@ -1187,9 +1314,11 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1187
1314
  sent += 1;
1188
1315
  }
1189
1316
  }
1317
+ // Not while the host follows the selection (P138, Tenny's review): its reports carry where
1318
+ // it is; a scroll after the following ends is re-sent as before.
1190
1319
  if (selectionScrolled) {
1191
1320
  selectionScrolled = false;
1192
- if (reportSelection(true)) {
1321
+ if (!followingSelection && reportSelection(true)) {
1193
1322
  sent += 1;
1194
1323
  }
1195
1324
  }
@@ -1459,6 +1588,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1459
1588
  const stop = () => {
1460
1589
  mode = { elements: false, text: false };
1461
1590
  hover = null;
1591
+ picked = null;
1462
1592
  reported = null;
1463
1593
  reportedBox = null;
1464
1594
  setCursor(false);
@@ -1526,6 +1656,9 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1526
1656
  return;
1527
1657
  }
1528
1658
  swallowUntil = performance.now() + 2000;
1659
+ holdSelected(anchor, { element });
1660
+ picked = followingSelection ? null : element;
1661
+ redraw();
1529
1662
  tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
1530
1663
  }, HOLD_MS),
1531
1664
  };
@@ -1573,6 +1706,9 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1573
1706
  mode = { elements: false, text: mode.text };
1574
1707
  hover = null;
1575
1708
  setCursor(false);
1709
+ holdSelected(anchor, { element });
1710
+ // Its outline stays (P138), now without its name, until the host follows it or it ends.
1711
+ picked = followingSelection ? null : element;
1576
1712
  draw();
1577
1713
  tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
1578
1714
  }, true);
@@ -1580,6 +1716,8 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1580
1716
  if (event.key !== "Escape") {
1581
1717
  return;
1582
1718
  }
1719
+ // The person wants out: a pick's outline goes (P138). The key is untouched by it.
1720
+ endPick();
1583
1721
  if (mode.elements) {
1584
1722
  event.preventDefault();
1585
1723
  event.stopImmediatePropagation();
@@ -1633,6 +1771,8 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1633
1771
  }
1634
1772
  reported = key;
1635
1773
  reportedBox = rect;
1774
+ holdSelected(anchor, { range: cloneRange.call(range) });
1775
+ endPick();
1636
1776
  tell(M.selected, Object.assign({ anchor, rect }, placeOf({ range })));
1637
1777
  return true;
1638
1778
  };
@@ -1643,6 +1783,10 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1643
1783
  }
1644
1784
  });
1645
1785
  window.addEventListener("scroll", () => {
1786
+ // Not while the host follows the selection (P138, Tenny's review).
1787
+ if (followingSelection) {
1788
+ return;
1789
+ }
1646
1790
  if (reported !== null) {
1647
1791
  selectionScrolled = true;
1648
1792
  settle();
@@ -1662,6 +1806,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1662
1806
  case M.start:
1663
1807
  mode = { elements: params.elements === true, text: params.text === true, hold: params.elements === "hold" };
1664
1808
  hover = null;
1809
+ picked = null;
1665
1810
  reported = null;
1666
1811
  reportedBox = null;
1667
1812
  setCursor(mode.elements);
@@ -1693,18 +1838,19 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1693
1838
  focus(String(params.id));
1694
1839
  break;
1695
1840
  case M.track:
1696
- track(params.id);
1841
+ track(params.id, params.selection === true);
1697
1842
  break;
1698
1843
  case M.clearSelection: {
1699
1844
  // The host used the person's selection (P115): it goes, and with it what the shell
1700
1845
  // held of it (a report waiting to settle, the one last told, a scroll's follow-up), so
1701
1846
  // nothing is told back: the host knows, and the selectionchange this makes finds
1702
- // nothing to report. Marks, a pick and the mode stay as they are. With nothing
1703
- // selected, nothing changes.
1847
+ // nothing to report. Marks, a pick and the mode stay as they are, but a pick's outline
1848
+ // goes (P138). With nothing selected, nothing changes.
1704
1849
  cancelLater(selectionTimer);
1705
1850
  selectionTimer = 0;
1706
1851
  reported = null;
1707
1852
  reportedBox = null;
1853
+ endPick();
1708
1854
  selectionScrolled = false;
1709
1855
  const selection = selectionOf.call(document);
1710
1856
  if (selection !== null) {
@@ -1717,6 +1863,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1717
1863
  break;
1718
1864
  case M.clear:
1719
1865
  track(null);
1866
+ picked = null;
1720
1867
  pendingFocus = null;
1721
1868
  pendingMarker = null;
1722
1869
  marks = [];