@botiverse/porthole 0.12.0 → 0.13.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/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/config/capabilities.d.ts +16 -3
- package/dist/config/capabilities.js +1 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/guide/runtime.js +1 -1
- package/dist/host/create-host.js +27 -0
- package/dist/host/types.d.ts +15 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/platform/focus-guard.d.ts +143 -0
- package/dist/platform/focus-guard.js +445 -0
- package/dist/platform/types.d.ts +18 -0
- package/dist/platform/web.js +22 -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/docs/ADOPTING.md +85 -6
- package/docs/DECISIONS.md +355 -5
- package/docs/DESIGN.md +9 -2
- package/docs/THREAT_MODEL.md +121 -29
- package/package.json +1 -1
- 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/config/capabilities.ts +16 -3
- package/src/guide/runtime.ts +1 -1
- package/src/host/create-host.ts +29 -0
- package/src/host/types.ts +13 -0
- package/src/index.ts +1 -0
- package/src/platform/focus-guard.ts +572 -0
- package/src/platform/types.ts +17 -0
- package/src/platform/web.ts +22 -0
- package/src/react/frame.tsx +10 -0
- package/src/runtime/requests.ts +36 -14
- package/src/runtime/types.generated.ts +1 -1
- package/types/runtime/v1/comments.d.ts +8 -4
package/dist/check/scroll.d.ts
CHANGED
|
@@ -10,7 +10,9 @@
|
|
|
10
10
|
* - body with overflow-y hidden or clip, where html's overflow is visible (body's then becomes the
|
|
11
11
|
* viewport's) or body is one screen tall;
|
|
12
12
|
* - the root with overflow-y hidden or clip and one screen tall;
|
|
13
|
-
* - any of them position: fixed and one screen tall (a fixed box's content scrolls nothing)
|
|
13
|
+
* - any of them position: fixed and one screen tall (a fixed box's content scrolls nothing), and
|
|
14
|
+
* body fixed whatever its height, unless it scrolls itself (where html's overflow is visible,
|
|
15
|
+
* body's is the viewport's and body itself doesn't: P110);
|
|
14
16
|
* and nothing in the page's markup below body that scrolls itself: no element there with style=""
|
|
15
17
|
* or a Tailwind utility giving it overflow-y auto or scroll, or matched by a rule the check reads
|
|
16
18
|
* that does (a rule whose selector it can't read, or that matches nothing in the markup, doesn't
|
|
@@ -26,7 +28,8 @@
|
|
|
26
28
|
* and bottom set (`inset: 0`).
|
|
27
29
|
*
|
|
28
30
|
* What it reads: the page's `<style>` elements, the stylesheets it links that the caller finds
|
|
29
|
-
* (a version's own files) and what they `@import`, in document order; style="" on
|
|
31
|
+
* (a version's own files) and what they `@import`, in document order; style="" on body and the
|
|
32
|
+
* root (not html's: the shell drops it, P110); the
|
|
30
33
|
* class rules that match their classes; and, where the page loads Tailwind from its CDN, the few
|
|
31
34
|
* Tailwind utilities that hold a page (h-screen, overflow-hidden, fixed, inset-0…). Specificity,
|
|
32
35
|
* order, !important and cascade layers decide between rules, so a later override is seen.
|
|
@@ -41,7 +44,8 @@
|
|
|
41
44
|
*
|
|
42
45
|
* Bounded: each stylesheet is read once per page, as it streams (nothing parsed is kept past the
|
|
43
46
|
* rule it is in, a rule's selectors one at a time), at most `SHEETS` of them and `READ` bytes in
|
|
44
|
-
* all, its own `<style>` included; past that, the rest isn't read
|
|
47
|
+
* all, its own `<style>` included; past that, the rest isn't read, nor asked for, and a sheet is
|
|
48
|
+
* decoded only once its size is taken (P110). At most `MOST_LAYERS` layers a
|
|
45
49
|
* page, each named in at most `LONGEST_LAYER` characters: a new one past either isn't read. Each
|
|
46
50
|
* element keeps, per property, only each layer's winner so far, and a compound is matched against
|
|
47
51
|
* an element's classes (a set) in bounded work, so time and memory are linear in what it reads. A
|
|
@@ -54,18 +58,25 @@
|
|
|
54
58
|
* HTML doesn't have; the fix is then !important where the name has less specificity than the
|
|
55
59
|
* selector).
|
|
56
60
|
*/
|
|
57
|
-
/**
|
|
61
|
+
/**
|
|
62
|
+
* A stylesheet the page links, as the caller finds it from `from` (a path), or null: its path, the
|
|
63
|
+
* fewest characters it may hold (`least`: a string's length; as bytes, a third of them, less a
|
|
64
|
+
* BOM's), and its text (at least its first `SCANNED` characters), decoded only where the rule may
|
|
65
|
+
* read it (P110: one page linking 400 sheets decoded and kept all of them, though the rule reads at
|
|
66
|
+
* most `SHEETS`, `READ` characters in all).
|
|
67
|
+
*/
|
|
58
68
|
export type LinkedSheet = (href: string, from: string) => {
|
|
59
69
|
readonly path: string;
|
|
60
|
-
readonly
|
|
70
|
+
readonly least: number;
|
|
71
|
+
readonly text: () => string;
|
|
61
72
|
} | null;
|
|
62
73
|
export interface ScrollLock {
|
|
63
74
|
/** What to change, for the agent. */
|
|
64
75
|
readonly message: string;
|
|
65
76
|
/** The file the rule that holds it is in (the page's own `path`, or a stylesheet's). */
|
|
66
77
|
readonly path?: string;
|
|
67
|
-
/** Its line (1-based). */
|
|
68
|
-
readonly line
|
|
78
|
+
/** Its line (1-based); none where the page couldn't be checked (P110). */
|
|
79
|
+
readonly line?: number;
|
|
69
80
|
}
|
|
70
81
|
/** The most stylesheets read for one page, each once. */
|
|
71
82
|
export declare const SHEETS = 32;
|
|
@@ -87,14 +98,19 @@ export interface ScrollBudget {
|
|
|
87
98
|
}
|
|
88
99
|
/** A version's budget, for one `lintFiles`. */
|
|
89
100
|
export declare const scrollBudget: () => ScrollBudget;
|
|
90
|
-
|
|
91
|
-
* Whether `page`'s own styles hold it to one screen, and what to tell the agent; null where they
|
|
92
|
-
* don't (or where it can't tell). `sheet` finds what the page links (a version's own files).
|
|
93
|
-
*/
|
|
94
|
-
export declare function scrollLock(page: string, options: {
|
|
101
|
+
interface ScrollOptions {
|
|
95
102
|
readonly noun: string;
|
|
96
103
|
readonly path?: string;
|
|
97
104
|
readonly sheet?: LinkedSheet;
|
|
98
105
|
/** The version's, shared by its pages (`scrollBudget()`); else this page's own. */
|
|
99
106
|
readonly budget?: ScrollBudget;
|
|
100
|
-
}
|
|
107
|
+
}
|
|
108
|
+
/**
|
|
109
|
+
* Whether `page`'s own styles hold it to one screen, and what to tell the agent; null where they
|
|
110
|
+
* don't (or where it can't tell). `sheet` finds what the page links (a version's own files).
|
|
111
|
+
* Advisory, so it fails soft (P110): a throw in it is this page not checked, said as such (no
|
|
112
|
+
* line), never a failed lint (a CSS escape past U+10FFFF threw out of `admitContent` and
|
|
113
|
+
* `admitFiles` in 0.11).
|
|
114
|
+
*/
|
|
115
|
+
export declare function scrollLock(page: string, options: ScrollOptions): ScrollLock | null;
|
|
116
|
+
export {};
|
package/dist/check/scroll.js
CHANGED
|
@@ -394,7 +394,11 @@ function identAt(text, at) {
|
|
|
394
394
|
if (code === "\\") {
|
|
395
395
|
const hex = /^[0-9a-f]{1,6}\s?/iu.exec(text.slice(index + 1, index + 8));
|
|
396
396
|
if (hex !== null) {
|
|
397
|
-
|
|
397
|
+
// CSS Syntax's "consume an escaped code point": 0, a surrogate or past U+10FFFF is U+FFFD
|
|
398
|
+
// (six hex digits reach 0xFFFFFF, which String.fromCodePoint throws on: P110).
|
|
399
|
+
const point = Number.parseInt(hex[0].trim(), 16);
|
|
400
|
+
const valid = point !== 0 && point <= 0x10ffff && (point < 0xd800 || point > 0xdfff);
|
|
401
|
+
value += String.fromCodePoint(valid ? point : 0xfffd);
|
|
398
402
|
index += 1 + hex[0].length;
|
|
399
403
|
}
|
|
400
404
|
else if (index + 1 < text.length) {
|
|
@@ -775,18 +779,38 @@ class Cascade {
|
|
|
775
779
|
this.bytes += size;
|
|
776
780
|
return true;
|
|
777
781
|
}
|
|
778
|
-
/**
|
|
782
|
+
/**
|
|
783
|
+
* Whether nothing more may be read for this page: `SHEETS` read, `READ` spent, or the version's
|
|
784
|
+
* budget. Then no sheet is asked for (P110).
|
|
785
|
+
*/
|
|
786
|
+
full() {
|
|
787
|
+
return this.read.size >= SHEETS || this.bytes >= READ || this.budget.spent;
|
|
788
|
+
}
|
|
789
|
+
/**
|
|
790
|
+
* A stylesheet's first `SCANNED` characters, if it may still be read for this page (once, within
|
|
791
|
+
* the budget), else null. The caps count characters, whatever the caller gives: where even its
|
|
792
|
+
* fewest are past what's left, it is refused before it is decoded (past the version's budget,
|
|
793
|
+
* spent); else it is decoded, cut, and charged what it holds, or dropped if that doesn't fit.
|
|
794
|
+
*/
|
|
779
795
|
take(found) {
|
|
780
796
|
if (found === null || this.read.has(found.path) || this.read.size >= SHEETS) {
|
|
781
|
-
return
|
|
797
|
+
return null;
|
|
782
798
|
}
|
|
783
|
-
const
|
|
784
|
-
if (this.bytes +
|
|
785
|
-
return
|
|
799
|
+
const least = Math.min(found.least, SCANNED);
|
|
800
|
+
if (this.bytes + least > READ) {
|
|
801
|
+
return null;
|
|
802
|
+
}
|
|
803
|
+
if (this.budget.spent || least > this.budget.bytes) {
|
|
804
|
+
this.budget.spent = true;
|
|
805
|
+
return null;
|
|
806
|
+
}
|
|
807
|
+
const text = found.text().slice(0, SCANNED);
|
|
808
|
+
if (this.bytes + text.length > READ || !this.spend(text.length)) {
|
|
809
|
+
return null;
|
|
786
810
|
}
|
|
787
811
|
this.read.add(found.path);
|
|
788
|
-
this.bytes +=
|
|
789
|
-
return
|
|
812
|
+
this.bytes += text.length;
|
|
813
|
+
return text;
|
|
790
814
|
}
|
|
791
815
|
/**
|
|
792
816
|
* A declaration for `node`, kept where it wins so far within its layer (and !important,
|
|
@@ -910,12 +934,19 @@ class Cascade {
|
|
|
910
934
|
}
|
|
911
935
|
take(to);
|
|
912
936
|
}
|
|
913
|
-
/**
|
|
914
|
-
|
|
915
|
-
|
|
937
|
+
/**
|
|
938
|
+
* A stylesheet the page links or a sheet imports (`href`, from `from`), if it may still be read:
|
|
939
|
+
* asked for only while the page may read more, decoded only once taken.
|
|
940
|
+
*/
|
|
941
|
+
file(href, from, layer) {
|
|
942
|
+
if (this.full()) {
|
|
943
|
+
return;
|
|
944
|
+
}
|
|
945
|
+
const found = this.find(href, from);
|
|
946
|
+
const text = this.take(found);
|
|
947
|
+
if (found === null || text === null) {
|
|
916
948
|
return;
|
|
917
949
|
}
|
|
918
|
-
const text = found.text.slice(0, SCANNED);
|
|
919
950
|
this.sheet(withoutComments(text), 0, text.length, {
|
|
920
951
|
source: { path: found.path, text },
|
|
921
952
|
base: 0,
|
|
@@ -1051,7 +1082,7 @@ class Cascade {
|
|
|
1051
1082
|
return;
|
|
1052
1083
|
}
|
|
1053
1084
|
}
|
|
1054
|
-
this.file(
|
|
1085
|
+
this.file(href, context.from, layer);
|
|
1055
1086
|
}
|
|
1056
1087
|
}
|
|
1057
1088
|
/** A value of a shape the check knows, as the agent may be told it; else its property alone. */
|
|
@@ -1092,8 +1123,22 @@ const lineOf = (text, index) => {
|
|
|
1092
1123
|
/**
|
|
1093
1124
|
* Whether `page`'s own styles hold it to one screen, and what to tell the agent; null where they
|
|
1094
1125
|
* don't (or where it can't tell). `sheet` finds what the page links (a version's own files).
|
|
1126
|
+
* Advisory, so it fails soft (P110): a throw in it is this page not checked, said as such (no
|
|
1127
|
+
* line), never a failed lint (a CSS escape past U+10FFFF threw out of `admitContent` and
|
|
1128
|
+
* `admitFiles` in 0.11).
|
|
1095
1129
|
*/
|
|
1096
1130
|
export function scrollLock(page, options) {
|
|
1131
|
+
try {
|
|
1132
|
+
return readScrollLock(page, options);
|
|
1133
|
+
}
|
|
1134
|
+
catch {
|
|
1135
|
+
return {
|
|
1136
|
+
message: `The ${options.noun} wasn't checked for scroll lock: its styles couldn't be read. If it holds html, body or its root to one screen (overflow: hidden with height: 100% or 100vh, or position: fixed), let it scroll as a document.`,
|
|
1137
|
+
...(options.path === undefined ? {} : { path: options.path }),
|
|
1138
|
+
};
|
|
1139
|
+
}
|
|
1140
|
+
}
|
|
1141
|
+
function readScrollLock(page, options) {
|
|
1097
1142
|
const shared = options.budget ?? { bytes: Infinity, steps: Infinity, spent: false };
|
|
1098
1143
|
if (shared.spent) {
|
|
1099
1144
|
return null;
|
|
@@ -1117,7 +1162,9 @@ export function scrollLock(page, options) {
|
|
|
1117
1162
|
};
|
|
1118
1163
|
};
|
|
1119
1164
|
const chain = [
|
|
1120
|
-
|
|
1165
|
+
// Not html's style="": the shell imports a page's html attributes but that one
|
|
1166
|
+
// (`renderDocument`), so it never applies in Porthole's frame (P110).
|
|
1167
|
+
{ ...nodeOf(scanned.html, "html", "html", false), style: null },
|
|
1121
1168
|
nodeOf(scanned.body, "body", "body", false),
|
|
1122
1169
|
];
|
|
1123
1170
|
const rootTag = scanned.body !== null && scanned.contentCount === 1 ? scanned.content[0] : undefined;
|
|
@@ -1174,7 +1221,7 @@ export function scrollLock(page, options) {
|
|
|
1174
1221
|
href === "") {
|
|
1175
1222
|
continue;
|
|
1176
1223
|
}
|
|
1177
|
-
cascade.file(
|
|
1224
|
+
cascade.file(href, from, null);
|
|
1178
1225
|
}
|
|
1179
1226
|
for (const node of chain) {
|
|
1180
1227
|
if (node.style !== null) {
|
|
@@ -1288,7 +1335,10 @@ export function scrollLock(page, options) {
|
|
|
1288
1335
|
}
|
|
1289
1336
|
const height = tall("height");
|
|
1290
1337
|
const maxHeight = tall("max-height");
|
|
1291
|
-
|
|
1338
|
+
// A fixed body holds the page whatever its height (P110): a fixed box adds nothing to what the
|
|
1339
|
+
// frame scrolls, so `body { position: fixed; top: 0 }`, the scroll-lock libraries' way, does.
|
|
1340
|
+
const fixedBody = index === 1 && position?.value === "fixed";
|
|
1341
|
+
if (positioned && position !== undefined && (spanned || height || maxHeight || fixedBody)) {
|
|
1292
1342
|
shown.unshift(position);
|
|
1293
1343
|
}
|
|
1294
1344
|
states.push({ screen: height || maxHeight || spanned, shown, position: position?.value ?? "" });
|
|
@@ -1312,10 +1362,14 @@ export function scrollLock(page, options) {
|
|
|
1312
1362
|
return found !== undefined && !CONTENT_HEIGHT.test(found) && !PARENT.test(found);
|
|
1313
1363
|
});
|
|
1314
1364
|
};
|
|
1365
|
+
// An element's own overflow-y: body's is the viewport's where html's overflow is visible, and
|
|
1366
|
+
// body's own is then visible (P110: `body { position: fixed; inset: 0; overflow: auto }` doesn't
|
|
1367
|
+
// scroll itself, the viewport takes its auto).
|
|
1368
|
+
const ownOverflowY = (index, node) => index === 1 && htmlVisible ? "visible" : overflowY(node);
|
|
1315
1369
|
const scrollBox = (index) => {
|
|
1316
1370
|
const node = chain[index];
|
|
1317
1371
|
return (node !== undefined &&
|
|
1318
|
-
SCROLLS.has(
|
|
1372
|
+
SCROLLS.has(ownOverflowY(index, node)) &&
|
|
1319
1373
|
((states[index]?.screen ?? false) || unread(index)));
|
|
1320
1374
|
};
|
|
1321
1375
|
const holds = [];
|
|
@@ -1330,7 +1384,9 @@ export function scrollLock(page, options) {
|
|
|
1330
1384
|
const clips = CLIPS.has(overflowY(node));
|
|
1331
1385
|
const overflow = value(node, "overflow-y");
|
|
1332
1386
|
const clipped = clips && (index === 0 ? true : index === 1 ? state.screen || htmlVisible : state.screen);
|
|
1333
|
-
const fixed = state.position === "fixed" &&
|
|
1387
|
+
const fixed = state.position === "fixed" &&
|
|
1388
|
+
(state.screen || index === 1) &&
|
|
1389
|
+
!SCROLLS.has(ownOverflowY(index, node));
|
|
1334
1390
|
if (!clipped && !fixed) {
|
|
1335
1391
|
continue;
|
|
1336
1392
|
}
|
|
@@ -15,9 +15,14 @@ export type CapabilityName = (typeof CAPABILITY_NAMES)[number];
|
|
|
15
15
|
/**
|
|
16
16
|
* What must hold before a call reaches the host's handler. A capability's gates all apply.
|
|
17
17
|
*
|
|
18
|
-
* - `user-activation`: the call follows a real user gesture
|
|
19
|
-
*
|
|
20
|
-
*
|
|
18
|
+
* - `user-activation`: the call follows a real user gesture. The shell refuses a call without one
|
|
19
|
+
* in its frame, but that check is the page's own (a page posts the call itself and skips it).
|
|
20
|
+
* The host checks its own page's transient activation, which a gesture in a child frame
|
|
21
|
+
* propagates to, and which lasts 5 s after any gesture anywhere on the host's page: a click on
|
|
22
|
+
* the host's own UI, or the person typing in its own composer, counts. So it stops calls made on
|
|
23
|
+
* load, or on a timer while nobody does anything; it is not proof that the gesture was in this
|
|
24
|
+
* frame, nor of intent. Where a capability needs that (`comments`, P109: its draft goes into
|
|
25
|
+
* the person's composer), the host also asks that its page's focus be in the calling frame.
|
|
21
26
|
* - `confirm`: the host's `confirm` function shows a person the call's whole effect, and the call
|
|
22
27
|
* goes only if they accept. No `confirm` function means the call is refused (fail closed).
|
|
23
28
|
* - `rateLimit`: at most `perMinute` calls per display per minute; the rest are refused.
|
|
@@ -53,6 +58,13 @@ export interface CapabilitySpec {
|
|
|
53
58
|
readonly method: string;
|
|
54
59
|
readonly sdk?: string;
|
|
55
60
|
};
|
|
61
|
+
/**
|
|
62
|
+
* Its `user-activation` gate also needs the person in the calling frame (P109): the host page's
|
|
63
|
+
* focus in that frame, which a press on it or a Tab into it gives and the focus guard keeps from
|
|
64
|
+
* a frame's own `focus()`. Activation alone lasts 5 s after any gesture on the host's page,
|
|
65
|
+
* typing in its own composer included.
|
|
66
|
+
*/
|
|
67
|
+
readonly inFrame?: true;
|
|
56
68
|
}
|
|
57
69
|
/** The most text one `copyText` call carries. */
|
|
58
70
|
export declare const MAX_COPY_CHARS = 20000;
|
|
@@ -174,6 +186,7 @@ export declare const CAPABILITIES: {
|
|
|
174
186
|
readonly request: {
|
|
175
187
|
readonly method: "porthole/call";
|
|
176
188
|
};
|
|
189
|
+
readonly inFrame: true;
|
|
177
190
|
};
|
|
178
191
|
/** This artifact's current version, and a new version of it, base-checked (P088). */
|
|
179
192
|
readonly artifact: {
|
|
@@ -109,6 +109,7 @@ export const CAPABILITIES = {
|
|
|
109
109
|
defaultGates: ["user-activation", rate(30)],
|
|
110
110
|
served: "handler",
|
|
111
111
|
request: { method: "porthole/call" },
|
|
112
|
+
inFrame: true,
|
|
112
113
|
},
|
|
113
114
|
/** This artifact's current version, and a new version of it, base-checked (P088). */
|
|
114
115
|
artifact: { defaultGates: [rate(10)], served: "handler", request: { method: "porthole/call" } },
|