crawlforge-mcp-server 6.4.0 → 6.6.0

package/src/core/browser/SessionStore.js

@@ -0,0 +1,331 @@
+/**
+ * BrowserSessionStore — the registry behind a browser session that outlives a
+ * single tool call.
+ *
+ * A session is a page the caller gets to keep: log in once, then click, type
+ * and snapshot across several calls without paying for the login every time.
+ * This file holds those pages, decides when one has gone stale, and hands it
+ * back. How a page was made — stealth or not, which engine, which context — is
+ * the caller's business, never ours.
+ *
+ * NO SECOND POOL. Sessions hold pages whose browser contexts are already
+ * registered in StealthBrowserManager's BrowserContextPool by the code that
+ * opened them. Constructing a pool here would double-count every context
+ * against a cap that exists to protect a 2 GB box, so do not "fix" the missing
+ * pool. The plan's "context id" field is carried implicitly by `releasePage`,
+ * the closure the creator supplies to give the page back: the store knows how
+ * to return a page, not how it was built, and so imports neither
+ * BrowserProcessor nor StealthBrowserManager.
+ *
+ * REFS NEED NO FIELD either. Element refs (`@e1`) live in a page-scoped WeakMap
+ * inside src/core/browser/snapshot.js, so a session that keeps its page keeps
+ * its refs for free — and loses them exactly when it should, on navigation or
+ * when the page closes. A second copy here could only disagree with that one.
+ *
+ * OWNERSHIP IS A TENANT BOUNDARY, not a convenience. Ids are random and every
+ * lookup is scoped to the caller; a wrong owner is answered with the same
+ * "session not found" an unknown id gets, so ids cannot be probed from the
+ * outside. See SessionNotFoundError.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+/**
+ * Thrown for an unknown id, a wrong owner and an expired session alike.
+ *
+ * It takes no message on purpose: a call site cannot vary what it says, so the
+ * three cases cannot drift apart over time and start telling a caller which one
+ * they hit. That sameness is what makes session ids non-enumerable, and it is
+ * also why the message never echoes the id back.
+ */
+export class SessionNotFoundError extends Error {
+  constructor() {
+    super(
+      'Session not found. It may have expired, been closed, or never existed — ' +
+      'open a new session and try again.'
+    );
+    this.name = 'SessionNotFoundError';
+    this.code = 'SESSION_NOT_FOUND';
+  }
+}
+
+/** Thrown when a new session would breach the per-owner or process-wide cap. */
+export class SessionLimitError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'SessionLimitError';
+    this.code = 'SESSION_LIMIT';
+  }
+}
+
+// Two clocks, and their bounds. The numbers match Firecrawl's session TTLs so
+// that our documentation reads familiar to anyone arriving from theirs.
+export const TTL_DEFAULT_MS = 600_000;            // 10 minutes from creation
+export const TTL_MIN_MS = 30_000;
+export const TTL_MAX_MS = 3_600_000;              // 1 hour
+export const ACTIVITY_TTL_DEFAULT_MS = 300_000;   // 5 minutes since last use
+export const ACTIVITY_TTL_MIN_MS = 10_000;
+export const ACTIVITY_TTL_MAX_MS = 3_600_000;
+
+export const DEFAULT_MAX_SESSIONS_PER_OWNER = 3;
+
+// Every live session pins one browser context for as long as it lives, and
+// one-shot scrapes draw contexts from the same pool — which caps at
+// MAX_BROWSER_CONTEXTS. Sessions therefore get at most half of it, so a burst
+// of them can never leave an ordinary scrape waiting on a slot that will not
+// free for another ten minutes.
+//
+// This is the SECOND reader of that variable — BrowserContextPool.js reads it
+// with the same '10' fallback — and "half the pool" holds only while the two
+// defaults agree. Change one and change this one with it. Deliberately not an
+// import of the pool's constant: nothing in this file may reach for the pool
+// (see the header), and a grep for MAX_BROWSER_CONTEXTS finds both sites.
+const CONTEXT_CAP = parseInt(process.env.MAX_BROWSER_CONTEXTS || '10', 10) || 10;
+export const DEFAULT_MAX_SESSIONS_TOTAL = Math.max(1, Math.floor(CONTEXT_CAP / 2));
+
+const DEFAULT_SWEEP_INTERVAL_MS = 30_000;
+
+/** Caller-supplied ttls are clamped, not rejected — see create(). */
+function clamp(value, min, max, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) ? Math.min(Math.max(n, min), max) : fallback;
+}
+
+export class BrowserSessionStore {
+  /**
+   * @param {Object} [opts]
+   * @param {number} [opts.maxPerOwner] — concurrent sessions one API key may hold
+   * @param {number} [opts.maxTotal] — concurrent sessions the process may hold
+   * @param {number} [opts.sweepIntervalMs]
+   */
+  constructor(opts = {}) {
+    this._maxPerOwner = opts.maxPerOwner ?? DEFAULT_MAX_SESSIONS_PER_OWNER;
+    this._maxTotal = opts.maxTotal ?? DEFAULT_MAX_SESSIONS_TOTAL;
+
+    // The only index. A store holds single digits of sessions, so the
+    // per-owner questions (cap, list, stats) are answered by scanning this map
+    // rather than by a second one that could fall out of step with it.
+    /** @type {Map<string, { id: string, ownerId: string, page: any, releasePage: Function, url: string|null, stealth: boolean, createdAt: number, lastUsedAt: number, ttlMs: number, activityTtlMs: number }>} */
+    this._sessions = new Map();
+
+    this._sweepTimer = setInterval(() => {
+      // An unhandled rejection inside a timer callback takes the server down
+      // with it. _release never rejects, and this is what keeps that true even
+      // if someone later changes it.
+      this.sweep().catch(() => {});
+    }, opts.sweepIntervalMs ?? DEFAULT_SWEEP_INTERVAL_MS);
+    this._sweepTimer.unref?.(); // never hold the process open
+  }
+
+  /**
+   * Register a live page as a session.
+   *
+   * @param {Object} args
+   * @param {string} args.ownerId — the caller's API-key identity; the tenant boundary
+   * @param {any} args.page — the Playwright page the session keeps
+   * @param {() => Promise<void>} args.releasePage — hands the page, and its context, back
+   * @param {string} [args.url]
+   * @param {boolean} [args.stealth=false]
+   * @param {number} [args.ttlMs] — clamped into [TTL_MIN_MS, TTL_MAX_MS]
+   * @param {number} [args.activityTtlMs] — clamped into [ACTIVITY_TTL_MIN_MS, ACTIVITY_TTL_MAX_MS]
+   * @param {number} [args.maxPerOwner] — a tighter cap for THIS owner, in place
+   *   of the store's. Some callers are not equal: a hosted REST customer shares
+   *   one box with every other one, where a stdio install has the box to itself.
+   *   Only the creator may say so, because only the creator knows who is asking.
+   * @throws {SessionLimitError} when the owner is at maxPerOwner, or the store at maxTotal
+   */
+  create({ ownerId, page, releasePage, url = null, stealth = false, ttlMs, activityTtlMs, maxPerOwner }) {
+    // Both of these are load-bearing rather than defensive: without an ownerId
+    // two tenants' sessions would share one anonymous bucket, and without a
+    // releasePage the page's context is pinned with no way to give it back.
+    if (!ownerId) {
+      throw new TypeError('BrowserSessionStore.create requires an ownerId');
+    }
+    if (typeof releasePage !== 'function') {
+      throw new TypeError('BrowserSessionStore.create requires a releasePage callback');
+    }
+
+    // Expired-but-unswept sessions must not count against the caps: a caller
+    // whose three sessions all timed out a second ago is not over quota.
+    this._purgeExpired();
+
+    // A refusal, never a queue. BrowserContextPool can make a caller wait for a
+    // slot because a context frees in milliseconds; a session slot frees on its
+    // TTL, minutes away, so waiting would simply hang the call.
+    const ownerCap = maxPerOwner ?? this._maxPerOwner;
+    if (this._countFor(ownerId) >= ownerCap) {
+      throw new SessionLimitError(
+        `You already have ${ownerCap} open browser session${ownerCap === 1 ? '' : 's'}, the maximum per API key. ` +
+        `Close one before opening another — sessions also close themselves when their TTL expires.`
+      );
+    }
+    if (this._sessions.size >= this._maxTotal) {
+      throw new SessionLimitError(
+        `The server is holding its maximum of ${this._maxTotal} browser sessions. ` +
+        `Try again shortly, or use a one-shot scrape instead of a session.`
+      );
+    }
+
+    const now = Date.now();
+    const session = {
+      id: randomUUID(),
+      ownerId,
+      page,
+      releasePage,
+      url,
+      stealth,
+      createdAt: now,
+      lastUsedAt: now,
+      // Clamped rather than rejected: the tool validates the caller-facing
+      // seconds with zod, so anything arriving out of range here is a bug on
+      // our side of the boundary, not a caller error to report.
+      ttlMs: clamp(ttlMs, TTL_MIN_MS, TTL_MAX_MS, TTL_DEFAULT_MS),
+      activityTtlMs: clamp(activityTtlMs, ACTIVITY_TTL_MIN_MS, ACTIVITY_TTL_MAX_MS, ACTIVITY_TTL_DEFAULT_MS)
+    };
+
+    this._sessions.set(session.id, session);
+    return session;
+  }
+
+  /**
+   * Look a session up on behalf of its owner. It records nothing — touch() does
+   * that — so a read never extends a session's life by accident.
+   *
+   * Unknown id, wrong owner and expired session all raise the identical
+   * SessionNotFoundError.
+   *
+   * @throws {SessionNotFoundError}
+   */
+  get(sessionId, ownerId) {
+    const session = this._sessions.get(sessionId);
+    if (!session || session.ownerId !== ownerId) throw new SessionNotFoundError();
+
+    if (this._isExpired(session, Date.now())) {
+      // Expiry is not the sweep's alone to notice. A session that timed out
+      // between sweeps is gone the moment it is asked for, and its page goes
+      // back now rather than up to half a minute later. get() is synchronous,
+      // so the release runs unawaited; _release never rejects.
+      this._sessions.delete(sessionId);
+      this._release(session);
+      throw new SessionNotFoundError();
+    }
+
+    return session;
+  }
+
+  /** Record activity, and the page's new url when it moved. Restarts the idle clock. */
+  touch(session, url) {
+    session.lastUsedAt = Date.now();
+    if (url) session.url = url;
+  }
+
+  /**
+   * Close a session on behalf of its owner and give its page back.
+   * @throws {SessionNotFoundError}
+   */
+  async close(sessionId, ownerId) {
+    const session = this.get(sessionId, ownerId);
+    // Out of the map BEFORE the first await. That is what makes releasePage run
+    // exactly once when two closes race, and what stops a throwing release from
+    // leaving a dead session behind for someone to find.
+    this._sessions.delete(sessionId);
+    await this._release(session);
+  }
+
+  /** One owner's live sessions, in the shape the tool reports. Pages stay in here. */
+  list(ownerId) {
+    this._purgeExpired();
+    const sessions = [];
+    for (const session of this._sessions.values()) {
+      if (session.ownerId !== ownerId) continue;
+      sessions.push({
+        id: session.id,
+        url: session.url,
+        stealth: session.stealth,
+        createdAt: session.createdAt,
+        lastUsedAt: session.lastUsedAt,
+        expiresAt: session.createdAt + session.ttlMs,
+        idleExpiresAt: session.lastUsedAt + session.activityTtlMs
+      });
+    }
+    return sessions;
+  }
+
+  /**
+   * Close everything past either clock. This is the backstop that keeps an
+   * abandoned session from pinning a browser context for the life of the
+   * process — on the 2 GB box that is an outage, not a leak.
+   *
+   * @returns {Promise<number>} sessions closed
+   */
+  async sweep() {
+    const expired = this._takeExpired(Date.now());
+    await Promise.all(expired.map((session) => this._release(session)));
+    return expired.length;
+  }
+
+  /** Close every session and stop the sweep. Safe to call twice. */
+  async destroy() {
+    clearInterval(this._sweepTimer);
+    const sessions = Array.from(this._sessions.values());
+    this._sessions.clear();
+    await Promise.all(sessions.map((session) => this._release(session)));
+  }
+
+  getStats() {
+    const byOwner = {};
+    for (const session of this._sessions.values()) {
+      byOwner[session.ownerId] = (byOwner[session.ownerId] || 0) + 1;
+    }
+    return { total: this._sessions.size, byOwner };
+  }
+
+  // ── internals ───────────────────────────────────────────────────────────────
+
+  _countFor(ownerId) {
+    let count = 0;
+    for (const session of this._sessions.values()) {
+      if (session.ownerId === ownerId) count++;
+    }
+    return count;
+  }
+
+  /** Past its absolute TTL, or idle past its activity TTL — whichever fires first. */
+  _isExpired(session, now) {
+    return now >= session.createdAt + session.ttlMs
+      || now >= session.lastUsedAt + session.activityTtlMs;
+  }
+
+  /** Remove every expired session from the map and return them, still unreleased. */
+  _takeExpired(now) {
+    const expired = [];
+    for (const [id, session] of this._sessions.entries()) {
+      if (this._isExpired(session, now)) {
+        this._sessions.delete(id);
+        expired.push(session);
+      }
+    }
+    return expired;
+  }
+
+  /** _takeExpired for the synchronous paths, which have no way to await the releases. */
+  _purgeExpired() {
+    for (const session of this._takeExpired(Date.now())) this._release(session);
+  }
+
+  /**
+   * Give one page back. Never rejects: by the time this runs the session is
+   * already out of the map, so a failed close is the pool's problem rather than
+   * anything the caller can act on — the same call BrowserContextPool.dispose
+   * makes about a context that will not close.
+   */
+  async _release(session) {
+    try {
+      await session.releasePage();
+    } catch {
+      // ignore release errors
+    }
+  }
+}
+
+export default BrowserSessionStore;

