@botiverse/porthole 0.14.14 → 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/ADOPTING.md CHANGED
@@ -289,7 +289,8 @@ composer.onClose(() => display.annotations.clearSelection());
289
289
 
290
290
  - **React** (P118): `PortholeFrame` and `PortholeView` take the same as props: `annotating`,
291
291
  `annotations`, `focusedAnnotation` and `trackedAnnotation` (the mark to follow, by value; `null`
292
- stops), every report through `onAnnotation` (`tracked` too). The selection is cleared through a
292
+ stops), `trackedSelection` (true while your composer is open: the selection is followed in the
293
+ mark's place, P138), every report through `onAnnotation` (`tracked` and `selectionTracked` too). The selection is cleared through a
293
294
  ref, which holds `clearSelection()` only (a `PortholeFrameHandle`; never the display, whose life
294
295
  is the binding's); with no display running it does nothing. Errors the core's calls throw (an id
295
296
  no shown mark has, a config without `annotate`) reach `onHostError`, kind `"annotations"`.
@@ -436,6 +437,45 @@ composer.onClose(() => display.annotations.clearSelection());
436
437
  composer.openAt(frame, clipToFrame(at), report.anchor); // the frame's px: clip them, then add its position
437
438
  });
438
439
  ```
440
+ - **A composer that stays beside what it is for** (P138): `selected` comes once for a pick (and
441
+ for words again only once a scroll settles), and a pick's outline goes with it. Follow the
442
+ selection while your composer is open, `annotations.track({ selection: true })` (React:
443
+ `trackedSelection`), and the frame highlights it (a picked element in the picking outline) and
444
+ reports `selectionTracked` as `tracked` reports a mark: at most 60 a second, its `rect` clamped,
445
+ `documentRect`, `lastLineDocumentRect` and `scroll` as above, and `inView`, so you hide the
446
+ composer (and show your own marker at the frame's edge, from `documentRect` and `scroll`, clipped)
447
+ while it is out of view. `state: "orphaned"`: it isn't in the page now (a re-render took it out;
448
+ a reload); keep the person's words, it may be found again. It follows the latest `selected`, so a
449
+ new pick or selection moves it. One thing is followed at a time: it takes a followed mark's
450
+ place, and `track(null)`, a mark's id or `clear` ends it, the highlight with it. End it on every
451
+ close (posted, dismissed, Escape in your composer: the frame's own Escape doesn't end it), as you
452
+ clear the selection: the page reads when it starts and ends, so an end on every close says nothing
453
+ of what came of it. The composer moves at the page's word: guard it as below, armed again each
454
+ time it moves or shows again. An older shell sends nothing (and draws nothing): place by
455
+ `selected` until the first `selectionTracked`, which a newer one sends at its next animation
456
+ frame. A newer shell keeps the picked element outlined from the pick on, so there is no gap
457
+ before the follow's highlight; ask for the follow before a `start` or `stop` you send as the
458
+ composer opens (React orders them so), or the stop ends that outline a moment before the follow
459
+ draws it again. Without a follow the outline ends as a selection does (the next pick, Escape,
460
+ `clearSelection`, `start`, `stop`, `clear`). While you follow the selection, `selected` isn't
461
+ re-sent after a scroll: read where it is from `selectionTracked`.
462
+
463
+ ```js
464
+ display.on("annotation", (report) => {
465
+ if (report.type === "selected") {
466
+ composer.openBeside(frame, report.rect, report.anchor); // as before: an older shell stops here
467
+ display.annotations.track({ selection: true });
468
+ }
469
+ if (report.type !== "selectionTracked") return;
470
+ if (report.state === "orphaned") return composer.detach(); // keep its words
471
+ if (!report.inView) return composer.collapseToMarker(report.documentRect, report.scroll);
472
+ if (composer.moveBeside(frame, report.rect) > 4) composerGuard.placed();
473
+ });
474
+ composer.onClose(() => {
475
+ display.annotations.track(null); // or the open card's mark: track(cardId)
476
+ display.annotations.clearSelection();
477
+ });
478
+ ```
439
479
  - **The keyboard** (P133): each marker is a button in the frame's Tab order, after the page's own
440
480
  stops, in reading order, named for what it is (`3 comments on "the words"`, from the `count` and
441
481
  the anchor's words, without an element's tag, P134; in English, whatever your UI's language). The
package/docs/DECISIONS.md CHANGED
@@ -5985,7 +5985,7 @@ answer needs its sandbox taken off for a worker, and none is: the narrowest fix
5985
5985
  `Sec-Fetch-Dest: worker` answer) would fix nothing. The agent manual already teaches workers from
5986
5986
  `blob:` URLs only.
5987
5987
 
5988
- ## P112 · 2026-10-28 · 0.14's comment UX: what annotations add for a host's comment modes · Accepted
5988
+ ## P112 · 2026-10-28 · 0.14's comment UX: what annotations add for a host's comment modes · Accepted; amended by P138
5989
5989
 
5990
5990
  **Context.** Raft's comment design (its modes A–C, a card that follows its mark, a list in document
5991
5991
  order, block selection on touch) needs more from `annotate` than 0.13 has. Each addition is the
@@ -6260,7 +6260,7 @@ Tested: `test/shell.test.ts` (`<`, `</`, `</di`, inside an attribute, and whole
6260
6260
  unchanged); `leak/react.spec.ts` "content streams through props…" (a draft cut after `</` and
6261
6261
  after `<` draws neither).
6262
6262
 
6263
- ## P118 · 2026-10-28 · React: `trackedAnnotation` and a handle with `clearSelection` · Accepted; amended by P131
6263
+ ## P118 · 2026-10-28 · React: `trackedAnnotation` and a handle with `clearSelection` · Accepted; amended by P131, P138
6264
6264
 
6265
6265
  **Context.** Raft's web app (Kirby) shows displays through `PortholeFrame` and `PortholeView`,
6266
6266
  which hold the display handle inside: it could not follow a mark (`annotations.track`, P112) or
@@ -8287,3 +8287,166 @@ of the host's, like the rest of the exception. No code changes.
8287
8287
  **Revisit when** a host's calm closes are seen dropped (the word's age on a real machine); people are
8288
8288
  seen moving on inside 100 ms; a platform gives frames a clock that is shared and monotonic; or the
8289
8289
  parked word's own age should count.
8290
+
8291
+ ## P138 · 2026-11-08 · The selection followed: a composer stays beside what it is for, and what was picked stays lit · Accepted
8292
+
8293
+ Amends P112 (`track` follows the selection too) and P118 (`trackedSelection`). From a Raft user's
8294
+ report, Kirby's design.
8295
+
8296
+ **Context.** A host opens its composer on `selected`, where the selection is at that moment. A pick
8297
+ ends with element mode, and its outline with it (`hover = null`), so after the click nothing in the
8298
+ page says which element the composer is for. `selected` is sent once for a pick, and for words again
8299
+ only once a scroll settles, at most a second apart (P105). So a composer drawn as a popover at the
8300
+ report's box stays where the element was as the page scrolls, resizes or lays itself out again, and
8301
+ covers whatever comes there. A posted comment's card has what the composer lacks: `track(id)` follows
8302
+ its mark at every animation frame (P112), with its place in the document (P132), and `anchored` says
8303
+ when it is orphaned. But it follows a mark by id, and the selection has none.
8304
+
8305
+ **Decision.**
8306
+
8307
+ 1. **`annotations.track({ selection: true })`** follows the selection the frame last reported as
8308
+ `selected` (the element picked, by a click or a held block, or the words selected) instead of a
8309
+ mark. One followed thing at a time, as before: a mark's id, `null` or `clear` ends it; a `show`, a
8310
+ `stop` and a pick's end leave it. It is kept for a frame that runs later, as a followed mark is.
8311
+ On the wire it is `porthole/annotate.track` with `{ id: null, selection: true }`.
8312
+ 2. **The shell keeps what each `selected` reported**: the element, or a copy of the range (the DOM's
8313
+ own `cloneRange`, taken before content runs), which the page's changes keep up to date and which
8314
+ outlives the page's own selection (a click elsewhere, the host's `clearSelection`, P115). A newer
8315
+ `selected` replaces it, and a followed selection follows the new one from the next frame. Taken
8316
+ out of the page (a re-render), it is found again by its anchor, as a mark is, at most twice a
8317
+ second while it is gone.
8318
+ 3. **`porthole/annotate.selectionTracked`** reports it as `tracked` reports a mark, on the same clock
8319
+ (an animation frame where it moved, at most one every 16 ms), and also when the frame's viewport
8320
+ changed size: `{ state: "attached", rect, documentRect, lastLineDocumentRect?, scroll, inView }`,
8321
+ or `{ state: "orphaned" }` once while it isn't in the page (or the frame has nothing to follow, a
8322
+ new frame after a reload). The first comes at the frame after the host asks. `inView` is whether
8323
+ any of its box is inside the viewport. It is a new method, not `tracked` with another shape, so
8324
+ that `tracked`'s `id: string` stays as hosts read it and an older host drops it unread (an unknown
8325
+ method is no report, and not a malformed one).
8326
+ 4. **`createHost` takes it only while it follows the selection**, at most 60 a second together with
8327
+ `tracked` (one array: one followed thing, one rate), outside the bridge's rate as `tracked` is
8328
+ (P112). Its `rect` is clamped (P104); `documentRect` and `lastLineDocumentRect` are checked and
8329
+ left unclamped (P132, P133); `inView` is the page's word and the host's together: false unless
8330
+ its box as reported reaches the viewport as the host reads it (`inViewport`), so a page can't say
8331
+ "in view" of a box the clamp puts on an edge. Every field but the last line is required: the
8332
+ method is new with its shell, which always has them.
8333
+ 5. **The followed selection is drawn** in the shell's layer while it is followed: an element in the
8334
+ picking outline (blue, lighter, without the tag that names it), words with a light blue fill and
8335
+ a line under them, apart from the marks' yellow, since no comment is there yet. In the layer's
8336
+ `aria-hidden` outlines, under the layer's `pointer-events: none`: no pointer, no Tab stop, no
8337
+ name. It goes when the following ends.
8338
+ 6. **React**: `trackedSelection?: boolean`. While true the selection is followed in
8339
+ `trackedAnnotation`'s place; false gives that mark back. A separate prop, not a wider
8340
+ `trackedAnnotation`, so the composer's state and the open card's are each a host's own value and
8341
+ the precedence is Porthole's, once.
8342
+
8343
+ **How a host tells, and what an older shell does.** A shell that follows a selection answers at its
8344
+ next animation frame, `attached` or `orphaned`. An older shell reads `{ id: null, selection: true }`
8345
+ as `track(null)`: it follows nothing, sends nothing, and draws nothing, which is today's behaviour,
8346
+ and a host that places by `selected`'s boxes until a `selectionTracked` comes keeps it there. An
8347
+ older host never asks, so a newer shell never sends it; a page that sends it anyway to an older host
8348
+ sends a method that host doesn't know.
8349
+
8350
+ **Not a loosening.** No CSP, sandbox flag, egress, gate or allowlist changes, and no new budget:
8351
+ - *Frame to host.* The same boxes the frame already sends in `selected` and `tracked` (`rect`,
8352
+ `documentRect`, `lastLineDocumentRect`, `scroll`) and a boolean, through the same checks, the same
8353
+ clamp and the same 60 a second as `tracked`, which it shares, since one thing is followed at a
8354
+ time: a host that followed a card and now follows a composer takes what it took. No anchor, label
8355
+ or words go with it: those went with `selected`. The host takes it only after it asked.
8356
+ - *Host to frame.* The page reads the host's messages (it shares the shell's realm, P053). It learns
8357
+ that the host follows its selection, and when that ends: that a composer is open on it, and closed.
8358
+ That is P112's `track(id)` (which card is open) and P121's `clearSelection` (when the person was done)
8359
+ for the composer: end it on every close, posted or dismissed, so the end says nothing of what came
8360
+ of it, as P121 asks of the clear.
8361
+ - *What the page can do with it.* It moves the host's composer, within its frame, as often as 60
8362
+ times a second, and can say it is out of view or gone. P112 accepted that for a card that follows
8363
+ its mark, under THREAT_MODEL §6's guard of a view a report moves (no press for 500 ms after it
8364
+ appears or moves, beside the frame where it can, no focus but by §6's exceptions); a composer that
8365
+ follows is such a view, and a composer hidden for `inView: false` and shown again appears again.
8366
+ `selectionTracked` joins §6's list. A forged `orphaned` or `inView: false` is no more than a page
8367
+ that never reports a selection, which it can already do; a host keeps the person's words in the
8368
+ composer either way.
8369
+ - *The layer.* A closed shadow root the page can't read, as for marks; the highlight takes no
8370
+ pointer, so the page's clicks and selections reach it as before.
8371
+
8372
+ **Focus and keys.** Following reads boxes and draws; it calls no `focus()`, changes no selection,
8373
+ adds no listener, and prevents and stops no event. Markers' tab stops, `focusMark` and its tests
8374
+ (P134, P135, P137), `display.focus()` on a nested page (P136), the hold gesture (P112) and Escape (a
8375
+ pick's, and text mode's `cancelled`) are as they were. Escape in the frame doesn't end the following:
8376
+ the host ends it from its composer's own Escape, and a frame's Escape while text is selected is
8377
+ `cancelled` as before (P112).
8378
+
8379
+ **Rejected.**
8380
+ - *A draft mark for the composer* (`show` with `kind: "draft"` and `track` its id), which works today:
8381
+ a draft is a comment the author kept, drawn with a marker, a button in the page's Tab order and
8382
+ named "Draft comment" (P107, P133), anchored again from its selectors (best-effort, 150 ms after a
8383
+ change), and it reaches the page as a draft; the composer is none of those until the person keeps
8384
+ it.
8385
+ - *`selected` re-sent at every frame*: it carries the anchor and its words, which the bridge's rate
8386
+ is for, and an older host would open its composer again at each one.
8387
+ - *`tracked` with `selection: true` and no `id`*: `tracked`'s `id` is a string hosts read, and an
8388
+ older host would count each as a malformed report against the page.
8389
+ - *`inView` computed by the host alone*: the shell can say more (a box its page clips), and the
8390
+ host's test still bounds it.
8391
+
8392
+ **Tested.** `test/annotate.test.ts` "the followed selection (P138)": `parseReport` rebuilds it from
8393
+ known fields (an anchor, a label or an id a page adds are dropped), drops a malformed or incomplete
8394
+ one; `inViewport` and `followsSelection`; through `createHost`, the wire message, an older shell's
8395
+ reading of it, reports taken only while followed, a show leaving it, a mark's id, `null` and `clear`
8396
+ ending it, the clamp and `inView`, 60 a second, and the following kept for a new frame; the shell's
8397
+ runtime: only `selection === true` follows it, a mark's id wins, its tells carry no words and it
8398
+ calls no focus, selection or listener, the kept `cloneRange`, every `selected` kept, the highlight in
8399
+ the aria-hidden outlines. `leak/annotate.spec.ts` "a followed selection's place comes as it moves…"
8400
+ (three engines): a picked element followed and lit, out of view and back as the document scrolls,
8401
+ orphaned when the page takes it out and found again when it puts it back, a page's own word taken
8402
+ neither unasked nor after `track(null)` nor past 60 a second, the highlight gone with the following;
8403
+ "following the selection moves no focus…": with the page's field focused, nothing moves the focus,
8404
+ the page hears every key, Escape is `cancelled` as before, and the words stay followed after the
8405
+ host's `clearSelection`, where the layout moves them. `leak/react.spec.ts` "trackedSelection follows
8406
+ the picked element…": in `trackedAnnotation`'s place, and false gives the mark back;
8407
+ `test/react-ssr.test.ts` its type. Negative control `track-selection-checks` (taken unasked, at any
8408
+ rate).
8409
+
8410
+ *After Tenny's review (porthole#116), two changes, decided by the reviewer:*
8411
+
8412
+ - **No gap at pick time.** A pick's outline went with the pick, and the follow's highlight came only
8413
+ once the host's `track` arrived: a frame or two with nothing drawn. Now the element just picked (a
8414
+ click's, or a held block's) keeps an outline after `selected`, drawn as the follow's highlight is,
8415
+ until the host follows it (the follow takes it over in the same draw, so nothing changes on
8416
+ screen) or the pick ends as a selection does: the next pick, or a selection reported after it;
8417
+ the host's `clearSelection`; a mode started or stopped (`start`, `stop`); `clear`; Escape in the
8418
+ frame (the key is left as it was: nothing prevents or stops it); or the element leaving the page.
8419
+ There is no timer. Not `unselected`: a selection made after the pick already ended it as it was
8420
+ reported, so the only selection `unselected` can be about is one from before the pick, which the
8421
+ pick's own click takes away where text is selected too, and ending on it would take the outline
8422
+ away a moment after the pick. An older host never follows, so its people now see the picked
8423
+ element outlined until one of those, where before the outline went at once: the shell's change
8424
+ alone, bounded by the events that end a selection today.
8425
+ So the follow comes before a mode change that a host makes in the same moment (it ends picking
8426
+ as its composer opens), the React binding sends the following before the mode (the mode's effect
8427
+ now runs after the following's); a host on the core calls `track({ selection: true })` before
8428
+ `start` or `stop`. The other way round, the stop ends the outline and the follow draws it again a
8429
+ task later, which is the gap this removes.
8430
+ - **No re-sent `selected` while followed.** While the selection is followed, a scroll sets no
8431
+ follow-up for it (P105's re-send once a scroll settles): the follow's reports already say where it
8432
+ is, and the re-send spent the bridge's 120 reports a minute, which the person's clicks need. A new
8433
+ selection is still reported, as ever. Once the following ends, a scroll re-sends it as before (its
8434
+ box is compared with the one last told, so one that moved meanwhile is told then).
8435
+
8436
+ *Tested.* `test/annotate.test.ts` "a pick keeps its outline until the host follows it…", "without a
8437
+ follow, a pick's outline ends as a selection does…", "while the selection is followed, a scroll
8438
+ re-sends no selected…" (the shell's runtime, as its other tests read it), and the highlight test
8439
+ reads the outline drawn for either. `leak/annotate.spec.ts` "a pick keeps its outline until the host
8440
+ follows it, and without a follow it ends as a selection does…" (three engines: outlined after the
8441
+ pick and 1.5 s on, then gone at Escape, which the page still hears, at a mode started, at stop, at
8442
+ `clearSelection`, at the next pick, at a selection after a pick, at `clear`; lit as the follow takes
8443
+ over and gone at its end); "while the selection is followed a scroll re-sends no selected…" (no
8444
+ `selected` past the settle and the follow-ups' clock while `selectionTracked` comes, then a re-send
8445
+ once the following ends); the follow's test now finds the picked element outlined before the host
8446
+ follows it. No new negative control: neither is a defense.
8447
+
8448
+ **Revisit when** a host needs two things followed at once (a composer beside an open card); the
8449
+ selection inside a page's own scrolling box (its `inView` there is the viewport's, not the box's);
8450
+ Escape in the frame should end a composer by itself; `inView` on a followed mark's `tracked` too; or
8451
+ an older host's people are seen confused by a pick's outline that stays.
8452
+
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
@@ -1049,12 +1050,13 @@ chooses), and the annotation runtime is in the shell only then.
1049
1050
  | host → frame | `porthole/annotate.clear` | — |
1050
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) |
1051
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()` |
1052
- | 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) |
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) |
1053
1054
  | frame → host | `porthole/annotate.unselected` | — (the text selection went away) |
