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.
@@ -20,6 +20,7 @@ import { prune as pruneTree } from './prune.js';
20
20
  import { dataSnapshot, stripLegend } from './data.js';
21
21
  import { annotateLinks } from './links.js';
22
22
  import { axSnapshotExpression, REF_ATTR } from './ax-snapshot.js';
23
+ import { parseWithin, zoomSnapshot } from './zoom.js';
23
24
  import { EXTRACT_EXPRESSION, finalizeReadable } from './readable.js';
24
25
  import { scopedCookiesForUrl } from './auth.js';
25
26
  import { assertNavigable, assertUploadAllowed } from './url-guard.js';
@@ -30,6 +31,9 @@ import { isChallengePage, countNodes } from './challenge.js';
30
31
  import { withTimeout } from './with-timeout.js';
31
32
  import { navFailed, navBlocked, httpWarning } from './navigation.js';
32
33
 
34
+ // Isolated BiDi realm holding the per-document stale-ref token (page script cannot reach it).
35
+ const DOC_SANDBOX = 'barebrowse';
36
+
33
37
  /** BiDi/WebDriver normalized key values for named keys (U+E000 block). */
34
38
  const BIDI_KEYS = {
35
39
  Enter: "\uE007", Tab: "\uE004", Escape: "\uE00C", Backspace: "\uE003",
@@ -91,6 +95,10 @@ export async function createFirefoxPage(bidi, opts = {}) {
91
95
  // ref (string int) → owning browsing-context id, rebuilt every snapshot so a
92
96
  // click after a snapshot routes to the frame the element actually lives in.
93
97
  let refContexts = new Map();
98
+ // context id → identity token stamped on that context's document at snapshot time.
99
+ // A document restored from the back/forward cache keeps its old data-bb-ref marks;
100
+ // its token differs from the one remembered here, so its refs are rejected.
101
+ let docTokens = new Map();
94
102
 
95
103
  /**
96
104
  * Depth-first list of the ACTIVE tab's contexts (main frame + descendant
@@ -119,6 +127,7 @@ export async function createFirefoxPage(bidi, opts = {}) {
119
127
  async function buildTree() {
120
128
  const contextIds = await allContexts();
121
129
  refContexts = new Map();
130
+ docTokens = new Map();
122
131
 
123
132
  // Snapshot each context, assigning refs from a shared running counter so
124
133
  // they're globally unique (matching CDP's flat integer refs).
@@ -127,7 +136,11 @@ export async function createFirefoxPage(bidi, opts = {}) {
127
136
  for (const ctx of contextIds) {
128
137
  let raw;
129
138
  try {
139
+ const token = Math.random().toString(36).slice(2);
130
140
  raw = await bidi.evaluate(ctx, axSnapshotExpression(base), false);
141
+ // The token lives in a sandbox realm: page script can neither read, delete nor break it.
142
+ await bidi.evaluate(ctx, `globalThis.__bbDoc = ${JSON.stringify(token)}`, false, DOC_SANDBOX);
143
+ docTokens.set(ctx, token);
131
144
  } catch { continue; } // frame navigated mid-snapshot — skip it
132
145
  const { tree, count } = JSON.parse(raw);
133
146
  for (let r = base + 1; r <= base + count; r++) refContexts.set(String(r), ctx);
@@ -161,17 +174,54 @@ export async function createFirefoxPage(bidi, opts = {}) {
161
174
  const context = refContexts.get(String(ref));
162
175
  if (!context) throw new Error(`Unknown ref: ${ref} (snapshot first, or it's stale)`);
163
176
  const res = await bidi.send('script.evaluate', {
164
- expression: `document.querySelector('[${REF_ATTR}="${ref}"]')`,
165
- target: { context }, awaitPromise: false, resultOwnership: 'root',
177
+ expression: `globalThis.__bbDoc === ${JSON.stringify(docTokens.get(context))} ? document.querySelector('[${REF_ATTR}="${ref}"]') : 'stale'`,
178
+ target: { context, sandbox: DOC_SANDBOX }, awaitPromise: false, resultOwnership: 'root',
166
179
  });
180
+ if (res.type === 'success' && res.result.type === 'string') {
181
+ throw new Error(`No element found for ref "${ref}" — the page navigated since the snapshot that gave it; take a fresh snapshot`);
182
+ }
167
183
  if (res.type === 'exception' || !res.result || res.result.type !== 'node') {
168
184
  throw new Error(`Could not resolve element for ref ${ref}`);
169
185
  }
170
186
  return { context, sharedId: res.result.sharedId };
171
187
  }
172
188
 
189
+ /** BiDi pointer moves do not scroll (Chromium's click does): bring the element on-screen first. */
190
+ async function scrollIntoView({ context, sharedId }) {
191
+ await bidi.send('script.callFunction', {
192
+ functionDeclaration: `function(){ this.scrollIntoView({ block: 'center', inline: 'center' }); }`,
193
+ this: { sharedId }, target: { context }, awaitPromise: false,
194
+ });
195
+ }
196
+
197
+ /** Mark the elements behind `within` ref selectors (in their frame) before a rebuild renumbers the refs. */
198
+ async function markRefs(selectors) {
199
+ const marks = new Map(); // old ref → context
200
+ for (const { ref } of selectors) {
201
+ if (!ref) continue;
202
+ const context = refContexts.get(ref);
203
+ if (!context) throw new Error(`within: ref ${ref} is not in the last snapshot (refs renumber on every snapshot and reset on navigation) — take a fresh ref from snapshot({ map: true })`);
204
+ const ok = await bidi.evaluate(context, `(() => { if (globalThis.__bbDoc !== ${JSON.stringify(docTokens.get(context))}) return false; const e = document.querySelector('[${REF_ATTR}="${ref}"]'); if (e) e.setAttribute('data-bb-zoom', '${ref}'); return !!e; })()`, false, DOC_SANDBOX).catch(() => false);
205
+ if (!ok) throw new Error(`within: the element behind ref ${ref} is no longer on the page — take a fresh ref from snapshot({ map: true })`);
206
+ marks.set(ref, context);
207
+ }
208
+ return marks;
209
+ }
210
+
211
+ /** Read (and clear) the marks after a rebuild: old ref → its new ref, or null when the element is gone. */
212
+ async function readMarks(marks) {
213
+ const refNodes = new Map();
214
+ for (const [ref, context] of marks) {
215
+ const now = await bidi.evaluate(context, `(() => { const e = document.querySelector('[data-bb-zoom="${ref}"]'); if (!e) return null; e.removeAttribute('data-bb-zoom'); return e.getAttribute('${REF_ATTR}'); })()`, false).catch(() => null);
216
+ refNodes.set(ref, now);
217
+ }
218
+ return refNodes;
219
+ }
220
+
173
221
  async function pointerClick(ref) {
174
- const { context, sharedId } = await resolveRef(ref);
222
+ const target = await resolveRef(ref);
223
+ await scrollIntoView(target);
224
+ const { context, sharedId } = target;
175
225
  await bidi.send('input.performActions', {
176
226
  context,
177
227
  actions: [{
@@ -309,6 +359,25 @@ export async function createFirefoxPage(bidi, opts = {}) {
309
359
  }
310
360
  }
311
361
 
362
+ // Settle after the accept click like consent.js does (1s): a consent form
363
+ // submits and navigates, and the click returns before the next page lands, so
364
+ // the snapshot would still show the interstitial.
365
+ // That landed document is the page goto() now reports (not the interstitial's).
366
+ async function consentClick(ref) {
367
+ const docs = [];
368
+ const off = bidi.on('network.responseCompleted', (e) => {
369
+ if (e.navigation && e.context === topContext) docs.push(e);
370
+ });
371
+ try {
372
+ await pointerClick(ref);
373
+ await new Promise((r) => setTimeout(r, 1000));
374
+ } finally {
375
+ off();
376
+ const last = docs.pop();
377
+ if (last) lastNavigation = { url: last.response.url, status: last.response.status };
378
+ }
379
+ }
380
+
312
381
  /**
313
382
  * Post-navigation routine shared by goto() and the hybrid retry: settle for
314
383
  * dynamic content, auto-dismiss consent (best-effort), then report whether
@@ -324,9 +393,13 @@ export async function createFirefoxPage(bidi, opts = {}) {
324
393
  try { root = await buildTree(); } catch { /* null → treated as challenge */ }
325
394
  consentRecheck = null;
326
395
  if (consent && root) {
327
- try { if (!(await dismissConsentFirefox(root, (ref) => pointerClick(ref)))) consentRecheck = await docKey(); }
396
+ try { if (!(await dismissConsentFirefox(root, consentClick))) consentRecheck = await docKey(); }
328
397
  catch { /* consent dismissal is best-effort */ }
329
398
  }
399
+ // The tree above was built for these internal passes, not shown to the caller: refs
400
+ // from before this navigation must stay dead (Chromium's goto never hands out refs
401
+ // either), or an old ref number resolves to a different element of the new page.
402
+ refContexts = new Map();
330
403
  return isChallengePage(root, countNodes(root));
331
404
  }
332
405
 
@@ -404,13 +477,24 @@ export async function createFirefoxPage(bidi, opts = {}) {
404
477
 
405
478
  /** @param {import('./index.js').SnapshotOptions|false} [pruneOpts] */
406
479
  async snapshot(pruneOpts = {}) {
407
- let root = await buildTree();
408
- if (root && consentRecheck) {
409
- const key = consentRecheck;
410
- consentRecheck = null; // once per navigation
411
- try {
412
- if (key === await docKey() && await dismissConsentFirefox(root, (ref) => pointerClick(ref))) root = await buildTree();
413
- } catch { /* best-effort */ }
480
+ // A `within` ref names an element of the previous snapshot. Refs renumber
481
+ // on every build, so mark the elements now and read their new refs after it.
482
+ const within = (pruneOpts || undefined)?.within;
483
+ const selectors = within != null ? parseWithin(within) : undefined;
484
+ const marks = await markRefs(selectors || []);
485
+ let root, refNodes;
486
+ try {
487
+ root = await buildTree();
488
+ if (root && consentRecheck) {
489
+ const key = consentRecheck;
490
+ consentRecheck = null; // once per navigation
491
+ try {
492
+ if (key === await docKey() && await dismissConsentFirefox(root, consentClick)) root = await buildTree();
493
+ } catch { /* best-effort */ }
494
+ }
495
+ } finally { refNodes = await readMarks(marks); }
496
+ for (const [ref, now] of refNodes) {
497
+ if (now == null) throw new Error(`within: the element behind ref ${ref} is no longer on the page — take a fresh ref from snapshot({ map: true })`);
414
498
  }
415
499
  if (!root) return '';
416
500
 
@@ -422,6 +506,9 @@ export async function createFirefoxPage(bidi, opts = {}) {
422
506
  if (pruneOpts === false) return `url: ${pageUrl}\n` + warn + (links ? formatTree(tree) : raw);
423
507
 
424
508
  const mode = pruneOpts?.mode || defaultPruneMode;
509
+ if (pruneOpts?.map || selectors) {
510
+ return zoomSnapshot(tree, { head: `url: ${pageUrl}\n` + warn, map: true, selectors, refNodes, mode, links });
511
+ }
425
512
  let out;
426
513
  if (mode === 'data') out = dataSnapshot(tree, { links });
427
514
  else { const pruned = pruneTree(tree, { mode, links }); out = pruned ? formatTree(pruned) : ''; }
@@ -438,7 +525,7 @@ export async function createFirefoxPage(bidi, opts = {}) {
438
525
 
439
526
  async click(ref) { await pointerClick(ref); },
440
527
 
441
- /** @param {string} ref @param {string} text @param {import('./index.js').TypeOptions} [typeOpts] */
528
+ /** @param {string|number} ref @param {string} text @param {import('./index.js').TypeOptions} [typeOpts] */
442
529
  async type(ref, text, typeOpts = {}) {
443
530
  const { context, sharedId } = await resolveRef(ref);
444
531
  // Focus the field (and optionally clear it) in-page, then send real key
@@ -466,7 +553,9 @@ export async function createFirefoxPage(bidi, opts = {}) {
466
553
  },
467
554
 
468
555
  async hover(ref) {
469
- const { context, sharedId } = await resolveRef(ref);
556
+ const target = await resolveRef(ref);
557
+ await scrollIntoView(target);
558
+ const { context, sharedId } = target;
470
559
  await bidi.send('input.performActions', {
471
560
  context,
472
561
  actions: [{
@@ -537,18 +626,22 @@ export async function createFirefoxPage(bidi, opts = {}) {
537
626
  if (from.context !== to.context) {
538
627
  throw new Error('drag() between elements in different frames is not supported');
539
628
  }
540
- await bidi.send('input.performActions', {
629
+ // Two calls so each target is scrolled into view before its move; the
630
+ // pressed-pointer state carries over between performActions calls.
631
+ const drag = (actions) => bidi.send('input.performActions', {
541
632
  context: from.context,
542
- actions: [{
543
- type: 'pointer', id: 'mouse', parameters: { pointerType: 'mouse' },
544
- actions: [
545
- { type: 'pointerMove', x: 0, y: 0, origin: { type: 'element', element: { sharedId: from.sharedId } } },
546
- { type: 'pointerDown', button: 0 },
547
- { type: 'pointerMove', x: 0, y: 0, origin: { type: 'element', element: { sharedId: to.sharedId } } },
548
- { type: 'pointerUp', button: 0 },
549
- ],
550
- }],
633
+ actions: [{ type: 'pointer', id: 'mouse', parameters: { pointerType: 'mouse' }, actions }],
551
634
  });
635
+ await scrollIntoView(from);
636
+ await drag([
637
+ { type: 'pointerMove', x: 0, y: 0, origin: { type: 'element', element: { sharedId: from.sharedId } } },
638
+ { type: 'pointerDown', button: 0 },
639
+ ]);
640
+ await scrollIntoView(to);
641
+ await drag([
642
+ { type: 'pointerMove', x: 0, y: 0, origin: { type: 'element', element: { sharedId: to.sharedId } } },
643
+ { type: 'pointerUp', button: 0 },
644
+ ]);
552
645
  },
553
646
 
554
647
  async upload(ref, files) {
package/src/index.js CHANGED
@@ -18,6 +18,7 @@ import { authenticate } from './auth.js';
18
18
  import { prune as pruneTree } from './prune.js';
19
19
  import { dataSnapshot, stripLegend } from './data.js';
20
20
  import { annotateLinks } from './links.js';
21
+ import { parseWithin, zoomSnapshot } from './zoom.js';
21
22
  import { click as cdpClick, type as cdpType, scroll as cdpScroll, press as cdpPress, hover as cdpHover, select as cdpSelect, drag as cdpDrag, upload as cdpUpload } from './interact.js';
22
23
  import { dismissConsent } from './consent.js';
23
24
  import { applyStealth } from './stealth.js';
@@ -234,7 +235,14 @@ export async function browse(url, opts = {}) {
234
235
  * pruning and return the raw ARIA tree.
235
236
  * `links: true` adds each link's absolute URL after its name (default off,
236
237
  * or the `connect({ links })` default).
237
- * @typedef {{ mode?: 'act'|'browse'|'navigate'|'full'|'read'|'data', links?: boolean }} SnapshotOptions
238
+ * `map: true` returns an outline of the page's big boxes (ref + size) instead of
239
+ * content. `within` zooms the snapshot to one box, or several (an array, output
240
+ * in page order): a ref from the map, a role (`'table'`), role + accessible name
241
+ * (`'list "Issues"'`) or an unnamed box by the heading before it
242
+ * (`'list after "Other flights"'`). Any `mode` and `links` apply inside a zoom,
243
+ * where the box is the whole page. Two or more matches return the map with the
244
+ * matches marked; none, or a ref that is gone, throws. `within` wins over `map`.
245
+ * @typedef {{ mode?: 'act'|'browse'|'navigate'|'full'|'read'|'data', links?: boolean, map?: boolean, within?: string|number|Array<string|number> }} SnapshotOptions
238
246
  */
239
247
 
240
248
  /**
@@ -406,6 +414,9 @@ export async function connect(opts = {}) {
406
414
  };
407
415
  let page = await createPage(cdp, !currentlyHeaded, pageOpts);
408
416
  let refMap = new Map();
417
+ // Main-document identity (navKey) when the current refs were handed out; read again
418
+ // fresh at every ref use, so a click/press that navigated to a new document kills them.
419
+ let refDoc = null;
409
420
  let botBlocked = false;
410
421
  // Outcome of the latest goto() ({url, status}); null before any goto.
411
422
  /** @type {NavigationOutcome|null} */
@@ -426,6 +437,38 @@ export async function connect(opts = {}) {
426
437
  } catch { return null; }
427
438
  }
428
439
 
440
+ /** Resolve a ref from the last snapshot; throws when the document it belongs to is gone. */
441
+ async function refEntry(ref) {
442
+ const entry = refMap.get(String(ref));
443
+ if (!entry) throw new Error(`No element found for ref "${ref}"`);
444
+ if (refDoc) {
445
+ const now = await navKey();
446
+ if (now && now !== refDoc) {
447
+ refMap = new Map(); refDoc = null;
448
+ throw new Error(`No element found for ref "${ref}" — the page navigated since the snapshot that gave it; take a fresh snapshot`);
449
+ }
450
+ }
451
+ return entry;
452
+ }
453
+
454
+ // A consent accept that navigates (a form submit, Google's consent.google.com) lands on
455
+ // the real page: report that document in lastNavigation, not the interstitial's.
456
+ async function dismissConsentTracked() {
457
+ const docs = [];
458
+ let off = () => {};
459
+ try {
460
+ const { frameTree } = await page.session.send('Page.getFrameTree');
461
+ off = page.session.on('Network.responseReceived', (p) => {
462
+ if (p.type === 'Document' && p.frameId === frameTree.frame.id) docs.push(p);
463
+ });
464
+ } catch { /* no tracking; dismissal itself still runs */ }
465
+ try { return await dismissConsent(page.session); } finally {
466
+ off();
467
+ const last = docs.pop();
468
+ if (last) lastNavigation = { url: last.response.url, status: last.response.status };
469
+ }
470
+ }
471
+
429
472
  // Suppress permission prompts. Skipped in attach mode — Browser.setPermission
430
473
  // is browser-wide (no origin scope here), so flipping permissions to denied
431
474
  // would leak into the user's other tabs.
@@ -553,7 +596,7 @@ export async function connect(opts = {}) {
553
596
 
554
597
  lastNavigation = await navigate(page, url, timeout, lock);
555
598
  if (opts.consent !== false) {
556
- const dismissed = await dismissConsent(page.session);
599
+ const dismissed = await dismissConsentTracked();
557
600
  if (!dismissed) consentRecheck = await navKey();
558
601
  }
559
602
 
@@ -578,7 +621,7 @@ export async function connect(opts = {}) {
578
621
  await suppressPermissions(cdp);
579
622
  lastNavigation = await navigate(page, url, timeout, lock);
580
623
  consentRecheck = null;
581
- if (opts.consent !== false && !(await dismissConsent(page.session))) {
624
+ if (opts.consent !== false && !(await dismissConsentTracked())) {
582
625
  consentRecheck = await navKey();
583
626
  }
584
627
 
@@ -596,9 +639,7 @@ export async function connect(opts = {}) {
596
639
  async goBack() {
597
640
  const { currentIndex, entries } = await page.session.send('Page.getNavigationHistory');
598
641
  if (currentIndex <= 0) throw new Error('No previous page in history');
599
- const loadPromise = page.session.once('Page.loadEventFired', 30000);
600
- await page.session.send('Page.navigateToHistoryEntry', { entryId: entries[currentIndex - 1].id });
601
- try { await loadPromise; } catch { await new Promise((r) => setTimeout(r, 500)); }
642
+ await traverse(page, entries[currentIndex - 1].id);
602
643
  refMap = new Map(); // refs from the previous page are now invalid
603
644
  consentRecheck = null;
604
645
  lastNavigation = null; // no outcome is known for the history entry we landed on
@@ -607,9 +648,7 @@ export async function connect(opts = {}) {
607
648
  async goForward() {
608
649
  const { currentIndex, entries } = await page.session.send('Page.getNavigationHistory');
609
650
  if (currentIndex >= entries.length - 1) throw new Error('No next page in history');
610
- const loadPromise = page.session.once('Page.loadEventFired', 30000);
611
- await page.session.send('Page.navigateToHistoryEntry', { entryId: entries[currentIndex + 1].id });
612
- try { await loadPromise; } catch { await new Promise((r) => setTimeout(r, 500)); }
651
+ await traverse(page, entries[currentIndex + 1].id);
613
652
  refMap = new Map();
614
653
  consentRecheck = null;
615
654
  lastNavigation = null;
@@ -642,11 +681,15 @@ export async function connect(opts = {}) {
642
681
  consentRecheck = null; // once per navigation
643
682
  // Only if we are still on the document the goto landed on.
644
683
  if (key === await navKey()) {
645
- try { await dismissConsent(page.session); } catch { /* best-effort */ }
684
+ try { await dismissConsentTracked(); } catch { /* best-effort */ }
646
685
  }
647
686
  }
687
+ // a navigation since the last snapshot leaves nothing for a `within` ref to name
688
+ const prevRefMap = refDoc && (await navKey() ?? refDoc) !== refDoc ? new Map() : refMap;
689
+ const docBefore = await navKey(); // before the tree: a navigation mid-build leaves the refs stale, not live
648
690
  const result = await ariaTree(page);
649
691
  refMap = result.refMap;
692
+ refDoc = docBefore;
650
693
  const raw = formatTree(result.tree);
651
694
  const { currentIndex, entries } = await page.session.send('Page.getNavigationHistory');
652
695
  const pageUrl = entries[currentIndex]?.url || '';
@@ -656,6 +699,20 @@ export async function connect(opts = {}) {
656
699
  const tree = links ? annotateLinks(result.tree, pageUrl) : result.tree;
657
700
  if (pruneOpts === false) return `url: ${pageUrl}\n` + warn + (links ? formatTree(tree) : raw);
658
701
  const mode = pruneOpts?.mode || opts.pruneMode || 'act';
702
+ if (pruneOpts?.map || pruneOpts?.within != null) {
703
+ // A ref names a node of the previous snapshot: find it again by its backend node.
704
+ const selectors = pruneOpts.within != null ? parseWithin(pruneOpts.within) : undefined;
705
+ const refNodes = new Map();
706
+ for (const s of selectors || []) {
707
+ if (!s.ref) continue;
708
+ const old = prevRefMap.get(s.ref);
709
+ if (!old) throw new Error(`within: ref ${s.ref} is not in the last snapshot (refs renumber on every snapshot and reset on navigation) — take a fresh ref from snapshot({ map: true })`);
710
+ const now = [...result.refMap].find(([, e]) => e.session === old.session && e.backendNodeId === old.backendNodeId);
711
+ if (!now) throw new Error(`within: the element behind ref ${s.ref} is no longer on the page — take a fresh ref from snapshot({ map: true })`);
712
+ refNodes.set(s.ref, now[0]);
713
+ }
714
+ return zoomSnapshot(tree, { head: `url: ${pageUrl}\n` + warn, map: true, selectors, refNodes, mode, links });
715
+ }
659
716
  const out = mode === 'data' ? dataSnapshot(tree, { links }) : formatTree(pruneTree(tree, { mode, links }));
660
717
  const sized = stripLegend(out); // the legend is not content
661
718
  const stats = `url: ${pageUrl}\n${raw.length.toLocaleString()} chars → ${sized.length.toLocaleString()} chars (${Math.round((1 - sized.length / raw.length) * 100)}% pruned)`;
@@ -673,15 +730,13 @@ export async function connect(opts = {}) {
673
730
  },
674
731
 
675
732
  async click(ref) {
676
- const entry = refMap.get(ref);
677
- if (!entry) throw new Error(`No element found for ref "${ref}"`);
733
+ const entry = await refEntry(ref);
678
734
  await cdpClick(entry.session, entry.backendNodeId);
679
735
  },
680
736
 
681
- /** @param {string} ref @param {string} text @param {TypeOptions} [typeOpts] */
737
+ /** @param {string|number} ref @param {string} text @param {TypeOptions} [typeOpts] */
682
738
  async type(ref, text, typeOpts = {}) {
683
- const entry = refMap.get(ref);
684
- if (!entry) throw new Error(`No element found for ref "${ref}"`);
739
+ const entry = await refEntry(ref);
685
740
  await cdpType(entry.session, entry.backendNodeId, text, typeOpts);
686
741
  },
687
742
 
@@ -694,22 +749,18 @@ export async function connect(opts = {}) {
694
749
  },
695
750
 
696
751
  async hover(ref) {
697
- const entry = refMap.get(ref);
698
- if (!entry) throw new Error(`No element found for ref "${ref}"`);
752
+ const entry = await refEntry(ref);
699
753
  await cdpHover(entry.session, entry.backendNodeId);
700
754
  },
701
755
 
702
756
  async select(ref, value) {
703
- const entry = refMap.get(ref);
704
- if (!entry) throw new Error(`No element found for ref "${ref}"`);
757
+ const entry = await refEntry(ref);
705
758
  await cdpSelect(entry.session, entry.backendNodeId, value);
706
759
  },
707
760
 
708
761
  async drag(fromRef, toRef) {
709
- const from = refMap.get(fromRef);
710
- const to = refMap.get(toRef);
711
- if (!from) throw new Error(`No element found for ref "${fromRef}"`);
712
- if (!to) throw new Error(`No element found for ref "${toRef}"`);
762
+ const from = await refEntry(fromRef);
763
+ const to = await refEntry(toRef);
713
764
  // Drag across different frames isn't physically meaningful — bail
714
765
  // rather than mix sessions and produce nonsense coordinates.
715
766
  if (from.session !== to.session) {
@@ -719,8 +770,7 @@ export async function connect(opts = {}) {
719
770
  },
720
771
 
721
772
  async upload(ref, files) {
722
- const entry = refMap.get(ref);
723
- if (!entry) throw new Error(`No element found for ref "${ref}"`);
773
+ const entry = await refEntry(ref);
724
774
  // Upload sandbox: when uploadDir is set, every path must resolve
725
775
  // (symlinks included, via realpath) inside it. Stops a prompt-injected
726
776
  // agent from attaching ~/.ssh/id_rsa or other arbitrary local files.
@@ -1187,6 +1237,33 @@ export function _resetBlocklistWarning() {
1187
1237
  blocklistWarned = false;
1188
1238
  }
1189
1239
 
1240
+ /**
1241
+ * Go to a history entry and wait until the traversal has landed. A bfcache
1242
+ * restore or a same-document entry never fires Page.loadEventFired, so wait
1243
+ * for the main frame's Page.frameStoppedLoading instead: it follows the load
1244
+ * event on a normal load and fires on both of those paths. Subscribed before
1245
+ * the navigate call so it cannot be missed; times out at 30s like before.
1246
+ * @param {*} page
1247
+ * @param {string} entryId history entry id (from Page.getNavigationHistory)
1248
+ */
1249
+ async function traverse(page, entryId) {
1250
+ const { session } = page;
1251
+ const { frameTree } = await session.send('Page.getFrameTree');
1252
+ const mainId = frameTree.frame.id;
1253
+ let off = () => {};
1254
+ const landed = new Promise((resolve, reject) => {
1255
+ const timer = setTimeout(() => { off(); reject(new Error('timeout')); }, 30000);
1256
+ off = session.on('Page.frameStoppedLoading', (p) => {
1257
+ if (p.frameId === mainId) { clearTimeout(timer); off(); resolve(undefined); }
1258
+ });
1259
+ });
1260
+ landed.catch(() => {});
1261
+ try {
1262
+ await session.send('Page.navigateToHistoryEntry', { entryId });
1263
+ } catch (e) { off(); throw e; }
1264
+ try { await landed; } catch { await new Promise((r) => setTimeout(r, 500)); }
1265
+ }
1266
+
1190
1267
  /**
1191
1268
  * Navigate to a URL and wait for the page to load. Resolves to the outcome of
1192
1269
  * the main-document navigation (final URL after redirects, HTTP status);
@@ -1227,7 +1304,9 @@ async function navigate(page, url, timeout = 30000, lock = null) {
1227
1304
  // response carries the status), so report it like any other HTTP error.
1228
1305
  const httpError = nav.errorText === 'net::ERR_HTTP_RESPONSE_CODE_FAILURE';
1229
1306
  if (nav.errorText && !aborted && !httpError) throw navFailed(url, nav.errorText);
1230
- if (!aborted) await loaded;
1307
+ // A same-document navigation (fragment-only change) commits no new document: Page.navigate
1308
+ // returns no loaderId and no load event follows, so don't wait for one.
1309
+ if (!aborted && nav.loaderId) await loaded;
1231
1310
  // Brief settle time for dynamic content
1232
1311
  await new Promise((r) => setTimeout(r, 500));
1233
1312
  // loaderId is shared by every redirect hop of one navigation.
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.whole=false] - `tree` is a zoom box (snapshot `within`): it is the whole page, so the landmark step (1) is skipped
65
66
  * @param {boolean} [options.links=false] - Links carry `urls` (see links.js): nodes that drop their children keep the URLs of links beneath them
66
67
  * @returns {object|null} Pruned tree
67
68
  */
@@ -77,8 +78,8 @@ export function prune(tree, options = {}) {
77
78
  // Wrap as array for pipeline
78
79
  let nodes = tree ? [tree] : [];
79
80
 
80
- // Step 1: Extract landmark regions
81
- nodes = extractRegions(nodes, allowedRegions);
81
+ // Step 1: Extract landmark regions (a zoom box is the whole page: keep it)
82
+ if (!options.whole) nodes = extractRegions(nodes, allowedRegions);
82
83
 
83
84
  // Step 2: Prune nodes
84
85
  const ctx = { mode, parentRole: null, keywords, links: !!options.links };