@botiverse/porthole 0.14.8 → 0.14.10

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.
Files changed (60) hide show
  1. package/CHANGELOG.md +46 -0
  2. package/dist/annotate/types.d.ts +33 -2
  3. package/dist/annotate/validate.d.ts +6 -1
  4. package/dist/annotate/validate.js +31 -3
  5. package/dist/bridge/bridge.d.ts +6 -0
  6. package/dist/bridge/bridge.js +5 -0
  7. package/dist/check/page-source.js +1 -1
  8. package/dist/config/capabilities.d.ts +16 -2
  9. package/dist/config/capabilities.js +8 -0
  10. package/dist/conformance/harness-source.js +1 -1
  11. package/dist/find/types.d.ts +83 -0
  12. package/dist/find/types.js +29 -0
  13. package/dist/find/validate.d.ts +17 -0
  14. package/dist/find/validate.js +82 -0
  15. package/dist/guide/guide.js +2 -1
  16. package/dist/host/create-host.js +219 -3
  17. package/dist/host/pass-on.js +3 -2
  18. package/dist/host/types.d.ts +54 -1
  19. package/dist/index.d.ts +5 -3
  20. package/dist/index.js +4 -1
  21. package/dist/react/frame.d.ts +45 -1
  22. package/dist/react/frame.js +107 -3
  23. package/dist/react/view.js +2 -0
  24. package/dist/runtime/contract.d.ts +1 -1
  25. package/dist/runtime/contract.js +1 -1
  26. package/dist/shell/annotate.d.ts +5 -1
  27. package/dist/shell/annotate.js +41 -107
  28. package/dist/shell/document.d.ts +3 -3
  29. package/dist/shell/document.js +5 -3
  30. package/dist/shell/find.d.ts +82 -0
  31. package/dist/shell/find.js +725 -0
  32. package/dist/shell/runtime.js +4 -1
  33. package/dist/shell/text.d.ts +17 -0
  34. package/dist/shell/text.js +140 -0
  35. package/docs/ADOPTING.md +112 -0
  36. package/docs/ARCHITECTURE.md +10 -3
  37. package/docs/DECISIONS.md +284 -1
  38. package/docs/DESIGN.md +48 -2
  39. package/docs/THREAT_MODEL.md +61 -5
  40. package/docs/insertion-entry-points.md +17 -0
  41. package/package.json +1 -1
  42. package/src/annotate/types.ts +43 -4
  43. package/src/annotate/validate.ts +34 -3
  44. package/src/bridge/bridge.ts +7 -0
  45. package/src/config/capabilities.ts +13 -1
  46. package/src/find/types.ts +86 -0
  47. package/src/find/validate.ts +101 -0
  48. package/src/guide/guide.ts +3 -1
  49. package/src/host/create-host.ts +235 -3
  50. package/src/host/pass-on.ts +3 -2
  51. package/src/host/types.ts +55 -1
  52. package/src/index.ts +14 -1
  53. package/src/react/frame.tsx +162 -2
  54. package/src/react/view.tsx +3 -0
  55. package/src/runtime/contract.ts +1 -1
  56. package/src/shell/annotate.ts +42 -107
  57. package/src/shell/document.ts +5 -3
  58. package/src/shell/find.ts +731 -0
  59. package/src/shell/runtime.ts +4 -1
  60. package/src/shell/text.ts +140 -0
package/docs/DESIGN.md CHANGED
@@ -1050,7 +1050,9 @@ chooses), and the annotation runtime is in the shell only then.
1050
1050
  | frame → host | `porthole/annotate.selected` | `{ anchor, rect }`; after a scroll, the same selection again only if its box moved more than 0.5 px, on the follow-ups' clock (P105) |
1051
1051
  | frame → host | `porthole/annotate.unselected` | — (the text selection went away) |
1052
1052
  | frame → host | `porthole/annotate.cancelled` | — (Escape) |
