@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/dist/host/create-host.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { ANNOTATE_METHODS, } from "../annotate/types.js";
|
|
2
|
-
import { annotateMode, checkMarks, clampRect, hasMarker, parseReport, } from "../annotate/validate.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),
|
|
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,
|
|
@@ -376,6 +394,23 @@ export function createHost(config, options = {}) {
|
|
|
376
394
|
emit("annotation", withinFrame(report));
|
|
377
395
|
return;
|
|
378
396
|
}
|
|
397
|
+
// The followed selection (P138): only while the host follows it, on the same 60 a second
|
|
398
|
+
// (one followed thing at a time), past the bridge's rate as the followed mark's.
|
|
399
|
+
if (report.type === "selectionTracked") {
|
|
400
|
+
if (!trackingSelection) {
|
|
401
|
+
return;
|
|
402
|
+
}
|
|
403
|
+
const at = Date.now();
|
|
404
|
+
while (trackedTimes.length > 0 && at - trackedTimes[0] >= 1_000) {
|
|
405
|
+
trackedTimes.shift();
|
|
406
|
+
}
|
|
407
|
+
if (trackedTimes.length >= TRACKED_PER_SECOND) {
|
|
408
|
+
return;
|
|
409
|
+
}
|
|
410
|
+
trackedTimes.push(at);
|
|
411
|
+
emit("annotation", withinFrame(report));
|
|
412
|
+
return;
|
|
413
|
+
}
|
|
379
414
|
switch (report.type) {
|
|
380
415
|
case "selected": {
|
|
381
416
|
const kind = report.anchor.kind;
|
|
@@ -540,6 +575,7 @@ export function createHost(config, options = {}) {
|
|
|
540
575
|
if (activeMark !== null && !marks.some((mark) => mark.id === activeMark)) {
|
|
541
576
|
activeMark = null;
|
|
542
577
|
}
|
|
578
|
+
// A followed selection (P138) isn't a mark: a show leaves it.
|
|
543
579
|
if (tracking !== null && !marks.some((mark) => mark.id === tracking)) {
|
|
544
580
|
tracking = null;
|
|
545
581
|
toFrame(ANNOTATE_METHODS.track, { id: null });
|
|
@@ -557,12 +593,22 @@ export function createHost(config, options = {}) {
|
|
|
557
593
|
activeMark = id;
|
|
558
594
|
toFrame(ANNOTATE_METHODS.focus, { id });
|
|
559
595
|
},
|
|
560
|
-
track(
|
|
596
|
+
track(target) {
|
|
561
597
|
needsAnnotate("track");
|
|
598
|
+
// The selection (P138), under `id: null`: an older shell follows nothing.
|
|
599
|
+
if (followsSelection(target)) {
|
|
600
|
+
tracking = null;
|
|
601
|
+
trackingSelection = true;
|
|
602
|
+
trackedTimes.length = 0;
|
|
603
|
+
toFrame(ANNOTATE_METHODS.track, { id: null, selection: true });
|
|
604
|
+
return;
|
|
605
|
+
}
|
|
606
|
+
const id = target;
|
|
562
607
|
if (id !== null && !marks.some((mark) => mark.id === id)) {
|
|
563
608
|
throw new TypeError(`annotations.track: no mark ${JSON.stringify(id)} is shown`);
|
|
564
609
|
}
|
|
565
610
|
tracking = id;
|
|
611
|
+
trackingSelection = false;
|
|
566
612
|
trackedTimes.length = 0;
|
|
567
613
|
toFrame(ANNOTATE_METHODS.track, { id });
|
|
568
614
|
},
|
|
@@ -571,6 +617,7 @@ export function createHost(config, options = {}) {
|
|
|
571
617
|
marks = [];
|
|
572
618
|
activeMark = null;
|
|
573
619
|
tracking = null;
|
|
620
|
+
trackingSelection = false;
|
|
574
621
|
toFrame(ANNOTATE_METHODS.clear, {});
|
|
575
622
|
},
|
|
576
623
|
clearSelection() {
|
package/dist/host/types.d.ts
CHANGED
|
@@ -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";
|
|
@@ -315,8 +315,22 @@ export interface AnnotationControls {
|
|
|
315
315
|
* Throws for an id no shown mark has; a `show` without it, or `clear`, stops it. From a newer
|
|
316
316
|
* shell (P132) each also carries the mark's `documentRect` and the document's `scroll`, so
|
|
317
317
|
* following one mark tells how far the document scrolled, for every mark placed by `documentRect`.
|
|
318
|
+
*
|
|
319
|
+
* `{ selection: true }` (P138) follows the selection the frame last reported as `selected` (the
|
|
320
|
+
* element picked, or the words selected) instead, for a composer that stays beside it: the frame
|
|
321
|
+
* highlights it while it is followed (an element in the outline it had while it was picked) and
|
|
322
|
+
* reports `{ type: "selectionTracked", ... }` with the same boxes as `tracked` and `inView`, or
|
|
323
|
+
* `state: "orphaned"` while it isn't in the page; at most 60 a second together with `tracked`.
|
|
324
|
+
* A `show` leaves it, and `stop` (or a pick ending) too: it ends with `track(null)`, `track(id)`
|
|
325
|
+
* or `clear` (comment posted, composer dismissed, Escape in it), and the highlight with it. A
|
|
326
|
+
* newer shell answers at its next animation frame; an older one sends nothing (it reads the
|
|
327
|
+
* message as `track(null)`), so until a `selectionTracked` comes, place by `selected`'s boxes.
|
|
328
|
+
* Kept for a frame that runs later, which has no selection: it answers `orphaned`. The element
|
|
329
|
+
* just picked stays outlined until then, so call it before a `start` or `stop` sent with it (a
|
|
330
|
+
* stop ends that outline); while followed, `selected` isn't re-sent after a scroll (Tenny's
|
|
331
|
+
* review).
|
|
318
332
|
*/
|
|
319
|
-
track(
|
|
333
|
+
track(target: AnnotationTrackTarget): void;
|
|
320
334
|
/** Removes every mark. */
|
|
321
335
|
clear(): void;
|
|
322
336
|
/**
|
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";
|
package/dist/react/frame.d.ts
CHANGED
|
@@ -338,6 +338,17 @@ export interface PortholeFrameProps {
|
|
|
338
338
|
* stop the following, as the core's `show` does; it starts again once they have it back.
|
|
339
339
|
*/
|
|
340
340
|
readonly trackedAnnotation?: string | null;
|
|
341
|
+
/**
|
|
342
|
+
* Follow the selection instead (`annotations.track({ selection: true })`, P138): while true, the
|
|
343
|
+
* element the person picked, or the words they selected, as the last `selected` reported them, is
|
|
344
|
+
* highlighted in the frame and `onAnnotation` gets `{ type: "selectionTracked", ... }` as it moves
|
|
345
|
+
* (the boxes `tracked` has, and `inView`; or `state: "orphaned"` while it isn't in the page), for
|
|
346
|
+
* a composer that stays beside it. It takes `trackedAnnotation`'s place while true (one followed
|
|
347
|
+
* thing at a time); false, or leaving it out, ends it and its highlight (the comment posted, the
|
|
348
|
+
* composer dismissed, Escape in it), and `trackedAnnotation`'s mark is followed again. Until a
|
|
349
|
+
* `selectionTracked` comes, place by `selected`'s boxes: an older shell sends none.
|
|
350
|
+
*/
|
|
351
|
+
readonly trackedSelection?: boolean;
|
|
341
352
|
/** The display's imperative calls (`PortholeFrameHandle`, P118): React 19's `ref` prop. */
|
|
342
353
|
readonly ref?: Ref<PortholeFrameHandle>;
|
|
343
354
|
/**
|
package/dist/react/frame.js
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
656
|
+
const wanted = followedOf(first);
|
|
655
657
|
asked.current = wanted;
|
|
656
658
|
if (wanted !== null) {
|
|
657
659
|
attempt(() => {
|
|
@@ -730,47 +732,52 @@ function Mount({ frame, page, running, findFor, initialHeightPx, placeholder, ru
|
|
|
730
732
|
const mode = annotating === undefined || annotating === null
|
|
731
733
|
? ""
|
|
732
734
|
: 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]);
|
|
743
735
|
useEffect(() => {
|
|
744
736
|
const display = handle.current;
|
|
745
737
|
if (annotates && display !== null) {
|
|
746
738
|
attempt(() => {
|
|
747
739
|
display.annotations.show(annotations ?? []);
|
|
748
|
-
// A show without the followed mark stops the following (the core's own)
|
|
749
|
-
|
|
740
|
+
// A show without the followed mark stops the following (the core's own); the selection
|
|
741
|
+
// stays followed (P138).
|
|
742
|
+
if (typeof following.current === "string" && !shown(annotations, following.current)) {
|
|
750
743
|
following.current = null;
|
|
751
744
|
}
|
|
752
745
|
}, latest());
|
|
753
746
|
}
|
|
754
747
|
}, [annotates, annotations]);
|
|
755
|
-
// The followed mark follows its
|
|
756
|
-
|
|
748
|
+
// The followed mark, or the selection (P138), follows its props (after the marks above, so the
|
|
749
|
+
// two can change together).
|
|
750
|
+
const followed = followedOf(frame);
|
|
757
751
|
useEffect(() => {
|
|
758
752
|
const display = handle.current;
|
|
759
|
-
const changed =
|
|
760
|
-
asked.current =
|
|
761
|
-
if (display === null ||
|
|
753
|
+
const changed = followed !== asked.current;
|
|
754
|
+
asked.current = followed;
|
|
755
|
+
if (display === null || followed === following.current) {
|
|
762
756
|
return;
|
|
763
757
|
}
|
|
764
758
|
// Its mark was taken off (the error, if any, was told when the prop said it): followed again
|
|
765
759
|
// once the marks have it back.
|
|
766
|
-
if (!changed &&
|
|
760
|
+
if (!changed && typeof followed === "string" && !shown(annotations, followed)) {
|
|
767
761
|
return;
|
|
768
762
|
}
|
|
769
763
|
attempt(() => {
|
|
770
|
-
display.annotations.track(
|
|
771
|
-
following.current =
|
|
764
|
+
display.annotations.track(followed);
|
|
765
|
+
following.current = followed;
|
|
772
766
|
}, latest());
|
|
773
|
-
}, [
|
|
767
|
+
}, [followed, annotations]);
|
|
768
|
+
// The mode follows its prop, after the following above (P138, Tenny's review): a host that
|
|
769
|
+
// follows the selection and ends picking in one render has the frame follow it first, so the
|
|
770
|
+
// pick's outline goes straight to the follow's highlight, never through the stop's gap.
|
|
771
|
+
useEffect(() => {
|
|
772
|
+
const display = handle.current;
|
|
773
|
+
if (!annotates || display === null) {
|
|
774
|
+
return;
|
|
775
|
+
}
|
|
776
|
+
const wanted = mode === "" ? null : JSON.parse(mode);
|
|
777
|
+
attempt(() => wanted === null
|
|
778
|
+
? display.annotations.stop()
|
|
779
|
+
: display.annotations.start({ elements: wanted[0], text: wanted[1] }), latest());
|
|
780
|
+
}, [annotates, mode]);
|
|
774
781
|
useEffect(() => {
|
|
775
782
|
const display = handle.current;
|
|
776
783
|
const id = focusOf(latest().focusedAnnotation);
|
|
@@ -865,6 +872,12 @@ function useByValue(value) {
|
|
|
865
872
|
const key = value === undefined ? "" : JSON.stringify(value);
|
|
866
873
|
return useMemo(() => (key === "" ? undefined : JSON.parse(key)), [key]);
|
|
867
874
|
}
|
|
875
|
+
/** What a display follows (P118, P138): a mark's id, the selection (this one object), or nothing. */
|
|
876
|
+
const SELECTION = Object.freeze({ selection: true });
|
|
877
|
+
/** What the props ask to follow: the selection while `trackedSelection`, else the mark, if any. */
|
|
878
|
+
function followedOf(frame) {
|
|
879
|
+
return frame.trackedSelection === true ? SELECTION : (frame.trackedAnnotation ?? null);
|
|
880
|
+
}
|
|
868
881
|
/** Whether `marks` has a mark `id`. */
|
|
869
882
|
function shown(marks, id) {
|
|
870
883
|
return (marks ?? []).some((mark) => mark.id === id);
|
package/dist/shell/annotate.d.ts
CHANGED
|
@@ -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,11 @@ 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, and while the host follows it (`track` with `selection`) it is drawn
|
|
65
|
+
* in the layer and its boxes are reported as a followed mark's are (`selectionTracked`), with
|
|
66
|
+
* whether it is in view, or that it is gone; it takes no pointer, no focus and no key.
|
|
63
67
|
*
|
|
64
68
|
* It shares the realm with the content, which can interfere with all of it: the host takes its
|
|
65
69
|
* reports as UI hints only.
|
package/dist/shell/annotate.js
CHANGED
|
@@ -77,7 +77,7 @@ export const WORD_LATE = String.raw `(at, now) => {
|
|
|
77
77
|
* in one).
|
|
78
78
|
*
|
|
79
79
|
* The host drives it (`porthole/annotate.start|stop|show|focus|clear|track|clearSelection|focusMark`)
|
|
80
|
-
* and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked`):
|
|
80
|
+
* and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked|selectionTracked`):
|
|
81
81
|
* - picking an element: the element under the pointer (or finger) is outlined with its name; a
|
|
82
82
|
* click or tap picks it, and the content's own handlers never see that click (unless the content
|
|
83
83
|
* patched the DOM's built-ins, P105); Escape cancels (while selecting text too, P112);
|
|
@@ -103,7 +103,11 @@ export const WORD_LATE = String.raw `(at, now) => {
|
|
|
103
103
|
* followed mark's (`tracked`) too, so a host places marks scrolled out of the frame, and keeps
|
|
104
104
|
* them placed as the document scrolls, from one report and the followed mark's scroll;
|
|
105
105
|
* - the last line (P133): where a selection or a mark's words end, in the document's coordinates
|
|
106
|
-
* too (`lastLineDocumentRect`), so a host places its UI after them
|
|
106
|
+
* too (`lastLineDocumentRect`), so a host places its UI after them;
|
|
107
|
+
* - the selection followed (P138): what the last `selected` reported (the element picked, or the
|
|
108
|
+
* words selected) is kept, and while the host follows it (`track` with `selection`) it is drawn
|
|
109
|
+
* in the layer and its boxes are reported as a followed mark's are (`selectionTracked`), with
|
|
110
|
+
* whether it is in view, or that it is gone; it takes no pointer, no focus and no key.
|
|
107
111
|
*
|
|
108
112
|
* It shares the realm with the content, which can interfere with all of it: the host takes its
|
|
109
113
|
* reports as UI hints only.
|
|
@@ -124,6 +128,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
124
128
|
activated: "porthole/annotate.activated",
|
|
125
129
|
track: "porthole/annotate.track",
|
|
126
130
|
tracked: "porthole/annotate.tracked",
|
|
131
|
+
selectionTracked: "porthole/annotate.selectionTracked",
|
|
127
132
|
clearSelection: "porthole/annotate.clearSelection",
|
|
128
133
|
focusMark: "porthole/annotate.focusMark",
|
|
129
134
|
};
|
|
@@ -142,6 +147,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
142
147
|
const elementRect = Element.prototype.getBoundingClientRect;
|
|
143
148
|
const rangeRect = Range.prototype.getBoundingClientRect;
|
|
144
149
|
const rangeRects = Range.prototype.getClientRects;
|
|
150
|
+
const cloneRange = Range.prototype.cloneRange;
|
|
145
151
|
const setStart = Range.prototype.setStart;
|
|
146
152
|
const setStartBefore = Range.prototype.setStartBefore;
|
|
147
153
|
const compareBoundaryPoints = Range.prototype.compareBoundaryPoints;
|
|
@@ -398,7 +404,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
398
404
|
// box of at least 44 by 44 px centred on its own (an invisible ::before; 100% is its padding
|
|
399
405
|
// box, its border 1 px), so a tap a few px off still lands on the shell's layer. A marker is
|
|
400
406
|
// a real button (P133): what a browser gives one is taken off, a ring says it has the focus.
|
|
401
|
-
|
|
407
|
+
// The selection the host follows (P138) is drawn as what is picked is: an element in the
|
|
408
|
+
// picking outline, a little lighter and without its name; words with a light fill and a line
|
|
409
|
+
// under them, in the same blue, apart from the marks' yellow (no comment is there yet).
|
|
410
|
+
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}";
|
|
402
411
|
// Inline and important: the content's own style sheets can't hide, shrink or move it by
|
|
403
412
|
// accident. Set again at each draw, since its scripts can rewrite it (narrowing only: the
|
|
404
413
|
// content can still cover the layer, or move it with its ancestors, P104). Clipped, where an
|
|
@@ -424,6 +433,31 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
424
433
|
|
|
425
434
|
let mode = { elements: false, text: false, hold: false };
|
|
426
435
|
let hover = null;
|
|
436
|
+
// The selection last reported as selected (P138): its anchor, and what it is in the page (the
|
|
437
|
+
// element picked, or a copy of the selection's range, which the page's changes keep up to
|
|
438
|
+
// date and which stays when the page's own selection goes). Followed while the host asks
|
|
439
|
+
// (track with selection), and drawn then. Each new selected replaces it.
|
|
440
|
+
let held = null;
|
|
441
|
+
let followingSelection = false;
|
|
442
|
+
// What the host was last told of it: "attached", "orphaned", or null (nothing yet).
|
|
443
|
+
let heldTold = null;
|
|
444
|
+
const heldGone = (found) => (found.range ? found.range.collapsed || !found.range.startContainer.isConnected : !found.element.isConnected);
|
|
445
|
+
const heldShown = () => followingSelection && held !== null && heldTold !== "orphaned" && !heldGone(held.found);
|
|
446
|
+
// The element just picked (P138, Tenny's review): it keeps its outline after selected, so
|
|
447
|
+
// there is no gap before the host follows it, and the follow's highlight takes over where it
|
|
448
|
+
// does. Without a follow (an older host) it ends as a selection does: the next pick or
|
|
449
|
+
// selection, the host's clearSelection, a mode started or stopped, clear, Escape, or the
|
|
450
|
+
// element leaving the page. Not unselected: a selection made after the pick has already
|
|
451
|
+
// ended it as it was reported, so the one unselected can clear is one from before, which
|
|
452
|
+
// the pick's own click takes away when text is selected too.
|
|
453
|
+
let picked = null;
|
|
454
|
+
const endPick = () => {
|
|
455
|
+
if (picked !== null) {
|
|
456
|
+
picked = null;
|
|
457
|
+
redraw();
|
|
458
|
+
}
|
|
459
|
+
};
|
|
460
|
+
const pickShown = () => picked !== null && !followingSelection && picked.isConnected;
|
|
427
461
|
let marks = [];
|
|
428
462
|
// The markers as last drawn, for a click to find: { id, element }. Each mark keeps its
|
|
429
463
|
// marker's node across draws, so a press that spans a redraw ends on the node it began on.
|
|
@@ -814,7 +848,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
814
848
|
return boxes;
|
|
815
849
|
};
|
|
816
850
|
const draw = () => {
|
|
817
|
-
if (marks.length === 0 && hover === null && layer === null) {
|
|
851
|
+
if (marks.length === 0 && hover === null && layer === null && !heldShown() && !pickShown()) {
|
|
818
852
|
return;
|
|
819
853
|
}
|
|
820
854
|
const root = ensureLayer();
|
|
@@ -909,6 +943,24 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
909
943
|
}
|
|
910
944
|
}
|
|
911
945
|
const outlines = [];
|
|
946
|
+
// The followed selection (P138), under the picking outline: no pointer, no focus, no name;
|
|
947
|
+
// before the host follows it, the element just picked, drawn the same way.
|
|
948
|
+
if (picked !== null && !picked.isConnected) {
|
|
949
|
+
picked = null;
|
|
950
|
+
}
|
|
951
|
+
const lit = heldShown() ? held.found : pickShown() ? { element: picked } : null;
|
|
952
|
+
if (lit !== null) {
|
|
953
|
+
const rects = lit.range ? Array.from(rangeRects.call(lit.range)).slice(0, LIMIT.boxes) : [elementRect.call(lit.element)];
|
|
954
|
+
for (const rect of rects) {
|
|
955
|
+
if (rect.width === 0 && rect.height === 0) {
|
|
956
|
+
continue;
|
|
957
|
+
}
|
|
958
|
+
const each = createElement.call(document, "div");
|
|
959
|
+
each.className = lit.range ? "held text" : "held";
|
|
960
|
+
each.style.cssText = "left:" + rect.left + "px;top:" + rect.top + "px;width:" + rect.width + "px;height:" + rect.height + "px";
|
|
961
|
+
outlines.push(each);
|
|
962
|
+
}
|
|
963
|
+
}
|
|
912
964
|
if (hover !== null && hover.isConnected) {
|
|
913
965
|
const rect = elementRect.call(hover);
|
|
914
966
|
const outline = createElement.call(document, "div");
|
|
@@ -954,9 +1006,17 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
954
1006
|
let trackedBox = null;
|
|
955
1007
|
let trackedAt = 0;
|
|
956
1008
|
let trackFrame = 0;
|
|
1009
|
+
// The followed selection's viewport as last told (P138): a frame made smaller can leave it
|
|
1010
|
+
// out of view without moving it.
|
|
1011
|
+
let trackedView = null;
|
|
957
1012
|
const trackTick = () => {
|
|
958
1013
|
trackFrame = 0;
|
|
959
|
-
if (tracking === null) {
|
|
1014
|
+
if (tracking === null && !followingSelection) {
|
|
1015
|
+
return;
|
|
1016
|
+
}
|
|
1017
|
+
if (followingSelection) {
|
|
1018
|
+
followHeld();
|
|
1019
|
+
trackFrame = nextFrame(trackTick);
|
|
960
1020
|
return;
|
|
961
1021
|
}
|
|
962
1022
|
const mark = marks.find((each) => each.id === tracking);
|
|
@@ -975,12 +1035,79 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
975
1035
|
}
|
|
976
1036
|
trackFrame = nextFrame(trackTick);
|
|
977
1037
|
};
|
|
978
|
-
|
|
1038
|
+
// The followed selection (P138), as a followed mark is, and on its clock: where it is at each
|
|
1039
|
+
// animation frame where it moved, or the viewport changed size, with whether any of it is in
|
|
1040
|
+
// the viewport; orphaned once while it isn't in the page (a page that took the element out,
|
|
1041
|
+
// a re-render, the words gone), found again by its anchor at most twice a second meanwhile.
|
|
1042
|
+
// Geometry only: its anchor and words went with selected. Reads boxes, nothing else: no
|
|
1043
|
+
// focus, no selection, no listener.
|
|
1044
|
+
const followHeld = () => {
|
|
1045
|
+
const now = performance.now();
|
|
1046
|
+
if (held !== null && heldGone(held.found) && now - held.tried >= 500) {
|
|
1047
|
+
held.tried = now;
|
|
1048
|
+
let found = null;
|
|
1049
|
+
try {
|
|
1050
|
+
found = find(held.anchor, textIndex());
|
|
1051
|
+
} catch (_) {
|
|
1052
|
+
found = null;
|
|
1053
|
+
}
|
|
1054
|
+
if (found !== null && !heldGone(found)) {
|
|
1055
|
+
held.found = found;
|
|
1056
|
+
}
|
|
1057
|
+
}
|
|
1058
|
+
if (held === null || heldGone(held.found)) {
|
|
1059
|
+
if (heldTold !== "orphaned") {
|
|
1060
|
+
heldTold = "orphaned";
|
|
1061
|
+
trackedBox = null;
|
|
1062
|
+
tell(M.selectionTracked, { state: "orphaned" });
|
|
1063
|
+
redraw();
|
|
1064
|
+
}
|
|
1065
|
+
return;
|
|
1066
|
+
}
|
|
1067
|
+
const rect = box(rectOf(held.found));
|
|
1068
|
+
const root = document.documentElement;
|
|
1069
|
+
const view = { width: root ? root.clientWidth : 0, height: root ? root.clientHeight : 0 };
|
|
1070
|
+
const resized = trackedView === null || trackedView.width !== view.width || trackedView.height !== view.height;
|
|
1071
|
+
if ((heldTold !== "attached" || resized || apart(trackedBox, rect)) && now - trackedAt >= 16) {
|
|
1072
|
+
heldTold = "attached";
|
|
1073
|
+
trackedBox = rect;
|
|
1074
|
+
trackedView = view;
|
|
1075
|
+
trackedAt = now;
|
|
1076
|
+
const scroll = scrollOf();
|
|
1077
|
+
const lastLineDocumentRect = lastLineOf(held.found, scroll);
|
|
1078
|
+
const inView = rect.x < view.width && rect.x + rect.width > 0 && rect.y < view.height && rect.y + rect.height > 0;
|
|
1079
|
+
tell(M.selectionTracked, Object.assign({ state: "attached", rect, documentRect: inDocument(rect, scroll), scroll, inView }, lastLineDocumentRect === null ? {} : { lastLineDocumentRect }));
|
|
1080
|
+
// The highlight goes with it (a layout change moves it without a scroll).
|
|
1081
|
+
redraw();
|
|
1082
|
+
}
|
|
1083
|
+
};
|
|
1084
|
+
// A mark, the selection (P138), or nothing: one at a time, each replacing the last.
|
|
1085
|
+
const track = (id, selection) => {
|
|
1086
|
+
const was = heldShown() || pickShown();
|
|
979
1087
|
tracking = typeof id === "string" ? id : null;
|
|
1088
|
+
followingSelection = tracking === null && selection === true;
|
|
1089
|
+
// The follow's highlight takes the pick's outline over, in this draw (Tenny's review).
|
|
1090
|
+
if (followingSelection) {
|
|
1091
|
+
picked = null;
|
|
1092
|
+
}
|
|
980
1093
|
trackedBox = null;
|
|
981
|
-
|
|
1094
|
+
trackedView = null;
|
|
1095
|
+
heldTold = null;
|
|
1096
|
+
if ((tracking !== null || followingSelection) && trackFrame === 0) {
|
|
982
1097
|
trackFrame = nextFrame(trackTick);
|
|
983
1098
|
}
|
|
1099
|
+
if (heldShown() || pickShown() || was) {
|
|
1100
|
+
draw();
|
|
1101
|
+
}
|
|
1102
|
+
};
|
|
1103
|
+
// A new selected (P138): what is followed, if the selection is, from the next frame on.
|
|
1104
|
+
const holdSelected = (anchor, found) => {
|
|
1105
|
+
held = { anchor, found, tried: 0 };
|
|
1106
|
+
if (followingSelection) {
|
|
1107
|
+
trackedBox = null;
|
|
1108
|
+
heldTold = null;
|
|
1109
|
+
redraw();
|
|
1110
|
+
}
|
|
984
1111
|
};
|
|
985
1112
|
|
|
986
1113
|
// Where each found mark starts in the document, in order (P112): its place in a list the host
|
|
@@ -1183,9 +1310,11 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1183
1310
|
sent += 1;
|
|
1184
1311
|
}
|
|
1185
1312
|
}
|
|
1313
|
+
// Not while the host follows the selection (P138, Tenny's review): its reports carry where
|
|
1314
|
+
// it is; a scroll after the following ends is re-sent as before.
|
|
1186
1315
|
if (selectionScrolled) {
|
|
1187
1316
|
selectionScrolled = false;
|
|
1188
|
-
if (reportSelection(true)) {
|
|
1317
|
+
if (!followingSelection && reportSelection(true)) {
|
|
1189
1318
|
sent += 1;
|
|
1190
1319
|
}
|
|
1191
1320
|
}
|
|
@@ -1455,6 +1584,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1455
1584
|
const stop = () => {
|
|
1456
1585
|
mode = { elements: false, text: false };
|
|
1457
1586
|
hover = null;
|
|
1587
|
+
picked = null;
|
|
1458
1588
|
reported = null;
|
|
1459
1589
|
reportedBox = null;
|
|
1460
1590
|
setCursor(false);
|
|
@@ -1522,6 +1652,9 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1522
1652
|
return;
|
|
1523
1653
|
}
|
|
1524
1654
|
swallowUntil = performance.now() + 2000;
|
|
1655
|
+
holdSelected(anchor, { element });
|
|
1656
|
+
picked = followingSelection ? null : element;
|
|
1657
|
+
redraw();
|
|
1525
1658
|
tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
|
|
1526
1659
|
}, HOLD_MS),
|
|
1527
1660
|
};
|
|
@@ -1569,6 +1702,9 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1569
1702
|
mode = { elements: false, text: mode.text };
|
|
1570
1703
|
hover = null;
|
|
1571
1704
|
setCursor(false);
|
|
1705
|
+
holdSelected(anchor, { element });
|
|
1706
|
+
// Its outline stays (P138), now without its name, until the host follows it or it ends.
|
|
1707
|
+
picked = followingSelection ? null : element;
|
|
1572
1708
|
draw();
|
|
1573
1709
|
tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
|
|
1574
1710
|
}, true);
|
|
@@ -1576,6 +1712,8 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1576
1712
|
if (event.key !== "Escape") {
|
|
1577
1713
|
return;
|
|
1578
1714
|
}
|
|
1715
|
+
// The person wants out: a pick's outline goes (P138). The key is untouched by it.
|
|
1716
|
+
endPick();
|
|
1579
1717
|
if (mode.elements) {
|
|
1580
1718
|
event.preventDefault();
|
|
1581
1719
|
event.stopImmediatePropagation();
|
|
@@ -1629,6 +1767,8 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1629
1767
|
}
|
|
1630
1768
|
reported = key;
|
|
1631
1769
|
reportedBox = rect;
|
|
1770
|
+
holdSelected(anchor, { range: cloneRange.call(range) });
|
|
1771
|
+
endPick();
|
|
1632
1772
|
tell(M.selected, Object.assign({ anchor, rect }, placeOf({ range })));
|
|
1633
1773
|
return true;
|
|
1634
1774
|
};
|
|
@@ -1639,6 +1779,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1639
1779
|
}
|
|
1640
1780
|
});
|
|
1641
1781
|
window.addEventListener("scroll", () => {
|
|
1782
|
+
// Not while the host follows the selection (P138, Tenny's review).
|
|
1783
|
+
if (followingSelection) {
|
|
1784
|
+
return;
|
|
1785
|
+
}
|
|
1642
1786
|
if (reported !== null) {
|
|
1643
1787
|
selectionScrolled = true;
|
|
1644
1788
|
settle();
|
|
@@ -1658,6 +1802,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1658
1802
|
case M.start:
|
|
1659
1803
|
mode = { elements: params.elements === true, text: params.text === true, hold: params.elements === "hold" };
|
|
1660
1804
|
hover = null;
|
|
1805
|
+
picked = null;
|
|
1661
1806
|
reported = null;
|
|
1662
1807
|
reportedBox = null;
|
|
1663
1808
|
setCursor(mode.elements);
|
|
@@ -1689,18 +1834,19 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1689
1834
|
focus(String(params.id));
|
|
1690
1835
|
break;
|
|
1691
1836
|
case M.track:
|
|
1692
|
-
track(params.id);
|
|
1837
|
+
track(params.id, params.selection === true);
|
|
1693
1838
|
break;
|
|
1694
1839
|
case M.clearSelection: {
|
|
1695
1840
|
// The host used the person's selection (P115): it goes, and with it what the shell
|
|
1696
1841
|
// held of it (a report waiting to settle, the one last told, a scroll's follow-up), so
|
|
1697
1842
|
// nothing is told back: the host knows, and the selectionchange this makes finds
|
|
1698
|
-
// nothing to report. Marks, a pick and the mode stay as they are
|
|
1699
|
-
// selected, nothing changes.
|
|
1843
|
+
// nothing to report. Marks, a pick and the mode stay as they are, but a pick's outline
|
|
1844
|
+
// goes (P138). With nothing selected, nothing changes.
|
|
1700
1845
|
cancelLater(selectionTimer);
|
|
1701
1846
|
selectionTimer = 0;
|
|
1702
1847
|
reported = null;
|
|
1703
1848
|
reportedBox = null;
|
|
1849
|
+
endPick();
|
|
1704
1850
|
selectionScrolled = false;
|
|
1705
1851
|
const selection = selectionOf.call(document);
|
|
1706
1852
|
if (selection !== null) {
|
|
@@ -1713,6 +1859,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1713
1859
|
break;
|
|
1714
1860
|
case M.clear:
|
|
1715
1861
|
track(null);
|
|
1862
|
+
picked = null;
|
|
1716
1863
|
pendingFocus = null;
|
|
1717
1864
|
pendingMarker = null;
|
|
1718
1865
|
marks = [];
|