@botiverse/porthole 0.8.0 → 0.9.0

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/docs/DECISIONS.md CHANGED
@@ -1109,7 +1109,7 @@ clipboard is closed to them otherwise. Item 1 of 0.1.3.
1109
1109
  shows the text); writing from inside the frame (P051).
1110
1110
  **Revisit when** MCP Apps defines a clipboard request (then the adapter maps it).
1111
1111
 
1112
- ## P053 · 2026-10-11 · Annotations are mechanism: the host's comments, anchored in content it can't trust · Accepted
1112
+ ## P053 · 2026-10-11 · Annotations are mechanism: the host's comments, anchored in content it can't trust · Accepted; amended by P104
1113
1113
 
1114
1114
  **Decision.** A new optional capability, `annotate`, declared by the host. It is for inline widgets
1115
1115
  and artifact pages, and for MCP Apps views where the host chooses. With it, the host can:
@@ -4589,3 +4589,157 @@ second wall on a tab); a host needs a served page to open windows from a tab (th
4589
4589
  `links.open`/`openLink`, never `allow-popups`); the platform adds a powerful feature with a
4590
4590
  `'self'` default (it joins `FRAME_DENIED_FEATURES`); or WebKit and Firefox apply
4591
4591
  `Permissions-Policy` to these features (the shell's device locks become the second wall there too).
4592
+
4593
+ ## P104 · 2026-10-20 · Annotation markers: a number at an anchor, a click the host hears, marks that follow a scroll · Accepted
4594
+
4595
+ A host that shows its comments beside an artifact page wants, at each comment's anchor in the page,
4596
+ a small marker (a bubble and how many comments are there) that scrolls with the content; a click on
4597
+ it opens the host's own bubble, with who wrote what, outside the frame. P053's marks are a fill and
4598
+ an underline (text) or an outline (an element), with no number and nothing to click, and the frame
4599
+ reported where marks are only after `show`, `focus` or a change of the content, never after a
4600
+ scroll, so a host's bubble beside a mark couldn't follow it. One adopter also found the element
4601
+ outline plain and unclear on its own.
4602
+
4603
+ **Decision.**
4604
+ 1. **A count on a mark.** `AnnotationMark.count?: number`, a whole number from 0 to
4605
+ `ANNOTATION_LIMITS.count` (999), checked by `checkMarks` (a bad one throws, as a bad anchor does).
4606
+ With it, the shell draws a marker in its own layer (the closed shadow root, P053): a bubble glyph
4607
+ and the number ("99+" above 99; 0 draws the bubble alone), at the end of a text anchor's last
4608
+ line, raised, and on an element's top right corner, kept inside the frame's width (and below its
4609
+ top while the anchor is in view); a second marker ending in the same place goes beside the
4610
+ first. Each mark keeps its marker's node across redraws, so a press that spans one isn't lost. Its colors, font and spacing are set in
4611
+ the layer, so the page's inherited styles don't reach it. Porthole doesn't say what is counted:
4612
+ comments, replies, anything per anchor.
4613
+ 2. **An element's mark with a marker is quieter**: a 1 px line 2 px out and a faint fill, 2 px
4614
+ when active, where it was a 2 px outline over a light fill. The marker says what the mark is,
4615
+ which the box alone didn't. A mark without a count draws as before (0.4.1's colors, P053's
4616
+ reasons: the content's words stay readable on light and dark pages).
4617
+ 3. **A click on a marker is reported**: `porthole/annotate.activated` with `{ id, rect }`, the
4618
+ marker's box in the frame's viewport, a new `AnnotationReport` (`type: "activated"`). The layer
4619
+ takes no pointer events but on its markers, so an event whose target is the layer is on one: the
4620
+ shell's first window listener (it runs before any of the content's) stops each press, release,
4621
+ click, double click, aux click, context menu, touch, and the pointer's moves over and out, there;
4622
+ cancels what the browser would do with a press (focus, selection, a menu); and reports a trusted
4623
+ primary click. The content's handlers, and what lies under the marker, never get it, as with
4624
+ element picking (P053). The content can still tell that a marker was pressed, and roughly where
4625
+ (see Trust). While elements are being picked the markers step aside (no pointer), so the click
4626
+ picks what is under one.
4627
+ 4. **The host takes `activated` only for a mark it shows with a count**, rebuilt from `id` and a
4628
+ `rect` (`parseReport`), through the bridge's 120 a minute, delivered as the `annotation` event
4629
+ (React: `onAnnotation`). An unknown id, or a mark shown without a count, is dropped; a malformed
4630
+ report is refused as `invalid`.
4631
+ 5. **Marks follow a scroll or a resize, while any mark has a marker.** Each mark keeps what the
4632
+ host was last told of it (its state and box). Once scrolling (any scroller in the page) or
4633
+ resizing has been quiet for 150 ms, or a run of changes of the content has (a run the 1 s
4634
+ deadline cut short is checked 150 ms after it), the shell reports `anchored` with only the marks
4635
+ whose state changed or whose box moved by more than 0.5 px since then, none when nothing moved,
4636
+ and at most one such report a second: a settle within a second of the last waits for the
4637
+ second's end and sends what is true then. Only while at least one shown mark has a `count`: a
4638
+ host that gives none hears exactly what 0.8 told it (every mark after `show`, the focused one,
4639
+ every mark when a change of the content changed a state). Rects stay in the frame's viewport; a
4640
+ host whose frame grows with its content (no scroll inside) sees no report for its own page's
4641
+ scroll, which it knows itself.
4642
+ 6. **Not focusable.** Markers have no tab stop and stay in the layer that is `aria-hidden`: a tab
4643
+ stop there would join the content's focus order, which the content controls (the realm is
4644
+ shared), and focusables under `aria-hidden` are a known accessibility fault. The host's own list
4645
+ of its marks, outside the frame, is the keyboard and assistive way, with `focus(id)` to bring
4646
+ one into view.
4647
+ 7. **After the review of b19e2e8.** Honest scrolling with a pause of 150 ms or more between turns
4648
+ sent a report per pause: 30 s of it spent the bridge's 120 a minute, and a real marker click was
4649
+ then refused (measured). Now follow-ups are at most one a second and only while a mark has a
4650
+ marker (point 5), so they take at most half the budget; a run cut short by the deadline left its
4651
+ last move untold, now checked once quiet. The layer's inline style also locks its size,
4652
+ `scale`, `translate`, `rotate`, `zoom`, `clip-path`, `mask`, `filter`, `content-visibility` and
4653
+ `contain`, and is set again at each draw; the pointer's moves over a marker are stopped too;
4654
+ a marker near the frame's top is kept below it. Each of these narrows; none closes what Trust
4655
+ says the content can still do.
4656
+ 8. **Every reported box is clamped to the frame** (after the review of 43768be). A box in
4657
+ `selected`, `activated` or an `anchored` result is the page's word, and `parseRect` checked only
4658
+ that it was finite and not negative in size: a hostile page could report one far outside its
4659
+ frame, and a host placing its own bubble by it would draw the host's UI wherever the page chose
4660
+ over the rest of the app (misdirection, though the page reads nothing). Now `createHost` clamps
4661
+ each, before the host hears it, to the frame's viewport as it is then (`Surface.viewport()`: the
4662
+ web platform's frame element's content box): each side is held within it, so a box overlapping
4663
+ it keeps the part inside, and one wholly outside becomes a box of no size on the nearest edge.
4664
+ Kept, not dropped: a mark scrolled out of view is still told, on the edge it went past (below
4665
+ the viewport: `y` at its height, of no height), which is what a host needs to point at it. A
4666
+ platform that can't tell the frame's size (no `viewport`) gets every box as nothing at the
4667
+ frame's corner: fail closed. This changes what 0.8 told for a mark outside the viewport. The
4668
+ page still chooses any point inside its own frame: a box is a positioning hint.
4669
+
4670
+ **Trust.** Unchanged in kind from P053: the shell shares the content's realm.
4671
+ - What content can now learn: each mark's `count`. Everything in a `show` (ids, anchors, counts)
4672
+ is posted into the frame's window, where the content can listen. So a host gives a count only
4673
+ where the page may know how many there are, and ids that say nothing (never a person's name or a
4674
+ comment's words). Who commented, and what, stays in the host's own bubble outside the frame.
4675
+ - What content can fake: an `activated` report for any mark the host shows with a count, without
4676
+ a click, and with any `rect` inside its frame (point 8); and look-alike markers drawn by its own elements (which
4677
+ report nothing unless it fakes one), or elements laid over Porthole's markers. The host takes a
4678
+ fake only for its own shown ids, at the bridge's rate. So `activated` opens the host's own view
4679
+ of that mark, placed near the rect within the frame's box, and never acts (no resolve, delete,
4680
+ approve or reply on it).
4681
+ - What content can tell: that a marker was pressed, and roughly where, though it gets none of the
4682
+ press's events. The pointer leaving its own element names the layer (`relatedTarget`), the layer
4683
+ matches `:hover` and `:active`, and the frame gets user activation. It can't act on the click or
4684
+ cancel it.
4685
+ - What content can do to the layer: not read or reach inside it (a closed shadow root), but hide,
4686
+ shrink, move or cover it. Its inline `!important` style holds against the content's style
4687
+ sheets, and is set again at each draw, but the content's scripts can rewrite it in between, lay
4688
+ elements over it, or transform the document it sits in. A host can't rely on a marker being
4689
+ seen.
4690
+ - The rate limit is shared: a page that floods reports can crowd out real ones; it could before.
4691
+ An honest page's follow-ups take at most 60 a minute (point 5).
4692
+
4693
+ **Tested.** `test/annotate.test.ts`: a count's bounds (0 and 999 kept; -1, 1.5, 1,000, NaN,
4694
+ Infinity, a string, null refused), the `activated` report's shape, and on `createHost` over a
4695
+ stand-in platform, a click taken only for a shown mark with a marker (an unknown id, a mark
4696
+ without a count, and after `clear`: dropped; malformed: `invalid`). `leak/annotate.spec.ts`, on
4697
+ Chromium, WebKit and Firefox: markers drawn with their numbers (read through Chromium's inspector:
4698
+ "", "3", "99+"; on all three, each wider with its number), a click on each reported with its id and
4699
+ box while none of the content's capture listeners, nor the element under it, hears it; a mark
4700
+ without a count takes no click; while picking, a click on a marker picks what is under it; a run of
4701
+ scrolls gives one report with only the marks that moved (a `position: fixed` one never), checked
4702
+ against the steps' measured pauses (P098), and a scroll down and back in the next frame gives none;
4703
+ a line inserted above one mark gives a report with that mark only, once quiet;
4704
+ a hostile page faking `activated` (no marks, an unknown id, a mark without a count, malformed: none
4705
+ taken; well-formed for a shown marker: taken, rebuilt), and its synthetic click on the layer
4706
+ reports nothing. After the review of 43768be: `clampRect`'s math (inside kept; overlapping, the
4707
+ part inside; wholly outside, no size on the nearest edge; an unknown or non-finite viewport,
4708
+ nothing at the corner; every result finite, inside and passing `parseRect`, over a grid of
4709
+ negative, fractional and huge inputs), the stand-in host clamping an `activated` box to its
4710
+ 600 by 400 viewport, and a hostile page's `activated` boxes (over the whole app; wholly outside),
4711
+ `selected` and `anchored` boxes reaching the host clamped to the frame's viewport; negative
4712
+ control `annotation-rect-clamp` (the clamp out) fails that case and the two that see a mark below
4713
+ the viewport on its edge. After the review of b19e2e8: a marker's double, right and middle click and the pointer's
4714
+ moves over it reach none of the content's listeners, and a selection and the focused input are as
4715
+ they were after its clicks; 140 wheel turns 200 ms apart (more than 120 settles) give at most 45
4716
+ follow-ups and no refusal, and a marker's click after them is reported (with one report per settle
4717
+ the same run gave 120 and the click was refused); a change every 40 ms for 0.9 s, cut short by the
4718
+ deadline, still reports where its last change moved the mark (nothing was reported before); a
4719
+ marker on an element at the frame's top is drawn whole and takes its click there. Negative
4720
+ controls (P032), in `scripts/controls.ts`: `annotation-activated` (the host's id check out) and
4721
+ `annotation-activated-count` (only its marker check out) fail the hostile case; `marker-trusted`
4722
+ (the shell's `isTrusted` check out) fails it too, by the content's synthetic click on the layer;
4723
+ `marker-click` (the shell's stop out) fails the markers case and the press case; each alone, on
4724
+ all three engines.
4725
+
4726
+ **Rejected.**
4727
+ - A style option per mark (marker only, underline only, colors): the host's policy is whether to
4728
+ give a count; a knob per look is surface without a threat or a need yet (PRINCIPLE 8).
4729
+ - Reporting every scroll frame: the bridge's 120 a minute (P053) would refuse most, and a host's
4730
+ bubble that follows each frame is a host that wants the frame's scroll position, not marks.
4731
+ - A budget of its own for `anchored`, apart from selections and clicks. It would take a second
4732
+ rate per capability in the bridge (a new mechanism), and it wouldn't protect against a hostile
4733
+ page, which can spend the shared budget with fakes of any kind anyway. Against an honest page
4734
+ the throttle is enough: its follow-ups take at most half.
4735
+ - Markers as buttons in the tab order (point 6).
4736
+ - Drawing the number with the CSS Custom Highlight API or in the content's DOM: P053's reasons.
4737
+ - A host-side id per marker distinct from the mark's: the mark's id is already the host's own, and
4738
+ already in the frame.
4739
+
4740
+ **Revisit when** a host needs a mark's box outside the viewport as it is (then a separate,
4741
+ named field, still never a place for the host's UI), a host needs markers reachable by keyboard
4742
+ inside the frame (then a focus model
4743
+ the content can't steal, likely the host's own overlay), a bubble must follow during a scroll (a
4744
+ coarser report, or the host drawing markers itself from `anchored`), or MCP Apps defines
4745
+ annotations.
package/docs/DESIGN.md CHANGED
@@ -1027,13 +1027,14 @@ chooses), and the annotation runtime is in the shell only then.
1027
1027
  |-----------|---------|--------|
1028
1028
  | host → frame | `porthole/annotate.start` | `{ elements, text }`: picking elements (the one under the pointer or finger outlined with its name; a click or tap picks it, never reaching the content; Escape cancels; one pick), selecting text (each settled selection), or both (a click picks, a drag selects) |
1029
1029
  | host → frame | `porthole/annotate.stop` | — |
1030
- | host → frame | `porthole/annotate.show` | `{ marks: [{ id, anchor }], active? }`: drawn over the content in the shell's own layer (a closed shadow root), found again whenever the content changes |
1030
+ | host → frame | `porthole/annotate.show` | `{ marks: [{ id, anchor, count? }], active? }`: drawn over the content in the shell's own layer (a closed shadow root), found again whenever the content changes; a mark with a `count` (0 to 999) also gets a marker (P104) |
1031
1031
  | host → frame | `porthole/annotate.focus` | `{ id }`: scrolled into view inside the frame, made the active mark, flashed |
1032
1032
  | host → frame | `porthole/annotate.clear` | — |
1033
1033
  | frame → host | `porthole/annotate.selected` | `{ anchor, rect }` |
1034
1034
  | frame → host | `porthole/annotate.unselected` | — (the text selection went away) |
1035
1035
  | frame → host | `porthole/annotate.cancelled` | — (Escape) |
1036
- | frame → host | `porthole/annotate.anchored` | `{ results: [{ id, state: "attached" \| "orphaned", rect? }] }`: every mark after `show`, the one after `focus`, and when the content changed, only if a state did |
1036
+ | 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 `count`, 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 (P104) |
1037
+ | frame → host | `porthole/annotate.activated` | `{ id, rect }`: the person clicked a mark's marker; `rect` is the marker's (P104) |
1037
1038
 
1038
1039
  - **Anchors** are W3C Web Annotation selectors, at most one of each:
1039
1040
  `CssSelector` (unique: the nearest id, else a path of `nth-of-type` steps),
@@ -1047,13 +1048,33 @@ chooses), and the annotation runtime is in the shell only then.
1047
1048
  selector is an id, or it has no words), else the element holding its words. What
