@botiverse/porthole 0.14.13 → 0.14.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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() {
@@ -667,9 +716,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
667
716
  focusMark(id) {
668
717
  // Host → frame only, and kept for no later frame (P134). A mark that has gone, or has no
669
718
  // marker, is nothing to ask for, and no fault: the host's card closed with the mark's.
719
+ // Stamped as it is sent: a frame judges by that how old the word is as it takes it (P137).
670
720
  needsAnnotate("focusMark");
671
721
  if (marks.some((mark) => mark.id === id && hasMarker(mark))) {
672
- toFrame(ANNOTATE_METHODS.focusMark, { id });
722
+ toFrame(ANNOTATE_METHODS.focusMark, { id, at: Date.now() });
673
723
  }
674
724
  },
675
725
  };
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
  /**
@@ -332,11 +351,12 @@ export interface AnnotationControls {
332
351
  *
333
352
  * On a calm page it lands at once, from anywhere on the host's page. While the frame is finding
334
353
  * its marks (a `show` just sent, the content just changed) it waits, and is then dropped unless
335
- * the focus is in the frame by then (P135), so a word that comes late takes no keyboard from a
336
- * person who moved on. Nothing says it was dropped: if the frame isn't your page's
354
+ * the focus is in the frame by then (P135). One the frame takes more than 100 ms after you sent
355
+ * it (its page is busy) is held to the same test (P137), so a word that comes late takes no
356
+ * keyboard from a person who moved on. Nothing says it was dropped: if the frame isn't your page's
337
357
  * `document.activeElement` soon after and the person hasn't moved on, call `focus()` and then
338
- * `focusMark(id)` again. Known gap: on a nested page that had the focus, `focus()` doesn't bring
339
- * it back into the page, so a second call that waits is dropped too (ADOPTING).
358
+ * `focusMark(id)` again. On a nested page only `focus()` reaches the page (P136): the frame's own
359
+ * `focus()` stops at its shell, and a second call that waits is dropped.
340
360
  */
341
361
  focusMark(id: string): void;
342
362
  }
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,
@@ -100,6 +100,13 @@ export const SHELL_BEAT_METHOD = "porthole/shell/beat";
100
100
  */
101
101
  export const SHELL_LOOK_METHOD = "porthole/shell/look";
102
102
 
103
+ /**
104
+ * The host's word to a nested page's shell (P136) that it moved the focus into the frame: pass it on
105
+ * to the page, in this task, not in the focus event (where the shell's move doesn't take). Sent by
106
+ * `display.focus()` alone; a page has no way to say it.
107
+ */
108
+ export const SHELL_FOCUS_METHOD = "porthole/shell/focus";
109
+
103
110
  /** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
104
111
  export const SHELL_METHOD_PREFIX = "porthole/shell/";
105
112
 
@@ -2,6 +2,7 @@ import { DOOR_SANDBOX_TOKENS } from "../compile/policy.ts";
2
2
  import type { ColorScheme } from "../config/schema.ts";
3
3
  import {
4
4
  SHELL_BEAT_METHOD,
5
+ SHELL_FOCUS_METHOD,
5
6
  SHELL_LOOK_METHOD,
6
7
  SHELL_METHOD_PREFIX,
7
8
  SHELL_STATE_METHOD,
@@ -194,6 +195,11 @@ export const webPlatform: PlatformHost = {
194
195
  },
195
196
  focus() {
196
197
  guard.focus(frame);
198
+ // A nested page (P136): the move stops at its shell on every engine, one way or another,
199
+ // and only the shell can pass it on. Only a move that landed: the shell asks no more of it.
200
+ if (nested && view.document.activeElement === frame) {
201
+ opened.send({ jsonrpc: "2.0", method: SHELL_FOCUS_METHOD });
202
+ }
197
203
  },
198
204
  onLoad(listener) {
199
205
  loaded.add(listener);
@@ -502,7 +502,8 @@ export interface PortholeFrameHandle {
502
502
  * once Escape closed your own view of that mark. Nothing happens for an id with no marker, or
503
503
  * while no display runs. A config without `annotate`: `onHostError`, kind `"annotations"`. While
504
504
  * the frame is finding its marks it waits, and is dropped unless the focus is in the frame by
505
- * then (P135): call it again after your own move of the focus into the frame.
505
+ * then (P135), and so is one a busy page takes late (P137): call it again after your own move of
506
+ * the focus into the frame.
506
507
  */
507
508
  focusMark(id: string): void;
