@botiverse/porthole 0.14.9 → 0.14.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +39 -0
- package/dist/annotate/types.d.ts +62 -13
- package/dist/annotate/types.js +1 -1
- package/dist/annotate/validate.d.ts +6 -1
- package/dist/annotate/validate.js +57 -4
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +5 -3
- package/dist/host/types.d.ts +3 -1
- package/dist/index.d.ts +2 -2
- package/dist/index.js +1 -1
- package/dist/react/frame.d.ts +2 -1
- package/dist/shell/annotate.d.ts +13 -5
- package/dist/shell/annotate.js +259 -48
- package/dist/shell/find.d.ts +1 -1
- package/dist/shell/find.js +1 -1
- package/docs/ADOPTING.md +60 -3
- package/docs/ARCHITECTURE.md +4 -3
- package/docs/DECISIONS.md +204 -2
- package/docs/DESIGN.md +61 -17
- package/docs/THREAT_MODEL.md +37 -3
- package/package.json +1 -1
- package/src/annotate/types.ts +72 -15
- package/src/annotate/validate.ts +65 -4
- package/src/host/create-host.ts +5 -3
- package/src/host/types.ts +3 -1
- package/src/index.ts +2 -1
- package/src/react/frame.tsx +2 -1
- package/src/shell/annotate.ts +259 -48
- package/src/shell/find.ts +1 -1
package/docs/ADOPTING.md
CHANGED
|
@@ -251,9 +251,10 @@ createHost(config, {
|
|
|
251
251
|
With `annotate` declared (`capabilities: { annotate: {} }`), a host lets people point at a
|
|
252
252
|
display and keeps its comments beside it ([P053](DECISIONS.md), P104). Everything the frame
|
|
253
253
|
reports is the page's word: a hint where to draw, never a permission. A mark's `count` puts a
|
|
254
|
-
numbered marker
|
|
255
|
-
|
|
256
|
-
|
|
254
|
+
numbered marker, a button, at the end of its words' paragraph (P133); a click on one, or Enter or
|
|
255
|
+
Space with the keyboard on it, is `activated`. A draft, a comment its author hasn't posted yet
|
|
256
|
+
(`kind: "draft"`, P107), is drawn apart, beside its own words: a dashed line and a hollow marker
|
|
257
|
+
with no number, which is clicked and followed as a posted one is.
|
|
257
258
|
|
|
258
259
|
```js
|
|
259
260
|
display.annotations.show([
|
|
@@ -385,6 +386,62 @@ composer.onClose(() => display.annotations.clearSelection());
|
|
|
385
386
|
position. A frame you scale or transform (a thumbnail, a zoomed preview) needs the box mapped
|
|
386
387
|
through that transform too (`frame.getBoundingClientRect().width / frame.clientWidth` for a
|
|
387
388
|
plain scale), or your view lands off by the difference.
|
|
389
|
+
- **Places in the document** (P132): for UI that lines up with marks outside the frame's view
|
|
390
|
+
(comment cards in a margin beside a scrolling page), a newer shell gives each attached result a
|
|
391
|
+
`documentRect` (its box in the document: it doesn't move as the page scrolls, and isn't clamped)
|
|
392
|
+
and each `anchored` report the `scroll` it was read at; `tracked` carries both too, so following
|
|
393
|
+
one mark (`track`) tells the scroll at every animation frame where it changed, whether that mark
|
|
394
|
+
is in view or not. A mark's top in the frame's viewport is then `documentRect.y - scroll.y`, with
|
|
395
|
+
no need to ask again as the page scrolls. The numbers are the page's word, and unclamped: clip
|
|
396
|
+
what you draw from them to the frame's box, or to your own region beside it. An older shell sends
|
|
397
|
+
neither: test for `scroll` and keep the viewport boxes' way where it is absent.
|
|
398
|
+
|
|
399
|
+
```js
|
|
400
|
+
const tops = new Map(); // mark id → its top in the document
|
|
401
|
+
let scrollY = null; // null: an older shell, places by `rect` only
|
|
402
|
+
display.on("annotation", (report) => {
|
|
403
|
+
if (report.type !== "anchored" && report.type !== "tracked") return;
|
|
404
|
+
if (report.scroll) scrollY = report.scroll.y;
|
|
405
|
+
if (report.type === "anchored") {
|
|
406
|
+
for (const result of report.results) {
|
|
407
|
+
if (result.documentRect) tops.set(result.id, result.documentRect.y);
|
|
408
|
+
else tops.delete(result.id); // orphaned
|
|
409
|
+
}
|
|
410
|
+
}
|
|
411
|
+
if (scrollY !== null) margin.place(tops, scrollY); // card top: frame top + top - scrollY, clipped
|
|
412
|
+
});
|
|
413
|
+
display.annotations.track(anyShownMarkId); // its reports carry the scroll
|
|
414
|
+
```
|
|
415
|
+
|
|
416
|
+
A page that scrolls a box of its own rather than its document moves the places of the marks in
|
|
417
|
+
it as it scrolls; show again (or follow such a mark) to hear them again.
|
|
418
|
+
- **After the last line** (P133): for UI after a selection's or a mark's words rather than beside
|
|
419
|
+
their whole box (a composer's button, a card), a newer shell gives `selected`, each attached
|
|
420
|
+
result and `tracked` a `lastLineDocumentRect`: the last line with words on it, in the document's
|
|
421
|
+
coordinates (an element's whole box: it has no lines), unclamped as `documentRect` is. `selected`
|
|
422
|
+
carries the `scroll` it was read at too; an `anchored` report and `tracked` already do. A line's
|
|
423
|
+
end in the frame's viewport is `x + width - scroll.x`, its bottom `y + height - scroll.y`. Clip
|
|
424
|
+
what you draw from it, as above, and keep `rect` where it is absent (an older shell):
|
|
425
|
+
|
|
426
|
+
```js
|
|
427
|
+
display.on("annotation", (report) => {
|
|
428
|
+
if (report.type !== "selected") return;
|
|
429
|
+
const line = report.lastLineDocumentRect;
|
|
430
|
+
const at = line
|
|
431
|
+
? { x: line.x + line.width - report.scroll.x, y: line.y + line.height - report.scroll.y }
|
|
432
|
+
: { x: report.rect.x + report.rect.width, y: report.rect.y + report.rect.height };
|
|
433
|
+
composer.openAt(frame, clipToFrame(at), report.anchor); // the frame's px: clip them, then add its position
|
|
434
|
+
});
|
|
435
|
+
```
|
|
436
|
+
- **The keyboard** (P133): each marker is a button in the frame's Tab order, after the page's own
|
|
437
|
+
stops, in reading order, named for what it is ("3 comments on …", from the `count` and the
|
|
438
|
+
anchor's `label`; in English, whatever your UI's language). Enter or Space on it is `activated`,
|
|
439
|
+
through the same path and the same gesture check as a click: nothing to handle apart. It is the
|
|
440
|
+
page's focus order, which a page can steal from or hide a marker from, and it is one more
|
|
441
|
+
`activated` the content can time: keep your own list of marks as the way a keyboard can rely on,
|
|
442
|
+
with `annotations.focus(id)` to bring one into view, and leave your view's guard as it is (it
|
|
443
|
+
takes no key for 500 ms either, and takes no focus: Enter again on the marker is one more
|
|
444
|
+
`activated`).
|
|
388
445
|
- **Labels and quotes are the page's text**: shown only as text. Porthole takes out of a label what
|
|
389
446
|
the person can't see; a quote (`exact`) keeps it, to be found again. Hand either to a model only
|
|
390
447
|
as the page's words.
|
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -326,9 +326,10 @@ several displays on one page are in [THREAT_MODEL.md](THREAT_MODEL.md).
|
|
|
326
326
|
`/server` from the host's store at `/_blob/<id>` on the artifact's origin.
|
|
327
327
|
- **Annotations** (`annotate`): the host drives a select mode and marks anchors in
|
|
328
328
|
the shell; anchors are W3C Web Annotation selectors a host stores with its own
|
|
329
|
-
comments (P053). A mark may carry a count, drawn as a
|
|
330
|
-
the host hears and answers with its own UI outside
|
|
331
|
-
draft, its author's unposted comment, drawn apart with a
|
|
329
|
+
comments (P053). A mark may carry a count, drawn as a marker, a button at its
|
|
330
|
+
paragraph's end (P133), whose click the host hears and answers with its own UI outside
|
|
331
|
+
the frame (P104), and may be a draft, its author's unposted comment, drawn apart with a
|
|
332
|
+
hollow marker (P107).
|
|
332
333
|
- **Find in page** (`find`): the host draws its own find bar and asks the shell for
|
|
333
334
|
a query (`porthole/find.query`, a request: how many matches, which is current);
|
|
334
335
|
the shell finds it in the same text index annotations read, highlights it in a layer
|
package/docs/DECISIONS.md
CHANGED
|
@@ -4595,7 +4595,7 @@ second wall on a tab); a host needs a served page to open windows from a tab (th
|
|
|
4595
4595
|
`'self'` default (it joins `FRAME_DENIED_FEATURES`); or WebKit and Firefox apply
|
|
4596
4596
|
`Permissions-Policy` to these features (the shell's device locks become the second wall there too).
|
|
4597
4597
|
|
|
4598
|
-
## P104 · 2026-10-20 · Annotation markers: a number at an anchor, a click the host hears, marks that follow a scroll · Accepted; amended by P105, P107, P116
|
|
4598
|
+
## P104 · 2026-10-20 · Annotation markers: a number at an anchor, a click the host hears, marks that follow a scroll · Accepted; amended by P105, P107, P116, P133
|
|
4599
4599
|
|
|
4600
4600
|
A host that shows its comments beside an artifact page wants, at each comment's anchor in the page,
|
|
4601
4601
|
a small marker (a bubble and how many comments are there) that scrolls with the content; a click on
|
|
@@ -4873,7 +4873,7 @@ when someone remembered, and what DESIGN.md said they fail had drifted from what
|
|
|
4873
4873
|
a control's run makes a CI job too long (shard the controls across jobs), or the kit's app gains
|
|
4874
4874
|
a weakening seam (then its controls join the registry).
|
|
4875
4875
|
|
|
4876
|
-
## P105 · 2026-10-20 · After the review of P104: a marker's click within a gesture and the host's view guarded, one clock for follow-ups, text markers beside their line · Accepted
|
|
4876
|
+
## P105 · 2026-10-20 · After the review of P104: a marker's click within a gesture and the host's view guarded, one clock for follow-ups, text markers beside their line · Accepted; amended by P133
|
|
4877
4877
|
|
|
4878
4878
|
Amends P104 (its points 1, 3, 5 and 7, and its Trust) and P053's Trust. From the independent
|
|
4879
4879
|
review of P104 and 0.9.0 (botiverse/porthole#37: no P0 or P1, two P2s, six P3s) and from #36
|
|
@@ -7531,3 +7531,205 @@ 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.
|
|
7599
|
+
|
|
7600
|
+
## P133 · 2026-11-06 · Markers are labelled buttons, a posted comment's sits at its paragraph's end, and reports say where the last line is · Accepted
|
|
7601
|
+
|
|
7602
|
+
Amends P104 (its point 6, and its "Revisit when" on a keyboard inside the frame) and P105 (its
|
|
7603
|
+
point 3, for posted text marks, and P2-B's click listener on each marker). Three follow-ups for
|
|
7604
|
+
comment markers, from a host (Raft web):
|
|
7605
|
+
|
|
7606
|
+
- A marker can't be reached from the keyboard or named by assistive technology (P104 point 6
|
|
7607
|
+
chose that, and named this as what would reopen it).
|
|
7608
|
+
- A marker beside the anchor's last line, in the gutter, sits between the lines of a paragraph
|
|
7609
|
+
someone is reading, up to the column's width from its words (P105 point 3 said so); the host
|
|
7610
|
+
wants it where the paragraph ends.
|
|
7611
|
+
- A host that puts its own UI after a selection's last line has only the selection's whole box:
|
|
7612
|
+
`rect` ends at the widest line's right, not where the words end, and it is clamped.
|
|
7613
|
+
|
|
7614
|
+
**Decision.**
|
|
7615
|
+
|
|
7616
|
+
1. **A marker is a real button.** A `<button type="button">` with an explicit tab stop (`tabindex`:
|
|
7617
|
+
Safari's Tab otherwise skips one) and a name that says what it is: `aria-label` "3 comments on
|
|
7618
|
+
…", "1 comment on …", "Comment on …" for a count of 0, "Draft comment on …", with the mark's
|
|
7619
|
+
`anchor.label`. The layer is no longer `aria-hidden`: its marks and its outline are, so the
|
|
7620
|
+
markers are all assistive technology finds in it. A marker's styles take off what a browser
|
|
7621
|
+
gives a button, and it has a focus ring of its own. Markers go in the page's reading order
|
|
7622
|
+
(each finding reads where each mark starts, as `order` does), which is the Tab key's: after the
|
|
7623
|
+
page's own stops, since the layer is the document's last child. A marker that stays in its
|
|
7624
|
+
place isn't touched, and none moves while one has the focus.
|
|
7625
|
+
2. **The existing path, from the keyboard.** Enter and Space make the button's own trusted click,
|
|
7626
|
+
which reaches the shell's first window listener as a pointer's does, retargeted to the layer. It
|
|
7627
|
+
has no click count and no point (0, 0, or the like), so the hit test can't place it: a trusted
|
|
7628
|
+
click with `detail` 0 is the focused marker's, read through the closed shadow root's
|
|
7629
|
+
`activeElement` by the platform's getter, kept before content runs, and otherwise goes on to the
|
|
7630
|
+
hit test as ever (assistive technology that clicks an element without focusing it is missed:
|
|
7631
|
+
see Revisit). `activated`, its `rect` (the marker's box), the
|
|
7632
|
+
host's id check and its gesture check are unchanged: a real key gives the host's page transient
|
|
7633
|
+
activation as a click does (as the HTML standard says for a key but Escape; unmeasured here, see
|
|
7634
|
+
Tested). While elements are picked a marker takes itself out of the Tab order (`tabindex` -1) and
|
|
7635
|
+
a click on one reports nothing, as the pointer's goes past it.
|
|
7636
|
+
3. **Enter and Space are stopped as a press is**, in the window's first listener, read through
|
|
7637
|
+
kept getters, on all of keydown, keypress and keyup while their target is the layer: the content
|
|
7638
|
+
neither hears them nor cancels the click. Every other key stays the page's, as on a button of its
|
|
7639
|
+
own: Tab, Escape (which the shell's own picking and selecting hear after this), and the host's
|
|
7640
|
+
find shortcut. A repeat of either is cancelled: a key held down clicks once, where 30 clicks a
|
|
7641
|
+
second would spend the bridge's 120 a minute on one press.
|
|
7642
|
+
4. **The focus stays while the page redraws.** A draw hit-tests places with the markers out of the
|
|
7643
|
+
display (P105), which loses a focused one, on every scroll. While one has the focus they only
|
|
7644
|
+
take no pointer (`pointer-events`, so the tests skip them): dearer for that time, as P105 measured
|
|
7645
|
+
(0.13 ms a marker per test), and only then. Nothing else in a draw touches a kept node.
|
|
7646
|
+
5. **The focus brings a marker into view.** One out of view is outside the layer's box. A focused
|
|
7647
|
+
element scrolls its scrolling ancestors into view, and `overflow: hidden` is one, so the layer
|
|
7648
|
+
would have scrolled away from everything it draws: it clips now (`overflow: clip`, `hidden`
|
|
7649
|
+
where an engine lacks it, Safari before 16; the shared `LAYER_STYLE`, find's layer too). The
|
|
7650
|
+
shell scrolls the document instead, to centre the marker, with the `scrollBy` kept before content
|
|
7651
|
+
runs, as `focus(id)` does for a mark. The focus on a marker lights its words as the pointer does.
|
|
7652
|
+
Focus events between two markers don't leave the shadow root, so these listen there.
|
|
7653
|
+
6. **A posted comment's marker sits at its paragraph's end.** A text anchor's, not a draft's: on
|
|
7654
|
+
the last line of the block its words end in, read from the anchor's end as far as a block inside
|
|
7655
|
+
it (a nested list's words are their own paragraph) and over only what is drawn, at most 256 text
|
|
7656
|
+
nodes, once for each finding (a range kept on the mark, so a draw reads one box). It takes P105's
|
|
7657
|
+
places on that line, after a new first one: just past the last word, where nothing follows that a
|
|
7658
|
+
marker could cover, which is what P105's gutter gave up for. Where the line leaves no room, the
|
|
7659
|
+
gutter, the frame's edge, compact and over the line's end as before. Those at one paragraph's end
|
|
7660
|
+
go together, in the order their words end.
|
|
7661
|
+
7. **A draft's stays by its words**, as P105 places it: it is the person's comment being written on
|
|
7662
|
+
those words, beside a composer near them, and nothing else says which words those are. **An
|
|
7663
|
+
element's stays on its corner** (P104): it may have no text and no lines, and a pinned paragraph's
|
|
7664
|
+
marker is P119's. The light on the words, on hover and on focus, still ties a marker at a
|
|
7665
|
+
paragraph's end to the words it is for.
|
|
7666
|
+
8. **`lastLineDocumentRect`** on `selected`, on each attached result of `anchored` and on `tracked`:
|
|
7667
|
+
the last line with words on it (the last client rect with a width: a triple click's empty box on
|
|
7668
|
+
the next block doesn't count), or an element's whole box, in the coordinates of `documentRect`:
|
|
7669
|
+
the box as the shell read it plus the `scroll` it was read at. **`selected` takes `scroll` too**,
|
|
7670
|
+
so it is `rect`'s equal: its viewport place is one less the other. `createHost` checks each as a
|
|
7671
|
+
box, clamps none (a clamp erases an offscreen line, and `rect` is P104's). No other field, method,
|
|
7672
|
+
option or rate. Follow-ups still go by `rect` and `order`: a line that moves inside an unmoved box
|
|
7673
|
+
isn't told, and comparing in document coordinates would tell a fixed mark at every scroll.
|
|
7674
|
+
9. **The marker's own click listener goes**, and with it the control `marker-tap`. It was there
|
|
7675
|
+
only so WebKit would make a tap a click on a `div`: P105's P2-B measured that it did so for a
|
|
7676
|
+
button all along. The tap probes stay, under `marker-click`.
|
|
7677
|
+
|
|
7678
|
+
**Compatibility.** Every field is optional and only added. An older shell sends none, and a host
|
|
7679
|
+
tests for `lastLineDocumentRect`; an older host drops them (each report is rebuilt from known
|
|
7680
|
+
fields, P053). A malformed one drops the whole report, as any malformed part does. Markers change in
|
|
7681
|
+
place for a host doing nothing: they move, and take the keyboard. `show`, `activated` and every
|
|
7682
|
+
existing field are as they were. The shell is the content server's: upgrade that for all of it.
|
|
7683
|
+
|
|
7684
|
+
**Threat.** P104 refused the tab stop because the content controls that focus order. That stands,
|
|
7685
|
+
and is accepted (THREAT_MODEL §7): the content can take the focus from a marker, keep a person from
|
|
7686
|
+
one, draw a look-alike with a tab stop of its own, and tell that the person is on one. It gains no
|
|
7687
|
+
power from that: a marker's press has no effect but `activated`, which it can fake within the host's
|
|
7688
|
+
checks anyway; a made-up key or `click()` is no trusted click; and keys reach a marker only while
|
|
7689
|
+
the frame has the focus, so P109's keyboard is untouched. The focus model P104 hoped for, one the
|
|
7690
|
+
content can't steal, is rejected below: only the host's own UI can be that, and the host's list of
|
|
7691
|
+
marks stays the way a keyboard can rely on. `activated` by keyboard is as fakeable and as guarded
|
|
7692
|
+
as by pointer; ADOPTING's guard already takes no key. The name carries the page's own words
|
|
7693
|
+
(`anchor.label`) to assistive technology, after the shell's own: a page can't change what kind of
|
|
7694
|
+
thing it says this is, and those words reach the frame in `show` already. `lastLineDocumentRect`
|
|
7695
|
+
re-opens what `documentRect` re-opened, no more: a host that draws from it without clipping lets the
|
|
7696
|
+
page choose where (P132's duty, THREAT_MODEL §6). `rect` stays clamped. The page learns nothing new
|
|
7697
|
+
from it (it goes from the frame to the host).
|
|
7698
|
+
|
|
7699
|
+
**Tested.** `test/annotate.test.ts` "the last line (P133)": kept in all three reports, rebuilt from
|
|
7700
|
+
known fields; an older shell's selection exactly as before; a malformed one or a selection's
|
|
7701
|
+
malformed scroll dropping the report; through `createHost`, `rect` clamped, the last line and the
|
|
7702
|
+
scroll as the shell said. `leak/annotate.spec.ts` (three engines), written and not yet run (test runs
|
|
7703
|
+
were paused where this was written, so everything measured above is reasoned from the standards and
|
|
7704
|
+
the engines' sources and awaits CI): "a marker is a button the keyboard reaches…" (`marker-key`,
|
|
7705
|
+
`marker-click`); "a marker out of view brings itself into view…"; "a posted comment's marker sits at
|
|
7706
|
+
its paragraph's end…"; "a selection's and a mark's last line…" (`annotation-rect-clamp`, as P132's).
|
|
7707
|
+
"text markers cover no word" now puts a draft in a line's middle: posted ones have no next word to
|
|
7708
|
+
cover, so that is what control `marker-place` shows. Tests that clicked a posted marker on its
|
|
7709
|
+
anchor's line now look on its paragraph's last line. New control `marker-key`.
|
|
7710
|
+
|
|
7711
|
+
**Rejected.**
|
|
7712
|
+
- A focus model the content can't steal, inside the frame (P104's hope): the shell shares the realm,
|
|
7713
|
+
so nothing in the frame is out of a page's reach. Only the host's overlay could be, a tab stop per
|
|
7714
|
+
mark outside the frame, kept level with content it can't see into: that is the host's list again.
|
|
7715
|
+
- `role="button"` on the `div`: every activation by hand (Enter on keydown, Space on keyup,
|
|
7716
|
+
nothing for assistive technology's own click), for nothing; "works with the existing path" is what
|
|
7717
|
+
a real button's trusted click gives.
|
|
7718
|
+
- A click listener on the marker itself, to know the target without the focus: the window's first
|
|
7719
|
+
listener has to stop the click before it gets there, or the content hears it.
|
|
7720
|
+
- Stopping every key on a marker: it would take Escape and Tab from a page's own handling, and the
|
|
7721
|
+
host's find shortcut, for no secret; what's stopped is what acts on a marker.
|
|
7722
|
+
- A host's `label` on a mark for the name in the person's language: a new field in `show` and in
|
|
7723
|
+
what the page reads, not asked for yet (see Revisit).
|
|
7724
|
+
- Moving the marker to the paragraph's end in the gutter always (P105's place on that line): it
|
|
7725
|
+
keeps the distance from the words that this is here to end.
|
|
7726
|
+
- A marker at a picked paragraph's end too: an element anchor isn't always text, and P119 pins that
|
|
7727
|
+
marker on purpose.
|
|
7728
|
+
- `documentRect` on `selected` as well: not asked for; `rect` and the last line place a host's UI.
|
|
7729
|
+
|
|
7730
|
+
**Revisit when** a host's UI isn't in English and its marker names should be (a host's `label` on a
|
|
7731
|
+
mark, sent into the frame, the page reading it); an engine's or a screen reader's click on a marker
|
|
7732
|
+
it didn't focus is missed, or reported as the marker that has the focus, so the wrong comment opens
|
|
7733
|
+
(give the layer a way to learn its target); a right-to-left paragraph's
|
|
7734
|
+
end should be on its left (P105's places aren't direction-aware either); paragraphs split by `<br>`
|
|
7735
|
+
should count as many; or a host wants a picked paragraph's marker at its end.
|
package/docs/DESIGN.md
CHANGED
|
@@ -1047,11 +1047,13 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1047
1047
|
| host → frame | `porthole/annotate.focus` | `{ id }`: scrolled into view inside the frame, made the active mark, flashed |
|
|
1048
1048
|
| host → frame | `porthole/annotate.clear` | — |
|
|
1049
1049
|
| host → frame | `porthole/annotate.clearSelection` | —: the page's text selection is taken away (the DOM's own `removeAllRanges`, taken before content runs) with what the shell held of it, and nothing is reported back; marks, drafts and the mode stay (P115) |
|
|
1050
|
-
| frame → host | `porthole/annotate.selected` | `{ anchor, rect }
|
|
1050
|
+
| frame → host | `porthole/annotate.selected` | `{ anchor, rect, lastLineDocumentRect?, scroll? }` (a newer shell's last two: P133, below); 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) |
|
|
1054
|
-
|
|
|
1053
|
+
| frame → host | `porthole/annotate.anchored` | `{ results: [{ id, state: "attached" \| "orphaned", rect?, documentRect?, lastLineDocumentRect?, order? }], scroll? }` (a newer shell's `documentRect` and `scroll`: P132, below; `lastLineDocumentRect`: P133): 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?, lastLineDocumentRect?, 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), and its last line's (P133) |
|
|
1056
|
+
| frame → host | `porthole/annotate.activated` | `{ id, rect }`: the person clicked a mark's marker, or pressed Enter or Space on it (P133); `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:
|
|
1057
1059
|
`CssSelector` (unique: the nearest id, else a path of `nth-of-type` steps),
|
|
@@ -1070,10 +1072,31 @@ 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.
|
|
1086
|
+
- **The last line** (P133). A newer shell says where a selection or a mark ends, for a
|
|
1087
|
+
host's UI after it: `lastLineDocumentRect`, on `selected` (with `scroll`, read with
|
|
1088
|
+
it), on each attached result of `anchored` and on `tracked`, in the coordinates of
|
|
1089
|
+
`documentRect`, checked and left unclamped as it is. It is the last box with a width
|
|
1090
|
+
of the words' client rects, the box a text marker's place starts from; an element,
|
|
1091
|
+
which has no lines of its own, gives its whole box. Its place in the frame's viewport
|
|
1092
|
+
is it less `scroll`. Absent from an older shell, and where nothing of it is drawn.
|
|
1073
1093
|
- **Markers** (P104). A mark with a `count` gets a bubble glyph and its number ("99+"
|
|
1074
|
-
above 99; 0 the bubble alone) on an element's top right
|
|
1075
|
-
width, and
|
|
1076
|
-
|
|
1094
|
+
above 99; 0 the bubble alone), a real button (P133, below), on an element's top right
|
|
1095
|
+
corner, inside the frame's width, and at the end of a text anchor's paragraph (P133):
|
|
1096
|
+
on the last line of the block its words end in, read as far as a block inside it,
|
|
1097
|
+
just past that line's last word, or where that doesn't fit at the places a draft's
|
|
1098
|
+
takes. A draft's goes beside its anchor's own last line, centred on it (P105, #36): in
|
|
1099
|
+
the line's gutter, just past the right edge of the anchor's block; at the frame's right
|
|
1077
1100
|
edge where the frame is too narrow for that; just past the line's last word where
|
|
1078
1101
|
something else is beside the block (a table's next cell, a card in a row). Each
|
|
1079
1102
|
place must be clear of that line's words and of anything of the content's but a box
|
|
@@ -1088,8 +1111,8 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1088
1111
|
is a thin line. The layer takes no pointer but on markers: a press on one, and the pointer's
|
|
1089
1112
|
moves over it, are stopped in the shell's first window listener, read through the
|
|
1090
1113
|
platform's own functions kept before content runs (P105), and a trusted click is
|
|
1091
|
-
reported `activated`; a tap too, on WebKit as well, since
|
|
1092
|
-
|
|
1114
|
+
reported `activated`; a tap too, on WebKit as well, since a button is an element it
|
|
1115
|
+
makes a tap a click on (P105). On
|
|
1093
1116
|
touch (P119), while the last pointer down or moved was a finger or a pen (before any,
|
|
1094
1117
|
where `(any-pointer: coarse)` matches), each marker also takes the pointer in a box of
|
|
1095
1118
|
at least 44 by 44 px centred on its bubble (an invisible `::before` in the layer), the
|
|
@@ -1100,10 +1123,26 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1100
1123
|
its handlers, nor what is under the marker, gets them; content that patches others
|
|
1101
1124
|
can reach the layer's nodes (P105). Either way the content can tell a press
|
|
1102
1125
|
happened, by `:active`, `relatedTarget` and user activation. Markers step aside
|
|
1103
|
-
while elements are picked
|
|
1104
|
-
|
|
1126
|
+
while elements are picked, the keyboard's Tab too.
|
|
1127
|
+
- **Markers from the keyboard** (P133). Each marker is a `<button>` with a tab stop,
|
|
1128
|
+
in the page's reading order after the page's own stops (the layer is the document's
|
|
1129
|
+
last child), named for what it is (`aria-label`: "3 comments on …", "Draft comment on
|
|
1130
|
+
…", with the mark's `anchor.label`, in English); only the markers are exposed to
|
|
1131
|
+
assistive technology, the layer no longer `aria-hidden`, its marks and outline are.
|
|
1132
|
+
A press of a pointer still moves no focus. Enter and Space make the button's own
|
|
1133
|
+
trusted click, which goes the way a pointer's does, but has no count and no place, so
|
|
1134
|
+
it is the focused marker's (read through the shadow root's `activeElement`, kept
|
|
1135
|
+
before content runs); those two keys are stopped at the window as a press is, a
|
|
1136
|
+
repeat of them cancelled (a key held down clicks once), and every other key stays the
|
|
1137
|
+
page's. A real key gives the host's page transient activation as a click does. The
|
|
1138
|
+
focus on a marker lights its words and, out of view, scrolls the document to it: the
|
|
1139
|
+
layer clips rather than hides, so it never scrolls itself. While one has the focus a
|
|
1140
|
+
draw takes the markers out of hit tests by `pointer-events`, not `display` (which
|
|
1141
|
+
would lose it), and moves none. The page shares the focus order: the host's own list
|
|
1142
|
+
of marks stays the keyboard path it can rely on.
|
|
1105
1143
|
- **Drafts** (P107). A mark with `kind: "draft"` (a comment not yet posted) has a
|
|
1106
|
-
marker whether or not it has a count, placed
|
|
1144
|
+
marker whether or not it has a count, placed by its own words (not at its paragraph's
|
|
1145
|
+
end, P133), and drawn apart: a
|
|
1107
1146
|
dashed underline (a dashed outline on an element), a lighter fill, and a hollow
|
|
1108
1147
|
marker (a light bubble with a dashed edge and the glyph's outline) with no number.
|
|
1109
1148
|
`checkMarks` sends a posted mark as before (no `kind`), a draft without its count,
|
|
@@ -1147,7 +1186,12 @@ they change; an MCP Apps view; and a hostile page faking every report (not asked
|
|
|
1147
1186
|
malformed, too large, the wrong kind, no such mark, a flood), whose negative
|
|
1148
1187
|
control is `annotation-checks`. Markers (P104): drawn with their numbers, a click
|
|
1149
1188
|
reported with its id and box and heard by none of the content's listeners, nor a
|
|
1150
|
-
double, right or middle click (`marker-click` → those two cases),
|
|
1189
|
+
double, right or middle click (`marker-click` → those two cases), by the keyboard
|
|
1190
|
+
too (P133: a button in reading order and named for what it is, Enter and Space
|
|
1191
|
+
reported once, a key held down once, none of it heard, nothing while elements are
|
|
1192
|
+
picked; `marker-key`, `marker-click` too), brought into view by the focus and keeping
|
|
1193
|
+
it through redraws, at its paragraph's end past the last word, a nested block's
|
|
1194
|
+
words not its own, a draft's by its words; focus and
|
|
1151
1195
|
selection kept, a drag from a marker too (`marker-prevent` → the press case), none
|
|
1152
1196
|
without a count, stepping aside while picking, drawn whole at the frame's top; a
|
|
1153
1197
|
run of scrolls reported with only the marks that moved, a fixed one never; marks
|
|
@@ -1164,9 +1208,9 @@ the layer itself (`annotation-activated`, `annotation-activated-count`,
|
|
|
1164
1208
|
`MouseEvent`'s prototypes neither hearing a marker's press nor stopping its report
|
|
1165
1209
|
(`marker-originals`; `marker-click` too); a tap on a marker reported on each
|
|
1166
1210
|
engine, a touch screen and a phone's emulation (iPhone 13, Pixel 5), content hearing
|
|
1167
|
-
none of it (`marker-
|
|
1211
|
+
none of it (`marker-click`); on a 640 px column and a phone page's lines
|
|
1168
1212
|
with one marker each, no marker covering a word (`marker-place`, the marker just
|
|
1169
|
-
past its words as 0.9.0 had it); drafts (P107) drawn apart from posted marks on the
|
|
1213
|
+
past its words as 0.9.0 had it, which a draft's in a line's middle shows); drafts (P107) drawn apart from posted marks on the
|
|
1170
1214
|
same anchors (the frame's pixels and the words' own differ; on Chromium every draft's
|
|
1171
1215
|
marker and line drawn as a draft's, no number though given a count), a draft's and a
|
|
1172
1216
|
posted marker's clicks reported beside each other, none reaching the content
|
|
@@ -1484,10 +1528,10 @@ control the tables above name to the registry):
|
|
|
1484
1528
|
| `annotation-activated` | `annotate.spec.ts` | `a hostile page fakes a marker's click: the host takes it only for a mark it shows with a marker` | — | — |
|
|
1485
1529
|
| `annotation-activated-count` | `annotate.spec.ts` | `a hostile page fakes a marker's click: the host takes it only for a mark it shows with a marker` | — | — |
|
|
1486
1530
|
| `marker-trusted` | `annotate.spec.ts` | `a hostile page fakes a marker's click: the host takes it only for a mark it shows with a marker` | — | — |
|
|
1487
|
-
| `marker-click` | `annotate.spec.ts` | `markers: a mark with a count gets a numbered bubble; its click is reported and never reaches the content`, `a marker's press, of any kind, moves nothing of the content's: no handler, no focus, no selection`, `a page that patches the event's built-ins neither hears a marker's press nor stops its report (P105)`, `a tap on a marker is reported on every engine, and the content hears none of it (P105)`, `drafts (P107): a dashed line and a hollow marker with no number, apart from posted marks; their clicks are reported the same`, `on touch, a marker takes a tap a few px off its bubble (44 by 44), after the page scrolled itself; a tap past that is the page's (P119)`, `on touch, where two markers' 44 px boxes overlap, a tap is the nearest bubble's (P119)`, `a paragraph's marker pinned at the frame's top once its start scrolled away takes a mouse click and a tap where it is drawn (P119, porthole#42)` | — | — |
|
|
1531
|
+
| `marker-click` | `annotate.spec.ts` | `markers: a mark with a count gets a numbered bubble; its click is reported and never reaches the content`, `a marker's press, of any kind, moves nothing of the content's: no handler, no focus, no selection`, `a page that patches the event's built-ins neither hears a marker's press nor stops its report (P105)`, `a tap on a marker is reported on every engine, and the content hears none of it (P105)`, `a marker is a button the keyboard reaches: Tab in reading order, Enter and Space report it once, the content hears neither, and it steps aside while elements are picked (P133)`, `drafts (P107): a dashed line and a hollow marker with no number, apart from posted marks; their clicks are reported the same`, `on touch, a marker takes a tap a few px off its bubble (44 by 44), after the page scrolled itself; a tap past that is the page's (P119)`, `on touch, where two markers' 44 px boxes overlap, a tap is the nearest bubble's (P119)`, `a paragraph's marker pinned at the frame's top once its start scrolled away takes a mouse click and a tap where it is drawn (P119, porthole#42)` | — | — |
|
|
1488
1532
|
| `marker-prevent` | `annotate.spec.ts` | `a marker's press, of any kind, moves nothing of the content's: no handler, no focus, no selection` | — | — |
|
|
1489
1533
|
| `marker-place` | `annotate.spec.ts` | `text markers cover no word: on a column page, and on a phone's lines with one marker each (P105, #36)` | — | — |
|
|
1490
|
-
| `marker-
|
|
1534
|
+
| `marker-key` | `annotate.spec.ts` | `a marker is a button the keyboard reaches: Tab in reading order, Enter and Space report it once, the content hears neither, and it steps aside while elements are picked (P133)` | — | — |
|
|
1491
1535
|
| `marker-originals` | `annotate.spec.ts` | `a page that patches the event's built-ins neither hears a marker's press nor stops its report (P105)` | — | — |
|
|
1492
1536
|
| `follow-throttle` | `annotate.spec.ts` | `an honest scroll session, long, in comment mode, leaves room for a marker's click: follow-ups, the selection's too, at most one a second` | — | — |
|
|
1493
1537
|
| `selection-follow` | `annotate.spec.ts` | `an honest scroll session, long, in comment mode, leaves room for a marker's click: follow-ups, the selection's too, at most one a second` | — | — |
|
|
@@ -1495,7 +1539,7 @@ control the tables above name to the registry):
|
|
|
1495
1539
|
| `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
1540
|
| `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
1541
|
| `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` | — | — |
|
|
1542
|
+
| `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)`, `a selection's and a mark's last line come in the document's coordinates with the scroll, offscreen ones too; rect stays clamped (P133)` | — | — |
|
|
1499
1543
|
| `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
1544
|
| `url-permissions` | `served/permissions.spec.ts` | `a url-mode frame gets no clipboard writes or full screen unless the host delegates them` | — | — |
|
|
1501
1545
|
| `navigate-guard` | `served/live.spec.ts`, `served/files.spec.ts`, `served/served.spec.ts`, `served/tab.spec.ts` | `served.domain.self-navigation`, `served.domain.tab-navigation`, `served.domain.tab-links`, `can't navigate itself away (location): to a site, or to another content origin`, `can't navigate itself away (replace): to a site, or to another content origin`, `can't navigate itself away (open-self): to a site, or to another content origin`, `can't navigate itself away (navigation-api): to a site, or to another content origin`, `a link to another page of the set opens it in the frame; the display goes on`, `a link to another page of the set opens it in the frame when the leaving page's notice is dropped (P098)`, `a link to another page of the set opens it in the frame when the leaving page's notice is late (P098)`, `a page opens nothing else: not a file that isn't a page, not another path of its origin`, `no report, content error or blocked navigation names the frame's sealed address (P083)` | — | — |
|
package/docs/THREAT_MODEL.md
CHANGED
|
@@ -5,7 +5,7 @@ What Porthole protects, from whom, and where that protection ends. For each way
|
|
|
5
5
|
guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
|
|
6
6
|
[DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
|
|
7
7
|
|
|
8
|
-
**Status.** This describes Porthole 0.14.
|
|
8
|
+
**Status.** This describes Porthole 0.14.11 (2026-11-06). 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,13 @@ 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. 0.14.11: P133
|
|
34
|
+
makes markers buttons in the frame's Tab order, reversing P104's "no tab stop": the page shares that
|
|
35
|
+
order, so it can steer or spoil the focus, and a host keeps its own list of marks (§7). A press only
|
|
36
|
+
reports `activated`, which the page could already fake; `lastLineDocumentRect` is unclamped, for a
|
|
37
|
+
host to clip as P132's are; no wall moves.
|
|
32
38
|
|
|
33
39
|
## 1. Two layers
|
|
34
40
|
|
|
@@ -193,7 +199,10 @@ Whatever the use:
|
|
|
193
199
|
framed as it is: upgrade the server/Worker first, resolve clean addresses through issue, P125):
|
|
194
200
|
log them, show nothing for them. A url-mode app can still say any outcome (S6).
|
|
195
201
|
- 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).
|
|
202
|
+
as permissions, and put nothing in a mark the page may not know (§7). A mark's place in the
|
|
203
|
+
document (`documentRect`, with the report's `scroll`, P132) and its last line's
|
|
204
|
+
(`lastLineDocumentRect`, P133) aren't clamped to the frame: clip whatever you draw from them to
|
|
205
|
+
the frame's box, or to your own region beside the frame.
|
|
197
206
|
- Under `find` (P131), know that the page reads every query your find bar sends it, and declare
|
|
198
207
|
`find` only for displays whose pages may learn what the person searches for (not a third-party
|
|
199
208
|
app with egress, S5, unless you accept it). Take its counts as the bar's numbers, and open your
|
|
@@ -813,6 +822,16 @@ own frame, below the shell, P111), so:
|
|
|
813
822
|
no size, or throws, clamps every box to nothing at the frame's corner (P105). The frame's size is
|
|
814
823
|
read for every report the host takes, before the report's rate: a forced layout of the host's
|
|
815
824
|
page per message, which a repeated `ui/initialize` already causes (accepted, P105).
|
|
825
|
+
A newer shell also says where each mark is in the document (`documentRect` in `anchored` and
|
|
826
|
+
`tracked`, with the document's `scroll`, P132), so a host can place a mark scrolled out of the
|
|
827
|
+
frame. Porthole checks those numbers (finite, within `ANNOTATION_LIMITS.coordinate`, sizes not
|
|
828
|
+
negative; a malformed one drops the report) but doesn't clamp them, since a clamp would erase
|
|
829
|
+
what they are for: a host that maps a `documentRect` onto its own page without clipping to the
|
|
830
|
+
frame's box (or to its own region beside it) lets the page choose where that UI goes, outside
|
|
831
|
+
the frame as well (accepted, P132; the host's duty in §6). They say nothing else: the page knows
|
|
832
|
+
where its words are anyway. Where a selection or a mark's words end (`lastLineDocumentRect` in
|
|
833
|
+
`selected`, `anchored` and `tracked`, P133) is one more such box, read, checked and left unclamped
|
|
834
|
+
the same way, with the same duty; `selected` also carries `scroll` now.
|
|
816
835
|
- *What holds, against content that patches none of the DOM's or JavaScript's built-ins.* A real
|
|
817
836
|
press or click on a marker reaches none of the content's handlers (the shell's first listener
|
|
818
837
|
stops it; control `marker-click`) and moves neither focus nor a selection (control
|
|
@@ -825,6 +844,21 @@ own frame, below the shell, P111), so:
|
|
|
825
844
|
loses a tap within 13 px of a bubble (a few px of its words above and below it), as it loses
|
|
826
845
|
one on the bubble. Which pointer is used is read from trusted pointer events only; a page that
|
|
827
846
|
makes its own up changes nothing, and a real `activated` still needs a real click.
|
|
847
|
+
- *The keyboard on a marker* (P133, reversing P104's point 6). A marker is a button with a tab
|
|
848
|
+
stop. Enter and Space on it are stopped in the shell's first listener, as a press is (control
|
|
849
|
+
`marker-key`), and the click they make is a trusted one the content doesn't get (`marker-click`):
|
|
850
|
+
it can neither hear nor cancel them. Every other key on a marker is the page's, as on a button of
|
|
851
|
+
its own, Tab too. So what P104 feared stands, and is accepted: the markers join a focus order the
|
|
852
|
+
content controls. It can take the focus from a marker (`focus()` from any handler or timer), keep
|
|
853
|
+
the person from reaching one (a trap on Tab in its own elements), draw its own look-alike with
|
|
854
|
+
its own tab stop, and tell that the person is on one (`document.activeElement` is the layer, its
|
|
855
|
+
own element's `focusout` names it). None of that gives it what it lacks: a marker's press has no
|
|
856
|
+
power but `activated`, which it can fake anyway within the host's checks, keys go to a marker only
|
|
857
|
+
while the frame has the focus, so nothing typed in the host passes through it (P109 is unchanged),
|
|
858
|
+
and a page's made-up key or `click()` is no trusted click. Assistive technology now reads the
|
|
859
|
+
marker's name, the page's own words (`anchor.label`, the host's copy with what can't be seen taken
|
|
860
|
+
out) after the shell's. A host can't rely on a marker being reached, as it can't on one being
|
|
861
|
+
seen: its own list of marks is the keyboard way that holds.
|
|
828
862
|
- *What doesn't hold against content that does.* The shell shares the content's realm. It reads
|
|
829
863
|
and stops a marker's press through the platform's own functions and getters, kept before
|
|
830
864
|
content runs (P105, control `marker-originals`), so patching `Event`'s or `MouseEvent`'s
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.14.
|
|
3
|
+
"version": "0.14.11",
|
|
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": {
|