@botiverse/porthole 0.14.13 → 0.14.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/DESIGN.md CHANGED
@@ -743,7 +743,7 @@ binding is mounting and lifecycle (P034).
743
743
  onContentError onHostError onResize onNavigated onNavigationBlocked onRefused onMuted
744
744
  onInitialized onOutcome
745
745
  fill? // fill the box and scroll inside, not grow with the content
746
- annotating? annotations? focusedAnnotation? trackedAnnotation? onAnnotation? // where annotate is declared
746
+ annotating? annotations? focusedAnnotation? trackedAnnotation? trackedSelection? onAnnotation? // where annotate is declared
747
747
  ref? // a PortholeFrameHandle: clearSelection() (P118)
748
748
  aliases? themeKey? renderPlaceholder? eager? confirm? document? instance?
749
749
  className? style? />
@@ -779,8 +779,9 @@ binding is mounting and lifecycle (P034).
779
779
  - **Annotations** follow props: `annotating` (what the person may point at now, or
780
780
  null), `annotations` (the marks), `focusedAnnotation` (each new id is brought into
781
781
  view; `{ id, key }` with a new key focuses the same one again), `trackedAnnotation`
782
- (the mark followed, or null, P118); `onAnnotation` gets what the frame reported, `tracked`
783
- boxes too. A frame that mounts again gets them all. A `ref` holds `clearSelection()`, `find`,
782
+ (the mark followed, or null, P118), `trackedSelection` (true: the selection followed in
783
+ its place, and highlighted, P138); `onAnnotation` gets what the frame reported, `tracked`
784
+ and `selectionTracked` boxes too. A frame that mounts again gets them all. A `ref` holds `clearSelection()`, `find`,
784
785
  `clearFind` and `focusMark(id)` (`PortholeFrameHandle`), each a no-op while no display runs.