1048
1049
  can't be found is `orphaned`, said so; a host keeps the comment and shows it apart.
1049
1050
  - **Rects** are in the frame's viewport, CSS px: add the frame element's position.
1051
+ They are the page's word: `createHost` clamps each to the frame's viewport before
1052
+ the host hears it (P104); a box wholly outside becomes one of no size on the
1053
+ nearest edge (a mark below the fold: `y` at the viewport's height, no height).
1054
+ - **Markers** (P104). A mark with a `count` gets a bubble glyph and its number ("99+"
1055
+ above 99; 0 the bubble alone) at the end of a text anchor's last line, raised, or on
1056
+ an element's top right corner, inside the frame's width; its element mark is then a
1057
+ thin line. The layer takes no pointer but on markers: a press on one, and the
1058
+ pointer's moves over it, are stopped in the shell's first window listener (none of
1059
+ the content's handlers, nor what is under it, gets them; the content can still tell
1060
+ a press happened, by `:active`, `relatedTarget` and user activation) and a trusted
1061
+ click is reported `activated`. Markers step aside
1062
+ while elements are picked. No tab stop, and the layer stays `aria-hidden`: the
1063
+ host's own list of marks is the keyboard path.
1064
+ - **Following** (P104), only while a mark has a `count`. Each mark keeps what the
1065
+ host was last told (state and box); a settled scroll or resize (any scroller), or
1066
+ a quiet run of content changes (one the deadline cut short is checked once quiet),
1067
+ reports only what moved, at most once a second (the latest), so honest scrolling
1068
+ takes at most half of the bridge's 120 a minute.
1050
1069
  - **Settled.** Nothing is reported before the content is in place (marks shown
1051
1070
  before it arrives are anchored once it has), nor while a run of changes settles; a
1052
1071
  `focus` asked for meanwhile waits for anchoring, then scrolls and reports, so a
1053
1072
  focus right after `show` says where the mark is, never `orphaned` first (P057).
1054
1073
  - **Trust.** The shell shares its realm with the content, which can interfere with
1055
- all of it or fake any report. The host takes a selection only while it asked for
1056
- that kind, a cancel only while picking, results only for its own marks; it
1074
+ all of it, read what `show` sends (ids, anchors, counts), or fake any report. The
1075
+ host takes a selection only while it asked for that kind, a cancel only while
1076
+ picking, results only for its own marks, a marker's click only for a mark it shows
1077
+ with a count; it
1057
1078
  rebuilds each from known fields within `ANNOTATION_LIMITS` and drops the rest,
1058
1079
  through the bridge's rate limit. UI hints only, never permissions: what a
1059
1080
  report says decides where a comment is drawn, never who may see or do anything.
@@ -1069,7 +1090,16 @@ view, one orphaned, all cleared; re-anchoring on a revised page (by id, by words
1069
1090
  moved, by words respaced, one deleted and orphaned); live changes reported only as
1070
1091
  they change; an MCP Apps view; and a hostile page faking every report (not asked,
1071
1092
  malformed, too large, the wrong kind, no such mark, a flood), whose negative
1072
- control is `annotation-checks`.
1093
+ control is `annotation-checks`. Markers (P104): drawn with their numbers, a click
1094
+ reported with its id and box and heard by none of the content's listeners, nor a
1095
+ double, right or middle click, focus and selection kept (`marker-click` → those
1096
+ two cases), none without a count, stepping aside while picking, drawn whole at the
1097
+ frame's top; a run of scrolls reported with only the marks that moved, a fixed one
1098
+ never; a long honest scroll session leaving a marker's click its budget; a content
1099
+ change that moves one mark reports it alone, even when the deadline cut its run
1100
+ short; and a hostile page faking a marker's click for no mark, an unknown id or a
1101
+ mark without a marker, or clicking the layer itself (`annotation-activated`,
1102
+ `annotation-activated-count`, `marker-trusted` → that case).
1073
1103
 
1074
1104
  ## The shell runtime
1075
1105
 
@@ -5,8 +5,8 @@ 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.8.0 (2026-10-20). A review on 2026-10-19 found gaps, and every
9
- decision it led to has merged but P096. A note **open until P096** means the gap exists in 0.8.0 and
8
+ **Status.** This describes Porthole 0.9.0 (2026-10-20). A review on 2026-10-19 found gaps, and every
9
+ decision it led to has merged but P096. A note **open until P096** means the gap exists in 0.9.0 and
10
10
  P096 is its planned fix; once it merges, the note becomes a guarantee. [§8](#8-fixes-in-flight)
11
11
  lists the decisions.
12
12
 
@@ -142,6 +142,8 @@ Whatever the use:
142
142
  host's own UI. A copy notice of its own shows what went on the clipboard (S1).
143
143
  - Show the text content reports (its errors, a blocked navigation's address, an annotation's
144
144
  quoted text) only as text, never as HTML.
145
+ - Take what the frame reports about annotations as UI hints (where to draw, what to open), never
146
+ as permissions, and put nothing in a mark the page may not know (§7).
145
147
  - List every app origin in `appOrigins` (`hostOrigins` in `/server`): only those may frame content,
146
148
  and only those are checked against the content domain for a shared site.
147
149
  - Under the app runtime, run `defineRuntimeConformance` with `api` in CI (§7).
@@ -526,6 +528,40 @@ wall on three engines, and `defineHostConformance` runs it against a host's own
526
528
  **The host must** do what [every host](#what-every-host-must-do) does, write the handlers (their
527
529
  effects are its own), and group displays by page (S7).
528
530
 
531
+ **Annotations** (`annotate`, P053, P104). The shell that draws marks and reports anchors shares
532
+ its realm with the content, so:
533
+
534
+ - *What content learns.* Everything the host sends in a `show` is posted into the frame's window,
535
+ where the content can listen: each mark's id, anchor and, where given, `count` (the number on
536
+ its marker). A host gives ids that say nothing (never a person's name or a comment's words), and
537
+ a count only where the page may know how many there are. Who commented and what they wrote stay
538
+ in the host's own UI, outside the frame.
539
+ - *What content can fake.* Any report: a selection while the host asks for one, where marks are,
540
+ and a marker's click (`activated`) for any mark the host shows with a count, with no click and
541
+ any box. It can draw look-alike markers, or lay its own elements over Porthole's. The host takes
542
+ each report only for what it asked for and its own shown ids, rebuilt within
543
+ `ANNOTATION_LIMITS`, at 120 a minute; `activated` for a mark without a marker, or an id it
544
+ doesn't show, is dropped (negative control `annotation-activated`).
545
+ - *Boxes.* Every box a report carries (`selected`, `activated`, `anchored`) is the page's word.
546
+ Porthole clamps each to the frame's viewport as it is when the report arrives, before the host
547
+ hears it: the part inside is kept, and a box wholly outside becomes one of no size on the
548
+ nearest edge (control `annotation-rect-clamp`). So a page can't make the host place its own UI
549
+ over the rest of the app. It still chooses any point inside its own frame: a box is a
550
+ positioning hint, never a fact about the content.
551
+ - *What holds.* A real press or click on a marker reaches none of the content's handlers (the
552
+ shell's first listener stops it; control `marker-click`), so content can't act on it or cancel
553
+ it. But content can tell that a marker was pressed, and roughly where: the pointer leaving its
554
+ own element names the layer, the layer matches `:hover` and `:active`, and the frame gets user
555
+ activation.
556
+ - *What doesn't.* Content can't read or reach inside the shell's layer (a closed shadow root),
557
+ but it can hide, shrink, move or cover it (its scripts can rewrite the layer's style, lay
558
+ elements over it, or transform the page it sits in), change its words so a mark is orphaned, or
559
+ flood the shared rate so real reports are refused. An honest page's follow-up reports (after a
560
+ scroll) are at most one a second, and only while a mark has a marker.
561
+ - So `activated` opens the host's own view of a mark it already shows, placed within the frame's
562
+ box, and never acts on it (no resolve, delete or reply); an anchor or a rect decides where
563
+ something is drawn, never who may see or do anything.
564
+
529
565
  ### The app runtime
