@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
|
@@ -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 {};
|