@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.
@@ -1,5 +1,5 @@
1
- import { ANNOTATE_METHODS, } from "../annotate/types.js";
2
- import { annotateMode, checkMarks, clampRect, hasMarker, parseReport, } from "../annotate/validate.js";
1
+ import { ANNOTATE_METHODS } from "../annotate/types.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,
@@ -352,6 +370,12 @@ export function createHost(config, options = {}) {
352
370
  if (type === undefined) {
353
371
  return;
354
372
  }
373
+ // The followed selection (P138) only while the host follows it, and dropped unread
374
+ // otherwise (P140): a host that doesn't follow it takes it as 0.14.14 took a method it
375
+ // didn't know, so a malformed one is no refusal either.
376
+ if (type === "selectionTracked" && !trackingSelection) {
377
+ return;
378
+ }
355
379
  let report = parseReport({ ...(isRecord(raw.params) ? raw.params : {}), type });
356
380
  if (report === null) {
357
381
  void through.call("annotate", null);
@@ -376,6 +400,20 @@ export function createHost(config, options = {}) {
376
400
  emit("annotation", withinFrame(report));
377
401
  return;
378
402
  }
403
+ // The followed selection (P138): only while the host follows it (above), on the same 60 a
404
+ // second (one followed thing at a time), past the bridge's rate as the followed mark's.
405
+ if (report.type === "selectionTracked") {
406
+ const at = Date.now();
407
+ while (trackedTimes.length > 0 && at - trackedTimes[0] >= 1_000) {
408
+ trackedTimes.shift();
409
+ }
410
+ if (trackedTimes.length >= TRACKED_PER_SECOND) {
411
+ return;
412
+ }
413
+ trackedTimes.push(at);
414
+ emit("annotation", withinFrame(report));
415
+ return;
416
+ }
379
417
  switch (report.type) {
380
418
  case "selected": {
381
419
  const kind = report.anchor.kind;
@@ -385,7 +423,7 @@ export function createHost(config, options = {}) {
385
423
  }
386
424
  // A pick ends with it; holding a block (P112) lasts until the host stops it.
387
425
  if (kind === "element" && annotating.elements === true) {
388
- annotating = annotating.text ? { elements: false, text: true } : null;
426
+ annotating = annotating.text ? { ...annotating, elements: false } : null;
389
427
  }
390
428
  break;
391
429
  }
@@ -401,7 +439,7 @@ export function createHost(config, options = {}) {
401
439
  return;
402
440
  }
403
441
  if (annotating.elements === true) {
404
- annotating = annotating.text ? { elements: false, text: true } : null;
442
+ annotating = annotating.text ? { ...annotating, elements: false } : null;
405
443
  }
406
444
  break;
407
445
  case "anchored": {
@@ -540,6 +578,7 @@ export function createHost(config, options = {}) {
540
578
  if (activeMark !== null && !marks.some((mark) => mark.id === activeMark)) {
541
579
  activeMark = null;
542
580
  }
581
+ // A followed selection (P138) isn't a mark: a show leaves it.
543
582
  if (tracking !== null && !marks.some((mark) => mark.id === tracking)) {
544
583
  tracking = null;
545
584
  toFrame(ANNOTATE_METHODS.track, { id: null });
@@ -557,12 +596,22 @@ export function createHost(config, options = {}) {
557
596
  activeMark = id;
558
597
  toFrame(ANNOTATE_METHODS.focus, { id });
559
598
  },
560
- track(id) {
599
+ track(target) {
561
600
  needsAnnotate("track");
601
+ // The selection (P138), under `id: null`: an older shell follows nothing.
602
+ if (followsSelection(target)) {
603
+ tracking = null;
604
+ trackingSelection = true;
605
+ trackedTimes.length = 0;
606
+ toFrame(ANNOTATE_METHODS.track, { id: null, selection: true });
607
+ return;
608
+ }
609
+ const id = target;
562
610
  if (id !== null && !marks.some((mark) => mark.id === id)) {
563
611
  throw new TypeError(`annotations.track: no mark ${JSON.stringify(id)} is shown`);
564
612
  }
565
613
  tracking = id;
614
+ trackingSelection = false;
566
615
  trackedTimes.length = 0;
567
616
  toFrame(ANNOTATE_METHODS.track, { id });
568
617
  },
@@ -571,6 +620,7 @@ export function createHost(config, options = {}) {
571
620
  marks = [];
572
621
  activeMark = null;
573
622
  tracking = null;
623
+ trackingSelection = false;
574
624
  toFrame(ANNOTATE_METHODS.clear, {});
575
625
  },
576
626
  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";
@@ -301,7 +301,11 @@ export interface FindControls {
301
301
  * given to every frame the display runs (a reload, a navigation recovered from).
302
302
  */
303
303
  export interface AnnotationControls {
304
- /** Lets the person point at elements, select text, or both (default both). */
304
+ /**
305
+ * Lets the person point at elements, select text, or both (default both). With
306
+ * `keepSelection: true` (P140) the frame keeps what is selected for `track({ selection: true })`;
307
+ * without it, nothing is kept and a pick's outline goes with the pick.
308
+ */
305
309
  start(mode?: AnnotateMode): void;
306
310
  stop(): void;
307
311
  /** Marks these anchors (replacing the marks before); the frame reports where they are. */
@@ -315,8 +319,25 @@ export interface AnnotationControls {
315
319
  * Throws for an id no shown mark has; a `show` without it, or `clear`, stops it. From a newer
316
320
  * shell (P132) each also carries the mark's `documentRect` and the document's `scroll`, so
317
321
  * following one mark tells how far the document scrolled, for every mark placed by `documentRect`.
322
+ *
323
+ * `{ selection: true }` (P138) follows the selection the frame last reported as `selected` (the
324
+ * element picked, or the words selected) instead, for a composer that stays beside it: the frame
325
+ * highlights it while it is followed (an element in the outline it had while it was picked) and
326
+ * reports `{ type: "selectionTracked", ... }` with the same boxes as `tracked` and `inView`, or
327
+ * `state: "orphaned"` while it isn't in the page; at most 60 a second together with `tracked`.
328
+ * The frame keeps a selection to follow only for a host that said so at `start`
329
+ * (`keepSelection`, P140), or one that already follows the selection as it is made: without
330
+ * either, a follow asked after `selected` has nothing to follow and answers `orphaned`. A `show`
331
+ * leaves it, and `stop` (or a pick ending) too: it ends with `track(null)`, `track(id)`
332
+ * or `clear` (comment posted, composer dismissed, Escape in it), and the highlight with it. A
333
+ * newer shell answers at its next animation frame; an older one sends nothing (it reads the
334
+ * message as `track(null)`), so until a `selectionTracked` comes, place by `selected`'s boxes.
335
+ * Kept for a frame that runs later, which has no selection: it answers `orphaned`. Under
336
+ * `keepSelection` the element just picked stays outlined until then, so call it before a `start`
337
+ * or `stop` sent with it (a stop ends that outline); while followed, `selected` isn't re-sent
338
+ * after a scroll (Tenny's review).
318
339
  */
319
- track(id: string | null): void;
340
+ track(target: AnnotationTrackTarget): void;
320
341
  /** Removes every mark. */
321
342
  clear(): void;
322
343
  /**
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";
@@ -311,7 +311,8 @@ export interface PortholeFrameProps {
311
311
  /**
312
312
  * Annotations, where the config declares `annotate` (P053): what the person may point at now
313
313
  * (elements, text, or both), or null to stop. A picked element ends element picking: set it
314
- * again to pick again.
314
+ * again to pick again. `keepSelection` is set for you on a start made while `trackedSelection` is
315
+ * given (P140).
315
316
  */
316
317
  readonly annotating?: AnnotateMode | null;
317
318
  /**
@@ -338,6 +339,24 @@ export interface PortholeFrameProps {
338
339
  * stop the following, as the core's `show` does; it starts again once they have it back.
339
340
  */
340
341
  readonly trackedAnnotation?: string | null;
342
+ /**
343
+ * Follow the selection instead (`annotations.track({ selection: true })`, P138): while true, the
344
+ * element the person picked, or the words they selected, as the last `selected` reported them, is
345
+ * highlighted in the frame and `onAnnotation` gets `{ type: "selectionTracked", ... }` as it moves
346
+ * (the boxes `tracked` has, and `inView`; or `state: "orphaned"` while it isn't in the page), for
347
+ * a composer that stays beside it. It takes `trackedAnnotation`'s place while true (one followed
348
+ * thing at a time); false, or leaving it out, ends it and its highlight (the comment posted, the
349
+ * composer dismissed, Escape in it), and `trackedAnnotation`'s mark is followed again. Until a
350
+ * `selectionTracked` comes, place by `selected`'s boxes: an older shell sends none.
351
+ *
352
+ * Give it from the first render, `false` until the composer opens (P140): each start of
353
+ * `annotating` made while it is given carries `keepSelection`, so the frame keeps what is picked
354
+ * or selected (and the picked element outlined) for the follow. It is read as a mode starts:
355
+ * giving it, or leaving it out, later restarts nothing, and counts from the next start. Left out
356
+ * when the mode started, the frame keeps nothing, and a follow asked after the pick has nothing
357
+ * to follow (`orphaned`).
358
+ */
359
+ readonly trackedSelection?: boolean;
341
360
  /** The display's imperative calls (`PortholeFrameHandle`, P118): React 19's `ref` prop. */
342
361
  readonly ref?: Ref<PortholeFrameHandle>;
343
362
  /**
@@ -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(() => {
@@ -727,50 +729,67 @@ function Mount({ frame, page, running, findFor, initialHeightPx, placeholder, ru
727
729
  : JSON.stringify([focusedAnnotation]);
728
730
  // By value: the same marks given again don't mark them again.
729
731
  const annotations = useByValue(frame.annotations);
732
+ // The mode, by value: what the person may point at, and the host's own `keepSelection`. Not
733
+ // whether `trackedSelection` is given (P140, Ferryman's review): that is read at each start, so
734
+ // a composer's prop that appears or goes restarts no mode (which would turn a pick that ended
735
+ // back on, for the person's next click to pick again).
730
736
  const mode = annotating === undefined || annotating === null
731
737
  ? ""
732
- : 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]);
738
+ : JSON.stringify([
739
+ annotating.elements ?? true,
740
+ annotating.text ?? true,
741
+ annotating.keepSelection === true,
742
+ ]);
743
743
  useEffect(() => {
744
744
  const display = handle.current;
745
745
  if (annotates && display !== null) {
746
746
  attempt(() => {
747
747
  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)) {
748
+ // A show without the followed mark stops the following (the core's own); the selection
749
+ // stays followed (P138).
750
+ if (typeof following.current === "string" && !shown(annotations, following.current)) {
750
751
  following.current = null;
751
752
  }
752
753
  }, latest());
753
754
  }
754
755
  }, [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;
756
+ // The followed mark, or the selection (P138), follows its props (after the marks above, so the
757
+ // two can change together).
758
+ const followed = followedOf(frame);
757
759
  useEffect(() => {
758
760
  const display = handle.current;
759
- const changed = trackedAnnotation !== asked.current;
760
- asked.current = trackedAnnotation;
761
- if (display === null || trackedAnnotation === following.current) {
761
+ const changed = followed !== asked.current;
762
+ asked.current = followed;
763
+ if (display === null || followed === following.current) {
762
764
  return;
763
765
  }
764
766
  // Its mark was taken off (the error, if any, was told when the prop said it): followed again
765
767
  // once the marks have it back.
766
- if (!changed && trackedAnnotation !== null && !shown(annotations, trackedAnnotation)) {
768
+ if (!changed && typeof followed === "string" && !shown(annotations, followed)) {
767
769
  return;
768
770
  }
769
771
  attempt(() => {
770
- display.annotations.track(trackedAnnotation);
771
- following.current = trackedAnnotation;
772
+ display.annotations.track(followed);
773
+ following.current = followed;
772
774
  }, latest());
773
- }, [trackedAnnotation, annotations]);
775
+ }, [followed, annotations]);
776
+ // The mode follows its prop, after the following above (P138, Tenny's review): a host that
777
+ // follows the selection and ends picking in one render has the frame follow it first, so the
778
+ // pick's outline goes straight to the follow's highlight, never through the stop's gap.
779
+ useEffect(() => {
780
+ const display = handle.current;
781
+ if (!annotates || display === null) {
782
+ return;
783
+ }
784
+ const wanted = mode === "" ? null : JSON.parse(mode);
785
+ attempt(() => wanted === null
786
+ ? display.annotations.stop()
787
+ : display.annotations.start({
788
+ elements: wanted[0],
789
+ text: wanted[1],
790
+ ...(wanted[2] || keepsSelection(latest()) ? { keepSelection: true } : {}),
791
+ }), latest());
792
+ }, [annotates, mode]);
774
793
  useEffect(() => {
775
794
  const display = handle.current;
776
795
  const id = focusOf(latest().focusedAnnotation);
@@ -852,7 +871,7 @@ function applyAnnotations(display, frame) {
852
871
  display.annotations.focus(focused);
853
872
  }
854
873
  if (frame.annotating !== undefined && frame.annotating !== null) {
855
- display.annotations.start(frame.annotating);
874
+ display.annotations.start(keepsSelection(frame) ? { ...frame.annotating, keepSelection: true } : frame.annotating);
856
875
  }
857
876
  }, frame);
858
877
  }
@@ -865,6 +884,20 @@ function useByValue(value) {
865
884
  const key = value === undefined ? "" : JSON.stringify(value);
866
885
  return useMemo(() => (key === "" ? undefined : JSON.parse(key)), [key]);
867
886
  }
887
+ /**
888
+ * Whether a start keeps what is selected for a follow (P140): while `trackedSelection` is given
889
+ * (true or false), or the host's own `keepSelection` says so. Read at each start, never a reason
890
+ * for one.
891
+ */
892
+ function keepsSelection(frame) {
893
+ return frame.annotating?.keepSelection === true || frame.trackedSelection !== undefined;
894
+ }
895
+ /** What a display follows (P118, P138): a mark's id, the selection (this one object), or nothing. */
896
+ const SELECTION = Object.freeze({ selection: true });
897
+ /** What the props ask to follow: the selection while `trackedSelection`, else the mark, if any. */
898
+ function followedOf(frame) {
899
+ return frame.trackedSelection === true ? SELECTION : (frame.trackedAnnotation ?? null);
900
+ }
868
901
  /** Whether `marks` has a mark `id`. */
869
902
  function shown(marks, id) {
870
903
  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,13 @@ 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 while the host follows the selection (`track` with `selection`) or said
65
+ * at `start` that it will (`keepSelection`, P140), and nothing is kept otherwise; while followed
66
+ * it is drawn in the layer and its boxes are reported as a followed mark's are
67
+ * (`selectionTracked`), with whether it is in view, or that it is gone; it takes no pointer, no
68
+ * focus and no key.
63
69
  *
64
70
  * It shares the realm with the content, which can interfere with all of it: the host takes its
65
71
  * reports as UI hints only.