@botiverse/porthole 0.14.14 → 0.14.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -84,8 +84,24 @@ export interface AnnotateMode {
84
84
  readonly elements?: boolean | "hold";
85
85
  /** Text, by selecting it: each settled selection is reported, and its clearing. */
86
86
  readonly text?: boolean;
87
+ /**
88
+ * That you follow what is selected (P140): `annotations.track({ selection: true })` once
89
+ * `selected` comes (React sets it while `trackedSelection` is given). Only then does the frame
90
+ * keep it for you to follow, the element just picked outlined until the follow takes over. Without
91
+ * it the frame keeps nothing and a pick's outline goes with the pick, as before 0.14.15; a follow
92
+ * asked before the pick still follows each selection reported while it lasts.
93
+ */
94
+ readonly keepSelection?: boolean;
87
95
  }
88
96
 
97
+ /**
98
+ * What `annotations.track` follows (P112, P138): a shown mark, by its id; the selection the frame
99
+ * last reported as `selected` (the element picked, or the words selected), highlighted in the
100
+ * frame while followed, and kept for a follow asked after `selected` only under `start`'s
101
+ * `keepSelection` (P140); or nothing (`null`). One at a time: each replaces the last.
102
+ */
103
+ export type AnnotationTrackTarget = string | { readonly selection: true } | null;
104
+
89
105
  /**
90
106
  * An anchor the host marks in the frame, under its own id. Everything here is sent into the
91
107
  * frame, so the content can read it: give ids that say nothing (never a person's name or the
@@ -209,6 +225,30 @@ export type AnnotationReport =
209
225
  readonly lastLineDocumentRect?: AnnotationRect;
210
226
  readonly scroll?: AnnotationScroll;
211
227
  }
228
+ /**
229
+ * Where the selection the host follows is (`annotations.track({ selection: true })`, P138): the
230
+ * element picked or the words selected, as the last `selected` reported them, at an animation
231
+ * frame where it moved or the frame's viewport changed size; at most 60 a second, together with
232
+ * `tracked` (one followed thing at a time). The same boxes as `tracked`'s: `rect` clamped to the
233
+ * frame, `documentRect` and `lastLineDocumentRect` in the document and unclamped, the `scroll`
234
+ * they were read at, always there. `inView`: whether any of it is inside the frame's viewport
235
+ * (false where the shell says so, or where `rect` lies wholly outside the viewport as the host
236
+ * reads it); hide UI attached to it while false. `orphaned`: it isn't in the page now (taken out,
237
+ * its words gone; or the frame has no selection, a new frame after a reload); `attached` again if
238
+ * it is found again by its anchor. The first report comes at the frame's next animation frame
239
+ * after the host asks, which is how a host tells a shell that follows a selection (an older one
240
+ * sends none). Geometry only, as `tracked`: no anchor, no words. The content's word.
241
+ */
242
+ | {
243
+ readonly type: "selectionTracked";
244
+ readonly state: "attached";
245
+ readonly rect: AnnotationRect;
246
+ readonly documentRect: AnnotationRect;
247
+ readonly lastLineDocumentRect?: AnnotationRect;
248
+ readonly scroll: AnnotationScroll;
249
+ readonly inView: boolean;
250
+ }
251
+ | { readonly type: "selectionTracked"; readonly state: "orphaned" }
212
252
  /**
213
253
  * The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
214
254
  * (P107), or pressed Enter or Space on it (P133); `rect` is the marker's box, to open the host's
@@ -237,10 +277,16 @@ export const ANNOTATE_METHODS = {
237
277
  anchored: "porthole/annotate.anchored",
238
278
  /** Frame → host: a mark's marker was clicked, or pressed from the keyboard (P104, P133). */
239
279
  activated: "porthole/annotate.activated",
240
- /** Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112). */
280
+ /**
281
+ * Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112), or the
282
+ * selection last reported, highlighted while followed (`{ id: null, selection: true }`, P138: an
283
+ * older shell reads it as none).
284
+ */
241
285
  track: "porthole/annotate.track",
242
286
  /** Frame → host: the followed mark's box, as it moves (P112). */
243
287
  tracked: "porthole/annotate.tracked",
