@botiverse/porthole 0.14.8 → 0.14.9
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 +27 -0
- 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 +214 -0
- package/dist/host/pass-on.js +3 -2
- package/dist/host/types.d.ts +51 -0
- package/dist/index.d.ts +3 -1
- package/dist/index.js +3 -0
- package/dist/react/frame.d.ts +43 -0
- 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.js +2 -95
- 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 +83 -0
- package/docs/ARCHITECTURE.md +10 -3
- package/docs/DECISIONS.md +219 -1
- package/docs/DESIGN.md +33 -0
- package/docs/THREAT_MODEL.md +48 -4
- package/docs/insertion-entry-points.md +17 -0
- package/package.json +1 -1
- 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 +230 -0
- package/src/host/pass-on.ts +3 -2
- package/src/host/types.ts +52 -0
- package/src/index.ts +12 -0
- package/src/react/frame.tsx +160 -1
- package/src/react/view.tsx +3 -0
- package/src/runtime/contract.ts +1 -1
- package/src/shell/annotate.ts +3 -95
- 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/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.9 (2026-11-04). 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,13 @@ 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.
|
|
29
32
|
|
|
30
33
|
## 1. Two layers
|
|
31
34
|
|
|
@@ -191,6 +194,10 @@ Whatever the use:
|
|
|
191
194
|
log them, show nothing for them. A url-mode app can still say any outcome (S6).
|
|
192
195
|
- Take what the frame reports about annotations as UI hints (where to draw, what to open), never
|
|
193
196
|
as permissions, and put nothing in a mark the page may not know (§7).
|
|
197
|
+
- Under `find` (P131), know that the page reads every query your find bar sends it, and declare
|
|
198
|
+
`find` only for displays whose pages may learn what the person searches for (not a third-party
|
|
199
|
+
app with egress, S5, unless you accept it). Take its counts as the bar's numbers, and open your
|
|
200
|
+
bar on `findRequested`, nothing more (§7 "Find in page").
|
|
194
201
|
- Guard a view that a frame's report opens or moves (`activated`, `anchored`, `selected`,
|
|
195
202
|
`tracked`: a comment's bubble, a composer, a card that follows its mark, which the page moves
|
|
196
203
|
at will, up to 60 times a second). The content chooses when it appears and where, so it can bring it
|
|
@@ -692,7 +699,8 @@ fallback (a sign-in prompt with a link out): that is the door's wall (P125).
|
|
|
692
699
|
|
|
693
700
|
What it is: the presets, the isolation, the egress walls, the shell, the bridge for the display's
|
|
694
701
|
host functions (`sendPrompt`, `openLink`, `downloadFile`, `copyText`, `callTool`, `readData`,
|
|
695
|
-
`subscribeData`, `setModelContext`, `reportError`, annotations) and the generated
|
|
702
|
+
`subscribeData`, `setModelContext`, `reportError`, annotations, find in page) and the generated
|
|
703
|
+
manual.
|
|
696
704
|
|
|
697
705
|
**Porthole guarantees** the two lines of [§4](#4-two-lines-of-defense) for each display except url
|
|
698
706
|
mode (S6), with S1–S5's open items: isolation, closed egress, the gates. One config generates the
|
|
@@ -855,6 +863,42 @@ own frame, below the shell, P111), so:
|
|
|
855
863
|
resolve, delete or reply); an anchor or a rect decides where something is drawn, never who may
|
|
856
864
|
see or do anything.
|
|
857
865
|
|
|
866
|
+
**Find in page** (`find`, P131). The host draws its own find bar; the shell finds the query in the
|
|
867
|
+
content's text (annotations' text index) and highlights the matches in a layer of its own (a closed
|
|
868
|
+
shadow root, as annotations' marks; never the CSS Custom Highlight API, which is the content's to
|
|
869
|
+
read and rewrite). It shares its realm with the content, so:
|
|
870
|
+
|
|
871
|
+
- *What content learns.* The query (`porthole/find.query`, posted into the frame's window), each
|
|
872
|
+
time the host sends it (a bar that searches as the person types sends their typing, key by key),
|
|
873
|
+
whether it is case-sensitive, each move to the next or previous match, when the bar clears, and
|
|
874
|
+
whether the host draws its own bar (`porthole/find.handled`). The query is the person's words,
|
|
875
|
+
typed in the host's own UI: a page with a way out (an MCP App's `connectDomains`, S5; egress a
|
|
876
|
+
host opened; a carrier such as `db`, `mayPassOn`) can send what the person searched for to its
|
|
877
|
+
author. That is why `find` is a capability a config declares, in no preset by default; accepted
|
|
878
|
+
by the product owner, with hosts sending queries on a pause or Enter rather than at every key
|
|
879
|
+
(P131). A query holds only for the content it was asked of: a new run or other content forgets
|
|
880
|
+
it, so another page is never searched with it (it would learn the words from what matched).
|
|
881
|
+
- *What content can say.* Any count and current match (bounded: at most 1,000, whole numbers, the
|
|
882
|
+
current one among them), any box inside its frame (clamped to the frame's viewport, as
|
|
883
|
+
annotations' boxes, P104), and an `updated` while a query is shown. The host takes an answer only
|
|
884
|
+
for a query it asked, under that query's id; anything malformed is `"unsupported"` or a refusal.
|
|
885
|
+
A find bar's numbers, never a fact about the content.
|
|
886
|
+
- *The shortcut.* While the host draws its own bar (`find.takeShortcut(true)`), the shell cancels
|
|
887
|
+
the browser's find on Cmd+F (Apple) or Ctrl+F (elsewhere) in the frame and says `requested`; a
|
|
888
|
+
page that handles the key itself keeps it. The page can say `requested` without the key, or keep
|
|
889
|
+
the key from the shell. The host takes it only while the platform says the page's focus is in
|
|
890
|
+
the frame (a press on it or a Tab put it there, P109; control `find-requested-focus`): a page
|
|
891
|
+
can't open the host's bar, which takes focus, while the person types in the host's composer, so
|
|
892
|
+
their next keys can't be steered into the bar and from there into the frame as queries. With the
|
|
893
|
+
person already in the frame the page has their keys anyway, and the bar moves the keyboard out of
|
|
894
|
+
it. Where a platform can't tell, it passes, as the gesture gate does. Open the bar, nothing more.
|
|
895
|
+
- *What content can always do.* Hide, cover or move the layer, change its words so the count
|
|
896
|
+
changes, reach the layer through built-ins it patched (as annotations' layer, P105), or make the
|
|
897
|
+
search dear: linear in its text, at most 1,000 matches kept and 10,000 looked at, a query of 256
|
|
898
|
+
characters, found again at most once a second while the content changes, and of a burst of
|
|
899
|
+
queries only the latest searched (the others answered superseded); in an opaque frame that
|
|
900
|
+
shares the host's process that time is the host's too ([§5](#5-out-of-scope)).
|
|
901
|
+
|
|
858
902
|
**The keyboard** (P109). Any display, of any kind and any version, can move the keyboard into its
|
|
859
903
|
frame: `element.focus()` runs in the content's realm, where nothing of Porthole can stop it, and on
|
|
860
904
|
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.9",
|
|
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/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;
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
import { parseRect } from "../annotate/validate.ts";
|
|
2
|
+
import {
|
|
3
|
+
FIND_LIMITS as LIMITS,
|
|
4
|
+
type FindDirection,
|
|
5
|
+
type FindOptions,
|
|
6
|
+
type FindReport,
|
|
7
|
+
type FindResult,
|
|
8
|
+
} from "./types.ts";
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* The host's checks on find in page (P131): what it sends (a query and its options) and what a
|
|
12
|
+
* frame says back. A frame's word is rebuilt from known fields only, within `FIND_LIMITS`, and is
|
|
13
|
+
* null for anything else: dropped whole, never repaired.
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
const isRecord = (value: unknown): value is Record<string, unknown> =>
|
|
17
|
+
value !== null && typeof value === "object" && !Array.isArray(value);
|
|
18
|
+
|
|
19
|
+
const whole = (value: unknown, max: number): value is number =>
|
|
20
|
+
typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= max;
|
|
21
|
+
|
|
22
|
+
/** An answer to `porthole/find.query`, or an `updated`'s numbers; null if malformed. */
|
|
23
|
+
export function parseFindResult(value: unknown): FindResult | null {
|
|
24
|
+
if (!isRecord(value)) {
|
|
25
|
+
return null;
|
|
26
|
+
}
|
|
27
|
+
const { total, active, capped, rect } = value;
|
|
28
|
+
if (!whole(total, LIMITS.matches) || !whole(active, total)) {
|
|
29
|
+
return null;
|
|
30
|
+
}
|
|
31
|
+
if ((total === 0) !== (active === 0)) {
|
|
32
|
+
return null;
|
|
33
|
+
}
|
|
34
|
+
if (capped !== undefined && capped !== true && capped !== false) {
|
|
35
|
+
return null;
|
|
36
|
+
}
|
|
37
|
+
// Capped only at the limit: fewer matches were all of them.
|
|
38
|
+
if (capped === true && total !== LIMITS.matches) {
|
|
39
|
+
return null;
|
|
40
|
+
}
|
|
41
|
+
const box = rect === undefined || active === 0 ? undefined : parseRect(rect);
|
|
42
|
+
if (box === null) {
|
|
43
|
+
return null;
|
|
44
|
+
}
|
|
45
|
+
return {
|
|
46
|
+
total,
|
|
47
|
+
active,
|
|
48
|
+
...(capped === true ? { capped: true as const } : {}),
|
|
49
|
+
...(box === undefined ? {} : { rect: box }),
|
|
50
|
+
};
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/** A report from the frame, checked; null if malformed (it is then dropped). */
|
|
54
|
+
export function parseFindReport(value: unknown): FindReport | null {
|
|
55
|
+
if (!isRecord(value)) {
|
|
56
|
+
return null;
|
|
57
|
+
}
|
|
58
|
+
switch (value.type) {
|
|
59
|
+
case "requested":
|
|
60
|
+
return { type: "requested" };
|
|
61
|
+
case "updated": {
|
|
62
|
+
// No box: where the current match is goes only with an answer to the host's own query.
|
|
63
|
+
const { rect: _rect, ...numbers } = value;
|
|
64
|
+
const result = parseFindResult(numbers);
|
|
65
|
+
return result === null ? null : { type: "updated", ...result };
|
|
66
|
+
}
|
|
67
|
+
default:
|
|
68
|
+
return null;
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
const DIRECTIONS: readonly FindDirection[] = ["next", "prev", "none"];
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* A query and its options as the host gives them, checked before they go to the frame; throws a
|
|
76
|
+
* `TypeError` for a query that isn't text, is longer than `FIND_LIMITS.query`, or options that
|
|
77
|
+
* aren't these. The query goes as it is (the shell trims it and loosens its spacing).
|
|
78
|
+
*/
|
|
79
|
+
export function checkFindQuery(
|
|
80
|
+
query: unknown,
|
|
81
|
+
options: FindOptions | undefined,
|
|
82
|
+
): { query: string; direction: FindDirection; caseSensitive: boolean } {
|
|
83
|
+
if (typeof query !== "string" || query.length > LIMITS.query) {
|
|
84
|
+
throw new TypeError(`find.query: the query is text, at most ${LIMITS.query} characters`);
|
|
85
|
+
}
|
|
86
|
+
if (options !== undefined && !isRecord(options)) {
|
|
87
|
+
throw new TypeError("find.query: options are { direction?, caseSensitive? }");
|
|
88
|
+
}
|
|
89
|
+
const direction: unknown = options?.direction ?? "none";
|
|
90
|
+
if (!(DIRECTIONS as readonly unknown[]).includes(direction)) {
|
|
91
|
+
throw new TypeError('find.query: direction is "next", "prev" or "none"');
|
|
92
|
+
}
|
|
93
|
+
const caseSensitive: unknown = options?.caseSensitive ?? false;
|
|
94
|
+
if (typeof caseSensitive !== "boolean") {
|
|
95
|
+
throw new TypeError("find.query: caseSensitive is true or false");
|
|
96
|
+
}
|
|
97
|
+
return { query, direction: direction as FindDirection, caseSensitive };
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** Whether a query finds nothing by its words alone: empty, or only spaces (it clears). */
|
|
101
|
+
export const blankQuery = (query: string): boolean => query.trim() === "";
|
package/src/guide/guide.ts
CHANGED
|
@@ -444,6 +444,8 @@ const ENTRIES: { readonly [N in CapabilityName]: (c: Context, gates: readonly Ga
|
|
|
444
444
|
: `- Copying: the request porthole/copy-text with { text } (at most ${MAX_COPY_CHARS.toLocaleString("en-US")} characters) copies text to the person's clipboard, and the app shows them what was copied; nothing else in the ${c.noun} can write the clipboard. ${gateWords(gates, "the text")}`,
|
|
445
445
|
annotate: (c) =>
|
|
446
446
|
`- Comments: the person may point at parts of the ${c.noun} to comment on them. Give headings and the parts that matter stable ids (id="revenue"), so comments stay on them when the ${c.noun} is written again.`,
|
|
447
|
+
find: (c) =>
|
|
448
|
+
`- Find: the person may search the ${c.noun}'s words with the app's own find bar (Cmd+F or Ctrl+F), which highlights them where they are. Keep the words they would look for as text (not in images or a canvas). A ${c.noun} that handles Cmd+F or Ctrl+F itself (preventDefault) keeps the key.`,
|
|
447
449
|
reportError: (c) =>
|
|
448
450
|
`- ${manualLimits(c.config, "").find((limit) => limit.id === "errors")?.text ?? ""}`,
|
|
449
451
|
resize: () => "",
|
|
@@ -456,7 +458,7 @@ const ENTRIES: { readonly [N in CapabilityName]: (c: Context, gates: readonly Ga
|
|
|
456
458
|
};
|
|
457
459
|
|
|
458
460
|
/** The shell's own capabilities, which content never calls by name: taught as they are. */
|
|
459
|
-
const SHELL_OWN: readonly CapabilityName[] = ["annotate", "reportError", "resize"];
|
|
461
|
+
const SHELL_OWN: readonly CapabilityName[] = ["annotate", "find", "reportError", "resize"];
|
|
460
462
|
|
|
461
463
|
function interactive(c: Context): string {
|
|
462
464
|
const { config, noun } = c;
|