@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
@@ -1,5 +1,6 @@
1
1
  import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
2
  import { createContext, useCallback, useContext, useEffect, useEffectEvent, useId, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
3
+ import { blankQuery, checkFindQuery } from "../find/validate.js";
3
4
  import { isRefused, reasonOf, Refused } from "../bridge/refusal.js";
4
5
  import { writeClipboard } from "../host/clipboard.js";
5
6
  import { createHost } from "../host/create-host.js";
@@ -259,6 +260,32 @@ export function PortholeProvider(props) {
259
260
  void writeClipboard(failed.text, globalThis.document).then((copied) => setNotice({ ...failed, copied }));
260
261
  } }))] }));
261
262
  }
263
+ /** What the frame shows with these props, for its handle's query (P131). */
264
+ export function findScopeOf(props) {
265
+ return {
266
+ shows: JSON.stringify([
267
+ props.config,
268
+ props.instance ?? null,
269
+ props.declaration ?? null,
270
+ props.viewer ?? null,
271
+ props.generation ?? 0,
272
+ ]),
273
+ document: props.document,
274
+ content: props.content,
275
+ };
276
+ }
277
+ /**
278
+ * Whether a frame showing `now` still shows what a query was asked of (`asked`, P131): the same
279
+ * config, instance, declaration, viewer, generation and document, and the content as it was or
280
+ * continued (more of a streamed page; asked before any content: whatever came). Otherwise the
281
+ * query was the last page's, and a new one is never searched with it.
282
+ */
283
+ export function sameFindScope(asked, now) {
284
+ return (asked.shows === now.shows &&
285
+ asked.document === now.document &&
286
+ (asked.content === undefined ||
287
+ (now.content !== undefined && now.content.startsWith(asked.content))));
288
+ }
262
289
  const PLACEHOLDER_STYLE = {
263
290
  position: "absolute",
264
291
  inset: 0,
@@ -303,6 +330,18 @@ export function PortholeFrame(props) {
303
330
  useLayoutEffect(() => {
304
331
  own.current = props;
305
332
  });
333
+ // The query the handle last found (P131): a display made after it, for the same content, finds
334
+ // it again.
335
+ const findShown = useRef(null);
336
+ // The query kept for what a display shows (`scope`), else forgotten: null.
337
+ const findFor = useCallback((scope) => {
338
+ const kept = findShown.current;
339
+ if (kept !== null && !sameFindScope(kept.scope, scope)) {
340
+ findShown.current = null;
341
+ return null;
342
+ }
343
+ return kept;
344
+ }, []);
306
345
  useImperativeHandle(handleRef, () => ({
307
346
  clearSelection() {
308
347
  const now = display.current;
@@ -310,6 +349,33 @@ export function PortholeFrame(props) {
310
349
  attempt(() => now.annotations.clearSelection(), own.current);
311
350
  }
312
351
  },
352
+ find(query, options) {
353
+ try {
354
+ checkFindQuery(query, options);
355
+ }
356
+ catch (error) {
357
+ hostFailed(own.current, error, "find");
358
+ return Promise.resolve("unsupported");
359
+ }
360
+ findShown.current = blankQuery(query)
361
+ ? null
362
+ : {
363
+ query,
364
+ caseSensitive: options?.caseSensitive === true,
365
+ scope: findScopeOf(own.current),
366
+ };
367
+ const now = display.current;
368
+ return now === null
369
+ ? Promise.resolve("unsupported")
370
+ : now.find.query(query, options).catch((error) => {
371
+ hostFailed(own.current, error, "find");
372
+ return "unsupported";
373
+ });
374
+ },
375
+ clearFind() {
376
+ findShown.current = null;
377
+ display.current?.find.clear();
378
+ },
313
379
  }), []);
314
380
  useEffect(() => {
315
381
  const element = box.current;
@@ -361,10 +427,10 @@ export function PortholeFrame(props) {
361
427
  : {}),
362
428
  ...(state === "running" ? {} : { minHeight: Math.max(height, PLACEHOLDER_HEIGHT_PX) }),
363
429
  ...props.style,
364
- }, children: state === "running" ? (_jsx(Mount, { frame: props, page: page, running: running, initialHeightPx: height, placeholder: placeholder, run: run }, String(props.generation ?? 0))) : (placeholder({ state, title: props.title, run })) }));
430
+ }, children: state === "running" ? (_jsx(Mount, { frame: props, page: page, running: running, findFor: findFor, initialHeightPx: height, placeholder: placeholder, run: run }, String(props.generation ?? 0))) : (placeholder({ state, title: props.title, run })) }));
365
431
  }