508
509
  /**
@@ -706,6 +707,17 @@ export interface PortholeFrameProps {
706
707
  * stop the following, as the core's `show` does; it starts again once they have it back.
707
708
  */
708
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;
709
721
  /** The display's imperative calls (`PortholeFrameHandle`, P118): React 19's `ref` prop. */
710
722
  readonly ref?: Ref<PortholeFrameHandle>;
711
723
  /**
@@ -965,9 +977,10 @@ function Mount({
965
977
  }: MountProps): ReactElement {
966
978
  const holder = useRef<HTMLDivElement>(null);
967
979
  const handle = useRef<DisplayHandle | null>(null);
968
- // The mark the display follows now, as the core keeps it (P118), and the prop as last seen.
969
- const following = useRef<string | null>(null);
970
- 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);
971
984
  const [ready, setReady] = useState(false);
972
985
  // The height this display started at: later reports don't make it start again.
973
986
  const [startHeight] = useState(initialHeightPx);
@@ -1198,9 +1211,10 @@ function Mount({
1198
1211
  if (config.capabilities.annotate !== undefined) {
1199
1212
  applyAnnotations(display, first);
1200
1213
  }
1201
- // 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.
1202
1216
  following.current = null;
1203
- const wanted = first.trackedAnnotation ?? null;
1217
+ const wanted = followedOf(first);
1204
1218
  asked.current = wanted;
1205
1219
  if (wanted !== null) {
1206
1220
  attempt(() => {
@@ -1282,51 +1296,56 @@ function Mount({
1282
1296
  annotating === undefined || annotating === null
1283
1297
  ? ""
1284
1298
  : JSON.stringify([annotating.elements ?? true, annotating.text ?? true]);
1285
- useEffect(() => {
1286
- const display = handle.current;
1287
- if (!annotates || display === null) {
1288
- return;
1289
- }
1290
- const wanted = mode === "" ? null : (JSON.parse(mode) as [boolean, boolean]);
1291
- attempt(
1292
- () =>
1293
- wanted === null
1294
- ? display.annotations.stop()
1295
- : display.annotations.start({ elements: wanted[0], text: wanted[1] }),
1296
- latest(),
1297
- );
1298
- }, [annotates, mode]);
1299
1299
  useEffect(() => {
1300
1300
  const display = handle.current;
1301
1301
  if (annotates && display !== null) {
1302
1302
  attempt(() => {
1303
1303
  display.annotations.show(annotations ?? []);
1304
- // A show without the followed mark stops the following (the core's own).
1305
- 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)) {
1306
1307
  following.current = null;
1307
1308
  }
1308
1309
  }, latest());
1309
1310
  }
1310
1311
  }, [annotates, annotations]);
1311
- // The followed mark follows its prop (after the marks above, so the two can change together).
1312
- 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);
1313
1315
  useEffect(() => {
1314
1316
  const display = handle.current;
1315
- const changed = trackedAnnotation !== asked.current;
1316
- asked.current = trackedAnnotation;
1317
- if (display === null || trackedAnnotation === following.current) {
1317
+ const changed = followed !== asked.current;
1318
+ asked.current = followed;
1319
+ if (display === null || followed === following.current) {
1318
1320
  return;
1319
1321
  }
1320
1322
  // Its mark was taken off (the error, if any, was told when the prop said it): followed again
1321
1323
  // once the marks have it back.
1322
- if (!changed && trackedAnnotation !== null && !shown(annotations, trackedAnnotation)) {
1324
+ if (!changed && typeof followed === "string" && !shown(annotations, followed)) {
1323
1325
  return;
1324
1326
  }
1325
1327
  attempt(() => {
1326
- display.annotations.track(trackedAnnotation);
1327
- following.current = trackedAnnotation;
1328
+ display.annotations.track(followed);
1329
+ following.current = followed;
1328
1330
  }, latest());
1329
- }, [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]);
1330
1349
  useEffect(() => {
1331
1350
  const display = handle.current;
1332
1351
  const id = focusOf(latest().focusedAnnotation);
@@ -1438,6 +1457,15 @@ function useByValue<T>(value: T): T {
1438
1457
  return useMemo(() => (key === "" ? undefined : JSON.parse(key)) as T, [key]);
1439
1458
  }
1440
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
+
1441
1469
  /** Whether `marks` has a mark `id`. */
1442
1470
  function shown(marks: readonly AnnotationMark[] | undefined, id: string): boolean {
1443
1471
  return (marks ?? []).some((mark) => mark.id === id);