@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
|
@@ -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.`
|
package/dist/guide/runtime.js
CHANGED
|
@@ -48,7 +48,7 @@ const CALLS = {
|
|
|
48
48
|
/** What each host function does, in a phrase, for its line. */
|
|
49
49
|
const WHAT = {
|
|
50
50
|
user: () => "who is viewing: { id, name, level }, as the app says",
|
|
51
|
-
comments: () => "opens the app's comment composer at a place the page names (a stable name like slide-3 or refs/a.md#L12, a label, the quoted text), optionally starting with a draft (at most 2,000 characters of visible text, lines and tabs fine, no zero-width, bidi or tag characters; e.g. a button's \"Approved\" or a checklist to fill in); the person edits and posts it in the app, or doesn't. True if it opened. Write-only: a page never reads comments, and never posts one",
|
|
51
|
+
comments: () => "opens the app's comment composer at a place the page names (a stable name like slide-3 or refs/a.md#L12, a label, the quoted text), optionally starting with a draft (at most 2,000 characters of visible text, lines and tabs fine, no zero-width characters, joiners only between two letters (Persian's or Hindi's are fine; an emoji joined with U+200D is refused; ❤️ is fine), no bidi or tag characters, line or paragraph separators, or runs of blanks; e.g. a button's \"Approved\" or a checklist to fill in); the person edits and posts it in the app, or doesn't. Call it from a click in the page. True if it opened. Write-only: a page never reads comments, and never posts one",
|
|
52
52
|
copyText: () => `copies text to the person's clipboard (at most ${MAX_COPY_CHARS.toLocaleString("en-US")} characters), and the app shows them what was copied; nothing else in the page can write the clipboard. True if copied`,
|
|
53
53
|
openLink: () => "opens an http(s) link outside the page; a click on an <a href> does the same. True if it opened",
|
|
54
54
|
downloadFile: () => "hands the person a file to save (<a download> doesn't work here). True if it started",
|
|
@@ -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,8 +8,11 @@ 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";
|
|
15
|
+
import { TAKES } from "../platform/focus-guard.js";
|
|
13
16
|
import { MCP_APPS_STYLE_VARIABLES, PORTHOLE_STYLES, } from "../protocol/mcp-apps.js";
|
|
14
17
|
import { shellAdapter } from "../protocol/shell-adapter.js";
|
|
15
18
|
import { resolveTheme } from "../theme/variables.js";
|
|
@@ -27,7 +30,10 @@ const REPORTS = {
|
|
|
27
30
|
[ANNOTATE_METHODS.cancelled]: "cancelled",
|
|
28
31
|
[ANNOTATE_METHODS.anchored]: "anchored",
|
|
29
32
|
[ANNOTATE_METHODS.activated]: "activated",
|
|
33
|
+
[ANNOTATE_METHODS.tracked]: "tracked",
|
|
30
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;
|
|
31
37
|
const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
|
|
32
38
|
const STANDARD = new Set(MCP_APPS_STYLE_VARIABLES);
|
|
33
39
|
/**
|
|
@@ -47,6 +53,7 @@ export function createHost(config, options = {}) {
|
|
|
47
53
|
const hostInfo = options.hostInfo ?? { name: "porthole", version: "0" };
|
|
48
54
|
return {
|
|
49
55
|
compiled,
|
|
56
|
+
mayPassOn: (declaration) => mayPassOn(config, declaration),
|
|
50
57
|
mount(container, mount) {
|
|
51
58
|
const handlers = { ...options.handlers, ...mount.handlers };
|
|
52
59
|
// A host whose consent is a Refused refuses every consent-gated call before its handler:
|
|
@@ -121,7 +128,11 @@ export function createHost(config, options = {}) {
|
|
|
121
128
|
let annotating = null;
|
|
122
129
|
let marks = [];
|
|
123
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 = [];
|
|
124
134
|
let handshaken = false;
|
|
135
|
+
let storageTold = false;
|
|
125
136
|
const toFrame = (method, params) => {
|
|
126
137
|
if (handshaken && surface !== null) {
|
|
127
138
|
surface.transport.send({ jsonrpc: "2.0", method, params });
|
|
@@ -137,6 +148,9 @@ export function createHost(config, options = {}) {
|
|
|
137
148
|
if (annotating !== null) {
|
|
138
149
|
toFrame(ANNOTATE_METHODS.start, { ...annotating });
|
|
139
150
|
}
|
|
151
|
+
if (tracking !== null) {
|
|
152
|
+
toFrame(ANNOTATE_METHODS.track, { id: tracking });
|
|
153
|
+
}
|
|
140
154
|
};
|
|
141
155
|
/**
|
|
142
156
|
* The frame's viewport as the platform tells it now; undefined where it can't (no
|
|
@@ -182,6 +196,7 @@ export function createHost(config, options = {}) {
|
|
|
182
196
|
switch (report.type) {
|
|
183
197
|
case "selected":
|
|
184
198
|
case "activated":
|
|
199
|
+
case "tracked":
|
|
185
200
|
return { ...report, rect: clampRect(report.rect, viewport) };
|
|
186
201
|
case "anchored":
|
|
187
202
|
return {
|
|
@@ -216,6 +231,25 @@ export function createHost(config, options = {}) {
|
|
|
216
231
|
void through.call("annotate", null);
|
|
217
232
|
return;
|
|
218
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
|
+
}
|
|
219
253
|
switch (report.type) {
|
|
220
254
|
case "selected": {
|
|
221
255
|
const kind = report.anchor.kind;
|
|
@@ -223,7 +257,8 @@ export function createHost(config, options = {}) {
|
|
|
223
257
|
!(kind === "element" ? annotating.elements : annotating.text)) {
|
|
224
258
|
return;
|
|
225
259
|
}
|
|
226
|
-
|
|
260
|
+
// A pick ends with it; holding a block (P112) lasts until the host stops it.
|
|
261
|
+
if (kind === "element" && annotating.elements === true) {
|
|
227
262
|
annotating = annotating.text ? { elements: false, text: true } : null;
|
|
228
263
|
}
|
|
229
264
|
break;
|
|
@@ -234,10 +269,14 @@ export function createHost(config, options = {}) {
|
|
|
234
269
|
}
|
|
235
270
|
break;
|
|
236
271
|
case "cancelled":
|
|
237
|
-
|
|
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) {
|
|
238
275
|
return;
|
|
239
276
|
}
|
|
240
|
-
|
|
277
|
+
if (annotating.elements === true) {
|
|
278
|
+
annotating = annotating.text ? { elements: false, text: true } : null;
|
|
279
|
+
}
|
|
241
280
|
break;
|
|
242
281
|
case "anchored": {
|
|
243
282
|
const known = new Set(marks.map((mark) => mark.id));
|
|
@@ -287,6 +326,10 @@ export function createHost(config, options = {}) {
|
|
|
287
326
|
if (activeMark !== null && !marks.some((mark) => mark.id === activeMark)) {
|
|
288
327
|
activeMark = null;
|
|
289
328
|
}
|
|
329
|
+
if (tracking !== null && !marks.some((mark) => mark.id === tracking)) {
|
|
330
|
+
tracking = null;
|
|
331
|
+
toFrame(ANNOTATE_METHODS.track, { id: null });
|
|
332
|
+
}
|
|
290
333
|
toFrame(ANNOTATE_METHODS.show, {
|
|
291
334
|
marks,
|
|
292
335
|
...(activeMark === null ? {} : { active: activeMark }),
|
|
@@ -300,10 +343,20 @@ export function createHost(config, options = {}) {
|
|
|
300
343
|
activeMark = id;
|
|
301
344
|
toFrame(ANNOTATE_METHODS.focus, { id });
|
|
302
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
|
+
},
|
|
303
355
|
clear() {
|
|
304
356
|
needsAnnotate("clear");
|
|
305
357
|
marks = [];
|
|
306
358
|
activeMark = null;
|
|
359
|
+
tracking = null;
|
|
307
360
|
toFrame(ANNOTATE_METHODS.clear, {});
|
|
308
361
|
},
|
|
309
362
|
};
|
|
@@ -363,6 +416,11 @@ export function createHost(config, options = {}) {
|
|
|
363
416
|
}
|
|
364
417
|
};
|
|
365
418
|
const stop = () => {
|
|
419
|
+
// A run that ran a page with storage of its own making and never heard it used: no (P111).
|
|
420
|
+
if (bridge !== null && handshaken && !storageTold && compiled.shell?.storage === "memory") {
|
|
421
|
+
emit("storage", { used: false });
|
|
422
|
+
}
|
|
423
|
+
storageTold = false;
|
|
366
424
|
// The run's bridge refuses what still waits for a confirmation: a yes to it runs nothing
|
|
367
425
|
// (P095, after the review), and the next run's bridge starts its count again.
|
|
368
426
|
bridge?.close();
|
|
@@ -396,6 +454,8 @@ export function createHost(config, options = {}) {
|
|
|
396
454
|
allow: compiled.allow,
|
|
397
455
|
referrerPolicy: compiled.referrerPolicy,
|
|
398
456
|
colorScheme: scheme,
|
|
457
|
+
// A nested page's shell (P111): the config's word, never the frame's.
|
|
458
|
+
...(config.nested === true ? { nested: true } : {}),
|
|
399
459
|
// An app reports no size: its frame fills the host's container, at least the minimum;
|
|
400
460
|
// so does any display the host mounts to fill, or whose layout fills (P065): its
|
|
401
461
|
// content scrolls itself.
|
|
@@ -422,6 +482,27 @@ export function createHost(config, options = {}) {
|
|
|
422
482
|
})
|
|
423
483
|
: framed;
|
|
424
484
|
surface = created;
|
|
485
|
+
// The focus guard undid a move of the keyboard into this frame (P109): heard each time,
|
|
486
|
+
// and a frame that keeps taking it is stopped, as one that keeps navigating away is.
|
|
487
|
+
const takes = [];
|
|
488
|
+
created.onFocusTaken?.(({ typing, failed }) => {
|
|
489
|
+
const at = Date.now();
|
|
490
|
+
// While the person typed, or a take-back that failed (the keys then go to the frame and
|
|
491
|
+
// the page sees no typing): either counts toward the first rule.
|
|
492
|
+
takes.push({ at, counts: typing || failed });
|
|
493
|
+
const within = (ms) => takes.filter((take) => at - take.at <= ms);
|
|
494
|
+
emit("focusTaken", { typing });
|
|
495
|
+
if (surface === created &&
|
|
496
|
+
(within(TAKES.typing.withinMs).filter((take) => take.counts).length >=
|
|
497
|
+
TAKES.typing.most ||
|
|
498
|
+
within(TAKES.any.withinMs).length >= TAKES.any.most)) {
|
|
499
|
+
stop();
|
|
500
|
+
contentError("The content kept taking the keyboard from the page; it was stopped.");
|
|
501
|
+
}
|
|
502
|
+
while (takes.length > 0 && at - takes[0].at > TAKES.typing.withinMs) {
|
|
503
|
+
takes.shift();
|
|
504
|
+
}
|
|
505
|
+
});
|
|
425
506
|
const watch = watchOutcome({
|
|
426
507
|
surface: created,
|
|
427
508
|
source,
|
|
@@ -456,6 +537,8 @@ export function createHost(config, options = {}) {
|
|
|
456
537
|
...(options.show === undefined ? {} : { show: options.show }),
|
|
457
538
|
...(options.cached === undefined ? {} : { cached: options.cached }),
|
|
458
539
|
userActivation: () => created.userActivation(),
|
|
540
|
+
// The person in this frame (P109): the page's focus in it, after the focus guard.
|
|
541
|
+
focused: () => created.focused?.(),
|
|
459
542
|
onEvent: onBridge,
|
|
460
543
|
...(declaration === null ? {} : { declaration }),
|
|
461
544
|
...(viewer === undefined ? {} : { viewer }),
|
|
@@ -463,6 +546,17 @@ export function createHost(config, options = {}) {
|
|
|
463
546
|
if (annotates) {
|
|
464
547
|
created.transport.listen((raw) => onAnnotation(raw, opening));
|
|
465
548
|
}
|
|
549
|
+
// Whether the page used storage (P111): once per run, the page's word (a count, no more).
|
|
550
|
+
created.transport.listen((raw) => {
|
|
551
|
+
if (!storageTold &&
|
|
552
|
+
isRecord(raw) &&
|
|
553
|
+
raw.jsonrpc === "2.0" &&
|
|
554
|
+
raw.method === STORAGE_USED_METHOD &&
|
|
555
|
+
!("id" in raw)) {
|
|
556
|
+
storageTold = true;
|
|
557
|
+
emit("storage", { used: true });
|
|
558
|
+
}
|
|
559
|
+
});
|
|
466
560
|
bridge = opening;
|
|
467
561
|
const opened = adapter.connect({
|
|
468
562
|
display: { id: mount.displayId, title: mount.title },
|
|
@@ -571,6 +665,9 @@ export function createHost(config, options = {}) {
|
|
|
571
665
|
restarts = 0;
|
|
572
666
|
run();
|
|
573
667
|
},
|
|
668
|
+
focus() {
|
|
669
|
+
surface?.focus?.();
|
|
670
|
+
},
|
|
574
671
|
destroy() {
|
|
575
672
|
destroyed = true;
|
|
576
673
|
stop();
|
|
@@ -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
|
@@ -205,6 +205,25 @@ export interface DisplayEvents {
|
|
|
205
205
|
};
|
|
206
206
|
/** Too many declines: the display stops asking until it runs again. */
|
|
207
207
|
readonly muted: undefined;
|
|
208
|
+
/**
|
|
209
|
+
* The content moved the keyboard into its frame from one of the page's text fields without the
|
|
210
|
+
* person (no press on the frame, no Tab, P109), and focus went back where it was; `typing`: the
|
|
211
|
+
* person had pressed a key on the page within the last second. The content's doing. Three while
|
|
212
|
+
* typing within 10 s, or five within 2 s, stop the display (`contentError` says so; `reload()`
|
|
213
|
+
* runs it again).
|
|
214
|
+
*/
|
|
215
|
+
readonly focusTaken: {
|
|
216
|
+
readonly typing: boolean;
|
|
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
|
+
};
|
|
208
227
|
/**
|
|
209
228
|
* What the frame reported about annotations (`annotate`, P053), checked and taken only while
|
|
210
229
|
* the host asked for it: a selection, its clearing, a cancelled pick, where marks are. The
|
|
@@ -224,6 +243,13 @@ export interface AnnotationControls {
|
|
|
224
243
|
show(marks: readonly AnnotationMark[]): void;
|
|
225
244
|
/** Brings a mark into view in the frame and makes it the active one. */
|
|
226
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;
|
|
227
253
|
/** Removes every mark. */
|
|
228
254
|
clear(): void;
|
|
229
255
|
}
|
|
@@ -241,6 +267,11 @@ export interface DisplayControls {
|
|
|
241
267
|
readonly annotations: AnnotationControls;
|
|
242
268
|
/** Runs the content again from the start, in a new frame. */
|
|
243
269
|
reload(): void;
|
|
270
|
+
/**
|
|
271
|
+
* Moves focus into the display's frame, as the host's own move: from one of the page's text
|
|
272
|
+
* fields, a frame's own `focus()` is taken for the content's and undone (P109).
|
|
273
|
+
*/
|
|
274
|
+
focus(): void;
|
|
244
275
|
/** Tears the view down and removes the frame. */
|
|
245
276
|
destroy(): void;
|
|
246
277
|
}
|
|
@@ -253,4 +284,10 @@ export interface PortholeHost<C extends AdapterConnection = ShellConnection> {
|
|
|
253
284
|
* none (here or in the host's options), so a manual never teaches a function nobody serves.
|
|
254
285
|
*/
|
|
255
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;
|
|
256
293
|
}
|
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,8 @@ 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";
|
|
41
|
+
export { focusField } from "./platform/focus-guard.ts";
|
|
38
42
|
export { entryTarget, frameFallback, portholeClient, type ContentClientMeta, type FrameFallback, type PortholeClient, type PortholeClientOptions, } from "./host/client.ts";
|
|
39
43
|
export { defineDisplays, type DisplayKind, type Displays } from "./displays/displays.ts";
|
|
40
44
|
export { fragmentOf, lintContent, type Finding, type LintRule } from "./check/lint.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,8 @@ 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";
|
|
42
|
+
export { focusField } from "./platform/focus-guard.js";
|
|
39
43
|
// The client half of the host kit, and the display registry (P072).
|
|
40
44
|
export { entryTarget, frameFallback, portholeClient, } from "./host/client.js";
|
|
41
45
|
export { defineDisplays } from "./displays/displays.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";
|