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/CHANGELOG.md +70 -0
- package/README.md +2 -0
- package/barebrowse.context.md +26 -2
- package/cli.js +19 -1
- package/commands/barebrowse/SKILL.md +5 -0
- package/mcp-server.js +39 -6
- package/package.json +1 -1
- package/src/auth.js +25 -7
- package/src/ax-snapshot.js +24 -5
- package/src/bidi.js +3 -2
- package/src/daemon.js +25 -2
- package/src/data.js +2 -2
- package/src/firefox-page.js +116 -23
- package/src/index.js +105 -26
- package/src/prune.js +3 -2
- package/src/zoom.js +250 -0
- package/types/auth.d.ts +26 -0
- package/types/data.d.ts +2 -1
- package/types/firefox-page.d.ts +2 -2
- package/types/index.d.ts +12 -3
- package/types/prune.d.ts +2 -0
- package/types/zoom.d.ts +51 -0
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.";
|
package/types/firefox-page.d.ts
CHANGED
|
@@ -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;
|
package/types/zoom.d.ts
ADDED
|
@@ -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
|
+
};
|