@botiverse/porthole 0.12.0 → 0.14.0
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/dist/annotate/types.d.ts +32 -3
- package/dist/annotate/types.js +4 -0
- package/dist/annotate/validate.js +19 -2
- package/dist/bridge/bridge.d.ts +8 -1
- package/dist/bridge/bridge.js +7 -0
- package/dist/bridge/unseen.d.ts +8 -0
- package/dist/bridge/unseen.js +17 -0
- package/dist/check/files.js +14 -10
- package/dist/check/lint.js +1 -1
- package/dist/check/page-source.js +1 -1
- package/dist/check/scroll.d.ts +29 -13
- package/dist/check/scroll.js +74 -18
- package/dist/compile/policy.d.ts +7 -0
- package/dist/compile/policy.js +13 -1
- package/dist/config/capabilities.d.ts +16 -3
- package/dist/config/capabilities.js +1 -0
- package/dist/config/schema.d.ts +11 -0
- package/dist/config/validate.js +19 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/displays/displays.js +3 -1
- package/dist/guide/limits.js +1 -1
- package/dist/guide/runtime.js +1 -1
- package/dist/host/create-host.d.ts +2 -0
- package/dist/host/create-host.js +100 -3
- package/dist/host/pass-on.d.ts +15 -0
- package/dist/host/pass-on.js +65 -0
- package/dist/host/types.d.ts +37 -0
- package/dist/index.d.ts +5 -1
- package/dist/index.js +5 -1
- package/dist/isolation/types.d.ts +8 -0
- package/dist/isolation/types.js +8 -0
- package/dist/platform/focus-guard.d.ts +212 -0
- package/dist/platform/focus-guard.js +620 -0
- package/dist/platform/types.d.ts +25 -0
- package/dist/platform/web.js +80 -2
- package/dist/presets/presets.d.ts +2 -0
- package/dist/presets/presets.js +1 -0
- package/dist/react/frame.d.ts +8 -0
- package/dist/react/frame.js +4 -0
- package/dist/runtime/requests.js +34 -12
- package/dist/runtime/types.generated.js +1 -1
- package/dist/server/files.js +19 -3
- package/dist/server/index.d.ts +1 -0
- package/dist/server/index.js +4 -0
- package/dist/server/nested.d.ts +37 -0
- package/dist/server/nested.js +70 -0
- package/dist/server/server.js +57 -7
- package/dist/shell/annotate.d.ts +1 -1
- package/dist/shell/annotate.js +157 -7
- package/dist/shell/frame.d.ts +45 -0
- package/dist/shell/frame.js +250 -0
- package/dist/shell/plan.js +2 -1
- package/dist/shell/runtime.js +49 -14
- package/docs/ADOPTING.md +140 -7
- package/docs/ARCHITECTURE.md +23 -0
- package/docs/DECISIONS.md +564 -5
- package/docs/DESIGN.md +18 -2
- package/docs/THREAT_MODEL.md +192 -30
- package/package.json +1 -1
- package/src/annotate/types.ts +28 -3
- package/src/annotate/validate.ts +23 -2
- package/src/bridge/bridge.ts +17 -1
- package/src/bridge/unseen.ts +24 -0
- package/src/check/files.ts +14 -10
- package/src/check/lint.ts +1 -1
- package/src/check/scroll.ts +106 -38
- package/src/compile/policy.ts +14 -1
- package/src/config/capabilities.ts +16 -3
- package/src/config/schema.ts +11 -0
- package/src/config/validate.ts +23 -0
- package/src/displays/displays.ts +3 -1
- package/src/guide/limits.ts +1 -1
- package/src/guide/runtime.ts +1 -1
- package/src/host/create-host.ts +105 -4
- package/src/host/pass-on.ts +73 -0
- package/src/host/types.ts +33 -0
- package/src/index.ts +5 -1
- package/src/isolation/types.ts +12 -0
- package/src/platform/focus-guard.ts +815 -0
- package/src/platform/types.ts +24 -0
- package/src/platform/web.ts +96 -2
- package/src/presets/presets.ts +3 -0
- package/src/react/frame.tsx +10 -0
- package/src/runtime/requests.ts +36 -14
- package/src/runtime/types.generated.ts +1 -1
- package/src/server/files.ts +19 -3
- package/src/server/index.ts +10 -0
- package/src/server/nested.ts +86 -0
- package/src/server/server.ts +65 -6
- package/src/shell/annotate.ts +157 -7
- package/src/shell/frame.ts +268 -0
- package/src/shell/plan.ts +2 -1
- package/src/shell/runtime.ts +49 -14
- package/types/runtime/v1/comments.d.ts +8 -4
package/src/host/create-host.ts
CHANGED
|
@@ -26,9 +26,11 @@ import { isRefused } from "../bridge/refusal.ts";
|
|
|
26
26
|
import { capabilitySpec } from "../config/capabilities.ts";
|
|
27
27
|
import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
|
|
28
28
|
import { locateServed } from "./locate.ts";
|
|
29
|
+
import { mayPassOn } from "./pass-on.ts";
|
|
29
30
|
import { watchOutcome, type OutcomeWatch } from "./outcome.ts";
|
|
30
|
-
import type
|
|
31
|
+
import { STORAGE_USED_METHOD, type FrameSource } from "../isolation/types.ts";
|
|
31
32
|
import { webPlatform } from "../platform/web.ts";
|
|
33
|
+
import { TAKES } from "../platform/focus-guard.ts";
|
|
32
34
|
import type { Surface } from "../platform/types.ts";
|
|
33
35
|
import type { AdapterConnection, ProtocolAdapter, ShellConnection } from "../protocol/adapter.ts";
|
|
34
36
|
import {
|
|
@@ -65,8 +67,12 @@ const REPORTS: Readonly<Record<string, AnnotationReport["type"]>> = {
|
|
|
65
67
|
[ANNOTATE_METHODS.cancelled]: "cancelled",
|
|
66
68
|
[ANNOTATE_METHODS.anchored]: "anchored",
|
|
67
69
|
[ANNOTATE_METHODS.activated]: "activated",
|
|
70
|
+
[ANNOTATE_METHODS.tracked]: "tracked",
|
|
68
71
|
};
|
|
69
72
|
|
|
73
|
+
/** The most `tracked` reports a second the host takes (P112): one per animation frame at 60 Hz. */
|
|
74
|
+
export const TRACKED_PER_SECOND = 60;
|
|
75
|
+
|
|
70
76
|
const isRecord = (value: unknown): value is Record<string, unknown> =>
|
|
71
77
|
value !== null && typeof value === "object" && !Array.isArray(value);
|
|
72
78
|
const STANDARD = new Set(MCP_APPS_STYLE_VARIABLES);
|
|
@@ -94,6 +100,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
94
100
|
|
|
95
101
|
return {
|
|
96
102
|
compiled,
|
|
103
|
+
mayPassOn: (declaration) => mayPassOn(config, declaration),
|
|
97
104
|
mount(container: HTMLElement, mount: MountOptions): DisplayHandle<C> {
|
|
98
105
|
const handlers = { ...options.handlers, ...mount.handlers };
|
|
99
106
|
// A host whose consent is a Refused refuses every consent-gated call before its handler:
|
|
@@ -183,7 +190,11 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
183
190
|
let annotating: Required<AnnotateMode> | null = null;
|
|
184
191
|
let marks: AnnotationMark[] = [];
|
|
185
192
|
let activeMark: string | null = null;
|
|
193
|
+
// The mark the host follows (P112), and when it took each `tracked` in the last second.
|
|
194
|
+
let tracking: string | null = null;
|
|
195
|
+
const trackedTimes: number[] = [];
|
|
186
196
|
let handshaken = false;
|
|
197
|
+
let storageTold = false;
|
|
187
198
|
const toFrame = (method: string, params: Record<string, unknown>) => {
|
|
188
199
|
if (handshaken && surface !== null) {
|
|
189
200
|
surface.transport.send({ jsonrpc: "2.0", method, params });
|
|
@@ -199,6 +210,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
199
210
|
if (annotating !== null) {
|
|
200
211
|
toFrame(ANNOTATE_METHODS.start, { ...annotating });
|
|
201
212
|
}
|
|
213
|
+
if (tracking !== null) {
|
|
214
|
+
toFrame(ANNOTATE_METHODS.track, { id: tracking });
|
|
215
|
+
}
|
|
202
216
|
};
|
|
203
217
|
/**
|
|
204
218
|
* The frame's viewport as the platform tells it now; undefined where it can't (no
|
|
@@ -242,6 +256,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
242
256
|
switch (report.type) {
|
|
243
257
|
case "selected":
|
|
244
258
|
case "activated":
|
|
259
|
+
case "tracked":
|
|
245
260
|
return { ...report, rect: clampRect(report.rect, viewport) };
|
|
246
261
|
case "anchored":
|
|
247
262
|
return {
|
|
@@ -280,6 +295,25 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
280
295
|
void through.call("annotate", null);
|
|
281
296
|
return;
|
|
282
297
|
}
|
|
298
|
+
// The followed mark's box (P112): the mark the host follows and no other, while it is
|
|
299
|
+
// shown, at most 60 a second; past the bridge's rate for reports, which a card that follows
|
|
300
|
+
// its mark at every frame would spend at once.
|
|
301
|
+
if (report.type === "tracked") {
|
|
302
|
+
const { id } = report;
|
|
303
|
+
if (id !== tracking || !marks.some((mark) => mark.id === id)) {
|
|
304
|
+
return;
|
|
305
|
+
}
|
|
306
|
+
const at = Date.now();
|
|
307
|
+
while (trackedTimes.length > 0 && at - (trackedTimes[0] as number) >= 1_000) {
|
|
308
|
+
trackedTimes.shift();
|
|
309
|
+
}
|
|
310
|
+
if (trackedTimes.length >= TRACKED_PER_SECOND) {
|
|
311
|
+
return;
|
|
312
|
+
}
|
|
313
|
+
trackedTimes.push(at);
|
|
314
|
+
emit("annotation", withinFrame(report));
|
|
315
|
+
return;
|
|
316
|
+
}
|
|
283
317
|
switch (report.type) {
|
|
284
318
|
case "selected": {
|
|
285
319
|
const kind = report.anchor.kind;
|
|
@@ -289,7 +323,8 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
289
323
|
) {
|
|
290
324
|
return;
|
|
291
325
|
}
|
|
292
|
-
|
|
326
|
+
// A pick ends with it; holding a block (P112) lasts until the host stops it.
|
|
327
|
+
if (kind === "element" && annotating.elements === true) {
|
|
293
328
|
annotating = annotating.text ? { elements: false, text: true } : null;
|
|
294
329
|
}
|
|
295
330
|
break;
|
|
@@ -300,10 +335,14 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
300
335
|
}
|
|
301
336
|
break;
|
|
302
337
|
case "cancelled":
|
|
303
|
-
|
|
338
|
+
// While the host asked for a pick or for text (P112: Escape while selecting text);
|
|
339
|
+
// a pick ends with it, text selection is the host's to stop.
|
|
340
|
+
if (annotating === null) {
|
|
304
341
|
return;
|
|
305
342
|
}
|
|
306
|
-
|
|
343
|
+
if (annotating.elements === true) {
|
|
344
|
+
annotating = annotating.text ? { elements: false, text: true } : null;
|
|
345
|
+
}
|
|
307
346
|
break;
|
|
308
347
|
case "anchored": {
|
|
309
348
|
const known = new Set(marks.map((mark) => mark.id));
|
|
@@ -353,6 +392,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
353
392
|
if (activeMark !== null && !marks.some((mark) => mark.id === activeMark)) {
|
|
354
393
|
activeMark = null;
|
|
355
394
|
}
|
|
395
|
+
if (tracking !== null && !marks.some((mark) => mark.id === tracking)) {
|
|
396
|
+
tracking = null;
|
|
397
|
+
toFrame(ANNOTATE_METHODS.track, { id: null });
|
|
398
|
+
}
|
|
356
399
|
toFrame(ANNOTATE_METHODS.show, {
|
|
357
400
|
marks,
|
|
358
401
|
...(activeMark === null ? {} : { active: activeMark }),
|
|
@@ -366,10 +409,20 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
366
409
|
activeMark = id;
|
|
367
410
|
toFrame(ANNOTATE_METHODS.focus, { id });
|
|
368
411
|
},
|
|
412
|
+
track(id) {
|
|
413
|
+
needsAnnotate("track");
|
|
414
|
+
if (id !== null && !marks.some((mark) => mark.id === id)) {
|
|
415
|
+
throw new TypeError(`annotations.track: no mark ${JSON.stringify(id)} is shown`);
|
|
416
|
+
}
|
|
417
|
+
tracking = id;
|
|
418
|
+
trackedTimes.length = 0;
|
|
419
|
+
toFrame(ANNOTATE_METHODS.track, { id });
|
|
420
|
+
},
|
|
369
421
|
clear() {
|
|
370
422
|
needsAnnotate("clear");
|
|
371
423
|
marks = [];
|
|
372
424
|
activeMark = null;
|
|
425
|
+
tracking = null;
|
|
373
426
|
toFrame(ANNOTATE_METHODS.clear, {});
|
|
374
427
|
},
|
|
375
428
|
};
|
|
@@ -435,6 +488,11 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
435
488
|
};
|
|
436
489
|
|
|
437
490
|
const stop = () => {
|
|
491
|
+
// A run that ran a page with storage of its own making and never heard it used: no (P111).
|
|
492
|
+
if (bridge !== null && handshaken && !storageTold && compiled.shell?.storage === "memory") {
|
|
493
|
+
emit("storage", { used: false });
|
|
494
|
+
}
|
|
495
|
+
storageTold = false;
|
|
438
496
|
// The run's bridge refuses what still waits for a confirmation: a yes to it runs nothing
|
|
439
497
|
// (P095, after the review), and the next run's bridge starts its count again.
|
|
440
498
|
bridge?.close();
|
|
@@ -468,6 +526,8 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
468
526
|
allow: compiled.allow,
|
|
469
527
|
referrerPolicy: compiled.referrerPolicy,
|
|
470
528
|
colorScheme: scheme,
|
|
529
|
+
// A nested page's shell (P111): the config's word, never the frame's.
|
|
530
|
+
...(config.nested === true ? { nested: true } : {}),
|
|
471
531
|
// An app reports no size: its frame fills the host's container, at least the minimum;
|
|
472
532
|
// so does any display the host mounts to fill, or whose layout fills (P065): its
|
|
473
533
|
// content scrolls itself.
|
|
@@ -495,6 +555,29 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
495
555
|
})
|
|
496
556
|
: framed;
|
|
497
557
|
surface = created;
|
|
558
|
+
// The focus guard undid a move of the keyboard into this frame (P109): heard each time,
|
|
559
|
+
// and a frame that keeps taking it is stopped, as one that keeps navigating away is.
|
|
560
|
+
const takes: { at: number; counts: boolean }[] = [];
|
|
561
|
+
created.onFocusTaken?.(({ typing, failed }) => {
|
|
562
|
+
const at = Date.now();
|
|
563
|
+
// While the person typed, or a take-back that failed (the keys then go to the frame and
|
|
564
|
+
// the page sees no typing): either counts toward the first rule.
|
|
565
|
+
takes.push({ at, counts: typing || failed });
|
|
566
|
+
const within = (ms: number) => takes.filter((take) => at - take.at <= ms);
|
|
567
|
+
emit("focusTaken", { typing });
|
|
568
|
+
if (
|
|
569
|
+
surface === created &&
|
|
570
|
+
(within(TAKES.typing.withinMs).filter((take) => take.counts).length >=
|
|
571
|
+
TAKES.typing.most ||
|
|
572
|
+
within(TAKES.any.withinMs).length >= TAKES.any.most)
|
|
573
|
+
) {
|
|
574
|
+
stop();
|
|
575
|
+
contentError("The content kept taking the keyboard from the page; it was stopped.");
|
|
576
|
+
}
|
|
577
|
+
while (takes.length > 0 && at - (takes[0] as { at: number }).at > TAKES.typing.withinMs) {
|
|
578
|
+
takes.shift();
|
|
579
|
+
}
|
|
580
|
+
});
|
|
498
581
|
const watch = watchOutcome({
|
|
499
582
|
surface: created,
|
|
500
583
|
source,
|
|
@@ -530,6 +613,8 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
530
613
|
...(options.show === undefined ? {} : { show: options.show }),
|
|
531
614
|
...(options.cached === undefined ? {} : { cached: options.cached }),
|
|
532
615
|
userActivation: () => created.userActivation(),
|
|
616
|
+
// The person in this frame (P109): the page's focus in it, after the focus guard.
|
|
617
|
+
focused: () => created.focused?.(),
|
|
533
618
|
onEvent: onBridge,
|
|
534
619
|
...(declaration === null ? {} : { declaration }),
|
|
535
620
|
...(viewer === undefined ? {} : { viewer }),
|
|
@@ -537,6 +622,19 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
537
622
|
if (annotates) {
|
|
538
623
|
created.transport.listen((raw) => onAnnotation(raw, opening));
|
|
539
624
|
}
|
|
625
|
+
// Whether the page used storage (P111): once per run, the page's word (a count, no more).
|
|
626
|
+
created.transport.listen((raw) => {
|
|
627
|
+
if (
|
|
628
|
+
!storageTold &&
|
|
629
|
+
isRecord(raw) &&
|
|
630
|
+
raw.jsonrpc === "2.0" &&
|
|
631
|
+
raw.method === STORAGE_USED_METHOD &&
|
|
632
|
+
!("id" in raw)
|
|
633
|
+
) {
|
|
634
|
+
storageTold = true;
|
|
635
|
+
emit("storage", { used: true });
|
|
636
|
+
}
|
|
637
|
+
});
|
|
540
638
|
bridge = opening;
|
|
541
639
|
const opened = adapter.connect({
|
|
542
640
|
display: { id: mount.displayId, title: mount.title },
|
|
@@ -651,6 +749,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
651
749
|
restarts = 0;
|
|
652
750
|
run();
|
|
653
751
|
},
|
|
752
|
+
focus() {
|
|
753
|
+
surface?.focus?.();
|
|
754
|
+
},
|
|
654
755
|
destroy() {
|
|
655
756
|
destroyed = true;
|
|
656
757
|
stop();
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
import type { CapabilityName } from "../config/capabilities.ts";
|
|
2
|
+
import type { PortholeConfig } from "../config/schema.ts";
|
|
3
|
+
import { egressOrigins, type EgressKind } from "../compile/policy.ts";
|
|
4
|
+
import { LIBRARY_CDNS } from "../presets/presets.ts";
|
|
5
|
+
import { familyOf, runtimeCapability } from "../runtime/contract.ts";
|
|
6
|
+
import type { PageDeclaration } from "../runtime/declaration.ts";
|
|
7
|
+
|
|
8
|
+
/** Every kind a page reaches the network by. */
|
|
9
|
+
const KINDS: readonly EgressKind[] = ["connect", "script", "style", "img", "font", "media"];
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* The host functions that carry what a page puts in them to someone other than the person viewing
|
|
13
|
+
* it (P112, after the review, porthole#54): stores others read (`db`, a new version through
|
|
14
|
+
* `artifact`, the asset library through `assets`), a URL the person opens (`openLink`), the agent's
|
|
15
|
+
* conversation and context (`sendPrompt`, `setModelContext`), and the host's data services, which
|
|
16
|
+
* may be someone else's (`callTool`, `readData`, `subscribeData`: their arguments are the page's).
|
|
17
|
+
* Not here: the person's own clipboard and disk (`copyText`, `downloadFile`), the host's own UI
|
|
18
|
+
* (`annotate`, `resize`, `comments`: the composer is the person's, under the host's duties), and
|
|
19
|
+
* what only reads (`user`). `reportError` is one where the config sends errors to the agent.
|
|
20
|
+
*/
|
|
21
|
+
const CARRIERS: readonly CapabilityName[] = [
|
|
22
|
+
"db",
|
|
23
|
+
"artifact",
|
|
24
|
+
"assets",
|
|
25
|
+
"openLink",
|
|
26
|
+
"sendPrompt",
|
|
27
|
+
"setModelContext",
|
|
28
|
+
"callTool",
|
|
29
|
+
"readData",
|
|
30
|
+
"subscribeData",
|
|
31
|
+
];
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Whether a page shown under `config` with `declaration` may pass on what it is given (P112: a
|
|
35
|
+
* person's draft, which a host shows a page only where it can't). It may when it can reach one of
|
|
36
|
+
* the host functions that carry what it puts in them to others (`CARRIERS`; `reportError` where
|
|
37
|
+
* errors go to the agent), or the network beyond the library CDNs (`LIBRARY_CDNS`): any https site
|
|
38
|
+
* (`anyHttps`), or an origin the host (or a capability) added for connections, scripts, styles,
|
|
39
|
+
* images, fonts or media. A library CDN serves published packages by their path, and its logs are
|
|
40
|
+
* its operator's, not the page author's: not counted. A page reaches a host function the config
|
|
41
|
+
* declares: under the runtime with a declaration, only through a built-in family or one it
|
|
42
|
+
* declared (one no family serves, wherever the config declares it); without a declaration (a page from before 0.7), or without the runtime, every one, as
|
|
43
|
+
* 0.6's globals. The host's rule made checkable: "a page with a channel gets no drafts".
|
|
44
|
+
*/
|
|
45
|
+
export function mayPassOn(config: PortholeConfig, declaration: PageDeclaration | null): boolean {
|
|
46
|
+
const declared = (declaration?.capabilities ?? {}) as Readonly<Record<string, unknown>>;
|
|
47
|
+
const reaches = (name: CapabilityName): boolean => {
|
|
48
|
+
if (config.capabilities[name] === undefined) {
|
|
49
|
+
return false;
|
|
50
|
+
}
|
|
51
|
+
if (config.runtime === undefined || declaration === null) {
|
|
52
|
+
return true;
|
|
53
|
+
}
|
|
54
|
+
// One no runtime family serves (`reportError`: the shell reports what the page throws) is
|
|
55
|
+
// the page's wherever the config declares it.
|
|
56
|
+
const family = familyOf(name);
|
|
57
|
+
return (
|
|
58
|
+
family === null ||
|
|
59
|
+
runtimeCapability(family.name).builtIn ||
|
|
60
|
+
declared[family.name] !== undefined
|
|
61
|
+
);
|
|
62
|
+
};
|
|
63
|
+
if (CARRIERS.some(reaches) || (config.errors === "agent" && reaches("reportError"))) {
|
|
64
|
+
return true;
|
|
65
|
+
}
|
|
66
|
+
if ((config.egress.anyHttps ?? []).length > 0) {
|
|
67
|
+
return true;
|
|
68
|
+
}
|
|
69
|
+
return KINDS.some((kind) => {
|
|
70
|
+
const cdns = new Set(LIBRARY_CDNS[kind] ?? []);
|
|
71
|
+
return egressOrigins(config, kind).some((origin) => !cdns.has(origin));
|
|
72
|
+
});
|
|
73
|
+
}
|
package/src/host/types.ts
CHANGED
|
@@ -201,6 +201,21 @@ export interface DisplayEvents {
|
|
|
201
201
|
readonly refused: { readonly capability: CapabilityName; readonly refusal: Refusal };
|
|
202
202
|
/** Too many declines: the display stops asking until it runs again. */
|
|
203
203
|
readonly muted: undefined;
|
|
204
|
+
/**
|
|
205
|
+
* The content moved the keyboard into its frame from one of the page's text fields without the
|
|
206
|
+
* person (no press on the frame, no Tab, P109), and focus went back where it was; `typing`: the
|
|
207
|
+
* person had pressed a key on the page within the last second. The content's doing. Three while
|
|
208
|
+
* typing within 10 s, or five within 2 s, stop the display (`contentError` says so; `reload()`
|
|
209
|
+
* runs it again).
|
|
210
|
+
*/
|
|
211
|
+
readonly focusTaken: { readonly typing: boolean };
|
|
212
|
+
/**
|
|
213
|
+
* Whether the page touched `localStorage` or `sessionStorage` (the in-memory stand-in of a frame
|
|
214
|
+
* without storage of its own: opaque, or a nested page, P111): once per run, `used: true` when
|
|
215
|
+
* the page first did, else `used: false` as the run ends. Never what it kept: for a host to count
|
|
216
|
+
* the pages that would need storage.
|
|
217
|
+
*/
|
|
218
|
+
readonly storage: { readonly used: boolean };
|
|
204
219
|
/**
|
|
205
220
|
* What the frame reported about annotations (`annotate`, P053), checked and taken only while
|
|
206
221
|
* the host asked for it: a selection, its clearing, a cancelled pick, where marks are. The
|
|
@@ -221,6 +236,13 @@ export interface AnnotationControls {
|
|
|
221
236
|
show(marks: readonly AnnotationMark[]): void;
|
|
222
237
|
/** Brings a mark into view in the frame and makes it the active one. */
|
|
223
238
|
focus(id: string): void;
|
|
239
|
+
/**
|
|
240
|
+
* Follows one shown mark (P112): while it moves (a scroll, a layout change) the display reports
|
|
241
|
+
* `{ type: "tracked", id, rect }` at most once per animation frame (60 a second), its box clamped
|
|
242
|
+
* to the frame, for that mark only; `null` stops. One at a time: a new id replaces the last.
|
|
243
|
+
* Throws for an id no shown mark has; a `show` without it, or `clear`, stops it.
|
|
244
|
+
*/
|
|
245
|
+
track(id: string | null): void;
|
|
224
246
|
/** Removes every mark. */
|
|
225
247
|
clear(): void;
|
|
226
248
|
}
|
|
@@ -242,6 +264,11 @@ export interface DisplayControls {
|
|
|
242
264
|
readonly annotations: AnnotationControls;
|
|
243
265
|
/** Runs the content again from the start, in a new frame. */
|
|
244
266
|
reload(): void;
|
|
267
|
+
/**
|
|
268
|
+
* Moves focus into the display's frame, as the host's own move: from one of the page's text
|
|
269
|
+
* fields, a frame's own `focus()` is taken for the content's and undone (P109).
|
|
270
|
+
*/
|
|
271
|
+
focus(): void;
|
|
245
272
|
/** Tears the view down and removes the frame. */
|
|
246
273
|
destroy(): void;
|
|
247
274
|
}
|
|
@@ -257,4 +284,10 @@ export interface PortholeHost<C extends AdapterConnection = ShellConnection> {
|
|
|
257
284
|
* none (here or in the host's options), so a manual never teaches a function nobody serves.
|
|
258
285
|
*/
|
|
259
286
|
mount(container: HTMLElement, options: MountOptions): DisplayHandle<C>;
|
|
287
|
+
/**
|
|
288
|
+
* Whether a page with `declaration` may pass on what it is given (`mayPassOn`, P112): true where
|
|
289
|
+
* it can store what others read (`db` and `user`) or reaches the network beyond the library CDNs.
|
|
290
|
+
* A host shows such a page none of a person's drafts.
|
|
291
|
+
*/
|
|
292
|
+
mayPassOn(declaration: PageDeclaration | null): boolean;
|
|
260
293
|
}
|
package/src/index.ts
CHANGED
|
@@ -50,7 +50,9 @@ export {
|
|
|
50
50
|
type UrlSandboxExtra,
|
|
51
51
|
} from "./config/schema.ts";
|
|
52
52
|
export { hostOriginProblem, isHostOrigin } from "./isolation/served.ts";
|
|
53
|
-
export { FRAME_STATUS_METHOD } from "./isolation/types.ts";
|
|
53
|
+
export { FRAME_STATUS_METHOD, SHELL_STATE_METHOD, STORAGE_USED_METHOD } from "./isolation/types.ts";
|
|
54
|
+
export { PAGE_SANDBOX_TOKENS } from "./compile/policy.ts";
|
|
55
|
+
export { SHELL_GESTURE_MS } from "./platform/focus-guard.ts";
|
|
54
56
|
|
|
55
57
|
// The capability runtime (P085-P090): its contract, levels, a page's declaration, its services'
|
|
56
58
|
// shapes. Hosts implement the services; Porthole carries, checks and gates the calls.
|
|
@@ -275,6 +277,8 @@ export type {
|
|
|
275
277
|
DbContext,
|
|
276
278
|
} from "./bridge/types.ts";
|
|
277
279
|
export { createHost } from "./host/create-host.ts";
|
|
280
|
+
export { mayPassOn } from "./host/pass-on.ts";
|
|
281
|
+
export { focusField } from "./platform/focus-guard.ts";
|
|
278
282
|
// The client half of the host kit, and the display registry (P072).
|
|
279
283
|
export {
|
|
280
284
|
entryTarget,
|
package/src/isolation/types.ts
CHANGED
|
@@ -74,6 +74,18 @@ export interface FrameLocation {
|
|
|
74
74
|
/** The message a served page sends its host about loading (own-prefixed, P040). */
|
|
75
75
|
export const FRAME_STATUS_METHOD = "porthole/notifications/frame-status";
|
|
76
76
|
|
|
77
|
+
/** A nested page's shell's report of its own state to the host (P111). */
|
|
78
|
+
export const SHELL_STATE_METHOD = "porthole/shell/state";
|
|
79
|
+
|
|
80
|
+
/** A nested page's shell's heartbeat, every 50 ms while it runs (P111, after its review). */
|
|
81
|
+
export const SHELL_BEAT_METHOD = "porthole/shell/beat";
|
|
82
|
+
|
|
83
|
+
/** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
|
|
84
|
+
export const SHELL_METHOD_PREFIX = "porthole/shell/";
|
|
85
|
+
|
|
86
|
+
/** A page's word that it used storage, once per load (P111): never a key or a value. */
|
|
87
|
+
export const STORAGE_USED_METHOD = "porthole/storage-used";
|
|
88
|
+
|
|
77
89
|
/**
|
|
78
90
|
* Turns an instance into the URL its frame loads. Implemented by the host, usually by asking its
|
|
79
91
|
* own backend (which authenticates the viewer and calls `PortholeServer.issue`). Called on every
|