288
+ /** Frame → host: where the followed selection is, as it moves (P138). */
289
+ selectionTracked: "porthole/annotate.selectionTracked",
244
290
  /** Host → frame: take the page's text selection away, telling nothing back (P115). */
245
291
  clearSelection: "porthole/annotate.clearSelection",
246
292
  /**
@@ -8,6 +8,7 @@ import {
8
8
  type AnnotationReport,
9
9
  type AnnotationScroll,
10
10
  type AnnotationSelector,
11
+ type AnnotationTrackTarget,
11
12
  } from "./types.ts";
12
13
  import { withoutUnseen } from "../bridge/unseen.ts";
13
14
 
@@ -145,6 +146,25 @@ export function clampRect(
145
146
  return { x: left, y: top, width: right - left, height: bottom - top };
146
147
  }
147
148
 
149
+ /**
150
+ * Whether a box the frame reported overlaps the frame's viewport (P138), before it is clamped: a
151
+ * box of no width or height counts where it lies strictly inside. Where the viewport isn't known,
152
+ * nothing is in it, as `clampRect` puts every box at the corner then.
153
+ */
154
+ export function inViewport(
155
+ rect: AnnotationRect,
156
+ viewport: { readonly width: number; readonly height: number } | null | undefined,
157
+ ): boolean {
158
+ if (viewport === null || typeof viewport !== "object") {
159
+ return false;
160
+ }
161
+ const { width, height } = viewport;
162
+ if (!Number.isFinite(width) || !Number.isFinite(height)) {
163
+ return false;
164
+ }
165
+ return rect.x < width && rect.x + rect.width > 0 && rect.y < height && rect.y + rect.height > 0;
166
+ }
167
+
148
168
  const markId = (value: unknown): value is string => text(value, LIMITS.id, 1);
149
169
 
150
170
  function results(value: unknown): AnchorResult[] | null {
@@ -280,15 +300,58 @@ export function parseReport(value: unknown): AnnotationReport | null {
280
300
  ...(scroll === undefined ? {} : { scroll }),
281
301
  };
282
302
  }
303
+ case "selectionTracked": {
304
+ // The followed selection (P138): gone, or where it is. New with its shell, so every box but
305
+ // the last line, and the scroll, are there; nothing about the page's words is.
306
+ if (value.state === "orphaned") {
307
+ return { type: "selectionTracked", state: "orphaned" };
308
+ }
309
+ if (value.state !== "attached" || typeof value.inView !== "boolean") {
310
+ return null;
311
+ }
312
+ const rect = parseRect(value.rect);
313
+ const documentRect = parseRect(value.documentRect);
314
+ const scroll = parseScroll(value.scroll);
315
+ const lastLineDocumentRect =
316
+ value.lastLineDocumentRect === undefined
317
+ ? undefined
318
+ : parseRect(value.lastLineDocumentRect);
319
+ if (
320
+ rect === null ||
321
+ documentRect === null ||
322
+ scroll === null ||
323
+ lastLineDocumentRect === null
324
+ ) {
325
+ return null;
326
+ }
327
+ return {
328
+ type: "selectionTracked",
329
+ state: "attached",
330
+ rect,
331
+ documentRect,
332
+ ...(lastLineDocumentRect === undefined ? {} : { lastLineDocumentRect }),
333
+ scroll,
334
+ inView: value.inView,
335
+ };
336
+ }
283
337
  default:
284
338
  return null;
285
339
  }
286
340
  }
287
341
 
