opensteer 0.4.13 → 0.5.0

package/dist/{chunk-JSH3VLMH.js → chunk-SXPIGCSD.js}

@@ -2,6 +2,232 @@ import {
   flattenExtractionDataToFieldPlan
 } from "./chunk-3H5RRIMZ.js";
 
+// src/error-normalization.ts
+function extractErrorMessage(error, fallback = "Unknown error.") {
+  if (error instanceof Error) {
+    const message = error.message.trim();
+    if (message) return message;
+    const name = error.name.trim();
+    if (name) return name;
+  }
+  if (typeof error === "string" && error.trim()) {
+    return error.trim();
+  }
+  const record = asRecord(error);
+  const recordMessage = toNonEmptyString(record?.message) || toNonEmptyString(record?.error);
+  if (recordMessage) {
+    return recordMessage;
+  }
+  return fallback;
+}
+function normalizeError(error, fallback = "Unknown error.", maxCauseDepth = 2) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  return normalizeErrorInternal(error, fallback, maxCauseDepth, seen);
+}
+function normalizeErrorInternal(error, fallback, depthRemaining, seen) {
+  const record = asRecord(error);
+  if (record) {
+    if (seen.has(record)) {
+      return {
+        message: extractErrorMessage(error, fallback)
+      };
+    }
+    seen.add(record);
+  }
+  const message = extractErrorMessage(error, fallback);
+  const code = extractCode(error);
+  const name = extractName(error);
+  const details = extractDetails(error);
+  if (depthRemaining <= 0) {
+    return compactErrorInfo({
+      message,
+      ...code ? { code } : {},
+      ...name ? { name } : {},
+      ...details ? { details } : {}
+    });
+  }
+  const cause = extractCause(error);
+  if (!cause) {
+    return compactErrorInfo({
+      message,
+      ...code ? { code } : {},
+      ...name ? { name } : {},
+      ...details ? { details } : {}
+    });
+  }
+  const normalizedCause = normalizeErrorInternal(
+    cause,
+    "Caused by an unknown error.",
+    depthRemaining - 1,
+    seen
+  );
+  return compactErrorInfo({
+    message,
+    ...code ? { code } : {},
+    ...name ? { name } : {},
+    ...details ? { details } : {},
+    cause: normalizedCause
+  });
+}
+function compactErrorInfo(info) {
+  const safeDetails = toJsonSafeRecord(info.details);
+  return {
+    message: info.message,
+    ...info.code ? { code: info.code } : {},
+    ...info.name ? { name: info.name } : {},
+    ...safeDetails ? { details: safeDetails } : {},
+    ...info.cause ? { cause: info.cause } : {}
+  };
+}
+function extractCode(error) {
+  const record = asRecord(error);
+  const raw = record?.code;
+  if (typeof raw === "string" && raw.trim()) {
+    return raw.trim();
+  }
+  if (typeof raw === "number" && Number.isFinite(raw)) {
+    return String(raw);
+  }
+  return void 0;
+}
+function extractName(error) {
+  if (error instanceof Error && error.name.trim()) {
+    return error.name.trim();
+  }
+  const record = asRecord(error);
+  return toNonEmptyString(record?.name);
+}
+function extractDetails(error) {
+  const record = asRecord(error);
+  if (!record) return void 0;
+  const details = {};
+  const rawDetails = asRecord(record.details);
+  if (rawDetails) {
+    Object.assign(details, rawDetails);
+  }
+  const action = toNonEmptyString(record.action);
+  if (action) {
+    details.action = action;
+  }
+  const selectorUsed = toNonEmptyString(record.selectorUsed);
+  if (selectorUsed) {
+    details.selectorUsed = selectorUsed;
+  }
+  if (typeof record.status === "number" && Number.isFinite(record.status)) {
+    details.status = record.status;
+  }
+  const failure = asRecord(record.failure);
+  if (failure) {
+    const failureCode = toNonEmptyString(failure.code);
+    const classificationSource = toNonEmptyString(
+      failure.classificationSource
+    );
+    const failureDetails = asRecord(failure.details);
+    if (failureCode || classificationSource || failureDetails) {
+      details.actionFailure = {
+        ...failureCode ? { code: failureCode } : {},
+        ...classificationSource ? { classificationSource } : {},
+        ...failureDetails ? { details: failureDetails } : {}
+      };
+    }
+  }
+  return Object.keys(details).length ? details : void 0;
+}
+function extractCause(error) {
+  if (error instanceof Error) {
+    return error.cause;
+  }
+  const record = asRecord(error);
+  return record?.cause;
+}
+function asRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value;
+}
+function toNonEmptyString(value) {
+  if (typeof value !== "string") return void 0;
+  const normalized = value.trim();
+  return normalized.length ? normalized : void 0;
+}
+function toJsonSafeRecord(value) {
+  if (!value) return void 0;
+  const sanitized = toJsonSafeValue(value, /* @__PURE__ */ new WeakSet());
+  if (!sanitized || typeof sanitized !== "object" || Array.isArray(sanitized)) {
+    return void 0;
+  }
+  const record = sanitized;
+  return Object.keys(record).length > 0 ? record : void 0;
+}
+function toJsonSafeValue(value, seen) {
+  if (value === null) return null;
+  if (typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : null;
+  }
+  if (typeof value === "bigint") {
+    return value.toString();
+  }
+  if (value === void 0 || typeof value === "function" || typeof value === "symbol") {
+    return void 0;
+  }
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? null : value.toISOString();
+  }
+  if (Array.isArray(value)) {
+    if (seen.has(value)) return "[Circular]";
+    seen.add(value);
+    const output = value.map((item) => {
+      const next = toJsonSafeValue(item, seen);
+      return next === void 0 ? null : next;
+    });
+    seen.delete(value);
+    return output;
+  }
+  if (value instanceof Set) {
+    if (seen.has(value)) return "[Circular]";
+    seen.add(value);
+    const output = Array.from(value, (item) => {
+      const next = toJsonSafeValue(item, seen);
+      return next === void 0 ? null : next;
+    });
+    seen.delete(value);
+    return output;
+  }
+  if (value instanceof Map) {
+    if (seen.has(value)) return "[Circular]";
+    seen.add(value);
+    const output = {};
+    for (const [key, item] of value.entries()) {
+      const normalizedKey = String(key);
+      const next = toJsonSafeValue(item, seen);
+      if (next !== void 0) {
+        output[normalizedKey] = next;
+      }
+    }
+    seen.delete(value);
+    return output;
+  }
+  if (typeof value === "object") {
+    const objectValue = value;
+    if (seen.has(objectValue)) return "[Circular]";
+    seen.add(objectValue);
+    const output = {};
+    for (const [key, item] of Object.entries(objectValue)) {
+      const next = toJsonSafeValue(item, seen);
+      if (next !== void 0) {
+        output[key] = next;
+      }
+    }
+    seen.delete(objectValue);
+    return output;
+  }
+  return void 0;
+}
+
 // src/storage/namespace.ts
 import path from "path";
 var DEFAULT_NAMESPACE = "default";