785
786
  - **Errors** (P055): `onContentError` gets what the content did wrong (what it
786
787
  threw, what the sandbox blocked, a navigation the shell stopped, that it kept
@@ -1003,6 +1004,7 @@ for that to lapse and click with raw input.
1003
1004
  | The keyboard: the focus guard (P109) | a move of the keyboard from one of the host page's text fields into a display's frame that the person didn't make (no press on the frame, `:active` on Chromium and WebKit, the pointer coming over it on Firefox; no Tab; no gesture the page's own events don't explain) is undone once the move is over; three while typing within 10 s, or five within 2 s, stop the display | `test/focus-guard.test.ts`; `leak/served/runtime.spec.ts`: "a page that takes the keyboard while the person types in the host's composer…", "a page that takes the keyboard back on its own blur keeps none of it…" (GK-1), "a composer the host focuses with focusField…", "the person's own moves into the frame keep the keyboard…" | `focus-guard` → the first (all three) and the next two (Firefox); `focus-guard-watch` (the watch after a take-back, the look at every frame) → those two (Firefox) |
1004
1005
  | The runtime: `comments.open` from the frame the person is in (P109) | its `user-activation` gate also needs the host page's focus in the calling frame (`CapabilitySpec.inFrame`, `Surface.focused`), after the focus guard | `leak/served/runtime.spec.ts`: "comments.open while the person types in the host's composer reaches no handler…" | `comments-in-frame` → that case (all three) |
1005
1006
  | A nested page: Porthole's shell above an opaque page (P111) | the framed address answers the shell alone (its own script by hash, framing and fetching only the sealed prefix); the page is its child, `sandbox="allow-scripts"` in the attribute and its CSP (never `allow-same-origin`: a static check over every sandbox Porthole writes), loaded without a cookie; the shell passes messages by `event.source`, never in its own namespace; the host takes a move into the frame, or a `comments.open`, for the person's only if the shell's activation turned on within the last second with no trusted press or key on the host's page since (or a Tab, the host's move, a press the engine shows), asking the shell to look as it hears the move; where the host's page sees the pointer over its frames, not with the pointer elsewhere within a second of typing; in a fight over a text field, a frame that takes focus again is judged without the shell and taken back at once, counted (P120); no press within 250 ms of the person's key on the host's page (P122) | `test/nested.test.ts`; `leak/served/nested.spec.ts` on full Chromium, the headless shell, WebKit and Firefox | `shell-namespace` → "the shell's words are the shell's alone…" (all three); `shell-host-input` → "a page's focus() just after the person pressed it and went back…" (all three); `pointer-rule` (P120's pointer rule out) → "an activation that came as the person typed…" (all three); `key-press` (P122's 250 ms out) → "an activation that turned on within 250 ms of the person's key…" (all three); `nested-fight` (a frame that takes focus back in a fight let be) → "a page that holds the keyboard from its load…" (Firefox); `leak/served/nested-keyboard.spec.ts` (a page that takes the keyboard as the person types: a race, no control's probe) |
1007
+ | A nested page's shell passes the focus on at the host's word (P136) | `display.focus()` sends `porthole/shell/focus`, only a move that landed; the shell acts only while the focus is on its own document, blurring its frame first, and a page's message in its namespace never reaches that code | `test/nested.test.ts` "the host's word that it moved the focus into a nested page's frame"; `leak/served/nested.spec.ts`: "a page that had the focus gets it back by the host's own move…", "a page that never had the focus…", "a second host's move into a page it just handed the focus to…", "the host's move into a page that holds the focus…", "the host's move from its own text field…", "the host's move takes no keyboard…", "the host's move from inside a key's own handler…" (`test.fail` on Firefox) | `shell-focus-held` |
1006
1008
  | A nested page's shell on a label of its own (P114, porthole#56) | the shell, its page and that page's files are served on `nestedLabelOf(<scope's label>)` (`porthole-<24 base32>`, one per scope), never on the scope's label, where the scope's other displays run content with `allow-same-origin`; that label answers only frame addresses of nested pages, their sealed prefix and status pages (no clean address, entry, asset, library, app, nor another instance's ticket, cookie or sealed address), the scope's label no nested page (a clean address goes on with a one-time ticket); no host's naming makes a `porthole-` label; an entry code is no document's ticket; outside `/server` too (P121), `createHost` refuses a nested page located on any other label, the shell runs on no other origin, and `nestedShellResponse` and `frameShellScript` refuse one; `nestedFileCsp` is the page's and its files' CSP for `/server` and a Worker of a host's own | `test/nested.test.ts`, `test/entry.test.ts` ("… (P114)"; `test/nested.test.ts` "… (P121)"); `leak/served/nested-siblings.spec.ts` (`[nested-siblings]`: a same-scope inline widget and artifact read each other, not the shell; `[nested-label]`: a nested page located on its scope's label is refused, no frame made) on full Chromium, the headless shell, WebKit and Firefox; `leak/kit.spec.ts` and the prod-shape profile (the label through `nodeHost`, and through a TLS edge and DNS) | `shell-label,nested-host-label,nested-shell-origin` (the shell on the scope's label, the host's and the shell's checks out) → `[nested-siblings]`, `[nested-label]` (all three); `nested-host-label` (the host's check out) → `[nested-label]` (all three) |
1007
1009
  | The asset library (P089, P091) | `/_blob/<id>` (or the frame's `<sealed base>__porthole/blob/<id>`) for an access to its artifact (a cookie, a sealed `Referer`, the sealed path), then the host's check, the store asked with it; typed by name, never a page, code only where trusted and uploaded code may run (asked at each load; by id alone, every artifact config must, P103), inert CSP, CORP, revalidated; the page's CSP opens `<origin>/_blob/` for images, media, fonts and data, for scripts and styles only where uploads are the admins' | `test/assets.test.ts` (a forged same-origin claim: 401; another artifact's session: 404; revoked: 403; bearer mode; a stricter config turns trusted code into a download, bearer mode too); `leak/served/runtime.spec.ts`: an upload loads in its frame; a set's page loads it; static `/_blob/` in a frame by `Referer` (Chromium, Firefox; WebKit sends only the origin: measured); "a script asset runs as code only if an admin uploaded it"; "scripts load from /_blob/ only where uploads are the admins'"; "an asset reaches only its own artifact's pages"; "an asset opened on its own runs nothing" | `blob-trusted` → the trusted-code case; `blob-script,blob-trusted` (two walls) → that case and the tab's CSP case; `blob-inert` → the opened-on-its-own case (all three; `scripts/controls.ts`) |
1008
1010
  | Workers (P044, P045) | no Node module in `/server`; D1 tickets taken by one `DELETE … RETURNING` | `test/workers.test.ts` (workerd, no `nodejs_compat`, real D1: once per ticket, a race, anonymous, a revocation, flat names, reserved namespaces) | — |
@@ -1047,13 +1049,14 @@ chooses), and the annotation runtime is in the shell only then.
1047
1049
  | host → frame | `porthole/annotate.focus` | `{ id }`: scrolled into view inside the frame, made the active mark, flashed |
1048
1050
  | host → frame | `porthole/annotate.clear` | — |
1049
1051
  | 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
- | host → frame | `porthole/annotate.focusMark` | `{ id }`: the DOM focus goes to that mark's marker (the DOM's own `focus`, taken before content runs), once the marks of a `show` are found; a call that had to wait for them is dropped unless the focus is in the frame's document as it lands (the DOM's own `hasFocus`, taken before content runs; P135; on a nested page that had the focus the host's `display.focus()` doesn't bring it back, a known gap), one that didn't wait isn't asked; nothing is reported back, and with no such marker, or while elements are picked, nothing happens. For after the keyboard closed the host's view: Escape, or a Tab past its ends (P134); a host calls it again after its own `display.focus()` |
1051
- | 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) |
1052
+ | host → frame | `porthole/annotate.focusMark` | `{ id, at }`, `at` the host's `Date.now()` as it sent it (P137): the DOM focus goes to that mark's marker (the DOM's own `focus`, taken before content runs), once the marks of a `show` are found; a call that had to wait for them is dropped unless the focus is in the frame's document as it lands (the DOM's own `hasFocus`, taken before content runs; P135), and so is one the frame takes 100 ms or more after `at` by its own clock (the DOM's own `Date.now`, taken before content runs) or with no `at` (P137); a fresh one isn't asked; nothing is reported back, and with no such marker, or while elements are picked, nothing happens. For after the keyboard closed the host's view: Escape, or a Tab past its ends (P134); a host calls it again after its own `display.focus()` |
1053
+ | frame → host | `porthole/annotate.selected` | `{ anchor, rect, lastLineDocumentRect?, scroll? }` (a newer shell's last two, only as a pair: P133, below, P137); after a scroll, the same selection again only if its box moved more than 0.5 px, on the follow-ups' clock (P105), and not while the host follows the selection (P138) |
1052
1054
  | frame → host | `porthole/annotate.unselected` | — (the text selection went away) |
1053
1055
  | frame → host | `porthole/annotate.cancelled` | — (Escape) |
1054
- | 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) |
1055
- | host → frame | `porthole/annotate.track` | `{ id }` or `{ id: null }`: follow one shown mark, or none (P112) |
1056
- | 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.anchored` | `{ results: [{ id, state: "attached" \| "orphaned", rect?, documentRect?, lastLineDocumentRect?, order? }], scroll? }` (a newer shell's `documentRect` and `scroll`: P132, below; `lastLineDocumentRect`: P133, never without `scroll`, P137): 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) |
1057
+ | host → frame | `porthole/annotate.track` | `{ id }` or `{ id: null }`: follow one shown mark, or none (P112); `{ id: null, selection: true }`: follow the selection last reported as `selected` instead, and highlight it while followed (P138; an older shell reads it as none) |
1058
+ | 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, never without the scroll, P137) |
1059
+ | frame → host | `porthole/annotate.selectionTracked` | `{ state: "attached", rect, documentRect, lastLineDocumentRect?, scroll, inView }` or `{ state: "orphaned" }`: the followed selection's boxes, as `tracked`'s, at an animation frame where it moved or the viewport changed size, at most one every 16 ms, the first at the frame after the host asks; `orphaned` once while it isn't in the page (or the frame has no selection), found again by its anchor at most twice a second; the host takes it only while it follows the selection, 60 a second with `tracked`, its `rect` clamped, `inView` false unless its box as read reaches the viewport (P138) |
1057
1060
  | 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) |
1058
1061
 
1059
1062
  - **Anchors** are W3C Web Annotation selectors, at most one of each:
@@ -1091,6 +1094,25 @@ chooses), and the annotation runtime is in the shell only then.
1091
1094
  of the words' client rects, the box a text marker's place starts from; an element,
1092
1095
  which has no lines of its own, gives its whole box. Its place in the frame's viewport
1093
1096
  is it less `scroll`. Absent from an older shell, and where nothing of it is drawn.
1097
+ - **The selection followed** (P138). The shell keeps what each `selected` reported: the
1098
+ element picked (a click, or a block held), or a copy of the selection's range (the
1099
+ DOM's own `cloneRange`, taken before content runs), which the page's changes keep up to
1100
+ date and which stays when the page's own selection goes (the host's `clearSelection`
1101
+ too). While the host follows it (`track` with `selection`; one followed thing at a time,
1102
+ so a mark's id or `null` ends it, as `clear` does; `show`, `stop` and a pick's end leave
1103
+ it), it is drawn in the layer as a pick is (an element in the picking outline, lighter
1104
+ and without its name; words with a light fill and a line under them, in the picking
1105
+ blue) and its boxes are told as a followed mark's are, with `inView` (any of its box in
1106
+ the viewport). Taken out of the page, it is `orphaned` once, and found again by its
1107
+ anchor as a mark is. It reads boxes only: no focus moves, no selection changes, no
1108
+ listener is added, and nothing about the words goes with it (they went with
1109
+ `selected`). A newer `selected` replaces it, followed from the next frame. Before the host
1110
+ follows it, the element just picked keeps an outline drawn the same way, so nothing changes on
1111
+ screen when the follow takes over; without a follow it ends as a selection does (the next pick or
1112
+ selection, `clearSelection`, `start`, `stop`, `clear`, Escape, the element leaving the page), on
1113
+ no timer (Tenny's review). While followed, a scroll re-sends no `selected` (P105's follow-up):
1114
+ once the following ends, it does again. The React binding sends the following before a mode
1115
+ change made in the same render.
1094
1116
  - **Markers** (P104). A mark with a `count` gets a bubble glyph and its number ("99+"
1095
1117
  above 99; 0 the bubble alone), a real button (P133, below), on an element's top right
1096
1118
  corner, inside the frame's width, and at the end of a text anchor's paragraph (P133):
@@ -1195,8 +1217,14 @@ it through redraws, reached by the host's `focusMark` after its card closed and
1195
1217
  alone where there's no such marker, by the kept `focus` (P134, `marker-focus`), a call parked meanwhile
1196
1218
  dropped once the person has moved on or the focus is on the host's body, and a second after the
1197
1219
  host's `display.focus()` landing (P135, `marker-late`), by the kept
1198
- `hasFocus`, which a page's patch can't answer (`marker-has-focus`); on a nested page a parked call
1199
- lands while the focus is in the page, and that host's move is a known gap (`test.fail`, P135), at its paragraph's end past the last word, a nested block's
1220
+ `hasFocus`, which a page's patch can't answer (`marker-has-focus`), a word a busy page takes late
1221
+ held to the same test, by the host's stamp and the kept clock, a calm close landing, and a second
1222
+ word after the host's move landing (P137, `marker-busy`, `marker-clock`, in
1223
+ `nested-late-word.spec.ts` so that full Chromium runs it, where a person's click comes before the
1224
+ word); on a nested page a parked call lands while the focus is in the page, not once the person has
1225
+ moved on (`marker-late`), a late word not either (`marker-busy`), and after
1226
+ the host's move, which the shell passes on (P136, `shell-focus-held`; on Firefox not from inside a
1227
+ key's own handler, `test.fail`), at its paragraph's end past the last word, a nested block's
1200
1228
  words not its own, a draft's by its words; focus and
1201
1229
  selection kept, a drag from a marker too (`marker-prevent` → the press case), none
1202
1230
  without a count, stepping aside while picking, drawn whole at the frame's top; a
@@ -1539,8 +1567,10 @@ control the tables above name to the registry):
1539
1567
  | `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)` | — | — |
1540
1568
  | `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)` | — | — |
1541
1569
  | `marker-focus` | `annotate.spec.ts` | `a page that patched focus isn't handed the marker the host's focusMark moves to (P134)` | — | — |
1542
- | `marker-late` | `annotate.spec.ts` | `a parked focusMark doesn't land once the person has moved on to the host's button (P135)`, `a focusMark parked with the focus in the frame doesn't land once the person moves on while it waits (P135)`, `a parked focusMark with the focus on the host's body is dropped; after the host's own move into the frame a second one, parked too, lands on the marker (P135)`, `a page that patched hasFocus to say yes gets no landing the platform's own answer refuses (P135)` | — | — |
1543
- | `marker-has-focus` | `annotate.spec.ts` | `a page that patched hasFocus to say yes gets no landing the platform's own answer refuses (P135)` | — | — |
1570
+ | `marker-late` | `annotate.spec.ts`, `served/nested.spec.ts` | `a parked focusMark doesn't land once the person has moved on to the host's button (P135)`, `a focusMark parked with the focus in the frame doesn't land once the person moves on while it waits (P135)`, `a parked focusMark with the focus on the host's body is dropped; after the host's own move into the frame a second one, parked too, lands on the marker (P135)`, `a page that patched hasFocus to say yes gets no landing the platform's own answer refuses (P135)`, `a parked focusMark doesn't land on a nested page once the person has moved on to the host's button (P135)` | — | — |
1571
+ | `marker-busy` | `nested-late-word.spec.ts`, `served/nested.spec.ts` | `a focusMark a busy page takes late doesn't land once the host's page has moved on (P137)`, `a page that stopped Date.now gets no landing for a word it took late (P137)`, `a page that patched hasFocus to say yes gets no landing for a word it took late (P137)`, `a focusMark a busy nested page takes late doesn't land once the host's page has moved on (P137)` | — | — |
1572
+ | `marker-clock` | `nested-late-word.spec.ts` | `a page that stopped Date.now gets no landing for a word it took late (P137)` | — | — |
1573
+ | `marker-has-focus` | `annotate.spec.ts`, `nested-late-word.spec.ts` | `a page that patched hasFocus to say yes gets no landing the platform's own answer refuses (P135)`, `a page that patched hasFocus to say yes gets no landing for a word it took late (P137)` | — | — |
1544
1574
  | `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)` | — | — |
