@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.
- package/CHANGELOG.md +46 -0
- package/dist/annotate/types.d.ts +33 -2
- package/dist/annotate/validate.d.ts +6 -1
- package/dist/annotate/validate.js +31 -3
- package/dist/bridge/bridge.d.ts +6 -0
- package/dist/bridge/bridge.js +5 -0
- package/dist/check/page-source.js +1 -1
- package/dist/config/capabilities.d.ts +16 -2
- package/dist/config/capabilities.js +8 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/find/types.d.ts +83 -0
- package/dist/find/types.js +29 -0
- package/dist/find/validate.d.ts +17 -0
- package/dist/find/validate.js +82 -0
- package/dist/guide/guide.js +2 -1
- package/dist/host/create-host.js +219 -3
- package/dist/host/pass-on.js +3 -2
- package/dist/host/types.d.ts +54 -1
- package/dist/index.d.ts +5 -3
- package/dist/index.js +4 -1
- package/dist/react/frame.d.ts +45 -1
- package/dist/react/frame.js +107 -3
- package/dist/react/view.js +2 -0
- package/dist/runtime/contract.d.ts +1 -1
- package/dist/runtime/contract.js +1 -1
- package/dist/shell/annotate.d.ts +5 -1
- package/dist/shell/annotate.js +41 -107
- package/dist/shell/document.d.ts +3 -3
- package/dist/shell/document.js +5 -3
- package/dist/shell/find.d.ts +82 -0
- package/dist/shell/find.js +725 -0
- package/dist/shell/runtime.js +4 -1
- package/dist/shell/text.d.ts +17 -0
- package/dist/shell/text.js +140 -0
- package/docs/ADOPTING.md +112 -0
- package/docs/ARCHITECTURE.md +10 -3
- package/docs/DECISIONS.md +284 -1
- package/docs/DESIGN.md +48 -2
- package/docs/THREAT_MODEL.md +61 -5
- package/docs/insertion-entry-points.md +17 -0
- package/package.json +1 -1
- package/src/annotate/types.ts +43 -4
- package/src/annotate/validate.ts +34 -3
- package/src/bridge/bridge.ts +7 -0
- package/src/config/capabilities.ts +13 -1
- package/src/find/types.ts +86 -0
- package/src/find/validate.ts +101 -0
- package/src/guide/guide.ts +3 -1
- package/src/host/create-host.ts +235 -3
- package/src/host/pass-on.ts +3 -2
- package/src/host/types.ts +55 -1
- package/src/index.ts +14 -1
- package/src/react/frame.tsx +162 -2
- package/src/react/view.tsx +3 -0
- package/src/runtime/contract.ts +1 -1
- package/src/shell/annotate.ts +42 -107
- package/src/shell/document.ts +5 -3
- package/src/shell/find.ts +731 -0
- package/src/shell/runtime.ts +4 -1
- 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
|
|
package/docs/THREAT_MODEL.md
CHANGED
|
@@ -5,7 +5,7 @@ What Porthole protects, from whom, and where that protection ends. For each way
|
|
|
5
5
|
guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
|
|
6
6
|
[DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
|
|
7
7
|
|
|
8
|
-
**Status.** This describes Porthole 0.14.
|
|
8
|
+
**Status.** This describes Porthole 0.14.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).
|
|
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
|
|
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.
|
|
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": {
|
package/src/annotate/types.ts
CHANGED
|
@@ -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
|
-
| {
|
|
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
|
-
| {
|
|
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
|
package/src/annotate/validate.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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;
|
package/src/bridge/bridge.ts
CHANGED
|
@@ -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;
|