package/src/core/browser/snapshot.js

@@ -0,0 +1,346 @@
+/**
+ * Snapshot — the accessibility-style page tree that hands an agent stable
+ * element refs (`@e1`, `@e2`, …) to act on instead of guessed CSS selectors.
+ *
+ * Why ours and not Playwright's: 1.62's `locator.ariaSnapshot()` emits YAML
+ * with no element refs at all, and `page._snapshotForAI()` is private API we
+ * will not depend on. The walk below is injected by us and returns the tree
+ * and the refs from one pass.
+ *
+ * A REF LIVES IN TWO PLACES, and the halves do different jobs:
+ *
+ *   1. In the page — the walk stamps `data-cf-ref="e1"` onto every element it
+ *      refs, so a ref resolves to an ordinary CSS selector,
+ *      `[data-cf-ref="e1"]`. That is what makes refs work with every existing
+ *      action path for free, including the stealth human-behaviour code that
+ *      takes a raw selector string.
+ *   2. In Node — a WeakMap<Page, state> cleared on every main-frame
+ *      navigation. This is the half that DETECTS staleness. Without it a ref
+ *      from a previous page would merely fail to match, and the caller would
+ *      be told "selector not found" instead of "take a new snapshot".
+ *
+ * So a stale ref fails loudly, with the reason and the fix (StaleRefError),
+ * and never silently hits the wrong element.
+ *
+ * Not to be confused with src/core/SnapshotManager.js, which is change-
+ * tracking history.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+export const REF_ATTRIBUTE = 'data-cf-ref';
+export const DEFAULT_MAX_NODES = 200;
+export const MAX_NODES_LIMIT = 1000;
+
+// Walks of one snapshot call, including the retry when the page navigates
+// mid-walk. Two: one retry is enough for a page that settles, and a page
+// navigating repeatedly is not one a snapshot can describe.
+const MAX_WALK_ATTEMPTS = 2;
+
+// Indentation follows the nesting of EMITTED nodes, and stops deepening past
+// this many levels so a deep DOM cannot produce runaway leading whitespace.
+const MAX_INDENT = 10;
+const MAX_NAME_LENGTH = 120;
+
+const REF_PATTERN = /^@e[1-9]\d*$/;
+
+/** Thrown when a ref cannot be resolved against the page's current snapshot. */
+export class StaleRefError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'StaleRefError';
+  }
+}
+
+// Page -> { snapshotId, refs, invalidated, tracking }. WeakMap so a closed
+// page's refs go with it.
+const pageState = new WeakMap();
+
+/** True for an element ref (`@e1`), false for anything else, including non-strings. */
+export function isRef(selector) {
+  return typeof selector === 'string' && REF_PATTERN.test(selector);
+}
+
+/**
+ * The injected walk. Fixed source, written by us — it is not caller-supplied
+ * JavaScript, so it has nothing to do with the ALLOW_JAVASCRIPT_EXECUTION flag
+ * that gates the `executeJavaScript` action. Do not put it behind that flag.
+ */
+function snapshotScript({ refAttribute, interactiveOnly, maxNodes, maxIndent, maxNameLength }) {
+  const SKIP_TAGS = new Set(['script', 'style', 'noscript', 'template', 'head']);
+  const INTERACTIVE_ROLES = new Set([
+    'button', 'link', 'checkbox', 'radio', 'textbox', 'combobox', 'menuitem',
+    'menuitemcheckbox', 'menuitemradio', 'tab', 'switch', 'option', 'searchbox',
+    'slider', 'spinbutton'
+  ]);
+  const STRUCTURAL_ROLES = new Set([
+    'heading', 'banner', 'navigation', 'contentinfo', 'complementary', 'main',
+    'form', 'region', 'search'
+  ]);
+  const LANDMARK_TAGS = {
+    main: 'main', nav: 'navigation', header: 'banner', footer: 'contentinfo',
+    aside: 'complementary', form: 'form'
+  };
+  const INPUT_ROLES = {
+    text: 'textbox', search: 'textbox', email: 'textbox', tel: 'textbox',
+    url: 'textbox', password: 'textbox', checkbox: 'checkbox', radio: 'radio',
+    submit: 'button', button: 'button', reset: 'button'
+  };
+
+  // Double quotes delimit the name in the tree, so a name may not contain one.
+  const clean = (value) => (value || '').replace(/\s+/g, ' ').trim().replace(/"/g, "'");
+  const truncate = (value) =>
+    (value.length > maxNameLength ? `${value.slice(0, maxNameLength - 1)}…` : value);
+
+  function roleOf(el, tag) {
+    const explicit = (el.getAttribute('role') || '').trim().toLowerCase();
+    if (explicit) return explicit.split(/\s+/)[0];
+    if (tag === 'input') return INPUT_ROLES[(el.getAttribute('type') || 'text').toLowerCase()] || tag;
+    if (tag === 'a') return el.hasAttribute('href') ? 'link' : tag;
+    if (tag === 'button' || tag === 'summary') return 'button';
+    if (tag === 'select') return 'combobox';
+    if (tag === 'textarea') return 'textbox';
+    if (/^h[1-6]$/.test(tag)) return 'heading';
+    return LANDMARK_TAGS[tag] || tag;
+  }
+
+  function nameOf(el, tag, allowTextContent) {
+    const ariaLabel = clean(el.getAttribute('aria-label'));
+    if (ariaLabel) return ariaLabel;
+
+    const labelledBy = (el.getAttribute('aria-labelledby') || '').trim();
+    if (labelledBy) {
+      const referenced = clean(labelledBy.split(/\s+/)
+        .map((id) => (document.getElementById(id) || {}).textContent || '')
+        .join(' '));
+      if (referenced) return referenced;
+    }
+
+    // el.labels covers both `label[for=id]` and an ancestor <label>; closest()
+    // is the fallback for elements that have no .labels (a contenteditable).
+    const labels = el.labels;
+    const labelText = clean(labels && labels.length
+      ? labels[0].textContent
+      : (el.closest('label') || {}).textContent);
+    if (labelText) return labelText;
+
+    for (const attribute of ['placeholder', 'title', 'alt']) {
+      const value = clean(el.getAttribute(attribute));
+      if (value) return value;
+    }
+
+    // A push button's label is its value; a text field's value is user data,
+    // not a name, which is why this is narrowed to the button types.
+    if (tag === 'input' && /^(button|submit|reset)$/.test((el.getAttribute('type') || '').toLowerCase())) {
+      const value = clean(el.value);
+      if (value) return value;
+    }
+
+    // A landmark is named by its label, never by everything inside it —
+    // otherwise <main> would be captioned with the whole page.
+    return allowTextContent ? clean(el.textContent) : '';
+  }
+
+  function isInteractive(el, tag, role) {
+    if (INTERACTIVE_ROLES.has(role)) return true;
+    if (tag === 'a') return el.hasAttribute('href');
+    if (tag === 'input') return (el.getAttribute('type') || '').toLowerCase() !== 'hidden';
+    if (tag === 'select' || tag === 'textarea' || tag === 'button' || tag === 'summary') return true;
+    const editable = el.getAttribute('contenteditable');
+    if (editable !== null && editable !== 'false') return true;
+    const tabindex = el.getAttribute('tabindex');
+    if (tabindex !== null && tabindex.trim() !== '-1') return true;
+    return el.hasAttribute('onclick');
+  }
+
+  function isHidden(el, tag) {
+    if (SKIP_TAGS.has(tag)) return true;
+    if (el.hasAttribute('hidden')) return true;
+    if (el.getAttribute('aria-hidden') === 'true') return true;
+    const style = getComputedStyle(el);
+    return style.display === 'none' || style.visibility === 'hidden';
+  }
+
+  const hasSize = (el) => {
+    const rect = el.getBoundingClientRect();
+    return rect.width > 0 && rect.height > 0;
+  };
+
+  const lines = [];
+  const refs = [];
+  let truncated = false;
+
+  function walk(el, depth) {
+    if (truncated) return;
+    const tag = el.tagName.toLowerCase();
+    if (isHidden(el, tag)) return; // the subtree is hidden with it
+
+    const role = roleOf(el, tag);
+    const interactive = isInteractive(el, tag, role);
+    const structural = !interactive && !interactiveOnly &&
+      (/^h[1-6]$/.test(tag) || Boolean(LANDMARK_TAGS[tag]) || STRUCTURAL_ROLES.has(role));
+    let childDepth = depth;
+
+    // A zero-size element is not emitted, but its children still are: a
+    // collapsed wrapper is common, an unreachable subtree is not.
+    if ((interactive || structural) && hasSize(el)) {
+      if (lines.length >= maxNodes) {
+        truncated = true;
+        return;
+      }
+      const name = truncate(nameOf(el, tag, interactive || role === 'heading'));
+      let ref = '';
+      // Only interactive nodes get a ref — a structural line is context, not a target.
+      if (interactive) {
+        const id = `e${refs.length + 1}`;
+        el.setAttribute(refAttribute, id);
+        refs.push({ id, role, name, tag });
+        ref = `@${id} `;
+      }
+      lines.push(`${'  '.repeat(Math.min(depth, maxIndent))}${ref}[${role}]${name ? ` "${name}"` : ''}`);
+      childDepth = depth + 1;
+    }
+
+    for (const child of el.children) walk(child, childDepth);
+  }
+
+  // Drop refs from an earlier walk so a re-snapshot of the same page numbers
+  // cleanly instead of leaving elements answering to a retired id.
+  for (const stale of document.querySelectorAll(`[${refAttribute}]`)) {
+    stale.removeAttribute(refAttribute);
+  }
+  walk(document.body || document.documentElement, 1);
+
+  return { title: clean(document.title), lines, refs, truncated };
+}
+
+function stateFor(page) {
+  let state = pageState.get(page);
+  if (!state) {
+    state = { snapshotId: null, refs: null, invalidated: false, tracking: false, generation: 0 };
+    pageState.set(page, state);
+  }
+  return state;
+}
+
+/**
+ * Walk the page and return its tree plus the refs it assigned.
+ *
+ * @param {import('playwright').Page} page
+ * @param {object} [options]
+ * @param {boolean} [options.interactiveOnly=true] — false also emits headings and landmarks, unreffed
+ * @param {number} [options.maxNodes=200] — cap on emitted nodes, clamped to [1, MAX_NODES_LIMIT]
+ */
+export async function captureSnapshot(page, options = {}) {
+  const interactiveOnly = options.interactiveOnly !== false;
+  const requested = Number(options.maxNodes);
+  const maxNodes = Number.isFinite(requested)
+    ? Math.min(Math.max(Math.floor(requested), 1), MAX_NODES_LIMIT)
+    : DEFAULT_MAX_NODES;
+
+  // Idempotent, and the guarantee that a later navigation invalidates these
+  // refs rather than leaving them to fail as a missing selector.
+  attachRefTracking(page);
+
+  const state = stateFor(page);
+  let title, lines, refs, truncated;
+
+  // A navigation that commits WHILE the walk is running would otherwise leave us
+  // holding refs for a document that has gone — the attributes were stamped on
+  // the old page, so `@e1` would match nothing and surface as a locator timeout
+  // instead of the named error D2 requires. `generation` moves on every
+  // main-frame navigation, so a change across the evaluate means exactly that.
+  // Walk the new document instead; if it navigates again, give up and leave the
+  // refs invalidated rather than publishing a tree for a page nobody is on.
+  for (let attempt = 0; ; attempt++) {
+    const generation = state.generation;
+    ({ title, lines, refs, truncated } = await page.evaluate(snapshotScript, {
+      refAttribute: REF_ATTRIBUTE,
+      interactiveOnly,
+      maxNodes,
+      maxIndent: MAX_INDENT,
+      maxNameLength: MAX_NAME_LENGTH
+    }));
+    if (state.generation === generation) break;
+    if (attempt >= MAX_WALK_ATTEMPTS - 1) {
+      clearRefs(page);
+      throw new StaleRefError(
+        'The page navigated while the snapshot was being taken — take a new snapshot.'
+      );
+    }
+  }
+
+  const snapshotId = randomUUID().slice(0, 8);
+  state.snapshotId = snapshotId;
+  state.refs = new Map(refs.map(({ id, role, name, tag }) => [id, { role, name, tag }]));
+  state.invalidated = false;
+
+  return {
+    snapshotId,
+    url: page.url(),
+    title,
+    tree: [`[document]${title ? ` "${title}"` : ''}`, ...lines].join('\n'),
+    refCount: refs.length,
+    nodeCount: lines.length,
+    truncated,
+    interactiveOnly
+  };
+}
+
+/**
+ * Turn `@e1` into the CSS selector every action path already understands.
+ * Throws StaleRefError when the ref does not belong to the page's current
+ * snapshot — it never guesses.
+ */
+export function resolveRef(page, selector) {
+  if (!isRef(selector)) {
+    // A programming error, not a stale ref: callers gate on isRef().
+    throw new Error(`resolveRef expects an element ref like "@e1", got ${JSON.stringify(selector)}`);
+  }
+
+  const state = pageState.get(page);
+  if (!state || (!state.refs && !state.invalidated)) {
+    throw new StaleRefError(
+      `Unknown element ref ${selector}: no snapshot has been taken on this page — add a { "type": "snapshot" } action before acting on refs.`
+    );
+  }
+  if (!state.refs) {
+    throw new StaleRefError(
+      `Stale element ref ${selector}: the page navigated since the last snapshot — take a new snapshot before acting on refs.`
+    );
+  }
+
+  const id = selector.slice(1);
+  if (!state.refs.has(id)) {
+    const count = state.refs.size;
+    throw new StaleRefError(count === 0
+      ? `Unknown element ref ${selector}: the current snapshot has no refs — take a new snapshot.`
+      : `Unknown element ref ${selector}: the current snapshot has ${count} refs (@e1-@e${count}) — take a new snapshot.`);
+  }
+
+  return `[${REF_ATTRIBUTE}="${id}"]`;
+}
+
+/** Register the navigation listener that invalidates this page's refs. Idempotent. */
+export function attachRefTracking(page) {
+  const state = stateFor(page);
+  if (state.tracking) return;
+  state.tracking = true;
+  page.on('framenavigated', (frame) => {
+    if (frame === page.mainFrame()) clearRefs(page);
+  });
+}
+
+/** Drop the page's refs. A ref resolved afterwards reports the navigation, not a miss. */
+export function clearRefs(page) {
+  const state = pageState.get(page);
+  if (!state) return;
+  // `invalidated` is only meaningful once a snapshot existed — it is what
+  // separates "the page navigated" from "no snapshot has been taken".
+  if (state.refs) state.invalidated = true;
+  state.refs = null;
+  state.snapshotId = null;
+  // Bumped on every clear so a walk in flight can tell the document changed
+  // under it — see captureSnapshot.
+  state.generation++;
+}