@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.
- package/CHANGELOG.md +63 -2
- package/dist/annotate/types.d.ts +47 -4
- package/dist/annotate/types.js +7 -1
- package/dist/annotate/validate.d.ts +17 -1
- package/dist/annotate/validate.js +74 -4
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +52 -4
- package/dist/host/types.d.ts +21 -6
- package/dist/index.d.ts +1 -1
- package/dist/isolation/types.d.ts +6 -0
- package/dist/isolation/types.js +6 -0
- package/dist/platform/web.js +6 -1
- package/dist/react/frame.d.ts +13 -1
- package/dist/react/frame.js +37 -24
- package/dist/shell/annotate.d.ts +18 -4
- package/dist/shell/annotate.js +193 -22
- package/dist/shell/frame.d.ts +6 -1
- package/dist/shell/frame.js +45 -5
- package/docs/ADOPTING.md +69 -15
- package/docs/ARCHITECTURE.md +1 -0
- package/docs/DECISIONS.md +500 -18
- package/docs/DESIGN.md +44 -12
- package/docs/THREAT_MODEL.md +48 -22
- package/package.json +1 -1
- package/src/annotate/types.ts +44 -4
- package/src/annotate/validate.ts +90 -4
- package/src/host/create-host.ts +53 -3
- package/src/host/types.ts +26 -6
- package/src/index.ts +1 -0
- package/src/isolation/types.ts +7 -0
- package/src/platform/web.ts +6 -0
- package/src/react/frame.tsx +59 -31
- package/src/shell/annotate.ts +194 -22
- package/src/shell/frame.ts +45 -5
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() {
|
|
@@ -581,9 +628,10 @@ export function createHost(config, options = {}) {
|
|
|
581
628
|
focusMark(id) {
|
|
582
629
|
// Host → frame only, and kept for no later frame (P134). A mark that has gone, or has no
|
|
583
630
|
// marker, is nothing to ask for, and no fault: the host's card closed with the mark's.
|
|
631
|
+
// Stamped as it is sent: a frame judges by that how old the word is as it takes it (P137).
|
|
584
632
|
needsAnnotate("focusMark");
|
|
585
633
|
if (marks.some((mark) => mark.id === id && hasMarker(mark))) {
|
|
586
|
-
toFrame(ANNOTATE_METHODS.focusMark, { id });
|
|
634
|
+
toFrame(ANNOTATE_METHODS.focusMark, { id, at: Date.now() });
|
|
587
635
|
}
|
|
588
636
|
},
|
|
589
637
|
};
|
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
|
/**
|
|
@@ -338,11 +352,12 @@ export interface AnnotationControls {
|
|
|
338
352
|
*
|
|
339
353
|
* On a calm page it lands at once, from anywhere on the host's page. While the frame is finding
|
|
340
354
|
* its marks (a `show` just sent, the content just changed) it waits, and is then dropped unless
|
|
341
|
-
* the focus is in the frame by then (P135)
|
|
342
|
-
*
|
|
355
|
+
* the focus is in the frame by then (P135). One the frame takes more than 100 ms after you sent
|
|
356
|
+
* it (its page is busy) is held to the same test (P137), so a word that comes late takes no
|
|
357
|
+
* keyboard from a person who moved on. Nothing says it was dropped: if the frame isn't your page's
|
|
343
358
|
* `document.activeElement` soon after and the person hasn't moved on, call `focus()` and then
|
|
344
|
-
* `focusMark(id)` again.
|
|
345
|
-
*
|
|
359
|
+
* `focusMark(id)` again. On a nested page only `focus()` reaches the page (P136): the frame's own
|
|
360
|
+
* `focus()` stops at its shell, and a second call that waits is dropped.
|
|
346
361
|
*/
|
|
347
362
|
focusMark(id: string): void;
|
|
348
363
|
}
|
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";
|
|
@@ -103,6 +103,12 @@ export declare const SHELL_BEAT_METHOD = "porthole/shell/beat";
|
|
|
103
103
|
* that names the ask (`asked`). The host asks as it hears focus move into the frame.
|
|
104
104
|
*/
|
|
105
105
|
export declare const SHELL_LOOK_METHOD = "porthole/shell/look";
|
|
106
|
+
/**
|
|
107
|
+
* The host's word to a nested page's shell (P136) that it moved the focus into the frame: pass it on
|
|
108
|
+
* to the page, in this task, not in the focus event (where the shell's move doesn't take). Sent by
|
|
109
|
+
* `display.focus()` alone; a page has no way to say it.
|
|
110
|
+
*/
|
|
111
|
+
export declare const SHELL_FOCUS_METHOD = "porthole/shell/focus";
|
|
106
112
|
/** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
|
|
107
113
|
export declare const SHELL_METHOD_PREFIX = "porthole/shell/";
|
|
108
114
|
/** A page's word that it used storage, once per load (P111): never a key or a value. */
|
package/dist/isolation/types.js
CHANGED
|
@@ -11,6 +11,12 @@ export const SHELL_BEAT_METHOD = "porthole/shell/beat";
|
|
|
11
11
|
* that names the ask (`asked`). The host asks as it hears focus move into the frame.
|
|
12
12
|
*/
|
|
13
13
|
export const SHELL_LOOK_METHOD = "porthole/shell/look";
|
|
14
|
+
/**
|
|
15
|
+
* The host's word to a nested page's shell (P136) that it moved the focus into the frame: pass it on
|
|
16
|
+
* to the page, in this task, not in the focus event (where the shell's move doesn't take). Sent by
|
|
17
|
+
* `display.focus()` alone; a page has no way to say it.
|
|
18
|
+
*/
|
|
19
|
+
export const SHELL_FOCUS_METHOD = "porthole/shell/focus";
|
|
14
20
|
/** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
|
|
15
21
|
export const SHELL_METHOD_PREFIX = "porthole/shell/";
|
|
16
22
|
/** A page's word that it used storage, once per load (P111): never a key or a value. */
|
package/dist/platform/web.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { DOOR_SANDBOX_TOKENS } from "../compile/policy.js";
|
|
2
|
-
import { SHELL_BEAT_METHOD, SHELL_LOOK_METHOD, SHELL_METHOD_PREFIX, SHELL_STATE_METHOD, } from "../isolation/types.js";
|
|
2
|
+
import { SHELL_BEAT_METHOD, SHELL_FOCUS_METHOD, SHELL_LOOK_METHOD, SHELL_METHOD_PREFIX, SHELL_STATE_METHOD, } from "../isolation/types.js";
|
|
3
3
|
import { postMessageTransport } from "../transport/post-message.js";
|
|
4
4
|
import { focusGuard } from "./focus-guard.js";
|
|
5
5
|
/** A shell's own message (P111), by its namespace. */
|
|
@@ -169,6 +169,11 @@ export const webPlatform = {
|
|
|
169
169
|
},
|
|
170
170
|
focus() {
|
|
171
171
|
guard.focus(frame);
|
|
172
|
+
// A nested page (P136): the move stops at its shell on every engine, one way or another,
|
|
173
|
+
// and only the shell can pass it on. Only a move that landed: the shell asks no more of it.
|
|
174
|
+
if (nested && view.document.activeElement === frame) {
|
|
175
|
+
opened.send({ jsonrpc: "2.0", method: SHELL_FOCUS_METHOD });
|
|
176
|
+
}
|
|
172
177
|
},
|
|
173
178
|
onLoad(listener) {
|
|
174
179
|
loaded.add(listener);
|
package/dist/react/frame.d.ts
CHANGED
|
@@ -159,7 +159,8 @@ export interface PortholeFrameHandle {
|
|
|
159
159
|
* once Escape closed your own view of that mark. Nothing happens for an id with no marker, or
|
|
160
160
|
* while no display runs. A config without `annotate`: `onHostError`, kind `"annotations"`. While
|
|
161
161
|
* the frame is finding its marks it waits, and is dropped unless the focus is in the frame by
|
|
162
|
-
* then (P135): call it again after your own move of
|
|
162
|
+
* then (P135), and so is one a busy page takes late (P137): call it again after your own move of
|
|
163
|
+
* the focus into the frame.
|
|
163
164
|
*/
|
|
164
165
|
focusMark(id: string): void;
|
|
165
166
|
/**
|
|
@@ -337,6 +338,17 @@ export interface PortholeFrameProps {
|
|
|
337
338
|
* stop the following, as the core's `show` does; it starts again once they have it back.
|
|
338
339
|
*/
|
|
339
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;
|
|
340
352
|
/** The display's imperative calls (`PortholeFrameHandle`, P118): React 19's `ref` prop. */
|
|
341
353
|
readonly ref?: Ref<PortholeFrameHandle>;
|
|
342
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
|
@@ -16,6 +16,16 @@ export declare const MARKER_HIT: string;
|
|
|
16
16
|
* `alt`) what follows the tag in the label. An element with neither has no words.
|
|
17
17
|
*/
|
|
18
18
|
export declare const MARKER_NAME: string;
|
|
19
|
+
/**
|
|
20
|
+
* Whether a host's `focusMark` is too old to land unasked (P137): `at` is the host's `Date.now()` as
|
|
21
|
+
* it sent the word, `now` the shell's, kept before content runs. Both read the one wall clock of
|
|
22
|
+
* this machine, the only clock two realms share (`performance.now()` counts from each one's own
|
|
23
|
+
* start). No number is an older host's word, which can't be known fresh. A word from ahead of the
|
|
24
|
+
* clock has the same bound behind it: two processes can read the clock a little apart, and past
|
|
25
|
+
* that the clock was set back, and the age says nothing. Comparisons only, nothing a page can
|
|
26
|
+
* patch, and a word that makes no number (`NaN`, `Infinity`) passes neither test.
|
|
27
|
+
*/
|
|
28
|
+
export declare const WORD_LATE: string;
|
|
19
29
|
/**
|
|
20
30
|
* The shell's annotation runtime (P053), spliced into the shell's runtime (`__ANNOTATE__`) when
|
|
21
31
|
* the config declares `annotate`, so it runs before any content does, with the DOM's own
|
|
@@ -23,7 +33,7 @@ export declare const MARKER_NAME: string;
|
|
|
23
33
|
* in one).
|
|
24
34
|
*
|
|
25
35
|
* The host drives it (`porthole/annotate.start|stop|show|focus|clear|track|clearSelection|focusMark`)
|
|
26
|
-
* and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked`):
|
|
36
|
+
* and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked|selectionTracked`):
|
|
27
37
|
* - picking an element: the element under the pointer (or finger) is outlined with its name; a
|
|
28
38
|
* click or tap picks it, and the content's own handlers never see that click (unless the content
|
|
29
39
|
* patched the DOM's built-ins, P105); Escape cancels (while selecting text too, P112);
|
|
@@ -39,8 +49,8 @@ export declare const MARKER_NAME: string;
|
|
|
39
49
|
* focus on it (P133), is reported (`activated`), and the content's own handlers never see it; a
|
|
40
50
|
* draft is drawn apart, a dashed line and a hollow bubble with no number, and has a marker with
|
|
41
51
|
* or without a count; the host's `focusMark` (P134) puts the focus on a marker that is there, and
|
|
42
|
-
* tells nothing back; one that had to wait for the marks
|
|
43
|
-
* document
|
|
52
|
+
* tells nothing back; one that had to wait for the marks (P135), or that this document took late
|
|
53
|
+
* (P137), lands only if the focus is in this document by then;
|
|
44
54
|
* - following: while a mark has a marker, once a scroll, a resize or a change of the content
|
|
45
55
|
* settles, the marks that moved since the host was last told are reported, at most once a
|
|
46
56
|
* second, so the host's own UI beside a mark can follow;
|
|
@@ -49,7 +59,11 @@ export declare const MARKER_NAME: string;
|
|
|
49
59
|
* followed mark's (`tracked`) too, so a host places marks scrolled out of the frame, and keeps
|
|
50
60
|
* them placed as the document scrolls, from one report and the followed mark's scroll;
|
|
51
61
|
* - the last line (P133): where a selection or a mark's words end, in the document's coordinates
|
|
52
|
-
* 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.
|
|
53
67
|
*
|
|
54
68
|
* It shares the realm with the content, which can interfere with all of it: the host takes its
|
|
55
69
|
* reports as UI hints only.
|