530
566
 
531
567
  What it is: `config.runtime: "1"`, for inline widgets and artifact pages. A page reaches the
@@ -584,7 +620,7 @@ section.
584
620
 
585
621
  ## 8. Fixes in flight
586
622
 
587
- The decisions below come from the 2026-10-19 review. "Planned" means not in 0.8.0: the gap its
623
+ The decisions below come from the 2026-10-19 review. "Planned" means not in 0.9.0: the gap its
588
624
  row names exists today, and the sections it cites say "open until" that decision. Each merged row
589
625
  says what was wrong, what holds now, and the limit its decision accepts, if any.
590
626
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.8.0",
3
+ "version": "0.9.0",
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": {
@@ -1,6 +1,7 @@
1
1
  /**
2
2
  * Annotations (P053): a person points at part of a display (an element, or text they select) to
3
- * comment on it, and the host marks the anchors already made. The host drives the shell with
3
+ * comment on it, and the host marks the anchors already made, each with a clickable marker and a
4
+ * number where it gives a count (P104). The host drives the shell with
4
5
  * Porthole's own messages (`porthole/annotate.*`); the shell answers with anchors and where they
5
6
  * are. An anchor is a set of W3C Web Annotation selectors, so it can be found again after the
6
7
  * content changes; finding it is best-effort, and says so (`orphaned`).
@@ -46,7 +47,11 @@ export interface AnnotationAnchor {
46
47
  readonly label: string;
47
48
  }
48
49
 
49
- /** A box in the frame's viewport, CSS px: add the frame element's position to place it on the page. */
50
+ /**
51
+ * A box in the frame's viewport, CSS px: add the frame element's position to place it on the page.
52
+ * The page's word: the host clamps each it reports to the frame's viewport (P104), so one wholly
53
+ * outside is a box of no size on the nearest edge. A positioning hint only.
54
+ */
50
55
  export interface AnnotationRect {
51
56
  readonly x: number;
52
57
  readonly y: number;
@@ -62,10 +67,21 @@ export interface AnnotateMode {
62
67
  readonly text?: boolean;
63
68
  }
64
69
 
65
- /** An anchor the host marks in the frame, under its own id. */
70
+ /**
71
+ * An anchor the host marks in the frame, under its own id. Everything here is sent into the
72
+ * frame, so the content can read it: give ids that say nothing (never a person's name or the
73
+ * comment's words).
74
+ */
66
75
  export interface AnnotationMark {
67
76
  readonly id: string;
68
77
  readonly anchor: AnnotationAnchor;
78
+ /**
79
+ * A marker (P104): with a count, the shell also draws a small bubble with this number (0 to
80
+ * `ANNOTATION_LIMITS.count`; above 99 it reads "99+", 0 draws the bubble alone) at the end of a
81
+ * text anchor and the top right of an element. The person can click it: the frame reports
82
+ * `activated`. The content can read the number; give one only where the page may know it.
83
+ */
84
+ readonly count?: number;
69
85
  }
70
86
 
71
87
  /** Whether a mark's anchor was found in the content as it is now. */
@@ -90,8 +106,20 @@ export type AnnotationReport =
90
106
  | { readonly type: "unselected" }
91
107
  /** The person pressed Escape while picking an element. */
92
108
  | { readonly type: "cancelled" }
93
- /** Where the marked anchors are now, after `show`, `focus`, or a change of the content. */
94
- | { readonly type: "anchored"; readonly results: readonly AnchorResult[] };
109
+ /**
110
+ * Where the marked anchors are now: every mark after `show`, the focused one after `focus`,
111
+ * every mark when the content changed one's state, and, while any mark has a `count`, once a
112
+ * scroll, a resize or a change of the content has settled, only the marks that moved since the
113
+ * host was last told, at most once a second (P104).
114
+ */
115
+ | { readonly type: "anchored"; readonly results: readonly AnchorResult[] }
116
+ /**
117
+ * The person clicked the marker of a mark the host shows with a `count` (P104); `rect` is the
118
+ * marker's box, to open the host's own UI beside it. The content can fake it for any mark the
119
+ * host shows with a count, and can tell a real one happened: open the host's own view of that
120
+ * mark, never act on it.
121
+ */
122
+ | { readonly type: "activated"; readonly id: string; readonly rect: AnnotationRect };
95
123
 
96
124
  /** Porthole's own messages for annotations (own-prefixed, P002). */
97
125
  export const ANNOTATE_METHODS = {
@@ -110,6 +138,8 @@ export const ANNOTATE_METHODS = {
110
138
  unselected: "porthole/annotate.unselected",
111
139
  cancelled: "porthole/annotate.cancelled",
112
140
  anchored: "porthole/annotate.anchored",
141
+ /** Frame → host: a mark's marker was clicked (P104). */
142
+ activated: "porthole/annotate.activated",
113
143
  } as const;
114
144
 
115
145
  /** The most of each part of an anchor or report the host takes. */
@@ -123,4 +153,6 @@ export const ANNOTATION_LIMITS = {
123
153
  id: 128,
124
154
  position: 50_000_000,
125
155
  coordinate: 10_000_000,
156
+ /** The largest `count` a mark's marker takes (P104). */
157
+ count: 999,
126
158
  } as const;
@@ -106,6 +106,26 @@ export function parseRect(value: unknown): AnnotationRect | null {
106
106
  return { x, y, width, height };
107
107
  }
108
108
 
109
+ /**
110
+ * A box the frame reported, clamped to the frame's viewport (`width` by `height`, CSS px, P104):
111
+ * each side is held within it, so what overlaps the viewport keeps the part inside, and what lies
112
+ * wholly outside becomes a box of no size on the nearest edge. Where the viewport isn't known, a
113
+ * box of no size at the frame's corner. The page still chooses any point inside its own frame.
114
+ */
115
+ export function clampRect(
116
+ rect: AnnotationRect,
117
+ viewport: { readonly width: number; readonly height: number } | undefined,
118
+ ): AnnotationRect {
119
+ const width = viewport !== undefined && Number.isFinite(viewport.width) ? viewport.width : 0;
120
+ const height = viewport !== undefined && Number.isFinite(viewport.height) ? viewport.height : 0;
121
+ const within = (value: number, most: number) => Math.min(Math.max(value, 0), Math.max(0, most));
122
+ const left = within(rect.x, width);
123
+ const top = within(rect.y, height);
124
+ const right = within(rect.x + rect.width, width);
125
+ const bottom = within(rect.y + rect.height, height);
126
+ return { x: left, y: top, width: right - left, height: bottom - top };
127
+ }
128
+
109
129
  const markId = (value: unknown): value is string => text(value, LIMITS.id, 1);
110
130
 
111
131
  function results(value: unknown): AnchorResult[] | null {
@@ -152,6 +172,10 @@ export function parseReport(value: unknown): AnnotationReport | null {
152
172
  const checked = results(value.results);
153
173
  return checked === null ? null : { type: "anchored", results: checked };
154
174
  }
175
+ case "activated": {
176
+ const rect = parseRect(value.rect);
177
+ return !markId(value.id) || rect === null ? null : { type: "activated", id: value.id, rect };
178
+ }
155
179
  default:
156
180
  return null;
157
181
  }
@@ -180,7 +204,12 @@ export function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[] {
180
204
  `annotations.show: mark ${index} needs a unique id (1 to ${LIMITS.id} characters) and a valid anchor`,
181
205
  );
182
206
  }
207
+ if (mark.count !== undefined && !count(mark.count, LIMITS.count)) {
208
+ throw new TypeError(
209
+ `annotations.show: mark ${index}'s count is a whole number from 0 to ${LIMITS.count}`,
210
+ );
211
+ }
183
212
  seen.add(mark.id);
184
- return { id: mark.id, anchor };
213
+ return { id: mark.id, anchor, ...(mark.count === undefined ? {} : { count: mark.count }) };
185
214
  });