366
432
  /** One running display: created when mounted, torn down when unmounted, fed as props change. */
367
- function Mount({ frame, page, running, initialHeightPx, placeholder, run, }) {
433
+ function Mount({ frame, page, running, findFor, initialHeightPx, placeholder, run, }) {
368
434
  const holder = useRef(null);
369
435
  const handle = useRef(null);
370
436
  // The mark the display follows now, as the core keeps it (P118), and the prop as last seen.
@@ -445,6 +511,12 @@ function Mount({ frame, page, running, initialHeightPx, placeholder, run, }) {
445
511
  case "annotation":
446
512
  frame.onAnnotation?.(detail);
447
513
  return;
514
+ case "findRequested":
515
+ frame.onFindRequested?.();
516
+ return;
517
+ case "findUpdated":
518
+ frame.onFindUpdated?.(detail);
519
+ return;
448
520
  }
449
521
  });
450
522
  useEffect(() => {
@@ -560,6 +632,8 @@ function Mount({ frame, page, running, initialHeightPx, placeholder, run, }) {
560
632
  "focusTaken",
561
633
  "outcome",
562
634
  "annotation",
635
+ "findRequested",
636
+ "findUpdated",
563
637
  "contentError",
564
638
  "hostError",
565
639
  ];
@@ -579,6 +653,22 @@ function Mount({ frame, page, running, initialHeightPx, placeholder, run, }) {
579
653
  following.current = wanted;
580
654
  }, first);
581
655
  }
656
+ // Find (P131): the shortcut is the host's where it listens for it; the handle's query, found
657
+ // again in this display where it shows what the query was asked of (its numbers told as an
658
+ // update: nobody awaits them), else forgotten: another page is never searched with it.
659
+ if (first.onFindRequested !== undefined) {
660
+ display.find.takeShortcut(true);
661
+ }
662
+ const shownQuery = findFor(findScopeOf(first));
663
+ if (shownQuery !== null) {
664
+ void display.find
665
+ .query(shownQuery.query, { caseSensitive: shownQuery.caseSensitive })
666
+ .then((result) => {
667
+ if (result !== "unsupported" && findFor(findScopeOf(latest())) === shownQuery) {
668
+ latest().onFindUpdated?.(result);
669
+ }
670
+ });
671
+ }
582
672
  if (first.content !== undefined) {
583
673
  display.setContent(first.content, { partial: first.partial === true });
584
674
  }
@@ -610,12 +700,16 @@ function Mount({ frame, page, running, initialHeightPx, placeholder, run, }) {
610
700
  locate,
611
701
  nonce,
612
702
  running,
703
+ findFor,
613
704
  ]);
614
705
  useEffect(() => {
615
706
  if (content !== undefined) {
616
707
  handle.current?.setContent(content, { partial: partial === true });
617
708
  }
618
- }, [content, partial]);
709
+ // Other content: the handle's query was the last one's, forgotten (the display forgot it too,
710
+ // P131).
711
+ findFor(findScopeOf(latest()));
712
+ }, [content, partial, findFor]);
619
713
  // Annotations follow their props (a new display gets them all when it is made, above).
620
714
  const annotates = config.capabilities.annotate !== undefined;
621
715
  const { annotating } = frame;
@@ -678,6 +772,16 @@ function Mount({ frame, page, running, initialHeightPx, placeholder, run, }) {
678
772
  attempt(() => display.annotations.focus(id), latest());
679
773
  }
680
774
  }, [annotates, focusToken]);
775
+ // The frame's shortcut is the host's while it listens for it (P131).
776
+ const takesFind = frame.onFindRequested !== undefined;
777
+ const [mountTakesFind] = useState(takesFind);
778
+ const findFlipped = useRef(false);
779
+ useEffect(() => {
780
+ if (findFlipped.current || takesFind !== mountTakesFind) {
781
+ findFlipped.current = true;
782
+ handle.current?.find.takeShortcut(takesFind);
783
+ }
784
+ }, [takesFind, mountTakesFind]);
681
785
  // A flip or a restyle after the display was made: its first scheme and values went with it.
682
786
  const [mountScheme] = useState(scheme);