288
- /** What the host may start with: elements, text, or both (default both). */
289
- export function annotateMode(mode: AnnotateMode | undefined): Required<AnnotateMode> {
342
+ /** A mode as the frame gets it: `keepSelection` only where it is true (P140). */
343
+ export type StartedMode = Required<Omit<AnnotateMode, "keepSelection">> & {
344
+ readonly keepSelection?: true;
345
+ };
346
+
347
+ /**
348
+ * What the host may start with: elements, text, or both (default both); and whether it follows
349
+ * what is selected (`keepSelection`, P140).
350
+ */
351
+ export function annotateMode(mode: AnnotateMode | undefined): StartedMode {
290
352
  const elements = mode?.elements ?? true;
291
353
  const words = mode?.text ?? true;
354
+ const keep = mode?.keepSelection ?? false;
292
355
  if (
293
356
  (typeof elements !== "boolean" && elements !== "hold") ||
294
357
  typeof words !== "boolean" ||
@@ -296,7 +359,10 @@ export function annotateMode(mode: AnnotateMode | undefined): Required<AnnotateM
296
359
  ) {
297
360
  throw new TypeError("annotations.start: elements, text, or both");
298
361
  }
299
- return { elements, text: words };
362
+ if (typeof keep !== "boolean") {
363
+ throw new TypeError("annotations.start: keepSelection is true or false");
364
+ }
365
+ return { elements, text: words, ...(keep ? { keepSelection: true } : {}) };
300
366
  }
301
367
 
302
368
  /**
@@ -345,3 +411,16 @@ export function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[] {
345
411
  };
346
412
  });
347
413
  }
414
+
415
+ /**
416
+ * Whether what `annotations.track` is given names the selection (P138): an object whose own
417
+ * `selection` is `true`, and nothing else does (a mark's id is a string).
418
+ */
419
+ export const followsSelection = (
420
+ target: AnnotationTrackTarget | undefined,
421
+ ): target is { readonly selection: true } =>
422
+ typeof target === "object" &&
423
+ target !== null &&
424
+ Object.hasOwn(target, "selection") &&
425
+ // A caller's word, untyped as JavaScript passes it: `true` and nothing else.
426
+ (target as { readonly selection?: unknown }).selection === true;
@@ -1,15 +1,13 @@
1
- import {
2
- ANNOTATE_METHODS,
3
- type AnnotateMode,
4
- type AnnotationMark,
5
- type AnnotationReport,
6
- } from "../annotate/types.ts";
1
+ import { ANNOTATE_METHODS, type AnnotationMark, type AnnotationReport } from "../annotate/types.ts";
7
2
  import {
8
3
  annotateMode,
9
4
  checkMarks,
10
5
  clampRect,
6
+ followsSelection,
11
7
  hasMarker,
8
+ inViewport,
12
9
  parseReport,
10
+ type StartedMode,
13
11
  } from "../annotate/validate.ts";
14
12
  import { FIND_LIMITS, FIND_METHODS, type FindReport, type FindResult } from "../find/types.ts";
15
13
  import { blankQuery, checkFindQuery, parseFindReport, parseFindResult } from "../find/validate.ts";
@@ -89,6 +87,7 @@ const REPORTS: Readonly<Record<string, AnnotationReport["type"]>> = {
89
87
  [ANNOTATE_METHODS.anchored]: "anchored",
90
88
  [ANNOTATE_METHODS.activated]: "activated",
91
89
  [ANNOTATE_METHODS.tracked]: "tracked",
90
+ [ANNOTATE_METHODS.selectionTracked]: "selectionTracked",
92
91
  };
93
92
 
94
93
  /** What the frame says of find in page unasked (P131), by method. */
@@ -231,11 +230,14 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
231
230
  const replay = new Map<string, unknown[]>();
232
231
  // Annotations: the host's state, given to each frame once it finished its handshake.
233
232
  const annotates = config.capabilities.annotate !== undefined;
234
- let annotating: Required<AnnotateMode> | null = null;
233
+ let annotating: StartedMode | null = null;
235
234
  let marks: AnnotationMark[] = [];
236
235
  let activeMark: string | null = null;
237
- // The mark the host follows (P112), and when it took each `tracked` in the last second.
236
+ // The mark the host follows (P112), or whether it follows the selection instead (P138), and
237
+ // when it took each `tracked` or `selectionTracked` in the last second: one followed thing
238
+ // at a time, one rate for both.
238
239
  let tracking: string | null = null;
240
+ let trackingSelection = false;
239
241
  const trackedTimes: number[] = [];
240
242
  // Find in page (P131): the query shown (for the content it was asked of only: a new run or
241
243
  // other content forgets it), whether the host takes the shortcut (kept for every frame the
@@ -353,6 +355,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
353
355
  if (tracking !== null) {
354
356
  toFrame(ANNOTATE_METHODS.track, { id: tracking });
355
357
  }
358
+ // A new frame has no selection: it answers `orphaned` (P138).
359
+ if (trackingSelection) {
360
+ toFrame(ANNOTATE_METHODS.track, { id: null, selection: true });
361
+ }
356
362
  };
