@botiverse/porthole 0.14.7 → 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 (87) hide show
  1. package/CHANGELOG.md +74 -0
  2. package/dist/bridge/bridge.d.ts +6 -0
  3. package/dist/bridge/bridge.js +5 -0
  4. package/dist/check/files.js +2 -0
  5. package/dist/check/lint.js +82 -3
  6. package/dist/check/page-source.js +1 -1
  7. package/dist/compile/policy.d.ts +17 -6
  8. package/dist/compile/policy.js +22 -7
  9. package/dist/config/capabilities.d.ts +16 -2
  10. package/dist/config/capabilities.js +8 -0
  11. package/dist/config/schema.d.ts +13 -0
  12. package/dist/config/validate.js +15 -0
  13. package/dist/conformance/harness-source.js +1 -1
  14. package/dist/conformance/kit.d.ts +5 -0
  15. package/dist/conformance/kit.js +21 -0
  16. package/dist/conformance/limits.js +10 -5
  17. package/dist/conformance/probes.js +139 -28
  18. package/dist/conformance/served.js +25 -4
  19. package/dist/find/types.d.ts +83 -0
  20. package/dist/find/types.js +29 -0
  21. package/dist/find/validate.d.ts +17 -0
  22. package/dist/find/validate.js +82 -0
  23. package/dist/guide/guide.js +2 -1
  24. package/dist/guide/limits.js +8 -1
  25. package/dist/host/create-host.js +249 -4
  26. package/dist/host/pass-on.js +3 -2
  27. package/dist/host/types.d.ts +51 -0
  28. package/dist/index.d.ts +4 -2
  29. package/dist/index.js +4 -1
  30. package/dist/presets/presets.d.ts +6 -0
  31. package/dist/presets/presets.js +6 -0
  32. package/dist/react/frame.d.ts +43 -0
  33. package/dist/react/frame.js +107 -3
  34. package/dist/react/view.js +2 -0
  35. package/dist/runtime/contract.d.ts +1 -1
  36. package/dist/runtime/contract.js +1 -1
  37. package/dist/server/files.js +4 -3
  38. package/dist/server/server.js +4 -1
  39. package/dist/shell/annotate.js +2 -95
  40. package/dist/shell/document.d.ts +3 -3
  41. package/dist/shell/document.js +5 -3
  42. package/dist/shell/find.d.ts +82 -0
  43. package/dist/shell/find.js +725 -0
  44. package/dist/shell/plan.d.ts +5 -0
  45. package/dist/shell/plan.js +2 -0
  46. package/dist/shell/runtime.d.ts +30 -1
  47. package/dist/shell/runtime.js +789 -105
  48. package/dist/shell/text.d.ts +17 -0
  49. package/dist/shell/text.js +140 -0
  50. package/docs/ADOPTING.md +103 -0
  51. package/docs/ARCHITECTURE.md +10 -3
  52. package/docs/DECISIONS.md +513 -1
  53. package/docs/DESIGN.md +40 -4
  54. package/docs/THREAT_MODEL.md +75 -6
  55. package/docs/insertion-entry-points.md +112 -0
  56. package/package.json +1 -1
  57. package/src/bridge/bridge.ts +7 -0
  58. package/src/check/files.ts +2 -0
  59. package/src/check/lint.ts +97 -8
  60. package/src/compile/policy.ts +23 -6
  61. package/src/config/capabilities.ts +13 -1
  62. package/src/config/schema.ts +13 -0
  63. package/src/config/validate.ts +16 -0
  64. package/src/conformance/kit.ts +22 -0
  65. package/src/conformance/limits.ts +10 -5
  66. package/src/conformance/probes.ts +149 -28
  67. package/src/conformance/served.ts +24 -4
  68. package/src/find/types.ts +86 -0
  69. package/src/find/validate.ts +101 -0
  70. package/src/guide/guide.ts +3 -1
  71. package/src/guide/limits.ts +9 -1
  72. package/src/host/create-host.ts +267 -4
  73. package/src/host/pass-on.ts +3 -2
  74. package/src/host/types.ts +52 -0
  75. package/src/index.ts +13 -0
  76. package/src/presets/presets.ts +15 -0
  77. package/src/react/frame.tsx +160 -1
  78. package/src/react/view.tsx +3 -0
  79. package/src/runtime/contract.ts +1 -1
  80. package/src/server/files.ts +8 -2
  81. package/src/server/server.ts +4 -1
  82. package/src/shell/annotate.ts +3 -95
  83. package/src/shell/document.ts +5 -3
  84. package/src/shell/find.ts +731 -0
  85. package/src/shell/plan.ts +7 -0
  86. package/src/shell/runtime.ts +792 -105
  87. package/src/shell/text.ts +140 -0
