@botiverse/porthole 0.14.15 → 0.14.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/DECISIONS.md CHANGED
@@ -2740,7 +2740,7 @@ artifact's display, not one sent eleven seconds before the load, and never for a
2740
2740
  Porthole supports lacks the Navigation API (then `frame-src` is the wall, and a set's pages restart
2741
2741
  the display).
2742
2742
 
2743
- ## P085 · 2026-10-18 · The capability runtime: one global, `porthole.use(name)`, under a contract pinned per artifact · Accepted; amended by P091
2743
+ ## P085 · 2026-10-18 · The capability runtime: one global, `porthole.use(name)`, under a contract pinned per artifact · Accepted; amended by P091, P139
2744
2744
 
2745
2745
  Task #124 (contract §7): a page published as an artifact is an app, and an app needs more of its host
2746
2746
  than 0.6's host functions: who is viewing, its comments, a new version of itself, an asset library,
@@ -4376,7 +4376,7 @@ aren't offered.
4376
4376
  the issue); a host needs image blocks (show them, then offer `image`); or a host's composer is the
4377
4377
  common surface (the React binding could offer a chip there).
4378
4378
 
4379
- ## P099 · 2026-10-19 · A served page carries its frame's sandbox in its own CSP; on a tab the shell opens no window · Accepted
4379
+ ## P099 · 2026-10-19 · A served page carries its frame's sandbox in its own CSP; on a tab the shell opens no window · Accepted; amended by P139
4380
4380
 
4381
4381
  The 2026-10-19 review of value and scenarios, S4 and its first P0 (baseline 264b12f): a served