1545
1575
  | `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` | — | — |
1546
1576
  | `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` | — | — |
@@ -1576,6 +1606,7 @@ control the tables above name to the registry):
1576
1606
  | `comments-in-frame` | `served/runtime.spec.ts` | `comments.open while the person types in the host's composer reaches no handler, by the page's own call or the shell's; from a press in the frame it does` | — | — |
1577
1607
  | `cancel-any-mode` | `annotate.spec.ts` | `Escape while selecting text is cancelled, and stays the page's key; with no mode on, a page's own cancel isn't heard (P112)`, `a hostile page fakes reports: the host takes none it didn't ask for, nothing malformed, and not a flood` | — | — |
1578
1608
  | `track-checks` | `annotate.spec.ts` | `a followed mark's box comes as it moves, for that mark only, at most 60 a second, clamped to the frame, until the host stops (P112)` | — | — |
1609
+ | `track-selection-checks` | `annotate.spec.ts` | `a followed selection's place comes as it moves, highlighted, out of view and back, gone and found again, only while the host follows it, at most 60 a second (P138)` | — | — |
1579
1610
  | `order-check` | `annotate.spec.ts` | `every found mark's place in the document comes with its box, offscreen ones too; a place that isn't one is no report (P112)` | — | — |
1580
1611
  | `hold-click` | `annotate.spec.ts` | `holding a block 500 ms selects it and its release's click never reaches the page; a tap, a moving finger and a mouse are the page's (P112)` | — | — |
