@botiverse/porthole 0.13.0 → 0.14.1
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 +770 -0
- package/dist/annotate/types.d.ts +36 -4
- package/dist/annotate/types.js +6 -0
- package/dist/annotate/validate.d.ts +2 -1
- package/dist/annotate/validate.js +30 -6
- package/dist/check/page-source.js +1 -1
- package/dist/compile/policy.d.ts +7 -0
- package/dist/compile/policy.js +13 -1
- 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/host/create-host.d.ts +2 -0
- package/dist/host/create-host.js +78 -3
- package/dist/host/pass-on.d.ts +15 -0
- package/dist/host/pass-on.js +65 -0
- package/dist/host/types.d.ts +29 -0
- package/dist/index.d.ts +4 -1
- package/dist/index.js +4 -1
- package/dist/isolation/types.d.ts +8 -0
- package/dist/isolation/types.js +8 -0
- package/dist/platform/focus-guard.d.ts +71 -2
- package/dist/platform/focus-guard.js +187 -12
- package/dist/platform/types.d.ts +8 -1
- package/dist/platform/web.js +60 -4
- package/dist/presets/presets.d.ts +2 -0
- package/dist/presets/presets.js +1 -0
- package/dist/react/frame.d.ts +4 -3
- package/dist/server/files.js +19 -3
- package/dist/server/index.d.ts +1 -0
- package/dist/server/index.js +5 -0
- package/dist/server/naming.js +4 -0
- package/dist/server/nested.d.ts +59 -0
- package/dist/server/nested.js +96 -0
- package/dist/server/server.js +193 -23
- package/dist/server/types.d.ts +5 -0
- package/dist/shell/annotate.d.ts +4 -3
- package/dist/shell/annotate.js +179 -9
- 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.d.ts +6 -0
- package/dist/shell/runtime.js +60 -15
- package/docs/ADOPTING.md +85 -2
- package/docs/ARCHITECTURE.md +28 -0
- package/docs/DECISIONS.md +416 -1
- package/docs/DESIGN.md +21 -4
- package/docs/THREAT_MODEL.md +102 -5
- package/package.json +6 -5
- package/src/annotate/types.ts +32 -4
- package/src/annotate/validate.ts +34 -8
- package/src/compile/policy.ts +14 -1
- 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/host/create-host.ts +81 -4
- package/src/host/pass-on.ts +73 -0
- package/src/host/types.ts +27 -0
- package/src/index.ts +4 -1
- package/src/isolation/types.ts +12 -0
- package/src/platform/focus-guard.ts +258 -15
- package/src/platform/types.ts +8 -1
- package/src/platform/web.ts +81 -9
- package/src/presets/presets.ts +3 -0
- package/src/react/frame.tsx +4 -3
- package/src/server/files.ts +19 -3
- package/src/server/index.ts +14 -0
- package/src/server/naming.ts +4 -0
- package/src/server/nested.ts +116 -0
- package/src/server/server.ts +224 -21
- package/src/server/types.ts +5 -0
- package/src/shell/annotate.ts +179 -9
- package/src/shell/frame.ts +268 -0
- package/src/shell/plan.ts +2 -1
- package/src/shell/runtime.ts +61 -15
|
@@ -24,8 +24,10 @@ export function defineDisplays(kinds) {
|
|
|
24
24
|
return presets.url({ ...kind.options, contentOrigins: [source] });
|
|
25
25
|
}
|
|
26
26
|
const options = kind.options ?? {};
|
|
27
|
+
// Nesting (P111) is a served page's: an opaque frame has nothing to nest.
|
|
28
|
+
const { nested: _nested, ...opaque } = options;
|
|
27
29
|
return presets[kind.preset](source === null
|
|
28
|
-
?
|
|
30
|
+
? opaque
|
|
29
31
|
: { ...options, ...kind.served, isolation: "domain", contentOrigins: [source] });
|
|
30
32
|
};
|
|
31
33
|
// Made once each: a page that asks every render gets the same objects.
|
package/dist/guide/limits.js
CHANGED
|
@@ -132,7 +132,7 @@ export function manualLimits(config, network) {
|
|
|
132
132
|
? `The ${it}'s address is about:srcdoc: it has no query string or hash to read.`
|
|
133
133
|
: `The ${it}'s address is its own (with Porthole's one-time ticket), never the app's: read no parameters from it.`);
|
|
134
134
|
add("shell", `document.write and document.open throw; nested frames (iframe, object, embed) are removed; full screen and the clipboard are closed${globals.has("copyText") ? " (copy buttons call copyText)" : config.runtime !== undefined && declared.has("copyText") ? " (copy buttons call clipboard.copy)" : ""}.`);
|
|
135
|
-
add("storage", config.isolation === "opaque"
|
|
135
|
+
add("storage", config.isolation === "opaque" || config.nested === true
|
|
136
136
|
? `State isn't saved: localStorage works but lasts only while the ${it} is on screen, and a reload or another device starts fresh. Keep what matters in the ${it}'s code.`
|
|
137
137
|
: config.storage?.scope !== undefined
|
|
138
138
|
? `localStorage is kept for ${config.storage.scope}, in this browser; another browser or device starts fresh. Reads and writes can throw (private windows, strict settings): wrap them in try/catch and keep only what can be lost.`
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
2
2
|
import type { AdapterConnection, ShellConnection } from "../protocol/adapter.ts";
|
|
3
3
|
import type { HostOptions, PortholeHost } from "./types.ts";
|
|
4
|
+
/** The most `tracked` reports a second the host takes (P112): one per animation frame at 60 Hz. */
|
|
5
|
+
export declare const TRACKED_PER_SECOND = 60;
|
|
4
6
|
/**
|
|
5
7
|
* Compiles `config` once and returns a host that mounts displays under it. Throws a `ConfigError`
|
|
6
8
|
* for a bad config.
|
package/dist/host/create-host.js
CHANGED
|
@@ -8,7 +8,9 @@ import { declaredCapabilities, effectiveGates } from "../compile/policy.js";
|
|
|
8
8
|
import { isRefused } from "../bridge/refusal.js";
|
|
9
9
|
import { capabilitySpec } from "../config/capabilities.js";
|
|
10
10
|
import { locateServed } from "./locate.js";
|
|
11
|
+
import { mayPassOn } from "./pass-on.js";
|
|
11
12
|
import { watchOutcome } from "./outcome.js";
|
|
13
|
+
import { STORAGE_USED_METHOD } from "../isolation/types.js";
|
|
12
14
|
import { webPlatform } from "../platform/web.js";
|
|
13
15
|
import { TAKES } from "../platform/focus-guard.js";
|
|
14
16
|
import { MCP_APPS_STYLE_VARIABLES, PORTHOLE_STYLES, } from "../protocol/mcp-apps.js";
|
|
@@ -28,7 +30,10 @@ const REPORTS = {
|
|
|
28
30
|
[ANNOTATE_METHODS.cancelled]: "cancelled",
|
|
29
31
|
[ANNOTATE_METHODS.anchored]: "anchored",
|
|
30
32
|
[ANNOTATE_METHODS.activated]: "activated",
|
|
33
|
+
[ANNOTATE_METHODS.tracked]: "tracked",
|
|
31
34
|
};
|
|
35
|
+
/** The most `tracked` reports a second the host takes (P112): one per animation frame at 60 Hz. */
|
|
36
|
+
export const TRACKED_PER_SECOND = 60;
|
|
32
37
|
const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
|
|
33
38
|
const STANDARD = new Set(MCP_APPS_STYLE_VARIABLES);
|
|
34
39
|
/**
|
|
@@ -48,6 +53,7 @@ export function createHost(config, options = {}) {
|
|
|
48
53
|
const hostInfo = options.hostInfo ?? { name: "porthole", version: "0" };
|
|
49
54
|
return {
|
|
50
55
|
compiled,
|
|
56
|
+
mayPassOn: (declaration) => mayPassOn(config, declaration),
|
|
51
57
|
mount(container, mount) {
|
|
52
58
|
const handlers = { ...options.handlers, ...mount.handlers };
|
|
53
59
|
// A host whose consent is a Refused refuses every consent-gated call before its handler:
|
|
@@ -122,7 +128,11 @@ export function createHost(config, options = {}) {
|
|
|
122
128
|
let annotating = null;
|
|
123
129
|
let marks = [];
|
|
124
130
|
let activeMark = null;
|
|
131
|
+
// The mark the host follows (P112), and when it took each `tracked` in the last second.
|
|
132
|
+
let tracking = null;
|
|
133
|
+
const trackedTimes = [];
|
|
125
134
|
let handshaken = false;
|
|
135
|
+
let storageTold = false;
|
|
126
136
|
const toFrame = (method, params) => {
|
|
127
137
|
if (handshaken && surface !== null) {
|
|
128
138
|
surface.transport.send({ jsonrpc: "2.0", method, params });
|
|
@@ -138,6 +148,9 @@ export function createHost(config, options = {}) {
|
|
|
138
148
|
if (annotating !== null) {
|
|
139
149
|
toFrame(ANNOTATE_METHODS.start, { ...annotating });
|
|
140
150
|
}
|
|
151
|
+
if (tracking !== null) {
|
|
152
|
+
toFrame(ANNOTATE_METHODS.track, { id: tracking });
|
|
153
|
+
}
|
|
141
154
|
};
|
|
142
155
|
/**
|
|
143
156
|
* The frame's viewport as the platform tells it now; undefined where it can't (no
|
|
@@ -183,6 +196,7 @@ export function createHost(config, options = {}) {
|
|
|
183
196
|
switch (report.type) {
|
|
184
197
|
case "selected":
|
|
185
198
|
case "activated":
|
|
199
|
+
case "tracked":
|
|
186
200
|
return { ...report, rect: clampRect(report.rect, viewport) };
|
|
187
201
|
case "anchored":
|
|
188
202
|
return {
|
|
@@ -217,6 +231,25 @@ export function createHost(config, options = {}) {
|
|
|
217
231
|
void through.call("annotate", null);
|
|
218
232
|
return;
|
|
219
233
|
}
|
|
234
|
+
// The followed mark's box (P112): the mark the host follows and no other, while it is
|
|
235
|
+
// shown, at most 60 a second; past the bridge's rate for reports, which a card that follows
|
|
236
|
+
// its mark at every frame would spend at once.
|
|
237
|
+
if (report.type === "tracked") {
|
|
238
|
+
const { id } = report;
|
|
239
|
+
if (id !== tracking || !marks.some((mark) => mark.id === id)) {
|
|
240
|
+
return;
|
|
241
|
+
}
|
|
242
|
+
const at = Date.now();
|
|
243
|
+
while (trackedTimes.length > 0 && at - trackedTimes[0] >= 1_000) {
|
|
244
|
+
trackedTimes.shift();
|
|
245
|
+
}
|
|
246
|
+
if (trackedTimes.length >= TRACKED_PER_SECOND) {
|
|
247
|
+
return;
|
|
248
|
+
}
|
|
249
|
+
trackedTimes.push(at);
|
|
250
|
+
emit("annotation", withinFrame(report));
|
|
251
|
+
return;
|
|
252
|
+
}
|
|
220
253
|
switch (report.type) {
|
|
221
254
|
case "selected": {
|
|
222
255
|
const kind = report.anchor.kind;
|
|
@@ -224,7 +257,8 @@ export function createHost(config, options = {}) {
|
|
|
224
257
|
!(kind === "element" ? annotating.elements : annotating.text)) {
|
|
225
258
|
return;
|
|
226
259
|
}
|
|
227
|
-
|
|
260
|
+
// A pick ends with it; holding a block (P112) lasts until the host stops it.
|
|
261
|
+
if (kind === "element" && annotating.elements === true) {
|
|
228
262
|
annotating = annotating.text ? { elements: false, text: true } : null;
|
|
229
263
|
}
|
|
230
264
|
break;
|
|
@@ -235,10 +269,14 @@ export function createHost(config, options = {}) {
|
|
|
235
269
|
}
|
|
236
270
|
break;
|
|
237
271
|
case "cancelled":
|
|
238
|
-
|
|
272
|
+
// While the host asked for a pick or for text (P112: Escape while selecting text);
|
|
273
|
+
// a pick ends with it, text selection is the host's to stop.
|
|
274
|
+
if (annotating === null) {
|
|
239
275
|
return;
|
|
240
276
|
}
|
|
241
|
-
|
|
277
|
+
if (annotating.elements === true) {
|
|
278
|
+
annotating = annotating.text ? { elements: false, text: true } : null;
|
|
279
|
+
}
|
|
242
280
|
break;
|
|
243
281
|
case "anchored": {
|
|
244
282
|
const known = new Set(marks.map((mark) => mark.id));
|
|
@@ -288,6 +326,10 @@ export function createHost(config, options = {}) {
|
|
|
288
326
|
if (activeMark !== null && !marks.some((mark) => mark.id === activeMark)) {
|
|
289
327
|
activeMark = null;
|
|
290
328
|
}
|
|
329
|
+
if (tracking !== null && !marks.some((mark) => mark.id === tracking)) {
|
|
330
|
+
tracking = null;
|
|
331
|
+
toFrame(ANNOTATE_METHODS.track, { id: null });
|
|
332
|
+
}
|
|
291
333
|
toFrame(ANNOTATE_METHODS.show, {
|
|
292
334
|
marks,
|
|
293
335
|
...(activeMark === null ? {} : { active: activeMark }),
|
|
@@ -301,12 +343,27 @@ export function createHost(config, options = {}) {
|
|
|
301
343
|
activeMark = id;
|
|
302
344
|
toFrame(ANNOTATE_METHODS.focus, { id });
|
|
303
345
|
},
|
|
346
|
+
track(id) {
|
|
347
|
+
needsAnnotate("track");
|
|
348
|
+
if (id !== null && !marks.some((mark) => mark.id === id)) {
|
|
349
|
+
throw new TypeError(`annotations.track: no mark ${JSON.stringify(id)} is shown`);
|
|
350
|
+
}
|
|
351
|
+
tracking = id;
|
|
352
|
+
trackedTimes.length = 0;
|
|
353
|
+
toFrame(ANNOTATE_METHODS.track, { id });
|
|
354
|
+
},
|
|
304
355
|
clear() {
|
|
305
356
|
needsAnnotate("clear");
|
|
306
357
|
marks = [];
|
|
307
358
|
activeMark = null;
|
|
359
|
+
tracking = null;
|
|
308
360
|
toFrame(ANNOTATE_METHODS.clear, {});
|
|
309
361
|
},
|
|
362
|
+
clearSelection() {
|
|
363
|
+
// Host → frame only, and kept for no later frame (P115).
|
|
364
|
+
needsAnnotate("clearSelection");
|
|
365
|
+
toFrame(ANNOTATE_METHODS.clearSelection, {});
|
|
366
|
+
},
|
|
310
367
|
};
|
|
311
368
|
const hostContext = () => {
|
|
312
369
|
const width = container.getBoundingClientRect().width;
|
|
@@ -364,6 +421,11 @@ export function createHost(config, options = {}) {
|
|
|
364
421
|
}
|
|
365
422
|
};
|
|
366
423
|
const stop = () => {
|
|
424
|
+
// A run that ran a page with storage of its own making and never heard it used: no (P111).
|
|
425
|
+
if (bridge !== null && handshaken && !storageTold && compiled.shell?.storage === "memory") {
|
|
426
|
+
emit("storage", { used: false });
|
|
427
|
+
}
|
|
428
|
+
storageTold = false;
|
|
367
429
|
// The run's bridge refuses what still waits for a confirmation: a yes to it runs nothing
|
|
368
430
|
// (P095, after the review), and the next run's bridge starts its count again.
|
|
369
431
|
bridge?.close();
|
|
@@ -397,6 +459,8 @@ export function createHost(config, options = {}) {
|
|
|
397
459
|
allow: compiled.allow,
|
|
398
460
|
referrerPolicy: compiled.referrerPolicy,
|
|
399
461
|
colorScheme: scheme,
|
|
462
|
+
// A nested page's shell (P111): the config's word, never the frame's.
|
|
463
|
+
...(config.nested === true ? { nested: true } : {}),
|
|
400
464
|
// An app reports no size: its frame fills the host's container, at least the minimum;
|
|
401
465
|
// so does any display the host mounts to fill, or whose layout fills (P065): its
|
|
402
466
|
// content scrolls itself.
|
|
@@ -487,6 +551,17 @@ export function createHost(config, options = {}) {
|
|
|
487
551
|
if (annotates) {
|
|
488
552
|
created.transport.listen((raw) => onAnnotation(raw, opening));
|
|
489
553
|
}
|
|
554
|
+
// Whether the page used storage (P111): once per run, the page's word (a count, no more).
|
|
555
|
+
created.transport.listen((raw) => {
|
|
556
|
+
if (!storageTold &&
|
|
557
|
+
isRecord(raw) &&
|
|
558
|
+
raw.jsonrpc === "2.0" &&
|
|
559
|
+
raw.method === STORAGE_USED_METHOD &&
|
|
560
|
+
!("id" in raw)) {
|
|
561
|
+
storageTold = true;
|
|
562
|
+
emit("storage", { used: true });
|
|
563
|
+
}
|
|
564
|
+
});
|
|
490
565
|
bridge = opening;
|
|
491
566
|
const opened = adapter.connect({
|
|
492
567
|
display: { id: mount.displayId, title: mount.title },
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import type { PortholeConfig } from "../config/schema.ts";
|
|
2
|
+
import type { PageDeclaration } from "../runtime/declaration.ts";
|
|
3
|
+
/**
|
|
4
|
+
* Whether a page shown under `config` with `declaration` may pass on what it is given (P112: a
|
|
5
|
+
* person's draft, which a host shows a page only where it can't). It may when it can reach one of
|
|
6
|
+
* the host functions that carry what it puts in them to others (`CARRIERS`; `reportError` where
|
|
7
|
+
* errors go to the agent), or the network beyond the library CDNs (`LIBRARY_CDNS`): any https site
|
|
8
|
+
* (`anyHttps`), or an origin the host (or a capability) added for connections, scripts, styles,
|
|
9
|
+
* images, fonts or media. A library CDN serves published packages by their path, and its logs are
|
|
10
|
+
* its operator's, not the page author's: not counted. A page reaches a host function the config
|
|
11
|
+
* declares: under the runtime with a declaration, only through a built-in family or one it
|
|
12
|
+
* 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
|
|
13
|
+
* 0.6's globals. The host's rule made checkable: "a page with a channel gets no drafts".
|
|
14
|
+
*/
|
|
15
|
+
export declare function mayPassOn(config: PortholeConfig, declaration: PageDeclaration | null): boolean;
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
import { egressOrigins } from "../compile/policy.js";
|
|
2
|
+
import { LIBRARY_CDNS } from "../presets/presets.js";
|
|
3
|
+
import { familyOf, runtimeCapability } from "../runtime/contract.js";
|
|
4
|
+
/** Every kind a page reaches the network by. */
|
|
5
|
+
const KINDS = ["connect", "script", "style", "img", "font", "media"];
|
|
6
|
+
/**
|
|
7
|
+
* The host functions that carry what a page puts in them to someone other than the person viewing
|
|
8
|
+
* it (P112, after the review, porthole#54): stores others read (`db`, a new version through
|
|
9
|
+
* `artifact`, the asset library through `assets`), a URL the person opens (`openLink`), the agent's
|
|
10
|
+
* conversation and context (`sendPrompt`, `setModelContext`), and the host's data services, which
|
|
11
|
+
* may be someone else's (`callTool`, `readData`, `subscribeData`: their arguments are the page's).
|
|
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 duties), and
|
|
14
|
+
* what only reads (`user`). `reportError` is one where the config sends errors to the agent.
|
|
15
|
+
*/
|
|
16
|
+
const CARRIERS = [
|
|
17
|
+
"db",
|
|
18
|
+
"artifact",
|
|
19
|
+
"assets",
|
|
20
|
+
"openLink",
|
|
21
|
+
"sendPrompt",
|
|
22
|
+
"setModelContext",
|
|
23
|
+
"callTool",
|
|
24
|
+
"readData",
|
|
25
|
+
"subscribeData",
|
|
26
|
+
];
|
|
27
|
+
/**
|
|
28
|
+
* Whether a page shown under `config` with `declaration` may pass on what it is given (P112: a
|
|
29
|
+
* person's draft, which a host shows a page only where it can't). It may when it can reach one of
|
|
30
|
+
* the host functions that carry what it puts in them to others (`CARRIERS`; `reportError` where
|
|
31
|
+
* errors go to the agent), or the network beyond the library CDNs (`LIBRARY_CDNS`): any https site
|
|
32
|
+
* (`anyHttps`), or an origin the host (or a capability) added for connections, scripts, styles,
|
|
33
|
+
* images, fonts or media. A library CDN serves published packages by their path, and its logs are
|
|
34
|
+
* its operator's, not the page author's: not counted. A page reaches a host function the config
|
|
35
|
+
* declares: under the runtime with a declaration, only through a built-in family or one it
|
|
36
|
+
* 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
|
|
37
|
+
* 0.6's globals. The host's rule made checkable: "a page with a channel gets no drafts".
|
|
38
|
+
*/
|
|
39
|
+
export function mayPassOn(config, declaration) {
|
|
40
|
+
const declared = (declaration?.capabilities ?? {});
|
|
41
|
+
const reaches = (name) => {
|
|
42
|
+
if (config.capabilities[name] === undefined) {
|
|
43
|
+
return false;
|
|
44
|
+
}
|
|
45
|
+
if (config.runtime === undefined || declaration === null) {
|
|
46
|
+
return true;
|
|
47
|
+
}
|
|
48
|
+
// One no runtime family serves (`reportError`: the shell reports what the page throws) is
|
|
49
|
+
// the page's wherever the config declares it.
|
|
50
|
+
const family = familyOf(name);
|
|
51
|
+
return (family === null ||
|
|
52
|
+
runtimeCapability(family.name).builtIn ||
|
|
53
|
+
declared[family.name] !== undefined);
|
|
54
|
+
};
|
|
55
|
+
if (CARRIERS.some(reaches) || (config.errors === "agent" && reaches("reportError"))) {
|
|
56
|
+
return true;
|
|
57
|
+
}
|
|
58
|
+
if ((config.egress.anyHttps ?? []).length > 0) {
|
|
59
|
+
return true;
|
|
60
|
+
}
|
|
61
|
+
return KINDS.some((kind) => {
|
|
62
|
+
const cdns = new Set(LIBRARY_CDNS[kind] ?? []);
|
|
63
|
+
return egressOrigins(config, kind).some((origin) => !cdns.has(origin));
|
|
64
|
+
});
|
|
65
|
+
}
|
package/dist/host/types.d.ts
CHANGED
|
@@ -215,6 +215,15 @@ export interface DisplayEvents {
|
|
|
215
215
|
readonly focusTaken: {
|
|
216
216
|
readonly typing: boolean;
|
|
217
217
|
};
|
|
218
|
+
/**
|
|
219
|
+
* Whether the page touched `localStorage` or `sessionStorage` (the in-memory stand-in of a frame
|
|
220
|
+
* without storage of its own: opaque, or a nested page, P111): once per run, `used: true` when
|
|
221
|
+
* the page first did, else `used: false` as the run ends. Never what it kept: for a host to count
|
|
222
|
+
* the pages that would need storage.
|
|
223
|
+
*/
|
|
224
|
+
readonly storage: {
|
|
225
|
+
readonly used: boolean;
|
|
226
|
+
};
|
|
218
227
|
/**
|
|
219
228
|
* What the frame reported about annotations (`annotate`, P053), checked and taken only while
|
|
220
229
|
* the host asked for it: a selection, its clearing, a cancelled pick, where marks are. The
|
|
@@ -234,8 +243,22 @@ export interface AnnotationControls {
|
|
|
234
243
|
show(marks: readonly AnnotationMark[]): void;
|
|
235
244
|
/** Brings a mark into view in the frame and makes it the active one. */
|
|
236
245
|
focus(id: string): void;
|
|
246
|
+
/**
|
|
247
|
+
* Follows one shown mark (P112): while it moves (a scroll, a layout change) the display reports
|
|
248
|
+
* `{ type: "tracked", id, rect }` at most once per animation frame (60 a second), its box clamped
|
|
249
|
+
* to the frame, for that mark only; `null` stops. One at a time: a new id replaces the last.
|
|
250
|
+
* Throws for an id no shown mark has; a `show` without it, or `clear`, stops it.
|
|
251
|
+
*/
|
|
252
|
+
track(id: string | null): void;
|
|
237
253
|
/** Removes every mark. */
|
|
238
254
|
clear(): void;
|
|
255
|
+
/**
|
|
256
|
+
* Takes the page's text selection away (P115), its highlight with it: for when the host has
|
|
257
|
+
* used it (a comment posted, a draft added). No `unselected` follows; marks (posted and drafts),
|
|
258
|
+
* the mode and a followed mark stay as they are. Nothing selected: nothing happens. Not kept for
|
|
259
|
+
* a frame that runs later (it has no selection to clear).
|
|
260
|
+
*/
|
|
261
|
+
clearSelection(): void;
|
|
239
262
|
}
|
|
240
263
|
export interface DisplayControls {
|
|
241
264
|
readonly displayId: string;
|
|
@@ -268,4 +291,10 @@ export interface PortholeHost<C extends AdapterConnection = ShellConnection> {
|
|
|
268
291
|
* none (here or in the host's options), so a manual never teaches a function nobody serves.
|
|
269
292
|
*/
|
|
270
293
|
mount(container: HTMLElement, options: MountOptions): DisplayHandle<C>;
|
|
294
|
+
/**
|
|
295
|
+
* Whether a page with `declaration` may pass on what it is given (`mayPassOn`, P112): true where
|
|
296
|
+
* it can store what others read (`db` and `user`) or reaches the network beyond the library CDNs.
|
|
297
|
+
* A host shows such a page none of a person's drafts.
|
|
298
|
+
*/
|
|
299
|
+
mayPassOn(declaration: PageDeclaration | null): boolean;
|
|
271
300
|
}
|
package/dist/index.d.ts
CHANGED
|
@@ -9,7 +9,9 @@ export { BUILT_IN_TOPICS, ConfigError, isOriginSource, originSourceProblem, vali
|
|
|
9
9
|
export { configWarnings, type ConfigWarning } from "./config/warnings.ts";
|
|
10
10
|
export { URL_PERMISSIONS, URL_SANDBOX_EXTRAS, type UrlPermission, type UrlSandboxExtra, } from "./config/schema.ts";
|
|
11
11
|
export { hostOriginProblem, isHostOrigin } from "./isolation/served.ts";
|
|
12
|
-
export { FRAME_STATUS_METHOD } from "./isolation/types.ts";
|
|
12
|
+
export { FRAME_STATUS_METHOD, SHELL_STATE_METHOD, STORAGE_USED_METHOD } from "./isolation/types.ts";
|
|
13
|
+
export { PAGE_SANDBOX_TOKENS } from "./compile/policy.ts";
|
|
14
|
+
export { SHELL_GESTURE_MS } from "./platform/focus-guard.ts";
|
|
13
15
|
export { RUNTIME_CALL_METHOD, RUNTIME_CAPABILITIES, RUNTIME_CAPABILITY_NAMES, RUNTIME_EVENT_METHOD, RUNTIME_EXPERIMENTAL_KEY, RUNTIME_GLOBAL, RUNTIME_HOST_FUNCTIONS, RUNTIME_UNWATCH_METHOD, RUNTIME_VERSION, RUNTIME_VERSIONS, familyOf, isRuntimeCapabilityName, methodGates, isRuntimeVersion, methodLevel, offeredCapabilities, rosterOf, type RuntimeCapability, type RuntimeCapabilityName, type RuntimeMethod, type RuntimeVersion, } from "./runtime/contract.ts";
|
|
14
16
|
export { VIEWER_LEVELS, atLeast, isViewerLevel, parseViewer, type ViewerInfo, type ViewerLevel, } from "./runtime/levels.ts";
|
|
15
17
|
export { checkDeclaration, declarationProblems, declareCapabilities, declaredMatch, intersectDeclarations, tryIntersectDeclarations, type CapabilityDeclaration, type DeclarationProblem, type DeclaredCapability, type DeclaredData, type DeclaredDb, type PageDeclaration, } from "./runtime/declaration.ts";
|
|
@@ -35,6 +37,7 @@ export { COPY_TEXT_METHOD, MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS
|
|
|
35
37
|
export { REFUSAL_CODES, Refused, isRefused, type RefusalCode, type RefusalReason, } from "./bridge/refusal.ts";
|
|
36
38
|
export type { CallContext, CallOptions, CallOutcome, CapabilityHandler, CapabilityHandlers, Confirm, ConfirmAnswer, ConfirmDisplay, ConfirmRequest, Consent, DataCache, Proceed, HostFunctionBridge, Refusal, Show, SubscriptionContext, DbContext, } from "./bridge/types.ts";
|
|
37
39
|
export { createHost } from "./host/create-host.ts";
|
|
40
|
+
export { mayPassOn } from "./host/pass-on.ts";
|
|
38
41
|
export { focusField } from "./platform/focus-guard.ts";
|
|
39
42
|
export { entryTarget, frameFallback, portholeClient, type ContentClientMeta, type FrameFallback, type PortholeClient, type PortholeClientOptions, } from "./host/client.ts";
|
|
40
43
|
export { defineDisplays, type DisplayKind, type Displays } from "./displays/displays.ts";
|
package/dist/index.js
CHANGED
|
@@ -9,7 +9,9 @@ export { BUILT_IN_TOPICS, ConfigError, isOriginSource, originSourceProblem, vali
|
|
|
9
9
|
export { configWarnings } from "./config/warnings.js";
|
|
10
10
|
export { URL_PERMISSIONS, URL_SANDBOX_EXTRAS, } from "./config/schema.js";
|
|
11
11
|
export { hostOriginProblem, isHostOrigin } from "./isolation/served.js";
|
|
12
|
-
export { FRAME_STATUS_METHOD } from "./isolation/types.js";
|
|
12
|
+
export { FRAME_STATUS_METHOD, SHELL_STATE_METHOD, STORAGE_USED_METHOD } from "./isolation/types.js";
|
|
13
|
+
export { PAGE_SANDBOX_TOKENS } from "./compile/policy.js";
|
|
14
|
+
export { SHELL_GESTURE_MS } from "./platform/focus-guard.js";
|
|
13
15
|
// The capability runtime (P085-P090): its contract, levels, a page's declaration, its services'
|
|
14
16
|
// shapes. Hosts implement the services; Porthole carries, checks and gates the calls.
|
|
15
17
|
export { RUNTIME_CALL_METHOD, RUNTIME_CAPABILITIES, RUNTIME_CAPABILITY_NAMES, RUNTIME_EVENT_METHOD, RUNTIME_EXPERIMENTAL_KEY, RUNTIME_GLOBAL, RUNTIME_HOST_FUNCTIONS, RUNTIME_UNWATCH_METHOD, RUNTIME_VERSION, RUNTIME_VERSIONS, familyOf, isRuntimeCapabilityName, methodGates, isRuntimeVersion, methodLevel, offeredCapabilities, rosterOf, } from "./runtime/contract.js";
|
|
@@ -36,6 +38,7 @@ export { COPY_TEXT_METHOD, MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS
|
|
|
36
38
|
// Why a call was refused, as content is told it, and the host's own refusals (P080).
|
|
37
39
|
export { REFUSAL_CODES, Refused, isRefused, } from "./bridge/refusal.js";
|
|
38
40
|
export { createHost } from "./host/create-host.js";
|
|
41
|
+
export { mayPassOn } from "./host/pass-on.js";
|
|
39
42
|
export { focusField } from "./platform/focus-guard.js";
|
|
40
43
|
// The client half of the host kit, and the display registry (P072).
|
|
41
44
|
export { entryTarget, frameFallback, portholeClient, } from "./host/client.js";
|
|
@@ -79,6 +79,14 @@ export interface FrameLocation {
|
|
|
79
79
|
}
|
|
80
80
|
/** The message a served page sends its host about loading (own-prefixed, P040). */
|
|
81
81
|
export declare const FRAME_STATUS_METHOD = "porthole/notifications/frame-status";
|
|
82
|
+
/** A nested page's shell's report of its own state to the host (P111). */
|
|
83
|
+
export declare const SHELL_STATE_METHOD = "porthole/shell/state";
|
|
84
|
+
/** A nested page's shell's heartbeat, every 50 ms while it runs (P111, after its review). */
|
|
85
|
+
export declare const SHELL_BEAT_METHOD = "porthole/shell/beat";
|
|
86
|
+
/** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
|
|
87
|
+
export declare const SHELL_METHOD_PREFIX = "porthole/shell/";
|
|
88
|
+
/** A page's word that it used storage, once per load (P111): never a key or a value. */
|
|
89
|
+
export declare const STORAGE_USED_METHOD = "porthole/storage-used";
|
|
82
90
|
/**
|
|
83
91
|
* Turns an instance into the URL its frame loads. Implemented by the host, usually by asking its
|
|
84
92
|
* own backend (which authenticates the viewer and calls `PortholeServer.issue`). Called on every
|
package/dist/isolation/types.js
CHANGED
|
@@ -1,2 +1,10 @@
|
|
|
1
1
|
/** The message a served page sends its host about loading (own-prefixed, P040). */
|
|
2
2
|
export const FRAME_STATUS_METHOD = "porthole/notifications/frame-status";
|
|
3
|
+
/** A nested page's shell's report of its own state to the host (P111). */
|
|
4
|
+
export const SHELL_STATE_METHOD = "porthole/shell/state";
|
|
5
|
+
/** A nested page's shell's heartbeat, every 50 ms while it runs (P111, after its review). */
|
|
6
|
+
export const SHELL_BEAT_METHOD = "porthole/shell/beat";
|
|
7
|
+
/** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
|
|
8
|
+
export const SHELL_METHOD_PREFIX = "porthole/shell/";
|
|
9
|
+
/** A page's word that it used storage, once per load (P111): never a key or a value. */
|
|
10
|
+
export const STORAGE_USED_METHOD = "porthole/storage-used";
|
|
@@ -60,6 +60,45 @@ export declare const TAKES: {
|
|
|
60
60
|
readonly withinMs: 2000;
|
|
61
61
|
};
|
|
62
62
|
};
|
|
63
|
+
/**
|
|
64
|
+
* A nested page's shell (P111) says its own activation turned on: a press or key of the person's
|
|
65
|
+
* in that page (activation goes up to ancestors, never down, so nothing on the host's page turns
|
|
66
|
+
* it on). A move of focus into the frame within this long of it, with no press or key on the
|
|
67
|
+
* host's page since, is the person's; so is a `comments.open` the page sends within it.
|
|
68
|
+
*/
|
|
69
|
+
export declare const SHELL_GESTURE_MS = 1000;
|
|
70
|
+
/**
|
|
71
|
+
* How long a move into a nested page's frame waits for its shell's word before it is taken for
|
|
72
|
+
* the page's: the shell says what it saw at its next animation frame, after the host's page
|
|
73
|
+
* already heard the move. A shell that says nothing in time (gone, stalled) has its frame's move
|
|
74
|
+
* taken back, as any page's.
|
|
75
|
+
*/
|
|
76
|
+
export declare const SHELL_WAIT_MS = 500;
|
|
77
|
+
/**
|
|
78
|
+
* A shell's word that came this long before the host's page heard the move is about that move
|
|
79
|
+
* (the shell's frame can come first); one from before then is about an earlier one.
|
|
80
|
+
*/
|
|
81
|
+
export declare const SHELL_EARLY_MS = 150;
|
|
82
|
+
/**
|
|
83
|
+
* A shell that went this long without a look, or without a word to the host (its heartbeat is every
|
|
84
|
+
* 50 ms), was stalled (P111, after its review): where the page shares the shell's thread (WebKit,
|
|
85
|
+
* Firefox), a page that holds it from its own click handler pushes the moment the shell sees its
|
|
86
|
+
* activation turn on past the person's next keys on the host's page. An activation it saw then is
|
|
87
|
+
* uncertain: it is no one's gesture until it lapses.
|
|
88
|
+
*/
|
|
89
|
+
export declare const SHELL_STALL_MS = 100;
|
|
90
|
+
/** What a nested page's shell last said (P111), on the host's clock. */
|
|
91
|
+
export interface ShellWord {
|
|
92
|
+
/** Whether its engine tells activation at all (`navigator.userActivation`). */
|
|
93
|
+
readonly supported: boolean;
|
|
94
|
+
/** When its activation last turned on; -Infinity if it hasn't, or is off. */
|
|
95
|
+
readonly activatedAt: number;
|
|
96
|
+
/** Whether it last said the page's focus is in it, and when it last said focus came in. */
|
|
97
|
+
readonly focused: boolean;
|
|
98
|
+
readonly focusedAt: number;
|
|
99
|
+
/** Its activation turned on while it was stalled: uncertain until it goes off (`SHELL_STALL_MS`). */
|
|
100
|
+
readonly uncertain?: boolean;
|
|
101
|
+
}
|
|
63
102
|
/** One move of the keyboard the guard undid. */
|
|
64
103
|
export interface FocusTake {
|
|
65
104
|
/** The person pressed a key on the host's page within the last second. */
|
|
@@ -96,6 +135,14 @@ export interface FocusMove {
|
|
|
96
135
|
readonly activation: boolean | undefined;
|
|
97
136
|
/** The host moved focus into the frame itself (`DisplayHandle.focus()`), just now. */
|
|
98
137
|
readonly hostMoved: boolean;
|
|
138
|
+
/**
|
|
139
|
+
* A nested page's frame (P111): what its shell said, and when the host's page last had a
|
|
140
|
+
* trusted press or key of its own. Absent for any other frame.
|
|
141
|
+
*/
|
|
142
|
+
readonly shell?: {
|
|
143
|
+
readonly word: ShellWord;
|
|
144
|
+
readonly hostInputAt: number;
|
|
145
|
+
};
|
|
99
146
|
}
|
|
100
147
|
/**
|
|
101
148
|
* Whether the person moved focus into the frame themselves:
|
|
@@ -115,12 +162,34 @@ export interface FocusMove {
|
|
|
115
162
|
* Anything else is the page's: focus goes back.
|
|
116
163
|
*/
|
|
117
164
|
export declare function personMoved(move: FocusMove): boolean;
|
|
165
|
+
/**
|
|
166
|
+
* Whether a nested page's shell saw the person's gesture just now (P111): its activation turned on
|
|
167
|
+
* within `SHELL_GESTURE_MS`, after the host's page's last trusted press or key.
|
|
168
|
+
*/
|
|
169
|
+
export declare function shellGesture(word: ShellWord, hostInputAt: number, now: number): boolean;
|
|
118
170
|
/** Whether `element` takes the person's typed text: a text field, a text area, an editable region. */
|
|
119
171
|
export declare function takesText(element: Element | null): element is HTMLElement;
|
|
120
172
|
/** One page's guard, shared by every display's frame on it. */
|
|
121
173
|
export interface FocusGuard {
|
|
122
|
-
/**
|
|
123
|
-
|
|
174
|
+
/**
|
|
175
|
+
* Guards `frame`: `taken` hears each move into it that was undone. `nested`: it holds a nested
|
|
176
|
+
* page's shell (P111), whose word (`shell`) decides the moves into it.
|
|
177
|
+
*/
|
|
178
|
+
add(frame: HTMLIFrameElement, taken: (take: FocusTake) => void, options?: {
|
|
179
|
+
readonly nested?: boolean;
|
|
180
|
+
}): () => void;
|
|
181
|
+
/** What a nested page's shell said (P111): its activation, its focus. */
|
|
182
|
+
shell(frame: HTMLIFrameElement, said: {
|
|
183
|
+
readonly supported: boolean;
|
|
184
|
+
readonly ago: number | null;
|
|
185
|
+
readonly focused: boolean;
|
|
186
|
+
/** How long the shell went without a look before this one (its own clock). */
|
|
187
|
+
readonly gap: number;
|
|
188
|
+
}): void;
|
|
189
|
+
/** A nested page's shell's heartbeat (P111): it is looking. */
|
|
190
|
+
beat(frame: HTMLIFrameElement): void;
|
|
191
|
+
/** Whether a nested page's shell saw the person's gesture just now (`shellGesture`). */
|
|
192
|
+
gesture(frame: HTMLIFrameElement): boolean;
|
|
124
193
|
/** The host moves focus into `frame` itself. */
|
|
125
194
|
focus(frame: HTMLIFrameElement): void;
|
|
126
195
|
/**
|