@botiverse/porthole 0.14.14 → 0.14.16
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +58 -0
- package/dist/annotate/types.d.ts +50 -1
- package/dist/annotate/types.js +7 -1
- package/dist/annotate/validate.d.ts +26 -3
- package/dist/annotate/validate.js +64 -2
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +56 -6
- package/dist/host/types.d.ts +24 -3
- package/dist/index.d.ts +1 -1
- package/dist/react/frame.d.ts +20 -1
- package/dist/react/frame.js +59 -26
- package/dist/shell/annotate.d.ts +8 -2
- package/dist/shell/annotate.js +178 -11
- package/dist/shell/runtime.d.ts +10 -0
- package/dist/shell/runtime.js +72 -26
- package/docs/ADOPTING.md +50 -1
- package/docs/DECISIONS.md +370 -4
- package/docs/DESIGN.md +37 -6
- package/docs/THREAT_MODEL.md +32 -5
- package/package.json +1 -1
- package/src/annotate/types.ts +47 -1
- package/src/annotate/validate.ts +82 -3
- package/src/host/create-host.ts +59 -11
- package/src/host/types.ts +29 -3
- package/src/index.ts +1 -0
- package/src/react/frame.tsx +91 -33
- package/src/shell/annotate.ts +178 -11
- package/src/shell/runtime.ts +73 -26
package/src/annotate/types.ts
CHANGED
|
@@ -84,8 +84,24 @@ export interface AnnotateMode {
|
|
|
84
84
|
readonly elements?: boolean | "hold";
|
|
85
85
|
/** Text, by selecting it: each settled selection is reported, and its clearing. */
|
|
86
86
|
readonly text?: boolean;
|
|
87
|
+
/**
|
|
88
|
+
* That you follow what is selected (P140): `annotations.track({ selection: true })` once
|
|
89
|
+
* `selected` comes (React sets it while `trackedSelection` is given). Only then does the frame
|
|
90
|
+
* keep it for you to follow, the element just picked outlined until the follow takes over. Without
|
|
91
|
+
* it the frame keeps nothing and a pick's outline goes with the pick, as before 0.14.15; a follow
|
|
92
|
+
* asked before the pick still follows each selection reported while it lasts.
|
|
93
|
+
*/
|
|
94
|
+
readonly keepSelection?: boolean;
|
|
87
95
|
}
|
|
88
96
|
|
|
97
|
+
/**
|
|
98
|
+
* What `annotations.track` follows (P112, P138): a shown mark, by its id; the selection the frame
|
|
99
|
+
* last reported as `selected` (the element picked, or the words selected), highlighted in the
|
|
100
|
+
* frame while followed, and kept for a follow asked after `selected` only under `start`'s
|
|
101
|
+
* `keepSelection` (P140); or nothing (`null`). One at a time: each replaces the last.
|
|
102
|
+
*/
|
|
103
|
+
export type AnnotationTrackTarget = string | { readonly selection: true } | null;
|
|
104
|
+
|
|
89
105
|
/**
|
|
90
106
|
* An anchor the host marks in the frame, under its own id. Everything here is sent into the
|
|
91
107
|
* frame, so the content can read it: give ids that say nothing (never a person's name or the
|
|
@@ -209,6 +225,30 @@ export type AnnotationReport =
|
|
|
209
225
|
readonly lastLineDocumentRect?: AnnotationRect;
|
|
210
226
|
readonly scroll?: AnnotationScroll;
|
|
211
227
|
}
|
|
228
|
+
/**
|
|
229
|
+
* Where the selection the host follows is (`annotations.track({ selection: true })`, P138): the
|
|
230
|
+
* element picked or the words selected, as the last `selected` reported them, at an animation
|
|
231
|
+
* frame where it moved or the frame's viewport changed size; at most 60 a second, together with
|
|
232
|
+
* `tracked` (one followed thing at a time). The same boxes as `tracked`'s: `rect` clamped to the
|
|
233
|
+
* frame, `documentRect` and `lastLineDocumentRect` in the document and unclamped, the `scroll`
|
|
234
|
+
* they were read at, always there. `inView`: whether any of it is inside the frame's viewport
|
|
235
|
+
* (false where the shell says so, or where `rect` lies wholly outside the viewport as the host
|
|
236
|
+
* reads it); hide UI attached to it while false. `orphaned`: it isn't in the page now (taken out,
|
|
237
|
+
* its words gone; or the frame has no selection, a new frame after a reload); `attached` again if
|
|
238
|
+
* it is found again by its anchor. The first report comes at the frame's next animation frame
|
|
239
|
+
* after the host asks, which is how a host tells a shell that follows a selection (an older one
|
|
240
|
+
* sends none). Geometry only, as `tracked`: no anchor, no words. The content's word.
|
|
241
|
+
*/
|
|
242
|
+
| {
|
|
243
|
+
readonly type: "selectionTracked";
|
|
244
|
+
readonly state: "attached";
|
|
245
|
+
readonly rect: AnnotationRect;
|
|
246
|
+
readonly documentRect: AnnotationRect;
|
|
247
|
+
readonly lastLineDocumentRect?: AnnotationRect;
|
|
248
|
+
readonly scroll: AnnotationScroll;
|
|
249
|
+
readonly inView: boolean;
|
|
250
|
+
}
|
|
251
|
+
| { readonly type: "selectionTracked"; readonly state: "orphaned" }
|
|
212
252
|
/**
|
|
213
253
|
* The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
|
|
214
254
|
* (P107), or pressed Enter or Space on it (P133); `rect` is the marker's box, to open the host's
|
|
@@ -237,10 +277,16 @@ export const ANNOTATE_METHODS = {
|
|
|
237
277
|
anchored: "porthole/annotate.anchored",
|
|
238
278
|
/** Frame → host: a mark's marker was clicked, or pressed from the keyboard (P104, P133). */
|
|
239
279
|
activated: "porthole/annotate.activated",
|
|
240
|
-
/**
|
|
280
|
+
/**
|
|
281
|
+
* Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112), or the
|
|
282
|
+
* selection last reported, highlighted while followed (`{ id: null, selection: true }`, P138: an
|
|
283
|
+
* older shell reads it as none).
|
|
284
|
+
*/
|
|
241
285
|
track: "porthole/annotate.track",
|
|
242
286
|
/** Frame → host: the followed mark's box, as it moves (P112). */
|
|
243
287
|
tracked: "porthole/annotate.tracked",
|
|
288
|
+
/** Frame → host: where the followed selection is, as it moves (P138). */
|
|
289
|
+
selectionTracked: "porthole/annotate.selectionTracked",
|
|
244
290
|
/** Host → frame: take the page's text selection away, telling nothing back (P115). */
|
|
245
291
|
clearSelection: "porthole/annotate.clearSelection",
|
|
246
292
|
/**
|
package/src/annotate/validate.ts
CHANGED
|
@@ -8,6 +8,7 @@ import {
|
|
|
8
8
|
type AnnotationReport,
|
|
9
9
|
type AnnotationScroll,
|
|
10
10
|
type AnnotationSelector,
|
|
11
|
+
type AnnotationTrackTarget,
|
|
11
12
|
} from "./types.ts";
|
|
12
13
|
import { withoutUnseen } from "../bridge/unseen.ts";
|
|
13
14
|
|
|
@@ -145,6 +146,25 @@ export function clampRect(
|
|
|
145
146
|
return { x: left, y: top, width: right - left, height: bottom - top };
|
|
146
147
|
}
|
|
147
148
|
|
|
149
|
+
/**
|
|
150
|
+
* Whether a box the frame reported overlaps the frame's viewport (P138), before it is clamped: a
|
|
151
|
+
* box of no width or height counts where it lies strictly inside. Where the viewport isn't known,
|
|
152
|
+
* nothing is in it, as `clampRect` puts every box at the corner then.
|
|
153
|
+
*/
|
|
154
|
+
export function inViewport(
|
|
155
|
+
rect: AnnotationRect,
|
|
156
|
+
viewport: { readonly width: number; readonly height: number } | null | undefined,
|
|
157
|
+
): boolean {
|
|
158
|
+
if (viewport === null || typeof viewport !== "object") {
|
|
159
|
+
return false;
|
|
160
|
+
}
|
|
161
|
+
const { width, height } = viewport;
|
|
162
|
+
if (!Number.isFinite(width) || !Number.isFinite(height)) {
|
|
163
|
+
return false;
|
|
164
|
+
}
|
|
165
|
+
return rect.x < width && rect.x + rect.width > 0 && rect.y < height && rect.y + rect.height > 0;
|
|
166
|
+
}
|
|
167
|
+
|
|
148
168
|
const markId = (value: unknown): value is string => text(value, LIMITS.id, 1);
|
|
149
169
|
|
|
150
170
|
function results(value: unknown): AnchorResult[] | null {
|
|
@@ -280,15 +300,58 @@ export function parseReport(value: unknown): AnnotationReport | null {
|
|
|
280
300
|
...(scroll === undefined ? {} : { scroll }),
|
|
281
301
|
};
|
|
282
302
|
}
|
|
303
|
+
case "selectionTracked": {
|
|
304
|
+
// The followed selection (P138): gone, or where it is. New with its shell, so every box but
|
|
305
|
+
// the last line, and the scroll, are there; nothing about the page's words is.
|
|
306
|
+
if (value.state === "orphaned") {
|
|
307
|
+
return { type: "selectionTracked", state: "orphaned" };
|
|
308
|
+
}
|
|
309
|
+
if (value.state !== "attached" || typeof value.inView !== "boolean") {
|
|
310
|
+
return null;
|
|
311
|
+
}
|
|
312
|
+
const rect = parseRect(value.rect);
|
|
313
|
+
const documentRect = parseRect(value.documentRect);
|
|
314
|
+
const scroll = parseScroll(value.scroll);
|
|
315
|
+
const lastLineDocumentRect =
|
|
316
|
+
value.lastLineDocumentRect === undefined
|
|
317
|
+
? undefined
|
|
318
|
+
: parseRect(value.lastLineDocumentRect);
|
|
319
|
+
if (
|
|
320
|
+
rect === null ||
|
|
321
|
+
documentRect === null ||
|
|
322
|
+
scroll === null ||
|
|
323
|
+
lastLineDocumentRect === null
|
|
324
|
+
) {
|
|
325
|
+
return null;
|
|
326
|
+
}
|
|
327
|
+
return {
|
|
328
|
+
type: "selectionTracked",
|
|
329
|
+
state: "attached",
|
|
330
|
+
rect,
|
|
331
|
+
documentRect,
|
|
332
|
+
...(lastLineDocumentRect === undefined ? {} : { lastLineDocumentRect }),
|
|
333
|
+
scroll,
|
|
334
|
+
inView: value.inView,
|
|
335
|
+
};
|
|
336
|
+
}
|
|
283
337
|
default:
|
|
284
338
|
return null;
|
|
285
339
|
}
|
|
286
340
|
}
|
|
287
341
|
|
|
288
|
-
/**
|
|
289
|
-
export
|
|
342
|
+
/** A mode as the frame gets it: `keepSelection` only where it is true (P140). */
|
|
343
|
+
export type StartedMode = Required<Omit<AnnotateMode, "keepSelection">> & {
|
|
344
|
+
readonly keepSelection?: true;
|
|
345
|
+
};
|
|
346
|
+
|
|
347
|
+
/**
|
|
348
|
+
* What the host may start with: elements, text, or both (default both); and whether it follows
|
|
349
|
+
* what is selected (`keepSelection`, P140).
|
|
350
|
+
*/
|
|
351
|
+
export function annotateMode(mode: AnnotateMode | undefined): StartedMode {
|
|
290
352
|
const elements = mode?.elements ?? true;
|
|
291
353
|
const words = mode?.text ?? true;
|
|
354
|
+
const keep = mode?.keepSelection ?? false;
|
|
292
355
|
if (
|
|
293
356
|
(typeof elements !== "boolean" && elements !== "hold") ||
|
|
294
357
|
typeof words !== "boolean" ||
|
|
@@ -296,7 +359,10 @@ export function annotateMode(mode: AnnotateMode | undefined): Required<AnnotateM
|
|
|
296
359
|
) {
|
|
297
360
|
throw new TypeError("annotations.start: elements, text, or both");
|
|
298
361
|
}
|
|
299
|
-
|
|
362
|
+
if (typeof keep !== "boolean") {
|
|
363
|
+
throw new TypeError("annotations.start: keepSelection is true or false");
|
|
364
|
+
}
|
|
365
|
+
return { elements, text: words, ...(keep ? { keepSelection: true } : {}) };
|
|
300
366
|
}
|
|
301
367
|
|
|
302
368
|
/**
|
|
@@ -345,3 +411,16 @@ export function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[] {
|
|
|
345
411
|
};
|
|
346
412
|
});
|
|
347
413
|
}
|
|
414
|
+
|
|
415
|
+
/**
|
|
416
|
+
* Whether what `annotations.track` is given names the selection (P138): an object whose own
|
|
417
|
+
* `selection` is `true`, and nothing else does (a mark's id is a string).
|
|
418
|
+
*/
|
|
419
|
+
export const followsSelection = (
|
|
420
|
+
target: AnnotationTrackTarget | undefined,
|
|
421
|
+
): target is { readonly selection: true } =>
|
|
422
|
+
typeof target === "object" &&
|
|
423
|
+
target !== null &&
|
|
424
|
+
Object.hasOwn(target, "selection") &&
|
|
425
|
+
// A caller's word, untyped as JavaScript passes it: `true` and nothing else.
|
|
426
|
+
(target as { readonly selection?: unknown }).selection === true;
|
package/src/host/create-host.ts
CHANGED
|
@@ -1,15 +1,13 @@
|
|
|
1
|
-
import {
|
|
2
|
-
ANNOTATE_METHODS,
|
|
3
|
-
type AnnotateMode,
|
|
4
|
-
type AnnotationMark,
|
|
5
|
-
type AnnotationReport,
|
|
6
|
-
} from "../annotate/types.ts";
|
|
1
|
+
import { ANNOTATE_METHODS, type AnnotationMark, type AnnotationReport } from "../annotate/types.ts";
|
|
7
2
|
import {
|
|
8
3
|
annotateMode,
|
|
9
4
|
checkMarks,
|
|
10
5
|
clampRect,
|
|
6
|
+
followsSelection,
|
|
11
7
|
hasMarker,
|
|
8
|
+
inViewport,
|
|
12
9
|
parseReport,
|
|
10
|
+
type StartedMode,
|
|
13
11
|
} from "../annotate/validate.ts";
|
|
14
12
|
import { FIND_LIMITS, FIND_METHODS, type FindReport, type FindResult } from "../find/types.ts";
|
|
15
13
|
import { blankQuery, checkFindQuery, parseFindReport, parseFindResult } from "../find/validate.ts";
|
|
@@ -89,6 +87,7 @@ const REPORTS: Readonly<Record<string, AnnotationReport["type"]>> = {
|
|
|
89
87
|
[ANNOTATE_METHODS.anchored]: "anchored",
|
|
90
88
|
[ANNOTATE_METHODS.activated]: "activated",
|
|
91
89
|
[ANNOTATE_METHODS.tracked]: "tracked",
|
|
90
|
+
[ANNOTATE_METHODS.selectionTracked]: "selectionTracked",
|
|
92
91
|
};
|
|
93
92
|
|
|
94
93
|
/** What the frame says of find in page unasked (P131), by method. */
|
|
@@ -231,11 +230,14 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
231
230
|
const replay = new Map<string, unknown[]>();
|
|
232
231
|
// Annotations: the host's state, given to each frame once it finished its handshake.
|
|
233
232
|
const annotates = config.capabilities.annotate !== undefined;
|
|
234
|
-
let annotating:
|
|
233
|
+
let annotating: StartedMode | null = null;
|
|
235
234
|
let marks: AnnotationMark[] = [];
|
|
236
235
|
let activeMark: string | null = null;
|
|
237
|
-
// The mark the host follows (P112),
|
|
236
|
+
// The mark the host follows (P112), or whether it follows the selection instead (P138), and
|
|
237
|
+
// when it took each `tracked` or `selectionTracked` in the last second: one followed thing
|
|
238
|
+
// at a time, one rate for both.
|
|
238
239
|
let tracking: string | null = null;
|
|
240
|
+
let trackingSelection = false;
|
|
239
241
|
const trackedTimes: number[] = [];
|
|
240
242
|
// Find in page (P131): the query shown (for the content it was asked of only: a new run or
|
|
241
243
|
// other content forgets it), whether the host takes the shortcut (kept for every frame the
|
|
@@ -353,6 +355,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
353
355
|
if (tracking !== null) {
|
|
354
356
|
toFrame(ANNOTATE_METHODS.track, { id: tracking });
|
|
355
357
|
}
|
|
358
|
+
// A new frame has no selection: it answers `orphaned` (P138).
|
|
359
|
+
if (trackingSelection) {
|
|
360
|
+
toFrame(ANNOTATE_METHODS.track, { id: null, selection: true });
|
|
361
|
+
}
|
|
356
362
|
};
|
|
357
363
|
/**
|
|
358
364
|
* The frame's viewport as the platform tells it now; undefined where it can't (no
|
|
@@ -400,6 +406,16 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
400
406
|
case "activated":
|
|
401
407
|
case "tracked":
|
|
402
408
|
return { ...report, rect: clampRect(report.rect, viewport) };
|
|
409
|
+
case "selectionTracked":
|
|
410
|
+
// In view only where the page says so and its box, as the host reads the viewport,
|
|
411
|
+
// reaches into it (P138): a box the clamp puts on an edge is never in view.
|
|
412
|
+
return report.state === "orphaned"
|
|
413
|
+
? report
|
|
414
|
+
: {
|
|
415
|
+
...report,
|
|
416
|
+
rect: clampRect(report.rect, viewport),
|
|
417
|
+
inView: report.inView && inViewport(report.rect, viewport),
|
|
418
|
+
};
|
|
403
419
|
case "anchored":
|
|
404
420
|
return {
|
|
405
421
|
...report,
|
|
@@ -432,6 +448,12 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
432
448
|
if (type === undefined) {
|
|
433
449
|
return;
|
|
434
450
|
}
|
|
451
|
+
// The followed selection (P138) only while the host follows it, and dropped unread
|
|
452
|
+
// otherwise (P140): a host that doesn't follow it takes it as 0.14.14 took a method it
|
|
453
|
+
// didn't know, so a malformed one is no refusal either.
|
|
454
|
+
if (type === "selectionTracked" && !trackingSelection) {
|
|
455
|
+
return;
|
|
456
|
+
}
|
|
435
457
|
let report = parseReport({ ...(isRecord(raw.params) ? raw.params : {}), type });
|
|
436
458
|
if (report === null) {
|
|
437
459
|
void through.call("annotate", null);
|
|
@@ -456,6 +478,20 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
456
478
|
emit("annotation", withinFrame(report));
|
|
457
479
|
return;
|
|
458
480
|
}
|
|
481
|
+
// The followed selection (P138): only while the host follows it (above), on the same 60 a
|
|
482
|
+
// second (one followed thing at a time), past the bridge's rate as the followed mark's.
|
|
483
|
+
if (report.type === "selectionTracked") {
|
|
484
|
+
const at = Date.now();
|
|
485
|
+
while (trackedTimes.length > 0 && at - (trackedTimes[0] as number) >= 1_000) {
|
|
486
|
+
trackedTimes.shift();
|
|
487
|
+
}
|
|
488
|
+
if (trackedTimes.length >= TRACKED_PER_SECOND) {
|
|
489
|
+
return;
|
|
490
|
+
}
|
|
491
|
+
trackedTimes.push(at);
|
|
492
|
+
emit("annotation", withinFrame(report));
|
|
493
|
+
return;
|
|
494
|
+
}
|
|
459
495
|
switch (report.type) {
|
|
460
496
|
case "selected": {
|
|
461
497
|
const kind = report.anchor.kind;
|
|
@@ -467,7 +503,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
467
503
|
}
|
|
468
504
|
// A pick ends with it; holding a block (P112) lasts until the host stops it.
|
|
469
505
|
if (kind === "element" && annotating.elements === true) {
|
|
470
|
-
annotating = annotating.text ? { elements: false
|
|
506
|
+
annotating = annotating.text ? { ...annotating, elements: false } : null;
|
|
471
507
|
}
|
|
472
508
|
break;
|
|
473
509
|
}
|
|
@@ -483,7 +519,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
483
519
|
return;
|
|
484
520
|
}
|
|
485
521
|
if (annotating.elements === true) {
|
|
486
|
-
annotating = annotating.text ? { elements: false
|
|
522
|
+
annotating = annotating.text ? { ...annotating, elements: false } : null;
|
|
487
523
|
}
|
|
488
524
|
break;
|
|
489
525
|
case "anchored": {
|
|
@@ -626,6 +662,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
626
662
|
if (activeMark !== null && !marks.some((mark) => mark.id === activeMark)) {
|
|
627
663
|
activeMark = null;
|
|
628
664
|
}
|
|
665
|
+
// A followed selection (P138) isn't a mark: a show leaves it.
|
|
629
666
|
if (tracking !== null && !marks.some((mark) => mark.id === tracking)) {
|
|
630
667
|
tracking = null;
|
|
631
668
|
toFrame(ANNOTATE_METHODS.track, { id: null });
|
|
@@ -643,12 +680,22 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
643
680
|
activeMark = id;
|
|
644
681
|
toFrame(ANNOTATE_METHODS.focus, { id });
|
|
645
682
|
},
|
|
646
|
-
track(
|
|
683
|
+
track(target) {
|
|
647
684
|
needsAnnotate("track");
|
|
685
|
+
// The selection (P138), under `id: null`: an older shell follows nothing.
|
|
686
|
+
if (followsSelection(target)) {
|
|
687
|
+
tracking = null;
|
|
688
|
+
trackingSelection = true;
|
|
689
|
+
trackedTimes.length = 0;
|
|
690
|
+
toFrame(ANNOTATE_METHODS.track, { id: null, selection: true });
|
|
691
|
+
return;
|
|
692
|
+
}
|
|
693
|
+
const id = target;
|
|
648
694
|
if (id !== null && !marks.some((mark) => mark.id === id)) {
|
|
649
695
|
throw new TypeError(`annotations.track: no mark ${JSON.stringify(id)} is shown`);
|
|
650
696
|
}
|
|
651
697
|
tracking = id;
|
|
698
|
+
trackingSelection = false;
|
|
652
699
|
trackedTimes.length = 0;
|
|
653
700
|
toFrame(ANNOTATE_METHODS.track, { id });
|
|
654
701
|
},
|
|
@@ -657,6 +704,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
657
704
|
marks = [];
|
|
658
705
|
activeMark = null;
|
|
659
706
|
tracking = null;
|
|
707
|
+
trackingSelection = false;
|
|
660
708
|
toFrame(ANNOTATE_METHODS.clear, {});
|
|
661
709
|
},
|
|
662
710
|
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 {
|
|
@@ -295,7 +300,11 @@ export interface FindControls {
|
|
|
295
300
|
* given to every frame the display runs (a reload, a navigation recovered from).
|
|
296
301
|
*/
|
|
297
302
|
export interface AnnotationControls {
|
|
298
|
-
/**
|
|
303
|
+
/**
|
|
304
|
+
* Lets the person point at elements, select text, or both (default both). With
|
|
305
|
+
* `keepSelection: true` (P140) the frame keeps what is selected for `track({ selection: true })`;
|
|
306
|
+
* without it, nothing is kept and a pick's outline goes with the pick.
|
|
307
|
+
*/
|
|
299
308
|
start(mode?: AnnotateMode): void;
|
|
300
309
|
stop(): void;
|
|
301
310
|
/** Marks these anchors (replacing the marks before); the frame reports where they are. */
|
|
@@ -309,8 +318,25 @@ export interface AnnotationControls {
|
|
|
309
318
|
* Throws for an id no shown mark has; a `show` without it, or `clear`, stops it. From a newer
|
|
310
319
|
* shell (P132) each also carries the mark's `documentRect` and the document's `scroll`, so
|
|
311
320
|
* following one mark tells how far the document scrolled, for every mark placed by `documentRect`.
|
|
321
|
+
*
|
|
322
|
+
* `{ selection: true }` (P138) follows the selection the frame last reported as `selected` (the
|
|
323
|
+
* element picked, or the words selected) instead, for a composer that stays beside it: the frame
|
|
324
|
+
* highlights it while it is followed (an element in the outline it had while it was picked) and
|
|
325
|
+
* reports `{ type: "selectionTracked", ... }` with the same boxes as `tracked` and `inView`, or
|
|
326
|
+
* `state: "orphaned"` while it isn't in the page; at most 60 a second together with `tracked`.
|
|
327
|
+
* The frame keeps a selection to follow only for a host that said so at `start`
|
|
328
|
+
* (`keepSelection`, P140), or one that already follows the selection as it is made: without
|
|
329
|
+
* either, a follow asked after `selected` has nothing to follow and answers `orphaned`. A `show`
|
|
330
|
+
* leaves it, and `stop` (or a pick ending) too: it ends with `track(null)`, `track(id)`
|
|
331
|
+
* or `clear` (comment posted, composer dismissed, Escape in it), and the highlight with it. A
|
|
332
|
+
* newer shell answers at its next animation frame; an older one sends nothing (it reads the
|
|
333
|
+
* message as `track(null)`), so until a `selectionTracked` comes, place by `selected`'s boxes.
|
|
334
|
+
* Kept for a frame that runs later, which has no selection: it answers `orphaned`. Under
|
|
335
|
+
* `keepSelection` the element just picked stays outlined until then, so call it before a `start`
|
|
336
|
+
* or `stop` sent with it (a stop ends that outline); while followed, `selected` isn't re-sent
|
|
337
|
+
* after a scroll (Tenny's review).
|
|
312
338
|
*/
|
|
313
|
-
track(
|
|
339
|
+
track(target: AnnotationTrackTarget): void;
|
|
314
340
|
/** Removes every mark. */
|
|
315
341
|
clear(): void;
|
|
316
342
|
/**
|
package/src/index.ts
CHANGED
package/src/react/frame.tsx
CHANGED
|
@@ -680,7 +680,8 @@ export interface PortholeFrameProps {
|
|
|
680
680
|
/**
|
|
681
681
|
* Annotations, where the config declares `annotate` (P053): what the person may point at now
|
|
682
682
|
* (elements, text, or both), or null to stop. A picked element ends element picking: set it
|
|
683
|
-
* again to pick again.
|
|
683
|
+
* again to pick again. `keepSelection` is set for you on a start made while `trackedSelection` is
|
|
684
|
+
* given (P140).
|
|
684
685
|
*/
|
|
685
686
|
readonly annotating?: AnnotateMode | null;
|
|
686
687
|
/**
|
|
@@ -707,6 +708,24 @@ export interface PortholeFrameProps {
|
|
|
707
708
|
* stop the following, as the core's `show` does; it starts again once they have it back.
|
|
708
709
|
*/
|
|
709
710
|
readonly trackedAnnotation?: string | null;
|
|
711
|
+
/**
|
|
712
|
+
* Follow the selection instead (`annotations.track({ selection: true })`, P138): while true, the
|
|
713
|
+
* element the person picked, or the words they selected, as the last `selected` reported them, is
|
|
714
|
+
* highlighted in the frame and `onAnnotation` gets `{ type: "selectionTracked", ... }` as it moves
|
|
715
|
+
* (the boxes `tracked` has, and `inView`; or `state: "orphaned"` while it isn't in the page), for
|
|
716
|
+
* a composer that stays beside it. It takes `trackedAnnotation`'s place while true (one followed
|
|
717
|
+
* thing at a time); false, or leaving it out, ends it and its highlight (the comment posted, the
|
|
718
|
+
* composer dismissed, Escape in it), and `trackedAnnotation`'s mark is followed again. Until a
|
|
719
|
+
* `selectionTracked` comes, place by `selected`'s boxes: an older shell sends none.
|
|
720
|
+
*
|
|
721
|
+
* Give it from the first render, `false` until the composer opens (P140): each start of
|
|
722
|
+
* `annotating` made while it is given carries `keepSelection`, so the frame keeps what is picked
|
|
723
|
+
* or selected (and the picked element outlined) for the follow. It is read as a mode starts:
|
|
724
|
+
* giving it, or leaving it out, later restarts nothing, and counts from the next start. Left out
|
|
725
|
+
* when the mode started, the frame keeps nothing, and a follow asked after the pick has nothing
|
|
726
|
+
* to follow (`orphaned`).
|
|
727
|
+
*/
|
|
728
|
+
readonly trackedSelection?: boolean;
|
|
710
729
|
/** The display's imperative calls (`PortholeFrameHandle`, P118): React 19's `ref` prop. */
|
|
711
730
|
readonly ref?: Ref<PortholeFrameHandle>;
|
|
712
731
|
/**
|
|
@@ -966,9 +985,10 @@ function Mount({
|
|
|
966
985
|
}: MountProps): ReactElement {
|
|
967
986
|
const holder = useRef<HTMLDivElement>(null);
|
|
968
987
|
const handle = useRef<DisplayHandle | null>(null);
|
|
969
|
-
// The mark the display follows now, as the core keeps it (P118), and
|
|
970
|
-
|
|
971
|
-
const
|
|
988
|
+
// The mark the display follows now, or the selection (P138), as the core keeps it (P118), and
|
|
989
|
+
// the props as last seen.
|
|
990
|
+
const following = useRef<Followed>(null);
|
|
991
|
+
const asked = useRef<Followed>(null);
|
|
972
992
|
const [ready, setReady] = useState(false);
|
|
973
993
|
// The height this display started at: later reports don't make it start again.
|
|
974
994
|
const [startHeight] = useState(initialHeightPx);
|
|
@@ -1199,9 +1219,10 @@ function Mount({
|
|
|
1199
1219
|
if (config.capabilities.annotate !== undefined) {
|
|
1200
1220
|
applyAnnotations(display, first);
|
|
1201
1221
|
}
|
|
1202
|
-
// The followed mark, once the marks are shown; without `annotate`, the core's
|
|
1222
|
+
// The followed mark or selection, once the marks are shown; without `annotate`, the core's
|
|
1223
|
+
// error.
|
|
1203
1224
|
following.current = null;
|
|
1204
|
-
const wanted = first
|
|
1225
|
+
const wanted = followedOf(first);
|
|
1205
1226
|
asked.current = wanted;
|
|
1206
1227
|
if (wanted !== null) {
|
|
1207
1228
|
attempt(() => {
|
|
@@ -1279,55 +1300,72 @@ function Mount({
|
|
|
1279
1300
|
: JSON.stringify([focusedAnnotation]);
|
|
1280
1301
|
// By value: the same marks given again don't mark them again.
|
|
1281
1302
|
const annotations = useByValue(frame.annotations);
|
|
1303
|
+
// The mode, by value: what the person may point at, and the host's own `keepSelection`. Not
|
|
1304
|
+
// whether `trackedSelection` is given (P140, Ferryman's review): that is read at each start, so
|
|
1305
|
+
// a composer's prop that appears or goes restarts no mode (which would turn a pick that ended
|
|
1306
|
+
// back on, for the person's next click to pick again).
|
|
1282
1307
|
const mode =
|
|
1283
1308
|
annotating === undefined || annotating === null
|
|
1284
1309
|
? ""
|
|
1285
|
-
: JSON.stringify([
|
|
1286
|
-
|
|
1287
|
-
|
|
1288
|
-
|
|
1289
|
-
|
|
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]);
|
|
1310
|
+
: JSON.stringify([
|
|
1311
|
+
annotating.elements ?? true,
|
|
1312
|
+
annotating.text ?? true,
|
|
1313
|
+
annotating.keepSelection === true,
|
|
1314
|
+
]);
|
|
1300
1315
|
useEffect(() => {
|
|
1301
1316
|
const display = handle.current;
|
|
1302
1317
|
if (annotates && display !== null) {
|
|
1303
1318
|
attempt(() => {
|
|
1304
1319
|
display.annotations.show(annotations ?? []);
|
|
1305
|
-
// A show without the followed mark stops the following (the core's own)
|
|
1306
|
-
|
|
1320
|
+
// A show without the followed mark stops the following (the core's own); the selection
|
|
1321
|
+
// stays followed (P138).
|
|
1322
|
+
if (typeof following.current === "string" && !shown(annotations, following.current)) {
|
|
1307
1323
|
following.current = null;
|
|
1308
1324
|
}
|
|
1309
1325
|
}, latest());
|
|
1310
1326
|
}
|
|
1311
1327
|
}, [annotates, annotations]);
|
|
1312
|
-
// The followed mark follows its
|
|
1313
|
-
|
|
1328
|
+
// The followed mark, or the selection (P138), follows its props (after the marks above, so the
|
|
1329
|
+
// two can change together).
|
|
1330
|
+
const followed = followedOf(frame);
|
|
1314
1331
|
useEffect(() => {
|
|
1315
1332
|
const display = handle.current;
|
|
1316
|
-
const changed =
|
|
1317
|
-
asked.current =
|
|
1318
|
-
if (display === null ||
|
|
1333
|
+
const changed = followed !== asked.current;
|
|
1334
|
+
asked.current = followed;
|
|
1335
|
+
if (display === null || followed === following.current) {
|
|
1319
1336
|
return;
|
|
1320
1337
|
}
|
|
1321
1338
|
// Its mark was taken off (the error, if any, was told when the prop said it): followed again
|
|
1322
1339
|
// once the marks have it back.
|
|
1323
|
-
if (!changed &&
|
|
1340
|
+
if (!changed && typeof followed === "string" && !shown(annotations, followed)) {
|
|
1324
1341
|
return;
|
|
1325
1342
|
}
|
|
1326
1343
|
attempt(() => {
|
|
1327
|
-
display.annotations.track(
|
|
1328
|
-
following.current =
|
|
1344
|
+
display.annotations.track(followed);
|
|
1345
|
+
following.current = followed;
|
|
1329
1346
|
}, latest());
|
|
1330
|
-
}, [
|
|
1347
|
+
}, [followed, annotations]);
|
|
1348
|
+
// The mode follows its prop, after the following above (P138, Tenny's review): a host that
|
|
1349
|
+
// follows the selection and ends picking in one render has the frame follow it first, so the
|
|
1350
|
+
// pick's outline goes straight to the follow's highlight, never through the stop's gap.
|
|
1351
|
+
useEffect(() => {
|
|
1352
|
+
const display = handle.current;
|
|
1353
|
+
if (!annotates || display === null) {
|
|
1354
|
+
return;
|
|
1355
|
+
}
|
|
1356
|
+
const wanted = mode === "" ? null : (JSON.parse(mode) as [boolean | "hold", boolean, boolean]);
|
|
1357
|
+
attempt(
|
|
1358
|
+
() =>
|
|
1359
|
+
wanted === null
|
|
1360
|
+
? display.annotations.stop()
|
|
1361
|
+
: display.annotations.start({
|
|
1362
|
+
elements: wanted[0],
|
|
1363
|
+
text: wanted[1],
|
|
1364
|
+
...(wanted[2] || keepsSelection(latest()) ? { keepSelection: true } : {}),
|
|
1365
|
+
}),
|
|
1366
|
+
latest(),
|
|
1367
|
+
);
|
|
1368
|
+
}, [annotates, mode]);
|
|
1331
1369
|
useEffect(() => {
|
|
1332
1370
|
const display = handle.current;
|
|
1333
1371
|
const id = focusOf(latest().focusedAnnotation);
|
|
@@ -1424,7 +1462,9 @@ function applyAnnotations(display: DisplayHandle, frame: PortholeFrameProps): vo
|
|
|
1424
1462
|
display.annotations.focus(focused);
|
|
1425
1463
|
}
|
|
1426
1464
|
if (frame.annotating !== undefined && frame.annotating !== null) {
|
|
1427
|
-
display.annotations.start(
|
|
1465
|
+
display.annotations.start(
|
|
1466
|
+
keepsSelection(frame) ? { ...frame.annotating, keepSelection: true } : frame.annotating,
|
|
1467
|
+
);
|
|
1428
1468
|
}
|
|
1429
1469
|
}, frame);
|
|
1430
1470
|
}
|
|
@@ -1439,6 +1479,24 @@ function useByValue<T>(value: T): T {
|
|
|
1439
1479
|
return useMemo(() => (key === "" ? undefined : JSON.parse(key)) as T, [key]);
|
|
1440
1480
|
}
|
|
1441
1481
|
|
|
1482
|
+
/**
|
|
1483
|
+
* Whether a start keeps what is selected for a follow (P140): while `trackedSelection` is given
|
|
1484
|
+
* (true or false), or the host's own `keepSelection` says so. Read at each start, never a reason
|
|
1485
|
+
* for one.
|
|
1486
|
+
*/
|
|
1487
|
+
function keepsSelection(frame: PortholeFrameProps): boolean {
|
|
1488
|
+
return frame.annotating?.keepSelection === true || frame.trackedSelection !== undefined;
|
|
1489
|
+
}
|
|
1490
|
+
|
|
1491
|
+
/** What a display follows (P118, P138): a mark's id, the selection (this one object), or nothing. */
|
|
1492
|
+
const SELECTION = Object.freeze({ selection: true } as const);
|
|
1493
|
+
type Followed = string | typeof SELECTION | null;
|
|
1494
|
+
|
|
1495
|
+
/** What the props ask to follow: the selection while `trackedSelection`, else the mark, if any. */
|
|
1496
|
+
function followedOf(frame: PortholeFrameProps): Followed {
|
|
1497
|
+
return frame.trackedSelection === true ? SELECTION : (frame.trackedAnnotation ?? null);
|
|
1498
|
+
}
|
|
1499
|
+
|
|
1442
1500
|
/** Whether `marks` has a mark `id`. */
|
|
1443
1501
|
function shown(marks: readonly AnnotationMark[] | undefined, id: string): boolean {
|
|
1444
1502
|
return (marks ?? []).some((mark) => mark.id === id);
|