barebrowse 0.24.1 → 0.26.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/prune.js CHANGED
@@ -62,6 +62,7 @@ const SKIP_ROLES = new Set([
62
62
  * @param {object} [options]
63
63
  * @param {'act'|'browse'|'navigate'|'full'|'read'} [options.mode='act'] - Pruning mode ('read' is an alias for 'browse')
64
64
  * @param {string} [options.context=''] - Search context for relevance filtering
65
+ * @param {boolean} [options.links=false] - Links carry `urls` (see links.js): nodes that drop their children keep the URLs of links beneath them
65
66
  * @returns {object|null} Pruned tree
66
67
  */
67
68
  export function prune(tree, options = {}) {
@@ -80,7 +81,7 @@ export function prune(tree, options = {}) {
80
81
  nodes = extractRegions(nodes, allowedRegions);
81
82
 
82
83
  // Step 2: Prune nodes
83
- const ctx = { mode, parentRole: null, keywords };
84
+ const ctx = { mode, parentRole: null, keywords, links: !!options.links };
84
85
  nodes = nodes.map((n) => pruneNode(n, ctx)).filter(Boolean);
85
86
 
86
87
  // Step 3: Collapse structural wrappers
@@ -204,7 +205,7 @@ function pruneNode(node, ctx) {
204
205
  return { ...node, children: pruneChildren(node.children, ctx) };
205
206
  }
206
207
  if (node.role === 'group' && node.name) {
207
- if (!isBrowse && /kleuren|colors?|couleurs?|farben/i.test(node.name)) {
208
+ if (!isBrowse && !ctx.links && /kleuren|colors?|couleurs?|farben/i.test(node.name)) {
208
209
  return collapseColors(node);
209
210
  }
210
211
  return { ...node, children: pruneChildren(node.children, ctx) };
@@ -217,7 +218,7 @@ function pruneNode(node, ctx) {
217
218
  return null;
218
219
  }
219
220
  }
220
- return { ...node, children: [] };
221
+ return { ...node, children: [], ...carryUrls(node, ctx) };
221
222
  }
222
223
 
223
224
  // StaticText — CDP equivalent of mcprune's "text" nodes
@@ -448,6 +449,13 @@ function flatten(nodes) {
448
449
  return result;
449
450
  }
450
451
 
452
+ // Links on: a node that drops its children keeps the URLs of the links beneath it.
453
+ function carryUrls(node, ctx) {
454
+ if (!ctx.links) return {};
455
+ const urls = [...new Set(flatten([node]).flatMap((n) => n.urls || []))];
456
+ return urls.length ? { urls } : {};
457
+ }
458
+
451
459
  function condenseCard(node) {
452
460
  const all = flatten([node]);
453
461
  const link = all.find((n) => n.role === 'link' && n.name);
package/types/aria.d.ts CHANGED
@@ -1,9 +1,3 @@
1
- /**
2
- * aria.js — Format ARIA accessibility tree nodes for agent consumption.
3
- *
4
- * Takes a nested tree (built from CDP's Accessibility.getFullAXTree)
5
- * and formats it as readable YAML-like text, similar to Playwright's ariaSnapshot.
6
- */
7
1
  /**
8
2
  * Format a nested ARIA tree as readable text output.
9
3
  *
@@ -8,5 +8,7 @@
8
8
  * pattern is added once and both engines get it.
9
9
  */
10
10
  export const ACCEPT_PATTERNS: RegExp[];
11
+ export const DIALOG_ONLY_ACCEPT_PATTERNS: RegExp[];
12
+ export const DIALOG_ACCEPT_PATTERNS: RegExp[];
11
13
  export const DIALOG_ROLES: Set<string>;
12
14
  export const CONSENT_DIALOG_HINTS: RegExp[];
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Render a raw ARIA tree in data mode.
3
+ *
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
6
+ * @returns {string} LEGEND line, then one line per record, YAML-ish like formatTree(); '' when there are no records
7
+ */
8
+ export function dataSnapshot(root: object, opts?: {
9
+ links?: boolean;
10
+ }): string;
11
+ /** First line of every data-mode snapshot: tells an agent with no docs how to read it. */
12
+ 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.";
13
+ /** Appended to the legend only when links are on. */
14
+ export const LINKS_NOTE: " Links: \"name\" <url>.";
15
+ export function stripLegend(s: any): any;
@@ -2,7 +2,8 @@
2
2
  * Build a Firefox/BiDi-backed page object.
3
3
  * @param {object} bidi - BiDi client from createBiDi()
4
4
  * @param {object} [opts]
5
- * @param {'act'|'browse'|'navigate'|'full'|'read'} [opts.pruneMode='act'] - Default prune mode.
5
+ * @param {'act'|'browse'|'navigate'|'full'|'read'|'data'} [opts.pruneMode='act'] - Default prune mode.
6
+ * @param {boolean} [opts.links=false] - Default for snapshot({ links }): show link URLs.
6
7
  * @param {{allowLocalUrls?: boolean, blockPrivateNetwork?: boolean}} [opts.urlGuard] - Navigation safety policy, applied on every goto().
7
8
  * @param {string} [opts.uploadDir] - When set, upload() rejects files outside this dir.
8
9
  * @param {boolean} [opts.incognito=false] - Clean session: injectCookies() is a no-op.
@@ -12,7 +13,8 @@
12
13
  * @param {?function(): Promise<{bidi: object, topContext: string}>} [opts.relaunchHeaded] - Hybrid relaunch hook (from connectFirefox).
13
14
  */
14
15
  export function createFirefoxPage(bidi: object, opts?: {
15
- pruneMode?: "act" | "browse" | "navigate" | "full" | "read" | undefined;
16
+ pruneMode?: "data" | "act" | "browse" | "navigate" | "full" | "read" | undefined;
17
+ links?: boolean | undefined;
16
18
  urlGuard?: {
17
19
  allowLocalUrls?: boolean;
18
20
  blockPrivateNetwork?: boolean;
@@ -33,6 +35,8 @@ export function createFirefoxPage(bidi: object, opts?: {
33
35
  readonly context: any;
34
36
  /** Whether the last goto() landed on a bot-challenge page (parity w/ CDP). */
35
37
  readonly botBlocked: boolean;
38
+ /** Outcome of the latest goto(): `{url, status}`, or null before any goto. */
39
+ readonly lastNavigation: import("./navigation.js").NavigationOutcome | null;
36
40
  /** @type {'firefox'} Engine driving this session (see also `capabilities`). */
37
41
  engine: "firefox";
38
42
  /**
@@ -44,7 +48,7 @@ export function createFirefoxPage(bidi: object, opts?: {
44
48
  * @type {import('./index.js').Capabilities}
45
49
  */
46
50
  capabilities: import("./index.js").Capabilities;
47
- goto(url: any, timeout?: number): Promise<void>;
51
+ goto(url: any, timeout?: number): Promise<import("./navigation.js").NavigationOutcome>;
48
52
  /** @param {import('./index.js').SnapshotOptions|false} [pruneOpts] */
49
53
  snapshot(pruneOpts?: import("./index.js").SnapshotOptions | false): Promise<string>;
50
54
  readable(): Promise<any>;
package/types/index.d.ts CHANGED
@@ -25,7 +25,8 @@
25
25
  * @param {{width: number, height: number}} [opts.viewport] - Viewport dimensions.
26
26
  * @param {string} [opts.browser] - Source browser for cookie extraction.
27
27
  * @param {boolean} [opts.consent=true] - Auto-dismiss cookie consent dialogs.
28
- * @param {'act'|'browse'|'navigate'|'full'|'read'} [opts.pruneMode='act'] - Pruning mode.
28
+ * @param {'act'|'browse'|'navigate'|'full'|'read'|'data'} [opts.pruneMode='act'] - Pruning mode.
29
+ * @param {boolean} [opts.links=false] - Show link URLs: `link "name" <url> [ref=N]`.
29
30
  * @returns {Promise<string>} ARIA snapshot text
30
31
  */
31
32
  export function browse(url: string, opts?: {
@@ -47,7 +48,8 @@ export function browse(url: string, opts?: {
47
48
  } | undefined;
48
49
  browser?: string | undefined;
49
50
  consent?: boolean | undefined;
50
- pruneMode?: "act" | "browse" | "navigate" | "full" | "read" | undefined;
51
+ pruneMode?: "data" | "act" | "browse" | "navigate" | "full" | "read" | undefined;
52
+ links?: boolean | undefined;
51
53
  }): Promise<string>;
52
54
  /**
53
55
  * Decide which engine connect() should use. Pure — the caller passes lazy
@@ -74,9 +76,10 @@ export function connect(opts?: {}): Promise<{
74
76
  readonly bidi: any;
75
77
  readonly context: any;
76
78
  readonly botBlocked: boolean;
79
+ readonly lastNavigation: import("./navigation.js").NavigationOutcome | null;
77
80
  engine: "firefox";
78
81
  capabilities: import("./index.js").Capabilities;
79
- goto(url: any, timeout?: number): Promise<void>;
82
+ goto(url: any, timeout?: number): Promise<import("./navigation.js").NavigationOutcome>;
80
83
  snapshot(pruneOpts?: import("./index.js").SnapshotOptions | false): Promise<string>;
81
84
  readable(): Promise<any>;
82
85
  click(ref: any): Promise<void>;
@@ -109,7 +112,7 @@ export function connect(opts?: {}): Promise<{
109
112
  waitForNavigation(timeout?: number): Promise<void>;
110
113
  close(): Promise<void>;
111
114
  } | {
112
- goto(url: any, timeout?: number): Promise<void>;
115
+ goto(url: any, timeout?: number): Promise<import("./navigation.js").NavigationOutcome>;
113
116
  goBack(): Promise<void>;
114
117
  goForward(): Promise<void>;
115
118
  reload(reloadOpts?: {}): Promise<void>;
@@ -133,6 +136,8 @@ export function connect(opts?: {}): Promise<{
133
136
  waitFor(waitOpts?: {}): Promise<void>;
134
137
  saveState(filePath: any): Promise<void>;
135
138
  readonly botBlocked: boolean;
139
+ /** Outcome of the latest goto(): `{url, status}`, or null before any goto. */
140
+ readonly lastNavigation: import("./navigation.js").NavigationOutcome | null;
136
141
  /** @type {'chromium'} Engine driving this session (see also `capabilities`) */
137
142
  engine: "chromium";
138
143
  /**
@@ -159,7 +164,7 @@ export function connect(opts?: {}): Promise<{
159
164
  /** Raw CDP session for escape hatch — getter so it survives hybrid fallback / tab swaps */
160
165
  readonly cdp: any;
161
166
  createTab(): Promise<{
162
- goto(url: any, timeout?: number): Promise<void>;
167
+ goto(url: any, timeout?: number): Promise<import("./navigation.js").NavigationOutcome>;
163
168
  readonly botBlocked: boolean;
164
169
  /** @param {string} url @param {CookieOptions} [cookieOpts] */
165
170
  injectCookies(url: string, cookieOpts?: CookieOptions): Promise<number>;
@@ -243,12 +248,22 @@ export type Capabilities = {
243
248
  */
244
249
  cookieInjection: boolean;
245
250
  };
251
+ /**
252
+ * What `goto()` resolves to: the final URL (after redirects) and the main
253
+ * document's HTTP status (0 when no HTTP response was observed, e.g. an aborted navigation).
254
+ * Network failures reject with an Error whose `code` is 'NAV_FAILED' and
255
+ * `reason` the browser's raw error string.
256
+ */
257
+ export type NavigationOutcome = import("./navigation.js").NavigationOutcome;
246
258
  /**
247
259
  * Options for `page.snapshot()`. Pass `false` instead of an object to skip
248
260
  * pruning and return the raw ARIA tree.
261
+ * `links: true` adds each link's absolute URL after its name (default off,
262
+ * or the `connect({ links })` default).
249
263
  */
250
264
  export type SnapshotOptions = {
251
- mode?: "act" | "browse" | "navigate" | "full" | "read";
265
+ mode?: "act" | "browse" | "navigate" | "full" | "read" | "data";
266
+ links?: boolean;
252
267
  };
253
268
  /**
254
269
  * Options for `page.type()`.
@@ -0,0 +1,28 @@
1
+ /**
2
+ * links.js — opt-in link URLs for snapshots (`links: true`).
3
+ *
4
+ * `annotateLinks()` stamps `urls: [url]` on every link node that has a usable
5
+ * browser-serialized absolute URL. aria.js, prune.js and data.js print/carry
6
+ * `urls` — they never see the option, so with links off nothing changes.
7
+ */
8
+ /**
9
+ * Normalise a link's URL for a snapshot line. Returns '' when it should not be
10
+ * shown: no URL, `javascript:`, or a same-document link (the page URL, only
11
+ * the #fragment differs). A raw space, `<` or `>` (browsers encode them, but
12
+ * not always in the fragment) is percent-encoded so a line splits cleanly on
13
+ * ` <` and `> `.
14
+ *
15
+ * @param {string|undefined} url - Absolute URL as serialized by the browser
16
+ * @param {string} [pageUrl] - URL of the page the link is on
17
+ * @returns {string}
18
+ */
19
+ export function linkUrl(url: string | undefined, pageUrl?: string): string;
20
+ /**
21
+ * Copy a tree with `urls` set on its link nodes (input is not mutated).
22
+ *
23
+ * @param {object|null} node - Root from buildTree()
24
+ * @param {string} pageUrl
25
+ * @returns {object|null}
26
+ */
27
+ export function annotateLinks(node: object | null, pageUrl: string): object | null;
28
+ export function urlsText(urls: any): any;
@@ -0,0 +1,44 @@
1
+ /**
2
+ * navigation.js — Shared pieces of the goto() outcome contract, so both
3
+ * engines (CDP in index.js, BiDi in firefox-page.js) report it identically.
4
+ */
5
+ /**
6
+ * What goto() resolves to: where the page ended up and how the server answered.
7
+ * `status` is 0 when no HTTP response was observed for the navigation (e.g. an
8
+ * aborted navigation that never got one).
9
+ * @typedef {{ url: string, status: number }} NavigationOutcome
10
+ */
11
+ /**
12
+ * Typed error for a navigation that never reached a document (DNS failure,
13
+ * connection refused, TLS error, ...). `code` is 'NAV_FAILED'; `reason` is the
14
+ * browser's raw error string (`net::ERR_NAME_NOT_RESOLVED`,
15
+ * `NS_ERROR_UNKNOWN_HOST`, ...).
16
+ * @param {string} url
17
+ * @param {string} reason
18
+ * @returns {Error & {code: 'NAV_FAILED', reason: string}}
19
+ */
20
+ export function navFailed(url: string, reason: string): Error & {
21
+ code: "NAV_FAILED";
22
+ reason: string;
23
+ };
24
+ /**
25
+ * True for a final HTTP status that is not 2xx (0 = unknown is not an error).
26
+ * @param {number|undefined} status
27
+ */
28
+ export function isHttpError(status: number | undefined): boolean;
29
+ /**
30
+ * Warning line for a non-2xx final status ('' for 2xx and for unknown 0), in
31
+ * the style of the bot-challenge line, newline-terminated for prepending.
32
+ * @param {number|undefined} status
33
+ * @returns {string}
34
+ */
35
+ export function httpWarning(status: number | undefined): string;
36
+ /**
37
+ * What goto() resolves to: where the page ended up and how the server answered.
38
+ * `status` is 0 when no HTTP response was observed for the navigation (e.g. an
39
+ * aborted navigation that never got one).
40
+ */
41
+ export type NavigationOutcome = {
42
+ url: string;
43
+ status: number;
44
+ };
package/types/prune.d.ts CHANGED
@@ -5,9 +5,11 @@
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.links=false] - Links carry `urls` (see links.js): nodes that drop their children keep the URLs of links beneath them
8
9
  * @returns {object|null} Pruned tree
9
10
  */
10
11
  export function prune(tree: object, options?: {
11
12
  mode?: "act" | "browse" | "navigate" | "full" | "read" | undefined;
12
13
  context?: string | undefined;
14
+ links?: boolean | undefined;
13
15
  }): object | null;