1581
1612
  | `clear-selection` | `annotate.spec.ts` | `clearSelection takes the page's selection away and tells nothing back; marks and drafts stay, the next selection is told (P115)` | — | — |
@@ -1585,6 +1616,7 @@ control the tables above name to the registry):
1585
1616
  | `door-opaque` | `served/siblings-status.spec.ts` | `[door-reach]` | — | — |
1586
1617
  | `frame-status-order` | `served/outcome.spec.ts` | `a nested page that says it is blocked, through its shell or past it, is told nothing and shown nothing (P124)` | — | — |
1587
1618
  | `shell-namespace` | `served/nested.spec.ts` | `the shell's words are the shell's alone: a page that says them, to its parent or to the host's window, moves nothing` | — | — |
1619
+ | `shell-focus-held` | `served/nested.spec.ts` | `the host's move takes no keyboard from where the host's page went on to in the same task (P136)`, `a second host's move into a page it just handed the focus to leaves it there: no blur, and its field keeps the keyboard (P136)` | — | — |
1588
1620
  | `shell-label,nested-host-label,nested-shell-origin` | `served/nested-siblings.spec.ts` | `[nested-siblings]`, `[nested-label]` | — | — |
1589
1621
  | `nested-host-label` | `served/nested-siblings.spec.ts` | `[nested-label]` | — | — |
1590
1622
  | `nested-shell-origin` | `served/nested-siblings.spec.ts` | nothing | — | the host's mount refuses a shell located on any other label first, and /server serves none there (`shell-label,nested-host-label,nested-shell-origin`) |
@@ -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.13 (2026-11-06). A review on 2026-10-19 found gaps, and every decision it led to
8
+ **Status.** This describes Porthole 0.14.15 (2026-11-08). 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
@@ -37,8 +37,11 @@ reports `activated`, which the page could already fake; `lastLineDocumentRect` i
37
37
  host to clip as P132's are; no wall moves. 0.14.12: P134 adds `annotations.focusMark(id)`, the host's
38
38
  word to put the keyboard back on a marker, and a second exception to "takes no focus" whose conditions
39
39
  are the host's own (§6, §7); no wall moves. 0.14.13: P135 drops a `focusMark` that had to wait unless the focus is