1054
1055
  | frame → host | `porthole/annotate.cancelled` | — (Escape) |
1055
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) |
1056
- | host → frame | `porthole/annotate.track` | `{ id }` or `{ id: null }`: follow one shown mark, or none (P112) |
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) |
1057
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) |
1058
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) |
1059
1061
 
1060
1062
  - **Anchors** are W3C Web Annotation selectors, at most one of each:
@@ -1092,6 +1094,25 @@ chooses), and the annotation runtime is in the shell only then.
1092
1094
  of the words' client rects, the box a text marker's place starts from; an element,
1093
1095
  which has no lines of its own, gives its whole box. Its place in the frame's viewport
1094
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.
1095
1116
  - **Markers** (P104). A mark with a `count` gets a bubble glyph and its number ("99+"
1096
1117
  above 99; 0 the bubble alone), a real button (P133, below), on an element's top right
1097
1118
  corner, inside the frame's width, and at the end of a text anchor's paragraph (P133):
@@ -1585,6 +1606,7 @@ control the tables above name to the registry):
1585
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` | — | — |
1586
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` | — | — |
1587
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)` | — | — |
1588
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)` | — | — |
1589
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)` | — | — |
1590
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)` | — | — |
@@ -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.14 (2026-11-07). 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
@@ -39,7 +39,9 @@ word to put the keyboard back on a marker, and a second exception to "takes no f
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
40
  in the frame's document by then; a call on a calm page is unchanged. 0.14.14: P136 brings `display.focus()`