1053
- | frame → host | `porthole/annotate.anchored` | `{ results: [{ id, state: "attached" \| "orphaned", rect? }] }`: every mark after `show`, the one after `focus`, every mark when the content changed a state, and, while any mark has a marker (a `count` or a draft, P107), once a scroll, a resize or a run of content changes has settled (150 ms quiet), only the marks that moved more than 0.5 px since the host was last told, at most one a second together with the selection's (P104, P105) |
1053
+ | frame → host | `porthole/annotate.anchored` | `{ results: [{ id, state: "attached" \| "orphaned", rect?, documentRect?, order? }], scroll? }` (a newer shell's `documentRect` and `scroll`: P132, below): every mark after `show`, the one after `focus`, every mark when the content changed a state, and, while any mark has a marker (a `count` or a draft, P107), once a scroll, a resize or a run of content changes has settled (150 ms quiet), only the marks that moved more than 0.5 px since the host was last told, at most one a second together with the selection's (P104, P105) |
1054
+ | host → frame | `porthole/annotate.track` | `{ id }` or `{ id: null }`: follow one shown mark, or none (P112) |
1055
+ | frame → host | `porthole/annotate.tracked` | `{ id, rect, documentRect?, 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) |
1054
1056
  | frame → host | `porthole/annotate.activated` | `{ id, rect }`: the person clicked a mark's marker; `rect` is the marker's (P104); taken only while the host's page has transient activation (P105) |
1055
1057
 
1056
1058
  - **Anchors** are W3C Web Annotation selectors, at most one of each:
@@ -1070,6 +1072,17 @@ chooses), and the annotation runtime is in the shell only then.
1070
1072
  hears it (P104); a box wholly outside becomes one of no size on the nearest edge
1071
1073
  (a mark below the fold: `y` at the viewport's height, no height). A platform whose
1072
1074
  `viewport()` answers no size or throws gets nothing at the corner (P105).
1075
+ - **Places in the document** (P132). A newer shell gives each attached result a
1076
+ `documentRect` too: its box plus how far the document was scrolled as it was read, the
1077
+ report's `scroll` (`{ x, y }`: the root element's top left from the viewport's, negated,
1078
+ read with the DOM's own `getBoundingClientRect`). So it stays put as the document
1079
+ scrolls, and says where a mark outside the frame is; `rect` is `documentRect` less
1080
+ `scroll`, before the clamp. `tracked` carries both too: a followed mark's box moves at
1081
+ every scroll, so its reports tell the scroll at each animation frame, in the frame or
1082
+ not. `createHost` checks them as boxes (finite, within the coordinate limit, sizes not
1083
+ negative; a malformed one drops the report) and clamps neither: the host clips what it
1084
+ draws from them. A page that scrolls a box of its own rather than its document moves
1085
+ its marks' places with it, as their `rect` does; those are told as before.
1073
1086
  - **Markers** (P104). A mark with a `count` gets a bubble glyph and its number ("99+"
1074
1087
  above 99; 0 the bubble alone) on an element's top right corner, inside the frame's
1075
1088
  width, and beside a text anchor's last line, centred on it (P105, #36): in the
@@ -1181,6 +1194,38 @@ a selection away from a page that patched `Selection.prototype.removeAllRanges`,
1181
1194
  nothing back, leaves marks and drafts found, and the same words selected again are told
1182
1195
  (`clear-selection`).
1183
1196
 
1197
+ ### Find in page
1198
+
1199
+ A host's own find bar over a display (P131), where the config declares `find`:
1200
+
1201
+ - **Shell.** `FIND_RUNTIME` (`src/shell/find.ts`), spliced in as the annotation runtime is, before
1202
+ content runs. It finds a query (`porthole/find.query`, a request) in annotations' text index
1203
+ (`TEXT_INDEX`, `src/shell/text.ts`, shared), case-insensitive and loose about spacing
1204
+ (`FIND_MATCH`), only matches that are drawn, at most 1,000; draws them in a layer of its own (a
1205
+ closed shadow root, annotations' layer style), the current one apart, redrawn on scroll and
1206
+ resize and found again as the content changes (`porthole/find.updated`, at most once a second);
1207
+ brings the current one into view through its scrolling ancestors and the window; and, while the
1208
+ host says it draws its own bar (`porthole/find.handled`), cancels the browser's find on Cmd+F or
1209
+ Ctrl+F a page didn't take (`FIND_SHORTCUT`) and says `porthole/find.requested`. Like the guards
1210
+ (P129), it and the text index call only built-ins captured before content runs, through
1211
+ `callOf`; its layer goes in through the guarded insertion methods (P130,
1212
+ [insertion-entry-points.md](insertion-entry-points.md) § The shell's own layers).
1213
+ - **Host API.** `display.find.query(query, { direction, caseSensitive })` → `{ total, active,
1214
+ capped?, rect? }` or `"unsupported"` (no `find`, an older shell's `-32601`, a malformed answer, no
1215
+ answer in `FIND_LIMITS.timeoutMs`, a query superseded by a later one: the shell searches only the
1216
+ latest of a burst, `FIND_LATEST`), `clear()`, `takeShortcut(take)`; the query holds only for the
1217
+ content it was asked of (a new run or other content forgets it); events `findRequested`
1218
+ (only while taken, with the page's focus in the frame) and `findUpdated` (only while a query is
1219
+ shown), checked and rate-limited through the bridge. React: `onFindRequested`, `onFindUpdated`,
1220
+ and the handle's `find` and `clearFind`.
1221
+ - **Trust.** The page reads every query; what it says back is a find bar's numbers. Tests:
1222
+ `test/find.test.ts` (the matching and its limits, the shortcut rule, the checks, the shell's
1223
+ splice and built-ins, only the latest query, `createHost`'s requests, answers, forgetting and
1224
+ gates, the React handle's scope); `leak/find.spec.ts`
1225
+ on three engines (highlights, next and previous into view, a scrolling box, a change found again,
1226
+ the shortcut the host's only while taken and the page's own find keeping it, and a hostile page's
1227
+ `requested` while the person types in the host's composer dropped: `find-requested-focus`).
1228
+
1184
1229
  ## The shell runtime
1185
1230
 
1186
1231
  The runtime (`src/shell/runtime.ts`, plain ES2020, no build) runs first in every
@@ -1463,7 +1508,7 @@ control the tables above name to the registry):
1463
1508
  | `draft-count` | `annotate.spec.ts` | `what the page reads of a draft (P107): that it is one, never its count; a posted mark as before` | — | — |
1464
1509
  | `draft-shell-checks` | `annotate.spec.ts` | `the shell's own checks on a raw show (P107): a draft draws no number, a kind it doesn't know is no mark` | — | — |
1465
1510
  | `annotation-activated-gesture` | `annotate.spec.ts` | `a hostile page's marker click with no gesture is dropped; one on the person's own press is the host's view to guard (P105)` | — | — |
1466
- | `annotation-rect-clamp` | `annotate.spec.ts` | `a hostile page reports a box outside its frame: the host gets it clamped to the frame's viewport`, `marks: drawn over their anchors, one brought into view, an unfound one orphaned, all cleared`, `following: once a scroll settles, one report with only the marks that moved` | — | — |
1511
+ | `annotation-rect-clamp` | `annotate.spec.ts` | `a hostile page reports a box outside its frame: the host gets it clamped to the frame's viewport`, `marks: drawn over their anchors, one brought into view, an unfound one orphaned, all cleared`, `following: once a scroll settles, one report with only the marks that moved`, `every attached mark's place in the document comes with the scroll it was read at, offscreen ones too, and the followed mark's as the document scrolls (P132)` | — | — |
1467
1512
  | `authorize` | `served/authorize.spec.ts` | `a revoked subject's ticket opens nothing: a page and an app are denied, and the host is told`, `in a tab of its own, a revoked app and page are denied from the next request on`, `a framed page mid-session: its next load after revocation is denied where the engine keeps its cookie` | Chromium, Firefox: `a framed app mid-session: its next request after revocation is denied, and its next load tells the host` | — |
1468
1513
  | `url-permissions` | `served/permissions.spec.ts` | `a url-mode frame gets no clipboard writes or full screen unless the host delegates them` | — | — |
1469
1514
  | `navigate-guard` | `served/live.spec.ts`, `served/files.spec.ts`, `served/served.spec.ts`, `served/tab.spec.ts` | `served.domain.self-navigation`, `served.domain.tab-navigation`, `served.domain.tab-links`, `can't navigate itself away (location): to a site, or to another content origin`, `can't navigate itself away (replace): to a site, or to another content origin`, `can't navigate itself away (open-self): to a site, or to another content origin`, `can't navigate itself away (navigation-api): to a site, or to another content origin`, `a link to another page of the set opens it in the frame; the display goes on`, `a link to another page of the set opens it in the frame when the leaving page's notice is dropped (P098)`, `a link to another page of the set opens it in the frame when the leaving page's notice is late (P098)`, `a page opens nothing else: not a file that isn't a page, not another path of its origin`, `no report, content error or blocked navigation names the frame's sealed address (P083)` | — | — |
@@ -1514,6 +1559,7 @@ control the tables above name to the registry):
1514
1559
  | `blob-trusted` | `served/runtime.spec.ts` | `a script asset runs as code only if an admin uploaded it where uploads are the admins'` | — | — |
