barebrowse 0.27.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
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.";
@@ -65,8 +65,8 @@ export function createFirefoxPage(bidi: object, opts?: {
65
65
  snapshot(pruneOpts?: import("./index.js").SnapshotOptions | false): Promise<string>;
66
66
  readable(): Promise<any>;
67
67
  click(ref: any): Promise<void>;
68
- /** @param {string} ref @param {string} text @param {import('./index.js').TypeOptions} [typeOpts] */
69
- 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>;
70
70
  press(key: any): Promise<void>;
71
71
  scroll(deltaY: any): Promise<void>;
72
72
  hover(ref: any): Promise<void>;
package/types/index.d.ts CHANGED
@@ -87,7 +87,7 @@ export function connect(opts?: {}): Promise<{
87
87
  snapshot(pruneOpts?: import("./index.js").SnapshotOptions | false): Promise<string>;
88
88
  readable(): Promise<any>;
89
89
  click(ref: any): Promise<void>;
90
- 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>;
91
91
  press(key: any): Promise<void>;
92
92
  scroll(deltaY: any): Promise<void>;
93
93
  hover(ref: any): Promise<void>;
@@ -126,8 +126,8 @@ export function connect(opts?: {}): Promise<{
126
126
  snapshot(pruneOpts?: SnapshotOptions | false): Promise<string>;
127
127
  readable(): Promise<any>;
128
128
  click(ref: any): Promise<void>;
129
- /** @param {string} ref @param {string} text @param {TypeOptions} [typeOpts] */
130
- 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>;
131
131
  scroll(deltaY: any): Promise<void>;
132
132
  press(key: any): Promise<void>;
133
133
  hover(ref: any): Promise<void>;
@@ -264,10 +264,19 @@ export type NavigationOutcome = import("./navigation.js").NavigationOutcome;
264
264
  * pruning and return the raw ARIA tree.
265
265
  * `links: true` adds each link's absolute URL after its name (default off,
266
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`.
267
274
  */
268
275
  export type SnapshotOptions = {
269
276
  mode?: "act" | "browse" | "navigate" | "full" | "read" | "data";
270
277
  links?: boolean;
278
+ map?: boolean;
279
+ within?: string | number | Array<string | number>;
271
280
  };
272
281
  /**
273
282
  * Options for `page.type()`.
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,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
+ };