@botiverse/porthole 0.10.0 → 0.12.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 (48) 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/check/files.d.ts +2 -0
  5. package/dist/check/files.js +67 -50
  6. package/dist/check/lint.d.ts +8 -1
  7. package/dist/check/lint.js +18 -0
  8. package/dist/check/markup.d.ts +7 -0
  9. package/dist/check/markup.js +49 -0
  10. package/dist/check/page-source.js +1 -1
  11. package/dist/check/scroll.d.ts +100 -0
  12. package/dist/check/scroll.js +1429 -0
  13. package/dist/conformance/harness-source.js +1 -1
  14. package/dist/conformance/runtime.js +6 -0
  15. package/dist/guide/guide.js +1 -1
  16. package/dist/guide/runtime.js +2 -2
  17. package/dist/host/create-host.js +3 -3
  18. package/dist/index.d.ts +1 -1
  19. package/dist/react/frame.d.ts +2 -1
  20. package/dist/runtime/requests.d.ts +5 -0
  21. package/dist/runtime/requests.js +16 -1
  22. package/dist/runtime/types.generated.js +1 -1
  23. package/dist/shell/annotate.d.ts +2 -1
  24. package/dist/shell/annotate.js +29 -12
  25. package/dist/shell/use.js +9 -1
  26. package/docs/ADOPTING.md +25 -3
  27. package/docs/ARCHITECTURE.md +2 -1
  28. package/docs/DECISIONS.md +391 -2
  29. package/docs/DESIGN.md +31 -9
  30. package/docs/THREAT_MODEL.md +42 -7
  31. package/package.json +1 -1
  32. package/src/annotate/types.ts +19 -6
  33. package/src/annotate/validate.ts +20 -1
  34. package/src/check/files.ts +68 -54
  35. package/src/check/lint.ts +24 -0
  36. package/src/check/markup.ts +53 -0
  37. package/src/check/scroll.ts +1757 -0
  38. package/src/conformance/runtime.ts +9 -0
  39. package/src/guide/guide.ts +1 -0
  40. package/src/guide/runtime.ts +2 -2
  41. package/src/host/create-host.ts +9 -3
  42. package/src/index.ts +1 -0
  43. package/src/react/frame.tsx +2 -1
  44. package/src/runtime/requests.ts +23 -1
  45. package/src/runtime/types.generated.ts +1 -1
  46. package/src/shell/annotate.ts +29 -12
  47. package/src/shell/use.ts +9 -1
  48. package/types/runtime/v1/comments.d.ts +14 -4