@@ -607,9 +833,11 @@ import path2 from "path";
 var LocalSelectorStorage = class {
   rootDir;
   namespace;
-  constructor(rootDir, namespace) {
+  debug;
+  constructor(rootDir, namespace, options = {}) {
     this.rootDir = rootDir;
     this.namespace = normalizeNamespace(namespace);
+    this.debug = options.debug === true;
   }
   getRootDir() {
     return this.rootDir;
@@ -643,7 +871,16 @@ var LocalSelectorStorage = class {
     try {
       const raw = fs.readFileSync(file, "utf8");
       return JSON.parse(raw);
-    } catch {
+    } catch (error) {
+      const message = extractErrorMessage(
+        error,
+        "Unable to parse selector registry JSON."
+      );
+      if (this.debug) {
+        console.warn(
+          `[opensteer] failed to read selector registry "${file}": ${message}`
+        );
+      }
       return createEmptyRegistry(this.namespace);
     }
   }
@@ -660,7 +897,16 @@ var LocalSelectorStorage = class {
     try {
       const raw = fs.readFileSync(file, "utf8");
       return JSON.parse(raw);
-    } catch {
+    } catch (error) {
+      const message = extractErrorMessage(
+        error,
+        "Unable to parse selector file JSON."
+      );
+      if (this.debug) {
+        console.warn(
+          `[opensteer] failed to read selector file "${file}": ${message}`
+        );
+      }
       return null;
     }
   }
@@ -946,9 +1192,6 @@ var ENSURE_NAME_SHIM_SCRIPT = `
 `;
 var OS_FRAME_TOKEN_KEY = "__opensteerFrameToken";
 var OS_INSTANCE_TOKEN_KEY = "__opensteerInstanceToken";
-var OS_COUNTER_OWNER_KEY = "__opensteerCounterOwner";
-var OS_COUNTER_VALUE_KEY = "__opensteerCounterValue";
-var OS_COUNTER_NEXT_KEY = "__opensteerCounterNext";
 
 // src/element-path/build.ts
 var MAX_ATTRIBUTE_VALUE_LENGTH = 300;
@@ -2739,567 +2982,179 @@ function cleanForAction(html) {
   return compactHtml(htmlOut);
 }
 
-// src/extract-value-normalization.ts
-var URL_LIST_ATTRIBUTES = /* @__PURE__ */ new Set(["srcset", "imagesrcset", "ping"]);
-function normalizeExtractedValue(raw, attribute) {
-  if (raw == null) return null;
-  const rawText = String(raw);
-  if (!rawText.trim()) return null;
-  const normalizedAttribute = String(attribute || "").trim().toLowerCase();
-  if (URL_LIST_ATTRIBUTES.has(normalizedAttribute)) {
-    const singleValue = pickSingleListAttributeValue(
-      normalizedAttribute,
-      rawText
-    ).trim();
-    return singleValue || null;
+// src/html/pipeline.ts
+import * as cheerio3 from "cheerio";
+function applyCleaner(mode, html) {
+  switch (mode) {
+    case "clickable":
+      return cleanForClickable(html);
+    case "scrollable":
+      return cleanForScrollable(html);
+    case "extraction":
+      return cleanForExtraction(html);
+    case "full":
+      return cleanForFull(html);
+    case "action":
+    default:
+      return cleanForAction(html);
   }
-  const text = rawText.replace(/\s+/g, " ").trim();
-  return text || null;
 }
-function pickSingleListAttributeValue(attribute, raw) {
-  if (attribute === "ping") {
-    const firstUrl = raw.trim().split(/\s+/)[0] || "";
-    return firstUrl.trim();
-  }
-  if (attribute === "srcset" || attribute === "imagesrcset") {
-    const picked = pickBestSrcsetCandidate(raw);
-    if (picked) return picked;
-    return pickFirstSrcsetToken(raw) || "";
+async function assignCounters(page, html, nodePaths, nodeMeta) {
+  const $ = cheerio3.load(html, { xmlMode: false });
+  const counterIndex = /* @__PURE__ */ new Map();
+  let nextCounter = 1;
+  const assignedByNodeId = /* @__PURE__ */ new Map();
+  $("*").each(function() {
+    const el = $(this);
+    const nodeId = el.attr(OS_NODE_ID_ATTR);
+    if (!nodeId) return;
+    const counter = nextCounter++;
+    assignedByNodeId.set(nodeId, counter);
+    const path5 = nodePaths.get(nodeId);
+    el.attr("c", String(counter));
+    el.removeAttr(OS_NODE_ID_ATTR);
+    if (path5) {
+      counterIndex.set(counter, cloneElementPath(path5));
+    }
+  });
+  try {
+    await syncLiveCounters(page, nodeMeta, assignedByNodeId);
+  } catch (error) {
+    await clearLiveCounters(page);
+    throw error;
   }
-  return raw.trim();
+  $(`[${OS_NODE_ID_ATTR}]`).removeAttr(OS_NODE_ID_ATTR);
+  return {
+    html: $.html(),
+    counterIndex
+  };
 }
-function pickBestSrcsetCandidate(raw) {
-  const candidates = parseSrcsetCandidates(raw);
-  if (!candidates.length) return null;
-  const widthCandidates = candidates.filter(
-    (candidate) => typeof candidate.width === "number" && Number.isFinite(candidate.width) && candidate.width > 0
-  );
-  if (widthCandidates.length) {
-    return widthCandidates.reduce(
-      (best, candidate) => candidate.width > best.width ? candidate : best
-    ).url;
-  }
-  const densityCandidates = candidates.filter(
-    (candidate) => typeof candidate.density === "number" && Number.isFinite(candidate.density) && candidate.density > 0
-  );
-  if (densityCandidates.length) {
-    return densityCandidates.reduce(
-      (best, candidate) => candidate.density > best.density ? candidate : best
-    ).url;
+async function syncLiveCounters(page, nodeMeta, assignedByNodeId) {
+  await clearLiveCounters(page);
+  if (!assignedByNodeId.size) return;
+  const groupedByFrame = /* @__PURE__ */ new Map();
+  for (const [nodeId, counter] of assignedByNodeId.entries()) {
+    const meta = nodeMeta.get(nodeId);
+    if (!meta?.frameToken) continue;
+    const list = groupedByFrame.get(meta.frameToken) || [];
+    list.push({
+      nodeId,
+      counter
+    });
+    groupedByFrame.set(meta.frameToken, list);
   }
-  return candidates[0]?.url || null;
-}
-function parseSrcsetCandidates(raw) {
-  const text = String(raw || "").trim();
-  if (!text) return [];
-  const out = [];
-  let index = 0;
-  while (index < text.length) {
-    index = skipSeparators(text, index);
-    if (index >= text.length) break;
-    const urlToken = readUrlToken(text, index);
-    index = urlToken.nextIndex;
-    const url = urlToken.value.trim();
-    if (!url) continue;
-    index = skipWhitespace(text, index);
-    const descriptors = [];
-    while (index < text.length && text[index] !== ",") {
-      const descriptorToken = readDescriptorToken(text, index);
-      if (!descriptorToken.value) {
-        index = descriptorToken.nextIndex;
-        continue;
+  if (!groupedByFrame.size) return;
+  const failures = [];
+  const framesByToken = await mapFramesByToken(page);
+  for (const [frameToken, entries] of groupedByFrame.entries()) {
+    const frame = framesByToken.get(frameToken);
+    if (!frame) {
+      for (const entry of entries) {
+        failures.push({
+          nodeId: entry.nodeId,
+          counter: entry.counter,
+          frameToken,
+          reason: "frame_missing"
+        });
       }
-      descriptors.push(descriptorToken.value);
-      index = descriptorToken.nextIndex;
-      index = skipWhitespace(text, index);
-    }
-    if (index < text.length && text[index] === ",") {
-      index += 1;
+      continue;
     }
-    let width = null;
-    let density = null;
-    for (const descriptor of descriptors) {
-      const token = descriptor.trim().toLowerCase();
-      if (!token) continue;
-      const widthMatch = token.match(/^(\d+)w$/);
-      if (widthMatch) {
-        const parsed = Number.parseInt(widthMatch[1], 10);
-        if (Number.isFinite(parsed)) {
-          width = parsed;
+    try {
+      const unresolved = await frame.evaluate(
+        ({ entries: entries2, nodeAttr }) => {
+          const index = /* @__PURE__ */ new Map();
+          const unresolved2 = [];
+          const walk = (root) => {
+            const children = Array.from(root.children);
+            for (const child of children) {
+              const nodeId = child.getAttribute(nodeAttr);
+              if (nodeId) {
+                const list = index.get(nodeId) || [];
+                list.push(child);
+                index.set(nodeId, list);
+              }
+              walk(child);
+              if (child.shadowRoot) {
+                walk(child.shadowRoot);
+              }
+            }
+          };
+          walk(document);
+          for (const entry of entries2) {
+            const matches = index.get(entry.nodeId) || [];
+            if (matches.length !== 1) {
+              unresolved2.push({
+                nodeId: entry.nodeId,
+                counter: entry.counter,
+                matches: matches.length
+              });
+              continue;
+            }
+            matches[0].setAttribute("c", String(entry.counter));
+          }
+          return unresolved2;
+        },
+        {
+          entries,
+          nodeAttr: OS_NODE_ID_ATTR
         }
-        continue;
+      );
+      for (const entry of unresolved) {
+        failures.push({
+          nodeId: entry.nodeId,
+          counter: entry.counter,
+          frameToken,
+          reason: "match_count",
+          matches: entry.matches
+        });
       }
-      const densityMatch = token.match(/^(\d*\.?\d+)x$/);
-      if (densityMatch) {
-        const parsed = Number.parseFloat(densityMatch[1]);
-        if (Number.isFinite(parsed)) {
-          density = parsed;
-        }
+    } catch {
+      for (const entry of entries) {
+        failures.push({
+          nodeId: entry.nodeId,
+          counter: entry.counter,
+          frameToken,
+          reason: "frame_unavailable"
+        });
       }
     }
-    out.push({
-      url,
-      width,
-      density
+  }
+  if (failures.length) {
+    const preview = failures.slice(0, 3).map((failure) => {
+      const base = `counter ${failure.counter} (nodeId "${failure.nodeId}") in frame "${failure.frameToken}"`;
+      if (failure.reason === "frame_missing") {
+        return `${base} could not be synchronized because the frame is missing.`;
+      }
+      if (failure.reason === "frame_unavailable") {
+        return `${base} could not be synchronized because frame evaluation failed.`;
+      }
+      return `${base} expected exactly one live node but found ${failure.matches ?? 0}.`;
     });
+    const remaining = failures.length > 3 ? ` (+${failures.length - 3} more)` : "";
+    throw new Error(
+      `Failed to synchronize snapshot counters with the live DOM: ${preview.join(" ")}${remaining}`
+    );
   }
-  return out;
 }
-function pickFirstSrcsetToken(raw) {
-  const candidate = parseSrcsetCandidates(raw)[0];
-  if (candidate?.url) {
-    return candidate.url;
+async function clearLiveCounters(page) {
+  for (const frame of page.frames()) {
+    try {
+      await frame.evaluate(() => {
+        const walk = (root) => {
+          const children = Array.from(root.children);
+          for (const child of children) {
+            child.removeAttribute("c");
+            walk(child);
+            if (child.shadowRoot) {
+              walk(child.shadowRoot);
+            }
+          }
+        };
+        walk(document);
+      });
+    } catch {
+    }
   }
-  const text = String(raw || "");
-  const start = skipSeparators(text, 0);
-  if (start >= text.length) return null;
-  const firstToken = readUrlToken(text, start).value.trim();
-  return firstToken || null;
-}
-function skipWhitespace(value, index) {
-  let cursor = index;
-  while (cursor < value.length && /\s/.test(value[cursor])) {
-    cursor += 1;
-  }
-  return cursor;
-}
-function skipSeparators(value, index) {
-  let cursor = skipWhitespace(value, index);
-  while (cursor < value.length && value[cursor] === ",") {
-    cursor += 1;
-    cursor = skipWhitespace(value, cursor);
-  }
-  return cursor;
-}
-function readUrlToken(value, index) {
-  let cursor = index;
-  let out = "";
-  const isDataUrl = value.slice(index, index + 5).toLowerCase().startsWith("data:");
-  while (cursor < value.length) {
-    const char = value[cursor];
-    if (/\s/.test(char)) {
-      break;
-    }
-    if (char === "," && !isDataUrl) {
-      break;
-    }
-    out += char;
-    cursor += 1;
-  }
-  if (isDataUrl && out.endsWith(",") && cursor < value.length) {
-    out = out.slice(0, -1);
-  }
-  return {
-    value: out,
-    nextIndex: cursor
-  };
-}
-function readDescriptorToken(value, index) {
-  let cursor = skipWhitespace(value, index);
-  let out = "";
-  while (cursor < value.length) {
-    const char = value[cursor];
-    if (char === "," || /\s/.test(char)) {
-      break;
-    }
-    out += char;
-    cursor += 1;
-  }
-  return {
-    value: out.trim(),
-    nextIndex: cursor
-  };
-}
-
-// src/html/counter-runtime.ts
-var CounterResolutionError = class extends Error {
-  code;
-  constructor(code, message) {
-    super(message);
-    this.name = "CounterResolutionError";
-    this.code = code;
-  }
-};
-async function ensureLiveCounters(page, nodeMeta, nodeIds) {
-  const out = /* @__PURE__ */ new Map();
-  if (!nodeIds.length) return out;
-  const grouped = /* @__PURE__ */ new Map();
-  for (const nodeId of nodeIds) {
-    const meta = nodeMeta.get(nodeId);
-    if (!meta) {
-      throw new CounterResolutionError(
-        "ERR_COUNTER_STALE_OR_NOT_FOUND",
-        `Missing metadata for node ${nodeId}. Run snapshot() again.`
-      );
-    }
-    const list = grouped.get(meta.frameToken) || [];
-    list.push({
-      nodeId,
-      instanceToken: meta.instanceToken
-    });
-    grouped.set(meta.frameToken, list);
-  }
-  const framesByToken = await mapFramesByToken(page);
-  let nextCounter = await readGlobalNextCounter(page);
-  const usedCounters = /* @__PURE__ */ new Map();
-  for (const [frameToken, entries] of grouped.entries()) {
-    const frame = framesByToken.get(frameToken);
-    if (!frame) {
-      throw new CounterResolutionError(
-        "ERR_COUNTER_FRAME_UNAVAILABLE",
-        `Counter frame ${frameToken} is unavailable. Run snapshot() again.`
-      );
-    }
-    const result = await frame.evaluate(
-      ({
-        entries: entries2,
-        nodeAttr,
-        instanceTokenKey,
-        counterOwnerKey,
-        counterValueKey,
-        startCounter
-      }) => {
-        const helpers = {
-          pushNode(map, node) {
-            const nodeId = node.getAttribute(nodeAttr);
-            if (!nodeId) return;
-            const list = map.get(nodeId) || [];
-            list.push(node);
-            map.set(nodeId, list);
-          },
-          walk(map, root) {
-            const children = Array.from(root.children);
-            for (const child of children) {
-              helpers.pushNode(map, child);
-              helpers.walk(map, child);
-              if (child.shadowRoot) {
-                helpers.walk(map, child.shadowRoot);
-              }
-            }
-          },
-          buildNodeIndex() {
-            const map = /* @__PURE__ */ new Map();
-            helpers.walk(map, document);
-            return map;
-          }
-        };
-        const index = helpers.buildNodeIndex();
-        const assigned = [];
-        const failures = [];
-        let next = Math.max(1, Number(startCounter || 1));
-        for (const entry of entries2) {
-          const matches = index.get(entry.nodeId) || [];
-          if (!matches.length) {
-            failures.push({
-              nodeId: entry.nodeId,
-              reason: "missing"
-            });
-            continue;
-          }
-          if (matches.length !== 1) {
-            failures.push({
-              nodeId: entry.nodeId,
-              reason: "ambiguous"
-            });
-            continue;
-          }
-          const target = matches[0];
-          if (target[instanceTokenKey] !== entry.instanceToken) {
-            failures.push({
-              nodeId: entry.nodeId,
-              reason: "instance_mismatch"
-            });
-            continue;
-          }
-          const owned = target[counterOwnerKey] === true;
-          const runtimeCounter = Number(target[counterValueKey] || 0);
-          if (owned && Number.isFinite(runtimeCounter) && runtimeCounter > 0) {
-            target.setAttribute("c", String(runtimeCounter));
-            assigned.push({
-              nodeId: entry.nodeId,
-              counter: runtimeCounter
-            });
-            continue;
-          }
-          const counter = next++;
-          target.setAttribute("c", String(counter));
-          Object.defineProperty(target, counterOwnerKey, {
-            value: true,
-            writable: true,
-            configurable: true
-          });
-          Object.defineProperty(target, counterValueKey, {
-            value: counter,
-            writable: true,
-            configurable: true
-          });
-          assigned.push({ nodeId: entry.nodeId, counter });
-        }
-        return {
-          assigned,
-          failures,
-          nextCounter: next
-        };
-      },
-      {
-        entries,
-        nodeAttr: OS_NODE_ID_ATTR,
-        instanceTokenKey: OS_INSTANCE_TOKEN_KEY,
-        counterOwnerKey: OS_COUNTER_OWNER_KEY,
-        counterValueKey: OS_COUNTER_VALUE_KEY,
-        startCounter: nextCounter
-      }
-    );
-    if (result.failures.length) {
-      const first = result.failures[0];
-      throw buildCounterFailureError(first.nodeId, first.reason);
-    }
-    nextCounter = result.nextCounter;
-    for (const item of result.assigned) {
-      const existingNode = usedCounters.get(item.counter);
-      if (existingNode && existingNode !== item.nodeId) {
-        throw new CounterResolutionError(
-          "ERR_COUNTER_AMBIGUOUS",
-          `Counter ${item.counter} is assigned to multiple nodes (${existingNode}, ${item.nodeId}). Run snapshot() again.`
-        );
-      }
-      usedCounters.set(item.counter, item.nodeId);
-      out.set(item.nodeId, item.counter);
-    }
-  }
-  await writeGlobalNextCounter(page, nextCounter);
-  return out;
-}
-async function resolveCounterElement(page, snapshot, counter) {
-  const binding = readBinding(snapshot, counter);
-  const framesByToken = await mapFramesByToken(page);
-  const frame = framesByToken.get(binding.frameToken);
-  if (!frame) {
-    throw new CounterResolutionError(
-      "ERR_COUNTER_FRAME_UNAVAILABLE",
-      `Counter ${counter} frame is unavailable. Run snapshot() again.`
-    );
-  }
-  const status = await frame.evaluate(
-    ({
-      nodeId,
-      instanceToken,
-      counter: counter2,
-      nodeAttr,
-      instanceTokenKey,
-      counterOwnerKey,
-      counterValueKey
-    }) => {
-      const helpers = {
-        walk(map, root) {
-          const children = Array.from(root.children);
-          for (const child of children) {
-            const id = child.getAttribute(nodeAttr);
-            if (id) {
-              const list = map.get(id) || [];
-              list.push(child);
-              map.set(id, list);
-            }
-            helpers.walk(map, child);
-            if (child.shadowRoot) {
-              helpers.walk(map, child.shadowRoot);
-            }
-          }
-        },
-        buildNodeIndex() {
-          const map = /* @__PURE__ */ new Map();
-          helpers.walk(map, document);
-          return map;
-        }
-      };
-      const matches = helpers.buildNodeIndex().get(nodeId) || [];
-      if (!matches.length) return "missing";
-      if (matches.length !== 1) return "ambiguous";
-      const target = matches[0];
-      if (target[instanceTokenKey] !== instanceToken) {
-        return "instance_mismatch";
-      }
-      if (target[counterOwnerKey] !== true) {
-        return "instance_mismatch";
-      }
-      if (Number(target[counterValueKey] || 0) !== counter2) {
-        return "instance_mismatch";
-      }
-      if (target.getAttribute("c") !== String(counter2)) {
-        return "instance_mismatch";
-      }
-      return "ok";
-    },
-    {
-      nodeId: binding.nodeId,
-      instanceToken: binding.instanceToken,
-      counter,
-      nodeAttr: OS_NODE_ID_ATTR,
-      instanceTokenKey: OS_INSTANCE_TOKEN_KEY,
-      counterOwnerKey: OS_COUNTER_OWNER_KEY,
-      counterValueKey: OS_COUNTER_VALUE_KEY
-    }
-  );
-  if (status !== "ok") {
-    throw buildCounterFailureError(binding.nodeId, status);
-  }
-  const handle = await frame.evaluateHandle(
-    ({ nodeId, nodeAttr }) => {
-      const helpers = {
-        walk(matches, root) {
-          const children = Array.from(root.children);
-          for (const child of children) {
-            if (child.getAttribute(nodeAttr) === nodeId) {
-              matches.push(child);
-            }
-            helpers.walk(matches, child);
-            if (child.shadowRoot) {
-              helpers.walk(matches, child.shadowRoot);
-            }
-          }
-        },
-        findUniqueNode() {
-          const matches = [];
-          helpers.walk(matches, document);
-          if (matches.length !== 1) return null;
-          return matches[0];
-        }
-      };
-      return helpers.findUniqueNode();
-    },
-    {
-      nodeId: binding.nodeId,
-      nodeAttr: OS_NODE_ID_ATTR
-    }
-  );
-  const element = handle.asElement();
-  if (!element) {
-    await handle.dispose();
-    throw new CounterResolutionError(
-      "ERR_COUNTER_STALE_OR_NOT_FOUND",
-      `Counter ${counter} became stale. Run snapshot() again.`
-    );
-  }
-  return element;
-}
-async function resolveCountersBatch(page, snapshot, requests) {
-  const out = {};
-  if (!requests.length) return out;
-  const grouped = /* @__PURE__ */ new Map();
-  for (const request of requests) {
-    const binding = readBinding(snapshot, request.counter);
-    const list = grouped.get(binding.frameToken) || [];
-    list.push({
-      ...request,
-      ...binding
-    });
-    grouped.set(binding.frameToken, list);
-  }
-  const framesByToken = await mapFramesByToken(page);
-  for (const [frameToken, entries] of grouped.entries()) {
-    const frame = framesByToken.get(frameToken);
-    if (!frame) {
-      throw new CounterResolutionError(
-        "ERR_COUNTER_FRAME_UNAVAILABLE",
-        `Counter frame ${frameToken} is unavailable. Run snapshot() again.`
-      );
-    }
-    const result = await frame.evaluate(
-      ({
-        entries: entries2,
-        nodeAttr,
-        instanceTokenKey,
-        counterOwnerKey,
-        counterValueKey
-      }) => {
-        const values = [];
-        const failures = [];
-        const helpers = {
-          walk(map, root) {
-            const children = Array.from(root.children);
-            for (const child of children) {
-              const id = child.getAttribute(nodeAttr);
-              if (id) {
-                const list = map.get(id) || [];
-                list.push(child);
-                map.set(id, list);
-              }
-              helpers.walk(map, child);
-              if (child.shadowRoot) {
-                helpers.walk(map, child.shadowRoot);
-              }
-            }
-          },
-          buildNodeIndex() {
-            const map = /* @__PURE__ */ new Map();
-            helpers.walk(map, document);
-            return map;
-          },
-          readRawValue(element, attribute) {
-            if (attribute) {
-              return element.getAttribute(attribute);
-            }
-            return element.textContent;
-          }
-        };
-        const index = helpers.buildNodeIndex();
-        for (const entry of entries2) {
-          const matches = index.get(entry.nodeId) || [];
-          if (!matches.length) {
-            failures.push({
-              nodeId: entry.nodeId,
-              reason: "missing"
-            });
-            continue;
-          }
-          if (matches.length !== 1) {
-            failures.push({
-              nodeId: entry.nodeId,
-              reason: "ambiguous"
-            });
-            continue;
-          }
-          const target = matches[0];
-          if (target[instanceTokenKey] !== entry.instanceToken || target[counterOwnerKey] !== true || Number(target[counterValueKey] || 0) !== entry.counter || target.getAttribute("c") !== String(entry.counter)) {
-            failures.push({
-              nodeId: entry.nodeId,
-              reason: "instance_mismatch"
-            });
-            continue;
-          }
-          values.push({
-            key: entry.key,
-            value: helpers.readRawValue(target, entry.attribute)
-          });
-        }
-        return {
-          values,
-          failures
-        };
-      },
-      {
-        entries,
-        nodeAttr: OS_NODE_ID_ATTR,
-        instanceTokenKey: OS_INSTANCE_TOKEN_KEY,
-        counterOwnerKey: OS_COUNTER_OWNER_KEY,
-        counterValueKey: OS_COUNTER_VALUE_KEY
-      }
-    );
-    if (result.failures.length) {
-      const first = result.failures[0];
-      throw buildCounterFailureError(first.nodeId, first.reason);
-    }
-    const attributeByKey = new Map(
-      entries.map((entry) => [entry.key, entry.attribute])
-    );
-    for (const item of result.values) {
-      out[item.key] = normalizeExtractedValue(
-        item.value,
-        attributeByKey.get(item.key)
-      );
-    }
-  }
-  return out;
 }
 async function mapFramesByToken(page) {
   const out = /* @__PURE__ */ new Map();
@@ -3321,182 +3176,6 @@ async function readFrameToken(frame) {
     return null;
   }
 }
-async function readGlobalNextCounter(page) {
-  const current = await page.mainFrame().evaluate((counterNextKey) => {
-    const win = window;
-    return Number(win[counterNextKey] || 0);
-  }, OS_COUNTER_NEXT_KEY).catch(() => 0);
-  if (Number.isFinite(current) && current > 0) {
-    return current;
-  }
-  let max = 0;
-  for (const frame of page.frames()) {
-    try {
-      const frameMax = await frame.evaluate(
-        ({ nodeAttr, counterOwnerKey, counterValueKey }) => {
-          let localMax = 0;
-          const helpers = {
-            walk(root) {
-              const children = Array.from(
-                root.children
-              );
-              for (const child of children) {
-                const candidate = child;
-                const hasNodeId = child.hasAttribute(nodeAttr);
-                const owned = candidate[counterOwnerKey] === true;
-                if (hasNodeId && owned) {
-                  const value = Number(
-                    candidate[counterValueKey] || 0
-                  );
-                  if (Number.isFinite(value) && value > localMax) {
-                    localMax = value;
-                  }
-                }
-                helpers.walk(child);
-                if (child.shadowRoot) {
-                  helpers.walk(child.shadowRoot);
-                }
-              }
-            }
-          };
-          helpers.walk(document);
-          return localMax;
-        },
-        {
-          nodeAttr: OS_NODE_ID_ATTR,
-          counterOwnerKey: OS_COUNTER_OWNER_KEY,
-          counterValueKey: OS_COUNTER_VALUE_KEY
-        }
-      );
-      if (frameMax > max) {
-        max = frameMax;
-      }
-    } catch {
-    }
-  }
-  const next = max + 1;
-  await writeGlobalNextCounter(page, next);
-  return next;
-}
-async function writeGlobalNextCounter(page, nextCounter) {
-  await page.mainFrame().evaluate(
-    ({ counterNextKey, nextCounter: nextCounter2 }) => {
-      const win = window;
-      win[counterNextKey] = nextCounter2;
-    },
-    {
-      counterNextKey: OS_COUNTER_NEXT_KEY,
-      nextCounter
-    }
-  ).catch(() => void 0);
-}
-function readBinding(snapshot, counter) {
-  if (!snapshot.counterBindings) {
-    throw new CounterResolutionError(
-      "ERR_COUNTER_NOT_FOUND",
-      `Counter ${counter} is unavailable because this snapshot has no counter bindings. Run snapshot() with counters first.`
-    );
-  }
-  const binding = snapshot.counterBindings.get(counter);
-  if (!binding) {
-    throw new CounterResolutionError(
-      "ERR_COUNTER_NOT_FOUND",
-      `Counter ${counter} was not found in the current snapshot. Run snapshot() again.`
-    );
-  }
-  if (binding.sessionId !== snapshot.snapshotSessionId) {
-    throw new CounterResolutionError(
-      "ERR_COUNTER_STALE_OR_NOT_FOUND",
-      `Counter ${counter} is stale for this snapshot session. Run snapshot() again.`
-    );
-  }
-  return binding;
-}
-function buildCounterFailureError(nodeId, reason) {
-  if (reason === "ambiguous") {
-    return new CounterResolutionError(
-      "ERR_COUNTER_AMBIGUOUS",
-      `Counter target is ambiguous for node ${nodeId}. Run snapshot() again.`
-    );
-  }
-  return new CounterResolutionError(
-    "ERR_COUNTER_STALE_OR_NOT_FOUND",
-    `Counter target is stale or missing for node ${nodeId}. Run snapshot() again.`
-  );
-}
-
-// src/html/pipeline.ts
-import * as cheerio3 from "cheerio";
-import { randomUUID } from "crypto";
-function applyCleaner(mode, html) {
-  switch (mode) {
-    case "clickable":
-      return cleanForClickable(html);
-    case "scrollable":
-      return cleanForScrollable(html);
-    case "extraction":
-      return cleanForExtraction(html);
-    case "full":
-      return cleanForFull(html);
-    case "action":
-    default:
-      return cleanForAction(html);
-  }
-}
-async function assignCounters(page, html, nodePaths, nodeMeta, snapshotSessionId) {
-  const $ = cheerio3.load(html, { xmlMode: false });
-  const counterIndex = /* @__PURE__ */ new Map();
-  const counterBindings = /* @__PURE__ */ new Map();
-  const orderedNodeIds = [];
-  $("*").each(function() {
-    const el = $(this);
-    const nodeId = el.attr(OS_NODE_ID_ATTR);
-    if (!nodeId) return;
-    orderedNodeIds.push(nodeId);
-  });
-  const countersByNodeId = await ensureLiveCounters(
-    page,
-    nodeMeta,
-    orderedNodeIds
-  );
-  $("*").each(function() {
-    const el = $(this);
-    const nodeId = el.attr(OS_NODE_ID_ATTR);
-    if (!nodeId) return;
-    const path5 = nodePaths.get(nodeId);
-    const meta = nodeMeta.get(nodeId);
-    const counter = countersByNodeId.get(nodeId);
-    if (counter == null || !Number.isFinite(counter)) {
-      throw new Error(
-        `Counter assignment failed for node ${nodeId}. Run snapshot() again.`
-      );
-    }
-    if (counterBindings.has(counter) && counterBindings.get(counter)?.nodeId !== nodeId) {
-      throw new Error(
-        `Counter ${counter} was assigned to multiple nodes. Run snapshot() again.`
-      );
-    }
-    el.attr("c", String(counter));
-    el.removeAttr(OS_NODE_ID_ATTR);
-    if (path5) {
-      counterIndex.set(counter, cloneElementPath(path5));
-    }
-    if (meta) {
-      counterBindings.set(counter, {
-        sessionId: snapshotSessionId,
-        frameToken: meta.frameToken,
-        nodeId,
-        instanceToken: meta.instanceToken
-      });
-    }
-  });
-  $(`[${OS_NODE_ID_ATTR}]`).removeAttr(OS_NODE_ID_ATTR);
-  return {
-    html: $.html(),
-    counterIndex,
-    counterBindings
-  };
-}
 function stripNodeIds(html) {
   if (!html.includes(OS_NODE_ID_ATTR)) return html;
   const $ = cheerio3.load(html, { xmlMode: false });
@@ -3504,7 +3183,6 @@ function stripNodeIds(html) {
   return $.html();
 }
 async function prepareSnapshot(page, options = {}) {
-  const snapshotSessionId = randomUUID();
   const mode = options.mode ?? "action";
   const withCounters = options.withCounters ?? true;
   const shouldMarkInteractive = options.markInteractive ?? true;
@@ -3517,18 +3195,15 @@ async function prepareSnapshot(page, options = {}) {
   const reducedHtml = applyCleaner(mode, processedHtml);
   let cleanedHtml = reducedHtml;
   let counterIndex = null;
-  let counterBindings = null;
   if (withCounters) {
     const counted = await assignCounters(
       page,
       reducedHtml,
       serialized.nodePaths,
-      serialized.nodeMeta,
-      snapshotSessionId
+      serialized.nodeMeta
     );
     cleanedHtml = counted.html;
     counterIndex = counted.counterIndex;
-    counterBindings = counted.counterBindings;
   } else {
     cleanedHtml = stripNodeIds(cleanedHtml);
   }
@@ -3537,15 +3212,13 @@ async function prepareSnapshot(page, options = {}) {
     cleanedHtml = $unwrap("body").html()?.trim() || cleanedHtml;
   }
   return {
-    snapshotSessionId,
     mode,
     url: page.url(),
     rawHtml,
     processedHtml,
     reducedHtml,
     cleanedHtml,
-    counterIndex,
-    counterBindings
+    counterIndex
   };
 }
 
@@ -3674,13 +3347,41 @@ function buildTargetNotFoundMessage(domPath, diagnostics) {
     return `${base} Tried ${Math.max(diagnostics.length, 0)} candidates.`;
   return `${base} Target depth ${depth}. Candidate counts: ${sample}.`;
 }
-function selectInDocument(selectors) {
+function selectInDocument(selectors) {
+  let fallback = null;
+  for (const selector of selectors) {
+    if (!selector) continue;
+    let count = 0;
+    try {
+      count = document.querySelectorAll(selector).length;
+    } catch {
+      count = 0;
+    }
+    if (count === 1) {
+      return {
+        selector,
+        count,
+        mode: "unique"
+      };
+    }
+    if (count > 1 && !fallback) {
+      fallback = {
+        selector,
+        count,
+        mode: "fallback"
+      };
+    }
+  }
+  return fallback;
+}
+function selectInRoot(root, selectors) {
+  if (!(root instanceof ShadowRoot)) return null;
   let fallback = null;
   for (const selector of selectors) {
     if (!selector) continue;
     let count = 0;
     try {
-      count = document.querySelectorAll(selector).length;
+      count = root.querySelectorAll(selector).length;
     } catch {
       count = 0;
     }
@@ -3701,9 +3402,23 @@ function selectInDocument(selectors) {
   }
   return fallback;
 }
-function selectInRoot(root, selectors) {
-  if (!(root instanceof ShadowRoot)) return null;
-  let fallback = null;
+function countInDocument(selectors) {
+  const out = [];
+  for (const selector of selectors) {
+    if (!selector) continue;
+    let count = 0;
+    try {
+      count = document.querySelectorAll(selector).length;
+    } catch {
+      count = 0;
+    }
+    out.push({ selector, count });
+  }
+  return out;
+}
+function countInRoot(root, selectors) {
+  if (!(root instanceof ShadowRoot)) return [];
+  const out = [];
   for (const selector of selectors) {
     if (!selector) continue;
     let count = 0;
@@ -3712,73 +3427,432 @@ function selectInRoot(root, selectors) {
     } catch {
       count = 0;
     }
-    if (count === 1) {
-      return {
-        selector,
-        count,
-        mode: "unique"
-      };
+    out.push({ selector, count });
+  }
+  return out;
+}
+function isPathDebugEnabled() {
+  const value = process.env.OPENSTEER_DEBUG_PATH || process.env.OPENSTEER_DEBUG || process.env.DEBUG_SELECTORS;
+  if (!value) return false;
+  const normalized = value.trim().toLowerCase();
+  return normalized === "1" || normalized === "true";
+}
+function debugPath(message, data) {
+  if (!isPathDebugEnabled()) return;
+  if (data !== void 0) {
+    console.log(`[opensteer:path] ${message}`, data);
+  } else {
+    console.log(`[opensteer:path] ${message}`);
+  }
+}
+async function disposeHandle(handle) {
+  if (!handle) return;
+  try {
+    await handle.dispose();
+  } catch {
+  }
+}
+
+// src/extract-value-normalization.ts
+var URL_LIST_ATTRIBUTES = /* @__PURE__ */ new Set(["srcset", "imagesrcset", "ping"]);
+function normalizeExtractedValue(raw, attribute) {
+  if (raw == null) return null;
+  const rawText = String(raw);
+  if (!rawText.trim()) return null;
+  const normalizedAttribute = String(attribute || "").trim().toLowerCase();
+  if (URL_LIST_ATTRIBUTES.has(normalizedAttribute)) {
+    const singleValue = pickSingleListAttributeValue(
+      normalizedAttribute,
+      rawText
+    ).trim();
+    return singleValue || null;
+  }
+  const text = rawText.replace(/\s+/g, " ").trim();
+  return text || null;
+}
+function pickSingleListAttributeValue(attribute, raw) {
+  if (attribute === "ping") {
+    const firstUrl = raw.trim().split(/\s+/)[0] || "";
+    return firstUrl.trim();
+  }
+  if (attribute === "srcset" || attribute === "imagesrcset") {
+    const picked = pickBestSrcsetCandidate(raw);
+    if (picked) return picked;
+    return pickFirstSrcsetToken(raw) || "";
+  }
+  return raw.trim();
+}
+function pickBestSrcsetCandidate(raw) {
+  const candidates = parseSrcsetCandidates(raw);
+  if (!candidates.length) return null;
+  const widthCandidates = candidates.filter(
+    (candidate) => typeof candidate.width === "number" && Number.isFinite(candidate.width) && candidate.width > 0
+  );
+  if (widthCandidates.length) {
+    return widthCandidates.reduce(
+      (best, candidate) => candidate.width > best.width ? candidate : best
+    ).url;
+  }
+  const densityCandidates = candidates.filter(
+    (candidate) => typeof candidate.density === "number" && Number.isFinite(candidate.density) && candidate.density > 0
+  );
+  if (densityCandidates.length) {
+    return densityCandidates.reduce(
+      (best, candidate) => candidate.density > best.density ? candidate : best
+    ).url;
+  }
+  return candidates[0]?.url || null;
+}
+function parseSrcsetCandidates(raw) {
+  const text = String(raw || "").trim();
+  if (!text) return [];
+  const out = [];
+  let index = 0;
+  while (index < text.length) {
+    index = skipSeparators(text, index);
+    if (index >= text.length) break;
+    const urlToken = readUrlToken(text, index);
+    index = urlToken.nextIndex;
+    const url = urlToken.value.trim();
+    if (!url) continue;
+    index = skipWhitespace(text, index);
+    const descriptors = [];
+    while (index < text.length && text[index] !== ",") {
+      const descriptorToken = readDescriptorToken(text, index);
+      if (!descriptorToken.value) {
+        index = descriptorToken.nextIndex;
+        continue;
+      }
+      descriptors.push(descriptorToken.value);
+      index = descriptorToken.nextIndex;
+      index = skipWhitespace(text, index);
+    }
+    if (index < text.length && text[index] === ",") {
+      index += 1;
+    }
+    let width = null;
+    let density = null;
+    for (const descriptor of descriptors) {
+      const token = descriptor.trim().toLowerCase();
+      if (!token) continue;
+      const widthMatch = token.match(/^(\d+)w$/);
+      if (widthMatch) {
+        const parsed = Number.parseInt(widthMatch[1], 10);
+        if (Number.isFinite(parsed)) {
+          width = parsed;
+        }
+        continue;
+      }
+      const densityMatch = token.match(/^(\d*\.?\d+)x$/);
+      if (densityMatch) {
+        const parsed = Number.parseFloat(densityMatch[1]);
+        if (Number.isFinite(parsed)) {
+          density = parsed;
+        }
+      }
+    }
+    out.push({
+      url,
+      width,
+      density
+    });
+  }
+  return out;
+}
+function pickFirstSrcsetToken(raw) {
+  const candidate = parseSrcsetCandidates(raw)[0];
+  if (candidate?.url) {
+    return candidate.url;
+  }
+  const text = String(raw || "");
+  const start = skipSeparators(text, 0);
+  if (start >= text.length) return null;
+  const firstToken = readUrlToken(text, start).value.trim();
+  return firstToken || null;
+}
+function skipWhitespace(value, index) {
+  let cursor = index;
+  while (cursor < value.length && /\s/.test(value[cursor])) {
+    cursor += 1;
+  }
+  return cursor;
+}
+function skipSeparators(value, index) {
+  let cursor = skipWhitespace(value, index);
+  while (cursor < value.length && value[cursor] === ",") {
+    cursor += 1;
+    cursor = skipWhitespace(value, cursor);
+  }
+  return cursor;
+}
+function readUrlToken(value, index) {
+  let cursor = index;
+  let out = "";
+  const isDataUrl = value.slice(index, index + 5).toLowerCase().startsWith("data:");
+  while (cursor < value.length) {
+    const char = value[cursor];
+    if (/\s/.test(char)) {
+      break;
+    }
+    if (char === "," && !isDataUrl) {
+      break;
+    }
+    out += char;
+    cursor += 1;
+  }
+  if (isDataUrl && out.endsWith(",") && cursor < value.length) {
+    out = out.slice(0, -1);
+  }
+  return {
+    value: out,
+    nextIndex: cursor
+  };
+}
+function readDescriptorToken(value, index) {
+  let cursor = skipWhitespace(value, index);
+  let out = "";
+  while (cursor < value.length) {
+    const char = value[cursor];
+    if (char === "," || /\s/.test(char)) {
+      break;
+    }
+    out += char;
+    cursor += 1;
+  }
+  return {
+    value: out.trim(),
+    nextIndex: cursor
+  };
+}
+
+// src/html/counter-runtime.ts
+var CounterResolutionError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "CounterResolutionError";
+    this.code = code;
+  }
+};
+async function resolveCounterElement(page, counter) {
+  const normalized = normalizeCounter(counter);
+  if (normalized == null) {
+    throw buildCounterNotFoundError(counter);
+  }
+  const scan = await scanCounterOccurrences(page, [normalized]);
+  const entry = scan.get(normalized);
+  if (!entry || entry.count <= 0 || !entry.frame) {
+    throw buildCounterNotFoundError(counter);
+  }
+  if (entry.count > 1) {
+    throw buildCounterAmbiguousError(counter);
+  }
+  const handle = await resolveUniqueHandleInFrame(entry.frame, normalized);
+  const element = handle.asElement();
+  if (!element) {
+    await handle.dispose();
+    throw buildCounterNotFoundError(counter);
+  }
+  return element;
+}
+async function resolveCountersBatch(page, requests) {
+  const out = {};
+  if (!requests.length) return out;
+  const counters = dedupeCounters(requests);
+  const scan = await scanCounterOccurrences(page, counters);
+  for (const counter of counters) {
+    const entry = scan.get(counter);
+    if (entry.count > 1) {
+      throw buildCounterAmbiguousError(counter);
+    }
+  }
+  const valueCache = /* @__PURE__ */ new Map();
+  for (const request of requests) {
+    const normalized = normalizeCounter(request.counter);
+    if (normalized == null) {
+      out[request.key] = null;
+      continue;
+    }
+    const entry = scan.get(normalized);
+    if (!entry || entry.count <= 0 || !entry.frame) {
+      out[request.key] = null;
+      continue;
     }
-    if (count > 1 && !fallback) {
-      fallback = {
-        selector,
-        count,
-        mode: "fallback"
-      };
+    const cacheKey = `${normalized}:${request.attribute || ""}`;
+    if (valueCache.has(cacheKey)) {
+      out[request.key] = valueCache.get(cacheKey);
+      continue;
+    }
+    const read = await readCounterValueInFrame(
+      entry.frame,
+      normalized,
+      request.attribute
+    );
+    if (read.status === "ambiguous") {
+      throw buildCounterAmbiguousError(normalized);
+    }
+    if (read.status === "missing") {
+      valueCache.set(cacheKey, null);
+      out[request.key] = null;
+      continue;
     }
+    const normalizedValue = normalizeExtractedValue(
+      read.value ?? null,
+      request.attribute
+    );
+    valueCache.set(cacheKey, normalizedValue);
+    out[request.key] = normalizedValue;
   }
-  return fallback;
+  return out;
 }
-function countInDocument(selectors) {
+function dedupeCounters(requests) {
+  const seen = /* @__PURE__ */ new Set();
   const out = [];
-  for (const selector of selectors) {
-    if (!selector) continue;
-    let count = 0;
-    try {
-      count = document.querySelectorAll(selector).length;
-    } catch {
-      count = 0;
-    }
-    out.push({ selector, count });
+  for (const request of requests) {
+    const normalized = normalizeCounter(request.counter);
+    if (normalized == null || seen.has(normalized)) continue;
+    seen.add(normalized);
+    out.push(normalized);
   }
   return out;
 }
-function countInRoot(root, selectors) {
-  if (!(root instanceof ShadowRoot)) return [];
-  const out = [];
-  for (const selector of selectors) {
-    if (!selector) continue;
-    let count = 0;
+function normalizeCounter(counter) {
+  if (!Number.isFinite(counter)) return null;
+  if (!Number.isInteger(counter)) return null;
+  if (counter <= 0) return null;
+  return counter;
+}
+async function scanCounterOccurrences(page, counters) {
+  const out = /* @__PURE__ */ new Map();
+  for (const counter of counters) {
+    out.set(counter, {
+      count: 0,
+      frame: null
+    });
+  }
+  if (!counters.length) return out;
+  for (const frame of page.frames()) {
+    let frameCounts;
     try {
-      count = root.querySelectorAll(selector).length;
+      frameCounts = await frame.evaluate((candidates) => {
+        const keys = new Set(candidates.map((value) => String(value)));
+        const counts = {};
+        for (const key of keys) {
+          counts[key] = 0;
+        }
+        const walk = (root) => {
+          const children = Array.from(root.children);
+          for (const child of children) {
+            const value = child.getAttribute("c");
+            if (value && keys.has(value)) {
+              counts[value] = (counts[value] || 0) + 1;
+            }
+            walk(child);
+            if (child.shadowRoot) {
+              walk(child.shadowRoot);
+            }
+          }
+        };
+        walk(document);
+        return counts;
+      }, counters);
     } catch {
-      count = 0;
+      continue;
+    }
+    for (const [rawCounter, rawCount] of Object.entries(frameCounts)) {
+      const counter = Number.parseInt(rawCounter, 10);
+      if (!Number.isFinite(counter)) continue;
+      const count = Number(rawCount || 0);
+      if (!Number.isFinite(count) || count <= 0) continue;
+      const entry = out.get(counter);
+      entry.count += count;
+      if (!entry.frame) {
+        entry.frame = frame;
+      }
     }
-    out.push({ selector, count });
   }
   return out;
 }
-function isPathDebugEnabled() {
-  const value = process.env.OPENSTEER_DEBUG_PATH || process.env.OPENSTEER_DEBUG || process.env.DEBUG_SELECTORS;
-  if (!value) return false;
-  const normalized = value.trim().toLowerCase();
-  return normalized === "1" || normalized === "true";
-}
-function debugPath(message, data) {
-  if (!isPathDebugEnabled()) return;
-  if (data !== void 0) {
-    console.log(`[opensteer:path] ${message}`, data);
-  } else {
-    console.log(`[opensteer:path] ${message}`);
-  }
+async function resolveUniqueHandleInFrame(frame, counter) {
+  return frame.evaluateHandle((targetCounter) => {
+    const matches = [];
+    const walk = (root) => {
+      const children = Array.from(root.children);
+      for (const child of children) {
+        if (child.getAttribute("c") === targetCounter) {
+          matches.push(child);
+        }
+        walk(child);
+        if (child.shadowRoot) {
+          walk(child.shadowRoot);
+        }
+      }
+    };
+    walk(document);
+    if (matches.length !== 1) {
+      return null;
+    }
+    return matches[0];
+  }, String(counter));
 }
-async function disposeHandle(handle) {
-  if (!handle) return;
+async function readCounterValueInFrame(frame, counter, attribute) {
   try {
-    await handle.dispose();
+    return await frame.evaluate(
+      ({ targetCounter, attribute: attribute2 }) => {
+        const matches = [];
+        const walk = (root) => {
+          const children = Array.from(root.children);
+          for (const child of children) {
+            if (child.getAttribute("c") === targetCounter) {
+              matches.push(child);
+            }
+            walk(child);
+            if (child.shadowRoot) {
+              walk(child.shadowRoot);
+            }
+          }
+        };
+        walk(document);
+        if (!matches.length) {
+          return {
+            status: "missing"
+          };
+        }
+        if (matches.length > 1) {
+          return {
+            status: "ambiguous"
+          };
+        }
+        const target = matches[0];
+        const value = attribute2 ? target.getAttribute(attribute2) : target.textContent;
+        return {
+          status: "ok",
+          value
+        };
+      },
+      {
+        targetCounter: String(counter),
+        attribute
+      }
+    );
   } catch {
+    return {
+      status: "missing"
+    };
   }
 }
+function buildCounterNotFoundError(counter) {
+  return new CounterResolutionError(
+    "ERR_COUNTER_NOT_FOUND",
+    `Counter ${counter} was not found in the live DOM.`
+  );
+}
+function buildCounterAmbiguousError(counter) {
+  return new CounterResolutionError(
+    "ERR_COUNTER_AMBIGUOUS",
+    `Counter ${counter} matches multiple live elements.`
+  );
+}
 
 // src/actions/actionability-probe.ts
 async function probeActionabilityState(element) {
@@ -3906,7 +3980,7 @@ function defaultActionFailureMessage(action) {
 function classifyActionFailure(input) {
   const typed = classifyTypedError(input.error);
   if (typed) return typed;
-  const message = extractErrorMessage(input.error, input.fallbackMessage);
+  const message = extractErrorMessage2(input.error, input.fallbackMessage);
   const fromCallLog = classifyFromPlaywrightMessage(message, input.probe);
   if (fromCallLog) return fromCallLog;
   const fromProbe = classifyFromProbe(input.probe);
@@ -3915,7 +3989,7 @@ function classifyActionFailure(input) {
   if (fromHeuristic) return fromHeuristic;
   return buildFailure({
     code: "UNKNOWN",
-    message: ensureMessage(input.fallbackMessage, "Action failed."),
+    message: ensureMessage(message, input.fallbackMessage),
     classificationSource: "unknown"
   });
 }
@@ -3971,13 +4045,6 @@ function classifyTypedError(error) {
         classificationSource: "typed_error"
       });
     }
-    if (error.code === "ERR_COUNTER_FRAME_UNAVAILABLE") {
-      return buildFailure({
-        code: "TARGET_UNAVAILABLE",
-        message: error.message,
-        classificationSource: "typed_error"
-      });
-    }
     if (error.code === "ERR_COUNTER_AMBIGUOUS") {
       return buildFailure({
         code: "TARGET_AMBIGUOUS",
@@ -3985,13 +4052,6 @@ function classifyTypedError(error) {
         classificationSource: "typed_error"
       });
     }
-    if (error.code === "ERR_COUNTER_STALE_OR_NOT_FOUND") {
-      return buildFailure({
-        code: "TARGET_STALE",
-        message: error.message,
-        classificationSource: "typed_error"
-      });
-    }
   }
   return null;
 }
@@ -4175,13 +4235,22 @@ function defaultRetryableForCode(code) {
       return true;
   }
 }
-function extractErrorMessage(error, fallbackMessage) {
+function extractErrorMessage2(error, fallbackMessage) {
   if (error instanceof Error && error.message.trim()) {
     return error.message;
   }
   if (typeof error === "string" && error.trim()) {
     return error.trim();
   }
+  if (error && typeof error === "object" && !Array.isArray(error)) {
+    const record = error;
+    if (typeof record.message === "string" && record.message.trim()) {
+      return record.message.trim();
+    }
+    if (typeof record.error === "string" && record.error.trim()) {
+      return record.error.trim();
+    }
+  }
   return ensureMessage(fallbackMessage, "Action failed.");
 }
 function ensureMessage(value, fallback) {
@@ -5140,7 +5209,8 @@ function withTokenQuery(wsUrl, token) {
 // src/cloud/local-cache-sync.ts
 import fs2 from "fs";
 import path3 from "path";
-function collectLocalSelectorCacheEntries(storage) {
+function collectLocalSelectorCacheEntries(storage, options = {}) {
+  const debug = options.debug === true;
   const namespace = storage.getNamespace();
   const namespaceDir = storage.getNamespaceDir();
   if (!fs2.existsSync(namespaceDir)) return [];
@@ -5149,7 +5219,7 @@ function collectLocalSelectorCacheEntries(storage) {
   for (const fileName of fileNames) {
     if (fileName === "index.json" || !fileName.endsWith(".json")) continue;
     const filePath = path3.join(namespaceDir, fileName);
-    const selector = readSelectorFile(filePath);
+    const selector = readSelectorFile(filePath, debug);
     if (!selector) continue;
     const descriptionHash = normalizeDescriptionHash(selector.id);
     const method = normalizeMethod(selector.method);
@@ -5174,11 +5244,20 @@ function collectLocalSelectorCacheEntries(storage) {
   }
   return dedupeNewest(entries);
 }
-function readSelectorFile(filePath) {
+function readSelectorFile(filePath, debug) {
   try {
     const raw = fs2.readFileSync(filePath, "utf8");
     return JSON.parse(raw);
-  } catch {
+  } catch (error) {
+    const message = extractErrorMessage(
+      error,
+      "Unable to parse selector cache file JSON."
+    );
+    if (debug) {
+      console.warn(
+        `[opensteer] failed to read local selector cache file "${filePath}": ${message}`
+      );
+    }
     return null;
   }
 }
@@ -7323,7 +7402,7 @@ function sleep3(ms) {
 }
 
 // src/opensteer.ts
-import { createHash, randomUUID as randomUUID2 } from "crypto";
+import { createHash, randomUUID } from "crypto";
 
 // src/browser/pool.ts
 import {
@@ -7824,11 +7903,12 @@ function dotenvFileOrder(nodeEnv) {
   files.push(".env");
   return files;
 }
-function loadDotenvValues(rootDir, baseEnv) {
+function loadDotenvValues(rootDir, baseEnv, options = {}) {
   const values = {};
   if (parseBool(baseEnv.OPENSTEER_DISABLE_DOTENV_AUTOLOAD) === true) {
     return values;
   }
+  const debug = options.debug ?? parseBool(baseEnv.OPENSTEER_DEBUG) === true;
   const baseDir = path4.resolve(rootDir);
   const nodeEnv = baseEnv.NODE_ENV?.trim() || "";
   for (const filename of dotenvFileOrder(nodeEnv)) {
@@ -7842,15 +7922,24 @@ function loadDotenvValues(rootDir, baseEnv) {
           values[key] = value;
         }
       }
-    } catch {
+    } catch (error) {
+      const message = extractErrorMessage(
+        error,
+        "Unable to read or parse dotenv file."
+      );
+      if (debug) {
+        console.warn(
+          `[opensteer] failed to load dotenv file "${filePath}": ${message}`
+        );
+      }
       continue;
     }
   }
   return values;
 }
-function resolveEnv(rootDir) {
+function resolveEnv(rootDir, options = {}) {
   const baseEnv = process.env;
-  const dotenvValues = loadDotenvValues(rootDir, baseEnv);
+  const dotenvValues = loadDotenvValues(rootDir, baseEnv, options);
   return {
     ...dotenvValues,
     ...baseEnv
@@ -7894,13 +7983,22 @@ function assertNoLegacyRuntimeConfig(source, config) {
     );
   }
 }
-function loadConfigFile(rootDir) {
+function loadConfigFile(rootDir, options = {}) {
   const configPath = path4.join(rootDir, ".opensteer", "config.json");
   if (!fs3.existsSync(configPath)) return {};
   try {
     const raw = fs3.readFileSync(configPath, "utf8");
     return JSON.parse(raw);
-  } catch {
+  } catch (error) {
+    const message = extractErrorMessage(
+      error,
+      "Unable to read or parse config file."
+    );
+    if (options.debug) {
+      console.warn(
+        `[opensteer] failed to load config file "${configPath}": ${message}`
+      );
+    }
     return {};
   }
 }
@@ -8032,6 +8130,8 @@ function resolveCloudSelection(config, env = process.env) {
   };
 }
 function resolveConfig(input = {}) {
+  const processEnv = process.env;
+  const debugHint = typeof input.debug === "boolean" ? input.debug : parseBool(processEnv.OPENSTEER_DEBUG) === true;
   const initialRootDir = input.storage?.rootDir ?? process.cwd();
   const runtimeDefaults = mergeDeep(DEFAULT_CONFIG, {
     storage: {
@@ -8040,12 +8140,16 @@ function resolveConfig(input = {}) {
   });
   assertNoLegacyAiConfig("Opensteer constructor config", input);
   assertNoLegacyRuntimeConfig("Opensteer constructor config", input);
-  const fileConfig = loadConfigFile(initialRootDir);
+  const fileConfig = loadConfigFile(initialRootDir, {
+    debug: debugHint
+  });
   assertNoLegacyAiConfig(".opensteer/config.json", fileConfig);
   assertNoLegacyRuntimeConfig(".opensteer/config.json", fileConfig);
   const fileRootDir = typeof fileConfig.storage?.rootDir === "string" ? fileConfig.storage.rootDir : void 0;
   const envRootDir = input.storage?.rootDir ?? fileRootDir ?? initialRootDir;
-  const env = resolveEnv(envRootDir);
+  const env = resolveEnv(envRootDir, {
+    debug: debugHint
+  });
   if (env.OPENSTEER_AI_MODEL) {
     throw new Error(
       "OPENSTEER_AI_MODEL is no longer supported. Use OPENSTEER_MODEL instead."
@@ -9579,7 +9683,9 @@ var Opensteer = class _Opensteer {
     this.aiExtract = this.createLazyExtractCallback(model);
     const rootDir = resolved.storage?.rootDir || process.cwd();
     this.namespace = resolveNamespace(resolved, rootDir);
-    this.storage = new LocalSelectorStorage(rootDir, this.namespace);
+    this.storage = new LocalSelectorStorage(rootDir, this.namespace, {
+      debug: Boolean(resolved.debug)
+    });
     this.pool = new BrowserPool(resolved.browser || {});
     if (cloudSelection.cloud) {
       const cloudConfig = resolved.cloud && typeof resolved.cloud === "object" ? resolved.cloud : void 0;
@@ -9598,12 +9704,20 @@ var Opensteer = class _Opensteer {
       this.cloud = null;
     }
   }
+  logDebugError(context, error) {
+    if (!this.config.debug) return;
+    const normalized = normalizeError(error, "Unknown error.");
+    const codeSuffix = normalized.code && normalized.code.trim() ? ` [${normalized.code.trim()}]` : "";
+    console.warn(
+      `[opensteer] ${context}: ${normalized.message}${codeSuffix}`
+    );
+  }
   createLazyResolveCallback(model) {
     let resolverPromise = null;
     return async (...args) => {
       try {
         if (!resolverPromise) {
-          resolverPromise = import("./resolver-HVZJQZ32.js").then(
+          resolverPromise = import("./resolver-ZREUOOTV.js").then(
             (m) => m.createResolveCallback(model)
           );
         }
@@ -9620,7 +9734,7 @@ var Opensteer = class _Opensteer {
     const extract = async (args) => {
       try {
         if (!extractorPromise) {
-          extractorPromise = import("./extractor-I6TJPTXV.js").then(
+          extractorPromise = import("./extractor-CZFCFUME.js").then(
             (m) => m.createExtractCallback(model)
           );
         }
@@ -9688,7 +9802,8 @@ var Opensteer = class _Opensteer {
     let tabs;
     try {
       tabs = await this.invokeCloudAction("tabs", {});
-    } catch {
+    } catch (error) {
+      this.logDebugError("cloud page reference sync (tabs lookup) failed", error);
       return;
     }
     if (!tabs.length) {
@@ -9826,12 +9941,7 @@ var Opensteer = class _Opensteer {
         try {
           await this.syncLocalSelectorCacheToCloud();
         } catch (error) {
-          if (this.config.debug) {
-            const message = error instanceof Error ? error.message : String(error);
-            console.warn(
-              `[opensteer] cloud selector cache sync failed: ${message}`
-            );
-          }
+          this.logDebugError("cloud selector cache sync failed", error);
         }
         localRunId = this.cloud.localRunId || buildLocalRunId(this.namespace);
         this.cloud.localRunId = localRunId;
@@ -9863,7 +9973,12 @@ var Opensteer = class _Opensteer {
         this.cloud.actionClient = actionClient;
         this.cloud.sessionId = sessionId;
         this.cloud.cloudSessionUrl = session2.cloudSessionUrl;
-        await this.syncCloudPageRef().catch(() => void 0);
+        await this.syncCloudPageRef().catch((error) => {
+          this.logDebugError(
+            "cloud page reference sync after launch failed",
+            error
+          );
+        });
         this.announceCloudSession({
           sessionId: session2.sessionId,
           workspaceId: session2.cloudSession.workspaceId,
@@ -9950,7 +10065,9 @@ var Opensteer = class _Opensteer {
   }
   async syncLocalSelectorCacheToCloud() {
     if (!this.cloud) return;
-    const entries = collectLocalSelectorCacheEntries(this.storage);
+    const entries = collectLocalSelectorCacheEntries(this.storage, {
+      debug: Boolean(this.config.debug)
+    });
     if (!entries.length) return;
     await this.cloud.sessionClient.importSelectorCache({
       entries
@@ -9959,9 +10076,12 @@ var Opensteer = class _Opensteer {
   async goto(url, options) {
     if (this.cloud) {
       await this.invokeCloudActionAndResetCache("goto", { url, options });
-      await this.syncCloudPageRef({ expectedUrl: url }).catch(
-        () => void 0
-      );
+      await this.syncCloudPageRef({ expectedUrl: url }).catch((error) => {
+        this.logDebugError(
+          "cloud page reference sync after goto failed",
+          error
+        );
+      });
       return;
     }
     const { waitUntil = "domcontentloaded", ...rest } = options ?? {};
@@ -10062,7 +10182,7 @@ var Opensteer = class _Opensteer {
       let persistPath = null;
       try {
         if (storageKey && resolution.shouldPersist) {
-          persistPath = await this.buildPathFromResolvedHandle(
+          persistPath = await this.tryBuildPathFromResolvedHandle(
             handle,
             "hover",
             resolution.counter
@@ -10161,7 +10281,7 @@ var Opensteer = class _Opensteer {
       let persistPath = null;
       try {
         if (storageKey && resolution.shouldPersist) {
-          persistPath = await this.buildPathFromResolvedHandle(
+          persistPath = await this.tryBuildPathFromResolvedHandle(
             handle,
             "input",
             resolution.counter
@@ -10264,7 +10384,7 @@ var Opensteer = class _Opensteer {
       let persistPath = null;
       try {
         if (storageKey && resolution.shouldPersist) {
-          persistPath = await this.buildPathFromResolvedHandle(
+          persistPath = await this.tryBuildPathFromResolvedHandle(
             handle,
             "select",
             resolution.counter
@@ -10374,7 +10494,7 @@ var Opensteer = class _Opensteer {
       let persistPath = null;
       try {
         if (storageKey && resolution.shouldPersist) {
-          persistPath = await this.buildPathFromResolvedHandle(
+          persistPath = await this.tryBuildPathFromResolvedHandle(
             handle,
             "scroll",
             resolution.counter
@@ -10473,7 +10593,12 @@ var Opensteer = class _Opensteer {
         }
       );
       await this.syncCloudPageRef({ expectedUrl: result.url }).catch(
-        () => void 0
+        (error) => {
+          this.logDebugError(
+            "cloud page reference sync after newTab failed",
+            error
+          );
+        }
       );
       return result;
     }
@@ -10485,7 +10610,12 @@ var Opensteer = class _Opensteer {
   async switchTab(index) {
     if (this.cloud) {
       await this.invokeCloudActionAndResetCache("switchTab", { index });
-      await this.syncCloudPageRef().catch(() => void 0);
+      await this.syncCloudPageRef().catch((error) => {
+        this.logDebugError(
+          "cloud page reference sync after switchTab failed",
+          error
+        );
+      });
       return;
     }
     const page = await switchTab(this.context, index);
@@ -10495,7 +10625,12 @@ var Opensteer = class _Opensteer {
   async closeTab(index) {
     if (this.cloud) {
       await this.invokeCloudActionAndResetCache("closeTab", { index });
-      await this.syncCloudPageRef().catch(() => void 0);
+      await this.syncCloudPageRef().catch((error) => {
+        this.logDebugError(
+          "cloud page reference sync after closeTab failed",
+          error
+        );
+      });
       return;
     }
     const newPage = await closeTab(this.context, this.page, index);
@@ -10655,22 +10790,28 @@ var Opensteer = class _Opensteer {
       const handle = await this.resolveCounterHandle(resolution.counter);
       try {
         if (storageKey && resolution.shouldPersist) {
-          const persistPath = await this.buildPathFromResolvedHandle(
+          const persistPath = await this.tryBuildPathFromResolvedHandle(
             handle,
             method,
             resolution.counter
           );
-          this.persistPath(
-            storageKey,
-            method,
-            options.description,
-            persistPath
-          );
+          if (persistPath) {
+            this.persistPath(
+              storageKey,
+              method,
+              options.description,
+              persistPath
+            );
+          }
         }
         return await counterFn(handle);
       } catch (err) {
-        const message = err instanceof Error ? err.message : `${method} failed.`;
-        throw new Error(message);
+        if (err instanceof Error) {
+          throw err;
+        }
+        throw new Error(
+          `${method} failed. ${extractErrorMessage(err, "Unknown error.")}`
+        );
       } finally {
         await handle.dispose();
       }
@@ -10699,7 +10840,7 @@ var Opensteer = class _Opensteer {
       let persistPath = null;
       try {
         if (storageKey && resolution.shouldPersist) {
-          persistPath = await this.buildPathFromResolvedHandle(
+          persistPath = await this.tryBuildPathFromResolvedHandle(
             handle,
             "uploadFile",
             resolution.counter
@@ -10797,6 +10938,9 @@ var Opensteer = class _Opensteer {
     if (this.cloud) {
       return await this.invokeCloudAction("extract", options);
     }
+    if (options.schema !== void 0) {
+      assertValidExtractSchemaRoot(options.schema);
+    }
     const storageKey = this.resolveStorageKey(options.description);
     const schemaHash = options.schema ? computeSchemaHash(options.schema) : null;
     const stored = storageKey ? this.storage.readSelector(storageKey) : null;
@@ -10805,7 +10949,7 @@ var Opensteer = class _Opensteer {
       try {
         payload = normalizePersistedExtractPayload(stored.path);
       } catch (err) {
-        const message = err instanceof Error ? err.message : "Unknown error";
+        const message = extractErrorMessage(err, "Unknown error.");
         const selectorFile = storageKey ? this.storage.getSelectorPath(storageKey) : "unknown selector file";
         throw new Error(
           `Cached extraction selector is invalid for the current schema at "${selectorFile}". Delete the cached selector and rerun extraction. ${message}`
@@ -10822,7 +10966,16 @@ var Opensteer = class _Opensteer {
       fields.push(...schemaFields);
     }
     if (!fields.length) {
-      const planResult = await this.parseAiExtractPlan(options);
+      let planResult;
+      try {
+        planResult = await this.parseAiExtractPlan(options);
+      } catch (error) {
+        const message = extractErrorMessage(error, "Unknown error.");
+        const contextMessage = options.schema ? "Schema extraction did not resolve deterministic field targets, so Opensteer attempted AI extraction planning." : "Opensteer attempted AI extraction planning.";
+        throw new Error(`${contextMessage} ${message}`, {
+          cause: error
+        });
+      }
       if (planResult.fields.length) {
         fields.push(...planResult.fields);
       } else if (planResult.data !== void 0) {
@@ -10963,7 +11116,7 @@ var Opensteer = class _Opensteer {
       let persistPath = null;
       try {
         if (storageKey && resolution.shouldPersist) {
-          persistPath = await this.buildPathFromResolvedHandle(
+          persistPath = await this.tryBuildPathFromResolvedHandle(
             handle,
             "click",
             resolution.counter
@@ -11059,17 +11212,6 @@ var Opensteer = class _Opensteer {
       }
     }
     if (options.element != null) {
-      const pathFromElement = await this.tryBuildPathFromCounter(
-        options.element
-      );
-      if (pathFromElement) {
-        return {
-          path: pathFromElement,
-          counter: null,
-          shouldPersist: Boolean(storageKey),
-          source: "element"
-        };
-      }
       return {
         path: null,
         counter: options.element,
@@ -11097,17 +11239,6 @@ var Opensteer = class _Opensteer {
         options.description
       );
       if (resolved?.counter != null) {
-        const pathFromAiCounter = await this.tryBuildPathFromCounter(
-          resolved.counter
-        );
-        if (pathFromAiCounter) {
-          return {
-            path: pathFromAiCounter,
-            counter: null,
-            shouldPersist: Boolean(storageKey),
-            source: "ai"
-          };
-        }
         return {
           path: null,
           counter: resolved.counter,
@@ -11189,23 +11320,22 @@ var Opensteer = class _Opensteer {
     try {
       const builtPath = await buildElementPathFromHandle(handle);
       if (builtPath) {
-        return this.withIndexedIframeContext(builtPath, indexedPath);
+        const withFrameContext = await this.withHandleIframeContext(
+          handle,
+          builtPath
+        );
+        return this.withIndexedIframeContext(
+          withFrameContext,
+          indexedPath
+        );
       }
       return indexedPath;
     } finally {
       await handle.dispose();
     }
   }
-  async tryBuildPathFromCounter(counter) {
-    try {
-      return await this.buildPathFromElement(counter);
-    } catch {
-      return null;
-    }
-  }
   async resolveCounterHandle(element) {
-    const snapshot = await this.ensureSnapshotWithCounters();
-    return resolveCounterElement(this.page, snapshot, element);
+    return resolveCounterElement(this.page, element);
   }
   async resolveCounterHandleForAction(action, description, element) {
     try {
@@ -11229,8 +11359,12 @@ var Opensteer = class _Opensteer {
     const indexedPath = await this.readPathFromCounterIndex(counter);
     const builtPath = await buildElementPathFromHandle(handle);
     if (builtPath) {
+      const withFrameContext = await this.withHandleIframeContext(
+        handle,
+        builtPath
+      );
       const normalized = this.withIndexedIframeContext(
-        builtPath,
+        withFrameContext,
         indexedPath
       );
       if (normalized.nodes.length) return normalized;
@@ -11240,15 +11374,34 @@ var Opensteer = class _Opensteer {
       `Unable to build element path from counter ${counter} during ${action}.`
     );
   }
+  async tryBuildPathFromResolvedHandle(handle, action, counter) {
+    try {
+      return await this.buildPathFromResolvedHandle(handle, action, counter);
+    } catch (error) {
+      this.logDebugError(
+        `path persistence skipped for ${action} counter ${counter}`,
+        error
+      );
+      return null;
+    }
+  }
   withIndexedIframeContext(builtPath, indexedPath) {
     const normalizedBuilt = this.normalizePath(builtPath);
     if (!indexedPath) return normalizedBuilt;
     const iframePrefix = collectIframeContextPrefix(indexedPath);
     if (!iframePrefix.length) return normalizedBuilt;
+    const builtContext = cloneContextHops(normalizedBuilt.context);
+    const overlap = measureContextOverlap(iframePrefix, builtContext);
+    const missingPrefix = cloneContextHops(
+      iframePrefix.slice(0, iframePrefix.length - overlap)
+    );
+    if (!missingPrefix.length) {
+      return normalizedBuilt;
+    }
     const merged = {
       context: [
-        ...cloneContextHops(iframePrefix),
-        ...cloneContextHops(normalizedBuilt.context)
+        ...missingPrefix,
+        ...builtContext
       ],
       nodes: cloneElementPath(normalizedBuilt).nodes
     };
@@ -11258,9 +11411,48 @@ var Opensteer = class _Opensteer {
     if (fallback.nodes.length) return fallback;
     return normalizedBuilt;
   }
+  async withHandleIframeContext(handle, path5) {
+    const ownFrame = await handle.ownerFrame();
+    if (!ownFrame) {
+      return this.normalizePath(path5);
+    }
+    let frame = ownFrame;
+    let prefix = [];
+    while (frame && frame !== this.page.mainFrame()) {
+      const parent = frame.parentFrame();
+      if (!parent) break;
+      const frameElement = await frame.frameElement().catch(() => null);
+      if (!frameElement) break;
+      try {
+        const frameElementPath = await buildElementPathFromHandle(frameElement);
+        if (frameElementPath?.nodes.length) {
+          const segment = [
+            ...cloneContextHops(frameElementPath.context),
+            {
+              kind: "iframe",
+              host: cloneElementPath(frameElementPath).nodes
+            }
+          ];
+          prefix = [...segment, ...prefix];
+        }
+      } finally {
+        await frameElement.dispose().catch(() => void 0);
+      }
+      frame = parent;
+    }
+    if (!prefix.length) {
+      return this.normalizePath(path5);
+    }
+    return this.normalizePath({
+      context: [...prefix, ...cloneContextHops(path5.context)],
+      nodes: cloneElementPath(path5).nodes
+    });
+  }
   async readPathFromCounterIndex(counter) {
-    const snapshot = await this.ensureSnapshotWithCounters();
-    const indexed = snapshot.counterIndex?.get(counter);
+    if (!this.snapshotCache || this.snapshotCache.url !== this.page.url() || !this.snapshotCache.counterIndex) {
+      return null;
+    }
+    const indexed = this.snapshotCache.counterIndex.get(counter);
     if (!indexed) return null;
     const normalized = this.normalizePath(indexed);
     if (!normalized.nodes.length) return null;
@@ -11271,15 +11463,6 @@ var Opensteer = class _Opensteer {
     if (!path5) return null;
     return this.normalizePath(path5);
   }
-  async ensureSnapshotWithCounters() {
-    if (!this.snapshotCache || !this.snapshotCache.counterBindings || this.snapshotCache.url !== this.page.url()) {
-      await this.snapshot({
-        mode: "full",
-        withCounters: true
-      });
-    }
-    return this.snapshotCache;
-  }
   persistPath(id, method, description, path5) {
     const now = Date.now();
     const safeFile = this.storage.getSelectorFileName(id);
@@ -11484,12 +11667,6 @@ var Opensteer = class _Opensteer {
     };
   }
   async buildFieldTargetsFromSchema(schema) {
-    if (!schema || typeof schema !== "object") {
-      return [];
-    }
-    if (Array.isArray(schema)) {
-      return [];
-    }
     const fields = [];
     await this.collectFieldTargetsFromSchemaObject(
       schema,
@@ -11535,17 +11712,6 @@ var Opensteer = class _Opensteer {
         return;
       }
       if (normalized.element != null) {
-        const path5 = await this.tryBuildPathFromCounter(
-          normalized.element
-        );
-        if (path5) {
-          fields.push({
-            key: fieldKey,
-            path: path5,
-            attribute: normalized.attribute
-          });
-          return;
-        }
         fields.push({
           key: fieldKey,
           counter: normalized.element,
@@ -11563,6 +11729,10 @@ var Opensteer = class _Opensteer {
             path: path5,
             attribute: normalized.attribute
           });
+        } else {
+          throw new Error(
+            `Extraction schema field "${fieldKey}" uses selector "${normalized.selector}", but no matching element path could be built from the current page snapshot.`
+          );
         }
         return;
       }
@@ -11586,15 +11756,6 @@ var Opensteer = class _Opensteer {
         continue;
       }
       if (fieldPlan.element != null) {
-        const path6 = await this.tryBuildPathFromCounter(fieldPlan.element);
-        if (path6) {
-          fields.push({
-            key,
-            path: path6,
-            attribute: fieldPlan.attribute
-          });
-          continue;
-        }
         fields.push({
           key,
           counter: fieldPlan.element,
@@ -11649,12 +11810,7 @@ var Opensteer = class _Opensteer {
       }
     }
     if (counterRequests.length) {
-      const snapshot = await this.ensureSnapshotWithCounters();
-      const counterValues = await resolveCountersBatch(
-        this.page,
-        snapshot,
-        counterRequests
-      );
+      const counterValues = await resolveCountersBatch(this.page, counterRequests);
       Object.assign(result, counterValues);
     }
     if (pathFields.length) {
@@ -11684,7 +11840,7 @@ var Opensteer = class _Opensteer {
       const path5 = await this.buildPathFromElement(field.counter);
       if (!path5) {
         throw new Error(
-          `Unable to build element path from counter ${field.counter} for extraction field "${field.key}".`
+          `Unable to persist extraction schema field "${field.key}": counter ${field.counter} could not be converted into a stable element path.`
         );
       }
       resolved.push({
@@ -11730,6 +11886,33 @@ function collectIframeContextPrefix(path5) {
   if (lastIframeIndex < 0) return [];
   return cloneContextHops(context.slice(0, lastIframeIndex + 1));
 }
+function measureContextOverlap(indexedPrefix, builtContext) {
+  const maxOverlap = Math.min(indexedPrefix.length, builtContext.length);
+  for (let size = maxOverlap; size > 0; size -= 1) {
+    if (matchesContextPrefix(indexedPrefix, builtContext, size, true)) {
+      return size;
+    }
+  }
+  for (let size = maxOverlap; size > 0; size -= 1) {
+    if (matchesContextPrefix(indexedPrefix, builtContext, size, false)) {
+      return size;
+    }
+  }
+  return 0;
+}
+function matchesContextPrefix(indexedPrefix, builtContext, size, strictHost) {
+  for (let idx = 0; idx < size; idx += 1) {
+    const left = indexedPrefix[indexedPrefix.length - size + idx];
+    const right = builtContext[idx];
+    if (left.kind !== right.kind) {
+      return false;
+    }
+    if (strictHost && JSON.stringify(left.host) !== JSON.stringify(right.host)) {
+      return false;
+    }
+  }
+  return true;
+}
 function normalizeSchemaValue(value) {
   if (!value) return null;
   if (typeof value !== "object" || Array.isArray(value)) {
@@ -11913,13 +12096,28 @@ function countNonNullLeaves(value) {
 function isPrimitiveLike(value) {
   return value == null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
 }
+function assertValidExtractSchemaRoot(schema) {
+  if (!schema || typeof schema !== "object") {
+    throw new Error(
+      "Invalid extraction schema: expected a JSON object at the top level."
+    );
+  }
+  if (Array.isArray(schema)) {
+    throw new Error(
+      'Invalid extraction schema: top-level arrays are not supported. Wrap array fields in an object (for example {"items":[...]}).'
+    );
+  }
+}
 function parseAiExtractResponse(response) {
   if (typeof response === "string") {
     const trimmed = stripCodeFence(response);
     try {
       return JSON.parse(trimmed);
     } catch {
-      throw new Error("LLM extraction returned a non-JSON string.");
+      const preview = summarizeForError(trimmed);
+      throw new Error(
+        `LLM extraction returned a non-JSON response.${preview ? ` Preview: "${preview}"` : ""}`
+      );
     }
   }
   if (response && typeof response === "object") {
@@ -11944,6 +12142,12 @@ function stripCodeFence(input) {
   if (lastFence === -1) return withoutHeader.trim();
   return withoutHeader.slice(0, lastFence).trim();
 }
+function summarizeForError(input, maxLength = 180) {
+  const compact = input.replace(/\s+/g, " ").trim();
+  if (!compact) return "";
+  if (compact.length <= maxLength) return compact;
+  return `${compact.slice(0, maxLength)}...`;
+}
 function getScrollDelta2(options) {
   const amount = typeof options.amount === "number" ? options.amount : 600;
   const absoluteAmount = Math.abs(amount);
@@ -11966,10 +12170,11 @@ function isInternalOrBlankPageUrl(url) {
 }
 function buildLocalRunId(namespace) {
   const normalized = namespace.trim() || "default";
-  return `${normalized}-${Date.now().toString(36)}-${randomUUID2().slice(0, 8)}`;
+  return `${normalized}-${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
 }
 
 export {
+  normalizeError,
   normalizeNamespace,
   resolveNamespaceDir,
   waitForVisualStability,
@@ -11995,13 +12200,12 @@ export {
   cleanForClickable,
   cleanForScrollable,
   cleanForAction,
-  CounterResolutionError,
-  ensureLiveCounters,
-  resolveCounterElement,
-  resolveCountersBatch,
   prepareSnapshot,
   ElementPathError,
   resolveElementPath,
+  CounterResolutionError,
+  resolveCounterElement,
+  resolveCountersBatch,
   performClick,
   performHover,
   performInput,