41
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.
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.
43
45
 
44
46
  ## 1. Two layers
45
47
 
@@ -213,8 +215,9 @@ Whatever the use:
213
215
  app with egress, S5, unless you accept it). Take its counts as the bar's numbers, and open your
214
216
  bar on `findRequested`, nothing more (§7 "Find in page").
215
217
  - Guard a view that a frame's report opens or moves (`activated`, `anchored`, `selected`,
216
- `tracked`: a comment's bubble, a composer, a card that follows its mark, which the page moves
217
- 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
218
221
  under a press the person meant for the content (a double click on the content's own button whose
219
222
  second click lands on the bubble's). Such a view takes no press of any kind for 500 ms after it
220
223
  appears or moves (not a `click` only: menu triggers act on `pointerdown`, and menu items click
@@ -856,7 +859,13 @@ own frame, below the shell, P111), so:
856
859
  where its words are anyway. Where a selection or a mark's words end (`lastLineDocumentRect` in
857
860
  `selected`, `anchored` and `tracked`, P133) is one more such box, read, checked and left unclamped
858
861
  the same way, with the same duty; `selected` also carries `scroll` now. A report with a last line
859
- and no `scroll` is dropped (P137), as a malformed part drops one.
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.
860
869
  - *What holds, against content that patches none of the DOM's or JavaScript's built-ins.* A real
