@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.
Files changed (68) hide show
  1. package/dist/annotate/types.d.ts +18 -6
  2. package/dist/annotate/validate.d.ts +11 -1
  3. package/dist/annotate/validate.js +18 -1
  4. package/dist/bridge/bridge.d.ts +8 -1
  5. package/dist/bridge/bridge.js +7 -0
  6. package/dist/bridge/unseen.d.ts +8 -0
  7. package/dist/bridge/unseen.js +17 -0
  8. package/dist/check/files.d.ts +2 -0
  9. package/dist/check/files.js +71 -50
  10. package/dist/check/lint.d.ts +8 -1
  11. package/dist/check/lint.js +18 -0
  12. package/dist/check/markup.d.ts +7 -0
  13. package/dist/check/markup.js +49 -0
  14. package/dist/check/page-source.js +1 -1
  15. package/dist/check/scroll.d.ts +116 -0
  16. package/dist/check/scroll.js +1485 -0
  17. package/dist/config/capabilities.d.ts +16 -3
  18. package/dist/config/capabilities.js +1 -0
  19. package/dist/conformance/harness-source.js +1 -1
  20. package/dist/conformance/runtime.js +6 -0
  21. package/dist/guide/guide.js +1 -1
  22. package/dist/guide/runtime.js +2 -2
  23. package/dist/host/create-host.js +30 -3
  24. package/dist/host/types.d.ts +15 -0
  25. package/dist/index.d.ts +2 -1
  26. package/dist/index.js +1 -0
  27. package/dist/platform/focus-guard.d.ts +143 -0
  28. package/dist/platform/focus-guard.js +445 -0
  29. package/dist/platform/types.d.ts +18 -0
  30. package/dist/platform/web.js +22 -0
  31. package/dist/react/frame.d.ts +10 -1
  32. package/dist/react/frame.js +4 -0
  33. package/dist/runtime/requests.d.ts +5 -0
  34. package/dist/runtime/requests.js +41 -4
  35. package/dist/runtime/types.generated.js +1 -1
  36. package/dist/shell/annotate.d.ts +2 -1
  37. package/dist/shell/annotate.js +29 -12
  38. package/dist/shell/use.js +9 -1
  39. package/docs/ADOPTING.md +106 -5
  40. package/docs/ARCHITECTURE.md +2 -1
  41. package/docs/DECISIONS.md +741 -2
  42. package/docs/DESIGN.md +38 -9
  43. package/docs/THREAT_MODEL.md +146 -19
  44. package/package.json +1 -1
  45. package/src/annotate/types.ts +19 -6
  46. package/src/annotate/validate.ts +20 -1
  47. package/src/bridge/bridge.ts +17 -1
  48. package/src/bridge/unseen.ts +24 -0
  49. package/src/check/files.ts +72 -54
  50. package/src/check/lint.ts +24 -0
  51. package/src/check/markup.ts +53 -0
  52. package/src/check/scroll.ts +1825 -0
  53. package/src/config/capabilities.ts +16 -3
  54. package/src/conformance/runtime.ts +9 -0
  55. package/src/guide/guide.ts +1 -0
  56. package/src/guide/runtime.ts +2 -2
  57. package/src/host/create-host.ts +38 -3
  58. package/src/host/types.ts +13 -0
  59. package/src/index.ts +2 -0
  60. package/src/platform/focus-guard.ts +572 -0
  61. package/src/platform/types.ts +17 -0
  62. package/src/platform/web.ts +22 -0
  63. package/src/react/frame.tsx +12 -1
  64. package/src/runtime/requests.ts +50 -6
  65. package/src/runtime/types.generated.ts +1 -1
  66. package/src/shell/annotate.ts +29 -12
  67. package/src/shell/use.ts +9 -1
  68. package/types/runtime/v1/comments.d.ts +20 -6
@@ -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 { lintContent, type Finding } from "./lint.ts";
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
- for (const finding of lintContent(config, text)) {
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
+ }