1515
1560
  | `blob-script,blob-trusted` | `served/runtime.spec.ts` | `a script asset runs as code only if an admin uploaded it where uploads are the admins'`, `scripts load from /_blob/ only where uploads are the admins' (a tab, its session)` | — | — |
1516
1561
  | `blob-inert` | `served/runtime.spec.ts` | `an asset opened on its own runs nothing, on a tab with the artifact's session` | — | — |
1562
+ | `find-requested-focus` | `find.spec.ts` | `a hostile page says the find shortcut was pressed while the person types in the host's composer: the host's find bar stays shut (P131)` | — | — |
1517
1563
 
1518
1564
  ## Milestones
1519
1565
 
@@ -5,7 +5,7 @@ What Porthole protects, from whom, and where that protection ends. For each way
5
5
  guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
6
6
  [DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
7
7
 
8
- **Status.** This describes Porthole 0.14.8 (2026-11-04). A review on 2026-10-19 found gaps, and every decision it led to
8
+ **Status.** This describes Porthole 0.14.10 (2026-11-05). 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
@@ -22,10 +22,15 @@ person, not the page, pressed in it (§7 "The keyboard", `comments`); and P112's
22
22
  additions for a host's comment modes (hints, as every report is, §7). 0.14.1: P114
23
23
  (porthole#56) serves a nested page's shell on a label of its own, on which nothing but nested
24
24
  pages' shells, their pages, those pages' files and status pages is ever served, so no other
25
- display of the scope is same-origin with the shell (S3). Unreleased: P128 lets a host opt a config
25
+ display of the scope is same-origin with the shell (S3). 0.14.8: P128 lets a host opt a config
26
26
  into a page's own nested frames (`nestedFrames: "own"`, off by default): its `srcdoc` frames and
27
27
  frames of its own files load and run, in realms the shell's hardening never reaches (WebRTC, the
28
- clipboard's guards: S1, S3); frames of other sites stay out.
28
+ clipboard's guards: S1, S3); frames of other sites stay out. 0.14.9: P131 adds find
29
+ in page (`find`, off unless a config declares it): the host's find bar sends the person's query
30
+ into the frame, where the content can read it, and takes counts, a box and the find shortcut back
31
+ as the content's word (§6, §7 "Find in page"); no wall moves. 0.14.10: P132 adds a mark's place in
32
+ the document and the document's scroll to annotation reports, unclamped, so a host must clip what it
33
+ draws from them to its own region (§6, §7); `rect` stays clamped and no wall moves.
29
34
 
30
35
  ## 1. Two layers
31
36
 
@@ -190,7 +195,13 @@ Whatever the use:
190
195
  framed as it is: upgrade the server/Worker first, resolve clean addresses through issue, P125):
191
196
  log them, show nothing for them. A url-mode app can still say any outcome (S6).
192
197
  - Take what the frame reports about annotations as UI hints (where to draw, what to open), never
193
- as permissions, and put nothing in a mark the page may not know (§7).
198
+ as permissions, and put nothing in a mark the page may not know (§7). A mark's place in the
199
+ document (`documentRect`, with the report's `scroll`, P132) isn't clamped to the frame: clip
200
+ whatever you draw from it to the frame's box, or to your own region beside the frame.
201
+ - Under `find` (P131), know that the page reads every query your find bar sends it, and declare
202
+ `find` only for displays whose pages may learn what the person searches for (not a third-party
203
+ app with egress, S5, unless you accept it). Take its counts as the bar's numbers, and open your
204
+ bar on `findRequested`, nothing more (§7 "Find in page").
194
205
  - Guard a view that a frame's report opens or moves (`activated`, `anchored`, `selected`,
195
206
  `tracked`: a comment's bubble, a composer, a card that follows its mark, which the page moves
196
207
  at will, up to 60 times a second). The content chooses when it appears and where, so it can bring it
@@ -692,7 +703,8 @@ fallback (a sign-in prompt with a link out): that is the door's wall (P125).
692
703
 
693
704
  What it is: the presets, the isolation, the egress walls, the shell, the bridge for the display's
694
705
  host functions (`sendPrompt`, `openLink`, `downloadFile`, `copyText`, `callTool`, `readData`,
695
- `subscribeData`, `setModelContext`, `reportError`, annotations) and the generated manual.
706
+ `subscribeData`, `setModelContext`, `reportError`, annotations, find in page) and the generated
707
+ manual.
696
708
 