861
870
  press or click on a marker reaches none of the content's handlers (the shell's first listener
862
871
  stops it; control `marker-click`) and moves neither focus nor a selection (control
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.14.14",
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
@@ -209,6 +216,30 @@ export type AnnotationReport =
209
216
  readonly lastLineDocumentRect?: AnnotationRect;
210
217
  readonly scroll?: AnnotationScroll;
211
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" }
212
243
  /**
213
244
  * The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
214
245
  * (P107), or pressed Enter or Space on it (P133); `rect` is the marker's box, to open the host's
@@ -237,10 +268,16 @@ export const ANNOTATE_METHODS = {
237
268
  anchored: "porthole/annotate.anchored",
238
269
  /** Frame → host: a mark's marker was clicked, or pressed from the keyboard (P104, P133). */
239
270
  activated: "porthole/annotate.activated",
240
- /** 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
+ */
241
276
  track: "porthole/annotate.track",
242
277
  /** Frame → host: the followed mark's box, as it moves (P112). */
243
278
  tracked: "porthole/annotate.tracked",
279
+ /** Frame → host: where the followed selection is, as it moves (P138). */
280
+ selectionTracked: "porthole/annotate.selectionTracked",
244
281
  /** Host → frame: take the page's text selection away, telling nothing back (P115). */
245
282
  clearSelection: "porthole/annotate.clearSelection",
246
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 {
@@ -280,6 +300,40 @@ export function parseReport(value: unknown): AnnotationReport | null {
280
300
  ...(scroll === undefined ? {} : { scroll }),
281
301
  };
282
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
+ }
283
337
  default:
284
338
  return null;
285
339
  }
@@ -345,3 +399,16 @@ export function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[] {
345
399
  };
346
400
  });
347
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;