@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.
Files changed (54) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/dist/bridge/bridge.d.ts +6 -0
  3. package/dist/bridge/bridge.js +5 -0
  4. package/dist/check/page-source.js +1 -1
  5. package/dist/config/capabilities.d.ts +16 -2
  6. package/dist/config/capabilities.js +8 -0
  7. package/dist/conformance/harness-source.js +1 -1
  8. package/dist/find/types.d.ts +83 -0
  9. package/dist/find/types.js +29 -0
  10. package/dist/find/validate.d.ts +17 -0
  11. package/dist/find/validate.js +82 -0
  12. package/dist/guide/guide.js +2 -1
  13. package/dist/host/create-host.js +214 -0
  14. package/dist/host/pass-on.js +3 -2
  15. package/dist/host/types.d.ts +51 -0
  16. package/dist/index.d.ts +3 -1
  17. package/dist/index.js +3 -0
  18. package/dist/react/frame.d.ts +43 -0
  19. package/dist/react/frame.js +107 -3
  20. package/dist/react/view.js +2 -0
  21. package/dist/runtime/contract.d.ts +1 -1
  22. package/dist/runtime/contract.js +1 -1
  23. package/dist/shell/annotate.js +2 -95
  24. package/dist/shell/document.d.ts +3 -3
  25. package/dist/shell/document.js +5 -3
  26. package/dist/shell/find.d.ts +82 -0
  27. package/dist/shell/find.js +725 -0
  28. package/dist/shell/runtime.js +4 -1
  29. package/dist/shell/text.d.ts +17 -0
  30. package/dist/shell/text.js +140 -0
  31. package/docs/ADOPTING.md +83 -0
  32. package/docs/ARCHITECTURE.md +10 -3
  33. package/docs/DECISIONS.md +219 -1
  34. package/docs/DESIGN.md +33 -0
  35. package/docs/THREAT_MODEL.md +48 -4
  36. package/docs/insertion-entry-points.md +17 -0
  37. package/package.json +1 -1
  38. package/src/bridge/bridge.ts +7 -0
  39. package/src/config/capabilities.ts +13 -1
  40. package/src/find/types.ts +86 -0
  41. package/src/find/validate.ts +101 -0
  42. package/src/guide/guide.ts +3 -1
  43. package/src/host/create-host.ts +230 -0
  44. package/src/host/pass-on.ts +3 -2
  45. package/src/host/types.ts +52 -0
  46. package/src/index.ts +12 -0
  47. package/src/react/frame.tsx +160 -1
  48. package/src/react/view.tsx +3 -0
  49. package/src/runtime/contract.ts +1 -1
  50. package/src/shell/annotate.ts +3 -95
  51. package/src/shell/document.ts +5 -3
  52. package/src/shell/find.ts +731 -0
  53. package/src/shell/runtime.ts +4 -1
  54. package/src/shell/text.ts +140 -0
@@ -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.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). 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.
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 manual.
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.8",
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": {
@@ -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() === "";
@@ -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;