barebrowse 0.26.0 → 0.28.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/src/zoom.js ADDED
@@ -0,0 +1,250 @@
1
+ /**
2
+ * zoom.js — map + zoom for `snapshot()`.
3
+ *
4
+ * `map: true` lists the page's big boxes (landmarks, lists, tables, …) with a
5
+ * ref and a size; `within` cuts the snapshot to one or more of them. The agent
6
+ * picks the box — nothing here guesses which part of a page matters. Both
7
+ * engines share this: they build the tree (and resolve any ref selector to a
8
+ * node id in it), this module selects, formats and writes the output.
9
+ *
10
+ * Inside a zoom the box is the whole page: prune's landmark step and data
11
+ * mode's main-only scope are off (`whole`), everything else prunes as usual.
12
+ */
13
+
14
+ import { formatTree } from './aria.js';
15
+ import { prune } from './prune.js';
16
+ import { dataSnapshot, stripLegend } from './data.js';
17
+
18
+ /** Roles the map lists (when big enough, or when a `within` matched them). */
19
+ export const BOX_ROLES = new Set([
20
+ 'banner', 'navigation', 'main', 'complementary', 'contentinfo', 'region', 'form', 'search',
21
+ 'list', 'table', 'grid', 'treegrid', 'feed', 'tablist', 'tabpanel', 'dialog',
22
+ ]);
23
+
24
+ /** Card groups are never looked for inside these: link columns and menus there are not content. */
25
+ const CHROME_ROLES = new Set(['banner', 'navigation', 'contentinfo']);
26
+ /** Parents that are already a map box of their own kind: their items are a list or a table, not a card group. */
27
+ const NATIVE_BOX = new Set(['list', 'feed', 'table', 'grid', 'treegrid']);
28
+ /** Roles that are one cell of something else, never a card. */
29
+ const NOT_CARD = new Set(['row', 'tab', 'option', 'menuitem', 'treeitem', 'StaticText', 'heading', 'link', 'button', 'cell', 'gridcell', 'columnheader', 'rowheader', 'separator']);
30
+ const NOISE = new Set(['StaticText', 'InlineTextBox', 'LineBreak', 'ListMarker', 'none', 'presentation', 'generic', 'image', 'img']);
31
+ /** A card: at least this much text and this many nodes; a group: at least this many alike cards, and half of the parent's substantial children. */
32
+ const CARD = { text: 15, nodes: 4, run: 4, similar: 0.6 };
33
+
34
+ /** A box is listed when its data-mode text is at least this many chars. */
35
+ const MAP_MIN = 800;
36
+
37
+ const norm = (s) => String(s ?? '').replace(/\s+/g, ' ').trim();
38
+ const kids = (n) => n.children.flatMap((c) => (c.ignored ? kids(c) : [c]));
39
+
40
+ /**
41
+ * One `within` selector: a ref, or role + optional name / preceding heading.
42
+ * @typedef {{ raw: string, ref?: string, role?: string, name?: string, after?: string }} Selector
43
+ */
44
+
45
+ /**
46
+ * Parse `within` (one selector or an array).
47
+ * @param {string|number|Array<string|number>} within
48
+ * @returns {Selector[]}
49
+ */
50
+ export function parseWithin(within) {
51
+ const list = Array.isArray(within) ? within : [within];
52
+ if (!list.length) throw new Error('within is empty — pass a ref, a role, role "name", or role after "heading"');
53
+ return list.map((w) => {
54
+ const raw = String(w).trim();
55
+ if (/^\d+$/.test(raw)) return { raw, ref: raw };
56
+ const m = raw.match(/^(\w+)(?: "(.*?)")?(?: after "(.*)")?$/);
57
+ if (!m) throw new Error(`within: cannot parse ${JSON.stringify(raw)} — use a ref, a role, role "name", or role after "heading"`);
58
+ /** @type {Selector} */
59
+ const sel = { raw, role: m[1] };
60
+ if (m[2] !== undefined) sel.name = norm(m[2]);
61
+ if (m[3] !== undefined) sel.after = norm(m[3]);
62
+ return sel;
63
+ });
64
+ }
65
+
66
+ /** Every non-ignored node in page order, with the heading right before it among its siblings. */
67
+ function index(root) {
68
+ const nodes = [];
69
+ const after = new Map();
70
+ (function walk(n) {
71
+ if (!n.ignored) nodes.push(n);
72
+ let heading = null; // text of the nearest preceding sibling heading; a box between ends it
73
+ for (const c of kids(n)) {
74
+ after.set(c, heading);
75
+ if (c.role === 'heading' && norm(c.name)) heading = norm(c.name);
76
+ else if (BOX_ROLES.has(c.role)) heading = null;
77
+ walk(c);
78
+ }
79
+ })(root);
80
+ let groups = null;
81
+ return { nodes, after, groups: (links) => (groups ??= cardGroups(root, links)) };
82
+ }
83
+
84
+ /**
85
+ * Card groups: a parent whose substantial children are mostly alike (same role, similar
86
+ * child-role sets): a grid of product, listing or video cards that no landmark or list role
87
+ * marks. Structure only. Not looked for inside banner/navigation/contentinfo, and not when
88
+ * the parent is a list, table or the like (already a map box of its own kind). A landmark
89
+ * parent (cards straight in `main`) is a group too; its ref is the landmark's. Returns parent node → { items, size }.
90
+ * @returns {Map<object, {items: object[], size: number}>}
91
+ */
92
+ function cardGroups(root, links) {
93
+ const text = new Map();
94
+ const count = new Map();
95
+ (function tally(n) {
96
+ let t = n.role === 'StaticText' ? norm(n.name).length : 0;
97
+ let c = 1;
98
+ for (const k of n.children) { tally(k); t += text.get(k); c += count.get(k); }
99
+ text.set(n, t); count.set(n, c);
100
+ })(root);
101
+ // role set of a node's children and grandchildren, noise left out
102
+ const shape = (n) => {
103
+ const set = new Set();
104
+ for (const c of kids(n)) {
105
+ if (!NOISE.has(c.role)) set.add(c.role);
106
+ for (const g of kids(c)) if (!NOISE.has(g.role)) set.add('>' + g.role);
107
+ }
108
+ return set;
109
+ };
110
+ const jaccard = (a, b) => {
111
+ if (!a.size && !b.size) return 1;
112
+ let both = 0;
113
+ for (const x of a) if (b.has(x)) both++;
114
+ return both / (a.size + b.size - both);
115
+ };
116
+ const isCard = (n) => !NOT_CARD.has(n.role) && text.get(n) >= CARD.text && count.get(n) >= CARD.nodes;
117
+
118
+ const groups = new Map();
119
+ (function walk(n) {
120
+ if (!n.ignored && CHROME_ROLES.has(n.role)) return;
121
+ const ks = kids(n);
122
+ // Cluster the cards by role and shape; a group need not be contiguous (an ad between cards does not split it).
123
+ const clusters = [];
124
+ const cards = ks.filter(isCard);
125
+ for (const k of cards) {
126
+ const sh = shape(k);
127
+ const c = clusters.find((x) => x.role === k.role && jaccard(x.shape, sh) >= CARD.similar);
128
+ if (c) c.items.push(k); else clusters.push({ role: k.role, shape: sh, items: [k] });
129
+ }
130
+ const best = clusters.sort((a, b) => b.items.length - a.items.length)[0];
131
+ if (best && best.items.length >= CARD.run && best.items.length >= 0.5 * cards.length) {
132
+ if (!NATIVE_BOX.has(n.role)) {
133
+ const size = best.items.reduce((sum, it) => sum + stripLegend(dataSnapshot(it, { links, whole: true })).length, 0);
134
+ groups.set(n, { items: best.items, size });
135
+ }
136
+ return; // a group's cards are not searched for more groups
137
+ }
138
+ for (const c of ks) walk(c);
139
+ })(root);
140
+ return groups;
141
+ }
142
+
143
+ const label = (n, after, group) => (group ? `group ×${group.items.length}` : `${n.role}${n.name ? ` "${norm(n.name)}"` : after ? ` after "${after}"` : ''}`);
144
+ const sizeText = (n) => (n < 1000 ? `${n}` : `${(n / 1000).toFixed(1)}k`);
145
+
146
+ /**
147
+ * The map: one line per box, nested by box depth.
148
+ * - role "name" [ref=N] (14.9k chars)
149
+ * - list after "Other flights" [ref=N] (3.1k chars) ← unnamed: its preceding heading
150
+ * - group ×18 (6.3k chars) [ref=N] ← a card group: its parent's ref, the cards' size
151
+ * Size is the box's data-mode text. Boxes in `marked` are listed whatever their size.
152
+ */
153
+ function mapLines(root, ix, links, marked = new Set()) {
154
+ const lines = [];
155
+ const groups = ix.groups(links);
156
+ (function walk(n, depth) {
157
+ let d = depth;
158
+ if (!n.ignored && BOX_ROLES.has(n.role)) {
159
+ const size = stripLegend(dataSnapshot(n, { links, whole: true })).length;
160
+ if (size >= MAP_MIN || marked.has(n)) {
161
+ lines.push(`${' '.repeat(depth)}- ${label(n, ix.after.get(n))} [ref=${n.nodeId}] (${sizeText(size)} chars)${marked.has(n) ? ' <- match' : ''}`);
162
+ d = depth + 1;
163
+ }
164
+ }
165
+ const g = !n.ignored && groups.get(n);
166
+ if (g && (g.size >= MAP_MIN || marked.has(n))) {
167
+ lines.push(`${' '.repeat(d)}- ${label(n, null, g)} (${sizeText(g.size)} chars) [ref=${n.nodeId}]${marked.has(n) ? ' <- match' : ''}`);
168
+ d += 1;
169
+ }
170
+ for (const c of n.children) walk(c, d);
171
+ })(root, 0);
172
+ return lines;
173
+ }
174
+
175
+ /**
176
+ * Write the map or a zoom of `tree`. Returns the finished snapshot text
177
+ * (`head` is the url/warning prefix the engine builds), or throws.
178
+ *
179
+ * @param {object} tree - Pruning-ready tree (links already annotated)
180
+ * @param {object} o
181
+ * @param {string} o.head - Text placed first (url line, warnings)
182
+ * @param {boolean} [o.map] - Write the map (ignored when `within` is set)
183
+ * @param {Selector[]} [o.selectors] - parseWithin() result
184
+ * @param {Map<string,string|null>} [o.refNodes] - ref selector → node id in `tree` (null: gone)
185
+ * @param {'act'|'browse'|'navigate'|'full'|'read'|'data'} o.mode - Pruning mode
186
+ * @param {boolean} o.links
187
+ */
188
+ export function zoomSnapshot(tree, { head, map, selectors, refNodes = new Map(), mode, links }) {
189
+ const ix = index(tree);
190
+ const mapText = (lines, intro) => `${head}${intro}\n${lines.join('\n')}`;
191
+ if (!selectors) {
192
+ const lines = mapLines(tree, ix, links);
193
+ return mapText(lines, `map: ${lines.length} boxes, size = chars in data mode. Zoom with within=<ref | role | role "name" | role after "heading"> (an array takes several boxes); any mode and links apply inside a zoom.`);
194
+ }
195
+
196
+ const found = selectors.map((s) => {
197
+ if (s.ref) {
198
+ const id = refNodes.get(s.ref);
199
+ return id ? ix.nodes.filter((n) => n.nodeId === id) : [];
200
+ }
201
+ // a bare `group` names the card groups the map lists (the real group nodes only when there are none)
202
+ if (s.role === 'group' && s.name === undefined && s.after === undefined && ix.groups(links).size) return [...ix.groups(links).keys()];
203
+ return ix.nodes.filter((n) => n.role === s.role
204
+ && (s.name === undefined || norm(n.name) === s.name)
205
+ && (s.after === undefined || ix.after.get(n) === s.after));
206
+ });
207
+ const none = selectors.findIndex((_, i) => !found[i].length);
208
+ if (none >= 0) {
209
+ throw new Error(`within: nothing matches ${selectors[none].raw} — take a ref, role or name from snapshot({ map: true })`);
210
+ }
211
+ const many = selectors.filter((_, i) => found[i].length > 1);
212
+ if (many.length) {
213
+ const marked = new Set(found.filter((f) => f.length > 1).flat());
214
+ const what = many.map((s) => `${s.raw} (${found[selectors.indexOf(s)].length})`).join(', ');
215
+ return mapText(mapLines(tree, ix, links, marked),
216
+ `within matched more than one box: ${what}. Marked "<- match" below; pick by ref, or add a name or after "heading".`);
217
+ }
218
+
219
+ // Page order, and a box inside another selected box is not repeated.
220
+ const picked = new Set(found.flat());
221
+ const boxes = [];
222
+ (function walk(n) {
223
+ if (picked.has(n)) { boxes.push(n); return; }
224
+ for (const c of n.children) walk(c);
225
+ })(tree);
226
+ const parts = boxes.map((b) => ({
227
+ raw: formatTree(b),
228
+ out: mode === 'data'
229
+ ? dataSnapshot(b, { links, whole: true })
230
+ : formatTree(prune(b, { mode, links, whole: true })),
231
+ }));
232
+ const body = parts.map((p, i) => (i && mode === 'data' ? stripLegend(p.out) : p.out)).filter(Boolean).join('\n');
233
+ const rawLen = parts.reduce((s, p) => s + p.raw.length, 0);
234
+ const sized = parts.reduce((s, p) => s + stripLegend(p.out).length, 0);
235
+ const what = boxes.map((b) => `${label(b, ix.after.get(b), !BOX_ROLES.has(b.role) && ix.groups(links).get(b))} [ref=${b.nodeId}]`).join(', ');
236
+ return `${head}zoom ${what}: ${rawLen.toLocaleString()} chars → ${sized.toLocaleString()} chars (${rawLen ? Math.round((1 - sized / rawLen) * 100) : 0}% pruned)\n${body}`;
237
+ }
238
+
239
+ /**
240
+ * Why a zoom/map came back as a file path only: it is over the inline cap.
241
+ * @param {'zoom'|'map'} kind
242
+ * @param {number} chars
243
+ * @param {number} limit
244
+ * @param {boolean} [cli] - flag spelling (--max-chars, --map) instead of tool arguments
245
+ */
246
+ export function overNote(kind, chars, limit, cli = false) {
247
+ const cap = cli ? '--max-chars' : 'maxChars';
248
+ const fix = kind === 'zoom' ? `raise ${cap}, or zoom a smaller box (from ${cli ? '--map' : 'map:true'})` : `raise ${cap}`;
249
+ return `The ${kind} was ${chars} chars, over ${cap} (${limit}): ${fix} to get it inline.`;
250
+ }
package/types/auth.d.ts CHANGED
@@ -11,6 +11,32 @@ export function findChromiumCookieDb(): {
11
11
  * @returns {string | null} Path to cookies.sqlite
12
12
  */
13
13
  export function findFirefoxCookieDb(): string | null;
14
+ /**
15
+ * kwallet-query output -> Chromium keyring password. Chromium feeds the stored
16
+ * string to PBKDF2 as-is (it is not base64 to decode).
17
+ * @param {string} stdout
18
+ * @returns {string}
19
+ */
20
+ export function kwalletPassword(stdout: string): string;
21
+ /**
22
+ * Derive AES key from Chromium keyring password.
23
+ * Chrome Linux: PBKDF2-SHA1, salt='saltysalt', 1 iteration, 16-byte key.
24
+ */
25
+ export function deriveKey(password: any): NonSharedBuffer;
26
+ /**
27
+ * Decrypt a Chromium encrypted cookie value.
28
+ * @param {Uint8Array} encrypted - encrypted_value from SQLite
29
+ * @param {Buffer} aesKey - Derived AES key
30
+ * @returns {string} Decrypted cookie value
31
+ */
32
+ export function decryptCookie(encrypted: Uint8Array, aesKey: Buffer): string;
33
+ /**
34
+ * Extract cookies from a Chromium-based browser.
35
+ * @param {string} dbPath - Path to Cookies SQLite database
36
+ * @param {string} [domain] - Filter by domain (e.g. '.github.com')
37
+ * @returns {Array<object>} Cookies in CDP Network.setCookie format
38
+ */
39
+ export function extractChromiumCookies(dbPath: string, domain?: string): Array<object>;
14
40
  /**
15
41
  * Extract cookies from Firefox (no encryption).
16
42
  * @param {string} dbPath - Path to cookies.sqlite
@@ -7,9 +7,10 @@
7
7
  * @param {boolean} [pageOpts.blockAds] - false disables the default list.
8
8
  * @param {string[]} [pageOpts.blockUrls] - extra CDP-format globs; extend the
9
9
  * default unless blockAds is false, in which case they're the whole list.
10
+ * @param {import('./site-lock.js').SiteLock|null} [lock] - Site lock to enforce in the same handler.
10
11
  * @returns {Promise<void>}
11
12
  */
12
13
  export function applyFirefoxBlocklist(bidi: object, pageOpts?: {
13
14
  blockAds?: boolean | undefined;
14
15
  blockUrls?: string[] | undefined;
15
- }): Promise<void>;
16
+ }, lock?: import("./site-lock.js").SiteLock | null): Promise<void>;
package/types/data.d.ts CHANGED
@@ -2,11 +2,12 @@
2
2
  * Render a raw ARIA tree in data mode.