40
- in the frame's document by then; a call on a calm page is unchanged. Known gap: a nested page that had the
41
- focus doesn't get it back from `display.focus()` (§6).
40
+ in the frame's document by then; a call on a calm page is unchanged. 0.14.14: P136 brings `display.focus()`
41
+ through a nested page's shell with a new host-to-shell word no page can say; P137 applies P135's check to a
42
+ word 100 ms old or more; no wall moves. 0.14.15: P138 lets the host follow the current selection
43
+ (`selectionTracked`, the same boxes as `tracked`, on its budget, only while asked) and keeps what was
44
+ picked lit; no wall moves.
42
45
 
43
46
  ## 1. Two layers
44
47
 
@@ -212,8 +215,9 @@ Whatever the use:
212
215
  app with egress, S5, unless you accept it). Take its counts as the bar's numbers, and open your
213
216
  bar on `findRequested`, nothing more (§7 "Find in page").
214
217
  - Guard a view that a frame's report opens or moves (`activated`, `anchored`, `selected`,
215
- `tracked`: a comment's bubble, a composer, a card that follows its mark, which the page moves
216
- at will, up to 60 times a second). The content chooses when it appears and where, so it can bring it
218
+ `tracked`, `selectionTracked`: a comment's bubble, a composer, a card that follows its mark, a
219
+ composer that follows the selection (P138), which the page moves at will, up to 60 times a
220
+ second, and hides and shows again with `inView`). The content chooses when it appears and where, so it can bring it
217
221
  under a press the person meant for the content (a double click on the content's own button whose
218
222
  second click lands on the bubble's). Such a view takes no press of any kind for 500 ms after it
219
223
  appears or moves (not a `click` only: menu triggers act on `pointerdown`, and menu items click
@@ -235,7 +239,10 @@ Whatever the use:
235
239
  it reads its own page's `document.activeElement` and that is this frame; the focus goes only to a
236
240
  container that takes no input (`tabindex="-1"`), never a field or a button; and every control in
237
241
  that view that can write has the host's own gate, so that a forged opening and the keys right after
238
- it can't submit. That's the host's duty: Porthole doesn't guarantee it.
242
+ it can't submit. The gate covers keys as well as controls: with the focus in that view the person's
243
+ next keys reach the host's document, so the view's own key handlers and the host's page-wide
244
+ shortcuts that write (an `r` that resolves, Cmd+Enter that posts) need it too (P137). That's the
245
+ host's duty: Porthole doesn't guarantee it.
239
246
  - Know that a display can take the keyboard: a page calls `focus()` on its own input whenever it
240
247
  likes (on Chromium and WebKit with no gesture), and what the person goes on typing goes to it.
241
248
  `createHost` (every `PortholeView` too) gives focus back when it leaves one of the page's text
@@ -246,13 +253,16 @@ Whatever the use:
246
253
  a fighting frame holds focus); and with a platform of your own, implement its focus guard
247
254
  (`focused`, `onFocusTaken`, `focus`) or accept that a display can read what is typed beside it.
248
255
  - Call `annotations.focusMark(id)` only as the person's key closes your view of that mark, and know
249
- it can be dropped (P135): one that has to wait while the frame finds its marks lands only if the
250
- focus is in the frame by then, and in the normal flow it is on your `<body>`. Nothing says so. If
256
+ it can be dropped (P135, P137): one that has to wait while the frame finds its marks, or that the
257
+ frame takes more than 100 ms after you sent it because its page is busy, lands only if the focus
258
+ is in the frame by then, and in the normal flow it is on your `<body>`. Nothing says so. If
251
259
  the focus is still on your body a moment later, the person hasn't moved on: `display.focus()`,
252
260
  then `focusMark(id)` again. Look first: that move is yours, the focus guard doesn't judge it, and
253
- a move after the person went on to a button of yours takes the keyboard from them. A known gap
254
- (P135): on a nested page that had the focus, `display.focus()` doesn't bring it back, so a word
255
- that waits is dropped even then. Nothing leaks: the keyboard stays out of the page.
261
+ a move after the person went on to a button of yours takes the keyboard from them. On a nested
262
+ page, use `display.focus()`: it tells the page's shell to pass the focus on (P136), and the frame's
263
+ own `focus()` stops at the shell, so a word that waits is dropped even after it. On Firefox,
264
+ `display.focus()` inside a key's own handler moves nothing: call it from a task (measured on a
265
+ nested page). Nothing leaks either way: the keyboard stays out of the page.
256
266
  - List every app origin in `appOrigins` (`hostOrigins` in `/server`): only those may frame content,
257
267
  and only those are checked against the content domain for a shared site.
258
268
  - Under the app runtime, run `defineRuntimeConformance` with `api` in CI (§7).
@@ -848,7 +858,14 @@ own frame, below the shell, P111), so:
848
858
  the frame as well (accepted, P132; the host's duty in §6). They say nothing else: the page knows
849
859
  where its words are anyway. Where a selection or a mark's words end (`lastLineDocumentRect` in
850
860
  `selected`, `anchored` and `tracked`, P133) is one more such box, read, checked and left unclamped
851
- the same way, with the same duty; `selected` also carries `scroll` now.
861
+ the same way, with the same duty; `selected` also carries `scroll` now. A report with a last line
862
+ and no `scroll` is dropped (P137), as a malformed part drops one. A followed selection's reports
863
+ (`selectionTracked`, P138) are the same boxes, checked and clamped the same way, taken only while
864
+ the host follows the selection and within `tracked`'s 60 a second (control
865
+ `track-selection-checks`); their `inView` is false unless the box reaches the frame's viewport as
866
+ the host reads it. They carry nothing of the page's words. The page reads the host's word that
867
+ starts and ends the following, so it learns when a composer is open on its selection, as it
868
+ learns which card is open from `track` (P112): end it on every close, kept or dismissed.
852
869
  - *What holds, against content that patches none of the DOM's or JavaScript's built-ins.* A real