683
787
  const flipped = useRef(false);
@@ -129,6 +129,8 @@ function InstanceView(props) {
129
129
  const shown = useRef(null);
130
130
  useImperativeHandle(ref, () => ({
131
131
  clearSelection: () => shown.current?.clearSelection(),
132
+ find: (query, options) => shown.current?.find(query, options) ?? Promise.resolve("unsupported"),
133
+ clearFind: () => shown.current?.clearFind(),
132
134
  }), []);
133
135
  const [failed, setFailed] = useState(null);
134
136
  const [generation, setGeneration] = useState(0);
@@ -152,7 +152,7 @@ export declare function runtimeCapability(name: RuntimeCapabilityName): RuntimeC
152
152
  export declare const RUNTIME_HOST_FUNCTIONS: readonly CapabilityName[];
153
153
  /**
154
154
  * Where a host function sits in the runtime: its capability and the methods it serves. Null for
155
- * the shell's own (`resize`, `reportError`, `annotate`), which content never calls by name.
155
+ * the shell's own (`resize`, `reportError`, `annotate`, `find`), which content never calls by name.
156
156
  */
157
157
  export declare function familyOf(serves: CapabilityName): {
158
158
  readonly name: RuntimeCapabilityName;
@@ -112,7 +112,7 @@ export const RUNTIME_HOST_FUNCTIONS = [
112
112
  ];
113
113
  /**
114
114
  * Where a host function sits in the runtime: its capability and the methods it serves. Null for
115
- * the shell's own (`resize`, `reportError`, `annotate`), which content never calls by name.
115
+ * the shell's own (`resize`, `reportError`, `annotate`, `find`), which content never calls by name.
116
116
  */
117
117
  export function familyOf(serves) {
118
118
  for (const name of RUNTIME_CAPABILITY_NAMES) {
@@ -1,4 +1,4 @@
1
- import { assetCspDirectives, fileSetCspDirectives, INERT_FILE_CSP, servedDocumentCsp, servedPermissionsPolicy, serializeCsp, } from "../compile/policy.js";
1
+ import { assetCspDirectives, fileSetCspDirectives, fileSetDirectives, INERT_FILE_CSP, servedDocumentCsp, servedPermissionsPolicy, serializeCsp, } from "../compile/policy.js";
2
2
  import { DEFAULT_ENTRY, lookupFile, requestFilePath } from "../files/paths.js";
3
3
  import { fileTypeOf } from "../files/types.js";
4
4
  import { isCodeAsset } from "../runtime/requests.js";
@@ -187,8 +187,9 @@ export async function serveFile(serving) {
187
187
  serving.compiled.config.capabilities.assets !== undefined
188
188
  ? "same-origin"
189
189
  : "no-referrer";
190
- // Its version's files (P082), and its artifact's assets where the config serves them (P089).
191
- const directives = assetCspDirectives(serving.compiled.config, fileSetCspDirectives(serving.compiled.cspDirectives, serving.source), serving.origin);
190
+ // Its version's files (P082), frames of them where the config opts in (P128), and its
191
+ // artifact's assets where the config serves them (P089).
192
+ const directives = assetCspDirectives(serving.compiled.config, fileSetCspDirectives(serving.compiled.cspDirectives, serving.source, fileSetDirectives(serving.compiled.config)), serving.origin);
192
193
  // A page and a script (a worker's policy is its script's) get the page's CSP, a page with its
193
194
  // frame's sandbox, on a tab of its own too (P099); anything else runs nothing when opened on
194
195
  // its own.
@@ -1032,6 +1032,9 @@ export function createServer(options) {
1032
1032
  const ancestors = nested ? nestedAncestors(access.origin, frameAncestors) : frameAncestors;
1033
1033
  if ("files" in served) {
1034
1034
  if (at !== undefined) {
1035
+ // A page's own frames (P128): its files below the base are framed by its own pages too,
1036
+ // on this origin (`frame-ancestors` names every ancestor). Never another origin's.
1037
+ const own = served.compiled.config.nestedFrames === "own";
1035
1038
  return serveFile({
1036
1039
  request,
1037
1040
  set: served.files,
@@ -1043,7 +1046,7 @@ export function createServer(options) {
1043
1046
  source: at.source,
1044
1047
  compiled: served.compiled,
1045
1048
  hostOrigins: options.hostOrigins,
1046
- frameAncestors: ancestors,
1049
+ frameAncestors: own ? `${access.origin} ${ancestors}` : ancestors,
1047
1050
  ...versionOf(access.instance),
1048
1051
  });
1049
1052
  }
@@ -1,3 +1,4 @@
1
+ import { TEXT_INDEX } from "./text.js";
1
2
  /**
2
3
  * Which marker a press on the shell's layer is for (P119), spliced into the runtime: the index of
3
4
  * `count` boxes (`boxAt(i)`, the markers' own boxes in the viewport, the last drawn on top), or -1.
@@ -106,101 +107,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
106
107
  const squash = (text) => String(text).replace(/\s+/g, " ").trim();
107
108
  const box = (rect) => ({ x: rect.left, y: rect.top, width: rect.width, height: rect.height });
108
109
 
109
- // The document's text: the body's text nodes in order, without scripts, styles, templates.
110
- const SKIPPED = { script: 1, style: 1, noscript: 1, template: 1 };
111
- const textIndex = () => {
112
- const nodes = [];
113
- const starts = [];
114
- const at = new Map();
115
- let text = "";
116
- const body = document.body;
117
- if (body) {
118
- const walker = createTreeWalker.call(document, body, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT, {
119
- acceptNode: (node) => (node.nodeType === 1 ? (SKIPPED[node.localName] ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_SKIP) : NodeFilter.FILTER_ACCEPT),
120
- });
121
- for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
122
- at.set(node, nodes.length);
123
- nodes.push(node);
124
- starts.push(text.length);
125
- text += node.nodeValue;
126
- }
127
- }
128
- return { nodes, starts, at, text };
129
- };
130
- // A boundary point as an offset into the text: in a text node, where it is; elsewhere, the
131
- // first text at or after it.
132
- const offsetOf = (index, container, offset) => {
133
- if (container.nodeType === 3 && index.at.has(container)) {
134
- return index.starts[index.at.get(container)] + Math.min(offset, container.nodeValue.length);
135
- }
136
- const point = createRange.call(document);
137
- try {
138
- point.setStart(container, offset);
139
- } catch (_) {
140
- return index.text.length;
141
- }
142
- point.collapse(true);
143
- let low = 0;
144
- let high = index.nodes.length;
145
- while (low < high) {
146
- const middle = (low + high) >> 1;
147
- if (point.comparePoint(index.nodes[middle], 0) >= 0) {
148
- high = middle;
149
- } else {
150
- low = middle + 1;
151
- }
152
- }
153
- return low < index.nodes.length ? index.starts[low] : index.text.length;
154
- };
155
- const pointAt = (index, at, end) => {
156
- let low = 0;
157
- let high = index.nodes.length - 1;
158
- let found = -1;
159
- while (low <= high) {
160
- const middle = (low + high) >> 1;
161
- if (index.starts[middle] <= at) {
162
- found = middle;
163
- low = middle + 1;
164
- } else {
165
- high = middle - 1;
166
- }
167
- }
168
- if (found === -1) {
169
- return null;
170
- }
171
- let node = index.nodes[found];
172
- let offset = at - index.starts[found];
173
- if (end) {
174
- // An end at a node's very start belongs to the text before it.
175
- while (offset === 0 && found > 0) {
176
- found -= 1;
177
- node = index.nodes[found];
178
- offset = node.nodeValue.length;
179
- }
180
- } else {
181
- while (offset >= node.nodeValue.length && found + 1 < index.nodes.length) {
182
- found += 1;
183
- node = index.nodes[found];
184
- offset = 0;
185
- }
186
- }
187
- return { node, offset: Math.min(offset, node.nodeValue.length) };
188
- };
189
- const rangeAt = (index, start, end) => {
190
- const from = pointAt(index, start, false);
191
- const to = pointAt(index, end, true);
192
- if (from === null || to === null) {
193
- return null;
194
- }
195
- const range = createRange.call(document);
196
- try {
197
- range.setStart(from.node, from.offset);
198
- range.setEnd(to.node, to.offset);
199
- } catch (_) {
200
- return null;
201
- }
202
- return range;
203
- };
110
+ ${TEXT_INDEX}
204
111
  const spanOf = (index, node) => {
205
112
  const range = createRange.call(document);
206
113
  range.selectNodeContents(node);
@@ -62,9 +62,9 @@ export interface ShellDocumentOptions {
62
62
  * A given `document` travels in the runtime's plan, as data.
63
63
  */
64
64
  /**
65
- * The shell's runtime for a plan, before its plan goes in: annotations where declared, 0.6's
66
- * globals (the legacy path, P085) for what the config declares, and the capability runtime where
67
- * the config has one.
65
+ * The shell's runtime for a plan, before its plan goes in: annotations and find in page (P131)
66
+ * where declared, 0.6's globals (the legacy path, P085) for what the config declares, and the
67
+ * capability runtime where the config has one.
68
68
  */
69
69
  export declare function composedRuntime(plan: ShellPlan): string;
70
70
  export declare function shellDocument(plan: ShellPlan, csp: string, options: ShellDocumentOptions): string;
@@ -1,5 +1,6 @@
1
1
  import { hostOriginProblem } from "../isolation/served.js";
2
2
  import { ANNOTATE_RUNTIME } from "./annotate.js";
3
+ import { FIND_RUNTIME } from "./find.js";
3
4
  import { LEGACY_GLOBALS_RUNTIME } from "./legacy.js";
4
5
  import { SHELL_RUNTIME } from "./runtime.js";
5
6
  import { USE_RUNTIME } from "./use.js";
@@ -65,12 +66,13 @@ body {
65
66
  * A given `document` travels in the runtime's plan, as data.
66
67
  */
67
68
  /**
68
- * The shell's runtime for a plan, before its plan goes in: annotations where declared, 0.6's
69
- * globals (the legacy path, P085) for what the config declares, and the capability runtime where
70
- * the config has one.
69
+ * The shell's runtime for a plan, before its plan goes in: annotations and find in page (P131)
70
+ * where declared, 0.6's globals (the legacy path, P085) for what the config declares, and the
71
+ * capability runtime where the config has one.
71
72
  */
72
73
  export function composedRuntime(plan) {
73
74
  return SHELL_RUNTIME.replace("__ANNOTATE__", () => plan.capabilities.annotate === undefined ? "" : ANNOTATE_RUNTIME)
75
+ .replace("__FIND__", () => (plan.capabilities.find === undefined ? "" : FIND_RUNTIME))
74
76
  .replace("__LEGACY__", () => LEGACY_GLOBALS_RUNTIME)
75
77
  .replace("__RUNTIME__", () => (plan.runtime === undefined ? "" : USE_RUNTIME));
76
78
  }
@@ -0,0 +1,82 @@
1
+ /**
2
+ * The matches of a query in the document's text (P131), spliced into the find runtime: `text` is
3
+ * the text index's (`textIndex().text`), `query` the person's words. Case-insensitive unless
4
+ * `caseSensitive` (Unicode simple case folding, `u` and `i`, so a match keeps the text's own
5
+ * offsets), and loose about spacing as annotations' `squash` is: the query is trimmed, and each
6
+ * run of white space in it matches any run of white space in the text. Everything else is
7
+ * literal (no pattern syntax reaches the expression). Matches don't overlap, in document order.
8
+ *
9
+ * `keep(start, end)` says whether a match counts (the runtime: whether it has a box on screen,
10
+ * and its range), null if not; at most `most` are kept, and at most ten times that many are
11
+ * looked at (`capped`: it stopped there, and there may be more). The platform's own `RegExp`,
12
+ * its `exec` and `Reflect.apply` come in as taken before content ran, and so do the list the
13
+ * spans go in and how one is added (`list`, `push`: the shell's prototype-less `listOf` and
14
+ * `pushTo`); nothing else is called on a prototype content could replace (only indexing,
15
+ * comparisons and `length`).
16
+ */
17
+ export declare const FIND_MATCH: string;
18
+ /**
19
+ * Whether a key is the find shortcut (P131), spliced into the find runtime: Cmd+F on Apple's
20
+ * platforms (`apple`), Ctrl+F elsewhere, with no Alt, no Shift and not the other of the two. The
21
+ * letter is `key`'s; on a layout whose letters aren't Latin (Cyrillic, Greek), the key in F's
22
+ * place (`code`), as browsers find there too. Comparisons only.
23
+ */
24
+ export declare const FIND_SHORTCUT: string;
25
+ /**
26
+ * Only the latest query (P131), spliced into the find runtime: what the shell does with each
27
+ * query the host asks. A search is synchronous and, on a large page, long (hundreds of ms), so a
28
+ * bar that asks at every key builds a queue of messages behind it. A query that comes while none
29
+ * waits, and not within `quiet` ms of the end of the last one run, is run at once (answered
30
+ * before any content's listener could answer it). Otherwise it waits for the next task, after the
31
+ * messages already queued: a later query (or a clear, `drop`) supersedes it, and the one it
32
+ * superseded is answered `superseded(id)` at once (an error; the host makes it `"unsupported"`).
33
+ * So a burst is at most the query running and the latest, never each in turn.
34
+ *
35
+ * `later(run, wait)` and `time()` are the shell's kept timers and clock, `run(id, request)` runs
36
+ * and answers a query; `request` is what the runtime read from the host's message when it came
37
+ * (read once, never again). Comparisons and its own closures only.
38
+ */
39
+ export declare const FIND_LATEST: string;
40
+ /**
41
+ * The style of the shell's layers over the content (annotations' and find's): inline and
42
+ * important, so the content's own style sheets can't hide, shrink or move it by accident (its
43
+ * scripts can, P104). The annotation runtime carries the same text (a test holds them equal).
44
+ */
45
+ export declare const LAYER_STYLE = "position:fixed!important;inset:0!important;width:auto!important;height:auto!important;min-width:0!important;min-height:0!important;max-width:none!important;max-height:none!important;display:block!important;visibility:visible!important;opacity:1!important;pointer-events:none!important;z-index:2147483647!important;overflow:hidden!important;margin:0!important;padding:0!important;border:0!important;background:none!important;transform:none!important;scale:none!important;translate:none!important;rotate:none!important;zoom:1!important;clip-path:none!important;mask:none!important;filter:none!important;content-visibility:visible!important;contain:none!important";
46
+ /**
47
+ * The shell's find in page (P131), spliced into the shell's runtime (`__FIND__`) when the config
48
+ * declares `find`, so it runs before any content does, with the DOM's own functions as they were.
49
+ * Plain ES2020 like the rest of the shell; no template literals (it sits in one).
50
+ *
51
+ * The host drives it (`porthole/find.query`, a request; `porthole/find.clear|handled`) and it
52
+ * says (`porthole/find.requested|updated`):
53
+ * - a query: its matches in the document's text (annotations' text index: the body's text nodes,
54
+ * without scripts, styles, noscript, templates), case-insensitive and loose about spacing,
55
+ * those with a box on screen, at most 1,000; each is drawn in a layer of the shell's own (a
56
+ * closed shadow root, over the content, as annotations' marks are; never the CSS Custom
57
+ * Highlight API, which content can read and rewrite: P053, P104), the current one apart, again
58
+ * at each scroll, resize and change of the content; the answer is how many and which, and the
59
+ * current one's box once it was scrolled into view (its scrolling ancestors first, then the
60
+ * window, centred); only the latest of a burst is searched, the ones it superseded answered
61
+ * with an error (`FIND_LATEST`);
62
+ * - a change of the content while a query is shown: found again once it settles (at most a
63
+ * second late), the current match kept by its place, and the host told when the count or the
64
+ * current one changed, at most once a second;
65
+ * - the shortcut: while the host says it draws its own find bar (`handled`), Cmd+F (Apple) or
66
+ * Ctrl+F (elsewhere) in the frame that the page didn't take itself (it called preventDefault)
67
+ * stops the browser's own find and is told (`requested`); otherwise the key is left alone.
68
+ *
69
+ * Every built-in it calls once content may have run is one it took before (the DOM's methods and
70
+ * getters, the timers, `postMessage`, `Map`, `RegExp`), called through the shell's `callOf`
71
+ * (P129); its lists are the shell's prototype-less ones, and what it reads from the host's message
72
+ * (the event's fields, the request's own properties) is read once and only as a string, a number
73
+ * or a boolean. The nodes of its layer go in only through the shell's guarded insertion methods
74
+ * (P130: `createElement`, `attachShadow`, `appendChild`, `replaceChildren`, the `textContent`
75
+ * setter, taken after the shell wrapped them), and it inserts nothing into the content's own
76
+ * trees.
77
+ *
78
+ * It shares the realm with the content, which can read the query, change what matches, hide the
79
+ * layer, keep the key from it or say `requested` itself: the host takes what it says as a find
80
+ * bar's numbers, never as facts.
81
+ */
82
+ export declare const FIND_RUNTIME: string;