3
3
  *
4
4
  * @param {object} root - Root node from buildTree() (CDP vocabulary)
5
- * @param {{ links?: boolean }} [opts] - links: the tree's link nodes carry `urls` (annotateLinks); adds the legend note
5
+ * @param {{ links?: boolean, whole?: boolean }} [opts] - links: the tree's link nodes carry `urls` (annotateLinks); adds the legend note. whole: root is a zoom box (snapshot `within`), so no main-only scope
6
6
  * @returns {string} LEGEND line, then one line per record, YAML-ish like formatTree(); '' when there are no records
7
7
  */
8
8
  export function dataSnapshot(root: object, opts?: {
9
9
  links?: boolean;
10
+ whole?: boolean;
10
11
  }): string;
11
12
  /** First line of every data-mode snapshot: tells an agent with no docs how to read it. */
12
13
  export const LEGEND: "# data mode: one line per record. Tables: row \"<label>\": <column>: <value> \u00B7 \u2026 Groups: <label>: a, b, c. A title line followed by detail lines is one block, up to the next title line. Main content only; use mode \"act\" for menus and page controls.";
@@ -6,6 +6,7 @@
6
6
  * @param {boolean} [opts.links=false] - Default for snapshot({ links }): show link URLs.
7
7
  * @param {{allowLocalUrls?: boolean, blockPrivateNetwork?: boolean}} [opts.urlGuard] - Navigation safety policy, applied on every goto().