697
709
  **Porthole guarantees** the two lines of [§4](#4-two-lines-of-defense) for each display except url
698
710
  mode (S6), with S1–S5's open items: isolation, closed egress, the gates. One config generates the
@@ -805,6 +817,14 @@ own frame, below the shell, P111), so:
805
817
  no size, or throws, clamps every box to nothing at the frame's corner (P105). The frame's size is
806
818
  read for every report the host takes, before the report's rate: a forced layout of the host's
807
819
  page per message, which a repeated `ui/initialize` already causes (accepted, P105).
820
+ A newer shell also says where each mark is in the document (`documentRect` in `anchored` and
821
+ `tracked`, with the document's `scroll`, P132), so a host can place a mark scrolled out of the
822
+ frame. Porthole checks those numbers (finite, within `ANNOTATION_LIMITS.coordinate`, sizes not
823
+ negative; a malformed one drops the report) but doesn't clamp them, since a clamp would erase
824
+ what they are for: a host that maps a `documentRect` onto its own page without clipping to the
825
+ frame's box (or to its own region beside it) lets the page choose where that UI goes, outside
826
+ the frame as well (accepted, P132; the host's duty in §6). They say nothing else: the page knows
827
+ where its words are anyway.
808
828
  - *What holds, against content that patches none of the DOM's or JavaScript's built-ins.* A real
809
829
  press or click on a marker reaches none of the content's handlers (the shell's first listener
810
830
  stops it; control `marker-click`) and moves neither focus nor a selection (control
@@ -855,6 +875,42 @@ own frame, below the shell, P111), so:
855
875
  resolve, delete or reply); an anchor or a rect decides where something is drawn, never who may
856
876
  see or do anything.
857
877
 
