@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.
- package/CHANGELOG.md +27 -0
- package/dist/annotate/types.d.ts +41 -1
- package/dist/annotate/types.js +7 -1
- package/dist/annotate/validate.d.ts +17 -1
- package/dist/annotate/validate.js +55 -0
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +50 -3
- package/dist/host/types.d.ts +16 -2
- package/dist/index.d.ts +1 -1
- package/dist/react/frame.d.ts +11 -0
- package/dist/react/frame.js +37 -24
- package/dist/shell/annotate.d.ts +6 -2
- package/dist/shell/annotate.js +158 -11
- package/docs/ADOPTING.md +41 -1
- package/docs/DECISIONS.md +165 -2
- package/docs/DESIGN.md +27 -5
- package/docs/THREAT_MODEL.md +14 -5
- package/package.json +1 -1
- package/src/annotate/types.ts +38 -1
- package/src/annotate/validate.ts +67 -0
- package/src/host/create-host.ts +51 -2
- package/src/host/types.ts +21 -2
- package/src/index.ts +1 -0
- package/src/react/frame.tsx +57 -30
- package/src/shell/annotate.ts +158 -11
package/src/host/create-host.ts
CHANGED
|
@@ -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),
|
|
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(
|
|
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 {
|
|
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(
|
|
332
|
+
track(target: AnnotationTrackTarget): void;
|
|
314
333
|
/** Removes every mark. */
|
|
315
334
|
clear(): void;
|
|
316
335
|
/**
|
package/src/index.ts
CHANGED
package/src/react/frame.tsx
CHANGED
|
@@ -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
|
|
970
|
-
|
|
971
|
-
const
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
1313
|
-
|
|
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 =
|
|
1317
|
-
asked.current =
|
|
1318
|
-
if (display === null ||
|
|
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 &&
|
|
1324
|
+
if (!changed && typeof followed === "string" && !shown(annotations, followed)) {
|
|
1324
1325
|
return;
|
|
1325
1326
|
}
|
|
1326
1327
|
attempt(() => {
|
|
1327
|
-
display.annotations.track(
|
|
1328
|
-
following.current =
|
|
1328
|
+
display.annotations.track(followed);
|
|
1329
|
+
following.current = followed;
|
|
1329
1330
|
}, latest());
|
|
1330
|
-
}, [
|
|
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);
|
package/src/shell/annotate.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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 = [];
|