@@ -0,0 +1,100 @@
1
+ /**
2
+ * Whether a page's own styles hold it to one screen (P106), read from its text: no layout, a
3
+ * cascade of the few properties that matter over the three elements that hold a document (html,
4
+ * body, and the body's one element of content, `#root` in an app's build). An app shell's styles
5
+ * (`html, body { height: 100%; overflow: hidden }`, `#root { position: fixed; height: 100dvh }`)
6
+ * stop a long page at its first screen in a frame: the person's wheel finds nothing to scroll.
7
+ *
8
+ * What counts, per element, by its cascaded values:
9
+ * - html with overflow-y hidden or clip (the viewport's own: nothing scrolls);
10
+ * - body with overflow-y hidden or clip, where html's overflow is visible (body's then becomes the
11
+ * viewport's) or body is one screen tall;
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);
14
+ * and nothing in the page's markup below body that scrolls itself: no element there with style=""
15
+ * or a Tailwind utility giving it overflow-y auto or scroll, or matched by a rule the check reads
16
+ * that does (a rule whose selector it can't read, or that matches nothing in the markup, doesn't
17
+ * count; nor does the root, by its style="", classes or rules: its own values say whether it
18
+ * scrolls the page, one screen tall or, in a one-screen body, in a height the check can't read
19
+ * (under a flex or grid body, a height of another shape), or grows with it). Then the page may
20
+ * scroll in that box, and
21
+ * the check can't tell which box holds what. A page its script draws (body holds an empty root at
22
+ * most) can't be matched: it is warned, worded as a page that looks held, as a box its script
23
+ * draws may scroll it. One screen tall: height or max-height (block-size, max-block-size) 100vh
24
+ * (dvh, svh, lvh) or calc(100vh - 4rem) (less one positive length), or 100% or calc(100% - 4rem)
25
+ * of an element that is (html's 100% is the frame's), or position fixed or absolute with both top
26
+ * and bottom set (`inset: 0`).
27
+ *
28
+ * 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 the three; the
30
+ * class rules that match their classes; and, where the page loads Tailwind from its CDN, the few
31
+ * Tailwind utilities that hold a page (h-screen, overflow-hidden, fixed, inset-0…). Specificity,
32
+ * order, !important and cascade layers decide between rules, so a later override is seen.
33
+ * What it doesn't: rules under @media (but `all` and `screen`), @supports or @container, selectors
34
+ * beyond type, id, class, `*`, `:root`, `:only-child`, `:first-child` and the descendant and child
35
+ * combinators (`:is()`, `:where()`, `:not()`, attributes, siblings and a compound of more than
36
+ * `MOST_IN_COMPOUND` ids and classes match nothing), nested rules, values through var() or calc()
37
+ * (but the two above), a stylesheet linked or imported a second time (read where it first comes),
38
+ * the rules of a layer named more than `LAYER_PARTS` deep (its first parts are still declared),
39
+ * and what scripts do. Each of those misses a lock, or an override (then the warning is wrong); it
40
+ * never refuses anything.
41
+ *
42
+ * Bounded: each stylesheet is read once per page, as it streams (nothing parsed is kept past the
43
+ * 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. At most `MOST_LAYERS` layers a
45
+ * page, each named in at most `LONGEST_LAYER` characters: a new one past either isn't read. Each
46
+ * element keeps, per property, only each layer's winner so far, and a compound is matched against
47
+ * an element's classes (a set) in bounded work, so time and memory are linear in what it reads. A
48
+ * version's pages (`lintFiles`: the entry and at most 7 more) share one `scrollBudget()`:
49
+ * `VERSION_READ` bytes of every sheet read for any of them, its own `<style>` included, and
50
+ * `VERSION_STEPS` match steps; a page that would spend more than is left isn't checked, nor are the
51
+ * pages after it. What it echoes to the agent is only values of a known shape, and selectors of
52
+ * plain characters and the root's plain id, each at most `ECHOED` characters with its !important (a
53
+ * selector or id that isn't: the element's own name, `#root`, `body > div`, or `body > *` for a tag
54
+ * HTML doesn't have; the fix is then !important where the name has less specificity than the
55
+ * selector).
56
+ */
57
+ /** A stylesheet the page links, as the caller finds it from `from` (a path), or null. */
58
+ export type LinkedSheet = (href: string, from: string) => {
59
+ readonly path: string;
60
+ readonly text: string;
61
+ } | null;
62
+ export interface ScrollLock {
63
+ /** What to change, for the agent. */
64
+ readonly message: string;
65
+ /** The file the rule that holds it is in (the page's own `path`, or a stylesheet's). */
66
+ readonly path?: string;
67
+ /** Its line (1-based). */
68
+ readonly line: number;
69
+ }
70
+ /** The most stylesheets read for one page, each once. */
71
+ export declare const SHEETS = 32;
72
+ /** The most bytes of stylesheets read for one page, in all. */
73
+ export declare const READ: number;
74
+ /**
75
+ * A version's pages share one budget (`lintFiles`, which checks the entry and at most 7 more):
76
+ * every byte of stylesheet read for any of them, its own `<style>` included (a sheet two pages
77
+ * link is read for each), and every step matching scroll rules against markup. A page that would
78
+ * spend more than is left isn't checked, nor are the pages after it.
79
+ */
80
+ export declare const VERSION_READ: number;
81
+ export declare const VERSION_STEPS = 2000000;
82
+ /** What a version's pages have left to spend on this rule, and whether one has run out. */
83
+ export interface ScrollBudget {
84
+ bytes: number;
85
+ steps: number;
86
+ spent: boolean;
87
+ }
88
+ /** A version's budget, for one `lintFiles`. */
89
+ 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: {
95
+ readonly noun: string;
96
+ readonly path?: string;
97
+ readonly sheet?: LinkedSheet;
98
+ /** The version's, shared by its pages (`scrollBudget()`); else this page's own. */
99
+ readonly budget?: ScrollBudget;
100
+ }): ScrollLock | null;