186
215
  }
@@ -4,7 +4,7 @@ import {
4
4
  type AnnotationMark,
5
5
  type AnnotationReport,
6
6
  } from "../annotate/types.ts";
7
- import { annotateMode, checkMarks, parseReport } from "../annotate/validate.ts";
7
+ import { annotateMode, checkMarks, clampRect, parseReport } from "../annotate/validate.ts";
8
8
  import {
9
9
  createBridge,
10
10
  onceConsent,
@@ -58,6 +58,7 @@ const REPORTS: Readonly<Record<string, AnnotationReport["type"]>> = {
58
58
  [ANNOTATE_METHODS.unselected]: "unselected",
59
59
  [ANNOTATE_METHODS.cancelled]: "cancelled",
60
60
  [ANNOTATE_METHODS.anchored]: "anchored",
61
+ [ANNOTATE_METHODS.activated]: "activated",
61
62
  };
62
63
 
63
64
  const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -193,9 +194,33 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
193
194
  toFrame(ANNOTATE_METHODS.start, { ...annotating });
194
195
  }
195
196
  };
197
+ /**
198
+ * Every box a report carries, clamped to the frame's viewport as it is now (P104): the page
199
+ * places the host's own UI nowhere outside its frame.
200
+ */
201
+ const withinFrame = (report: AnnotationReport): AnnotationReport => {
202
+ const viewport = surface?.viewport?.();
203
+ switch (report.type) {
204
+ case "selected":
205
+ case "activated":
206
+ return { ...report, rect: clampRect(report.rect, viewport) };
207
+ case "anchored":
208
+ return {
209
+ type: "anchored",
210
+ results: report.results.map((result) =>
211
+ result.rect === undefined
212
+ ? result
213
+ : { ...result, rect: clampRect(result.rect, viewport) },
214
+ ),
215
+ };
216
+ default:
217
+ return report;
218
+ }
219
+ };
196
220
  /**
197
221
  * A report from the frame: checked, taken only while the host asked for it (a selection
198
- * only in select mode, results only for its own marks), then through the bridge's gates.
222
+ * only in select mode, results only for its own marks, a marker's click only for a mark it
223
+ * shows with one), then through the bridge's gates.
199
224
  */
