@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
@@ -0,0 +1,116 @@
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), 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);
16
+ * and nothing in the page's markup below body that scrolls itself: no element there with style=""
17
+ * or a Tailwind utility giving it overflow-y auto or scroll, or matched by a rule the check reads
18
+ * that does (a rule whose selector it can't read, or that matches nothing in the markup, doesn't
19
+ * count; nor does the root, by its style="", classes or rules: its own values say whether it
20
+ * scrolls the page, one screen tall or, in a one-screen body, in a height the check can't read
21
+ * (under a flex or grid body, a height of another shape), or grows with it). Then the page may
22
+ * scroll in that box, and
23
+ * the check can't tell which box holds what. A page its script draws (body holds an empty root at
24
+ * most) can't be matched: it is warned, worded as a page that looks held, as a box its script
25
+ * draws may scroll it. One screen tall: height or max-height (block-size, max-block-size) 100vh
26
+ * (dvh, svh, lvh) or calc(100vh - 4rem) (less one positive length), or 100% or calc(100% - 4rem)
27
+ * of an element that is (html's 100% is the frame's), or position fixed or absolute with both top
28
+ * and bottom set (`inset: 0`).
29
+ *
30
+ * What it reads: the page's `<style>` elements, the stylesheets it links that the caller finds
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
33
+ * class rules that match their classes; and, where the page loads Tailwind from its CDN, the few
34
+ * Tailwind utilities that hold a page (h-screen, overflow-hidden, fixed, inset-0…). Specificity,
35
+ * order, !important and cascade layers decide between rules, so a later override is seen.
36
+ * What it doesn't: rules under @media (but `all` and `screen`), @supports or @container, selectors
37
+ * beyond type, id, class, `*`, `:root`, `:only-child`, `:first-child` and the descendant and child
38
+ * combinators (`:is()`, `:where()`, `:not()`, attributes, siblings and a compound of more than
39
+ * `MOST_IN_COMPOUND` ids and classes match nothing), nested rules, values through var() or calc()
40
+ * (but the two above), a stylesheet linked or imported a second time (read where it first comes),
41
+ * the rules of a layer named more than `LAYER_PARTS` deep (its first parts are still declared),
42
+ * and what scripts do. Each of those misses a lock, or an override (then the warning is wrong); it
43
+ * never refuses anything.
44
+ *
45
+ * Bounded: each stylesheet is read once per page, as it streams (nothing parsed is kept past the
46
+ * rule it is in, a rule's selectors one at a time), at most `SHEETS` of them and `READ` bytes in
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
49
+ * page, each named in at most `LONGEST_LAYER` characters: a new one past either isn't read. Each
50
+ * element keeps, per property, only each layer's winner so far, and a compound is matched against
51
+ * an element's classes (a set) in bounded work, so time and memory are linear in what it reads. A
52
+ * version's pages (`lintFiles`: the entry and at most 7 more) share one `scrollBudget()`:
53
+ * `VERSION_READ` bytes of every sheet read for any of them, its own `<style>` included, and
54
+ * `VERSION_STEPS` match steps; a page that would spend more than is left isn't checked, nor are the
55
+ * pages after it. What it echoes to the agent is only values of a known shape, and selectors of
56
+ * plain characters and the root's plain id, each at most `ECHOED` characters with its !important (a
57
+ * selector or id that isn't: the element's own name, `#root`, `body > div`, or `body > *` for a tag
58
+ * HTML doesn't have; the fix is then !important where the name has less specificity than the
59
+ * selector).
60
+ */
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
+ */
68
+ export type LinkedSheet = (href: string, from: string) => {
69
+ readonly path: string;
70
+ readonly least: number;
71
+ readonly text: () => string;
72
+ } | null;
73
+ export interface ScrollLock {
74
+ /** What to change, for the agent. */
75
+ readonly message: string;
76
+ /** The file the rule that holds it is in (the page's own `path`, or a stylesheet's). */
77
+ readonly path?: string;
78
+ /** Its line (1-based); none where the page couldn't be checked (P110). */
79
+ readonly line?: number;
80
+ }
81
+ /** The most stylesheets read for one page, each once. */
82
+ export declare const SHEETS = 32;
83
+ /** The most bytes of stylesheets read for one page, in all. */
84
+ export declare const READ: number;
85
+ /**
86
+ * A version's pages share one budget (`lintFiles`, which checks the entry and at most 7 more):
87
+ * every byte of stylesheet read for any of them, its own `<style>` included (a sheet two pages
88
+ * link is read for each), and every step matching scroll rules against markup. A page that would
89
+ * spend more than is left isn't checked, nor are the pages after it.
90
+ */
91
+ export declare const VERSION_READ: number;
92
+ export declare const VERSION_STEPS = 2000000;
93
+ /** What a version's pages have left to spend on this rule, and whether one has run out. */
94
+ export interface ScrollBudget {
95
+ bytes: number;
96
+ steps: number;
97
+ spent: boolean;
98
+ }
99
+ /** A version's budget, for one `lintFiles`. */
100
+ export declare const scrollBudget: () => ScrollBudget;
101
+ interface ScrollOptions {
102
+ readonly noun: string;
103
+ readonly path?: string;
104
+ readonly sheet?: LinkedSheet;
105
+ /** The version's, shared by its pages (`scrollBudget()`); else this page's own. */
106
+ readonly budget?: ScrollBudget;
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 {};