craftdriver 1.6.0 → 1.8.0

package/dist/cli/snapshot.js

@@ -1,23 +1,96 @@
+import { PAGE_SEMANTICS_JS } from './pageSemantics.js';
 const MAX_NODES = 80;
 const MAX_NAME = 80;
+/**
+ * Upper bound on refs issued per document. Reaching it resets the registry
+ * under a fresh `documentId`, which invalidates every outstanding ref
+ * rather than letting numbers wrap onto live elements.
+ */
+const MAX_REFS = 2000;
 /**
  * Build a fresh snapshot of the active page. Errors swallowed so a
  * partial post-action payload never breaks the protocol.
  */
-export async function takeSnapshot(browser) {
+export async function takeSnapshot(browser, minRef = 0) {
     try {
         const page = await browser.activePage();
         const [url, title] = await Promise.all([
             page.url().catch(() => ''),
             page.title().catch(() => ''),
         ]);
-        const lines = await page.evaluate(JS_SNAPSHOT);
-        return { url, title, lines: Array.isArray(lines) ? lines : [] };
+        const raw = await page.evaluate(jsSnapshot(minRef));
+        if (!raw || typeof raw !== 'object')
+            return null;
+        const shaped = raw;
+        return {
+            url,
+            title,
+            lines: Array.isArray(shaped.lines) ? shaped.lines : [],
+            documentId: typeof shaped.documentId === 'string' ? shaped.documentId : '',
+            revision: 0,
+            refs: Array.isArray(shaped.refs) ? shaped.refs : [],
+            nextRef: typeof shaped.nextRef === 'number' ? shaped.nextRef : minRef + 1,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Return the text of an open JavaScript dialog, or null if none is open.
+ *
+ * Cheap (~2ms) and, unlike almost every other command, safe to call while
+ * a modal dialog is blocking the page. That matters: a modal blocks script
+ * execution, so an unguarded post-action snapshot sits there until the
+ * WebDriver script timeout — a measured 60 seconds — before failing.
+ */
+export async function peekDialog(browser) {
+    try {
+        return await browser.getDialogMessage();
     }
     catch {
+        // The driver reports "no such alert" by throwing; that is the common case.
         return null;
     }
 }
+/**
+ * Ask the page whether `ref` still identifies exactly one live element.
+ *
+ * `expectedDocumentId` is the document the ref was issued against; a
+ * mismatch means the page navigated and every outstanding ref is stale.
+ */
+export async function probeRef(browser, ref, expectedDocumentId) {
+    if (!/^e\d+$/.test(ref))
+        return { status: 'unknown-ref', documentId: null };
+    try {
+        const page = await browser.activePage();
+        const js = jsProbeRef(ref, expectedDocumentId);
+        const raw = await page.evaluate(js);
+        if (!raw || typeof raw !== 'object')
+            return { status: 'no-registry', documentId: null };
+        const shaped = raw;
+        return {
+            status: (typeof shaped.status === 'string' ? shaped.status : 'no-registry'),
+            documentId: typeof shaped.documentId === 'string' ? shaped.documentId : null,
+            ...(typeof shaped.count === 'number' ? { count: shaped.count } : {}),
+        };
+    }
+    catch {
+        return { status: 'no-registry', documentId: null };
+    }
+}
+/** Human-readable reason attached to a STALE_REF failure. */
+export function describeRefStatus(status) {
+    switch (status) {
+        case 'no-snapshot': return 'no snapshot has been taken in this session yet';
+        case 'no-registry': return 'the page has no ref registry (it navigated or was replaced)';
+        case 'document-changed': return 'the page navigated or reloaded after the ref was issued';
+        case 'unknown-ref': return 'the ref was never issued for the current document';
+        case 'detached': return 'the element was removed from the document';
+        case 'ambiguous': return 'the ref no longer identifies exactly one element';
+        default: return 'the ref is no longer valid';
+    }
+}
 /**
  * Render a snapshot as a compact, agent-friendly string. Either the
  * full snapshot (first call in a session) or a `+/-` diff vs. the
@@ -26,10 +99,8 @@ export async function takeSnapshot(browser) {
  * Diff format intentionally mirrors `diff -u` lines so agents
  * already familiar with unified diffs read it without instruction.
  *
- * Ref numbers (`e1`, `e2`, …) re-allocate on every snapshot so they
- * can't be used to drive the diff directly — we strip them before
- * the set-difference and re-attach them when rendering, so the diff
- * stays semantically stable across renumberings.
+ * Refs are stripped before the set-difference and re-attached when
+ * rendering, so a diff reports semantic change rather than renumbering.
  */
 export function renderDelta(prev, next) {
     if (!next)
@@ -41,15 +112,41 @@ export function renderDelta(prev, next) {
             return `${header}\n(no interactive elements detected)`;
         return `${header}\n${next.lines.join('\n')}`;
     }
-    if (prev.url !== next.url) {
-        // Page changed — full snapshot.
+    // A new document means the old lines describe a page that no longer
+    // exists; a diff against them would be noise. Same-URL reloads count.
+    if (prev.documentId !== next.documentId || prev.url !== next.url) {
         return `${header}\n${next.lines.join('\n')}`;
     }
     const strip = (l) => l.replace(/^e\d+:\s*/, '');
-    const prevBodies = new Set(prev.lines.map(strip));
-    const nextBodies = new Set(next.lines.map(strip));
-    const removed = prev.lines.filter((l) => !nextBodies.has(strip(l))).map((l) => `- ${l}`);
-    const added = next.lines.filter((l) => !prevBodies.has(strip(l))).map((l) => `+ ${l}`);
+    // Count occurrences rather than testing membership: a page with three
+    // identical "Remove" buttons must still report a change when one of them
+    // goes, and a set-difference silently calls that "no changes".
+    const tally = (lines) => {
+        const counts = new Map();
+        for (const line of lines) {
+            const body = strip(line);
+            counts.set(body, (counts.get(body) ?? 0) + 1);
+        }
+        return counts;
+    };
+    const prevCounts = tally(prev.lines);
+    const nextCounts = tally(next.lines);
+    const take = (lines, budget) => {
+        const out = [];
+        const seen = new Map();
+        for (const line of lines) {
+            const body = strip(line);
+            const used = seen.get(body) ?? 0;
+            // Report the surplus copies only — the first N matching lines are
+            // accounted for by the other side.
+            if (used >= (budget.get(body) ?? 0))
+                out.push(line);
+            seen.set(body, used + 1);
+        }
+        return out;
+    };
+    const removed = take(prev.lines, nextCounts).map((l) => `- ${l}`);
+    const added = take(next.lines, prevCounts).map((l) => `+ ${l}`);
     if (removed.length === 0 && added.length === 0) {
         return `${header}\n(no a11y changes)`;
     }
@@ -69,20 +166,139 @@ export function renderFull(next) {
     }
     return `${header}\n${next.lines.join('\n')}`;
 }
+/**
+ * Owns the one snapshot baseline and ref-issuing document for a session.
+ *
+ * Both explicit `snapshot` and the automatic post-action snapshot record
+ * through here, so an explicit snapshot the agent has already been shown
+ * is never re-reported as a change caused by the next action.
+ */
+export class SnapshotTracker {
+    baseline = null;
+    revision = 0;
+    highWater = 0;
+    /** The document outstanding refs were issued against, if any. */
+    get documentId() {
+        return this.baseline ? this.baseline.documentId : null;
+    }
+    get current() {
+        return this.baseline;
+    }
+    /**
+     * Highest ref number issued anywhere in this session.
+     *
+     * Seeding each new document above this is what stops a reload from
+     * reissuing `e2` to a different element: a ref the agent still holds
+     * would otherwise silently resolve against the new page.
+     */
+    get minRef() {
+        return this.highWater;
+    }
+    /** Stamp a session-monotonic revision and make this the new baseline. */
+    record(snap) {
+        if (!snap)
+            return null;
+        const stamped = { ...snap, revision: ++this.revision };
+        this.baseline = stamped;
+        this.highWater = Math.max(this.highWater, stamped.nextRef - 1);
+        return stamped;
+    }
+    /** Diff against the baseline and advance it in one step. */
+    advance(snap) {
+        if (!snap)
+            return '';
+        const delta = renderDelta(this.baseline, { ...snap, revision: this.revision + 1 });
+        this.record(snap);
+        return delta;
+    }
+    reset() {
+        this.baseline = null;
+    }
+}
+/**
+ * Ref-validation probe. `ref` is `^e\d+$`-validated before it gets here and
+ * both values are JSON-encoded into the source, so neither can break out.
+ */
+function jsProbeRef(ref, expectedDocumentId) {
+    return `
+const reg = window.__craftdriverRefs;
+const ref = ${JSON.stringify(ref)};
+const expected = ${JSON.stringify(expectedDocumentId)};
+if (!reg || !reg.map) return { status: 'no-registry', documentId: null };
+if (expected !== null && reg.doc !== expected) {
+  return { status: 'document-changed', documentId: reg.doc };
+}
+const el = reg.map.get(ref);
+if (!el) return { status: 'unknown-ref', documentId: reg.doc };
+if (!document.contains(el)) return { status: 'detached', documentId: reg.doc };
+const marked = document.querySelectorAll('[data-craftdriver-ref="' + ref + '"]');
+if (marked.length !== 1 || marked[0] !== el) {
+  return { status: 'ambiguous', documentId: reg.doc, count: marked.length };
+}
+return { status: 'ok', documentId: reg.doc };
+`;
+}
 /**
  * JS executed in-page. Keep it self-contained — no closure capture.
  *
  * Strategy:
- * 1. Walk a curated set of selectors (interactive + structural).
- * 2. Skip nodes outside the viewport-ish bounds and zero-sized nodes.
- * 3. For each, compute role + accessible name + a stable selector hint
- *    (prefer #id, then [data-testid], then [name], then tag+text).
- * 4. Cap output at MAX_NODES so the snapshot stays bounded regardless
+ * 1. Get or create the per-document ref registry.
+ * 2. Walk a curated set of selectors (interactive + structural).
+ * 3. Skip nodes outside the viewport-ish bounds and zero-sized nodes.
+ * 4. Reuse each node's existing ref, or issue the next unused one.
+ * 5. Cap output at MAX_NODES so the snapshot stays bounded regardless
  *    of page complexity.
  */
-const JS_SNAPSHOT = `
+function jsSnapshot(minRef) {
+    const floor = Number.isSafeInteger(minRef) && minRef >= 0 ? minRef : 0;
+    return `
 const MAX_NODES = ${MAX_NODES};
 const MAX_NAME = ${MAX_NAME};
+const MAX_REFS = ${MAX_REFS};
+const MIN_REF = ${floor};
+function newDocId(epoch) {
+  return 'd' + epoch + '-' + Math.random().toString(36).slice(2, 10);
+}
+function registry() {
+  let reg = window.__craftdriverRefs;
+  if (!reg || !reg.map) {
+    reg = { doc: newDocId(1), epoch: 1, next: 1, issued: 0, map: new Map() };
+    window.__craftdriverRefs = reg;
+  }
+  // Never reissue a number the session has already handed out. A fresh
+  // document starts its counter above the session high-water mark, so a
+  // ref captured before a navigation can never match a new element.
+  if (reg.next <= MIN_REF) reg.next = MIN_REF + 1;
+  // Bounded: at the cap, drop every marker and re-key the document so all
+  // outstanding refs fail as stale instead of wrapping onto live elements.
+  //
+  // The cap counts refs issued *by this registry*, not the counter value.
+  // Counting the counter would compare against the session-wide high-water
+  // mark, which passes the cap after enough navigations and would then
+  // re-key on every single snapshot — invalidating refs the instant they
+  // were handed out.
+  if (reg.issued >= MAX_REFS) {
+    const marked = document.querySelectorAll('[data-craftdriver-ref]');
+    for (let i = 0; i < marked.length; i++) marked[i].removeAttribute('data-craftdriver-ref');
+    reg.epoch += 1;
+    reg.doc = newDocId(reg.epoch);
+    reg.issued = 0;
+    reg.map = new Map();
+  }
+  return reg;
+}
+function refFor(reg, el) {
+  const existing = el.getAttribute('data-craftdriver-ref');
+  // Trust the attribute only when the registry agrees it names this node;
+  // that rejects authored markup and cloneNode duplicates.
+  if (existing && reg.map.get(existing) === el) return existing;
+  const ref = 'e' + reg.next;
+  reg.next += 1;
+  reg.issued += 1;
+  reg.map.set(ref, el);
+  el.setAttribute('data-craftdriver-ref', ref);
+  return ref;
+}
 function visible(el) {
   if (!el || !el.getClientRects) return false;
   if (el.hidden) return false;
@@ -94,81 +310,7 @@ function visible(el) {
   if (cs.visibility === 'hidden' || cs.display === 'none' || cs.opacity === '0') return false;
   return true;
 }
-function firstRoleToken(el) {
-  const role = (el.getAttribute('role') || '').trim();
-  return role ? role.split(/\\s+/)[0] : null;
-}
-function hasSectioningAncestor(el) {
-  for (let p = el.parentElement; p; p = p.parentElement) {
-    const t = p.tagName.toLowerCase();
-    if (t === 'article' || t === 'aside' || t === 'main' || t === 'nav' || t === 'section') {
-      return true;
-    }
-    const role = firstRoleToken(p);
-    if (
-      role === 'article' ||
-      role === 'complementary' ||
-      role === 'main' ||
-      role === 'navigation' ||
-      role === 'region'
-    ) {
-      return true;
-    }
-  }
-  return false;
-}
-function impliedRole(el) {
-  const t = el.tagName.toLowerCase();
-  const explicit = firstRoleToken(el);
-  if (explicit) return explicit;
-  if (t === 'a' && el.hasAttribute('href')) return 'link';
-  if (t === 'button') return 'button';
-  if (t === 'input') {
-    const it = (el.getAttribute('type') || 'text').toLowerCase();
-    if (it === 'submit' || it === 'button' || it === 'reset') return 'button';
-    if (it === 'checkbox') return 'checkbox';
-    if (it === 'radio') return 'radio';
-    return 'textbox';
-  }
-  if (t === 'textarea') return 'textbox';
-  if (t === 'select') {
-    const size = Number(el.getAttribute('size') || '0');
-    return el.multiple || size > 1 ? 'listbox' : 'combobox';
-  }
-  if (/^h[1-6]$/.test(t)) return 'heading';
-  if (t === 'nav') return 'navigation';
-  if (t === 'main') return 'main';
-  if (t === 'header') return hasSectioningAncestor(el) ? null : 'banner';
-  if (t === 'footer') return hasSectioningAncestor(el) ? null : 'contentinfo';
-  if (t === 'form') return 'form';
-  if (t === 'img') return 'img';
-  return t;
-}
-function accName(el) {
-  const aria = el.getAttribute('aria-label');
-  if (aria) return aria.trim();
-  const labelledby = el.getAttribute('aria-labelledby');
-  if (labelledby) {
-    const ref = document.getElementById(labelledby);
-    if (ref) return (ref.textContent || '').trim();
-  }
-  if (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA' || el.tagName === 'SELECT') {
-    if (el.id) {
-      const lbl = document.querySelector('label[for=' + JSON.stringify(el.id) + ']');
-      if (lbl) return (lbl.textContent || '').trim();
-    }
-    const parentLabel = el.closest('label');
-    if (parentLabel) return (parentLabel.textContent || '').trim();
-    const placeholder = el.getAttribute('placeholder');
-    if (placeholder) return placeholder.trim();
-  }
-  if (el.tagName === 'IMG') {
-    const alt = el.getAttribute('alt');
-    if (alt) return alt.trim();
-  }
-  const text = (el.textContent || '').trim().replace(/\\s+/g, ' ');
-  return text;
-}
+${PAGE_SEMANTICS_JS}
 function locatorHint(el) {
   if (el.id) return '#' + el.id;
   const testid = el.getAttribute('data-testid') || el.getAttribute('data-test-id');
@@ -177,22 +319,25 @@ function locatorHint(el) {
   if (name) return el.tagName.toLowerCase() + '[name=' + JSON.stringify(name) + ']';
   return null;
 }
+const reg = registry();
 const sel = 'a,button,input,select,textarea,h1,h2,h3,h4,h5,h6,[role],nav,main,header,footer,form,img,label';
-// Wipe stale refs from a previous snapshot so numbering is deterministic.
-const stale = document.querySelectorAll('[data-craftdriver-ref]');
-for (let i = 0; i < stale.length; i++) stale[i].removeAttribute('data-craftdriver-ref');
 const out = [];
+const refs = [];
 const nodes = document.querySelectorAll(sel);
 for (let i = 0; i < nodes.length && out.length < MAX_NODES; i++) {
   const el = nodes[i];
   if (!visible(el)) continue;
-  const role = impliedRole(el);
-  if (!role) continue;
+  // A <header>/<footer> inside sectioning content is not a landmark, and
+  // listing it as a bare tag would be pure noise. Everything else keeps a
+  // line even without an ARIA role, so controls stay addressable by ref.
+  const tag = el.tagName.toLowerCase();
+  if (!ariaRole(el) && (tag === 'header' || tag === 'footer')) continue;
+  const role = displayRole(el);
   let name = accName(el);
   if (name.length > MAX_NAME) name = name.slice(0, MAX_NAME - 1) + '…';
   const hint = locatorHint(el);
-  const ref = 'e' + (out.length + 1);
-  el.setAttribute('data-craftdriver-ref', ref);
+  const ref = refFor(reg, el);
+  refs.push(ref);
   let line = ref + ': ' + role;
   if (name) line += ' "' + name + '"';
   if (hint) line += ' ' + hint;
@@ -201,6 +346,7 @@ for (let i = 0; i < nodes.length && out.length < MAX_NODES; i++) {
   if (el.checked) line += ' (checked)';
   out.push(line);
 }
-return out;
+return { lines: out, refs: refs, documentId: reg.doc, nextRef: reg.next };
 `;
+}
 //# sourceMappingURL=snapshot.js.map

package/dist/cli/snapshot.js.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/cli/snapshot.ts"],"names":[],"mappings":"AAiBA,MAAM,SAAS,GAAG,EAAE,CAAC;AACrB,MAAM,QAAQ,GAAG,EAAE,CAAC;AASpB;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAAgB;IACjD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC;QACxC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YACrC,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC;SAC7B,CAAC,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;QAC/C,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,KAAkB,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IAChF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CACzB,IAA0B,EAC1B,IAA0B;IAE1B,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,MAAM,MAAM,GAAG,SAAS,IAAI,CAAC,KAAK,IAAI,YAAY,MAAM,IAAI,CAAC,GAAG,IAAI,UAAU,EAAE,CAAC;IACjF,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,+BAA+B;QAC/B,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,GAAG,MAAM,sCAAsC,CAAC;QACpF,OAAO,GAAG,MAAM,KAAK,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IAC/C,CAAC;IACD,IAAI,IAAI,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC;QAC1B,gCAAgC;QAChC,OAAO,GAAG,MAAM,KAAK,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IAC/C,CAAC;IACD,MAAM,KAAK,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAChE,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;IAClD,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;IAClD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACzF,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACvF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/C,OAAO,GAAG,MAAM,qBAAqB,CAAC;IACxC,CAAC;IACD,OAAO,GAAG,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AAC1D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,IAA0B;IACnD,IAAI,CAAC,IAAI;QAAE,OAAO,yBAAyB,CAAC;IAC5C,MAAM,MAAM,GAAG,SAAS,IAAI,CAAC,KAAK,IAAI,YAAY,MAAM,IAAI,CAAC,GAAG,IAAI,UAAU,EAAE,CAAC;IACjF,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,GAAG,MAAM,sCAAsC,CAAC;IACzD,CAAC;IACD,OAAO,GAAG,MAAM,KAAK,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,GAAG;oBACA,SAAS;mBACV,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwH1B,CAAC"}
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/cli/snapshot.ts"],"names":[],"mappings":"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"}

package/dist/cli/stateStore.d.ts

@@ -0,0 +1,50 @@
+import type { SessionState } from '../lib/bidi/types.js';
+import { prepareTempPath, commitFile, discardTempFile } from './artifactPaths.js';
+/** Owned root for state files, overridable for tests and CI sandboxes. */
+export declare function stateRoot(env?: NodeJS.ProcessEnv): string;
+/** Longest accepted state name. Kept exported for the error-message tests. */
+export declare const MAX_STATE_NAME = 64;
+/**
+ * Normalize and validate an untrusted state name.
+ *
+ * The rule is shared with every other CLI-owned artifact — see
+ * `artifactPaths.ts` — so a name that is safe as a path component is safe for
+ * all of them, and there is only one place to get it wrong.
+ */
+export declare function validateStateName(raw: unknown): string;
+/**
+ * Full path for a state name, guaranteed to sit inside the owned root.
+ */
+export declare function resolveStatePath(name: string, env?: NodeJS.ProcessEnv): Promise<string>;
+/** @see prepareTempPath */
+export declare const prepareTempStatePath: typeof prepareTempPath;
+/** @see commitFile */
+export declare const commitStateFile: typeof commitFile;
+/** @see discardTempFile */
+export declare const discardTempStateFile: typeof discardTempFile;
+/**
+ * Read and structurally validate a state file.
+ *
+ * The file is JSON that will be fed back into a browser, so a malformed or
+ * hand-edited one should fail here with a clear message rather than deep
+ * inside cookie restoration.
+ */
+export declare function readStateFile(target: string, name: string): Promise<SessionState>;
+/** Origins whose storage a state file carries. */
+export declare function stateOrigins(state: SessionState): string[];
+export interface StateSummary {
+    cookies: number;
+    origins: string[];
+    storageKeys: number;
+}
+/**
+ * Reportable shape of a state file: counts and origins, never values.
+ *
+ * Cookie names and storage keys are omitted too. They are not secrets in the
+ * way values are, but they are unnecessary to the caller and land in agent
+ * transcripts and CI logs, so the useful-to-leaky trade is not worth it.
+ */
+export declare function summarizeState(state: SessionState): StateSummary;
+/** Saved state names under the root, without the `.json` suffix. */
+export declare function listStateNames(env?: NodeJS.ProcessEnv): Promise<string[]>;
+//# sourceMappingURL=stateStore.d.ts.map

package/dist/cli/stateStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stateStore.d.ts","sourceRoot":"","sources":["../../src/cli/stateStore.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,OAAO,EAIL,eAAe,EACf,UAAU,EACV,eAAe,EAEhB,MAAM,oBAAoB,CAAC;AAE5B,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAEtE;AAED,8EAA8E;AAC9E,eAAO,MAAM,cAAc,KAAoB,CAAC;AAEhD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAEtD;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAO7F;AAED,2BAA2B;AAC3B,eAAO,MAAM,oBAAoB,wBAAkB,CAAC;AACpD,sBAAsB;AACtB,eAAO,MAAM,eAAe,mBAAa,CAAC;AAC1C,2BAA2B;AAC3B,eAAO,MAAM,oBAAoB,wBAAkB,CAAC;AAEpD;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAevF;AAED,kDAAkD;AAClD,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,EAAE,CAK1D;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,CAYhE;AAED,oEAAoE;AACpE,wBAAsB,cAAc,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAW/E"}

package/dist/cli/stateStore.js

@@ -0,0 +1,122 @@
+/**
+ * Safe on-disk storage for authentication/session state.
+ *
+ * A saved state file holds live session cookies — it is a credential, not a
+ * fixture. Three properties follow from that, and each is enforced here rather
+ * than at the call site:
+ *
+ * - **Files live under one owned root.** Callers name a file, not a path, so a
+ *   command can never be talked into writing over `~/.ssh/config` or reading
+ *   an arbitrary file back into a browser. The root is `CRAFTDRIVER_STATE_DIR`
+ *   when set, else `.craftdriver/state` under the working directory.
+ * - **Symlinks cannot escape it.** Containment is checked against the resolved
+ *   real path of the deepest existing ancestor, so a symlink planted inside
+ *   the root does not widen it.
+ * - **Nothing is half-written and nothing is world-readable.** Writes land on
+ *   a temp file created `0600` and are renamed into place, so a reader sees
+ *   either the old file or the new one, never a truncated JSON document.
+ *
+ * Callers must also never print what these files contain — see
+ * `summarizeState`, which is deliberately the only reporting path.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { CraftdriverError, ErrorCode } from '../lib/errors.js';
+import { parseSessionState } from '../lib/sessionStateValidation.js';
+import { artifactRoot, resolveArtifactPath, validateArtifactName, prepareTempPath, commitFile, discardTempFile, MAX_ARTIFACT_NAME, } from './artifactPaths.js';
+/** Owned root for state files, overridable for tests and CI sandboxes. */
+export function stateRoot(env = process.env) {
+    return artifactRoot('state', 'CRAFTDRIVER_STATE_DIR', env);
+}
+/** Longest accepted state name. Kept exported for the error-message tests. */
+export const MAX_STATE_NAME = MAX_ARTIFACT_NAME;
+/**
+ * Normalize and validate an untrusted state name.
+ *
+ * The rule is shared with every other CLI-owned artifact — see
+ * `artifactPaths.ts` — so a name that is safe as a path component is safe for
+ * all of them, and there is only one place to get it wrong.
+ */
+export function validateStateName(raw) {
+    return validateArtifactName(raw, 'state', stateRoot());
+}
+/**
+ * Full path for a state name, guaranteed to sit inside the owned root.
+ */
+export async function resolveStatePath(name, env) {
+    return resolveArtifactPath({
+        root: stateRoot(env),
+        name,
+        suffix: '.json',
+        kind: 'state',
+    });
+}
+/** @see prepareTempPath */
+export const prepareTempStatePath = prepareTempPath;
+/** @see commitFile */
+export const commitStateFile = commitFile;
+/** @see discardTempFile */
+export const discardTempStateFile = discardTempFile;
+/**
+ * Read and structurally validate a state file.
+ *
+ * The file is JSON that will be fed back into a browser, so a malformed or
+ * hand-edited one should fail here with a clear message rather than deep
+ * inside cookie restoration.
+ */
+export async function readStateFile(target, name) {
+    try {
+        await fs.access(target);
+    }
+    catch {
+        throw new CraftdriverError(ErrorCode.STATE_INVALID, `state: no saved state named ${JSON.stringify(name)}`, {
+            detail: { root: path.dirname(target) },
+            hint: 'save one first with `craftdriver state save <name>`, or `state list` to see what exists',
+        });
+    }
+    return parseSessionState(target, { operation: 'cli.state.load' });
+}
+/** Origins whose storage a state file carries. */
+export function stateOrigins(state) {
+    const origins = new Set();
+    for (const key of Object.keys(state.localStorage ?? {}))
+        origins.add(key);
+    for (const key of Object.keys(state.sessionStorage ?? {}))
+        origins.add(key);
+    return [...origins];
+}
+/**
+ * Reportable shape of a state file: counts and origins, never values.
+ *
+ * Cookie names and storage keys are omitted too. They are not secrets in the
+ * way values are, but they are unnecessary to the caller and land in agent
+ * transcripts and CI logs, so the useful-to-leaky trade is not worth it.
+ */
+export function summarizeState(state) {
+    let storageKeys = 0;
+    for (const bucket of [state.localStorage, state.sessionStorage]) {
+        for (const entries of Object.values(bucket ?? {})) {
+            storageKeys += Object.keys(entries ?? {}).length;
+        }
+    }
+    return {
+        cookies: state.cookies?.length ?? 0,
+        origins: stateOrigins(state),
+        storageKeys,
+    };
+}
+/** Saved state names under the root, without the `.json` suffix. */
+export async function listStateNames(env) {
+    const root = stateRoot(env);
+    try {
+        const entries = await fs.readdir(root);
+        return entries
+            .filter((entry) => entry.endsWith('.json'))
+            .map((entry) => entry.slice(0, -'.json'.length))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=stateStore.js.map

package/dist/cli/stateStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stateStore.js","sourceRoot":"","sources":["../../src/cli/stateStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,UAAU,EACV,eAAe,EACf,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAE5B,0EAA0E;AAC1E,MAAM,UAAU,SAAS,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC5D,OAAO,YAAY,CAAC,OAAO,EAAE,uBAAuB,EAAE,GAAG,CAAC,CAAC;AAC7D,CAAC;AAED,8EAA8E;AAC9E,MAAM,CAAC,MAAM,cAAc,GAAG,iBAAiB,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAY;IAC5C,OAAO,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;AACzD,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAY,EAAE,GAAuB;IAC1E,OAAO,mBAAmB,CAAC;QACzB,IAAI,EAAE,SAAS,CAAC,GAAG,CAAC;QACpB,IAAI;QACJ,MAAM,EAAE,OAAO;QACf,IAAI,EAAE,OAAO;KACd,CAAC,CAAC;AACL,CAAC;AAED,2BAA2B;AAC3B,MAAM,CAAC,MAAM,oBAAoB,GAAG,eAAe,CAAC;AACpD,sBAAsB;AACtB,MAAM,CAAC,MAAM,eAAe,GAAG,UAAU,CAAC;AAC1C,2BAA2B;AAC3B,MAAM,CAAC,MAAM,oBAAoB,GAAG,eAAe,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAc,EAAE,IAAY;IAC9D,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,gBAAgB,CACxB,SAAS,CAAC,aAAa,EACvB,+BAA+B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,EACrD;YACE,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE;YACtC,IAAI,EAAE,yFAAyF;SAChG,CACF,CAAC;IACJ,CAAC;IAED,OAAO,iBAAiB,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,gBAAgB,EAAE,CAAC,CAAC;AACpE,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,YAAY,CAAC,KAAmB;IAC9C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,IAAI,EAAE,CAAC;QAAE,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC1E,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,cAAc,IAAI,EAAE,CAAC;QAAE,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5E,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC;AACtB,CAAC;AAQD;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAAmB;IAChD,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,KAAK,MAAM,MAAM,IAAI,CAAC,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,cAAc,CAAC,EAAE,CAAC;QAChE,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;YAClD,WAAW,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QACnD,CAAC;IACH,CAAC;IACD,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;QACnC,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC;QAC5B,WAAW;KACZ,CAAC;AACJ,CAAC;AAED,oEAAoE;AACpE,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,GAAuB;IAC1D,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAC5B,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACvC,OAAO,OAAO;aACX,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;aAC1C,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;aAC/C,IAAI,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export { BrowserContext, type ClearCookiesFilter, type ContextStorageStateOption
 export { Keyboard } from './lib/keyboard.js';
 export { Mouse } from './lib/mouse.js';
 export { type TraceStartOptions, type TraceStopOptions, type TraceScreenshotMode, type TraceEvent, } from './lib/tracing.js';
-export { NetworkInterceptor, LogMonitor, SessionStateManager, type Cookie, type CookieInput, type SessionState, type StorageStateOptions, type MockResponse, type InterceptedRequest, type InterceptedResponse, type ConsoleMessage, type JavaScriptError, type LogMessage, } from './lib/bidi/index.js';
+export { NetworkInterceptor, LogMonitor, SessionStateManager, type Cookie, type CookieInput, type SessionState, type SessionStateCookie, type StorageStateOptions, type MockResponse, type InterceptedRequest, type InterceptedResponse, type ConsoleMessage, type JavaScriptError, type LogMessage, } from './lib/bidi/index.js';
 export { ChromeService, type ChromeServiceOptions } from './lib/chrome.js';
 export { ElectronService, type ElectronServiceOptions } from './lib/electron.js';
 export { FirefoxService, type FirefoxServiceOptions } from './lib/firefox.js';
@@ -20,5 +20,6 @@ export { type ElectronDialogMock, type ElectronDialogMethod, type ElectronDialog
 export { type ElectronMock, type ElectronMockCall } from './lib/electronMock.js';
 export { ElectronMainLogMonitor, type ElectronMainLog, type ElectronMainLogLevel, type ElectronMainLogHandler, } from './lib/electronMainLogs.js';
 export { Clock, type ClockTime, type ClockInstallOptions, } from './lib/clock.js';
+export { compareScreenshots, VisualMismatchError, type ScreenshotCompareOptions, type ExpectScreenshotOptions, type VisualScreenshotOptions, type VisualComparisonResult, type ScreenshotMatchResult, } from './lib/visual/index.js';
 export { A11y, A11yError, type A11yOptions, type A11yResult, type A11yViolation, type A11yViolationNode, type A11yImpact, } from './lib/a11y.js';
 //# sourceMappingURL=index.d.ts.map