200
225
  const onAnnotation = (raw: unknown, through: HostFunctionBridge) => {
201
226
  if (
@@ -250,8 +275,15 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
250
275
  report = { type: "anchored", results };
251
276
  break;
252
277
  }
278
+ case "activated": {
279
+ const { id } = report;
280
+ if (!marks.some((mark) => mark.id === id && mark.count !== undefined)) {
281
+ return;
282
+ }
283
+ break;
284
+ }
253
285
  }
254
- void through.call("annotate", report);
286
+ void through.call("annotate", withinFrame(report));
255
287
  };
256
288
  const needsAnnotate = (operation: string) => {
257
289
  if (!annotates) {
@@ -38,6 +38,12 @@ export interface Surface {
38
38
  * activates its ancestors), or undefined where the platform can't tell.
39
39
  */
40
40
  userActivation(): boolean | undefined;
41
+ /**
42
+ * The frame's viewport now, CSS px (its content box): what a box the frame reports is clamped
43
+ * to (P104). Undefined, or absent, where the platform can't tell: every reported box is then
44
+ * clamped to nothing, at the frame's corner.
45
+ */
46
+ viewport?(): { readonly width: number; readonly height: number } | undefined;
41
47
  /**
42
48
  * The frame loaded a document other than the one it was given: the content navigated it. The
43
49
  * framework starts it again from its content and reports it.
@@ -84,6 +84,16 @@ export const webPlatform: PlatformHost = {
84
84
  setColorScheme(scheme: ColorScheme) {
85
85
  frame.style.colorScheme = scheme;
86
86
  },
87
+ viewport() {
88
+ const style = view.getComputedStyle(frame);
89
+ const width =
90
+ frame.clientWidth - parseFloat(style.paddingLeft) - parseFloat(style.paddingRight);
91
+ const height =
92
+ frame.clientHeight - parseFloat(style.paddingTop) - parseFloat(style.paddingBottom);
93
+ return Number.isFinite(width) && Number.isFinite(height)
94
+ ? { width: Math.max(0, width), height: Math.max(0, height) }
95
+ : undefined;
96
+ },
87
97
  userActivation() {
88
98
  const activation = (
89
99
  view.navigator as Navigator & { userActivation?: { isActive: boolean } }
@@ -585,7 +585,10 @@ export interface PortholeFrameProps {
585
585
  * again to pick again.
586
586
  */
587
587
  readonly annotating?: AnnotateMode | null;
588
- /** The anchors to mark in the frame (the host's comments). Keep it stable (memoized). */
588
+ /**
589
+ * The anchors to mark in the frame (the host's comments). A mark with a `count` gets a
590
+ * clickable marker (P104). Compared by value.
591
+ */
589
592
  readonly annotations?: readonly AnnotationMark[];
590
593
  /**
591
594
  * The mark to bring into view and make the active one; each new id focuses it. To focus the
@@ -597,7 +600,8 @@ export interface PortholeFrameProps {
597
600
  | null;
598
601
  /**
599
602
  * What the frame reported: a selection (an anchor and where it is), its clearing, a cancelled
600
- * pick, where marks are. The content's word: UI hints, never permissions.
603
+ * pick, where marks are (again once a scroll settles: those that moved), a marker clicked
604
+ * (`activated`). The content's word: UI hints, never permissions.
601
605
  */
602
606
  readonly onAnnotation?: (report: AnnotationReport) => void;
603
607
  /** Draws the placeholder instead of the default one. */