853
870
  press or click on a marker reaches none of the content's handlers (the shell's first listener
854
871
  stops it; control `marker-click`) and moves neither focus nor a selection (control
@@ -886,7 +903,7 @@ own frame, below the shell, P111), so:
886
903
  `activated` while the person really is in the frame, and this signal doesn't stop that.** A host
887
904
  that moves the keyboard into its view on the signal takes §6's second exception, with its
888
905
  conditions: a page can put the person's next keys in that view, and keeping those keys from posting
889
- is the host's own gate on that view's controls, not Porthole's.
906
+ is the host's own gate on that view's controls and on its shortcuts, not Porthole's.
890
907
  - *Back to a marker* (P134). `annotations.focusMark(id)` is the host's word to the frame
891
908
  (`porthole/annotate.focusMark`, `{ id }`), for one moment only: after the keyboard closed the host's
892
909
  own view of that mark, by Escape or by a Tab past its first or last control. No content goes with it, beyond an id the frame has, and nothing comes back. The
@@ -898,15 +915,23 @@ own frame, below the shell, P111), so:
898
915
  host's text field that still has focus it is undone and counted (P109), not passed as the host's:
899
916
  no window was opened in the guard for it.
900
917
  A word that has to wait while the frame finds its marks is up to a second old when it could land
901
- (P135), and a marker's `focus()` takes the keyboard with no gesture on Chromium and WebKit, past a
902
- guard that defends only text fields: a person gone on to a host's button would be pulled back. So
903
- the shell drops a parked word unless the focus is in its document as it lands, by `hasFocus` as it
904
- was before content ran (control `marker-has-focus`: a page that replaced it to say yes gets the
905
- landing otherwise; `marker-late` takes the test out). A word that doesn't wait isn't asked: it is
906
- the host's word of this moment, and the frame has no focus then on the very path it is for. A page
918
+ (P135). A word the shell doesn't park can be as old: the frame takes it when its thread is free, a
919
+ busy page changes nothing the shell can see, and a frame out of process doesn't stop the host's
920
+ page meanwhile (P137). A marker's `focus()` takes the keyboard with no gesture on Chromium and
921
+ WebKit, past a guard that defends only text fields: a person gone on to a host's button would be
922
+ pulled back. So the shell drops a parked word unless the focus is in its document as it lands, and
923
+ a word older than 100 ms unless the focus is there as it comes, by `hasFocus` as it was before
924
+ content ran (control `marker-has-focus`: a page that replaced it to say yes gets the landing
925
+ otherwise; `marker-late` takes the first test out, `marker-busy` the second). A word's age is the
926
+ shell's `Date.now` as it was before content ran, less the stamp `createHost` put on it as it was
927
+ sent (`at`): one machine's wall clock (control `marker-clock`: a page that stopped its own clock
928
+ makes a late word look fresh otherwise). A word with no stamp, from an older host, is old. A fresh
929
+ word isn't asked: the frame has no focus then on the very path it is for. That leaves a person who
930
+ moves on within those 100 ms, faster than a person does, and a page that forges the whole word with
931
+ a fresh stamp, or rewrites a real word as it arrives, as it can forge the word at all, which gives it nothing (P134). A page
907
932
  can really take the focus and so pass the test, which gives it nothing, since it then has the
908
- keyboard; and a parked word can still move the focus off the page's own field onto a marker, inside
909
- the frame. §6 has the host's side: a second `focusMark` after its own `display.focus()`.
933
+ keyboard; and a word that passes it can still move the focus off the page's own field onto a marker,
934
+ inside the frame. §6 has the host's side: a second `focusMark` after its own `display.focus()`.
910
935
  The word is a message, so from the host's close until the frame moves, the focus rests on the host's
911
936
  body. A forged `activated` in that gap finds no frame focused, so a host that gates a view on "the
912
937
  frame had the focus" doesn't gate that one. That is accepted, on the host's side of the wall: such
@@ -1043,7 +1068,8 @@ unposted words beside the frame and tell the page when.
1043
1068
  since; or a Tab, the host's own move, or a press the engine shows on the frame element. Nothing
1044
1069
  else counts as a press: no pointer over the frame, no host-wide activation. A move the shell
1045
1070
  hasn't spoken of yet waits for its word at most 500 ms (the host asks it to look at once,
1046
- `porthole/shell/look`), then is taken back. A key the person types into the page turns its
1071
+ `porthole/shell/look`), then is taken back. The shell passes a focus on to the page by the host's
1072
+ word (`porthole/shell/focus`, P136), which only `display.focus()` sends and no page can say. A key the person types into the page turns its
1047
1073
  activation on as a press does, so (P120, after the audit of P111's guard, NG-1): where the
1048
1074
  host's page sees the pointer over its frames (Firefox; Chromium and WebKit where the frame is in
1049
1075
  their process, once the pointer has been over one), an activation while the pointer isn't over
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.14.13",
3
+ "version": "0.14.15",
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": {
@@ -86,6 +86,13 @@ export interface AnnotateMode {
86
86
  readonly text?: boolean;
87
87
  }
88
88
 
