@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.
- package/CHANGELOG.md +74 -0
- package/dist/bridge/bridge.d.ts +6 -0
- package/dist/bridge/bridge.js +5 -0
- package/dist/check/files.js +2 -0
- package/dist/check/lint.js +82 -3
- package/dist/check/page-source.js +1 -1
- package/dist/compile/policy.d.ts +17 -6
- package/dist/compile/policy.js +22 -7
- package/dist/config/capabilities.d.ts +16 -2
- package/dist/config/capabilities.js +8 -0
- package/dist/config/schema.d.ts +13 -0
- package/dist/config/validate.js +15 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/kit.d.ts +5 -0
- package/dist/conformance/kit.js +21 -0
- package/dist/conformance/limits.js +10 -5
- package/dist/conformance/probes.js +139 -28
- package/dist/conformance/served.js +25 -4
- 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/guide/limits.js +8 -1
- package/dist/host/create-host.js +249 -4
- package/dist/host/pass-on.js +3 -2
- package/dist/host/types.d.ts +51 -0
- package/dist/index.d.ts +4 -2
- package/dist/index.js +4 -1
- package/dist/presets/presets.d.ts +6 -0
- package/dist/presets/presets.js +6 -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/server/files.js +4 -3
- package/dist/server/server.js +4 -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/plan.d.ts +5 -0
- package/dist/shell/plan.js +2 -0
- package/dist/shell/runtime.d.ts +30 -1
- package/dist/shell/runtime.js +789 -105
- package/dist/shell/text.d.ts +17 -0
- package/dist/shell/text.js +140 -0
- package/docs/ADOPTING.md +103 -0
- package/docs/ARCHITECTURE.md +10 -3
- package/docs/DECISIONS.md +513 -1
- package/docs/DESIGN.md +40 -4
- package/docs/THREAT_MODEL.md +75 -6
- package/docs/insertion-entry-points.md +112 -0
- package/package.json +1 -1
- package/src/bridge/bridge.ts +7 -0
- package/src/check/files.ts +2 -0
- package/src/check/lint.ts +97 -8
- package/src/compile/policy.ts +23 -6
- package/src/config/capabilities.ts +13 -1
- package/src/config/schema.ts +13 -0
- package/src/config/validate.ts +16 -0
- package/src/conformance/kit.ts +22 -0
- package/src/conformance/limits.ts +10 -5
- package/src/conformance/probes.ts +149 -28
- package/src/conformance/served.ts +24 -4
- package/src/find/types.ts +86 -0
- package/src/find/validate.ts +101 -0
- package/src/guide/guide.ts +3 -1
- package/src/guide/limits.ts +9 -1
- package/src/host/create-host.ts +267 -4
- package/src/host/pass-on.ts +3 -2
- package/src/host/types.ts +52 -0
- package/src/index.ts +13 -0
- package/src/presets/presets.ts +15 -0
- package/src/react/frame.tsx +160 -1
- package/src/react/view.tsx +3 -0
- package/src/runtime/contract.ts +1 -1
- package/src/server/files.ts +8 -2
- package/src/server/server.ts +4 -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/plan.ts +7 -0
- package/src/shell/runtime.ts +792 -105
- package/src/shell/text.ts +140 -0
package/dist/host/create-host.js
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import { ANNOTATE_METHODS, } from "../annotate/types.js";
|
|
2
2
|
import { annotateMode, checkMarks, clampRect, hasMarker, parseReport, } from "../annotate/validate.js";
|
|
3
|
+
import { FIND_LIMITS, FIND_METHODS } from "../find/types.js";
|
|
4
|
+
import { blankQuery, checkFindQuery, parseFindReport, parseFindResult } from "../find/validate.js";
|
|
3
5
|
import { createBridge, onceConsent, } from "../bridge/bridge.js";
|
|
4
6
|
import { compile } from "../compile/compile.js";
|
|
5
7
|
import { servesFiles } from "../files/paths.js";
|
|
@@ -44,6 +46,11 @@ const REPORTS = {
|
|
|
44
46
|
[ANNOTATE_METHODS.activated]: "activated",
|
|
45
47
|
[ANNOTATE_METHODS.tracked]: "tracked",
|
|
46
48
|
};
|
|
49
|
+
/** What the frame says of find in page unasked (P131), by method. */
|
|
50
|
+
const FIND_REPORTS = {
|
|
51
|
+
[FIND_METHODS.requested]: "requested",
|
|
52
|
+
[FIND_METHODS.updated]: "updated",
|
|
53
|
+
};
|
|
47
54
|
/** The most `tracked` reports a second the host takes (P112): one per animation frame at 60 Hz. */
|
|
48
55
|
export const TRACKED_PER_SECOND = 60;
|
|
49
56
|
const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
|
|
@@ -160,6 +167,14 @@ export function createHost(config, options = {}) {
|
|
|
160
167
|
// The mark the host follows (P112), and when it took each `tracked` in the last second.
|
|
161
168
|
let tracking = null;
|
|
162
169
|
const trackedTimes = [];
|
|
170
|
+
// Find in page (P131): the query shown (for the content it was asked of only: a new run or
|
|
171
|
+
// other content forgets it), whether the host takes the shortcut (kept for every frame the
|
|
172
|
+
// display runs), and the queries asked and not yet answered.
|
|
173
|
+
const finds = config.capabilities.find !== undefined;
|
|
174
|
+
let findShown = null;
|
|
175
|
+
let takesShortcut = false;
|
|
176
|
+
let nextFind = 1;
|
|
177
|
+
const findsAsked = new Map();
|
|
163
178
|
let handshaken = false;
|
|
164
179
|
let storageTold = false;
|
|
165
180
|
const toFrame = (method, params) => {
|
|
@@ -167,6 +182,86 @@ export function createHost(config, options = {}) {
|
|
|
167
182
|
surface.transport.send({ jsonrpc: "2.0", method, params });
|
|
168
183
|
}
|
|
169
184
|
};
|
|
185
|
+
/** A query asked of the frame running now (once it finished its handshake). */
|
|
186
|
+
const sendFind = (id, params) => {
|
|
187
|
+
if (handshaken && surface !== null) {
|
|
188
|
+
surface.transport.send({ jsonrpc: "2.0", id, method: FIND_METHODS.query, params });
|
|
189
|
+
}
|
|
190
|
+
};
|
|
191
|
+
/** Answers a query asked, once; a later answer for it is dropped. */
|
|
192
|
+
const settleFind = (id, result) => {
|
|
193
|
+
const asked = findsAsked.get(id);
|
|
194
|
+
if (asked !== undefined) {
|
|
195
|
+
findsAsked.delete(id);
|
|
196
|
+
clearTimeout(asked.timer);
|
|
197
|
+
asked.resolve(result);
|
|
198
|
+
}
|
|
199
|
+
};
|
|
200
|
+
/**
|
|
201
|
+
* Asks the frame a query: at once where one finished its handshake, else when one does
|
|
202
|
+
* (its load's time and the answer's). No answer in time, an error (an older shell's "isn't
|
|
203
|
+
* offered here"), or one malformed: `"unsupported"`.
|
|
204
|
+
*/
|
|
205
|
+
const askFind = (params) => new Promise((resolve) => {
|
|
206
|
+
const id = `porthole-find-${nextFind++}`;
|
|
207
|
+
const wait = handshaken ? FIND_LIMITS.timeoutMs : timeoutMs + FIND_LIMITS.timeoutMs;
|
|
208
|
+
findsAsked.set(id, {
|
|
209
|
+
params,
|
|
210
|
+
resolve,
|
|
211
|
+
timer: setTimeout(() => settleFind(id, "unsupported"), wait),
|
|
212
|
+
});
|
|
213
|
+
sendFind(id, params);
|
|
214
|
+
});
|
|
215
|
+
/**
|
|
216
|
+
* A new frame's find (after its handshake): the shortcut, and the latest of the queries
|
|
217
|
+
* asked while it loaded (those it superseded answered `"unsupported"`, never sent). A query
|
|
218
|
+
* cleared since it was asked is answered as nothing found, unasked. The query shown before
|
|
219
|
+
* this run is never given again: a run's frame may show other content (forgetFind).
|
|
220
|
+
*/
|
|
221
|
+
const giveFind = () => {
|
|
222
|
+
if (!finds) {
|
|
223
|
+
return;
|
|
224
|
+
}
|
|
225
|
+
if (takesShortcut) {
|
|
226
|
+
toFrame(FIND_METHODS.handled, { handled: true });
|
|
227
|
+
}
|
|
228
|
+
if (findShown === null) {
|
|
229
|
+
for (const id of findsAsked.keys()) {
|
|
230
|
+
settleFind(id, { total: 0, active: 0 });
|
|
231
|
+
}
|
|
232
|
+
return;
|
|
233
|
+
}
|
|
234
|
+
const waiting = [...findsAsked];
|
|
235
|
+
for (const [id] of waiting.slice(0, -1)) {
|
|
236
|
+
settleFind(id, "unsupported");
|
|
237
|
+
}
|
|
238
|
+
const last = waiting.at(-1);
|
|
239
|
+
if (last !== undefined) {
|
|
240
|
+
const [id, asked] = last;
|
|
241
|
+
clearTimeout(asked.timer);
|
|
242
|
+
asked.timer = setTimeout(() => settleFind(id, "unsupported"), FIND_LIMITS.timeoutMs);
|
|
243
|
+
sendFind(id, asked.params);
|
|
244
|
+
}
|
|
245
|
+
};
|
|
246
|
+
/**
|
|
247
|
+
* The content the query was asked of is gone (P131): a new run (a reload, a restart after
|
|
248
|
+
* the content navigated away, a new location) or other content. The query is forgotten and
|
|
249
|
+
* what waits is answered `"unsupported"`, so a new page is never searched with the last
|
|
250
|
+
* one's query unless the host asks it again; `clearFrame` also clears the frame running now.
|
|
251
|
+
*/
|
|
252
|
+
const forgetFind = (clearFrame) => {
|
|
253
|
+
if (!finds) {
|
|
254
|
+
return;
|
|
255
|
+
}
|
|
256
|
+
const had = findShown !== null || findsAsked.size > 0;
|
|
257
|
+
findShown = null;
|
|
258
|
+
for (const id of findsAsked.keys()) {
|
|
259
|
+
settleFind(id, "unsupported");
|
|
260
|
+
}
|
|
261
|
+
if (clearFrame && had) {
|
|
262
|
+
toFrame(FIND_METHODS.clear, {});
|
|
263
|
+
}
|
|
264
|
+
};
|
|
170
265
|
const giveAnnotations = () => {
|
|
171
266
|
if (marks.length > 0) {
|
|
172
267
|
toFrame(ANNOTATE_METHODS.show, {
|
|
@@ -333,6 +428,94 @@ export function createHost(config, options = {}) {
|
|
|
333
428
|
}
|
|
334
429
|
void through.call("annotate", withinFrame(report));
|
|
335
430
|
};
|
|
431
|
+
/**
|
|
432
|
+
* What the frame says of find (P131): an answer to a query asked (its own id only, checked,
|
|
433
|
+
* its box clamped to the frame), or a report unasked, taken only while the host asked for it
|
|
434
|
+
* (the shortcut while the host takes it and the page's focus is in the frame; a changed count
|
|
435
|
+
* while a query is shown), then through the bridge's gates.
|
|
436
|
+
*/
|
|
437
|
+
const onFind = (raw, through, focused) => {
|
|
438
|
+
if (!isRecord(raw) || raw.jsonrpc !== "2.0") {
|
|
439
|
+
return;
|
|
440
|
+
}
|
|
441
|
+
if (typeof raw.method !== "string") {
|
|
442
|
+
// Its own entries only: an id the host never asked is no answer.
|
|
443
|
+
const id = raw.id;
|
|
444
|
+
if (typeof id !== "string" || !findsAsked.has(id)) {
|
|
445
|
+
return;
|
|
446
|
+
}
|
|
447
|
+
const result = "error" in raw || !("result" in raw) ? null : parseFindResult(raw.result);
|
|
448
|
+
settleFind(id, result === null
|
|
449
|
+
? "unsupported"
|
|
450
|
+
: result.rect === undefined
|
|
451
|
+
? result
|
|
452
|
+
: { ...result, rect: clampRect(result.rect, frameViewport()) });
|
|
453
|
+
return;
|
|
454
|
+
}
|
|
455
|
+
if ("id" in raw) {
|
|
456
|
+
return;
|
|
457
|
+
}
|
|
458
|
+
const type = Object.hasOwn(FIND_REPORTS, raw.method) ? FIND_REPORTS[raw.method] : undefined;
|
|
459
|
+
if (type === undefined) {
|
|
460
|
+
return;
|
|
461
|
+
}
|
|
462
|
+
const report = parseFindReport({ ...(isRecord(raw.params) ? raw.params : {}), type });
|
|
463
|
+
if (report === null) {
|
|
464
|
+
void through.call("find", null);
|
|
465
|
+
return;
|
|
466
|
+
}
|
|
467
|
+
if (report.type === "requested") {
|
|
468
|
+
// The person's key in the frame: the page's focus is there (where the platform can tell),
|
|
469
|
+
// so a page can't bring the host's find bar up while the person types beside it.
|
|
470
|
+
let inFrame;
|
|
471
|
+
try {
|
|
472
|
+
inFrame = focused();
|
|
473
|
+
}
|
|
474
|
+
catch {
|
|
475
|
+
inFrame = false;
|
|
476
|
+
}
|
|
477
|
+
if (!takesShortcut || inFrame === false) {
|
|
478
|
+
return;
|
|
479
|
+
}
|
|
480
|
+
}
|
|
481
|
+
else if (findShown === null) {
|
|
482
|
+
return;
|
|
483
|
+
}
|
|
484
|
+
void through.call("find", report);
|
|
485
|
+
};
|
|
486
|
+
const find = {
|
|
487
|
+
query(query, given) {
|
|
488
|
+
if (!finds) {
|
|
489
|
+
return Promise.resolve("unsupported");
|
|
490
|
+
}
|
|
491
|
+
let checked;
|
|
492
|
+
try {
|
|
493
|
+
checked = checkFindQuery(query, given);
|
|
494
|
+
}
|
|
495
|
+
catch (error) {
|
|
496
|
+
return Promise.reject(error);
|
|
497
|
+
}
|
|
498
|
+
if (blankQuery(checked.query)) {
|
|
499
|
+
findShown = null;
|
|
500
|
+
toFrame(FIND_METHODS.clear, {});
|
|
501
|
+
return Promise.resolve({ total: 0, active: 0 });
|
|
502
|
+
}
|
|
503
|
+
findShown = { query: checked.query, caseSensitive: checked.caseSensitive };
|
|
504
|
+
return askFind({ ...checked });
|
|
505
|
+
},
|
|
506
|
+
clear() {
|
|
507
|
+
if (finds) {
|
|
508
|
+
findShown = null;
|
|
509
|
+
toFrame(FIND_METHODS.clear, {});
|
|
510
|
+
}
|
|
511
|
+
},
|
|
512
|
+
takeShortcut(take) {
|
|
513
|
+
if (finds) {
|
|
514
|
+
takesShortcut = take;
|
|
515
|
+
toFrame(FIND_METHODS.handled, { handled: takesShortcut });
|
|
516
|
+
}
|
|
517
|
+
},
|
|
518
|
+
};
|
|
336
519
|
const needsAnnotate = (operation) => {
|
|
337
520
|
if (!annotates) {
|
|
338
521
|
throw new TypeError(`annotations.${operation}: the config doesn't declare annotate`);
|
|
@@ -420,16 +603,40 @@ export function createHost(config, options = {}) {
|
|
|
420
603
|
...options.hostContext?.(),
|
|
421
604
|
};
|
|
422
605
|
};
|
|
606
|
+
// A frame's size is taken at most once an animation frame after its run's first, and only
|
|
607
|
+
// when it changed (P127): `resize` has no gate, and each one would reflow the host's page and
|
|
608
|
+
// tell its listeners.
|
|
609
|
+
let sizeFrame = null;
|
|
610
|
+
let pendingSize = null;
|
|
611
|
+
let shownSize = null;
|
|
612
|
+
const applySize = () => {
|
|
613
|
+
sizeFrame = null;
|
|
614
|
+
const size = pendingSize;
|
|
615
|
+
pendingSize = null;
|
|
616
|
+
if (size === null ||
|
|
617
|
+
(shownSize !== null && size.height === shownSize.height && size.width === shownSize.width)) {
|
|
618
|
+
return;
|
|
619
|
+
}
|
|
620
|
+
shownSize = size;
|
|
621
|
+
height = size.height;
|
|
622
|
+
surface?.setHeight(size.height);
|
|
623
|
+
emit("resize", size);
|
|
624
|
+
};
|
|
423
625
|
const onBridge = (event) => {
|
|
424
626
|
switch (event.type) {
|
|
425
627
|
case "resize": {
|
|
426
628
|
const next = Math.min(config.limits.maxHeightPx, Math.max(config.limits.minHeightPx, Math.ceil(event.height)));
|
|
427
|
-
|
|
428
|
-
surface?.setHeight(next);
|
|
429
|
-
emit("resize", {
|
|
629
|
+
pendingSize = {
|
|
430
630
|
height: next,
|
|
431
631
|
...(event.width === undefined ? {} : { width: event.width }),
|
|
432
|
-
}
|
|
632
|
+
};
|
|
633
|
+
// A run's first size at once: until then its frame has no height of its own.
|
|
634
|
+
if (view === null || shownSize === null) {
|
|
635
|
+
applySize();
|
|
636
|
+
}
|
|
637
|
+
else if (sizeFrame === null) {
|
|
638
|
+
sizeFrame = view.requestAnimationFrame(applySize);
|
|
639
|
+
}
|
|
433
640
|
return;
|
|
434
641
|
}
|
|
435
642
|
case "navigationBlocked":
|
|
@@ -447,6 +654,15 @@ export function createHost(config, options = {}) {
|
|
|
447
654
|
case "annotation":
|
|
448
655
|
emit("annotation", event.report);
|
|
449
656
|
return;
|
|
657
|
+
case "find":
|
|
658
|
+
if (event.report.type === "requested") {
|
|
659
|
+
emit("findRequested", undefined);
|
|
660
|
+
}
|
|
661
|
+
else {
|
|
662
|
+
const { type: _type, ...result } = event.report;
|
|
663
|
+
emit("findUpdated", result);
|
|
664
|
+
}
|
|
665
|
+
return;
|
|
450
666
|
}
|
|
451
667
|
};
|
|
452
668
|
const closeDoor = () => {
|
|
@@ -465,6 +681,13 @@ export function createHost(config, options = {}) {
|
|
|
465
681
|
bridge?.close();
|
|
466
682
|
bridge = null;
|
|
467
683
|
handshaken = false;
|
|
684
|
+
// The next run's frame tells its own size, the same as this one's or not.
|
|
685
|
+
if (sizeFrame !== null) {
|
|
686
|
+
view?.cancelAnimationFrame(sizeFrame);
|
|
687
|
+
sizeFrame = null;
|
|
688
|
+
}
|
|
689
|
+
pendingSize = null;
|
|
690
|
+
shownSize = null;
|
|
468
691
|
abort?.abort();
|
|
469
692
|
abort = null;
|
|
470
693
|
outcomeWatch?.stop();
|
|
@@ -627,6 +850,9 @@ export function createHost(config, options = {}) {
|
|
|
627
850
|
if (annotates) {
|
|
628
851
|
created.transport.listen((raw) => onAnnotation(raw, opening));
|
|
629
852
|
}
|
|
853
|
+
if (finds) {
|
|
854
|
+
created.transport.listen((raw) => onFind(raw, opening, () => created.focused?.()));
|
|
855
|
+
}
|
|
630
856
|
// Whether the page used storage (P111): once per run, the page's word (a count, no more).
|
|
631
857
|
created.transport.listen((raw) => {
|
|
632
858
|
if (!storageTold &&
|
|
@@ -657,6 +883,7 @@ export function createHost(config, options = {}) {
|
|
|
657
883
|
if (!handshaken) {
|
|
658
884
|
handshaken = true;
|
|
659
885
|
giveAnnotations();
|
|
886
|
+
giveFind();
|
|
660
887
|
}
|
|
661
888
|
emit("initialized", undefined);
|
|
662
889
|
}
|
|
@@ -670,6 +897,8 @@ export function createHost(config, options = {}) {
|
|
|
670
897
|
};
|
|
671
898
|
const run = () => {
|
|
672
899
|
stop();
|
|
900
|
+
// Each run is a new frame, maybe of other content: it starts with no query (P131).
|
|
901
|
+
forgetFind(false);
|
|
673
902
|
if (destroyed) {
|
|
674
903
|
return;
|
|
675
904
|
}
|
|
@@ -750,6 +979,7 @@ export function createHost(config, options = {}) {
|
|
|
750
979
|
const controls = {
|
|
751
980
|
displayId: mount.displayId,
|
|
752
981
|
annotations,
|
|
982
|
+
find,
|
|
753
983
|
setTheme(next) {
|
|
754
984
|
if (themeless) {
|
|
755
985
|
return;
|
|
@@ -793,6 +1023,9 @@ export function createHost(config, options = {}) {
|
|
|
793
1023
|
destroyed = true;
|
|
794
1024
|
stop();
|
|
795
1025
|
listeners.clear();
|
|
1026
|
+
for (const id of findsAsked.keys()) {
|
|
1027
|
+
settleFind(id, "unsupported");
|
|
1028
|
+
}
|
|
796
1029
|
},
|
|
797
1030
|
};
|
|
798
1031
|
// The adapter's own operations (`setContent` for the shell adapter): forwarded to the frame
|
|
@@ -801,6 +1034,10 @@ export function createHost(config, options = {}) {
|
|
|
801
1034
|
get(target, key, receiver) {
|
|
802
1035
|
if (typeof key === "string" && !(key in target) && !BASE_KEYS.has(key)) {
|
|
803
1036
|
return (...args) => {
|
|
1037
|
+
// Other content (not the content so far, continued): the query was the last one's.
|
|
1038
|
+
if (key === "setContent" && !continues(replay.get(key)?.[0], args[0])) {
|
|
1039
|
+
forgetFind(true);
|
|
1040
|
+
}
|
|
804
1041
|
replay.delete(key);
|
|
805
1042
|
replay.set(key, args);
|
|
806
1043
|
const operation = connection?.[key];
|
|
@@ -815,6 +1052,14 @@ export function createHost(config, options = {}) {
|
|
|
815
1052
|
},
|
|
816
1053
|
};
|
|
817
1054
|
}
|
|
1055
|
+
/**
|
|
1056
|
+
* Whether `next` is the content `before` was, continued (P131): the same, or more of it (the next
|
|
1057
|
+
* part of a streamed page). Nothing given before: anything continues it.
|
|
1058
|
+
*/
|
|
1059
|
+
function continues(before, next) {
|
|
1060
|
+
return (before === undefined ||
|
|
1061
|
+
(typeof before === "string" && typeof next === "string" && next.startsWith(before)));
|
|
1062
|
+
}
|
|
818
1063
|
/** The host's nonce option, read now (`HostOptions.nonce`). */
|
|
819
1064
|
function nonceOf(nonce) {
|
|
820
1065
|
const value = typeof nonce === "function" ? nonce() : nonce;
|
package/dist/host/pass-on.js
CHANGED
|
@@ -10,8 +10,9 @@ const KINDS = ["connect", "script", "style", "img", "font", "media"];
|
|
|
10
10
|
* conversation and context (`sendPrompt`, `setModelContext`), and the host's data services, which
|
|
11
11
|
* may be someone else's (`callTool`, `readData`, `subscribeData`: their arguments are the page's).
|
|
12
12
|
* Not here: the person's own clipboard and disk (`copyText`, `downloadFile`), the host's own UI
|
|
13
|
-
* (`annotate`, `resize`, `comments`: the composer is the person's, under the host's
|
|
14
|
-
* what only reads (`user`). `reportError` is one where the config sends errors to the
|
|
13
|
+
* (`annotate`, `find`, `resize`, `comments`: the composer is the person's, under the host's
|
|
14
|
+
* duties), and what only reads (`user`). `reportError` is one where the config sends errors to the
|
|
15
|
+
* agent.
|
|
15
16
|
*/
|
|
16
17
|
const CARRIERS = [
|
|
17
18
|
"db",
|
package/dist/host/types.d.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 { Confirm, CapabilityHandlers, Consent, DataCache, Refusal, Show } from "../bridge/types.ts";
|
|
4
5
|
import type { CompiledConfig } from "../compile/compile.ts";
|
|
@@ -118,6 +119,8 @@ export type HostErrorKind =
|
|
|
118
119
|
| "mount"
|
|
119
120
|
/** An annotation call was refused (an invalid mark, an unknown id). */
|
|
120
121
|
| "annotations"
|
|
122
|
+
/** A find call was refused (a query too long, options that aren't these: P131). */
|
|
123
|
+
| "find"
|
|
121
124
|
/**
|
|
122
125
|
* A frame status (`porthole/notifications/frame-status`) the host didn't take, since it came
|
|
123
126
|
* from the frame's content, not from a page of Porthole's server (P124): never shown, never an
|
|
@@ -246,6 +249,52 @@ export interface DisplayEvents {
|
|
|
246
249
|
* content's word: UI hints, never permissions.
|
|
247
250
|
*/
|
|
248
251
|
readonly annotation: AnnotationReport;
|
|
252
|
+
/**
|
|
253
|
+
* The person pressed Cmd+F (Apple) or Ctrl+F (elsewhere) with the keyboard in the frame (`find`,
|
|
254
|
+
* P131): open the host's find bar. Only while the host takes the shortcut
|
|
255
|
+
* (`find.takeShortcut(true)`, which stops the browser's own find there) and the page's focus is
|
|
256
|
+
* in the frame (where the platform can tell). The content's word: it can say it without the key,
|
|
257
|
+
* or keep the key; open the bar, nothing more.
|
|
258
|
+
*/
|
|
259
|
+
readonly findRequested: undefined;
|
|
260
|
+
/**
|
|
261
|
+
* The matches of the query shown changed without the host asking (`find`, P131): the content
|
|
262
|
+
* changed (more of it, or the page's own changes). At most once a second, from an honest shell.
|
|
263
|
+
* The content's word: a find bar's numbers.
|
|
264
|
+
*/
|
|
265
|
+
readonly findUpdated: FindResult;
|
|
266
|
+
}
|
|
267
|
+
/**
|
|
268
|
+
* Find in page on a display whose config declares `find` (P131): the host draws the find bar,
|
|
269
|
+
* the frame finds and highlights. The query is posted into the frame, where the content can read
|
|
270
|
+
* it. Where the config doesn't declare `find`, `query` answers `"unsupported"` and the rest do
|
|
271
|
+
* nothing. The shortcut is kept and given to every frame the display runs. The query holds only for
|
|
272
|
+
* the content it was asked of: a new run (`reload()`, a restart after the content navigated away,
|
|
273
|
+
* a new location) or other content (`setContent` with content that doesn't continue what was
|
|
274
|
+
* given) forgets it and answers what waits `"unsupported"`, and nothing is found there until the
|
|
275
|
+
* host asks again: clear your find bar then.
|
|
276
|
+
*/
|
|
277
|
+
export interface FindControls {
|
|
278
|
+
/**
|
|
279
|
+
* Finds `query` in the content's text (case-insensitive by default, any spacing), highlights
|
|
280
|
+
* every match, makes one current (the first in view for a new query; the next or previous one
|
|
281
|
+
* with `direction`), scrolls it into view, and answers where they stand. An empty query (or
|
|
282
|
+
* only spaces) clears, and answers no matches. `"unsupported"` where the frame can't find: the
|
|
283
|
+
* config doesn't declare `find`, the frame's shell is older (it answered that it doesn't know
|
|
284
|
+
* the request), it failed, it didn't answer in `FIND_LIMITS.timeoutMs` once it ran, a later
|
|
285
|
+
* query superseded it before it ran (only the latest is searched: show the answer to your latest
|
|
286
|
+
* query only), or the content it was asked of is gone (a new run, other content). Rejects
|
|
287
|
+
* with a `TypeError` for a query longer than `FIND_LIMITS.query`, or options that aren't these.
|
|
288
|
+
*/
|
|
289
|
+
query(query: string, options?: FindOptions): Promise<FindResult | "unsupported">;
|
|
290
|
+
/** Removes the highlights and forgets the query (the find bar closed). */
|
|
291
|
+
clear(): void;
|
|
292
|
+
/**
|
|
293
|
+
* Whether the host draws its own find bar for this display (default no): while it does, Cmd+F
|
|
294
|
+
* or Ctrl+F in the frame doesn't open the browser's own find, and the display says
|
|
295
|
+
* `findRequested` instead. A page that handles the key itself keeps it.
|
|
296
|
+
*/
|
|
297
|
+
takeShortcut(take: boolean): void;
|
|
249
298
|
}
|
|
250
299
|
/**
|
|
251
300
|
* Annotations on a display whose config declares `annotate` (P053). The host's state is kept and
|
|
@@ -288,6 +337,8 @@ export interface DisplayControls {
|
|
|
288
337
|
on<E extends keyof DisplayEvents>(event: E, listener: (detail: DisplayEvents[E]) => void): () => void;
|
|
289
338
|
/** Annotations (`annotate`): throws on use where the config doesn't declare it. */
|
|
290
339
|
readonly annotations: AnnotationControls;
|
|
340
|
+
/** Find in page (`find`, P131): `"unsupported"` where the config doesn't declare it. */
|
|
341
|
+
readonly find: FindControls;
|
|
291
342
|
/** Runs the content again from the start, in a new frame. */
|
|
292
343
|
reload(): void;
|
|
293
344
|
/**
|
package/dist/index.d.ts
CHANGED
|
@@ -23,7 +23,7 @@ export { LIBRARY_PATH, VENDORED_LIBRARIES, libraryPath, licensePath, type Vendor
|
|
|
23
23
|
export { checkFileSet, DEFAULT_ENTRY, DEFAULT_MAX_FILE_BYTES, DEFAULT_MAX_FILES, DEFAULT_MAX_VERSION_BYTES, fileLimits, filePathProblem, lookupFile, requestFilePath, servesFiles, type FileLimits, type FileLookup, type FileSetProblem, } from "./files/paths.ts";
|
|
24
24
|
export { fileTypeOf, KNOWN_EXTENSIONS, UNKNOWN_TYPE, type FileRole, type FileType, } from "./files/types.ts";
|
|
25
25
|
export { compile, type CompiledConfig } from "./compile/compile.ts";
|
|
26
|
-
export { allEgressOrigins, anyHttps, declaredCapabilities, effectiveGates, egressOrigins, embedderCsp, embedderFrameSourcesOf, ASSET_CODE_DIRECTIVES, ASSET_DIRECTIVES, assetCodeRuns, assetCspDirectives, FILE_SET_DIRECTIVES, fileSetCspDirectives, INERT_FILE_CSP, type CspDirective, type EgressKind, } from "./compile/policy.ts";
|
|
26
|
+
export { allEgressOrigins, anyHttps, declaredCapabilities, effectiveGates, egressOrigins, embedderCsp, embedderFrameSourcesOf, ASSET_CODE_DIRECTIVES, ASSET_DIRECTIVES, assetCodeRuns, assetCspDirectives, FILE_SET_DIRECTIVES, fileSetCspDirectives, fileSetDirectives, INERT_FILE_CSP, type CspDirective, type EgressKind, } from "./compile/policy.ts";
|
|
27
27
|
export { shellPlan, type ShellPlan } from "./shell/plan.ts";
|
|
28
28
|
export type { ShellDocumentOptions } from "./shell/document.ts";
|
|
29
29
|
export { generateGuide, generateToolDescription, type BuiltInTopic, type GuideTopic, } from "./guide/guide.ts";
|
|
@@ -46,6 +46,8 @@ export { lintFiles, type FileContents, type FileFinding } from "./check/files.ts
|
|
|
46
46
|
export { admitContent, admitFiles, type AdmitFilesResult, answerGuide, checkTool, guideChanges, guideTool, guideTopics, showTool, type AdmitResult, type JsonSchema, type ToolDefinition, } from "./check/tools.ts";
|
|
47
47
|
export { writeClipboard } from "./host/clipboard.ts";
|
|
48
48
|
export { httpLocator, LocateError, servedOrOpaque, type HttpLocatorOptions, type ServedMeta, } from "./host/locator.ts";
|
|
49
|
-
export type { AnnotationControls, DisplayControls, DisplayEvents, FrameBlock, FrameOutcome, DisplayHandle, HostOptions, MountOptions, PortholeHost, } from "./host/types.ts";
|
|
49
|
+
export type { AnnotationControls, FindControls, DisplayControls, DisplayEvents, FrameBlock, FrameOutcome, DisplayHandle, HostOptions, MountOptions, PortholeHost, } from "./host/types.ts";
|
|
50
50
|
export { ANNOTATE_METHODS, ANNOTATION_LIMITS, type AnchorResult, type AnchorState, type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type AnnotationMarkKind, type AnnotationRect, type AnnotationReport, type AnnotationSelector, type CssSelector, type TextPositionSelector, type TextQuoteSelector, } from "./annotate/types.ts";
|
|
51
51
|
export { parseAnchor, parseRect, parseReport } from "./annotate/validate.ts";
|
|
52
|
+
export { FIND_LIMITS, FIND_METHODS, type FindDirection, type FindOptions, type FindReport, type FindResult, } from "./find/types.ts";
|
|
53
|
+
export { parseFindReport, parseFindResult } from "./find/validate.ts";
|
package/dist/index.js
CHANGED
|
@@ -28,7 +28,7 @@ export { checkFileSet, DEFAULT_ENTRY, DEFAULT_MAX_FILE_BYTES, DEFAULT_MAX_FILES,
|
|
|
28
28
|
export { fileTypeOf, KNOWN_EXTENSIONS, UNKNOWN_TYPE, } from "./files/types.js";
|
|
29
29
|
// The compiler.
|
|
30
30
|
export { compile } from "./compile/compile.js";
|
|
31
|
-
export { allEgressOrigins, anyHttps, declaredCapabilities, effectiveGates, egressOrigins, embedderCsp, embedderFrameSourcesOf, ASSET_CODE_DIRECTIVES, ASSET_DIRECTIVES, assetCodeRuns, assetCspDirectives, FILE_SET_DIRECTIVES, fileSetCspDirectives, INERT_FILE_CSP, } from "./compile/policy.js";
|
|
31
|
+
export { allEgressOrigins, anyHttps, declaredCapabilities, effectiveGates, egressOrigins, embedderCsp, embedderFrameSourcesOf, ASSET_CODE_DIRECTIVES, ASSET_DIRECTIVES, assetCodeRuns, assetCspDirectives, FILE_SET_DIRECTIVES, fileSetCspDirectives, fileSetDirectives, INERT_FILE_CSP, } from "./compile/policy.js";
|
|
32
32
|
export { shellPlan } from "./shell/plan.js";
|
|
33
33
|
export { generateGuide, generateToolDescription, } from "./guide/guide.js";
|
|
34
34
|
export { GUIDE_EXAMPLES } from "./guide/examples.js";
|
|
@@ -53,3 +53,6 @@ export { httpLocator, LocateError, servedOrOpaque, } from "./host/locator.js";
|
|
|
53
53
|
// Annotations (P053): anchors, what a frame reports, and the host's checks on both.
|
|
54
54
|
export { ANNOTATE_METHODS, ANNOTATION_LIMITS, } from "./annotate/types.js";
|
|
55
55
|
export { parseAnchor, parseRect, parseReport } from "./annotate/validate.js";
|
|
56
|
+
// Find in page (P131): the host's find bar, the frame's matches, and the host's checks on both.
|
|
57
|
+
export { FIND_LIMITS, FIND_METHODS, } from "./find/types.js";
|
|
58
|
+
export { parseFindReport, parseFindResult } from "./find/validate.js";
|
|
@@ -42,6 +42,12 @@ export interface PresetOptions {
|
|
|
42
42
|
readonly runtime?: RuntimeVersion;
|
|
43
43
|
/** Domain isolation, artifact pages: the page in an opaque child of Porthole's shell (P111). */
|
|
44
44
|
readonly nested?: true;
|
|
45
|
+
/**
|
|
46
|
+
* `own` (P128): an `<iframe>` of one of the page's own files (a relative `src`) or a `srcdoc`
|
|
47
|
+
* one loads and runs, in a realm of its own that the shell's hardening doesn't reach
|
|
48
|
+
* (`PortholeConfig.nestedFrames`). `none` (default): every nested frame is removed.
|
|
49
|
+
*/
|
|
50
|
+
readonly nestedFrames?: "none" | "own";
|
|
45
51
|
}
|
|
46
52
|
/** What a live widget may say about a capability (P103): anything but origins of its own. */
|
|
47
53
|
export type LiveCapabilityConfig = Omit<CapabilityConfig, "connect" | "resource">;
|
package/dist/presets/presets.js
CHANGED
|
@@ -142,6 +142,7 @@ function build(mode, defaults, options) {
|
|
|
142
142
|
...(options.errors === undefined ? {} : { errors: options.errors }),
|
|
143
143
|
...(options.runtime === undefined ? {} : { runtime: options.runtime }),
|
|
144
144
|
...(options.nested === undefined ? {} : { nested: options.nested }),
|
|
145
|
+
...(options.nestedFrames === undefined ? {} : { nestedFrames: options.nestedFrames }),
|
|
145
146
|
});
|
|
146
147
|
}
|
|
147
148
|
export const presets = {
|
|
@@ -164,6 +165,11 @@ export const presets = {
|
|
|
164
165
|
if (options.egress !== undefined) {
|
|
165
166
|
throw new ConfigError("options.egress", "a live widget has no network of its own: its egress stays closed (P079)");
|
|
166
167
|
}
|
|
168
|
+
// A child frame is a realm the shell's WebRTC removal never reached (P128): a network of its
|
|
169
|
+
// own, which a live widget never has.
|
|
170
|
+
if (options.nestedFrames === "own") {
|
|
171
|
+
throw new ConfigError("options.nestedFrames", "a live widget has no network of its own: its frames stay removed (P079, P128)");
|
|
172
|
+
}
|
|
167
173
|
// A capability's own origins join the CSP as egress does (P103): none for a live widget.
|
|
168
174
|
for (const [name, value] of Object.entries(options.capabilities ?? {})) {
|
|
169
175
|
for (const field of ["connect", "resource"]) {
|
package/dist/react/frame.d.ts
CHANGED
|
@@ -2,6 +2,7 @@ import type { PageDeclaration } from "../runtime/declaration.ts";
|
|
|
2
2
|
import type { ViewerInfo } from "../runtime/levels.ts";
|
|
3
3
|
import { type CSSProperties, type ReactElement, type ReactNode, type Ref } from "react";
|
|
4
4
|
import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
|
|
5
|
+
import type { FindOptions, FindResult } from "../find/types.ts";
|
|
5
6
|
import type { CapabilityHandler, CapabilityHandlers, Confirm, ConfirmRequest, Consent, DataCache, Refusal, Show } from "../bridge/types.ts";
|
|
6
7
|
import { Refused, type RefusalReason } from "../bridge/refusal.ts";
|
|
7
8
|
import type { CapabilityName } from "../config/capabilities.ts";
|
|
@@ -153,7 +154,37 @@ export interface PortholeFrameHandle {
|
|
|
153
154
|
* `"annotations"` (the core's call throws; this never does).
|
|
154
155
|
*/
|
|
155
156
|
clearSelection(): void;
|
|
157
|
+
/**
|
|
158
|
+
* Finds `query` in the frame and highlights it (`find.query`, P131): where the matches stand,
|
|
159
|
+
* or `"unsupported"` (a config without `find`, an older shell, no answer in time, a later
|
|
160
|
+
* query superseded it, or no display running now). The query is kept for the content the frame
|
|
161
|
+
* shows now only: a display made later for the same content (the frame neared the screen again)
|
|
162
|
+
* finds it again and tells `onFindUpdated`; other content (another `content` that doesn't
|
|
163
|
+
* continue it, `document`, `instance`, `config`, `declaration` or `viewer`, a new `generation`)
|
|
164
|
+
* forgets it, and nothing is found there until `find` is called again (clear your find bar
|
|
165
|
+
* then). A query too long, or options that aren't these: `onHostError`, kind `"find"`, and
|
|
166
|
+
* `"unsupported"` (never a rejection). An empty query clears.
|
|
167
|
+
*/
|
|
168
|
+
find(query: string, options?: FindOptions): Promise<FindResult | "unsupported">;
|
|
169
|
+
/** Removes the highlights and forgets the query (`find.clear`): the host's find bar closed. */
|
|
170
|
+
clearFind(): void;
|
|
171
|
+
}
|
|
172
|
+
/** What a frame shows, as its handle's query holds it (P131). */
|
|
173
|
+
export interface FindScope {
|
|
174
|
+
/** The config, instance (its version too), declaration, viewer and generation, by value. */
|
|
175
|
+
readonly shows: string;
|
|
176
|
+
readonly document: string | undefined;
|
|
177
|
+
readonly content: string | undefined;
|
|
156
178
|
}
|
|
179
|
+
/** What the frame shows with these props, for its handle's query (P131). */
|
|
180
|
+
export declare function findScopeOf(props: PortholeFrameProps): FindScope;
|
|
181
|
+
/**
|
|
182
|
+
* Whether a frame showing `now` still shows what a query was asked of (`asked`, P131): the same
|
|
183
|
+
* config, instance, declaration, viewer, generation and document, and the content as it was or
|
|
184
|
+
* continued (more of a streamed page; asked before any content: whatever came). Otherwise the
|
|
185
|
+
* query was the last page's, and a new one is never searched with it.
|
|
186
|
+
*/
|
|
187
|
+
export declare function sameFindScope(asked: FindScope, now: FindScope): boolean;
|
|
157
188
|
export interface PortholeFrameProps {
|
|
158
189
|
/** A preset's config. Keep it stable (module scope or memoized): a new one remounts the frame. */
|
|
159
190
|
readonly config: PortholeConfig;
|
|
@@ -305,6 +336,18 @@ export interface PortholeFrameProps {
|
|
|
305
336
|
* (`activated`). The content's word: UI hints, never permissions.
|
|
306
337
|
*/
|
|
307
338
|
readonly onAnnotation?: (report: AnnotationReport) => void;
|
|
339
|
+
/**
|
|
340
|
+
* The person pressed Cmd+F or Ctrl+F in the frame (`findRequested`, P131): open the host's find
|
|
341
|
+
* bar. Given, it makes the frame's shortcut the host's (`find.takeShortcut(true)`): the
|
|
342
|
+
* browser's own find doesn't open there. The content's word (it can say it, or keep the key):
|
|
343
|
+
* open the bar, nothing more. Where the config declares `find`.
|
|
344
|
+
*/
|
|
345
|
+
readonly onFindRequested?: () => void;
|
|
346
|
+
/**
|
|
347
|
+
* The matches of the query shown changed without the host asking (`findUpdated`, P131): the
|
|
348
|
+
* content changed, or a display made later found the handle's query again.
|
|
349
|
+
*/
|
|
350
|
+
readonly onFindUpdated?: (result: FindResult) => void;
|
|
308
351
|
/** Draws the placeholder instead of the default one. */
|
|
309
352
|
readonly renderPlaceholder?: (props: PlaceholderProps) => ReactNode;
|
|
310
353
|
readonly className?: string;
|