@botiverse/porthole 0.14.9 → 0.14.10
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 +19 -0
- package/dist/annotate/types.d.ts +33 -2
- package/dist/annotate/validate.d.ts +6 -1
- package/dist/annotate/validate.js +31 -3
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +5 -3
- package/dist/host/types.d.ts +3 -1
- package/dist/index.d.ts +2 -2
- package/dist/index.js +1 -1
- package/dist/react/frame.d.ts +2 -1
- package/dist/shell/annotate.d.ts +5 -1
- package/dist/shell/annotate.js +39 -12
- package/docs/ADOPTING.md +29 -0
- package/docs/DECISIONS.md +65 -0
- package/docs/DESIGN.md +15 -2
- package/docs/THREAT_MODEL.md +15 -3
- package/package.json +1 -1
- package/src/annotate/types.ts +43 -4
- package/src/annotate/validate.ts +34 -3
- package/src/host/create-host.ts +5 -3
- package/src/host/types.ts +3 -1
- package/src/index.ts +2 -1
- package/src/react/frame.tsx +2 -1
- package/src/shell/annotate.ts +39 -12
package/dist/host/create-host.js
CHANGED
|
@@ -313,7 +313,9 @@ export function createHost(config, options = {}) {
|
|
|
313
313
|
};
|
|
314
314
|
/**
|
|
315
315
|
* Every box a report carries, clamped to the frame's viewport as it is now (P104): the page
|
|
316
|
-
* places the host's own UI nowhere outside its frame.
|
|
316
|
+
* places the host's own UI nowhere outside its frame. A mark's `documentRect` and the
|
|
317
|
+
* document's `scroll` (P132) pass as they were checked: where a mark is in the document,
|
|
318
|
+
* offscreen too, which a clamp would erase; the host clips what it draws from them.
|
|
317
319
|
*/
|
|
318
320
|
const withinFrame = (report) => {
|
|
319
321
|
const viewport = frameViewport();
|
|
@@ -324,7 +326,7 @@ export function createHost(config, options = {}) {
|
|
|
324
326
|
return { ...report, rect: clampRect(report.rect, viewport) };
|
|
325
327
|
case "anchored":
|
|
326
328
|
return {
|
|
327
|
-
|
|
329
|
+
...report,
|
|
328
330
|
results: report.results.map((result) => result.rect === undefined
|
|
329
331
|
? result
|
|
330
332
|
: { ...result, rect: clampRect(result.rect, viewport) }),
|
|
@@ -408,7 +410,7 @@ export function createHost(config, options = {}) {
|
|
|
408
410
|
if (results.length === 0) {
|
|
409
411
|
return;
|
|
410
412
|
}
|
|
411
|
-
report = {
|
|
413
|
+
report = { ...report, results };
|
|
412
414
|
break;
|
|
413
415
|
}
|
|
414
416
|
case "activated": {
|
package/dist/host/types.d.ts
CHANGED
|
@@ -312,7 +312,9 @@ export interface AnnotationControls {
|
|
|
312
312
|
* Follows one shown mark (P112): while it moves (a scroll, a layout change) the display reports
|
|
313
313
|
* `{ type: "tracked", id, rect }` at most once per animation frame (60 a second), its box clamped
|
|
314
314
|
* to the frame, for that mark only; `null` stops. One at a time: a new id replaces the last.
|
|
315
|
-
* Throws for an id no shown mark has; a `show` without it, or `clear`, stops it.
|
|
315
|
+
* Throws for an id no shown mark has; a `show` without it, or `clear`, stops it. From a newer
|
|
316
|
+
* shell (P132) each also carries the mark's `documentRect` and the document's `scroll`, so
|
|
317
|
+
* following one mark tells how far the document scrolled, for every mark placed by `documentRect`.
|
|
316
318
|
*/
|
|
317
319
|
track(id: string | null): void;
|
|
318
320
|
/** Removes every mark. */
|
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 AnnotationSelector, type CssSelector, type TextPositionSelector, type TextQuoteSelector, } from "./annotate/types.ts";
|
|
51
|
-
export { parseAnchor, parseRect, parseReport } from "./annotate/validate.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";
|
|
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/index.js
CHANGED
|
@@ -52,7 +52,7 @@ export { writeClipboard } from "./host/clipboard.js";
|
|
|
52
52
|
export { httpLocator, LocateError, servedOrOpaque, } from "./host/locator.js";
|
|
53
53
|
// Annotations (P053): anchors, what a frame reports, and the host's checks on both.
|
|
54
54
|
export { ANNOTATE_METHODS, ANNOTATION_LIMITS, } from "./annotate/types.js";
|
|
55
|
-
export { parseAnchor, parseRect, parseReport } from "./annotate/validate.js";
|
|
55
|
+
export { parseAnchor, parseRect, parseReport, parseScroll } from "./annotate/validate.js";
|
|
56
56
|
// Find in page (P131): the host's find bar, the frame's matches, and the host's checks on both.
|
|
57
57
|
export { FIND_LIMITS, FIND_METHODS, } from "./find/types.js";
|
|
58
58
|
export { parseFindReport, parseFindResult } from "./find/validate.js";
|
package/dist/react/frame.d.ts
CHANGED
|
@@ -321,7 +321,8 @@ export interface PortholeFrameProps {
|
|
|
321
321
|
} | null;
|
|
322
322
|
/**
|
|
323
323
|
* The mark to follow (`annotations.track`, P112, P118): while it moves, `onAnnotation` gets
|
|
324
|
-
* `{ type: "tracked", id, rect }` at most once per animation frame, for it alone
|
|
324
|
+
* `{ type: "tracked", id, rect }` at most once per animation frame, for it alone (from a newer
|
|
325
|
+
* shell with its `documentRect` and the document's `scroll`, P132). `null` (or
|
|
325
326
|
* leaving it out once set) stops. By value: given when it changes, and when the display is made.
|
|
326
327
|
* Only a shown mark (`annotations`) is followed: another id, or a config without `annotate`, is
|
|
327
328
|
* `onHostError` (kind `"annotations"`), as the core's call throws. `annotations` without it
|
package/dist/shell/annotate.d.ts
CHANGED
|
@@ -30,7 +30,11 @@ export declare const MARKER_HIT: string;
|
|
|
30
30
|
* bubble with no number, and has a marker with or without a count;
|
|
31
31
|
* - following: while a mark has a marker, once a scroll, a resize or a change of the content
|
|
32
32
|
* settles, the marks that moved since the host was last told are reported, at most once a
|
|
33
|
-
* second, so the host's own UI beside a mark can follow
|
|
33
|
+
* second, so the host's own UI beside a mark can follow;
|
|
34
|
+
* - places in the document (P132): each result's box also in the document's coordinates
|
|
35
|
+
* (`documentRect`), with how far the document was scrolled as it was read (`scroll`), and the
|
|
36
|
+
* followed mark's (`tracked`) too, so a host places marks scrolled out of the frame, and keeps
|
|
37
|
+
* them placed as the document scrolls, from one report and the followed mark's scroll.
|
|
34
38
|
*
|
|
35
39
|
* It shares the realm with the content, which can interfere with all of it: the host takes its
|
|
36
40
|
* reports as UI hints only.
|
package/dist/shell/annotate.js
CHANGED
|
@@ -55,7 +55,11 @@ export const MARKER_HIT = String.raw `(count, boxAt, x, y, touch) => {
|
|
|
55
55
|
* bubble with no number, and has a marker with or without a count;
|
|
56
56
|
* - following: while a mark has a marker, once a scroll, a resize or a change of the content
|
|
57
57
|
* settles, the marks that moved since the host was last told are reported, at most once a
|
|
58
|
-
* second, so the host's own UI beside a mark can follow
|
|
58
|
+
* second, so the host's own UI beside a mark can follow;
|
|
59
|
+
* - places in the document (P132): each result's box also in the document's coordinates
|
|
60
|
+
* (`documentRect`), with how far the document was scrolled as it was read (`scroll`), and the
|
|
61
|
+
* followed mark's (`tracked`) too, so a host places marks scrolled out of the frame, and keeps
|
|
62
|
+
* them placed as the document scrolls, from one report and the followed mark's scroll.
|
|
59
63
|
*
|
|
60
64
|
* It shares the realm with the content, which can interfere with all of it: the host takes its
|
|
61
65
|
* reports as UI hints only.
|
|
@@ -304,6 +308,19 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
304
308
|
return null;
|
|
305
309
|
};
|
|
306
310
|
const rectOf = (found) => (found.range ? rangeRect.call(found.range) : elementRect.call(found.element));
|
|
311
|
+
// How far the document is scrolled (P132): the top left of its root's box from the
|
|
312
|
+
// viewport's, negated, read with the DOM's own getBoundingClientRect (taken before content
|
|
313
|
+
// runs), never window.scrollY, which the content can replace. 0 - n: no -0 for a top at 0.
|
|
314
|
+
const scrollOf = () => {
|
|
315
|
+
const root = document.documentElement;
|
|
316
|
+
if (!root) {
|
|
317
|
+
return { x: 0, y: 0 };
|
|
318
|
+
}
|
|
319
|
+
const rect = elementRect.call(root);
|
|
320
|
+
return { x: 0 - rect.left, y: 0 - rect.top };
|
|
321
|
+
};
|
|
322
|
+
// A box in the viewport, in the document (P132): where it is as the document scrolls.
|
|
323
|
+
const inDocument = (rect, scroll) => ({ x: rect.x + scroll.x, y: rect.y + scroll.y, width: rect.width, height: rect.height });
|
|
307
324
|
|
|
308
325
|
// The shell's own layer, over the content: marks, the outline of what would be picked.
|
|
309
326
|
let layer = null;
|
|
@@ -797,7 +814,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
797
814
|
if (apart(trackedBox, rect) && now - trackedAt >= 16) {
|
|
798
815
|
trackedBox = rect;
|
|
799
816
|
trackedAt = now;
|
|
800
|
-
|
|
817
|
+
// Its box moves as the document scrolls, inside the frame or not: each one tells the
|
|
818
|
+
// host the scroll, for every mark it places by its place in the document (P132).
|
|
819
|
+
const scroll = scrollOf();
|
|
820
|
+
tell(M.tracked, { id: tracking, rect, documentRect: inDocument(rect, scroll), scroll });
|
|
801
821
|
}
|
|
802
822
|
}
|
|
803
823
|
trackFrame = nextFrame(trackTick);
|
|
@@ -841,12 +861,15 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
841
861
|
placed.forEach((each, at) => orders.set(each.mark, at));
|
|
842
862
|
return orders;
|
|
843
863
|
};
|
|
844
|
-
|
|
864
|
+
// A mark's result: its box in the viewport, and in the document (P132) by scroll, the
|
|
865
|
+
// report's one reading of it.
|
|
866
|
+
const resultOf = (mark, orders, scroll) => {
|
|
845
867
|
if (mark.found === null) {
|
|
846
868
|
return { id: mark.id, state: "orphaned" };
|
|
847
869
|
}
|
|
848
870
|
const order = (orders || ordersOf()).get(mark);
|
|
849
|
-
|
|
871
|
+
const rect = box(rectOf(mark.found));
|
|
872
|
+
return Object.assign({ id: mark.id, state: "attached", rect, documentRect: inDocument(rect, scroll) }, order === undefined ? {} : { order });
|
|
850
873
|
};
|
|
851
874
|
// Two boxes more than 0.5 px apart on any side (or one of them unknown).
|
|
852
875
|
const apart = (a, b) => !a || !b || Math.abs(a.x - b.x) > 0.5 || Math.abs(a.y - b.y) > 0.5 || Math.abs(a.width - b.width) > 0.5 || Math.abs(a.height - b.height) > 0.5;
|
|
@@ -858,17 +881,18 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
858
881
|
}
|
|
859
882
|
return result.state === "attached" && (apart(told.rect, result.rect) || told.order !== result.order);
|
|
860
883
|
};
|
|
861
|
-
|
|
884
|
+
// With the scroll the results' document boxes were read at (P132).
|
|
885
|
+
const report = (pairs, scroll) => {
|
|
862
886
|
if (pairs.length > 0) {
|
|
863
887
|
for (const pair of pairs) {
|
|
864
888
|
pair.mark.told = pair.result;
|
|
865
889
|
}
|
|
866
|
-
tell(M.anchored, { results: pairs.map((pair) => pair.result) });
|
|
890
|
+
tell(M.anchored, { results: pairs.map((pair) => pair.result), scroll });
|
|
867
891
|
}
|
|
868
892
|
};
|
|
869
|
-
const resultsOf = (only) => {
|
|
893
|
+
const resultsOf = (only, scroll) => {
|
|
870
894
|
const orders = ordersOf();
|
|
871
|
-
return marks.map((mark) => ({ mark, result: resultOf(mark, orders) })).filter((pair) => !only || moved(pair.mark, pair.result));
|
|
895
|
+
return marks.map((mark) => ({ mark, result: resultOf(mark, orders, scroll) })).filter((pair) => !only || moved(pair.mark, pair.result));
|
|
872
896
|
};
|
|
873
897
|
// Finds every mark again; tells the host every result (after show, or when a state changed),
|
|
874
898
|
// only the marks that moved (once the content is quiet), or nothing.
|
|
@@ -890,7 +914,8 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
890
914
|
mark.state = state;
|
|
891
915
|
}
|
|
892
916
|
if (all || changed) {
|
|
893
|
-
|
|
917
|
+
const scroll = scrollOf();
|
|
918
|
+
report(resultsOf(false, scroll), scroll);
|
|
894
919
|
} else if (quiet) {
|
|
895
920
|
follow();
|
|
896
921
|
}
|
|
@@ -975,9 +1000,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
975
1000
|
const sendFollow = () => {
|
|
976
1001
|
let sent = 0;
|
|
977
1002
|
if (marks.length > 0 && !settling() && counted()) {
|
|
978
|
-
const
|
|
1003
|
+
const scroll = scrollOf();
|
|
1004
|
+
const pairs = resultsOf(true, scroll);
|
|
979
1005
|
if (pairs.length > 0) {
|
|
980
|
-
report(pairs);
|
|
1006
|
+
report(pairs, scroll);
|
|
981
1007
|
sent += 1;
|
|
982
1008
|
}
|
|
983
1009
|
}
|
|
@@ -1041,7 +1067,8 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1041
1067
|
setTimeout(redraw, 1850);
|
|
1042
1068
|
}
|
|
1043
1069
|
draw();
|
|
1044
|
-
|
|
1070
|
+
const scroll = scrollOf();
|
|
1071
|
+
report([{ mark, result: resultOf(mark, null, scroll) }], scroll);
|
|
1045
1072
|
};
|
|
1046
1073
|
|
|
1047
1074
|
// A marker's click (P104). The layer takes no pointer but on its markers, so a press whose
|
package/docs/ADOPTING.md
CHANGED
|
@@ -385,6 +385,35 @@ composer.onClose(() => display.annotations.clearSelection());
|
|
|
385
385
|
position. A frame you scale or transform (a thumbnail, a zoomed preview) needs the box mapped
|
|
386
386
|
through that transform too (`frame.getBoundingClientRect().width / frame.clientWidth` for a
|
|
387
387
|
plain scale), or your view lands off by the difference.
|
|
388
|
+
- **Places in the document** (P132): for UI that lines up with marks outside the frame's view
|
|
389
|
+
(comment cards in a margin beside a scrolling page), a newer shell gives each attached result a
|
|
390
|
+
`documentRect` (its box in the document: it doesn't move as the page scrolls, and isn't clamped)
|
|
391
|
+
and each `anchored` report the `scroll` it was read at; `tracked` carries both too, so following
|
|
392
|
+
one mark (`track`) tells the scroll at every animation frame where it changed, whether that mark
|
|
393
|
+
is in view or not. A mark's top in the frame's viewport is then `documentRect.y - scroll.y`, with
|
|
394
|
+
no need to ask again as the page scrolls. The numbers are the page's word, and unclamped: clip
|
|
395
|
+
what you draw from them to the frame's box, or to your own region beside it. An older shell sends
|
|
396
|
+
neither: test for `scroll` and keep the viewport boxes' way where it is absent.
|
|
397
|
+
|
|
398
|
+
```js
|
|
399
|
+
const tops = new Map(); // mark id → its top in the document
|
|
400
|
+
let scrollY = null; // null: an older shell, places by `rect` only
|
|
401
|
+
display.on("annotation", (report) => {
|
|
402
|
+
if (report.type !== "anchored" && report.type !== "tracked") return;
|
|
403
|
+
if (report.scroll) scrollY = report.scroll.y;
|
|
404
|
+
if (report.type === "anchored") {
|
|
405
|
+
for (const result of report.results) {
|
|
406
|
+
if (result.documentRect) tops.set(result.id, result.documentRect.y);
|
|
407
|
+
else tops.delete(result.id); // orphaned
|
|
408
|
+
}
|
|
409
|
+
}
|
|
410
|
+
if (scrollY !== null) margin.place(tops, scrollY); // card top: frame top + top - scrollY, clipped
|
|
411
|
+
});
|
|
412
|
+
display.annotations.track(anyShownMarkId); // its reports carry the scroll
|
|
413
|
+
```
|
|
414
|
+
|
|
415
|
+
A page that scrolls a box of its own rather than its document moves the places of the marks in
|
|
416
|
+
it as it scrolls; show again (or follow such a mark) to hear them again.
|
|
388
417
|
- **Labels and quotes are the page's text**: shown only as text. Porthole takes out of a label what
|
|
389
418
|
the person can't see; a quote (`exact`) keeps it, to be found again. Hand either to a model only
|
|
390
419
|
as the page's words.
|
package/docs/DECISIONS.md
CHANGED
|
@@ -7531,3 +7531,68 @@ probe, with its positive control: taken with the person in the frame).
|
|
|
7531
7531
|
Escape or Cmd+G in the frame should reach the host's bar, a host searches as the person types and
|
|
7532
7532
|
wants the page not to see each keystroke (debounce in the host first), or engines give a frame a
|
|
7533
7533
|
highlight registry content can't reach.
|
|
7534
|
+
|
|
7535
|
+
## P132 · 2026-11-05 · A mark's place in the document, and the document's scroll, beside its box in the viewport · Accepted
|
|
7536
|
+
|
|
7537
|
+
A host that lines its own UI up with marks beside a scrolling page (comment cards in a margin
|
|
7538
|
+
next to the frame, each level with its passage) needs to know where every mark is, the ones
|
|
7539
|
+
scrolled out of the frame included, and to keep that as the page scrolls. 0.14 gives it boxes in
|
|
7540
|
+
the frame's viewport only, clamped to it (P104): a mark above or below the frame is a box of no
|
|
7541
|
+
size on that edge, so its card can't be placed; and a box read before a scroll is wrong after it.
|
|
7542
|
+
Such a host followed one mark (`track`, P112) and moved every card by as much as it moved, hid
|
|
7543
|
+
the cards it knew no place for, and asked for every place again (a `show` that changed) when the
|
|
7544
|
+
page stopped scrolling, every few hundred ms during a long scroll, when the followed mark left the
|
|
7545
|
+
frame, and on a poll while nothing was placed: a message and a full re-anchoring per ask, and
|
|
7546
|
+
cards missing until the answer.
|
|
7547
|
+
|
|
7548
|
+
**Decision.**
|
|
7549
|
+
- **`documentRect`** on each attached result of `anchored`: the mark's box as the shell read it
|
|
7550
|
+
(before the host's clamp) plus how far the document was scrolled. It stays where it is as the
|
|
7551
|
+
document scrolls and says where an offscreen mark is.
|
|
7552
|
+
- **`scroll`** (`{ x, y }`) on each `anchored` report: how far the document was scrolled as its
|
|
7553
|
+
boxes were read, one reading for every result in it. It is the top left of the document's root
|
|
7554
|
+
element (`<html>`) from the viewport's, negated, read with the DOM's own `getBoundingClientRect`
|
|
7555
|
+
taken before content runs, not `window.scrollX`/`scrollY` (a page can replace those). `rect` =
|
|
7556
|
+
`documentRect` − `scroll`, before the clamp. Its presence is how a host tells a shell that reports places in the document.
|
|
7557
|
+
- **`tracked`** carries both too. The followed mark's box moves at every scroll of the document,
|
|
7558
|
+
in the frame or not, so its reports (one an animation frame at most, 60 a second the host takes,
|
|
7559
|
+
P112) are the document's scroll as it changes: a host places every mark it has a `documentRect`
|
|
7560
|
+
for from one report and the followed mark's scroll, and asks again only when the content changes
|
|
7561
|
+
(a `tracked` whose `documentRect` moved says the layout did, near that mark at least).
|
|
7562
|
+
- No new message, method, option or rate: the existing reports carry two optional fields; the
|
|
7563
|
+
React binding passes them through `onAnnotation` unchanged.
|
|
7564
|
+
- Rather than a scroll message of its own (a shell that posts the scroll at every frame while asked,
|
|
7565
|
+
with its own opt-in and its own rate): the host that needs the scroll already follows a mark, and
|
|
7566
|
+
each `tracked` is already a message per frame that moved; a second stream per frame would double
|
|
7567
|
+
that for no more information. Rather than reports pushed at every scroll for every mark: 500 marks
|
|
7568
|
+
a frame is a cost the shell and the bridge's rate can't carry; their places in the document don't
|
|
7569
|
+
change as it scrolls, so one report is enough.
|
|
7570
|
+
|
|
7571
|
+
**Compatibility.** Both fields are optional. An older shell sends neither and a host reads
|
|
7572
|
+
`rect` as before; an older host drops fields it doesn't know (each report is rebuilt from known
|
|
7573
|
+
fields, P053), so a newer shell's reports reach it as they did. A malformed `documentRect` or
|
|
7574
|
+
`scroll` drops the whole report, as any malformed part does.
|
|
7575
|
+
|
|
7576
|
+
**Threat.** P104's clamp holds a page's boxes to its frame so it can't make the host place its UI
|
|
7577
|
+
over the rest of the app. `documentRect` isn't clamped, because a clamp would erase what it is for:
|
|
7578
|
+
a host that maps one onto its own page without clipping lets the page choose where that UI goes,
|
|
7579
|
+
outside the frame too. Bounded by the checks every box gets (finite, within
|
|
7580
|
+
`ANNOTATION_LIMITS.coordinate`, sizes not negative) and by the host's duty to clip what it draws
|
|
7581
|
+
from them to the frame's box or to its own region beside the frame (THREAT_MODEL §6, ADOPTING);
|
|
7582
|
+
`rect` stays clamped, so a host that reads only it is as before. The page learns nothing new (the
|
|
7583
|
+
fields go from the frame to the host) and could already say any place inside its frame; where its
|
|
7584
|
+
words are in its own document it knows anyway.
|
|
7585
|
+
|
|
7586
|
+
**Tested.** `test/annotate.test.ts` "places in the document (P132)": `parseScroll`; both fields
|
|
7587
|
+
kept in `anchored` and `tracked`, rebuilt from known fields, an older shell's reports exactly as
|
|
7588
|
+
before; a malformed one dropping the report; through `createHost`, each `rect` clamped and each
|
|
7589
|
+
`documentRect` and `scroll` as the shell said. `leak/annotate.spec.ts` "every attached mark's place
|
|
7590
|
+
in the document comes with the scroll it was read at…" (three engines): an offscreen mark's place
|
|
7591
|
+
where the page measures it, its `rect` clamped; the followed mark's reports telling the scroll as
|
|
7592
|
+
the document scrolls, its place unchanged, place less scroll where the page draws it; a page's
|
|
7593
|
+
malformed place or scroll refused, a place far down its document taken as it said. No negative
|
|
7594
|
+
control: nothing here is a defense; the bound is `parseRect`'s, which existing probes hold.
|
|
7595
|
+
|
|
7596
|
+
**Revisit when** a host needs places within a page's own scrolling box (a place relative to that
|
|
7597
|
+
box, and its scroll), the scroll without following a mark (a page with no marks the host follows),
|
|
7598
|
+
or a host draws from `documentRect` inside the frame's own area and wants Porthole to clip for it.
|
package/docs/DESIGN.md
CHANGED
|
@@ -1050,7 +1050,9 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1050
1050
|
| frame → host | `porthole/annotate.selected` | `{ anchor, rect }`; after a scroll, the same selection again only if its box moved more than 0.5 px, on the follow-ups' clock (P105) |
|
|
1051
1051
|
| frame → host | `porthole/annotate.unselected` | — (the text selection went away) |
|
|
1052
1052
|
| frame → host | `porthole/annotate.cancelled` | — (Escape) |
|
|
1053
|
-
| frame → host | `porthole/annotate.anchored` | `{ results: [{ id, state: "attached" \| "orphaned", rect? }] }`: every mark after `show`, the one after `focus`, every mark when the content changed a state, and, while any mark has a marker (a `count` or a draft, P107), once a scroll, a resize or a run of content changes has settled (150 ms quiet), only the marks that moved more than 0.5 px since the host was last told, at most one a second together with the selection's (P104, P105) |
|
|
1053
|
+
| frame → host | `porthole/annotate.anchored` | `{ results: [{ id, state: "attached" \| "orphaned", rect?, documentRect?, order? }], scroll? }` (a newer shell's `documentRect` and `scroll`: P132, below): every mark after `show`, the one after `focus`, every mark when the content changed a state, and, while any mark has a marker (a `count` or a draft, P107), once a scroll, a resize or a run of content changes has settled (150 ms quiet), only the marks that moved more than 0.5 px since the host was last told, at most one a second together with the selection's (P104, P105) |
|
|
1054
|
+
| host → frame | `porthole/annotate.track` | `{ id }` or `{ id: null }`: follow one shown mark, or none (P112) |
|
|
1055
|
+
| frame → host | `porthole/annotate.tracked` | `{ id, rect, documentRect?, scroll? }`: the followed mark's box at an animation frame where it moved, at most one every 16 ms; the host takes 60 a second, for that mark only (P112); a newer shell adds its place in the document and the document's scroll (P132) |
|
|
1054
1056
|
| frame → host | `porthole/annotate.activated` | `{ id, rect }`: the person clicked a mark's marker; `rect` is the marker's (P104); taken only while the host's page has transient activation (P105) |
|
|
1055
1057
|
|
|
1056
1058
|
- **Anchors** are W3C Web Annotation selectors, at most one of each:
|
|
@@ -1070,6 +1072,17 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1070
1072
|
hears it (P104); a box wholly outside becomes one of no size on the nearest edge
|
|
1071
1073
|
(a mark below the fold: `y` at the viewport's height, no height). A platform whose
|
|
1072
1074
|
`viewport()` answers no size or throws gets nothing at the corner (P105).
|
|
1075
|
+
- **Places in the document** (P132). A newer shell gives each attached result a
|
|
1076
|
+
`documentRect` too: its box plus how far the document was scrolled as it was read, the
|
|
1077
|
+
report's `scroll` (`{ x, y }`: the root element's top left from the viewport's, negated,
|
|
1078
|
+
read with the DOM's own `getBoundingClientRect`). So it stays put as the document
|
|
1079
|
+
scrolls, and says where a mark outside the frame is; `rect` is `documentRect` less
|
|
1080
|
+
`scroll`, before the clamp. `tracked` carries both too: a followed mark's box moves at
|
|
1081
|
+
every scroll, so its reports tell the scroll at each animation frame, in the frame or
|
|
1082
|
+
not. `createHost` checks them as boxes (finite, within the coordinate limit, sizes not
|
|
1083
|
+
negative; a malformed one drops the report) and clamps neither: the host clips what it
|
|
1084
|
+
draws from them. A page that scrolls a box of its own rather than its document moves
|
|
1085
|
+
its marks' places with it, as their `rect` does; those are told as before.
|
|
1073
1086
|
- **Markers** (P104). A mark with a `count` gets a bubble glyph and its number ("99+"
|
|
1074
1087
|
above 99; 0 the bubble alone) on an element's top right corner, inside the frame's
|
|
1075
1088
|
width, and beside a text anchor's last line, centred on it (P105, #36): in the
|
|
@@ -1495,7 +1508,7 @@ control the tables above name to the registry):
|
|
|
1495
1508
|
| `draft-count` | `annotate.spec.ts` | `what the page reads of a draft (P107): that it is one, never its count; a posted mark as before` | — | — |
|
|
1496
1509
|
| `draft-shell-checks` | `annotate.spec.ts` | `the shell's own checks on a raw show (P107): a draft draws no number, a kind it doesn't know is no mark` | — | — |
|
|
1497
1510
|
| `annotation-activated-gesture` | `annotate.spec.ts` | `a hostile page's marker click with no gesture is dropped; one on the person's own press is the host's view to guard (P105)` | — | — |
|
|
1498
|
-
| `annotation-rect-clamp` | `annotate.spec.ts` | `a hostile page reports a box outside its frame: the host gets it clamped to the frame's viewport`, `marks: drawn over their anchors, one brought into view, an unfound one orphaned, all cleared`, `following: once a scroll settles, one report with only the marks that moved` | — | — |
|
|
1511
|
+
| `annotation-rect-clamp` | `annotate.spec.ts` | `a hostile page reports a box outside its frame: the host gets it clamped to the frame's viewport`, `marks: drawn over their anchors, one brought into view, an unfound one orphaned, all cleared`, `following: once a scroll settles, one report with only the marks that moved`, `every attached mark's place in the document comes with the scroll it was read at, offscreen ones too, and the followed mark's as the document scrolls (P132)` | — | — |
|
|
1499
1512
|
| `authorize` | `served/authorize.spec.ts` | `a revoked subject's ticket opens nothing: a page and an app are denied, and the host is told`, `in a tab of its own, a revoked app and page are denied from the next request on`, `a framed page mid-session: its next load after revocation is denied where the engine keeps its cookie` | Chromium, Firefox: `a framed app mid-session: its next request after revocation is denied, and its next load tells the host` | — |
|
|
1500
1513
|
| `url-permissions` | `served/permissions.spec.ts` | `a url-mode frame gets no clipboard writes or full screen unless the host delegates them` | — | — |
|
|
1501
1514
|
| `navigate-guard` | `served/live.spec.ts`, `served/files.spec.ts`, `served/served.spec.ts`, `served/tab.spec.ts` | `served.domain.self-navigation`, `served.domain.tab-navigation`, `served.domain.tab-links`, `can't navigate itself away (location): to a site, or to another content origin`, `can't navigate itself away (replace): to a site, or to another content origin`, `can't navigate itself away (open-self): to a site, or to another content origin`, `can't navigate itself away (navigation-api): to a site, or to another content origin`, `a link to another page of the set opens it in the frame; the display goes on`, `a link to another page of the set opens it in the frame when the leaving page's notice is dropped (P098)`, `a link to another page of the set opens it in the frame when the leaving page's notice is late (P098)`, `a page opens nothing else: not a file that isn't a page, not another path of its origin`, `no report, content error or blocked navigation names the frame's sealed address (P083)` | — | — |
|
package/docs/THREAT_MODEL.md
CHANGED
|
@@ -5,7 +5,7 @@ What Porthole protects, from whom, and where that protection ends. For each way
|
|
|
5
5
|
guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
|
|
6
6
|
[DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
|
|
7
7
|
|
|
8
|
-
**Status.** This describes Porthole 0.14.
|
|
8
|
+
**Status.** This describes Porthole 0.14.10 (2026-11-05). A review on 2026-10-19 found gaps, and every decision it led to
|
|
9
9
|
has merged ([§8](#8-fixes-in-flight) lists them). P096 changed the negative-control runner and CI,
|
|
10
10
|
and the shipped conformance probes' messages and timing, not what they check. P104 (0.9.0's
|
|
11
11
|
annotation markers) had a review of its own, and P105, in 0.10.0, is what it led to. 0.11.0 was
|
|
@@ -28,7 +28,9 @@ frames of its own files load and run, in realms the shell's hardening never reac
|
|
|
28
28
|
clipboard's guards: S1, S3); frames of other sites stay out. 0.14.9: P131 adds find
|
|
29
29
|
in page (`find`, off unless a config declares it): the host's find bar sends the person's query
|
|
30
30
|
into the frame, where the content can read it, and takes counts, a box and the find shortcut back
|
|
31
|
-
as the content's word (§6, §7 "Find in page"); no wall moves.
|
|
31
|
+
as the content's word (§6, §7 "Find in page"); no wall moves. 0.14.10: P132 adds a mark's place in
|
|
32
|
+
the document and the document's scroll to annotation reports, unclamped, so a host must clip what it
|
|
33
|
+
draws from them to its own region (§6, §7); `rect` stays clamped and no wall moves.
|
|
32
34
|
|
|
33
35
|
## 1. Two layers
|
|
34
36
|
|
|
@@ -193,7 +195,9 @@ Whatever the use:
|
|
|
193
195
|
framed as it is: upgrade the server/Worker first, resolve clean addresses through issue, P125):
|
|
194
196
|
log them, show nothing for them. A url-mode app can still say any outcome (S6).
|
|
195
197
|
- Take what the frame reports about annotations as UI hints (where to draw, what to open), never
|
|
196
|
-
as permissions, and put nothing in a mark the page may not know (§7).
|
|
198
|
+
as permissions, and put nothing in a mark the page may not know (§7). A mark's place in the
|
|
199
|
+
document (`documentRect`, with the report's `scroll`, P132) isn't clamped to the frame: clip
|
|
200
|
+
whatever you draw from it to the frame's box, or to your own region beside the frame.
|
|
197
201
|
- Under `find` (P131), know that the page reads every query your find bar sends it, and declare
|
|
198
202
|
`find` only for displays whose pages may learn what the person searches for (not a third-party
|
|
199
203
|
app with egress, S5, unless you accept it). Take its counts as the bar's numbers, and open your
|
|
@@ -813,6 +817,14 @@ own frame, below the shell, P111), so:
|
|
|
813
817
|
no size, or throws, clamps every box to nothing at the frame's corner (P105). The frame's size is
|
|
814
818
|
read for every report the host takes, before the report's rate: a forced layout of the host's
|
|
815
819
|
page per message, which a repeated `ui/initialize` already causes (accepted, P105).
|
|
820
|
+
A newer shell also says where each mark is in the document (`documentRect` in `anchored` and
|
|
821
|
+
`tracked`, with the document's `scroll`, P132), so a host can place a mark scrolled out of the
|
|
822
|
+
frame. Porthole checks those numbers (finite, within `ANNOTATION_LIMITS.coordinate`, sizes not
|
|
823
|
+
negative; a malformed one drops the report) but doesn't clamp them, since a clamp would erase
|
|
824
|
+
what they are for: a host that maps a `documentRect` onto its own page without clipping to the
|
|
825
|
+
frame's box (or to its own region beside it) lets the page choose where that UI goes, outside
|
|
826
|
+
the frame as well (accepted, P132; the host's duty in §6). They say nothing else: the page knows
|
|
827
|
+
where its words are anyway.
|
|
816
828
|
- *What holds, against content that patches none of the DOM's or JavaScript's built-ins.* A real
|
|
817
829
|
press or click on a marker reaches none of the content's handlers (the shell's first listener
|
|
818
830
|
stops it; control `marker-click`) and moves neither focus nor a selection (control
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.14.
|
|
3
|
+
"version": "0.14.10",
|
|
4
4
|
"description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
|
|
5
5
|
"homepage": "https://github.com/botiverse/porthole#readme",
|
|
6
6
|
"bugs": {
|
package/src/annotate/types.ts
CHANGED
|
@@ -52,7 +52,8 @@ export interface AnnotationAnchor {
|
|
|
52
52
|
* The page's word: the host clamps each it reports to the frame's viewport (P104), so one wholly
|
|
53
53
|
* outside is a box of no size on the nearest edge. A positioning hint only. It is in the frame's
|
|
54
54
|
* own layout px: a host that scales or transforms the frame maps it through that transform too
|
|
55
|
-
* (P105).
|
|
55
|
+
* (P105). A result's `documentRect` (P132) is the same shape in the document's coordinates, and
|
|
56
|
+
* isn't clamped.
|
|
56
57
|
*/
|
|
57
58
|
export interface AnnotationRect {
|
|
58
59
|
readonly x: number;
|
|
@@ -61,6 +62,17 @@ export interface AnnotationRect {
|
|
|
61
62
|
readonly height: number;
|
|
62
63
|
}
|
|
63
64
|
|
|
65
|
+
/**
|
|
66
|
+
* How far the frame's document is scrolled when the boxes beside it were read (P132), CSS px: the
|
|
67
|
+
* top left of the document's root element (`<html>`), from the viewport's, negated (`window.scrollX`
|
|
68
|
+
* and `window.scrollY` on a page whose root has no margin). A box in the viewport is its
|
|
69
|
+
* `documentRect` less this. The page's word, as every box is.
|
|
70
|
+
*/
|
|
71
|
+
export interface AnnotationScroll {
|
|
72
|
+
readonly x: number;
|
|
73
|
+
readonly y: number;
|
|
74
|
+
}
|
|
75
|
+
|
|
64
76
|
/** What the person may point at while the host is asking. */
|
|
65
77
|
export interface AnnotateMode {
|
|
66
78
|
/**
|
|
@@ -112,6 +124,14 @@ export interface AnchorResult {
|
|
|
112
124
|
readonly state: AnchorState;
|
|
113
125
|
/** Where it is now, when attached. */
|
|
114
126
|
readonly rect?: AnnotationRect;
|
|
127
|
+
/**
|
|
128
|
+
* Where it is in the document (P132): `rect` as the shell read it, before the host clamped it,
|
|
129
|
+
* plus the report's `scroll`; so it stays where it is as the document scrolls, and says where a
|
|
130
|
+
* mark scrolled out of the frame is. Not clamped to the frame's viewport (an offscreen mark's is
|
|
131
|
+
* outside it: that is its point): a host places its own UI from it only clipped to the frame's
|
|
132
|
+
* box, or to its own region beside the frame. Absent from an older shell. The page's word.
|
|
133
|
+
*/
|
|
134
|
+
readonly documentRect?: AnnotationRect;
|
|
115
135
|
/**
|
|
116
136
|
* Its place in the document among the found marks, from 0 (P112): where it starts, offscreen
|
|
117
137
|
* marks included, for a host that lists marks in reading order. The content's word: an order to
|
|
@@ -143,13 +163,32 @@ export type AnnotationReport =
|
|
|
143
163
|
* scroll, a resize or a change of the content has settled, only the marks that moved since the
|
|
144
164
|
* host was last told, at most once a second (P104).
|
|
145
165
|
*/
|
|
146
|
-
| {
|
|
166
|
+
| {
|
|
167
|
+
readonly type: "anchored";
|
|
168
|
+
readonly results: readonly AnchorResult[];
|
|
169
|
+
/**
|
|
170
|
+
* How far the document was scrolled as the boxes were read (P132); with it, each attached
|
|
171
|
+
* result has its `documentRect`. Absent from an older shell: its results have no
|
|
172
|
+
* `documentRect` either, and only `rect` says where marks are.
|
|
173
|
+
*/
|
|
174
|
+
readonly scroll?: AnnotationScroll;
|
|
175
|
+
}
|
|
147
176
|
/**
|
|
148
177
|
* The box of the mark the host follows (`annotations.track`, P112), in the frame's viewport, at
|
|
149
178
|
* an animation frame where it moved: at most 60 a second, for that mark only, clamped to the
|
|
150
|
-
* frame. The content's word: where to put a card beside it, nothing more.
|
|
179
|
+
* frame. The content's word: where to put a card beside it, nothing more. A newer shell (P132)
|
|
180
|
+
* adds the mark's `documentRect` and the document's `scroll`: the mark's box moves as the
|
|
181
|
+
* document scrolls, so a host following one mark hears the scroll at every animation frame where
|
|
182
|
+
* it changed, whether that mark is in the frame or not, and places every mark it holds a
|
|
183
|
+
* `documentRect` for (an `anchored` report's) without asking again.
|
|
151
184
|
*/
|
|
152
|
-
| {
|
|
185
|
+
| {
|
|
186
|
+
readonly type: "tracked";
|
|
187
|
+
readonly id: string;
|
|
188
|
+
readonly rect: AnnotationRect;
|
|
189
|
+
readonly documentRect?: AnnotationRect;
|
|
190
|
+
readonly scroll?: AnnotationScroll;
|
|
191
|
+
}
|
|
153
192
|
/**
|
|
154
193
|
* The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
|
|
155
194
|
* (P107); `rect` is the marker's box, to open the host's own UI beside it. The content can fake
|
package/src/annotate/validate.ts
CHANGED
|
@@ -6,6 +6,7 @@ import {
|
|
|
6
6
|
type AnnotationMark,
|
|
7
7
|
type AnnotationRect,
|
|
8
8
|
type AnnotationReport,
|
|
9
|
+
type AnnotationScroll,
|
|
9
10
|
type AnnotationSelector,
|
|
10
11
|
} from "./types.ts";
|
|
11
12
|
import { withoutUnseen } from "../bridge/unseen.ts";
|
|
@@ -112,6 +113,17 @@ export function parseRect(value: unknown): AnnotationRect | null {
|
|
|
112
113
|
return { x, y, width, height };
|
|
113
114
|
}
|
|
114
115
|
|
|
116
|
+
/**
|
|
117
|
+
* How far the document is scrolled (P132): two finite numbers within the coordinate limit (either
|
|
118
|
+
* may be negative: an engine's overscroll); null for anything else.
|
|
119
|
+
*/
|
|
120
|
+
export function parseScroll(value: unknown): AnnotationScroll | null {
|
|
121
|
+
if (!isRecord(value) || !coordinate(value.x) || !coordinate(value.y)) {
|
|
122
|
+
return null;
|
|
123
|
+
}
|
|
124
|
+
return { x: value.x, y: value.y };
|
|
125
|
+
}
|
|
126
|
+
|
|
115
127
|
/**
|
|
116
128
|
* A box the frame reported, clamped to the frame's viewport (`width` by `height`, CSS px, P104):
|
|
117
129
|
* each side is held within it, so what overlaps the viewport keeps the part inside, and what lies
|
|
@@ -152,7 +164,9 @@ function results(value: unknown): AnchorResult[] | null {
|
|
|
152
164
|
return null;
|
|
153
165
|
}
|
|
154
166
|
const rect = each.rect === undefined ? undefined : parseRect(each.rect);
|
|
155
|
-
|
|
167
|
+
// Where it is in the document (P132): a box as `rect` is, never clamped.
|
|
168
|
+
const documentRect = each.documentRect === undefined ? undefined : parseRect(each.documentRect);
|
|
169
|
+
if (rect === null || documentRect === null) {
|
|
156
170
|
return null;
|
|
157
171
|
}
|
|
158
172
|
// A place among the marks (P112): a whole number below the most marks a show carries.
|
|
@@ -167,6 +181,7 @@ function results(value: unknown): AnchorResult[] | null {
|
|
|
167
181
|
id: each.id,
|
|
168
182
|
state: "attached",
|
|
169
183
|
...(rect === undefined ? {} : { rect }),
|
|
184
|
+
...(documentRect === undefined ? {} : { documentRect }),
|
|
170
185
|
...(order === undefined ? {} : { order }),
|
|
171
186
|
});
|
|
172
187
|
}
|
|
@@ -190,7 +205,10 @@ export function parseReport(value: unknown): AnnotationReport | null {
|
|
|
190
205
|
return { type: "cancelled" };
|
|
191
206
|
case "anchored": {
|
|
192
207
|
const checked = results(value.results);
|
|
193
|
-
|
|
208
|
+
const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
|
|
209
|
+
return checked === null || scroll === null
|
|
210
|
+
? null
|
|
211
|
+
: { type: "anchored", results: checked, ...(scroll === undefined ? {} : { scroll }) };
|
|
194
212
|
}
|
|
195
213
|
case "activated": {
|
|
196
214
|
const rect = parseRect(value.rect);
|
|
@@ -198,7 +216,20 @@ export function parseReport(value: unknown): AnnotationReport | null {
|
|
|
198
216
|
}
|
|
199
217
|
case "tracked": {
|
|
200
218
|
const rect = parseRect(value.rect);
|
|
201
|
-
|
|
219
|
+
// A newer shell's (P132): where the mark is in the document, and how far it is scrolled.
|
|
220
|
+
const documentRect =
|
|
221
|
+
value.documentRect === undefined ? undefined : parseRect(value.documentRect);
|
|
222
|
+
const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
|
|
223
|
+
if (!markId(value.id) || rect === null || documentRect === null || scroll === null) {
|
|
224
|
+
return null;
|
|
225
|
+
}
|
|
226
|
+
return {
|
|
227
|
+
type: "tracked",
|
|
228
|
+
id: value.id,
|
|
229
|
+
rect,
|
|
230
|
+
...(documentRect === undefined ? {} : { documentRect }),
|
|
231
|
+
...(scroll === undefined ? {} : { scroll }),
|
|
232
|
+
};
|
|
202
233
|
}
|
|
203
234
|
default:
|
|
204
235
|
return null;
|
package/src/host/create-host.ts
CHANGED
|
@@ -389,7 +389,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
389
389
|
};
|
|
390
390
|
/**
|
|
391
391
|
* Every box a report carries, clamped to the frame's viewport as it is now (P104): the page
|
|
392
|
-
* places the host's own UI nowhere outside its frame.
|
|
392
|
+
* places the host's own UI nowhere outside its frame. A mark's `documentRect` and the
|
|
393
|
+
* document's `scroll` (P132) pass as they were checked: where a mark is in the document,
|
|
394
|
+
* offscreen too, which a clamp would erase; the host clips what it draws from them.
|
|
393
395
|
*/
|
|
394
396
|
const withinFrame = (report: AnnotationReport): AnnotationReport => {
|
|
395
397
|
const viewport = frameViewport();
|
|
@@ -400,7 +402,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
400
402
|
return { ...report, rect: clampRect(report.rect, viewport) };
|
|
401
403
|
case "anchored":
|
|
402
404
|
return {
|
|
403
|
-
|
|
405
|
+
...report,
|
|
404
406
|
results: report.results.map((result) =>
|
|
405
407
|
result.rect === undefined
|
|
406
408
|
? result
|
|
@@ -490,7 +492,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
490
492
|
if (results.length === 0) {
|
|
491
493
|
return;
|
|
492
494
|
}
|
|
493
|
-
report = {
|
|
495
|
+
report = { ...report, results };
|
|
494
496
|
break;
|
|
495
497
|
}
|
|
496
498
|
case "activated": {
|
package/src/host/types.ts
CHANGED
|
@@ -306,7 +306,9 @@ export interface AnnotationControls {
|
|
|
306
306
|
* Follows one shown mark (P112): while it moves (a scroll, a layout change) the display reports
|
|
307
307
|
* `{ type: "tracked", id, rect }` at most once per animation frame (60 a second), its box clamped
|
|
308
308
|
* to the frame, for that mark only; `null` stops. One at a time: a new id replaces the last.
|
|
309
|
-
* Throws for an id no shown mark has; a `show` without it, or `clear`, stops it.
|
|
309
|
+
* Throws for an id no shown mark has; a `show` without it, or `clear`, stops it. From a newer
|
|
310
|
+
* shell (P132) each also carries the mark's `documentRect` and the document's `scroll`, so
|
|
311
|
+
* following one mark tells how far the document scrolled, for every mark placed by `documentRect`.
|
|
310
312
|
*/
|
|
311
313
|
track(id: string | null): void;
|
|
312
314
|
/** Removes every mark. */
|
package/src/index.ts
CHANGED
|
@@ -342,12 +342,13 @@ export {
|
|
|
342
342
|
type AnnotationMarkKind,
|
|
343
343
|
type AnnotationRect,
|
|
344
344
|
type AnnotationReport,
|
|
345
|
+
type AnnotationScroll,
|
|
345
346
|
type AnnotationSelector,
|
|
346
347
|
type CssSelector,
|
|
347
348
|
type TextPositionSelector,
|
|
348
349
|
type TextQuoteSelector,
|
|
349
350
|
} from "./annotate/types.ts";
|
|
350
|
-
export { parseAnchor, parseRect, parseReport } from "./annotate/validate.ts";
|
|
351
|
+
export { parseAnchor, parseRect, parseReport, parseScroll } from "./annotate/validate.ts";
|
|
351
352
|
|
|
352
353
|
// Find in page (P131): the host's find bar, the frame's matches, and the host's checks on both.
|
|
353
354
|
export {
|