@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/dist/annotate/types.d.ts +40 -4
- package/dist/annotate/types.js +6 -1
- package/dist/annotate/validate.d.ts +10 -0
- package/dist/annotate/validate.js +24 -1
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +33 -3
- package/dist/platform/types.d.ts +9 -0
- package/dist/platform/web.js +8 -0
- package/dist/react/frame.d.ts +6 -2
- package/dist/shell/annotate.d.ts +7 -2
- package/dist/shell/annotate.js +233 -15
- package/docs/ARCHITECTURE.md +2 -1
- package/docs/DECISIONS.md +155 -1
- package/docs/DESIGN.md +35 -5
- package/docs/THREAT_MODEL.md +39 -3
- package/package.json +1 -1
- package/src/annotate/types.ts +37 -5
- package/src/annotate/validate.ts +30 -1
- package/src/host/create-host.ts +35 -3
- package/src/platform/types.ts +6 -0
- package/src/platform/web.ts +10 -0
- package/src/react/frame.tsx +6 -2
- package/src/shell/annotate.ts +233 -15
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`,
|
|
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
|
|
1056
|
-
|
|
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
|
|
package/docs/THREAT_MODEL.md
CHANGED
|
@@ -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.
|
|
9
|
-
decision it led to has merged but P096. A note **open until P096** means the gap exists in 0.
|
|
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.
|
|
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.
|
|
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": {
|
package/src/annotate/types.ts
CHANGED
|
@@ -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
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
94
|
-
|
|
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;
|
package/src/annotate/validate.ts
CHANGED
|
@@ -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
|
}
|
package/src/host/create-host.ts
CHANGED
|
@@ -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
|
|
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) {
|
package/src/platform/types.ts
CHANGED
|
@@ -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.
|
package/src/platform/web.ts
CHANGED
|
@@ -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 } }
|
package/src/react/frame.tsx
CHANGED
|
@@ -585,7 +585,10 @@ export interface PortholeFrameProps {
|
|
|
585
585
|
* again to pick again.
|
|
586
586
|
*/
|
|
587
587
|
readonly annotating?: AnnotateMode | null;
|
|
588
|
-
/**
|
|
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
|
|
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. */
|