89
+ /**
90
+ * What `annotations.track` follows (P112, P138): a shown mark, by its id; the selection the frame
91
+ * last reported as `selected` (the element picked, or the words selected), highlighted in the
92
+ * frame while followed; or nothing (`null`). One at a time: each replaces the last.
93
+ */
94
+ export type AnnotationTrackTarget = string | { readonly selection: true } | null;
95
+
89
96
  /**
90
97
  * An anchor the host marks in the frame, under its own id. Everything here is sent into the
91
98
  * frame, so the content can read it: give ids that say nothing (never a person's name or the
@@ -137,7 +144,8 @@ export interface AnchorResult {
137
144
  * Where its last line is in the document (P133), in the coordinates of `documentRect` and as
138
145
  * unclamped: its last line with words on it for text, its whole box for an element, which has no
139
146
  * lines of its own. For a host's UI after the last line (its right, or its bottom). Absent from
140
- * an older shell, and where nothing of the mark is drawn. The page's word.
147
+ * an older shell, and where nothing of the mark is drawn. Never without its report's `scroll`
148
+ * (a report that tries is dropped, P137). The page's word.
141
149
  */
142
150
  readonly lastLineDocumentRect?: AnnotationRect;
143
151
  /**
@@ -154,7 +162,8 @@ export type AnnotationReport =
154
162
  * The person pointed at an element or settled a text selection. A newer shell (P133) adds where
155
163
  * it ends, for a host's UI after its last line: `lastLineDocumentRect` as a result's is, with
156
164
  * how far the document was scrolled as it was read (so its place in the frame's viewport is the
157
- * one less the other, unclamped). Both absent from an older shell.
165
+ * one less the other, unclamped). Both absent from an older shell, and never one alone (a report
166
+ * that tries is dropped, P137).
158
167
  */