357
363
  /**
358
364
  * The frame's viewport as the platform tells it now; undefined where it can't (no
@@ -400,6 +406,16 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
400
406
  case "activated":
401
407
  case "tracked":
402
408
  return { ...report, rect: clampRect(report.rect, viewport) };
409
+ case "selectionTracked":
410
+ // In view only where the page says so and its box, as the host reads the viewport,
411
+ // reaches into it (P138): a box the clamp puts on an edge is never in view.
412
+ return report.state === "orphaned"
413
+ ? report
414
+ : {
415
+ ...report,
416
+ rect: clampRect(report.rect, viewport),
417
+ inView: report.inView && inViewport(report.rect, viewport),
418
+ };
403
419
  case "anchored":
404
420
  return {
405
421
  ...report,
@@ -432,6 +448,12 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
432
448
  if (type === undefined) {
433
449
  return;
434
450
  }
451
+ // The followed selection (P138) only while the host follows it, and dropped unread
452
+ // otherwise (P140): a host that doesn't follow it takes it as 0.14.14 took a method it
453
+ // didn't know, so a malformed one is no refusal either.
454
+ if (type === "selectionTracked" && !trackingSelection) {
455
+ return;
456
+ }
435
457
  let report = parseReport({ ...(isRecord(raw.params) ? raw.params : {}), type });
436
458
  if (report === null) {
437
459
  void through.call("annotate", null);
@@ -456,6 +478,20 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
456
478
  emit("annotation", withinFrame(report));
457
479
  return;
458
480
  }
481
+ // The followed selection (P138): only while the host follows it (above), on the same 60 a
482
+ // second (one followed thing at a time), past the bridge's rate as the followed mark's.
483
+ if (report.type === "selectionTracked") {
484
+ const at = Date.now();
485
+ while (trackedTimes.length > 0 && at - (trackedTimes[0] as number) >= 1_000) {
486
+ trackedTimes.shift();
487
+ }
488
+ if (trackedTimes.length >= TRACKED_PER_SECOND) {
489
+ return;
490
+ }
491
+ trackedTimes.push(at);
492
+ emit("annotation", withinFrame(report));
493
+ return;
494
+ }
459
495
  switch (report.type) {
460
496
  case "selected": {
461
497
  const kind = report.anchor.kind;
@@ -467,7 +503,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
467
503
  }
468
504
  // A pick ends with it; holding a block (P112) lasts until the host stops it.
469
505
  if (kind === "element" && annotating.elements === true) {
470
- annotating = annotating.text ? { elements: false, text: true } : null;
506
+ annotating = annotating.text ? { ...annotating, elements: false } : null;
471
507
  }
472
508
  break;
473
509
  }
@@ -483,7 +519,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
483
519
  return;
484
520
  }
485
521
  if (annotating.elements === true) {
486
- annotating = annotating.text ? { elements: false, text: true } : null;
522
+ annotating = annotating.text ? { ...annotating, elements: false } : null;
487
523
  }
488
524
  break;
489
525
  case "anchored": {
@@ -626,6 +662,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
626
662
  if (activeMark !== null && !marks.some((mark) => mark.id === activeMark)) {
627
663
  activeMark = null;
628
664
  }
665
+ // A followed selection (P138) isn't a mark: a show leaves it.
629
666
  if (tracking !== null && !marks.some((mark) => mark.id === tracking)) {
630
667
  tracking = null;
631
668
  toFrame(ANNOTATE_METHODS.track, { id: null });
@@ -643,12 +680,22 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
643
680
  activeMark = id;
644
681
  toFrame(ANNOTATE_METHODS.focus, { id });
645
682
  },
646
- track(id) {
683
+ track(target) {
647
684
  needsAnnotate("track");
685
+ // The selection (P138), under `id: null`: an older shell follows nothing.
686
+ if (followsSelection(target)) {
687
+ tracking = null;
688
+ trackingSelection = true;
689
+ trackedTimes.length = 0;
690
+ toFrame(ANNOTATE_METHODS.track, { id: null, selection: true });
691
+ return;
692
+ }
693
+ const id = target;
648
694
  if (id !== null && !marks.some((mark) => mark.id === id)) {
649
695
  throw new TypeError(`annotations.track: no mark ${JSON.stringify(id)} is shown`);
650
696
  }
651
697
  tracking = id;
698
+ trackingSelection = false;
652
699
  trackedTimes.length = 0;
653
700
  toFrame(ANNOTATE_METHODS.track, { id });
654
701
  },
@@ -657,6 +704,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
657
704
  marks = [];
658
705
  activeMark = null;
659
706
  tracking = null;
707
+ trackingSelection = false;
660
708
  toFrame(ANNOTATE_METHODS.clear, {});
661
709
  },
662
710
  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 {
@@ -295,7 +300,11 @@ export interface FindControls {
295
300
  * given to every frame the display runs (a reload, a navigation recovered from).
296
301
  */
