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/CHANGELOG.md +90 -0
- package/README.md +13 -1
- package/barebrowse.context.md +30 -5
- package/cli.js +39 -3
- package/commands/barebrowse/SKILL.md +6 -0
- package/commands/barebrowse.md +1 -0
- package/mcp-server.js +108 -9
- 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/blocklist-firefox.js +12 -4
- package/src/daemon.js +27 -2
- package/src/data.js +2 -2
- package/src/firefox-page.js +126 -25
- package/src/index.js +152 -37
- package/src/navigation.js +12 -0
- package/src/prune.js +3 -2
- package/src/site-lock.js +184 -0
- package/src/zoom.js +250 -0
- package/types/auth.d.ts +26 -0
- package/types/blocklist-firefox.d.ts +2 -1
- package/types/data.d.ts +2 -1
- package/types/firefox-page.d.ts +14 -2
- package/types/index.d.ts +16 -3
- package/types/navigation.d.ts +12 -0
- package/types/prune.d.ts +2 -0
- package/types/site-lock.d.ts +70 -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
|
|
@@ -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.";
|
package/types/firefox-page.d.ts
CHANGED
|
@@ -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()`.
|
package/types/navigation.d.ts
CHANGED
|
@@ -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>;
|
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
|
+
};
|