8
8
  * @param {string} [opts.uploadDir] - When set, upload() rejects files outside this dir.
9
+ * @param {?import('./site-lock.js').SiteLock} [opts.siteLock] - Site lock (allowHosts) state; the request-level enforcement is installed by applyFirefoxBlocklist, this side maps it to NAV_BLOCKED and snapshot notes.
9
10
  * @param {boolean} [opts.incognito=false] - Clean session: injectCookies() is a no-op.
10
11
  * @param {boolean} [opts.consent=true] - Auto-dismiss cookie consent dialogs after goto().
11
12
  * @param {boolean} [opts.hybrid=false] - Relaunch headed on a bot-challenge page and retry.
@@ -20,6 +21,17 @@ export function createFirefoxPage(bidi: object, opts?: {
20
21
  blockPrivateNetwork?: boolean;
21
22
  } | undefined;
22
23
  uploadDir?: string | undefined;
24
+ siteLock?: {
25
+ allowed: (url: string) => boolean;
26
+ assertAllowed(url: string): void;
27
+ record(url: any, ctx: any): void;
28
+ startGoto(ctx: any): void;
29
+ takeGotoBlock(ctx: any): {
30
+ url: string;
31
+ host: string;
32
+ } | null;
33
+ takeNotes(ctx: any): string;
34
+ } | null | undefined;
23
35
  incognito?: boolean | undefined;
24
36
  consent?: boolean | undefined;
25
37
  hybrid?: boolean | undefined;
@@ -53,8 +65,8 @@ export function createFirefoxPage(bidi: object, opts?: {
53
65
  snapshot(pruneOpts?: import("./index.js").SnapshotOptions | false): Promise<string>;
54
66
  readable(): Promise<any>;
55
67
  click(ref: any): Promise<void>;
56
- /** @param {string} ref @param {string} text @param {import('./index.js').TypeOptions} [typeOpts] */
57
- type(ref: string, text: string, typeOpts?: import("./index.js").TypeOptions): Promise<void>;
68
+ /** @param {string|number} ref @param {string} text @param {import('./index.js').TypeOptions} [typeOpts] */
69
+ type(ref: string | number, text: string, typeOpts?: import("./index.js").TypeOptions): Promise<void>;
58
70
  press(key: any): Promise<void>;
59
71
  scroll(deltaY: any): Promise<void>;
60
72
  hover(ref: any): Promise<void>;
package/types/index.d.ts CHANGED
@@ -27,6 +27,9 @@
27
27
  * @param {boolean} [opts.consent=true] - Auto-dismiss cookie consent dialogs.
28
28
  * @param {'act'|'browse'|'navigate'|'full'|'read'|'data'} [opts.pruneMode='act'] - Pruning mode.
29
29
  * @param {boolean} [opts.links=false] - Show link URLs: `link "name" <url> [ref=N]`.
30
+ * @param {string[]} [opts.allowHosts] - Site lock: top-level navigations (the URL, its
31
+ * redirects) to hosts outside this list reject with NAV_BLOCKED. Entries are `host`
32
+ * or `*.host` (strict subdomains). Subresources and iframes are not locked.
30
33
  * @returns {Promise<string>} ARIA snapshot text
31
34
  */
32
35
  export function browse(url: string, opts?: {
@@ -50,6 +53,7 @@ export function browse(url: string, opts?: {
50
53
  consent?: boolean | undefined;
51
54
  pruneMode?: "data" | "act" | "browse" | "navigate" | "full" | "read" | undefined;
52
55
  links?: boolean | undefined;
56
+ allowHosts?: string[] | undefined;
53
57
  }): Promise<string>;
54
58
  /**
55
59
  * Decide which engine connect() should use. Pure — the caller passes lazy
@@ -83,7 +87,7 @@ export function connect(opts?: {}): Promise<{
83
87
  snapshot(pruneOpts?: import("./index.js").SnapshotOptions | false): Promise<string>;
84
88
  readable(): Promise<any>;
85
89
  click(ref: any): Promise<void>;
86
- type(ref: string, text: string, typeOpts?: import("./index.js").TypeOptions): Promise<void>;
90
+ type(ref: string | number, text: string, typeOpts?: import("./index.js").TypeOptions): Promise<void>;
87
91
  press(key: any): Promise<void>;
88
92
  scroll(deltaY: any): Promise<void>;
89
93
  hover(ref: any): Promise<void>;
@@ -122,8 +126,8 @@ export function connect(opts?: {}): Promise<{
122
126
  snapshot(pruneOpts?: SnapshotOptions | false): Promise<string>;
123
127
  readable(): Promise<any>;
124
128
  click(ref: any): Promise<void>;
125
- /** @param {string} ref @param {string} text @param {TypeOptions} [typeOpts] */
126
- type(ref: string, text: string, typeOpts?: TypeOptions): Promise<void>;
129
+ /** @param {string|number} ref @param {string} text @param {TypeOptions} [typeOpts] */
130
+ type(ref: string | number, text: string, typeOpts?: TypeOptions): Promise<void>;
127
131
  scroll(deltaY: any): Promise<void>;
128
132
  press(key: any): Promise<void>;
129
133
  hover(ref: any): Promise<void>;
@@ -260,10 +264,19 @@ export type NavigationOutcome = import("./navigation.js").NavigationOutcome;
260
264
  * pruning and return the raw ARIA tree.
261
265
  * `links: true` adds each link's absolute URL after its name (default off,
262
266
  * or the `connect({ links })` default).
267
+ * `map: true` returns an outline of the page's big boxes (ref + size) instead of
268
+ * content. `within` zooms the snapshot to one box, or several (an array, output
269
+ * in page order): a ref from the map, a role (`'table'`), role + accessible name
270
+ * (`'list "Issues"'`) or an unnamed box by the heading before it
271
+ * (`'list after "Other flights"'`). Any `mode` and `links` apply inside a zoom,
272
+ * where the box is the whole page. Two or more matches return the map with the
273
+ * matches marked; none, or a ref that is gone, throws. `within` wins over `map`.
263
274
  */
264
275
  export type SnapshotOptions = {
265
276
  mode?: "act" | "browse" | "navigate" | "full" | "read" | "data";
266
277
  links?: boolean;
278
+ map?: boolean;
279
+ within?: string | number | Array<string | number>;
267
280
  };
268
281
  /**
269
282
  * Options for `page.type()`.
@@ -21,6 +21,18 @@ export function navFailed(url: string, reason: string): Error & {
21
21
  code: "NAV_FAILED";
22
22
  reason: string;
23
23
  };
24
+ /**
25
+ * Typed error for a top-level navigation the site lock (`allowHosts`) refused:
26
+ * the target, or a redirect hop of it, is off the allowed list. `code` is
27
+ * 'NAV_BLOCKED'; `host` is the refused hostname. The page stays where it was.
28
+ * @param {string} url - The refused URL (the redirect target, if it was a hop).
29
+ * @param {string} host
30
+ * @returns {Error & {code: 'NAV_BLOCKED', host: string}}
31
+ */
32
+ export function navBlocked(url: string, host: string): Error & {
33
+ code: "NAV_BLOCKED";
34
+ host: string;
35
+ };
24
36
  /**
25
37
  * True for a final HTTP status that is not 2xx (0 = unknown is not an error).
26
38
  * @param {number|undefined} status
package/types/prune.d.ts CHANGED
@@ -5,11 +5,13 @@
5
5
  * @param {object} [options]
6
6
  * @param {'act'|'browse'|'navigate'|'full'|'read'} [options.mode='act'] - Pruning mode ('read' is an alias for 'browse')
7
7
  * @param {string} [options.context=''] - Search context for relevance filtering
8
+ * @param {boolean} [options.whole=false] - `tree` is a zoom box (snapshot `within`): it is the whole page, so the landmark step (1) is skipped
8
9
  * @param {boolean} [options.links=false] - Links carry `urls` (see links.js): nodes that drop their children keep the URLs of links beneath them
9
10
  * @returns {object|null} Pruned tree
10
11
  */
11
12
  export function prune(tree: object, options?: {
12
13
  mode?: "act" | "browse" | "navigate" | "full" | "read" | undefined;
13
14
  context?: string | undefined;
15
+ whole?: boolean | undefined;
14
16
  links?: boolean | undefined;
15
17
  }): object | null;
@@ -0,0 +1,70 @@
1
+ /**
2
+ * Validate and normalize an allow list. Entry = `host` or `*.host`; anything
3
+ * else (scheme, port, path, spaces, empty, bare `*`) throws — a typo must never
4
+ * silently widen or drop the lock.
5
+ * @param {string[]} list
6
+ * @returns {string[]} lowercase entries
7
+ */
8
+ export function parseAllowHosts(list: string[]): string[];
9
+ /**
10
+ * Build a URL matcher from an allow list. Non-http(s) URLs (about:, data:,
11
+ * blob:) are allowed; `host` matches that host exactly, `*.host` matches its
12
+ * strict subdomains only (not `host` itself). An unparseable URL is refused.
13
+ * @param {string[]} list
14
+ * @returns {(url: string) => boolean}
15
+ */
16
+ export function makeHostMatcher(list: string[]): (url: string) => boolean;
17
+ /**
18
+ * The lock's shared state, one per connect()/browse() call, surviving
19
+ * relaunches and new tabs (each transport just keeps calling record()).
20
+ * @param {string[]} list
21
+ */
22
+ export function createSiteLock(list: string[]): {
23
+ allowed: (url: string) => boolean;
24
+ /** @param {string} url @throws NAV_BLOCKED when url is off the list */
25
+ assertAllowed(url: string): void;
26
+ /** A top-level document request was refused. ctx = tab/context it belongs to. */
27
+ record(url: any, ctx: any): void;
28
+ /** Call right before a goto navigates; drops that tab's pending notes too. */
29
+ startGoto(ctx: any): void;
30
+ /**
31
+ * The block that hit this goto's own tab (a popup's block is not the
32
+ * goto's), consumed; it is reported as NAV_BLOCKED, so no snapshot note.
33
+ */
34
+ takeGotoBlock(ctx: any): {
35
+ url: string;
36
+ host: string;
37
+ } | null;
38
+ /** Snapshot lines for this tab's in-page blocked jumps since the last call. */
39
+ takeNotes(ctx: any): string;
40
+ };
41
+ /** @typedef {ReturnType<typeof createSiteLock>} SiteLock */
42
+ /**
43
+ * Chromium: lock every page target of this browser. A BROWSER-level
44
+ * Fetch.enable (root client, no sessionId) pauses document requests of every
45
+ * target, popups included, so one handler covers tabs we create later and
46
+ * windows the page opens itself. A request is top-level when its frameId is a
47
+ * page target id (OOPIF iframes are 'iframe' targets, subframes share their
48
+ * parent's id space). 'Aborted' (not BlockedByClient) fails the request but
49
+ * keeps the old page instead of swapping in a chrome-error:// page.
50
+ * Call once per CDP connection, before the first navigation.
51
+ * @param {object} cdp - root CDP client
52
+ * @param {SiteLock} lock
53
+ */
54
+ export function applySiteLockCDP(cdp: object, lock: SiteLock): Promise<void>;
55
+ /**
56
+ * Firefox/BiDi: build the "is this paused request a locked top-level load?"
57
+ * check that blocklist-firefox.js's single intercept handler calls (two
58
+ * catch-all handlers on one paused request would race — one continues before
59
+ * the other fails). A request is a top-level document load when it carries a
60
+ * navigation id and its context has no parent. Context ids are tracked from
61
+ * contextCreated and refreshed from getTree when an unknown one shows up, so a
62
+ * popup whose create event lags its first request can't slip through; one that
63
+ * is still unknown after the refresh is treated as top-level (fail closed).
64
+ * Redirect hops arrive as their own beforeRequestSent, so each is checked.
65
+ * @param {object} bidi - BiDi client
66
+ * @param {SiteLock} lock
67
+ * @returns {Promise<(e: object) => Promise<boolean>>} true = fail this request
68
+ */
69
+ export function createFirefoxLockCheck(bidi: object, lock: SiteLock): Promise<(e: object) => Promise<boolean>>;
70
+ export type SiteLock = ReturnType<typeof createSiteLock>;
@@ -0,0 +1,51 @@
1
+ /**
2
+ * One `within` selector: a ref, or role + optional name / preceding heading.
3
+ * @typedef {{ raw: string, ref?: string, role?: string, name?: string, after?: string }} Selector
4
+ */
5
+ /**
6
+ * Parse `within` (one selector or an array).
7
+ * @param {string|number|Array<string|number>} within
8
+ * @returns {Selector[]}
9
+ */
10
+ export function parseWithin(within: string | number | Array<string | number>): Selector[];
11
+ /**
12
+ * Write the map or a zoom of `tree`. Returns the finished snapshot text
13
+ * (`head` is the url/warning prefix the engine builds), or throws.
14
+ *
15
+ * @param {object} tree - Pruning-ready tree (links already annotated)
16
+ * @param {object} o
17
+ * @param {string} o.head - Text placed first (url line, warnings)
18
+ * @param {boolean} [o.map] - Write the map (ignored when `within` is set)
19
+ * @param {Selector[]} [o.selectors] - parseWithin() result
20
+ * @param {Map<string,string|null>} [o.refNodes] - ref selector → node id in `tree` (null: gone)
21
+ * @param {'act'|'browse'|'navigate'|'full'|'read'|'data'} o.mode - Pruning mode
22
+ * @param {boolean} o.links
23
+ */
24
+ export function zoomSnapshot(tree: object, { head, map, selectors, refNodes, mode, links }: {
25
+ head: string;
26
+ map?: boolean | undefined;
27
+ selectors?: Selector[] | undefined;
28
+ refNodes?: Map<string, string | null> | undefined;
29
+ mode: "act" | "browse" | "navigate" | "full" | "read" | "data";
30
+ links: boolean;
31
+ }): string;
32
+ /**
33
+ * Why a zoom/map came back as a file path only: it is over the inline cap.
34
+ * @param {'zoom'|'map'} kind
35
+ * @param {number} chars
36
+ * @param {number} limit
37
+ * @param {boolean} [cli] - flag spelling (--max-chars, --map) instead of tool arguments
38
+ */
39
+ export function overNote(kind: "zoom" | "map", chars: number, limit: number, cli?: boolean): string;
40
+ /** Roles the map lists (when big enough, or when a `within` matched them). */
41
+ export const BOX_ROLES: Set<string>;
42
+ /**
43
+ * One `within` selector: a ref, or role + optional name / preceding heading.
44
+ */
45
+ export type Selector = {
46
+ raw: string;
47
+ ref?: string;
48
+ role?: string;
49
+ name?: string;
50
+ after?: string;
51
+ };