297
302
  export interface AnnotationControls {
298
- /** Lets the person point at elements, select text, or both (default both). */
303
+ /**
304
+ * Lets the person point at elements, select text, or both (default both). With
305
+ * `keepSelection: true` (P140) the frame keeps what is selected for `track({ selection: true })`;
306
+ * without it, nothing is kept and a pick's outline goes with the pick.
307
+ */
299
308
  start(mode?: AnnotateMode): void;
300
309
  stop(): void;
301
310
  /** Marks these anchors (replacing the marks before); the frame reports where they are. */
@@ -309,8 +318,25 @@ export interface AnnotationControls {
309
318
  * Throws for an id no shown mark has; a `show` without it, or `clear`, stops it. From a newer
310
319
  * shell (P132) each also carries the mark's `documentRect` and the document's `scroll`, so
311
320
  * following one mark tells how far the document scrolled, for every mark placed by `documentRect`.
321
+ *
322
+ * `{ selection: true }` (P138) follows the selection the frame last reported as `selected` (the
323
+ * element picked, or the words selected) instead, for a composer that stays beside it: the frame
324
+ * highlights it while it is followed (an element in the outline it had while it was picked) and
325
+ * reports `{ type: "selectionTracked", ... }` with the same boxes as `tracked` and `inView`, or
326
+ * `state: "orphaned"` while it isn't in the page; at most 60 a second together with `tracked`.
327
+ * The frame keeps a selection to follow only for a host that said so at `start`
328
+ * (`keepSelection`, P140), or one that already follows the selection as it is made: without
329
+ * either, a follow asked after `selected` has nothing to follow and answers `orphaned`. A `show`
330
+ * leaves it, and `stop` (or a pick ending) too: it ends with `track(null)`, `track(id)`
331
+ * or `clear` (comment posted, composer dismissed, Escape in it), and the highlight with it. A
332
+ * newer shell answers at its next animation frame; an older one sends nothing (it reads the
333
+ * message as `track(null)`), so until a `selectionTracked` comes, place by `selected`'s boxes.
334
+ * Kept for a frame that runs later, which has no selection: it answers `orphaned`. Under
335
+ * `keepSelection` the element just picked stays outlined until then, so call it before a `start`
336
+ * or `stop` sent with it (a stop ends that outline); while followed, `selected` isn't re-sent
337
+ * after a scroll (Tenny's review).
312
338
  */
313
- track(id: string | null): void;
339
+ track(target: AnnotationTrackTarget): void;
314
340
  /** Removes every mark. */
315
341
  clear(): void;
316
342
  /**
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,
@@ -680,7 +680,8 @@ export interface PortholeFrameProps {
680
680
  /**
681
681
  * Annotations, where the config declares `annotate` (P053): what the person may point at now
682
682
  * (elements, text, or both), or null to stop. A picked element ends element picking: set it
683
- * again to pick again.
683
+ * again to pick again. `keepSelection` is set for you on a start made while `trackedSelection` is
684
+ * given (P140).
684
685
  */
685
686
  readonly annotating?: AnnotateMode | null;
686
687
  /**
@@ -707,6 +708,24 @@ export interface PortholeFrameProps {
707
708
  * stop the following, as the core's `show` does; it starts again once they have it back.
708
709
  */
709
710
  readonly trackedAnnotation?: string | null;
711
+ /**
712
+ * Follow the selection instead (`annotations.track({ selection: true })`, P138): while true, the
713
+ * element the person picked, or the words they selected, as the last `selected` reported them, is
714
+ * highlighted in the frame and `onAnnotation` gets `{ type: "selectionTracked", ... }` as it moves
715
+ * (the boxes `tracked` has, and `inView`; or `state: "orphaned"` while it isn't in the page), for
716
+ * a composer that stays beside it. It takes `trackedAnnotation`'s place while true (one followed
717
+ * thing at a time); false, or leaving it out, ends it and its highlight (the comment posted, the
718
+ * composer dismissed, Escape in it), and `trackedAnnotation`'s mark is followed again. Until a
719
+ * `selectionTracked` comes, place by `selected`'s boxes: an older shell sends none.
720
+ *
721
+ * Give it from the first render, `false` until the composer opens (P140): each start of
722
+ * `annotating` made while it is given carries `keepSelection`, so the frame keeps what is picked
723
+ * or selected (and the picked element outlined) for the follow. It is read as a mode starts:
724
+ * giving it, or leaving it out, later restarts nothing, and counts from the next start. Left out
725
+ * when the mode started, the frame keeps nothing, and a follow asked after the pick has nothing
726
+ * to follow (`orphaned`).
727
+ */
728
+ readonly trackedSelection?: boolean;
710
729
  /** The display's imperative calls (`PortholeFrameHandle`, P118): React 19's `ref` prop. */
711
730
  readonly ref?: Ref<PortholeFrameHandle>;
712
731
  /**
@@ -966,9 +985,10 @@ function Mount({
966
985
  }: MountProps): ReactElement {
967
986
  const holder = useRef<HTMLDivElement>(null);
968
987
  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);
988
+ // The mark the display follows now, or the selection (P138), as the core keeps it (P118), and
989
+ // the props as last seen.
990
+ const following = useRef<Followed>(null);
991
+ const asked = useRef<Followed>(null);
972
992
  const [ready, setReady] = useState(false);
973
993
  // The height this display started at: later reports don't make it start again.
974
994
  const [startHeight] = useState(initialHeightPx);
@@ -1199,9 +1219,10 @@ function Mount({
1199
1219
  if (config.capabilities.annotate !== undefined) {
1200
1220
  applyAnnotations(display, first);
1201
1221
  }
1202
- // The followed mark, once the marks are shown; without `annotate`, the core's error.
1222
+ // The followed mark or selection, once the marks are shown; without `annotate`, the core's
1223
+ // error.
1203
1224
  following.current = null;
1204
- const wanted = first.trackedAnnotation ?? null;
1225
+ const wanted = followedOf(first);
1205
1226
  asked.current = wanted;
1206
1227
  if (wanted !== null) {
1207
1228
  attempt(() => {
@@ -1279,55 +1300,72 @@ function Mount({
1279
1300
  : JSON.stringify([focusedAnnotation]);
1280
1301
  // By value: the same marks given again don't mark them again.
1281
1302
  const annotations = useByValue(frame.annotations);
1303
+ // The mode, by value: what the person may point at, and the host's own `keepSelection`. Not
1304
+ // whether `trackedSelection` is given (P140, Ferryman's review): that is read at each start, so
1305
+ // a composer's prop that appears or goes restarts no mode (which would turn a pick that ended
1306
+ // back on, for the person's next click to pick again).
1282
1307
  const mode =
1283
1308
  annotating === undefined || annotating === null
1284
1309
  ? ""
1285
- : 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]);
1310
+ : JSON.stringify([
1311
+ annotating.elements ?? true,
1312
+ annotating.text ?? true,
1313
+ annotating.keepSelection === true,
1314
+ ]);
1300
1315
  useEffect(() => {
1301
1316
  const display = handle.current;
1302
1317
  if (annotates && display !== null) {
1303
1318
  attempt(() => {
1304
1319
  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)) {
1320
+ // A show without the followed mark stops the following (the core's own); the selection
1321
+ // stays followed (P138).
1322
+ if (typeof following.current === "string" && !shown(annotations, following.current)) {
1307
1323
  following.current = null;
1308
1324
  }
1309
1325
  }, latest());
1310
1326
  }
1311
1327
  }, [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;
1328
+ // The followed mark, or the selection (P138), follows its props (after the marks above, so the
1329
+ // two can change together).
1330
+ const followed = followedOf(frame);
1314
1331
  useEffect(() => {
1315
1332
  const display = handle.current;
1316
- const changed = trackedAnnotation !== asked.current;
1317
- asked.current = trackedAnnotation;
1318
- if (display === null || trackedAnnotation === following.current) {
1333
+ const changed = followed !== asked.current;
1334
+ asked.current = followed;
1335
+ if (display === null || followed === following.current) {
1319
1336
  return;
1320
1337
  }
1321
1338
  // Its mark was taken off (the error, if any, was told when the prop said it): followed again
1322
1339
  // once the marks have it back.
1323
- if (!changed && trackedAnnotation !== null && !shown(annotations, trackedAnnotation)) {
1340
+ if (!changed && typeof followed === "string" && !shown(annotations, followed)) {
1324
1341
  return;
1325
1342
  }
1326
1343
  attempt(() => {
1327
- display.annotations.track(trackedAnnotation);
1328
- following.current = trackedAnnotation;
1344
+ display.annotations.track(followed);
1345
+ following.current = followed;
1329
1346
  }, latest());
1330
- }, [trackedAnnotation, annotations]);
1347
+ }, [followed, annotations]);
1348
+ // The mode follows its prop, after the following above (P138, Tenny's review): a host that
1349
+ // follows the selection and ends picking in one render has the frame follow it first, so the
1350
+ // pick's outline goes straight to the follow's highlight, never through the stop's gap.
1351
+ useEffect(() => {
1352
+ const display = handle.current;
1353
+ if (!annotates || display === null) {
1354
+ return;
1355
+ }
1356
+ const wanted = mode === "" ? null : (JSON.parse(mode) as [boolean | "hold", boolean, boolean]);
1357
+ attempt(
1358
+ () =>
1359
+ wanted === null
1360
+ ? display.annotations.stop()
1361
+ : display.annotations.start({
1362
+ elements: wanted[0],
1363
+ text: wanted[1],
1364
+ ...(wanted[2] || keepsSelection(latest()) ? { keepSelection: true } : {}),
1365
+ }),
1366
+ latest(),
1367
+ );
1368
+ }, [annotates, mode]);
1331
1369
  useEffect(() => {
1332
1370
  const display = handle.current;
1333
1371
  const id = focusOf(latest().focusedAnnotation);
@@ -1424,7 +1462,9 @@ function applyAnnotations(display: DisplayHandle, frame: PortholeFrameProps): vo
1424
1462
  display.annotations.focus(focused);
1425
1463
  }
1426
1464
  if (frame.annotating !== undefined && frame.annotating !== null) {
1427
- display.annotations.start(frame.annotating);
1465
+ display.annotations.start(
1466
+ keepsSelection(frame) ? { ...frame.annotating, keepSelection: true } : frame.annotating,
1467
+ );
1428
1468
  }
1429
1469
  }, frame);
1430
1470
  }
@@ -1439,6 +1479,24 @@ function useByValue<T>(value: T): T {
1439
1479
  return useMemo(() => (key === "" ? undefined : JSON.parse(key)) as T, [key]);
1440
1480
  }
1441
1481
 
1482
+ /**
1483
+ * Whether a start keeps what is selected for a follow (P140): while `trackedSelection` is given
1484
+ * (true or false), or the host's own `keepSelection` says so. Read at each start, never a reason
1485
+ * for one.
1486
+ */
1487
+ function keepsSelection(frame: PortholeFrameProps): boolean {
1488
+ return frame.annotating?.keepSelection === true || frame.trackedSelection !== undefined;
1489
+ }
1490
+
1491
+ /** What a display follows (P118, P138): a mark's id, the selection (this one object), or nothing. */
1492
+ const SELECTION = Object.freeze({ selection: true } as const);
1493
+ type Followed = string | typeof SELECTION | null;
1494
+
1495
+ /** What the props ask to follow: the selection while `trackedSelection`, else the mark, if any. */
1496
+ function followedOf(frame: PortholeFrameProps): Followed {
1497
+ return frame.trackedSelection === true ? SELECTION : (frame.trackedAnnotation ?? null);
1498
+ }
1499
+
1442
1500
  /** Whether `marks` has a mark `id`. */
1443
1501
  function shown(marks: readonly AnnotationMark[] | undefined, id: string): boolean {
1444
1502
  return (marks ?? []).some((mark) => mark.id === id);