878
+ **Find in page** (`find`, P131). The host draws its own find bar; the shell finds the query in the
879
+ content's text (annotations' text index) and highlights the matches in a layer of its own (a closed
880
+ shadow root, as annotations' marks; never the CSS Custom Highlight API, which is the content's to
881
+ read and rewrite). It shares its realm with the content, so:
882
+
883
+ - *What content learns.* The query (`porthole/find.query`, posted into the frame's window), each
884
+ time the host sends it (a bar that searches as the person types sends their typing, key by key),
885
+ whether it is case-sensitive, each move to the next or previous match, when the bar clears, and
886
+ whether the host draws its own bar (`porthole/find.handled`). The query is the person's words,
887
+ typed in the host's own UI: a page with a way out (an MCP App's `connectDomains`, S5; egress a
888
+ host opened; a carrier such as `db`, `mayPassOn`) can send what the person searched for to its
889
+ author. That is why `find` is a capability a config declares, in no preset by default; accepted
890
+ by the product owner, with hosts sending queries on a pause or Enter rather than at every key
891
+ (P131). A query holds only for the content it was asked of: a new run or other content forgets
892
+ it, so another page is never searched with it (it would learn the words from what matched).
893
+ - *What content can say.* Any count and current match (bounded: at most 1,000, whole numbers, the
894
+ current one among them), any box inside its frame (clamped to the frame's viewport, as
895
+ annotations' boxes, P104), and an `updated` while a query is shown. The host takes an answer only
896
+ for a query it asked, under that query's id; anything malformed is `"unsupported"` or a refusal.
897
+ A find bar's numbers, never a fact about the content.
898
+ - *The shortcut.* While the host draws its own bar (`find.takeShortcut(true)`), the shell cancels
899
+ the browser's find on Cmd+F (Apple) or Ctrl+F (elsewhere) in the frame and says `requested`; a
900
+ page that handles the key itself keeps it. The page can say `requested` without the key, or keep
901
+ the key from the shell. The host takes it only while the platform says the page's focus is in
902
+ the frame (a press on it or a Tab put it there, P109; control `find-requested-focus`): a page
903
+ can't open the host's bar, which takes focus, while the person types in the host's composer, so
904
+ their next keys can't be steered into the bar and from there into the frame as queries. With the
905
+ person already in the frame the page has their keys anyway, and the bar moves the keyboard out of
906
+ it. Where a platform can't tell, it passes, as the gesture gate does. Open the bar, nothing more.
907
+ - *What content can always do.* Hide, cover or move the layer, change its words so the count
908
+ changes, reach the layer through built-ins it patched (as annotations' layer, P105), or make the
909
+ search dear: linear in its text, at most 1,000 matches kept and 10,000 looked at, a query of 256
910
+ characters, found again at most once a second while the content changes, and of a burst of
911
+ queries only the latest searched (the others answered superseded); in an opaque frame that
912
+ shares the host's process that time is the host's too ([§5](#5-out-of-scope)).
913
+
858
914
  **The keyboard** (P109). Any display, of any kind and any version, can move the keyboard into its
859
915
  frame: `element.focus()` runs in the content's realm, where nothing of Porthole can stop it, and on
860
916
  Chromium and WebKit it needs no gesture. What the person goes on typing then goes to the page,
@@ -86,6 +86,23 @@ not recursion). A shadow root it finds is also watched by the observer.
86
86
  A drop or paste of formatted content into an editable region goes in as plain text. A text field
87
87
  (`<input>`, `<textarea>`) takes text only and is unaffected.
88
88
 
89
+ ## The shell's own layers
90
+
91
+ Find in page (P131), where a config declares `find`, draws its highlights in a layer of the
92
+ shell's own: an element over the content holding a closed shadow root. It adds no entry point. It
93
+ is spliced into the runtime after step 3, takes the methods below then (the guarded ones), and
94
+ calls each through `callOf` (P129), so its nodes go in the way any node does:
95
+
96
+ - `createElement` for the layer, its style element and each highlight box (A21);
97
+ - `attachShadow` for the layer's closed root (A19);
98
+ - `appendChild` of the layer into the document element (A1);
99
+ - `replaceChildren` on the shadow root and on the element holding the boxes (A2);
100
+ - the `textContent` setter for its style sheet's text (A5).
101
+
102
+ It inserts nothing into the content's own trees: no element wraps or splits the content's text, and
103
+ the matches are ranges, read for their boxes only. Its inline styles are set through CSSOM
104
+ (`cssText`), and it doesn't use the CSS Custom Highlight API.
105
+
89
106
  ## Under `nestedFrames: "own"`
90
107
 
91
108
  The configuration that keeps a page's own iframes (P128) keeps creation open: an `iframe` can be
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.14.8",
3
+ "version": "0.14.10",
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": {
@@ -52,7 +52,8 @@ export interface AnnotationAnchor {
52
52
  * The page's word: the host clamps each it reports to the frame's viewport (P104), so one wholly
53
53
  * outside is a box of no size on the nearest edge. A positioning hint only. It is in the frame's
54
54
  * own layout px: a host that scales or transforms the frame maps it through that transform too
55
- * (P105).
55
+ * (P105). A result's `documentRect` (P132) is the same shape in the document's coordinates, and
56
+ * isn't clamped.
56
57
  */
57
58
  export interface AnnotationRect {
58
59
  readonly x: number;
@@ -61,6 +62,17 @@ export interface AnnotationRect {
61
62
  readonly height: number;
62
63
  }
63
64
 
65
+ /**
66
+ * How far the frame's document is scrolled when the boxes beside it were read (P132), CSS px: the
67
+ * top left of the document's root element (`<html>`), from the viewport's, negated (`window.scrollX`
68
+ * and `window.scrollY` on a page whose root has no margin). A box in the viewport is its
69
+ * `documentRect` less this. The page's word, as every box is.
70
+ */
71
+ export interface AnnotationScroll {
72
+ readonly x: number;
73
+ readonly y: number;
74
+ }
75
+
64
76
  /** What the person may point at while the host is asking. */
65
77
  export interface AnnotateMode {
66
78
  /**
@@ -112,6 +124,14 @@ export interface AnchorResult {
112
124
  readonly state: AnchorState;
113
125
  /** Where it is now, when attached. */
114
126
  readonly rect?: AnnotationRect;
127
+ /**
128
+ * Where it is in the document (P132): `rect` as the shell read it, before the host clamped it,
129
+ * plus the report's `scroll`; so it stays where it is as the document scrolls, and says where a
130
+ * mark scrolled out of the frame is. Not clamped to the frame's viewport (an offscreen mark's is
131
+ * outside it: that is its point): a host places its own UI from it only clipped to the frame's
132
+ * box, or to its own region beside the frame. Absent from an older shell. The page's word.
133
+ */
134
+ readonly documentRect?: AnnotationRect;
115
135
  /**
116
136
  * Its place in the document among the found marks, from 0 (P112): where it starts, offscreen
117
137
  * marks included, for a host that lists marks in reading order. The content's word: an order to
@@ -143,13 +163,32 @@ export type AnnotationReport =
143
163
  * scroll, a resize or a change of the content has settled, only the marks that moved since the
144
164
  * host was last told, at most once a second (P104).
145
165
  */
146
- | { readonly type: "anchored"; readonly results: readonly AnchorResult[] }
166
+ | {
167
+ readonly type: "anchored";
168
+ readonly results: readonly AnchorResult[];
169
+ /**
170
+ * How far the document was scrolled as the boxes were read (P132); with it, each attached
171
+ * result has its `documentRect`. Absent from an older shell: its results have no
172
+ * `documentRect` either, and only `rect` says where marks are.
173
+ */
174
+ readonly scroll?: AnnotationScroll;
175
+ }
147
176
  /**
148
177
  * The box of the mark the host follows (`annotations.track`, P112), in the frame's viewport, at
149
178
  * an animation frame where it moved: at most 60 a second, for that mark only, clamped to the
150
- * frame. The content's word: where to put a card beside it, nothing more.
179
+ * frame. The content's word: where to put a card beside it, nothing more. A newer shell (P132)
180
+ * adds the mark's `documentRect` and the document's `scroll`: the mark's box moves as the
181
+ * document scrolls, so a host following one mark hears the scroll at every animation frame where
182
+ * it changed, whether that mark is in the frame or not, and places every mark it holds a
183
+ * `documentRect` for (an `anchored` report's) without asking again.
151
184
  */
152
- | { readonly type: "tracked"; readonly id: string; readonly rect: AnnotationRect }
185
+ | {
186
+ readonly type: "tracked";
187
+ readonly id: string;
188
+ readonly rect: AnnotationRect;
189
+ readonly documentRect?: AnnotationRect;
190
+ readonly scroll?: AnnotationScroll;
191
+ }
153
192
  /**
154
193
  * The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
155
194
  * (P107); `rect` is the marker's box, to open the host's own UI beside it. The content can fake
@@ -6,6 +6,7 @@ import {
6
6
  type AnnotationMark,
7
7
  type AnnotationRect,
8
8
  type AnnotationReport,
9
+ type AnnotationScroll,
9
10
  type AnnotationSelector,
10
11
  } from "./types.ts";
11
12
  import { withoutUnseen } from "../bridge/unseen.ts";
@@ -112,6 +113,17 @@ export function parseRect(value: unknown): AnnotationRect | null {
112
113
  return { x, y, width, height };
113
114
  }
114
115
 
116
+ /**
117
+ * How far the document is scrolled (P132): two finite numbers within the coordinate limit (either
118
+ * may be negative: an engine's overscroll); null for anything else.
119
+ */
120
+ export function parseScroll(value: unknown): AnnotationScroll | null {
121
+ if (!isRecord(value) || !coordinate(value.x) || !coordinate(value.y)) {
122
+ return null;
123
+ }
124
+ return { x: value.x, y: value.y };
125
+ }
126
+
115
127
  /**
116
128
  * A box the frame reported, clamped to the frame's viewport (`width` by `height`, CSS px, P104):
117
129
  * each side is held within it, so what overlaps the viewport keeps the part inside, and what lies
@@ -152,7 +164,9 @@ function results(value: unknown): AnchorResult[] | null {
152
164
  return null;
153
165
  }
154
166
  const rect = each.rect === undefined ? undefined : parseRect(each.rect);
155
- if (rect === null) {
167
+ // Where it is in the document (P132): a box as `rect` is, never clamped.
168
+ const documentRect = each.documentRect === undefined ? undefined : parseRect(each.documentRect);
169
+ if (rect === null || documentRect === null) {
156
170
  return null;
157
171
  }
158
172
  // A place among the marks (P112): a whole number below the most marks a show carries.
@@ -167,6 +181,7 @@ function results(value: unknown): AnchorResult[] | null {
167
181
  id: each.id,
168
182
  state: "attached",
169
183
  ...(rect === undefined ? {} : { rect }),
184
+ ...(documentRect === undefined ? {} : { documentRect }),
170
185
  ...(order === undefined ? {} : { order }),
171
186
  });
172
187
  }
@@ -190,7 +205,10 @@ export function parseReport(value: unknown): AnnotationReport | null {
190
205
  return { type: "cancelled" };
191
206
  case "anchored": {
192
207
  const checked = results(value.results);
193
- return checked === null ? null : { type: "anchored", results: checked };
208
+ const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
209
+ return checked === null || scroll === null
210
+ ? null
211
+ : { type: "anchored", results: checked, ...(scroll === undefined ? {} : { scroll }) };
194
212
  }
195
213
  case "activated": {
196
214
  const rect = parseRect(value.rect);
@@ -198,7 +216,20 @@ export function parseReport(value: unknown): AnnotationReport | null {
198
216
  }
199
217
  case "tracked": {
200
218
  const rect = parseRect(value.rect);
201
- return !markId(value.id) || rect === null ? null : { type: "tracked", id: value.id, rect };
219
+ // A newer shell's (P132): where the mark is in the document, and how far it is scrolled.
220
+ const documentRect =
221
+ value.documentRect === undefined ? undefined : parseRect(value.documentRect);
222
+ const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
223
+ if (!markId(value.id) || rect === null || documentRect === null || scroll === null) {
224
+ return null;
225
+ }
226
+ return {
227
+ type: "tracked",
228
+ id: value.id,
229
+ rect,
230
+ ...(documentRect === undefined ? {} : { documentRect }),
231
+ ...(scroll === undefined ? {} : { scroll }),
232
+ };
202
233
  }
203
234
  default:
204
235
  return null;
@@ -8,6 +8,8 @@ import {
8
8
  } from "../config/capabilities.ts";
9
9
  import type { AnnotationReport } from "../annotate/types.ts";
10
10
  import { parseReport } from "../annotate/validate.ts";
11
+ import type { FindReport } from "../find/types.ts";
12
+ import { parseFindReport } from "../find/validate.ts";
11
13
  import type { PortholeConfig } from "../config/schema.ts";
12
14
  import { callGates, effectiveGates } from "../compile/policy.ts";
13
15
  import { boundedText } from "./bounded-text.ts";
@@ -84,6 +86,8 @@ export type BridgeEvent =
84
86
  /** The shell cancelled a navigation of the frame to `url` (P080): the content's word. */
85
87
  | { readonly type: "navigationBlocked"; readonly url: string }
86
88
  | { readonly type: "annotation"; readonly report: AnnotationReport }
89
+ /** What the frame said of find in page unasked (P131), checked. */
90
+ | { readonly type: "find"; readonly report: FindReport }
87
91
  | { readonly type: "refused"; readonly capability: CapabilityName; readonly refusal: Refusal }
88
92
  | { readonly type: "muted" };
89
93
 
@@ -319,6 +323,7 @@ const VALIDATORS: { readonly [N in CapabilityName]: Validator<N> } = {
319
323
  : null;
320
324
  },
321
325
  annotate: (args) => parseReport(args),
326
+ find: (args) => parseFindReport(args),
322
327
  // The runtime's own (P088-P090): their shapes and limits, before any gate.
323
328
  user: (args) => (args === undefined || isRecord(args) ? {} : null),
324
329
  comments: (args) => parseCommentRequest(args),
@@ -819,6 +824,8 @@ export function createBridge(options: BridgeOptions): DisplayBridge {
819
824
  onEvent({ type: "resize", ...size });
820
825
  } else if (capability === "annotate") {
821
826
  onEvent({ type: "annotation", report: args as CapabilityArgs["annotate"] });
827
+ } else if (capability === "find") {
828
+ onEvent({ type: "find", report: args as CapabilityArgs["find"] });
822
829
  } else {
823
830
  const report = args as CapabilityArgs["reportError"];
824
831
  if (report.navigationBlocked !== undefined) {
@@ -1,4 +1,5 @@
1
1
  import type { AnnotationReport } from "../annotate/types.ts";
2
+ import type { FindReport } from "../find/types.ts";
2
3
  import type { DbRequest, DbResult } from "../runtime/db.ts";
3
4
  import type {
4
5
  ArtifactInfo,
@@ -32,6 +33,7 @@ export const CAPABILITY_NAMES = [
32
33
  "resize",
33
34
  "copyText",
34
35
  "annotate",
36
+ "find",
35
37
  // The capability runtime's own (P085, `config.runtime`): reached through `porthole.use`.
36
38
  "user",
37
39
  "comments",
@@ -84,7 +86,7 @@ export interface CapabilitySpec {
84
86
  /**
85
87
  * How content reaches it without the shell's global: the MCP Apps request (or Porthole's own,
86
88
  * `porthole/…`, where the standard has none), and the official App SDK's method for it, if any.
87
- * Absent for what the shell does by itself (sizes, errors, annotations).
89
+ * Absent for what the shell does by itself (sizes, errors, annotations, find).
88
90
  */
89
91
  readonly request?: { readonly method: string; readonly sdk?: string };
90
92
  /**
@@ -175,6 +177,13 @@ export const CAPABILITIES = {
175
177
  * (it shares the realm): UI hints for the host, never permissions.
176
178
  */
177
179
  annotate: { defaultGates: [rate(120)], served: "event" },
180
+ /**
181
+ * Find in page (P131): the host's find bar asks the shell to find the person's words in the
182
+ * content and highlight them; the shell answers how many and which is current, and says when
183
+ * the person pressed the find shortcut in the frame. The query goes into the content's realm,
184
+ * which can read it; what the frame says back is the content's word: a find bar's numbers.
185
+ */
186
+ find: { defaultGates: [rate(120)], served: "event" },
178
187
  /** Who is viewing (P087): answered from the viewer the host gave the display. */
179
188
  user: { defaultGates: [rate(60)], served: "viewer", request: { method: "porthole/call" } },
180
189
  /** Opens the host's comment composer at the page's anchor (P090): write-only. */
@@ -221,6 +230,8 @@ export interface CapabilityArgs {
221
230
  readonly copyText: { readonly text: string };
222
231
  /** What the frame reported, once checked (`AnnotationReport`). */
223
232
  readonly annotate: AnnotationReport;
233
+ /** What the frame said unasked, once checked (`FindReport`): the shortcut, a changed count. */
234
+ readonly find: FindReport;
224
235
  readonly user: Readonly<Record<string, never>>;
225
236
  readonly comments: CommentRequest;
226
237
  readonly artifact: ArtifactRequest;
@@ -247,6 +258,7 @@ export interface CapabilityResults {
247
258
  /** Whether the text was copied. */
248
259
  readonly copyText: boolean;
249
260
  readonly annotate: undefined;
261
+ readonly find: undefined;
250
262
  readonly user: UserInfo;
251
263
  /** Whether the composer opened. Never a thread: content doesn't read comments (P090). */
252
264
  readonly comments: boolean;
@@ -0,0 +1,86 @@
1
+ import type { AnnotationRect } from "../annotate/types.ts";
2
+
3
+ /**
4
+ * Find in page (P131): the host draws its own find bar (a query box, previous and next, "3/12")
5
+ * and the shell finds the query in the content's text and highlights it, the current match apart,
6
+ * in a layer of its own. The host drives it with Porthole's own messages (`porthole/find.*`); the
7
+ * shell answers how many matches there are and which is current.
8
+ *
9
+ * Everything the frame says is the content's word: the shell shares its realm with the content,
10
+ * which can read the query, change the count or hide the highlights. Use what it says for the
11
+ * find bar (a count, where the current match is), never as a fact about the content.
12
+ */
13
+
14
+ /** Which match becomes the current one: the next, the previous, or the same (a new query: the first in view). */
15
+ export type FindDirection = "next" | "prev" | "none";
16
+
17
+ export interface FindOptions {
18
+ /** Default `"none"`: a new query's first match at or after where the person is reading. */
19
+ readonly direction?: FindDirection;
20
+ /** Default false: case-insensitive, as a browser's own find is. */
21
+ readonly caseSensitive?: boolean;
22
+ }
23
+
24
+ /**
25
+ * Where the matches stand. The content's word: a count for the find bar, nothing more.
26
+ */
27
+ export interface FindResult {
28
+ /** How many matches, at most `FIND_LIMITS.matches`. */
29
+ readonly total: number;
30
+ /** The current match, from 1; 0 when there is none. */
31
+ readonly active: number;
32
+ /** There may be more than `total`: the shell stopped at `FIND_LIMITS.matches` ("1000+"). */
33
+ readonly capped?: true;
34
+ /**
35
+ * The current match's box in the frame's viewport, once it was scrolled into view, clamped to
36
+ * the frame's viewport as an annotation's box is (P104): for a host whose frame doesn't scroll
37
+ * itself (a display that grows with its content) to scroll its own page to it. A hint only.
38
+ */
39
+ readonly rect?: AnnotationRect;
40
+ }
41
+
42
+ /** What the frame says unasked, once the host has checked it. */
43
+ export type FindReport =
44
+ /**
45
+ * The person pressed Cmd+F (Apple) or Ctrl+F (elsewhere) with the keyboard in the frame, and the
46
+ * page didn't take the key itself. Sent only while the host takes the shortcut
47
+ * (`find.takeShortcut(true)`), which also stops the browser's own find. The page's word too: it
48
+ * can send it, or keep the key from the shell. Open the host's find bar, nothing more.
49
+ */
50
+ | { readonly type: "requested" }
51
+ /**
52
+ * The matches changed while a query is shown, without the host asking: the content changed
53
+ * (more of it, or the page's own changes). At most once a second.
54
+ */
55
+ | ({ readonly type: "updated" } & FindResult);
56
+
57
+ /** Porthole's own messages for find in page (own-prefixed, P002). */
58
+ export const FIND_METHODS = {
59
+ /**
60
+ * Host → frame, a request: `{ query, direction?, caseSensitive? }`, answered with a
61
+ * `FindResult`. An empty query (or only spaces) clears, and answers no matches. One that a later
62
+ * query or a clear superseded before the shell ran it is answered with an error (code -32800,
63
+ * "superseded by a later query"; the host's `"unsupported"`): only the latest is searched.
64
+ */
65
+ query: "porthole/find.query",
66
+ /** Host → frame: remove the highlights and forget the query. */
67
+ clear: "porthole/find.clear",
68
+ /**
69
+ * Host → frame: `{ handled: boolean }`, whether the host draws its own find bar: while it does,
70
+ * the shell stops the browser's own find on Cmd+F or Ctrl+F in the frame and says `requested`.
71
+ */
72
+ handled: "porthole/find.handled",
73
+ /** Frame → host. */
74
+ requested: "porthole/find.requested",
75
+ updated: "porthole/find.updated",
76
+ } as const;
77
+
78
+ /** The most of each part of a query or an answer. */
79
+ export const FIND_LIMITS = {
80
+ /** The longest query, in UTF-16 code units. */
81
+ query: 256,
82
+ /** The most matches the shell finds and highlights; past it the answer says `capped`. */
83
+ matches: 1_000,
84
+ /** How long the host waits for an answer before it calls the display's find unsupported, ms. */
85
+ timeoutMs: 3_000,
86
+ } as const;