@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.
- 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/check/files.d.ts +2 -0
- package/dist/check/files.js +67 -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 +100 -0
- package/dist/check/scroll.js +1429 -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 +3 -3
- package/dist/index.d.ts +1 -1
- package/dist/react/frame.d.ts +2 -1
- package/dist/runtime/requests.d.ts +5 -0
- package/dist/runtime/requests.js +16 -1
- 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 +25 -3
- package/docs/ARCHITECTURE.md +2 -1
- package/docs/DECISIONS.md +391 -2
- package/docs/DESIGN.md +31 -9
- package/docs/THREAT_MODEL.md +42 -7
- package/package.json +1 -1
- package/src/annotate/types.ts +19 -6
- package/src/annotate/validate.ts +20 -1
- package/src/check/files.ts +68 -54
- package/src/check/lint.ts +24 -0
- package/src/check/markup.ts +53 -0
- package/src/check/scroll.ts +1757 -0
- 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 +9 -3
- package/src/index.ts +1 -0
- package/src/react/frame.tsx +2 -1
- package/src/runtime/requests.ts +23 -1
- 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 +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;
|