@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.
@@ -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
- type: "anchored",
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 = { type: "anchored", results };
413
+ report = { ...report, results };
412
414
  break;
413
415
  }
414
416
  case "activated": {
@@ -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";
@@ -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. `null` (or
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
@@ -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.
@@ -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
- tell(M.tracked, { id: tracking, rect });
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
- const resultOf = (mark, orders) => {
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
- return Object.assign({ id: mark.id, state: "attached", rect: box(rectOf(mark.found)) }, order === undefined ? {} : { order });
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
- const report = (pairs) => {
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
- report(resultsOf(false));
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 pairs = resultsOf(true);
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
- report([{ mark, result: resultOf(mark) }]);
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)` | — | — |
@@ -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.9 (2026-11-04). A review on 2026-10-19 found gaps, and every decision it led to
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.9",
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": {
@@ -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
- | { readonly type: "anchored"; readonly results: readonly AnchorResult[] }
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
- | { readonly type: "tracked"; readonly id: string; readonly rect: AnnotationRect }
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
@@ -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
- if (rect === null) {
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
- return checked === null ? null : { type: "anchored", results: checked };
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
- return !markId(value.id) || rect === null ? null : { type: "tracked", id: value.id, rect };
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;
@@ -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
- type: "anchored",
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 = { type: "anchored", results };
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 {