@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/src/host/create-host.ts
CHANGED
|
@@ -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`);
|
|
@@ -550,6 +747,14 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
550
747
|
case "annotation":
|
|
551
748
|
emit("annotation", event.report);
|
|
552
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;
|
|
553
758
|
}
|
|
554
759
|
};
|
|
555
760
|
|
|
@@ -745,6 +950,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
745
950
|
if (annotates) {
|
|
746
951
|
created.transport.listen((raw) => onAnnotation(raw, opening));
|
|
747
952
|
}
|
|
953
|
+
if (finds) {
|
|
954
|
+
created.transport.listen((raw) => onFind(raw, opening, () => created.focused?.()));
|
|
955
|
+
}
|
|
748
956
|
// Whether the page used storage (P111): once per run, the page's word (a count, no more).
|
|
749
957
|
created.transport.listen((raw) => {
|
|
750
958
|
if (
|
|
@@ -777,6 +985,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
777
985
|
if (!handshaken) {
|
|
778
986
|
handshaken = true;
|
|
779
987
|
giveAnnotations();
|
|
988
|
+
giveFind();
|
|
780
989
|
}
|
|
781
990
|
emit("initialized", undefined);
|
|
782
991
|
}
|
|
@@ -791,6 +1000,8 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
791
1000
|
|
|
792
1001
|
const run = () => {
|
|
793
1002
|
stop();
|
|
1003
|
+
// Each run is a new frame, maybe of other content: it starts with no query (P131).
|
|
1004
|
+
forgetFind(false);
|
|
794
1005
|
if (destroyed) {
|
|
795
1006
|
return;
|
|
796
1007
|
}
|
|
@@ -879,6 +1090,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
879
1090
|
const controls = {
|
|
880
1091
|
displayId: mount.displayId,
|
|
881
1092
|
annotations,
|
|
1093
|
+
find,
|
|
882
1094
|
setTheme(next: ColorScheme) {
|
|
883
1095
|
if (themeless) {
|
|
884
1096
|
return;
|
|
@@ -922,6 +1134,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
922
1134
|
destroyed = true;
|
|
923
1135
|
stop();
|
|
924
1136
|
listeners.clear();
|
|
1137
|
+
for (const id of findsAsked.keys()) {
|
|
1138
|
+
settleFind(id, "unsupported");
|
|
1139
|
+
}
|
|
925
1140
|
},
|
|
926
1141
|
};
|
|
927
1142
|
|
|
@@ -931,6 +1146,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
931
1146
|
get(target, key, receiver) {
|
|
932
1147
|
if (typeof key === "string" && !(key in target) && !BASE_KEYS.has(key)) {
|
|
933
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
|
+
}
|
|
934
1153
|
replay.delete(key);
|
|
935
1154
|
replay.set(key, args);
|
|
936
1155
|
const operation = (connection as unknown as Record<string, unknown> | null)?.[key];
|
|
@@ -946,6 +1165,17 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
946
1165
|
};
|
|
947
1166
|
}
|
|
948
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
|
+
|
|
949
1179
|
/** The host's nonce option, read now (`HostOptions.nonce`). */
|
|
950
1180
|
function nonceOf(nonce: HostOptions["nonce"]): { nonce?: string } {
|
|
951
1181
|
const value = typeof nonce === "function" ? nonce() : nonce;
|
package/src/host/pass-on.ts
CHANGED
|
@@ -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
|
|
19
|
-
* what only reads (`user`). `reportError` is one where the config sends errors to the
|
|
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
|
@@ -319,6 +319,7 @@ export {
|
|
|
319
319
|
} from "./host/locator.ts";
|
|
320
320
|
export type {
|
|
321
321
|
AnnotationControls,
|
|
322
|
+
FindControls,
|
|
322
323
|
DisplayControls,
|
|
323
324
|
DisplayEvents,
|
|
324
325
|
FrameBlock,
|
|
@@ -347,3 +348,14 @@ export {
|
|
|
347
348
|
type TextQuoteSelector,
|
|
348
349
|
} from "./annotate/types.ts";
|
|
349
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";
|
package/src/react/frame.tsx
CHANGED
|
@@ -19,6 +19,8 @@ import {
|
|
|
19
19
|
type Ref,
|
|
20
20
|
} from "react";
|
|
21
21
|
import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
|
|
22
|
+
import type { FindOptions, FindResult } from "../find/types.ts";
|
|
23
|
+
import { blankQuery, checkFindQuery } from "../find/validate.ts";
|
|
22
24
|
import type {
|
|
23
25
|
CallContext,
|
|
24
26
|
CapabilityHandler,
|
|
@@ -495,6 +497,68 @@ export interface PortholeFrameHandle {
|
|
|
495
497
|
* `"annotations"` (the core's call throws; this never does).
|
|
496
498
|
*/
|
|
497
499
|
clearSelection(): void;
|
|
500
|
+
/**
|
|
501
|
+
* Finds `query` in the frame and highlights it (`find.query`, P131): where the matches stand,
|
|
502
|
+
* or `"unsupported"` (a config without `find`, an older shell, no answer in time, a later
|
|
503
|
+
* query superseded it, or no display running now). The query is kept for the content the frame
|
|
504
|
+
* shows now only: a display made later for the same content (the frame neared the screen again)
|
|
505
|
+
* finds it again and tells `onFindUpdated`; other content (another `content` that doesn't
|
|
506
|
+
* continue it, `document`, `instance`, `config`, `declaration` or `viewer`, a new `generation`)
|
|
507
|
+
* forgets it, and nothing is found there until `find` is called again (clear your find bar
|
|
508
|
+
* then). A query too long, or options that aren't these: `onHostError`, kind `"find"`, and
|
|
509
|
+
* `"unsupported"` (never a rejection). An empty query clears.
|
|
510
|
+
*/
|
|
511
|
+
find(query: string, options?: FindOptions): Promise<FindResult | "unsupported">;
|
|
512
|
+
/** Removes the highlights and forgets the query (`find.clear`): the host's find bar closed. */
|
|
513
|
+
clearFind(): void;
|
|
514
|
+
}
|
|
515
|
+
|
|
516
|
+
/**
|
|
517
|
+
* The query a frame's handle last found (P131), and what the frame showed when it was asked: a
|
|
518
|
+
* display made after it finds it again only where the frame still shows that (`sameFindScope`).
|
|
519
|
+
*/
|
|
520
|
+
type FindShown = {
|
|
521
|
+
readonly query: string;
|
|
522
|
+
readonly caseSensitive: boolean;
|
|
523
|
+
readonly scope: FindScope;
|
|
524
|
+
} | null;
|
|
525
|
+
|
|
526
|
+
/** What a frame shows, as its handle's query holds it (P131). */
|
|
527
|
+
export interface FindScope {
|
|
528
|
+
/** The config, instance (its version too), declaration, viewer and generation, by value. */
|
|
529
|
+
readonly shows: string;
|
|
530
|
+
readonly document: string | undefined;
|
|
531
|
+
readonly content: string | undefined;
|
|
532
|
+
}
|
|
533
|
+
|
|
534
|
+
/** What the frame shows with these props, for its handle's query (P131). */
|
|
535
|
+
export function findScopeOf(props: PortholeFrameProps): FindScope {
|
|
536
|
+
return {
|
|
537
|
+
shows: JSON.stringify([
|
|
538
|
+
props.config,
|
|
539
|
+
props.instance ?? null,
|
|
540
|
+
props.declaration ?? null,
|
|
541
|
+
props.viewer ?? null,
|
|
542
|
+
props.generation ?? 0,
|
|
543
|
+
]),
|
|
544
|
+
document: props.document,
|
|
545
|
+
content: props.content,
|
|
546
|
+
};
|
|
547
|
+
}
|
|
548
|
+
|
|
549
|
+
/**
|
|
550
|
+
* Whether a frame showing `now` still shows what a query was asked of (`asked`, P131): the same
|
|
551
|
+
* config, instance, declaration, viewer, generation and document, and the content as it was or
|
|
552
|
+
* continued (more of a streamed page; asked before any content: whatever came). Otherwise the
|
|
553
|
+
* query was the last page's, and a new one is never searched with it.
|
|
554
|
+
*/
|
|
555
|
+
export function sameFindScope(asked: FindScope, now: FindScope): boolean {
|
|
556
|
+
return (
|
|
557
|
+
asked.shows === now.shows &&
|
|
558
|
+
asked.document === now.document &&
|
|
559
|
+
(asked.content === undefined ||
|
|
560
|
+
(now.content !== undefined && now.content.startsWith(asked.content)))
|
|
561
|
+
);
|
|
498
562
|
}
|
|
499
563
|
|
|
500
564
|
export interface PortholeFrameProps {
|
|
@@ -641,6 +705,18 @@ export interface PortholeFrameProps {
|
|
|
641
705
|
* (`activated`). The content's word: UI hints, never permissions.
|
|
642
706
|
*/
|
|
643
707
|
readonly onAnnotation?: (report: AnnotationReport) => void;
|
|
708
|
+
/**
|
|
709
|
+
* The person pressed Cmd+F or Ctrl+F in the frame (`findRequested`, P131): open the host's find
|
|
710
|
+
* bar. Given, it makes the frame's shortcut the host's (`find.takeShortcut(true)`): the
|
|
711
|
+
* browser's own find doesn't open there. The content's word (it can say it, or keep the key):
|
|
712
|
+
* open the bar, nothing more. Where the config declares `find`.
|
|
713
|
+
*/
|
|
714
|
+
readonly onFindRequested?: () => void;
|
|
715
|
+
/**
|
|
716
|
+
* The matches of the query shown changed without the host asking (`findUpdated`, P131): the
|
|
717
|
+
* content changed, or a display made later found the handle's query again.
|
|
718
|
+
*/
|
|
719
|
+
readonly onFindUpdated?: (result: FindResult) => void;
|
|
644
720
|
/** Draws the placeholder instead of the default one. */
|
|
645
721
|
readonly renderPlaceholder?: (props: PlaceholderProps) => ReactNode;
|
|
646
722
|
readonly className?: string;
|
|
@@ -714,6 +790,18 @@ export function PortholeFrame(props: PortholeFrameProps): ReactElement {
|
|
|
714
790
|
useLayoutEffect(() => {
|
|
715
791
|
own.current = props;
|
|
716
792
|
});
|
|
793
|
+
// The query the handle last found (P131): a display made after it, for the same content, finds
|
|
794
|
+
// it again.
|
|
795
|
+
const findShown = useRef<FindShown>(null);
|
|
796
|
+
// The query kept for what a display shows (`scope`), else forgotten: null.
|
|
797
|
+
const findFor = useCallback((scope: FindScope): FindShown => {
|
|
798
|
+
const kept = findShown.current;
|
|
799
|
+
if (kept !== null && !sameFindScope(kept.scope, scope)) {
|
|
800
|
+
findShown.current = null;
|
|
801
|
+
return null;
|
|
802
|
+
}
|
|
803
|
+
return kept;
|
|
804
|
+
}, []);
|
|
717
805
|
useImperativeHandle(
|
|
718
806
|
handleRef,
|
|
719
807
|
(): PortholeFrameHandle => ({
|
|
@@ -723,6 +811,32 @@ export function PortholeFrame(props: PortholeFrameProps): ReactElement {
|
|
|
723
811
|
attempt(() => now.annotations.clearSelection(), own.current);
|
|
724
812
|
}
|
|
725
813
|
},
|
|
814
|
+
find(query, options) {
|
|
815
|
+
try {
|
|
816
|
+
checkFindQuery(query, options);
|
|
817
|
+
} catch (error) {
|
|
818
|
+
hostFailed(own.current, error, "find");
|
|
819
|
+
return Promise.resolve("unsupported");
|
|
820
|
+
}
|
|
821
|
+
findShown.current = blankQuery(query)
|
|
822
|
+
? null
|
|
823
|
+
: {
|
|
824
|
+
query,
|
|
825
|
+
caseSensitive: options?.caseSensitive === true,
|
|
826
|
+
scope: findScopeOf(own.current),
|
|
827
|
+
};
|
|
828
|
+
const now = display.current;
|
|
829
|
+
return now === null
|
|
830
|
+
? Promise.resolve("unsupported")
|
|
831
|
+
: now.find.query(query, options).catch((error: unknown) => {
|
|
832
|
+
hostFailed(own.current, error, "find");
|
|
833
|
+
return "unsupported" as const;
|
|
834
|
+
});
|
|
835
|
+
},
|
|
836
|
+
clearFind() {
|
|
837
|
+
findShown.current = null;
|
|
838
|
+
display.current?.find.clear();
|
|
839
|
+
},
|
|
726
840
|
}),
|
|
727
841
|
[],
|
|
728
842
|
);
|
|
@@ -795,6 +909,7 @@ export function PortholeFrame(props: PortholeFrameProps): ReactElement {
|
|
|
795
909
|
frame={props}
|
|
796
910
|
page={page}
|
|
797
911
|
running={running}
|
|
912
|
+
findFor={findFor}
|
|
798
913
|
initialHeightPx={height}
|
|
799
914
|
placeholder={placeholder}
|
|
800
915
|
run={run}
|
|
@@ -811,6 +926,11 @@ interface MountProps {
|
|
|
811
926
|
readonly page: PageState;
|
|
812
927
|
/** Tells the frame which display runs now (null: none), for its handle. */
|
|
813
928
|
readonly running: (display: DisplayHandle | null) => void;
|
|
929
|
+
/**
|
|
930
|
+
* The query the frame's handle last found, where it was asked of what `scope` shows (P131): a
|
|
931
|
+
* new display for its content finds it again. Otherwise it is forgotten, and null.
|
|
932
|
+
*/
|
|
933
|
+
readonly findFor: (scope: FindScope) => FindShown;
|
|
814
934
|
readonly initialHeightPx: number;
|
|
815
935
|
readonly placeholder: (props: PlaceholderProps) => ReactNode;
|
|
816
936
|
readonly run: () => void;
|
|
@@ -823,6 +943,7 @@ function Mount({
|
|
|
823
943
|
frame,
|
|
824
944
|
page,
|
|
825
945
|
running,
|
|
946
|
+
findFor,
|
|
826
947
|
initialHeightPx,
|
|
827
948
|
placeholder,
|
|
828
949
|
run,
|
|
@@ -919,6 +1040,12 @@ function Mount({
|
|
|
919
1040
|
case "annotation":
|
|
920
1041
|
frame.onAnnotation?.(detail as DisplayEvents["annotation"]);
|
|
921
1042
|
return;
|
|
1043
|
+
case "findRequested":
|
|
1044
|
+
frame.onFindRequested?.();
|
|
1045
|
+
return;
|
|
1046
|
+
case "findUpdated":
|
|
1047
|
+
frame.onFindUpdated?.(detail as DisplayEvents["findUpdated"]);
|
|
1048
|
+
return;
|
|
922
1049
|
}
|
|
923
1050
|
},
|
|
924
1051
|
);
|
|
@@ -1045,6 +1172,8 @@ function Mount({
|
|
|
1045
1172
|
"focusTaken",
|
|
1046
1173
|
"outcome",
|
|
1047
1174
|
"annotation",
|
|
1175
|
+
"findRequested",
|
|
1176
|
+
"findUpdated",
|
|
1048
1177
|
"contentError",
|
|
1049
1178
|
"hostError",
|
|
1050
1179
|
];
|
|
@@ -1064,6 +1193,22 @@ function Mount({
|
|
|
1064
1193
|
following.current = wanted;
|
|
1065
1194
|
}, first);
|
|
1066
1195
|
}
|
|
1196
|
+
// Find (P131): the shortcut is the host's where it listens for it; the handle's query, found
|
|
1197
|
+
// again in this display where it shows what the query was asked of (its numbers told as an
|
|
1198
|
+
// update: nobody awaits them), else forgotten: another page is never searched with it.
|
|
1199
|
+
if (first.onFindRequested !== undefined) {
|
|
1200
|
+
display.find.takeShortcut(true);
|
|
1201
|
+
}
|
|
1202
|
+
const shownQuery = findFor(findScopeOf(first));
|
|
1203
|
+
if (shownQuery !== null) {
|
|
1204
|
+
void display.find
|
|
1205
|
+
.query(shownQuery.query, { caseSensitive: shownQuery.caseSensitive })
|
|
1206
|
+
.then((result) => {
|
|
1207
|
+
if (result !== "unsupported" && findFor(findScopeOf(latest())) === shownQuery) {
|
|
1208
|
+
latest().onFindUpdated?.(result);
|
|
1209
|
+
}
|
|
1210
|
+
});
|
|
1211
|
+
}
|
|
1067
1212
|
if (first.content !== undefined) {
|
|
1068
1213
|
display.setContent(first.content, { partial: first.partial === true });
|
|
1069
1214
|
}
|
|
@@ -1095,13 +1240,17 @@ function Mount({
|
|
|
1095
1240
|
locate,
|
|
1096
1241
|
nonce,
|
|
1097
1242
|
running,
|
|
1243
|
+
findFor,
|
|
1098
1244
|
]);
|
|
1099
1245
|
|
|
1100
1246
|
useEffect(() => {
|
|
1101
1247
|
if (content !== undefined) {
|
|
1102
1248
|
handle.current?.setContent(content, { partial: partial === true });
|
|
1103
1249
|
}
|
|
1104
|
-
|
|
1250
|
+
// Other content: the handle's query was the last one's, forgotten (the display forgot it too,
|
|
1251
|
+
// P131).
|
|
1252
|
+
findFor(findScopeOf(latest()));
|
|
1253
|
+
}, [content, partial, findFor]);
|
|
1105
1254
|
// Annotations follow their props (a new display gets them all when it is made, above).
|
|
1106
1255
|
const annotates = config.capabilities.annotate !== undefined;
|
|
1107
1256
|
const { annotating } = frame;
|
|
@@ -1170,6 +1319,16 @@ function Mount({
|
|
|
1170
1319
|
attempt(() => display.annotations.focus(id), latest());
|
|
1171
1320
|
}
|
|
1172
1321
|
}, [annotates, focusToken]);
|
|
1322
|
+
// The frame's shortcut is the host's while it listens for it (P131).
|
|
1323
|
+
const takesFind = frame.onFindRequested !== undefined;
|
|
1324
|
+
const [mountTakesFind] = useState(takesFind);
|
|
1325
|
+
const findFlipped = useRef(false);
|
|
1326
|
+
useEffect(() => {
|
|
1327
|
+
if (findFlipped.current || takesFind !== mountTakesFind) {
|
|
1328
|
+
findFlipped.current = true;
|
|
1329
|
+
handle.current?.find.takeShortcut(takesFind);
|
|
1330
|
+
}
|
|
1331
|
+
}, [takesFind, mountTakesFind]);
|
|
1173
1332
|
// A flip or a restyle after the display was made: its first scheme and values went with it.
|
|
1174
1333
|
const [mountScheme] = useState(scheme);
|
|
1175
1334
|
const flipped = useRef(false);
|