@botiverse/porthole 0.10.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/annotate/types.d.ts +18 -6
- package/dist/annotate/validate.d.ts +11 -1
- package/dist/annotate/validate.js +18 -1
- 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.d.ts +2 -0
- package/dist/check/files.js +71 -50
- package/dist/check/lint.d.ts +8 -1
- package/dist/check/lint.js +18 -0
- package/dist/check/markup.d.ts +7 -0
- package/dist/check/markup.js +49 -0
- package/dist/check/page-source.js +1 -1
- package/dist/check/scroll.d.ts +116 -0
- package/dist/check/scroll.js +1485 -0
- 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/conformance/runtime.js +6 -0
- package/dist/guide/guide.js +1 -1
- package/dist/guide/runtime.js +2 -2
- package/dist/host/create-host.js +30 -3
- package/dist/host/types.d.ts +15 -0
- package/dist/index.d.ts +2 -1
- 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 +10 -1
- package/dist/react/frame.js +4 -0
- package/dist/runtime/requests.d.ts +5 -0
- package/dist/runtime/requests.js +41 -4
- package/dist/runtime/types.generated.js +1 -1
- package/dist/shell/annotate.d.ts +2 -1
- package/dist/shell/annotate.js +29 -12
- package/dist/shell/use.js +9 -1
- package/docs/ADOPTING.md +106 -5
- package/docs/ARCHITECTURE.md +2 -1
- package/docs/DECISIONS.md +741 -2
- package/docs/DESIGN.md +38 -9
- package/docs/THREAT_MODEL.md +146 -19
- package/package.json +1 -1
- package/src/annotate/types.ts +19 -6
- package/src/annotate/validate.ts +20 -1
- package/src/bridge/bridge.ts +17 -1
- package/src/bridge/unseen.ts +24 -0
- package/src/check/files.ts +72 -54
- package/src/check/lint.ts +24 -0
- package/src/check/markup.ts +53 -0
- package/src/check/scroll.ts +1825 -0
- package/src/config/capabilities.ts +16 -3
- package/src/conformance/runtime.ts +9 -0
- package/src/guide/guide.ts +1 -0
- package/src/guide/runtime.ts +2 -2
- package/src/host/create-host.ts +38 -3
- package/src/host/types.ts +13 -0
- package/src/index.ts +2 -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 +12 -1
- package/src/runtime/requests.ts +50 -6
- package/src/runtime/types.generated.ts +1 -1
- package/src/shell/annotate.ts +29 -12
- package/src/shell/use.ts +9 -1
- package/types/runtime/v1/comments.d.ts +20 -6
package/src/check/files.ts
CHANGED
|
@@ -8,7 +8,9 @@ import {
|
|
|
8
8
|
} from "../files/paths.ts";
|
|
9
9
|
import { fileTypeOf, knownType } from "../files/types.ts";
|
|
10
10
|
import { sizeWords } from "../guide/limits.ts";
|
|
11
|
-
import {
|
|
11
|
+
import { lintPage, type Finding } from "./lint.ts";
|
|
12
|
+
import { attributesOf } from "./markup.ts";
|
|
13
|
+
import { scrollBudget, scrollLock, type LinkedSheet } from "./scroll.ts";
|
|
12
14
|
|
|
13
15
|
/**
|
|
14
16
|
* What can be told about a page that comes with files (P081), without running it: each page
|
|
@@ -82,58 +84,6 @@ const REFERENCE_ATTRIBUTES: Readonly<Record<string, readonly string[]>> = {
|
|
|
82
84
|
/** A tag: its name and its attributes' text. Bounded, and never across another `<`: linear. */
|
|
83
85
|
const TAG = /<([a-z][a-z0-9-]{0,30})\b([^<>]{0,8192})>/giu;
|
|
84
86
|
|
|
85
|
-
const isSpace = (code: number): boolean =>
|
|
86
|
-
code === 32 || code === 9 || code === 10 || code === 12 || code === 13;
|
|
87
|
-
|
|
88
|
-
/** A tag's attributes, read once from left to right (linear): each name, value and its offset. */
|
|
89
|
-
function attributesOf(text: string): { name: string; value: string; at: number }[] {
|
|
90
|
-
const out: { name: string; value: string; at: number }[] = [];
|
|
91
|
-
let at = 0;
|
|
92
|
-
while (at < text.length) {
|
|
93
|
-
while (at < text.length && (isSpace(text.charCodeAt(at)) || text[at] === "/")) {
|
|
94
|
-
at += 1;
|
|
95
|
-
}
|
|
96
|
-
const nameStart = at;
|
|
97
|
-
while (
|
|
98
|
-
at < text.length &&
|
|
99
|
-
!isSpace(text.charCodeAt(at)) &&
|
|
100
|
-
text[at] !== "=" &&
|
|
101
|
-
text[at] !== "/"
|
|
102
|
-
) {
|
|
103
|
-
at += 1;
|
|
104
|
-
}
|
|
105
|
-
const name = text.slice(nameStart, at).toLowerCase();
|
|
106
|
-
if (name === "") {
|
|
107
|
-
at += 1;
|
|
108
|
-
continue;
|
|
109
|
-
}
|
|
110
|
-
while (at < text.length && isSpace(text.charCodeAt(at))) {
|
|
111
|
-
at += 1;
|
|
112
|
-
}
|
|
113
|
-
if (text[at] !== "=") {
|
|
114
|
-
continue;
|
|
115
|
-
}
|
|
116
|
-
at += 1;
|
|
117
|
-
while (at < text.length && isSpace(text.charCodeAt(at))) {
|
|
118
|
-
at += 1;
|
|
119
|
-
}
|
|
120
|
-
const quote = text[at];
|
|
121
|
-
if (quote === '"' || quote === "'") {
|
|
122
|
-
const close = text.indexOf(quote, at + 1);
|
|
123
|
-
const end = close < 0 ? text.length : close;
|
|
124
|
-
out.push({ name, value: text.slice(at + 1, end), at: at + 1 });
|
|
125
|
-
at = end + 1;
|
|
126
|
-
} else {
|
|
127
|
-
const start = at;
|
|
128
|
-
while (at < text.length && !isSpace(text.charCodeAt(at))) {
|
|
129
|
-
at += 1;
|
|
130
|
-
}
|
|
131
|
-
out.push({ name, value: text.slice(start, at), at: start });
|
|
132
|
-
}
|
|
133
|
-
}
|
|
134
|
-
return out;
|
|
135
|
-
}
|
|
136
|
-
|
|
137
87
|
/** What a page's markup loads or links: each element's `src`, `href` or `poster`. */
|
|
138
88
|
function markupReferences(text: string): Reference[] {
|
|
139
89
|
const found: Reference[] = [];
|
|
@@ -225,6 +175,9 @@ function resolve(directory: string, reference: string): string | null {
|
|
|
225
175
|
|
|
226
176
|
const directoryOf = (path: string): string => path.slice(0, path.lastIndexOf("/") + 1);
|
|
227
177
|
|
|
178
|
+
/** The most pages the scroll-lock rule reads in a version: its entry, and 7 more (P106). */
|
|
179
|
+
export const SCROLL_PAGES = 8;
|
|
180
|
+
|
|
228
181
|
/**
|
|
229
182
|
* Lints a page that comes with files (P081): the set (paths, limits, its entry), each page as
|
|
230
183
|
* `lintContent` lints a page, each relative reference looked up in the set (a leading `/`, which
|
|
@@ -319,7 +272,34 @@ export function lintFiles(
|
|
|
319
272
|
}
|
|
320
273
|
}
|
|
321
274
|
};
|
|
275
|
+
// A stylesheet a page links or a stylesheet imports, found in the set by its path (P106). The
|
|
276
|
+
// fewest characters it may hold first: the rule decodes its text only where it may read it, and
|
|
277
|
+
// nothing keeps it after (P110: kept for the set, one page linking 400 sheets of 240 KB held
|
|
278
|
+
// them all, 200 MB, for the 4 MiB the rule reads).
|
|
279
|
+
const stylesheet: LinkedSheet = (href, from) => {
|
|
280
|
+
if (href === "" || elsewhere(href) || href.startsWith("/")) {
|
|
281
|
+
return null;
|
|
282
|
+
}
|
|
283
|
+
const target = resolve(directoryOf(from), href);
|
|
284
|
+
const sheet = target === null || !has(target) ? undefined : files[target];
|
|
285
|
+
if (sheet === undefined || target === null) {
|
|
286
|
+
return null;
|
|
287
|
+
}
|
|
288
|
+
// As bytes, at most 3 a character (after a BOM's 3): its fewest characters, and the bytes that
|
|
289
|
+
// hold its first SCANNED.
|
|
290
|
+
return typeof sheet === "string"
|
|
291
|
+
? { path: target, least: sheet.length, text: () => sheet }
|
|
292
|
+
: {
|
|
293
|
+
path: target,
|
|
294
|
+
least: Math.max(0, Math.ceil(sheet.byteLength / 3) - 1),
|
|
295
|
+
text: () => textOf(sheet.subarray(0, 3 * SCANNED + 3)),
|
|
296
|
+
};
|
|
297
|
+
};
|
|
298
|
+
const it = config.mode === "mcp-app" ? "view" : config.mode === "inline" ? "widget" : "page";
|
|
322
299
|
const maxPage = config.limits.maxBytes;
|
|
300
|
+
// The version's pages, read, for the scroll-lock rule after the rest (P106). A page over its
|
|
301
|
+
// limit isn't read at all: its error says so.
|
|
302
|
+
const pages = new Set<string>();
|
|
323
303
|
for (const [path, body] of Object.entries(files)) {
|
|
324
304
|
const { role } = fileTypeOf(path);
|
|
325
305
|
if (!knownType(path)) {
|
|
@@ -344,9 +324,12 @@ export function lintFiles(
|
|
|
344
324
|
continue;
|
|
345
325
|
}
|
|
346
326
|
const text = textOf(body);
|
|
347
|
-
|
|
327
|
+
// The scroll-lock rule apart, with the stylesheets the page links (P106).
|
|
328
|
+
for (const finding of lintPage(config, text, { scrollLock: false })) {
|
|
348
329
|
findings.push({ ...finding, path });
|
|
349
330
|
}
|
|
331
|
+
// Its path only: the few the rule reads are decoded again there, one at a time.
|
|
332
|
+
pages.add(path);
|
|
350
333
|
const lines = linesOf(text);
|
|
351
334
|
check(path, lines, markupReferences(text), directory, "error");
|
|
352
335
|
check(path, lines, patternReferences(text, CSS_REFERENCES), directory, "warning");
|
|
@@ -376,6 +359,41 @@ export function lintFiles(
|
|
|
376
359
|
);
|
|
377
360
|
}
|
|
378
361
|
}
|
|
362
|
+
// Its own styles holding a page to one screen (P106): the entry first, then the others in path
|
|
363
|
+
// order, at most SCROLL_PAGES, within one budget for them all. A warning: past either, the pages
|
|
364
|
+
// left aren't checked, and it says how many.
|
|
365
|
+
const budget = scrollBudget();
|
|
366
|
+
const order = [
|
|
367
|
+
...(pages.has(entry) ? [entry] : []),
|
|
368
|
+
...[...pages].filter((path) => path !== entry).sort(),
|
|
369
|
+
];
|
|
370
|
+
let checked = 0;
|
|
371
|
+
for (const path of order.slice(0, SCROLL_PAGES)) {
|
|
372
|
+
const body = files[path];
|
|
373
|
+
const text = body === undefined ? "" : textOf(body);
|
|
374
|
+
const held = scrollLock(text, { noun: it, path, sheet: stylesheet, budget });
|
|
375
|
+
if (budget.spent) {
|
|
376
|
+
break;
|
|
377
|
+
}
|
|
378
|
+
checked += 1;
|
|
379
|
+
if (held !== null) {
|
|
380
|
+
findings.push({
|
|
381
|
+
rule: "scroll-lock",
|
|
382
|
+
severity: "warning",
|
|
383
|
+
message: held.message,
|
|
384
|
+
path: held.path ?? path,
|
|
385
|
+
...(held.line === undefined ? {} : { line: held.line }),
|
|
386
|
+
});
|
|
387
|
+
}
|
|
388
|
+
}
|
|
389
|
+
const unchecked = pages.size - checked;
|
|
390
|
+
if (unchecked > 0) {
|
|
391
|
+
findings.push({
|
|
392
|
+
rule: "scroll-lock",
|
|
393
|
+
severity: "warning",
|
|
394
|
+
message: `${unchecked} page${unchecked === 1 ? "" : "s"} not checked for scroll lock: the check reads the entry and at most ${SCROLL_PAGES - 1} other pages, within one budget. If one of them 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.`,
|
|
395
|
+
});
|
|
396
|
+
}
|
|
379
397
|
return findings;
|
|
380
398
|
}
|
|
381
399
|
|
package/src/check/lint.ts
CHANGED
|
@@ -8,6 +8,7 @@ import {
|
|
|
8
8
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
9
9
|
import { sizeWords } from "../guide/limits.ts";
|
|
10
10
|
import { originMatchesSource } from "../isolation/served.ts";
|
|
11
|
+
import { scrollLock } from "./scroll.ts";
|
|
11
12
|
|
|
12
13
|
/**
|
|
13
14
|
* What can be told about content without running it (P073), worded as the manual words it, so
|
|
@@ -26,6 +27,7 @@ export type LintRule =
|
|
|
26
27
|
| "egress"
|
|
27
28
|
| "unpinned"
|
|
28
29
|
| "position-fixed"
|
|
30
|
+
| "scroll-lock"
|
|
29
31
|
| "new-window";
|
|
30
32
|
|
|
31
33
|
export interface Finding {
|
|
@@ -123,6 +125,18 @@ const OWN_CDN: readonly {
|
|
|
123
125
|
];
|
|
124
126
|
|
|
125
127
|
export function lintContent(config: PortholeConfig, content: string): Finding[] {
|
|
128
|
+
return lintPage(config, content, { scrollLock: true });
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* `lintContent`, with or without the scroll-lock rule: `lintFiles` reads that one itself, once,
|
|
133
|
+
* with the stylesheets the page links.
|
|
134
|
+
*/
|
|
135
|
+
export function lintPage(
|
|
136
|
+
config: PortholeConfig,
|
|
137
|
+
content: string,
|
|
138
|
+
options: { readonly scrollLock: boolean },
|
|
139
|
+
): Finding[] {
|
|
126
140
|
if (config.mode === "url") {
|
|
127
141
|
return [];
|
|
128
142
|
}
|
|
@@ -274,6 +288,16 @@ export function lintContent(config: PortholeConfig, content: string): Finding[]
|
|
|
274
288
|
);
|
|
275
289
|
}
|
|
276
290
|
}
|
|
291
|
+
// Its own styles holding it to one screen (P106): a warning, as a one-screen app means it.
|
|
292
|
+
const held = options.scrollLock ? scrollLock(content, { noun: it }) : null;
|
|
293
|
+
if (held !== null) {
|
|
294
|
+
findings.push({
|
|
295
|
+
rule: "scroll-lock",
|
|
296
|
+
severity: "warning",
|
|
297
|
+
message: held.message,
|
|
298
|
+
...(held.line === undefined ? {} : { line: held.line }),
|
|
299
|
+
});
|
|
300
|
+
}
|
|
277
301
|
const opens = /target\s*=\s*["']?_blank|\bwindow\s*\.\s*open\s*\(/u.exec(content);
|
|
278
302
|
if (opens !== null && !declared.has("openLink")) {
|
|
279
303
|
add(
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/** Reading markup without parsing it: what the checks share. Linear, however it was written. */
|
|
2
|
+
|
|
3
|
+
const isSpace = (code: number): boolean =>
|
|
4
|
+
code === 32 || code === 9 || code === 10 || code === 12 || code === 13;
|
|
5
|
+
|
|
6
|
+
/** A tag's attributes, read once from left to right (linear): each name, value and its offset. */
|
|
7
|
+
export function attributesOf(text: string): { name: string; value: string; at: number }[] {
|
|
8
|
+
const out: { name: string; value: string; at: number }[] = [];
|
|
9
|
+
let at = 0;
|
|
10
|
+
while (at < text.length) {
|
|
11
|
+
while (at < text.length && (isSpace(text.charCodeAt(at)) || text[at] === "/")) {
|
|
12
|
+
at += 1;
|
|
13
|
+
}
|
|
14
|
+
const nameStart = at;
|
|
15
|
+
while (
|
|
16
|
+
at < text.length &&
|
|
17
|
+
!isSpace(text.charCodeAt(at)) &&
|
|
18
|
+
text[at] !== "=" &&
|
|
19
|
+
text[at] !== "/"
|
|
20
|
+
) {
|
|
21
|
+
at += 1;
|
|
22
|
+
}
|
|
23
|
+
const name = text.slice(nameStart, at).toLowerCase();
|
|
24
|
+
if (name === "") {
|
|
25
|
+
at += 1;
|
|
26
|
+
continue;
|
|
27
|
+
}
|
|
28
|
+
while (at < text.length && isSpace(text.charCodeAt(at))) {
|
|
29
|
+
at += 1;
|
|
30
|
+
}
|
|
31
|
+
if (text[at] !== "=") {
|
|
32
|
+
continue;
|
|
33
|
+
}
|
|
34
|
+
at += 1;
|
|
35
|
+
while (at < text.length && isSpace(text.charCodeAt(at))) {
|
|
36
|
+
at += 1;
|
|
37
|
+
}
|
|
38
|
+
const quote = text[at];
|
|
39
|
+
if (quote === '"' || quote === "'") {
|
|
40
|
+
const close = text.indexOf(quote, at + 1);
|
|
41
|
+
const end = close < 0 ? text.length : close;
|
|
42
|
+
out.push({ name, value: text.slice(at + 1, end), at: at + 1 });
|
|
43
|
+
at = end + 1;
|
|
44
|
+
} else {
|
|
45
|
+
const start = at;
|
|
46
|
+
while (at < text.length && !isSpace(text.charCodeAt(at))) {
|
|
47
|
+
at += 1;
|
|
48
|
+
}
|
|
49
|
+
out.push({ name, value: text.slice(start, at), at: start });
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
return out;
|
|
53
|
+
}
|