159
168
  | {
160
169
  readonly type: "selected";
@@ -196,7 +205,8 @@ export type AnnotationReport =
196
205
  * document scrolls, so a host following one mark hears the scroll at every animation frame where
197
206
  * it changed, whether that mark is in the frame or not, and places every mark it holds a
198
207
  * `documentRect` for (an `anchored` report's) without asking again. A newer one still (P133) adds
199
- * its `lastLineDocumentRect`.
208
+ * its `lastLineDocumentRect`, never without `scroll` (a report that tries is dropped, P137), though
209
+ * `scroll` comes without it.
200
210
  */
201
211
  | {
202
212
  readonly type: "tracked";
@@ -206,6 +216,30 @@ export type AnnotationReport =
206
216
  readonly lastLineDocumentRect?: AnnotationRect;
207
217
  readonly scroll?: AnnotationScroll;
208
218
  }
219
+ /**
220
+ * Where the selection the host follows is (`annotations.track({ selection: true })`, P138): the
221
+ * element picked or the words selected, as the last `selected` reported them, at an animation
222
+ * frame where it moved or the frame's viewport changed size; at most 60 a second, together with
223
+ * `tracked` (one followed thing at a time). The same boxes as `tracked`'s: `rect` clamped to the
224
+ * frame, `documentRect` and `lastLineDocumentRect` in the document and unclamped, the `scroll`
225
+ * they were read at, always there. `inView`: whether any of it is inside the frame's viewport
226
+ * (false where the shell says so, or where `rect` lies wholly outside the viewport as the host
227
+ * reads it); hide UI attached to it while false. `orphaned`: it isn't in the page now (taken out,
228
+ * its words gone; or the frame has no selection, a new frame after a reload); `attached` again if
229
+ * it is found again by its anchor. The first report comes at the frame's next animation frame
230
+ * after the host asks, which is how a host tells a shell that follows a selection (an older one
231
+ * sends none). Geometry only, as `tracked`: no anchor, no words. The content's word.
232
+ */
233
+ | {
234
+ readonly type: "selectionTracked";
235
+ readonly state: "attached";
236
+ readonly rect: AnnotationRect;
237
+ readonly documentRect: AnnotationRect;
238
+ readonly lastLineDocumentRect?: AnnotationRect;
239
+ readonly scroll: AnnotationScroll;
240
+ readonly inView: boolean;
241
+ }
242
+ | { readonly type: "selectionTracked"; readonly state: "orphaned" }
209
243
  /**
210
244
  * The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
211
245
  * (P107), or pressed Enter or Space on it (P133); `rect` is the marker's box, to open the host's
@@ -234,10 +268,16 @@ export const ANNOTATE_METHODS = {
234
268
  anchored: "porthole/annotate.anchored",
235
269
  /** Frame → host: a mark's marker was clicked, or pressed from the keyboard (P104, P133). */
236
270
  activated: "porthole/annotate.activated",
237
- /** Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112). */
271
+ /**
272
+ * Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112), or the
273
+ * selection last reported, highlighted while followed (`{ id: null, selection: true }`, P138: an
274
+ * older shell reads it as none).
275
+ */
238
276
  track: "porthole/annotate.track",
239
277
  /** Frame → host: the followed mark's box, as it moves (P112). */
240
278
  tracked: "porthole/annotate.tracked",
279
+ /** Frame → host: where the followed selection is, as it moves (P138). */
280
+ selectionTracked: "porthole/annotate.selectionTracked",
241
281
  /** Host → frame: take the page's text selection away, telling nothing back (P115). */
242
282
  clearSelection: "porthole/annotate.clearSelection",
243
283
  /**
@@ -8,6 +8,7 @@ import {
8
8
  type AnnotationReport,
9
9
  type AnnotationScroll,
10
10
  type AnnotationSelector,
11
+ type AnnotationTrackTarget,
11
12
  } from "./types.ts";
12
13
  import { withoutUnseen } from "../bridge/unseen.ts";
13
14
 
@@ -145,6 +146,25 @@ export function clampRect(
145
146
  return { x: left, y: top, width: right - left, height: bottom - top };
146
147
  }
147
148
 
149
+ /**
150
+ * Whether a box the frame reported overlaps the frame's viewport (P138), before it is clamped: a
151
+ * box of no width or height counts where it lies strictly inside. Where the viewport isn't known,
152
+ * nothing is in it, as `clampRect` puts every box at the corner then.
153
+ */
154
+ export function inViewport(
155
+ rect: AnnotationRect,
156
+ viewport: { readonly width: number; readonly height: number } | null | undefined,
157
+ ): boolean {
158
+ if (viewport === null || typeof viewport !== "object") {
159
+ return false;
160
+ }
161
+ const { width, height } = viewport;
162
+ if (!Number.isFinite(width) || !Number.isFinite(height)) {
163
+ return false;
164
+ }
165
+ return rect.x < width && rect.x + rect.width > 0 && rect.y < height && rect.y + rect.height > 0;
166
+ }
167
+
148
168
  const markId = (value: unknown): value is string => text(value, LIMITS.id, 1);
149
169
 
150
170
  function results(value: unknown): AnchorResult[] | null {
@@ -192,6 +212,15 @@ function results(value: unknown): AnchorResult[] | null {
192
212
  return out;
193
213
  }
194
214
 
215
+ /**
216
+ * A last line with nothing to read it by (P137): its place in the frame's viewport is its own less
217
+ * the scroll it was read at, so a shell sends no last line without one, and a host needn't test for
218
+ * both. The scroll alone is a shell's own: 0.14.10's `tracked` and `anchored` (P132, no last line yet),
219
+ * and a newer one's where nothing of the mark is drawn.
220
+ */
221
+ const lineWithoutScroll = (line: AnnotationRect | undefined, scroll: unknown): boolean =>
222
+ line !== undefined && scroll === undefined;
223
+
195
224
  /** A report from the frame, checked; null if malformed (it is then dropped). */
196
225
  export function parseReport(value: unknown): AnnotationReport | null {
197
226
  if (!isRecord(value)) {
@@ -210,6 +239,10 @@ export function parseReport(value: unknown): AnnotationReport | null {
210
239
  if (anchor === null || rect === null || lastLineDocumentRect === null || scroll === null) {
211
240
  return null;
212
241
  }
242
+ // A pair, here (P137): a selection has never had one without the other.
243
+ if ((lastLineDocumentRect === undefined) !== (scroll === undefined)) {
244
+ return null;
245
+ }
213
246
  return {
214
247
  type: "selected",
215
248
  anchor,
@@ -225,9 +258,14 @@ export function parseReport(value: unknown): AnnotationReport | null {
225
258
  case "anchored": {
226
259
  const checked = results(value.results);
227
260
  const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
228
- return checked === null || scroll === null
229
- ? null
230
- : { type: "anchored", results: checked, ...(scroll === undefined ? {} : { scroll }) };
261
+ if (
262
+ checked === null ||
263
+ scroll === null ||
264
+ checked.some((each) => lineWithoutScroll(each.lastLineDocumentRect, scroll))
265
+ ) {
266
+ return null;
267
+ }
268
+ return { type: "anchored", results: checked, ...(scroll === undefined ? {} : { scroll }) };
231
269
  }
232
270
  case "activated": {
233
271
  const rect = parseRect(value.rect);
@@ -248,7 +286,8 @@ export function parseReport(value: unknown): AnnotationReport | null {
248
286
  rect === null ||
249
287
  documentRect === null ||
250
288
  lastLineDocumentRect === null ||
251
- scroll === null
289
+ scroll === null ||
290
+ lineWithoutScroll(lastLineDocumentRect, scroll)
252
291
  ) {
253
292
  return null;
254
293
  }
@@ -261,6 +300,40 @@ export function parseReport(value: unknown): AnnotationReport | null {
261
300
  ...(scroll === undefined ? {} : { scroll }),
262
301
  };
263
302
  }
303
+ case "selectionTracked": {
304
+ // The followed selection (P138): gone, or where it is. New with its shell, so every box but
305
+ // the last line, and the scroll, are there; nothing about the page's words is.
306
+ if (value.state === "orphaned") {
307
+ return { type: "selectionTracked", state: "orphaned" };
308
+ }
309
+ if (value.state !== "attached" || typeof value.inView !== "boolean") {
310
+ return null;
311
+ }
312
+ const rect = parseRect(value.rect);
313
+ const documentRect = parseRect(value.documentRect);
314
+ const scroll = parseScroll(value.scroll);
315
+ const lastLineDocumentRect =
316
+ value.lastLineDocumentRect === undefined
317
+ ? undefined
318
+ : parseRect(value.lastLineDocumentRect);
319
+ if (
320
+ rect === null ||
321
+ documentRect === null ||
322
+ scroll === null ||
323
+ lastLineDocumentRect === null
324
+ ) {
325
+ return null;
326
+ }
327
+ return {
328
+ type: "selectionTracked",
329
+ state: "attached",
330
+ rect,
331
+ documentRect,
332
+ ...(lastLineDocumentRect === undefined ? {} : { lastLineDocumentRect }),
333
+ scroll,
334
+ inView: value.inView,
335
+ };
336
+ }
264
337
  default:
265
338
  return null;
266
339
  }
@@ -326,3 +399,16 @@ export function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[] {
326
399
  };
327
400
  });
328
401
  }
402
+
403
+ /**
404
+ * Whether what `annotations.track` is given names the selection (P138): an object whose own
405
+ * `selection` is `true`, and nothing else does (a mark's id is a string).
406
+ */
407
+ export const followsSelection = (
408
+ target: AnnotationTrackTarget | undefined,
409
+ ): target is { readonly selection: true } =>
410
+ typeof target === "object" &&
411
+ target !== null &&
412
+ Object.hasOwn(target, "selection") &&
413
+ // A caller's word, untyped as JavaScript passes it: `true` and nothing else.
414
+ (target as { readonly selection?: unknown }).selection === true;