@@ -11,6 +11,8 @@ import {
11
11
  hasMarker,
12
12
  parseReport,
13
13
  } from "../annotate/validate.ts";
14
+ import { FIND_LIMITS, FIND_METHODS, type FindReport, type FindResult } from "../find/types.ts";
15
+ import { blankQuery, checkFindQuery, parseFindReport, parseFindResult } from "../find/validate.ts";
14
16
  import {
15
17
  createBridge,
16
18
  onceConsent,
@@ -46,6 +48,7 @@ import { checkDeclaration } from "../runtime/declaration.ts";
46
48
  import { parseViewer } from "../runtime/levels.ts";
47
49
  import type {
48
50
  AnnotationControls,
51
+ FindControls,
49
52
  HostErrorKind,
50
53
  DisplayEvents,
51
54
  DisplayHandle,
@@ -88,6 +91,12 @@ const REPORTS: Readonly<Record<string, AnnotationReport["type"]>> = {
88
91
  [ANNOTATE_METHODS.tracked]: "tracked",
89
92
  };
90
93
 
94
+ /** What the frame says of find in page unasked (P131), by method. */
95
+ const FIND_REPORTS: Readonly<Record<string, FindReport["type"]>> = {
96
+ [FIND_METHODS.requested]: "requested",
97
+ [FIND_METHODS.updated]: "updated",
98
+ };
99
+
91
100
  /** The most `tracked` reports a second the host takes (P112): one per animation frame at 60 Hz. */
92
101
  export const TRACKED_PER_SECOND = 60;
93
102
 
@@ -228,6 +237,21 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
228
237
  // The mark the host follows (P112), and when it took each `tracked` in the last second.
229
238
  let tracking: string | null = null;
230
239
  const trackedTimes: number[] = [];
240
+ // Find in page (P131): the query shown (for the content it was asked of only: a new run or
241
+ // other content forgets it), whether the host takes the shortcut (kept for every frame the
242
+ // display runs), and the queries asked and not yet answered.
243
+ const finds = config.capabilities.find !== undefined;
244
+ let findShown: { readonly query: string; readonly caseSensitive: boolean } | null = null;
245
+ let takesShortcut = false;
246
+ let nextFind = 1;
247
+ const findsAsked = new Map<
248
+ string,
249
+ {
250
+ readonly params: Record<string, unknown>;
251
+ readonly resolve: (result: FindResult | "unsupported") => void;
252
+ timer: ReturnType<typeof setTimeout>;
253
+ }
254
+ >();
231
255
  let handshaken = false;
232
256
  let storageTold = false;
233
257
  const toFrame = (method: string, params: Record<string, unknown>) => {
@@ -235,6 +259,87 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
235
259
  surface.transport.send({ jsonrpc: "2.0", method, params });
236
260
  }
237
261
  };
262
+ /** A query asked of the frame running now (once it finished its handshake). */
263
+ const sendFind = (id: string, params: Record<string, unknown>) => {
264
+ if (handshaken && surface !== null) {
265
+ surface.transport.send({ jsonrpc: "2.0", id, method: FIND_METHODS.query, params });
266
+ }
267
+ };
268
+ /** Answers a query asked, once; a later answer for it is dropped. */
269
+ const settleFind = (id: string, result: FindResult | "unsupported") => {
270
+ const asked = findsAsked.get(id);
271
+ if (asked !== undefined) {
272
+ findsAsked.delete(id);
273
+ clearTimeout(asked.timer);
274
+ asked.resolve(result);
275
+ }
276
+ };
277
+ /**
278
+ * Asks the frame a query: at once where one finished its handshake, else when one does
279
+ * (its load's time and the answer's). No answer in time, an error (an older shell's "isn't
280
+ * offered here"), or one malformed: `"unsupported"`.
281
+ */
282
+ const askFind = (params: Record<string, unknown>): Promise<FindResult | "unsupported"> =>
283
+ new Promise((resolve) => {
284
+ const id = `porthole-find-${nextFind++}`;
285
+ const wait = handshaken ? FIND_LIMITS.timeoutMs : timeoutMs + FIND_LIMITS.timeoutMs;
286
+ findsAsked.set(id, {
287
+ params,
288
+ resolve,
289
+ timer: setTimeout(() => settleFind(id, "unsupported"), wait),
290
+ });
291
+ sendFind(id, params);
292
+ });
293
+ /**
294
+ * A new frame's find (after its handshake): the shortcut, and the latest of the queries
295
+ * asked while it loaded (those it superseded answered `"unsupported"`, never sent). A query
296
+ * cleared since it was asked is answered as nothing found, unasked. The query shown before
297
+ * this run is never given again: a run's frame may show other content (forgetFind).
298
+ */
299
+ const giveFind = () => {
300
+ if (!finds) {
301
+ return;
302
+ }
303
+ if (takesShortcut) {
304
+ toFrame(FIND_METHODS.handled, { handled: true });
305
+ }
306
+ if (findShown === null) {
307
+ for (const id of findsAsked.keys()) {
308
+ settleFind(id, { total: 0, active: 0 });
309
+ }
310
+ return;
311
+ }
312
+ const waiting = [...findsAsked];
313
+ for (const [id] of waiting.slice(0, -1)) {
314
+ settleFind(id, "unsupported");
315
+ }
316
+ const last = waiting.at(-1);
317
+ if (last !== undefined) {
318
+ const [id, asked] = last;
319
+ clearTimeout(asked.timer);
320
+ asked.timer = setTimeout(() => settleFind(id, "unsupported"), FIND_LIMITS.timeoutMs);
321
+ sendFind(id, asked.params);
322
+ }
323
+ };
324
+ /**
325
+ * The content the query was asked of is gone (P131): a new run (a reload, a restart after
326
+ * the content navigated away, a new location) or other content. The query is forgotten and
327
+ * what waits is answered `"unsupported"`, so a new page is never searched with the last
328
+ * one's query unless the host asks it again; `clearFrame` also clears the frame running now.
329
+ */
330
+ const forgetFind = (clearFrame: boolean) => {
331
+ if (!finds) {
332
+ return;
333
+ }
334
+ const had = findShown !== null || findsAsked.size > 0;
335
+ findShown = null;
336
+ for (const id of findsAsked.keys()) {
337
+ settleFind(id, "unsupported");
338
+ }
339
+ if (clearFrame && had) {
340
+ toFrame(FIND_METHODS.clear, {});
341
+ }
342
+ };
238
343
  const giveAnnotations = () => {
239
344
  if (marks.length > 0) {
240
345
  toFrame(ANNOTATE_METHODS.show, {
@@ -405,6 +510,98 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
405
510
  }
406
511
  void through.call("annotate", withinFrame(report));
407
512
  };
513
+ /**
514
+ * What the frame says of find (P131): an answer to a query asked (its own id only, checked,
515
+ * its box clamped to the frame), or a report unasked, taken only while the host asked for it
516
+ * (the shortcut while the host takes it and the page's focus is in the frame; a changed count
517
+ * while a query is shown), then through the bridge's gates.
518
+ */
519
+ const onFind = (
520
+ raw: unknown,
521
+ through: HostFunctionBridge,
522
+ focused: () => boolean | undefined,
523
+ ) => {
524
+ if (!isRecord(raw) || raw.jsonrpc !== "2.0") {
525
+ return;
526
+ }
527
+ if (typeof raw.method !== "string") {
528
+ // Its own entries only: an id the host never asked is no answer.
529
+ const id = raw.id;
530
+ if (typeof id !== "string" || !findsAsked.has(id)) {
531
+ return;
532
+ }
533
+ const result = "error" in raw || !("result" in raw) ? null : parseFindResult(raw.result);
534
+ settleFind(
535
+ id,
536
+ result === null
537
+ ? "unsupported"
538
+ : result.rect === undefined
539
+ ? result
540
+ : { ...result, rect: clampRect(result.rect, frameViewport()) },
541
+ );
542
+ return;
543
+ }
544
+ if ("id" in raw) {
545
+ return;
546
+ }
547
+ const type = Object.hasOwn(FIND_REPORTS, raw.method) ? FIND_REPORTS[raw.method] : undefined;
548
+ if (type === undefined) {
549
+ return;
550
+ }
551
+ const report = parseFindReport({ ...(isRecord(raw.params) ? raw.params : {}), type });
552
+ if (report === null) {
553
+ void through.call("find", null);
554
+ return;
555
+ }
556
+ if (report.type === "requested") {
557
+ // The person's key in the frame: the page's focus is there (where the platform can tell),
558
+ // so a page can't bring the host's find bar up while the person types beside it.
559
+ let inFrame: boolean | undefined;
560
+ try {
561
+ inFrame = focused();
562
+ } catch {
563
+ inFrame = false;
564
+ }
565
+ if (!takesShortcut || inFrame === false) {
566
+ return;
567
+ }
568
+ } else if (findShown === null) {
569
+ return;
570
+ }
571
+ void through.call("find", report);
572
+ };
573
+ const find: FindControls = {
574
+ query(query, given) {
575
+ if (!finds) {
576
+ return Promise.resolve("unsupported");
577
+ }
578
+ let checked: ReturnType<typeof checkFindQuery>;
579
+ try {
580
+ checked = checkFindQuery(query, given);
581
+ } catch (error) {
582
+ return Promise.reject(error);
583
+ }
584
+ if (blankQuery(checked.query)) {
585
+ findShown = null;
586
+ toFrame(FIND_METHODS.clear, {});
587
+ return Promise.resolve({ total: 0, active: 0 });
588
+ }
589
+ findShown = { query: checked.query, caseSensitive: checked.caseSensitive };
590
+ return askFind({ ...checked });
591
+ },
592
+ clear() {
593
+ if (finds) {
594
+ findShown = null;
595
+ toFrame(FIND_METHODS.clear, {});
596
+ }
597
+ },
598
+ takeShortcut(take) {
599
+ if (finds) {
600
+ takesShortcut = take;
601
+ toFrame(FIND_METHODS.handled, { handled: takesShortcut });
602
+ }
603
+ },
604
+ };
408
605
  const needsAnnotate = (operation: string) => {
409
606
  if (!annotates) {
410
607
  throw new TypeError(`annotations.${operation}: the config doesn't declare annotate`);
@@ -494,6 +691,28 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
494
691
  };
495
692
  };
496
693
 
694
+ // A frame's size is taken at most once an animation frame after its run's first, and only
695
+ // when it changed (P127): `resize` has no gate, and each one would reflow the host's page and
696
+ // tell its listeners.
697
+ let sizeFrame: number | null = null;
698
+ let pendingSize: DisplayEvents["resize"] | null = null;
699
+ let shownSize: DisplayEvents["resize"] | null = null;
700
+ const applySize = () => {
701
+ sizeFrame = null;
702
+ const size = pendingSize;
703
+ pendingSize = null;
704
+ if (
705
+ size === null ||
706
+ (shownSize !== null && size.height === shownSize.height && size.width === shownSize.width)
707
+ ) {
708
+ return;
709
+ }
710
+ shownSize = size;
711
+ height = size.height;
712
+ surface?.setHeight(size.height);
713
+ emit("resize", size);
714
+ };
715
+
497
716
  const onBridge = (event: BridgeEvent) => {
498
717
  switch (event.type) {
499
718
  case "resize": {
@@ -501,12 +720,16 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
501
720
  config.limits.maxHeightPx,
502
721
  Math.max(config.limits.minHeightPx, Math.ceil(event.height)),
503
722
  );
504
- height = next;
505
- surface?.setHeight(next);
506
- emit("resize", {
723
+ pendingSize = {
507
724
  height: next,
508
725
  ...(event.width === undefined ? {} : { width: event.width }),
509
- });
726
+ };
727
+ // A run's first size at once: until then its frame has no height of its own.
728
+ if (view === null || shownSize === null) {
729
+ applySize();
730
+ } else if (sizeFrame === null) {
731
+ sizeFrame = view.requestAnimationFrame(applySize);
732
+ }
510
733
  return;
511
734
  }
512
735
  case "navigationBlocked":
@@ -524,6 +747,14 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
524
747
  case "annotation":
525
748
  emit("annotation", event.report);
526
749
  return;
750
+ case "find":
751
+ if (event.report.type === "requested") {
752
+ emit("findRequested", undefined);
753
+ } else {
754
+ const { type: _type, ...result } = event.report;
755
+ emit("findUpdated", result);
756
+ }
757
+ return;
527
758
  }
528
759
  };
529
760
 
@@ -544,6 +775,13 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
544
775
  bridge?.close();
545
776
  bridge = null;
546
777
  handshaken = false;
778
+ // The next run's frame tells its own size, the same as this one's or not.
779
+ if (sizeFrame !== null) {
780
+ view?.cancelAnimationFrame(sizeFrame);
781
+ sizeFrame = null;
782
+ }
783
+ pendingSize = null;
784
+ shownSize = null;
547
785
  abort?.abort();
548
786
  abort = null;
549
787
  outcomeWatch?.stop();
@@ -712,6 +950,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
712
950
  if (annotates) {
713
951
  created.transport.listen((raw) => onAnnotation(raw, opening));
714
952
  }
953
+ if (finds) {
954
+ created.transport.listen((raw) => onFind(raw, opening, () => created.focused?.()));
955
+ }
715
956
  // Whether the page used storage (P111): once per run, the page's word (a count, no more).
716
957
  created.transport.listen((raw) => {
717
958
  if (
@@ -744,6 +985,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
744
985
  if (!handshaken) {
745
986
  handshaken = true;
746
987
  giveAnnotations();
988
+ giveFind();
747
989
  }
748
990
  emit("initialized", undefined);
749
991
  }
@@ -758,6 +1000,8 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
758
1000
 
759
1001
  const run = () => {
760
1002
  stop();
1003
+ // Each run is a new frame, maybe of other content: it starts with no query (P131).
1004
+ forgetFind(false);
761
1005
  if (destroyed) {
762
1006
  return;
763
1007
  }
@@ -846,6 +1090,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
846
1090
  const controls = {
847
1091
  displayId: mount.displayId,
848
1092
  annotations,
1093
+ find,
849
1094
  setTheme(next: ColorScheme) {
850
1095
  if (themeless) {
851
1096
  return;
@@ -889,6 +1134,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
889
1134
  destroyed = true;
890
1135
  stop();
891
1136
  listeners.clear();
1137
+ for (const id of findsAsked.keys()) {
1138
+ settleFind(id, "unsupported");
1139
+ }
892
1140
  },
893
1141
  };
894
1142
 
@@ -898,6 +1146,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
898
1146
  get(target, key, receiver) {
899
1147
  if (typeof key === "string" && !(key in target) && !BASE_KEYS.has(key)) {
900
1148
  return (...args: unknown[]) => {
1149
+ // Other content (not the content so far, continued): the query was the last one's.
1150
+ if (key === "setContent" && !continues(replay.get(key)?.[0], args[0])) {
1151
+ forgetFind(true);
1152
+ }
901
1153
  replay.delete(key);
902
1154
  replay.set(key, args);
903
1155
  const operation = (connection as unknown as Record<string, unknown> | null)?.[key];
@@ -913,6 +1165,17 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
913
1165
  };
914
1166
  }
915
1167
 
1168
+ /**
1169
+ * Whether `next` is the content `before` was, continued (P131): the same, or more of it (the next
1170
+ * part of a streamed page). Nothing given before: anything continues it.
1171
+ */
1172
+ function continues(before: unknown, next: unknown): boolean {
1173
+ return (
1174
+ before === undefined ||
1175
+ (typeof before === "string" && typeof next === "string" && next.startsWith(before))
1176
+ );
1177
+ }
1178
+
916
1179
  /** The host's nonce option, read now (`HostOptions.nonce`). */
917
1180
  function nonceOf(nonce: HostOptions["nonce"]): { nonce?: string } {
918
1181
  const value = typeof nonce === "function" ? nonce() : nonce;
@@ -15,8 +15,9 @@ const KINDS: readonly EgressKind[] = ["connect", "script", "style", "img", "font
15
15
  * conversation and context (`sendPrompt`, `setModelContext`), and the host's data services, which
16
16
  * may be someone else's (`callTool`, `readData`, `subscribeData`: their arguments are the page's).
17
17
  * Not here: the person's own clipboard and disk (`copyText`, `downloadFile`), the host's own UI
18
- * (`annotate`, `resize`, `comments`: the composer is the person's, under the host's duties), and
19
- * what only reads (`user`). `reportError` is one where the config sends errors to the agent.
18
+ * (`annotate`, `find`, `resize`, `comments`: the composer is the person's, under the host's
19
+ * duties), and what only reads (`user`). `reportError` is one where the config sends errors to the
20
+ * agent.
20
21
  */
21
22
  const CARRIERS: readonly CapabilityName[] = [
22
23
  "db",
package/src/host/types.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
2
+ import type { FindOptions, FindResult } from "../find/types.ts";
2
3
  import type { Refused } from "../bridge/refusal.ts";
3
4
  import type {
4
5
  Confirm,
@@ -126,6 +127,8 @@ export type HostErrorKind =
126
127
  | "mount"
127
128
  /** An annotation call was refused (an invalid mark, an unknown id). */
128
129
  | "annotations"
130
+ /** A find call was refused (a query too long, options that aren't these: P131). */
131
+ | "find"
129
132
  /**
130
133
  * A frame status (`porthole/notifications/frame-status`) the host didn't take, since it came
131
134
  * from the frame's content, not from a page of Porthole's server (P124): never shown, never an
@@ -238,6 +241,53 @@ export interface DisplayEvents {
238
241
  * content's word: UI hints, never permissions.
239
242
  */
240
243
  readonly annotation: AnnotationReport;
244
+ /**
245
+ * The person pressed Cmd+F (Apple) or Ctrl+F (elsewhere) with the keyboard in the frame (`find`,
246
+ * P131): open the host's find bar. Only while the host takes the shortcut
247
+ * (`find.takeShortcut(true)`, which stops the browser's own find there) and the page's focus is
248
+ * in the frame (where the platform can tell). The content's word: it can say it without the key,
249
+ * or keep the key; open the bar, nothing more.
250
+ */
251
+ readonly findRequested: undefined;
252
+ /**
253
+ * The matches of the query shown changed without the host asking (`find`, P131): the content
254
+ * changed (more of it, or the page's own changes). At most once a second, from an honest shell.
255
+ * The content's word: a find bar's numbers.
256
+ */
257
+ readonly findUpdated: FindResult;
258
+ }
259
+
260
+ /**
261
+ * Find in page on a display whose config declares `find` (P131): the host draws the find bar,
262
+ * the frame finds and highlights. The query is posted into the frame, where the content can read
263
+ * it. Where the config doesn't declare `find`, `query` answers `"unsupported"` and the rest do
264
+ * nothing. The shortcut is kept and given to every frame the display runs. The query holds only for
265
+ * the content it was asked of: a new run (`reload()`, a restart after the content navigated away,
266
+ * a new location) or other content (`setContent` with content that doesn't continue what was
267
+ * given) forgets it and answers what waits `"unsupported"`, and nothing is found there until the
268
+ * host asks again: clear your find bar then.
269
+ */
270
+ export interface FindControls {
271
+ /**
272
+ * Finds `query` in the content's text (case-insensitive by default, any spacing), highlights
273
+ * every match, makes one current (the first in view for a new query; the next or previous one
274
+ * with `direction`), scrolls it into view, and answers where they stand. An empty query (or
275
+ * only spaces) clears, and answers no matches. `"unsupported"` where the frame can't find: the
276
+ * config doesn't declare `find`, the frame's shell is older (it answered that it doesn't know
277
+ * the request), it failed, it didn't answer in `FIND_LIMITS.timeoutMs` once it ran, a later
278
+ * query superseded it before it ran (only the latest is searched: show the answer to your latest
279
+ * query only), or the content it was asked of is gone (a new run, other content). Rejects
280
+ * with a `TypeError` for a query longer than `FIND_LIMITS.query`, or options that aren't these.
281
+ */
282
+ query(query: string, options?: FindOptions): Promise<FindResult | "unsupported">;
283
+ /** Removes the highlights and forgets the query (the find bar closed). */
284
+ clear(): void;
285
+ /**
286
+ * Whether the host draws its own find bar for this display (default no): while it does, Cmd+F
287
+ * or Ctrl+F in the frame doesn't open the browser's own find, and the display says
288
+ * `findRequested` instead. A page that handles the key itself keeps it.
289
+ */
290
+ takeShortcut(take: boolean): void;
241
291
  }
242
292
 
243
293
  /**
@@ -285,6 +335,8 @@ export interface DisplayControls {
285
335
  ): () => void;
286
336
  /** Annotations (`annotate`): throws on use where the config doesn't declare it. */
287
337
  readonly annotations: AnnotationControls;
338
+ /** Find in page (`find`, P131): `"unsupported"` where the config doesn't declare it. */
339
+ readonly find: FindControls;
288
340
  /** Runs the content again from the start, in a new frame. */
289
341
  reload(): void;
290
342
  /**
package/src/index.ts CHANGED
@@ -197,6 +197,7 @@ export {
197
197
  assetCspDirectives,
198
198
  FILE_SET_DIRECTIVES,
199
199
  fileSetCspDirectives,
200
+ fileSetDirectives,
200
201
  INERT_FILE_CSP,
201
202
  type CspDirective,
202
203
  type EgressKind,
@@ -318,6 +319,7 @@ export {
318
319
  } from "./host/locator.ts";
319
320
  export type {
320
321
  AnnotationControls,
322
+ FindControls,
321
323
  DisplayControls,
322
324
  DisplayEvents,
323
325
  FrameBlock,
@@ -346,3 +348,14 @@ export {
346
348
  type TextQuoteSelector,
347
349
  } from "./annotate/types.ts";
348
350
  export { parseAnchor, parseRect, parseReport } from "./annotate/validate.ts";
351
+
352
+ // Find in page (P131): the host's find bar, the frame's matches, and the host's checks on both.
353
+ export {
354
+ FIND_LIMITS,
355
+ FIND_METHODS,
356
+ type FindDirection,
357
+ type FindOptions,
358
+ type FindReport,
359
+ type FindResult,
360
+ } from "./find/types.ts";
361
+ export { parseFindReport, parseFindResult } from "./find/validate.ts";
@@ -58,6 +58,12 @@ export interface PresetOptions {
58
58
  readonly runtime?: RuntimeVersion;
59
59
  /** Domain isolation, artifact pages: the page in an opaque child of Porthole's shell (P111). */
60
60
  readonly nested?: true;
61
+ /**
62
+ * `own` (P128): an `<iframe>` of one of the page's own files (a relative `src`) or a `srcdoc`
63
+ * one loads and runs, in a realm of its own that the shell's hardening doesn't reach
64
+ * (`PortholeConfig.nestedFrames`). `none` (default): every nested frame is removed.
65
+ */
66
+ readonly nestedFrames?: "none" | "own";
61
67
  }
62
68
 
63
69
  /** What a live widget may say about a capability (P103): anything but origins of its own. */
@@ -244,6 +250,7 @@ function build(
244
250
  ...(options.errors === undefined ? {} : { errors: options.errors }),
245
251
  ...(options.runtime === undefined ? {} : { runtime: options.runtime }),
246
252
  ...(options.nested === undefined ? {} : { nested: options.nested }),
253
+ ...(options.nestedFrames === undefined ? {} : { nestedFrames: options.nestedFrames }),
247
254
  });
248
255
  }
249
256
 
@@ -271,6 +278,14 @@ export const presets = {
271
278
  "a live widget has no network of its own: its egress stays closed (P079)",
272
279
  );
273
280
  }
281
+ // A child frame is a realm the shell's WebRTC removal never reached (P128): a network of its
282
+ // own, which a live widget never has.
283
+ if (options.nestedFrames === "own") {
284
+ throw new ConfigError(
285
+ "options.nestedFrames",
286
+ "a live widget has no network of its own: its frames stay removed (P079, P128)",
287
+ );
288
+ }
274
289
  // A capability's own origins join the CSP as egress does (P103): none for a live widget.
275
290
  for (const [name, value] of Object.entries((options as PresetOptions).capabilities ?? {})) {
276
291
  for (const field of ["connect", "resource"] as const) {