4382
4382
  page opened on a tab of its own (a public link, "open in a new tab", a bookmark, a frame's address
@@ -8288,7 +8288,7 @@ of the host's, like the rest of the exception. No code changes.
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
8290
 
8291
- ## P138 · 2026-11-08 · The selection followed: a composer stays beside what it is for, and what was picked stays lit · Accepted
8291
+ ## P138 · 2026-11-08 · The selection followed: a composer stays beside what it is for, and what was picked stays lit · Accepted; amended by P140
8292
8292
 
8293
8293
  Amends P112 (`track` follows the selection too) and P118 (`trackedSelection`). From a Raft user's
8294
8294
  report, Kirby's design.
@@ -8450,3 +8450,206 @@ selection inside a page's own scrolling box (its `inView` there is the viewport'
8450
8450
  Escape in the frame should end a composer by itself; `inView` on a followed mark's `tracked` too; or
8451
8451
  an older host's people are seen confused by a pick's outline that stays.
8452
8452
 
8453
+
8454
+ ## P139 · 2026-11-08 · On a tab the shell asks no host, and says how its handshake ended · Accepted
8455
+
8456
+ Amends P085 (the handshake's give-up) and P099 (a page on a tab). From Raft's publish check (task
8457
+ #proj-workspace:#232): its Worker opens each version's ticket top-level in a headless browser and
8458
+ waits a fixed 10.5 s before it shoots, for the shell to give up.
8459
+
8460
+ **Context.** The shell asks its host `ui/initialize` up to 40 times, 250 ms apart, before the
8461
+ runtime is told there is nothing to offer (`runtimeOffer(null)`), since a host may start listening
8462
+ after the frame's shell runs. It did that on a tab of its own too (`window.top === window`), where
8463
+ its parent is the window itself: `post` sends nothing there (`window.parent !== window` is false),
8464
+ so 40 requests sat unanswered in `pending` and the handshake ended 10 s after the page started,
8465
+ every time. `porthole.use` was null at once on a tab already (P085: it checks the window itself),
8466
+ so a page drew the same either way; but a tool that shoots a page on a tab can't know when the
8467
+ shell has settled, and waited for the worst case.
8468
+
8469
+ **Decision.**
8470
+ 1. **On a tab the shell asks nothing.** `HANDSHAKE` (`shell/runtime.ts`, spliced into the runtime
8471
+ as `HELD_BACK` is) is the handshake as it was, with one first step: given `window.top === window`
8472
+ (read as the shell starts, before any content runs; `top` is unforgeable), it ends at once with
8473
+ no host (`runtimeOffer(null)`), no request and no timer. In a frame it is as before, unchanged:
8474
+ 40 tries, 250 ms apart, the first answer taken once, a refusal no answer, and an answer after
8475
+ the give-up still taken.
8476
+ 2. **The shell says how its handshake ended**, on the document's root element (`<html>`):
8477
+ `data-porthole-host="none"` once no host will
8478
+ answer (on a tab, as the shell starts, so before the page's own scripts run; in a frame after
8479
+ the 40th try), `"answered"` once one has (a late answer after `"none"` changes it). A tool that
8480
+ shoots a page on a tab waits for it instead of a fixed time, and a shell without it (before this
8481
+ version) is told apart by its absence: such a tool keeps its fixed wait as the fallback and as
8482
+ the most it waits. The attribute is set through `setAttribute` kept before content runs, on the
8483
+ root as the shell starts. A whole document (an artifact page) replaces the shell's body once the
8484
+ shell's document has loaded, the shell's own script with it, but keeps the root: the render adds
8485
+ the page's own `<html>` attributes to it and removes none (a page whose `<html>` carries
8486
+ `data-porthole-host` itself says its own word, as it can from a script).
8487
+
8488
+ **Not a loosening.** No CSP, sandbox flag, egress, gate or allowlist changes, and no message
8489
+ changes:
8490
+ - *Egress.* On a tab the shell sent nothing before either: `post` goes nowhere when the parent is
8491
+ the window itself. Now it builds no request either. In a frame every message is as it was.
8492
+ - *The runtime.* On a tab `porthole.use` was null at once already, and every capability with it;
8493
+ `runtimeOffer(null)` now comes at the start instead of 10 s in, which wakes nothing on a tab
8494
+ (`use` never waits there). The host functions a page reaches are the bridge's, which a tab has
8495
+ none of: nothing was offered there, and nothing is.
8496
+ - *The attribute.* It is the page's own word and decides nothing: the shell reads it nowhere, and
8497
+ no host or gate trusts it. A page can set, change or remove it, as it can any element's
8498
+ attribute; all that changes is when a tool that reads it shoots the page, which the page could
8499
+ already decide by when it draws. It says nothing the page couldn't learn already (`window.top`,
8500
+ and in a frame the host's answer, which the page shares the shell's realm to hear, P053).
8501
+ - *A frame that claims to be a tab* can't: `window.top` is the browser's own (unforgeable), and a
8502
+ frame that reads itself as a tab is one.
8503
+
8504
+ **Rejected.**
8505
+ - *An event (`porthole:standalone`)*: a tool that attaches after it fired misses it; an attribute
8506
+ can be read at any time, and its absence says "an older shell" at once.
8507
+ - *On the shell's own script element*, where it says which locks didn't take
8508
+ (`data-porthole-unfixed`), as this entry first had it: a whole document's render replaces the
8509
+ body, and the script in it, once the shell's document has loaded, so the word was gone by the
8510
+ time a tool reads a page that has loaded (porthole#118's CI: a probe that read it at
8511
+ `DOMContentLoaded` read nothing, at the event the shell fires again after the page's scripts).
8512
+ The root is the page's too, and frameworks change its attributes, but none removes another's.
8513
+ - *Shortening the frame's retries too*: a host that mounts the frame before it listens is the reason
8514
+ for them, and no tool waits on a frame's handshake.
8515
+
8516
+ **Tested.** `test/shell.test.ts` "the shell's handshake with its host (P085, P139)": `HANDSHAKE` run
8517
+ with its effects recorded and its timers by hand: on a tab, nothing asked, no timer, no host at
8518
+ once; in a frame, 40 asks 250 ms apart then no host; the first answer once and no more asks; a
8519
+ refusal no answer, and an answer after the give-up taken; the runtime splices it, gives it
8520
+ `window.top === window`, asks `ui/initialize` in one place and marks the root (with the setAttribute
8521
+ kept before the locks; the render removes no root attribute). `leak/served/tab.spec.ts` "the shell
8522
+ fixes each of its walls in place…": in a frame nothing until the test answers the shell's
8523
+ `ui/initialize` as a host does (the reference host page answers nothing by itself), then
8524
+ `"answered"`; `"none"` on a tab once its document is parsed; `leak/served/runtime.spec.ts` "on a
8525
+ tab, with no host, use resolves null at once, and the shell says so before the page loaded":
8526
+ `"none"` at the parser's `DOMContentLoaded`, and still after the page's document replaced the
8527
+ shell's body. No negative
8528
+ control: it is no defense.
8529
+
8530
+ **Revisit when** a tab gets a host of its own (an opener that answers, a web view's native bridge),
8531
+ which would need it asked; or a tool needs to know more of the shell's state than its handshake
8532
+ (the page drawn, its scripts run), for which this attribute is no model.
8533
+
8534
+
8535
+ ## P140 · 2026-11-09 · A pick stays lit, and a selection kept, only for a host that follows it (`keepSelection`) · Accepted
8536
+
8537
+ Amends P138 (its decision 2 and Tenny's "no gap at pick time"). From Ferryman's audit of 0.14.15.
8538
+
8539
+ **Context.** P138 changed what every host's people see, not only a host that follows the selection.
8540
+ After a pick the shell kept the element outlined until the next pick or selection,
8541
+ `clearSelection`, `start`, `stop`, `clear`, Escape or the element leaving the page, and kept every
8542
+ `selected` (the element, or a copy of the range) in memory until the next. A host that never calls
8543
+ `track({ selection: true })` got that too: on Chromium and Firefox the outline was still there 2 s
8544
+ after the pick, where 0.14.14 took it away with the pick. The outline is in the layer's closed
8545
+ shadow root and takes no pointer, so the page could neither read it nor be clicked through it; but
8546
+ it is a change to the default path that a host didn't ask for, which CHANGELOG, ADOPTING and P138
8547
+ named and THREAT_MODEL §7 didn't. Two smaller findings with it: a host that follows no selection
8548
+ parsed a page's `selectionTracked` before dropping it, so a malformed one became an
8549
+ `annotate:invalid` refusal where 0.14.14 ignored the method unread; and ADOPTING said in one
8550
+ place that a pick's outline goes with it and later that it stays.
8551
+
8552
+ The outline and the kept selection exist for one thing: a follow that comes after `selected`
8553
+ (the host opens its composer on the report, then asks). The shell can't tell at pick time whether
8554
+ that follow will come, and the host can: it knows whether it follows selections at all.
8555
+
8556
+ **Decision.**
8557
+
8558
+ 1. **`start` says whether the host follows what is selected:** `annotations.start({ ...,
8559
+ keepSelection: true })`, on the wire `porthole/annotate.start` with `keepSelection: true` (absent
8560
+ when false; `annotateMode` throws for a value that isn't a boolean). It holds until the next
8561
+ `start`, and is kept with the mode for a frame that runs later and past a pick that leaves text
8562
+ selection on. A `stop` leaves it, so a stop sent as a composer opens doesn't take the selection
8563
+ away before the follow arrives.
8564
+ 2. **The shell keeps a selection only while the host follows the selection, or said at its last
8565
+ `start` that it will.** Otherwise a `selected` keeps nothing (P138's `held` stays null), a pick's
8566
+ outline goes with the pick (`picked` is set only under `keepSelection`), and the end of a
8567
+ following lets the kept selection go. That is 0.14.14's behaviour, exactly: the same draw at the
8568
+ pick, nothing in memory after it. Under `keepSelection` everything is as P138 has it: the
8569
+ outline until the follow takes it over or the pick ends as a selection does, the selection kept
8570
+ for a follow asked after `selected`.
8571
+ 3. **A follow asked before the pick needs no option.** While the host follows the selection, each
8572
+ `selected` is kept and followed from the next frame, as P138 has it; the highlight is drawn at
8573
+ the pick, in the same draw, so there is no gap either.
8574
+ 4. **React** starts the mode with `keepSelection` while `trackedSelection` is given (true or false),
8575
+ from the first render: `trackedSelection={composerOpen}` is the shape it documents. Read at each
8576
+ start, never a reason for one (after Ferryman's review, below). A host that
8577
+ gives `annotating` a `keepSelection` of its own keeps it too.
8578
+ 5. **`createHost` drops `selectionTracked` unread while it follows no selection**, before parsing
8579
+ it: no report, no refusal, as 0.14.14 dropped a method it didn't know. While it follows, a
8580
+ malformed one is refused as before.
8581
+
8582
+ **Versions.** A newer host with a 0.14.15 shell: the shell ignores `keepSelection` and keeps every
8583
+ pick lit, as it does now. A newer host with an older shell: nothing changes (no follow there). A
8584
+ 0.14.15 host that follows the selection after `selected`, with a newer shell: it never says
8585
+ `keepSelection`, so the shell has nothing to follow and answers `orphaned`. The composer stays
8586
+ where `selected` put it, as with an older shell, until the host upgrades (or asks for the follow
8587
+ before the pick). 0.14.15 is a day old; the CHANGELOG says to upgrade the host with the content
8588
+ server.
8589
+
8590
+ **Not a loosening.** It narrows P138: less is drawn and less is kept for a host that doesn't follow,
8591
+ and a page's word is read by fewer hosts. No CSP, sandbox, egress or gate change. The page reads
8592
+ `keepSelection` (it shares the shell's realm, P053), so it learns at every `start` that the host
8593
+ will follow the selection: before any pick, and earlier than the first `track` would tell it. That
8594
+ is a property of the host's UI, not of anything the person did or wrote. What the shell keeps (a
8595
+ reference to the picked element, a copy of the range) is in the shell's script's memory, not in
8596
+ its layer: only the outline is in the closed shadow root. Negative control `track-selection-checks` now also takes out the unread drop,
8597
+ with the rate.
8598
+
8599
+ **Rejected.**
8600
+ - *Tying it to the following alone* (keep and outline only while `track({ selection: true })` is
8601
+ on, and no option): the host's documented order, P138's sample and React's `trackedSelection`
8602
+ ask for the follow after `selected`, which would then always find nothing. Every following host
8603
+ would have to follow from before the pick, and get `orphaned` reports while nothing is picked:
8604
+ a change to how 0.14.15's hosts call it, where `keepSelection` is one field at `start`. Point 3
8605
+ keeps that order working for a host that prefers it.
8606
+ - *A timer* (keep the pick for a second): P138 chose no timer, and the auditor's 2 s measure would
8607
+ still see it.
8608
+ - *The anchor sent back with `track`, found again by the shell*: no state in the frame, but the
8609
+ gap at pick time returns, and a found anchor can be another element than the one picked.
8610
+ - *`keepPick`* (the auditor's name): what is kept is the words selected too.
8611
+
8612
+ **Tested.** `test/annotate.test.ts`: `annotateMode` with `keepSelection` (only where true, a
8613
+ non-boolean throws); through `createHost`, `start` sends it only where asked and keeps it for a
8614
+ later frame past a pick; "not following the selection, a selectionTracked is dropped unread…": five
8615
+ malformed reports and a good one, no refusal and no report, again after a following ended, and a
8616
+ refusal for the same malformed one while followed; in the shell's runtime, kept only while
8617
+ followed or kept (`keeps()`), `start` setting it and letting go, `holdSelected` keeping nothing
8618
+ otherwise, the outline set only under it, a following's end letting go, `stop` leaving it.
8619
+ `leak/annotate.spec.ts` "without keepSelection or a follow, a pick's outline goes with the pick and
8620
+ nothing is kept…" (Chromium and Firefox here): no outline at the pick and 2 s on; a page's
8621
+ malformed `selectionTracked` no refusal; a follow asked after the pick `orphaned`, nothing drawn; a
8622
+ follow asked before the pick attached and lit, and let go with its end; words selected without it
8623
+ `orphaned` too. P138's browser tests now start with `keepSelection` where they follow after
8624
+ `selected` (the outline, the follow, the scroll, the focus), and React's `trackedSelection` test
8625
+ gives it false from the first render.
8626
+
8627
+ *After Ferryman's review of porthole#119, one change and one correction:*
8628
+
8629
+ - **React restarts no mode for `trackedSelection`.** Decision 4 first put "`trackedSelection` is
8630
+ given" into the mode's key, so the prop appearing or going restarted the mode: a host that keeps
8631
+ `annotating` on and gives `trackedSelection` as its composer opens (0.14.15's prop docs allow it)
8632
+ sent `start` again, element picking came back on after the pick had ended it, and the person's
8633
+ next click in the frame picked again and sent another `selected`. Now the key is the mode alone
8634
+ (`elements`, `text`, and the host's own `keepSelection`), and whether `trackedSelection` is given
8635
+ is read at each start: it rides with the next one, and is never a reason for one. So it counts
8636
+ from the mode's start: given (false is enough) when the mode started, the pick is kept and a
8637
+ follow after it is `attached`; given only after the pick, nothing was kept and the follow is
8638
+ `orphaned`, which is decision 2 for a host that hadn't said it follows (0.14.15 was `attached`
8639
+ there because it kept every host's pick). No shell change, and no message between starts: the
8640
+ shell needs the word before the pick, and a start is where React has it, given from the first
8641
+ render as documented.
8642
+ - **Where things are.** Only the outline is in the layer's closed shadow root; the kept selection
8643
+ (a reference to the element, a copy of the range) is in the shell's script's memory, and it is
8644
+ the page's own DOM. `keepSelection` tells the page at every `start` that the host will follow the
8645
+ selection, before any pick and earlier than the first `track`. THREAT_MODEL §7 now says both.
8646
+
8647
+ *Tested.* `leak/react.spec.ts` "trackedSelection given or left out while annotating stays on
8648
+ restarts no mode…" (Chromium and Firefox here): with the mode left on, `trackedSelection` given after
8649
+ the pick restarts nothing (the next click is no second `selected`) and the follow is `orphaned`, and
8650
+ taking it away restarts nothing either; given as false from the first render, the follow after the
8651
+ pick is `attached` and the next click again no second `selected`. With "is given" back in the key,
8652
+ it fails at the second pick.
8653
+
8654
+ **Revisit when** a host needs the pick kept without following it (a host that draws its own
8655
+ highlight from `selected`), or a host is seen confused by `orphaned` after an upgrade.
package/docs/DESIGN.md CHANGED
@@ -684,6 +684,10 @@ the bridge, `ui/message` and `ui/open-link` into the bridge, `ui/resource-teardo
684
684
  Content may also use the official App SDK directly; the adapter answers a second
685
685
  `ui/initialize` from the same frame, and the shell numbers its own requests with
686
686
  strings (`porthole-shell-1`) so neither takes the other's answers.
687
+ The shell asks `ui/initialize` up to 40 times, 250 ms apart (the host may listen after it runs);
688
+ on a tab of its own it asks nothing, since no host can hear it, and its runtime has nothing to
689
+ offer from the start. The document's root says how the handshake ended (`data-porthole-host`:
690
+ `"answered"`, or `"none"`), for a tool that shoots a page to wait on (P139).
687
691
 
688
692
  The host context carries in `styles.variables` only the names MCP Apps defines
689
693
  (`MCP_APPS_STYLE_VARIABLES`): the official SDK refuses any other name there and fails
@@ -1043,7 +1047,7 @@ chooses), and the annotation runtime is in the shell only then.
1043
1047
 
1044
1048
  | Direction | Message | Params |
1045
1049
  |-----------|---------|--------|
1046
- | host → frame | `porthole/annotate.start` | `{ elements, text }`: picking elements (the one under the pointer or finger outlined with its name; a click or tap picks it, never reaching the content; Escape cancels; one pick), selecting text (each settled selection), or both (a click picks, a drag selects) |
1050
+ | host → frame | `porthole/annotate.start` | `{ elements, text, keepSelection? }`: picking elements (the one under the pointer or finger outlined with its name; a click or tap picks it, never reaching the content; Escape cancels; one pick), selecting text (each settled selection), or both (a click picks, a drag selects); `keepSelection: true` (absent otherwise): the host follows what is selected, so the frame keeps it, and a pick's outline, for a follow asked after `selected` (P140) |
1047
1051
  | host → frame | `porthole/annotate.stop` | — |
1048
1052
  | host → frame | `porthole/annotate.show` | `{ marks: [{ id, anchor, count?, kind? }], active? }`: drawn over the content in the shell's own layer (a closed shadow root), found again whenever the content changes; a mark with a `count` (0 to 999; the host clamps a larger one, P116) also gets a marker (P104); `kind: "draft"` (absent: posted) is drawn apart, with a marker and never a count (P107) |
1049
1053
  | host → frame | `porthole/annotate.focus` | `{ id }`: scrolled into view inside the frame, made the active mark, flashed |
@@ -1056,7 +1060,7 @@ chooses), and the annotation runtime is in the shell only then.
1056
1060
  | 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
1061
  | 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
1062
  | 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) |
1063
+ | 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 (otherwise dropped unread, no refusal, P140), 60 a second with `tracked`, its `rect` clamped, `inView` false unless its box as read reaches the viewport (P138) |
1060
1064
  | 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) |
1061
1065
 
1062
1066
  - **Anchors** are W3C Web Annotation selectors, at most one of each:
@@ -1094,7 +1098,8 @@ chooses), and the annotation runtime is in the shell only then.
1094
1098
  of the words' client rects, the box a text marker's place starts from; an element,
1095
1099
  which has no lines of its own, gives its whole box. Its place in the frame's viewport
1096
1100
  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
1101
+ - **The selection followed** (P138, P140). For a host that follows the selection, or said at
1102
+ `start` that it will (`keepSelection`), the shell keeps what each `selected` reported: the
1098
1103
  element picked (a click, or a block held), or a copy of the selection's range (the
1099
1104
  DOM's own `cloneRange`, taken before content runs), which the page's changes keep up to
1100
1105
  date and which stays when the page's own selection goes (the host's `clearSelection`
@@ -1106,13 +1111,17 @@ chooses), and the annotation runtime is in the shell only then.
1106
1111
  the viewport). Taken out of the page, it is `orphaned` once, and found again by its
1107
1112
  anchor as a mark is. It reads boxes only: no focus moves, no selection changes, no
1108
1113
  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
+ `selected`). A newer `selected` replaces it, followed from the next frame. For any other host
1115
+ nothing is kept and a pick's outline goes with the pick, as before P138; the end of a following
1116
+ lets the kept selection go unless `keepSelection` holds (P140). Under `keepSelection`, before the
1117
+ host follows it, the element just picked keeps an outline drawn the same way, so nothing changes
1118
+ on screen when the follow takes over; until a follow it ends as a selection does (the next pick
1119
+ or selection, `clearSelection`, `start`, `stop`, `clear`, Escape, the element leaving the page),
1120
+ on no timer (Tenny's review). While followed, a scroll re-sends no `selected` (P105's follow-up):
1114
1121
  once the following ends, it does again. The React binding sends the following before a mode
1115
- change made in the same render.
1122
+ change made in the same render, and starts the mode with `keepSelection` while
1123
+ `trackedSelection` is given (P140), read at each start and never a reason for one. The host drops a `selectionTracked` unread, before parsing
1124
+ it, while it follows no selection (P140).
1116
1125
  - **Markers** (P104). A mark with a `count` gets a bubble glyph and its number ("99+"
1117
1126
  above 99; 0 the bubble alone), a real button (P133, below), on an element's top right
1118
1127
  corner, inside the frame's width, and at the end of a text anchor's paragraph (P133):
@@ -1606,7 +1615,7 @@ control the tables above name to the registry):
1606
1615
  | `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` | — | — |
1607
1616
  | `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` | — | — |
1608
1617
  | `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)` | — | — |
1618
+ | `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)`, `without keepSelection or a follow, a pick's outline goes with the pick and nothing is kept: a follow asked after it has nothing, one asked before it follows it; a page's malformed word is no refusal (P140)` | — | — |
1610
1619
  | `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)` | — | — |
1611
1620
  | `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)` | — | — |
1612
1621
  | `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.15 (2026-11-08). A review on 2026-10-19 found gaps, and every decision it led to
8
+ **Status.** This describes Porthole 0.14.16 (2026-11-09). 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
@@ -41,7 +41,9 @@ in the frame's document by then; a call on a calm page is unchanged. 0.14.14: P1
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
42
  word 100 ms old or more; no wall moves. 0.14.15: P138 lets the host follow the current selection
43
43
  (`selectionTracked`, the same boxes as `tracked`, on its budget, only while asked) and keeps what was
44
- picked lit; no wall moves.
44
+ picked lit; no wall moves. 0.14.16: P139 has a shell on a tab of its own ask no host; P140 narrows P138: a pick stays lit, and a
45
+ selection is kept in the frame, only for a host that follows the selection (`keepSelection`), and a
46
+ host that follows none drops `selectionTracked` unread (§7).
45
47
 
46
48
  ## 1. Two layers
47
49
 
@@ -863,9 +865,25 @@ own frame, below the shell, P111), so:
863
865
  (`selectionTracked`, P138) are the same boxes, checked and clamped the same way, taken only while
864
866
  the host follows the selection and within `tracked`'s 60 a second (control
865
867
  `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.
868
+ the host reads it. They carry nothing of the page's words; a host that follows no selection
869
+ drops them unread, so a malformed one is no refusal either (P140). The page reads the host's word
870
+ that starts and ends the following, so it learns when a composer is open on its selection, as it
871
+ learns which card is open from `track` (P112): end it on every close, kept or dismissed. The
872
+ outline the frame draws over what was picked, or over the followed selection, is in the shell's
873
+ layer, a closed shadow root that takes no pointer: the page can't read it, and its clicks reach
874
+ the page as before. What the frame keeps for a follow (a reference to the element picked, or a
875
+ copy of the selected range) is not in that layer: it is held in the shell's own script, in
876
+ memory, in a variable no page script can name. It is the page's own DOM all the same (the
877
+ element is the page's, and the range's copy moves with the page's nodes), so it tells the page
878
+ nothing it can't read itself, and the page can change or remove what it points at, which is
879
+ `orphaned`. In 0.14.15 every host's frame kept both after a pick, the outline until the next
880
+ pick or selection, `clearSelection`, `start`, `stop`, `clear`, Escape or the element leaving the
881
+ page, and the kept selection until the next `selected`; since P140 only a host that follows the
882
+ selection (`track({ selection: true })`) or said at `start` that it will (`keepSelection`) gets
883
+ them, and any other host's frame draws and keeps nothing after a pick, as in 0.14.14. The page
884
+ reads `keepSelection` in every `start`, so it learns at each one that the host will follow the
885
+ selection: before any pick, and earlier than the first `track` would tell it. That is a property
886
+ of the host's UI, not of anything the person did or wrote.
869
887
  - *What holds, against content that patches none of the DOM's or JavaScript's built-ins.* A real
870
888
  press or click on a marker reaches none of the content's handlers (the shell's first listener
871
889
  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.15",
3
+ "version": "0.14.16",
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": {
@@ -84,12 +84,21 @@ export interface AnnotateMode {
84
84
  readonly elements?: boolean | "hold";
85
85
  /** Text, by selecting it: each settled selection is reported, and its clearing. */
86
86
  readonly text?: boolean;
87
+ /**
88
+ * That you follow what is selected (P140): `annotations.track({ selection: true })` once
89
+ * `selected` comes (React sets it while `trackedSelection` is given). Only then does the frame
90
+ * keep it for you to follow, the element just picked outlined until the follow takes over. Without
91
+ * it the frame keeps nothing and a pick's outline goes with the pick, as before 0.14.15; a follow
92
+ * asked before the pick still follows each selection reported while it lasts.
93
+ */
94
+ readonly keepSelection?: boolean;
87
95
  }
88
96
 
89
97
  /**
90
98
  * What `annotations.track` follows (P112, P138): a shown mark, by its id; the selection the frame
91
99
  * 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.
100
+ * frame while followed, and kept for a follow asked after `selected` only under `start`'s
101
+ * `keepSelection` (P140); or nothing (`null`). One at a time: each replaces the last.
93
102
  */
94
103
  export type AnnotationTrackTarget = string | { readonly selection: true } | null;
95
104
 
@@ -339,10 +339,19 @@ export function parseReport(value: unknown): AnnotationReport | null {
339
339
  }
340
340
  }
341
341
 
342
- /** What the host may start with: elements, text, or both (default both). */
343
- export function annotateMode(mode: AnnotateMode | undefined): Required<AnnotateMode> {
342
+ /** A mode as the frame gets it: `keepSelection` only where it is true (P140). */
343
+ export type StartedMode = Required<Omit<AnnotateMode, "keepSelection">> & {
344
+ readonly keepSelection?: true;
345
+ };
346
+
347
+ /**
348
+ * What the host may start with: elements, text, or both (default both); and whether it follows
349
+ * what is selected (`keepSelection`, P140).
350
+ */
351
+ export function annotateMode(mode: AnnotateMode | undefined): StartedMode {
344
352
  const elements = mode?.elements ?? true;
345
353
  const words = mode?.text ?? true;
354
+ const keep = mode?.keepSelection ?? false;
346
355
  if (
347
356
  (typeof elements !== "boolean" && elements !== "hold") ||
348
357
  typeof words !== "boolean" ||
@@ -350,7 +359,10 @@ export function annotateMode(mode: AnnotateMode | undefined): Required<AnnotateM
350
359
  ) {
351
360
  throw new TypeError("annotations.start: elements, text, or both");
352
361
  }
353
- return { elements, text: words };
362
+ if (typeof keep !== "boolean") {
363
+ throw new TypeError("annotations.start: keepSelection is true or false");
364
+ }
365
+ return { elements, text: words, ...(keep ? { keepSelection: true } : {}) };
354
366
  }
355
367
 
356
368
  /**
@@ -1,9 +1,4 @@
1
- import {
2
- ANNOTATE_METHODS,
3
- type AnnotateMode,
4
- type AnnotationMark,
5
- type AnnotationReport,
6
- } from "../annotate/types.ts";
1
+ import { ANNOTATE_METHODS, type AnnotationMark, type AnnotationReport } from "../annotate/types.ts";
7
2
  import {
8
3
  annotateMode,
9
4
  checkMarks,
@@ -12,6 +7,7 @@ import {
12
7
  hasMarker,
13
8
  inViewport,
14
9
  parseReport,
10
+ type StartedMode,
15
11
  } from "../annotate/validate.ts";
16
12
  import { FIND_LIMITS, FIND_METHODS, type FindReport, type FindResult } from "../find/types.ts";
17
13
  import { blankQuery, checkFindQuery, parseFindReport, parseFindResult } from "../find/validate.ts";
@@ -234,7 +230,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
234
230
  const replay = new Map<string, unknown[]>();
235
231
  // Annotations: the host's state, given to each frame once it finished its handshake.
236
232
  const annotates = config.capabilities.annotate !== undefined;
237
- let annotating: Required<AnnotateMode> | null = null;
233
+ let annotating: StartedMode | null = null;
238
234
  let marks: AnnotationMark[] = [];
239
235
  let activeMark: string | null = null;
240
236
  // The mark the host follows (P112), or whether it follows the selection instead (P138), and
@@ -452,6 +448,12 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
452
448
  if (type === undefined) {
453
449
  return;
454
450
  }
451
+ // The followed selection (P138) only while the host follows it, and dropped unread
452
+ // otherwise (P140): a host that doesn't follow it takes it as 0.14.14 took a method it
453
+ // didn't know, so a malformed one is no refusal either.
454
+ if (type === "selectionTracked" && !trackingSelection) {
455
+ return;
456
+ }
455
457
  let report = parseReport({ ...(isRecord(raw.params) ? raw.params : {}), type });
456
458
  if (report === null) {
457
459
  void through.call("annotate", null);
@@ -476,12 +478,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
476
478
  emit("annotation", withinFrame(report));
477
479
  return;
478
480
  }
479
- // The followed selection (P138): only while the host follows it, on the same 60 a second
480
- // (one followed thing at a time), past the bridge's rate as the followed mark's.
481
+ // The followed selection (P138): only while the host follows it (above), on the same 60 a
482
+ // second (one followed thing at a time), past the bridge's rate as the followed mark's.
481
483
  if (report.type === "selectionTracked") {
482
- if (!trackingSelection) {
483
- return;
484
- }
485
484
  const at = Date.now();
486
485
  while (trackedTimes.length > 0 && at - (trackedTimes[0] as number) >= 1_000) {
487
486
  trackedTimes.shift();
@@ -504,7 +503,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
504
503
  }
505
504
  // A pick ends with it; holding a block (P112) lasts until the host stops it.
506
505
  if (kind === "element" && annotating.elements === true) {
507
- annotating = annotating.text ? { elements: false, text: true } : null;
506
+ annotating = annotating.text ? { ...annotating, elements: false } : null;
508
507
  }
509
508
  break;
510
509
  }
@@ -520,7 +519,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
520
519
  return;
521
520
  }
522
521
  if (annotating.elements === true) {
523
- annotating = annotating.text ? { elements: false, text: true } : null;
522
+ annotating = annotating.text ? { ...annotating, elements: false } : null;
524
523
  }
525
524
  break;
526
525
  case "anchored": {
package/src/host/types.ts CHANGED
@@ -300,7 +300,11 @@ export interface FindControls {
300
300
  * given to every frame the display runs (a reload, a navigation recovered from).
301
301
  */
302
302
  export interface AnnotationControls {
303
- /** Lets the person point at elements, select text, or both (default both). */
303
+ /**
304
+ * Lets the person point at elements, select text, or both (default both). With
305
+ * `keepSelection: true` (P140) the frame keeps what is selected for `track({ selection: true })`;
306
+ * without it, nothing is kept and a pick's outline goes with the pick.
307
+ */
304
308
  start(mode?: AnnotateMode): void;
305
309
  stop(): void;
306
310
  /** Marks these anchors (replacing the marks before); the frame reports where they are. */
@@ -320,14 +324,17 @@ export interface AnnotationControls {
320
324
  * highlights it while it is followed (an element in the outline it had while it was picked) and
321
325
  * reports `{ type: "selectionTracked", ... }` with the same boxes as `tracked` and `inView`, or
322
326
  * `state: "orphaned"` while it isn't in the page; at most 60 a second together with `tracked`.
323
- * A `show` leaves it, and `stop` (or a pick ending) too: it ends with `track(null)`, `track(id)`
327
+ * The frame keeps a selection to follow only for a host that said so at `start`
328
+ * (`keepSelection`, P140), or one that already follows the selection as it is made: without
329
+ * either, a follow asked after `selected` has nothing to follow and answers `orphaned`. A `show`
330
+ * leaves it, and `stop` (or a pick ending) too: it ends with `track(null)`, `track(id)`
324
331
  * or `clear` (comment posted, composer dismissed, Escape in it), and the highlight with it. A
325
332
  * newer shell answers at its next animation frame; an older one sends nothing (it reads the
326
333
  * message as `track(null)`), so until a `selectionTracked` comes, place by `selected`'s boxes.
327
- * Kept for a frame that runs later, which has no selection: it answers `orphaned`. The element
328
- * just picked stays outlined until then, so call it before a `start` or `stop` sent with it (a
329
- * stop ends that outline); while followed, `selected` isn't re-sent after a scroll (Tenny's
330
- * review).
334
+ * Kept for a frame that runs later, which has no selection: it answers `orphaned`. Under
335
+ * `keepSelection` the element just picked stays outlined until then, so call it before a `start`
336
+ * or `stop` sent with it (a stop ends that outline); while followed, `selected` isn't re-sent
337
+ * after a scroll (Tenny's review).
331
338
  */
332
339
  track(target: AnnotationTrackTarget): void;
333
340
  /** Removes every mark. */