opensteer 0.4.13 → 0.5.0

package/dist/cli/server.cjs

@@ -108,6 +108,15 @@ function resolveProviderInfo(modelStr) {
       return info;
     }
   }
+  const slash = modelStr.indexOf("/");
+  if (slash > 0) {
+    const provider = modelStr.slice(0, slash).trim().toLowerCase();
+    if (provider) {
+      throw new Error(
+        `Unsupported model provider prefix "${provider}" in model "${modelStr}". Use one of: openai, anthropic, google, xai, groq.`
+      );
+    }
+  }
   return { pkg: "@ai-sdk/openai", providerFn: "openai" };
 }
 function stripProviderPrefix(modelStr) {
@@ -351,7 +360,7 @@ var import_net = require("net");
 var import_fs4 = require("fs");
 
 // src/opensteer.ts
-var import_crypto2 = require("crypto");
+var import_crypto = require("crypto");
 
 // src/browser/pool.ts
 var import_playwright = require("playwright");
@@ -821,6 +830,232 @@ var import_path3 = __toESM(require("path"), 1);
 var import_url = require("url");
 var import_dotenv = require("dotenv");
 
+// 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
 var import_path2 = __toESM(require("path"), 1);
 var DEFAULT_NAMESPACE = "default";
@@ -884,11 +1119,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 = import_path3.default.resolve(rootDir);
   const nodeEnv = baseEnv.NODE_ENV?.trim() || "";
   for (const filename of dotenvFileOrder(nodeEnv)) {
@@ -902,15 +1138,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
@@ -954,13 +1199,22 @@ function assertNoLegacyRuntimeConfig(source, config) {
     );
   }
 }
-function loadConfigFile(rootDir) {
+function loadConfigFile(rootDir, options = {}) {
   const configPath = import_path3.default.join(rootDir, ".opensteer", "config.json");
   if (!import_fs.default.existsSync(configPath)) return {};
   try {
     const raw = import_fs.default.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 {};
   }
 }
@@ -1092,6 +1346,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: {
@@ -1100,12 +1356,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."
@@ -1789,9 +2049,11 @@ function createEmptyRegistry(name) {
 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;
@@ -1825,7 +2087,16 @@ var LocalSelectorStorage = class {
     try {
       const raw = import_fs2.default.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);
     }
   }
@@ -1842,7 +2113,16 @@ var LocalSelectorStorage = class {
     try {
       const raw = import_fs2.default.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;
     }
   }
@@ -1862,7 +2142,6 @@ var LocalSelectorStorage = class {
 
 // src/html/pipeline.ts
 var cheerio3 = __toESM(require("cheerio"), 1);
-var import_crypto = require("crypto");
 
 // src/html/serializer.ts
 var cheerio = __toESM(require("cheerio"), 1);
@@ -2135,9 +2414,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;
@@ -3927,567 +4203,178 @@ 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
+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;
-  }
-  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) {
+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) {
-            if (child.getAttribute(nodeAttr) === nodeId) {
-              matches.push(child);
-            }
-            helpers.walk(matches, child);
+            child.removeAttribute("c");
+            walk(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);
-              }
+              walk(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)
-      );
+        walk(document);
+      });
+    } catch {
     }
   }
-  return out;
 }
 async function mapFramesByToken(page) {
   const out = /* @__PURE__ */ new Map();
@@ -4509,193 +4396,18 @@ 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 stripNodeIds(html) {
+  if (!html.includes(OS_NODE_ID_ATTR)) return html;
+  const $ = cheerio3.load(html, { xmlMode: false });
+  $(`[${OS_NODE_ID_ATTR}]`).removeAttr(OS_NODE_ID_ATTR);
+  return $.html();
 }
-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
-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 });
-  $(`[${OS_NODE_ID_ATTR}]`).removeAttr(OS_NODE_ID_ATTR);
-  return $.html();
-}
-async function prepareSnapshot(page, options = {}) {
-  const snapshotSessionId = (0, import_crypto.randomUUID)();
-  const mode = options.mode ?? "action";
-  const withCounters = options.withCounters ?? true;
-  const shouldMarkInteractive = options.markInteractive ?? true;
-  if (shouldMarkInteractive) {
-    await markInteractiveElements(page);
+async function prepareSnapshot(page, options = {}) {
+  const mode = options.mode ?? "action";
+  const withCounters = options.withCounters ?? true;
+  const shouldMarkInteractive = options.markInteractive ?? true;
+  if (shouldMarkInteractive) {
+    await markInteractiveElements(page);
   }
   const serialized = await serializePageHTML(page);
   const rawHtml = serialized.html;
@@ -4703,18 +4415,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);
   }
@@ -4723,325 +4432,724 @@ async function prepareSnapshot(page, options = {}) {
     cleanedHtml = $unwrap("body").html()?.trim() || cleanedHtml;
   }
   return {
-    snapshotSessionId,
     mode,
     url: page.url(),
     rawHtml,
     processedHtml,
     reducedHtml,
     cleanedHtml,
-    counterIndex,
-    counterBindings
+    counterIndex
+  };
+}
+
+// src/element-path/errors.ts
+var ElementPathError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "ElementPathError";
+    this.code = code;
+  }
+};
+
+// src/element-path/resolver.ts
+async function resolveElementPath(page, rawPath) {
+  const path5 = sanitizeElementPath(rawPath);
+  let frame = page.mainFrame();
+  let rootHandle = null;
+  for (const hop of path5.context) {
+    const host = await resolveDomPath(frame, hop.host, rootHandle);
+    if (!host) {
+      await disposeHandle(rootHandle);
+      throw new ElementPathError(
+        "ERR_PATH_CONTEXT_HOST_NOT_FOUND",
+        "Unable to resolve context host from stored match selectors."
+      );
+    }
+    if (hop.kind === "iframe") {
+      const nextFrame = await host.element.contentFrame();
+      await host.element.dispose();
+      await disposeHandle(rootHandle);
+      rootHandle = null;
+      if (!nextFrame) {
+        throw new ElementPathError(
+          "ERR_PATH_IFRAME_UNAVAILABLE",
+          "Iframe is unavailable or inaccessible for this path."
+        );
+      }
+      frame = nextFrame;
+      continue;
+    }
+    const shadowRoot = await host.element.evaluateHandle(
+      (element) => element.shadowRoot
+    );
+    await host.element.dispose();
+    const isMissing = await shadowRoot.evaluate((value) => value == null);
+    if (isMissing) {
+      await shadowRoot.dispose();
+      await disposeHandle(rootHandle);
+      throw new ElementPathError(
+        "ERR_PATH_SHADOW_ROOT_UNAVAILABLE",
+        "Shadow root is unavailable for this path."
+      );
+    }
+    await disposeHandle(rootHandle);
+    rootHandle = shadowRoot;
+  }
+  const target = await resolveDomPath(frame, path5.nodes, rootHandle);
+  if (!target) {
+    const diagnostics = await collectCandidateDiagnostics(
+      frame,
+      path5.nodes,
+      rootHandle
+    );
+    await disposeHandle(rootHandle);
+    throw new ElementPathError(
+      "ERR_PATH_TARGET_NOT_FOUND",
+      buildTargetNotFoundMessage(path5.nodes, diagnostics)
+    );
+  }
+  await disposeHandle(rootHandle);
+  if (isPathDebugEnabled()) {
+    debugPath("resolved", {
+      selector: target.selector,
+      mode: target.mode,
+      count: target.count,
+      targetDepth: path5.nodes.length
+    });
+  }
+  return {
+    element: target.element,
+    usedSelector: target.selector || buildPathSelectorHint(path5)
+  };
+}
+async function resolveDomPath(frame, domPath, rootHandle) {
+  const candidates = buildPathCandidates(domPath);
+  if (!candidates.length) return null;
+  if (isPathDebugEnabled()) {
+    debugPath("trying selectors", { candidates });
+  }
+  const selected = rootHandle ? await rootHandle.evaluate(selectInRoot, candidates) : await frame.evaluate(selectInDocument, candidates);
+  if (!selected || !selected.selector) return null;
+  const handle = rootHandle ? await rootHandle.evaluateHandle((root, selector) => {
+    if (!(root instanceof ShadowRoot)) return null;
+    return root.querySelector(selector);
+  }, selected.selector) : await frame.evaluateHandle(
+    (selector) => document.querySelector(selector),
+    selected.selector
+  );
+  const element = handle.asElement();
+  if (!element) {
+    await handle.dispose();
+    return null;
+  }
+  return {
+    element,
+    selector: selected.selector,
+    mode: selected.mode,
+    count: selected.count
+  };
+}
+async function collectCandidateDiagnostics(frame, domPath, rootHandle) {
+  const candidates = buildPathCandidates(domPath);
+  if (!candidates.length) return [];
+  const diagnostics = rootHandle ? await rootHandle.evaluate(countInRoot, candidates) : await frame.evaluate(countInDocument, candidates);
+  return Array.isArray(diagnostics) ? diagnostics.map((item) => ({
+    selector: String(item?.selector || ""),
+    count: Number(item?.count || 0)
+  })).filter((item) => item.selector) : [];
+}
+function buildTargetNotFoundMessage(domPath, diagnostics) {
+  const depth = Array.isArray(domPath) ? domPath.length : 0;
+  const sample = diagnostics.slice(0, 4).map((item) => `"${item.selector}" => ${item.count}`).join(", ");
+  const base = "Element path resolution failed (ERR_PATH_TARGET_NOT_FOUND): no selector candidate matched the current DOM.";
+  if (!sample)
+    return `${base} Tried ${Math.max(diagnostics.length, 0)} candidates.`;
+  return `${base} Target depth ${depth}. Candidate counts: ${sample}.`;
+}
+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 = root.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 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;
+    try {
+      count = root.querySelectorAll(selector).length;
+    } catch {
+      count = 0;
+    }
+    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/actions/actionability-probe.ts
+async function probeActionabilityState(element) {
+  try {
+    return await element.evaluate((target) => {
+      if (!(target instanceof Element)) {
+        return {
+          connected: false,
+          visible: null,
+          enabled: null,
+          editable: null,
+          blocker: null
+        };
+      }
+      const connected = target.isConnected;
+      if (!connected) {
+        return {
+          connected: false,
+          visible: null,
+          enabled: null,
+          editable: null,
+          blocker: null
+        };
+      }
+      const style = window.getComputedStyle(target);
+      const rect = target.getBoundingClientRect();
+      const hasBox = rect.width > 0 && rect.height > 0;
+      const opacity = Number.parseFloat(style.opacity || "1");
+      const isVisible = hasBox && style.display !== "none" && style.visibility !== "hidden" && style.visibility !== "collapse" && (!Number.isFinite(opacity) || opacity > 0);
+      let enabled = null;
+      if (target instanceof HTMLButtonElement || target instanceof HTMLInputElement || target instanceof HTMLSelectElement || target instanceof HTMLTextAreaElement || target instanceof HTMLOptionElement || target instanceof HTMLOptGroupElement || target instanceof HTMLFieldSetElement) {
+        enabled = !target.disabled;
+      }
+      let editable = null;
+      if (target instanceof HTMLInputElement) {
+        editable = !target.readOnly && !target.disabled;
+      } else if (target instanceof HTMLTextAreaElement) {
+        editable = !target.readOnly && !target.disabled;
+      } else if (target instanceof HTMLSelectElement) {
+        editable = !target.disabled;
+      } else if (target instanceof HTMLElement && target.isContentEditable) {
+        editable = true;
+      }
+      let blocker = null;
+      if (hasBox && window.innerWidth > 0 && window.innerHeight > 0) {
+        const x = Math.min(
+          Math.max(rect.left + rect.width / 2, 0),
+          window.innerWidth - 1
+        );
+        const y = Math.min(
+          Math.max(rect.top + rect.height / 2, 0),
+          window.innerHeight - 1
+        );
+        const top = document.elementFromPoint(x, y);
+        if (top && top !== target && !target.contains(top)) {
+          const classes = String(top.className || "").split(/\s+/).map((value) => value.trim()).filter(Boolean).slice(0, 5);
+          blocker = {
+            tag: top.tagName.toLowerCase(),
+            id: top.id || null,
+            classes,
+            role: top.getAttribute("role"),
+            text: (top.textContent || "").trim().slice(0, 80) || null
+          };
+        }
+      }
+      return {
+        connected,
+        visible: isVisible,
+        enabled,
+        editable,
+        blocker
+      };
+    });
+  } catch {
+    return null;
+  }
+}
+
+// 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/element-path/errors.ts
-var ElementPathError = class extends Error {
+// src/html/counter-runtime.ts
+var CounterResolutionError = class extends Error {
   code;
   constructor(code, message) {
     super(message);
-    this.name = "ElementPathError";
+    this.name = "CounterResolutionError";
     this.code = code;
   }
 };
-
-// src/element-path/resolver.ts
-async function resolveElementPath(page, rawPath) {
-  const path5 = sanitizeElementPath(rawPath);
-  let frame = page.mainFrame();
-  let rootHandle = null;
-  for (const hop of path5.context) {
-    const host = await resolveDomPath(frame, hop.host, rootHandle);
-    if (!host) {
-      await disposeHandle(rootHandle);
-      throw new ElementPathError(
-        "ERR_PATH_CONTEXT_HOST_NOT_FOUND",
-        "Unable to resolve context host from stored match selectors."
-      );
-    }
-    if (hop.kind === "iframe") {
-      const nextFrame = await host.element.contentFrame();
-      await host.element.dispose();
-      await disposeHandle(rootHandle);
-      rootHandle = null;
-      if (!nextFrame) {
-        throw new ElementPathError(
-          "ERR_PATH_IFRAME_UNAVAILABLE",
-          "Iframe is unavailable or inaccessible for this path."
-        );
-      }
-      frame = nextFrame;
-      continue;
-    }
-    const shadowRoot = await host.element.evaluateHandle(
-      (element) => element.shadowRoot
-    );
-    await host.element.dispose();
-    const isMissing = await shadowRoot.evaluate((value) => value == null);
-    if (isMissing) {
-      await shadowRoot.dispose();
-      await disposeHandle(rootHandle);
-      throw new ElementPathError(
-        "ERR_PATH_SHADOW_ROOT_UNAVAILABLE",
-        "Shadow root is unavailable for this path."
-      );
-    }
-    await disposeHandle(rootHandle);
-    rootHandle = shadowRoot;
-  }
-  const target = await resolveDomPath(frame, path5.nodes, rootHandle);
-  if (!target) {
-    const diagnostics = await collectCandidateDiagnostics(
-      frame,
-      path5.nodes,
-      rootHandle
-    );
-    await disposeHandle(rootHandle);
-    throw new ElementPathError(
-      "ERR_PATH_TARGET_NOT_FOUND",
-      buildTargetNotFoundMessage(path5.nodes, diagnostics)
-    );
+async function resolveCounterElement(page, counter) {
+  const normalized = normalizeCounter(counter);
+  if (normalized == null) {
+    throw buildCounterNotFoundError(counter);
   }
-  await disposeHandle(rootHandle);
-  if (isPathDebugEnabled()) {
-    debugPath("resolved", {
-      selector: target.selector,
-      mode: target.mode,
-      count: target.count,
-      targetDepth: path5.nodes.length
-    });
+  const scan = await scanCounterOccurrences(page, [normalized]);
+  const entry = scan.get(normalized);
+  if (!entry || entry.count <= 0 || !entry.frame) {
+    throw buildCounterNotFoundError(counter);
   }
-  return {
-    element: target.element,
-    usedSelector: target.selector || buildPathSelectorHint(path5)
-  };
-}
-async function resolveDomPath(frame, domPath, rootHandle) {
-  const candidates = buildPathCandidates(domPath);
-  if (!candidates.length) return null;
-  if (isPathDebugEnabled()) {
-    debugPath("trying selectors", { candidates });
+  if (entry.count > 1) {
+    throw buildCounterAmbiguousError(counter);
   }
-  const selected = rootHandle ? await rootHandle.evaluate(selectInRoot, candidates) : await frame.evaluate(selectInDocument, candidates);
-  if (!selected || !selected.selector) return null;
-  const handle = rootHandle ? await rootHandle.evaluateHandle((root, selector) => {
-    if (!(root instanceof ShadowRoot)) return null;
-    return root.querySelector(selector);
-  }, selected.selector) : await frame.evaluateHandle(
-    (selector) => document.querySelector(selector),
-    selected.selector
-  );
+  const handle = await resolveUniqueHandleInFrame(entry.frame, normalized);
   const element = handle.asElement();
   if (!element) {
     await handle.dispose();
-    return null;
+    throw buildCounterNotFoundError(counter);
   }
-  return {
-    element,
-    selector: selected.selector,
-    mode: selected.mode,
-    count: selected.count
-  };
-}
-async function collectCandidateDiagnostics(frame, domPath, rootHandle) {
-  const candidates = buildPathCandidates(domPath);
-  if (!candidates.length) return [];
-  const diagnostics = rootHandle ? await rootHandle.evaluate(countInRoot, candidates) : await frame.evaluate(countInDocument, candidates);
-  return Array.isArray(diagnostics) ? diagnostics.map((item) => ({
-    selector: String(item?.selector || ""),
-    count: Number(item?.count || 0)
-  })).filter((item) => item.selector) : [];
-}
-function buildTargetNotFoundMessage(domPath, diagnostics) {
-  const depth = Array.isArray(domPath) ? domPath.length : 0;
-  const sample = diagnostics.slice(0, 4).map((item) => `"${item.selector}" => ${item.count}`).join(", ");
-  const base = "Element path resolution failed (ERR_PATH_TARGET_NOT_FOUND): no selector candidate matched the current DOM.";
-  if (!sample)
-    return `${base} Tried ${Math.max(diagnostics.length, 0)} candidates.`;
-  return `${base} Target depth ${depth}. Candidate counts: ${sample}.`;
+  return element;
 }
-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"
-      };
+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);
     }
   }
-  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 = root.querySelectorAll(selector).length;
-    } catch {
-      count = 0;
+  const valueCache = /* @__PURE__ */ new Map();
+  for (const request of requests) {
+    const normalized = normalizeCounter(request.counter);
+    if (normalized == null) {
+      out[request.key] = null;
+      continue;
     }
-    if (count === 1) {
-      return {
-        selector,
-        count,
-        mode: "unique"
-      };
+    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;
     }
-  }
-  return fallback;
-}
-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;
+    const read = await readCounterValueInFrame(
+      entry.frame,
+      normalized,
+      request.attribute
+    );
+    if (read.status === "ambiguous") {
+      throw buildCounterAmbiguousError(normalized);
     }
-    out.push({ selector, count });
+    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 out;
 }
-function countInRoot(root, selectors) {
-  if (!(root instanceof ShadowRoot)) return [];
+function dedupeCounters(requests) {
+  const seen = /* @__PURE__ */ new Set();
   const out = [];
-  for (const selector of selectors) {
-    if (!selector) continue;
-    let count = 0;
-    try {
-      count = root.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 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}`);
-  }
+function normalizeCounter(counter) {
+  if (!Number.isFinite(counter)) return null;
+  if (!Number.isInteger(counter)) return null;
+  if (counter <= 0) return null;
+  return counter;
 }
-async function disposeHandle(handle) {
-  if (!handle) return;
-  try {
-    await handle.dispose();
-  } catch {
+async function scanCounterOccurrences(page, counters) {
+  const out = /* @__PURE__ */ new Map();
+  for (const counter of counters) {
+    out.set(counter, {
+      count: 0,
+      frame: null
+    });
   }
-}
-
-// src/actions/actionability-probe.ts
-async function probeActionabilityState(element) {
-  try {
-    return await element.evaluate((target) => {
-      if (!(target instanceof Element)) {
-        return {
-          connected: false,
-          visible: null,
-          enabled: null,
-          editable: null,
-          blocker: null
-        };
-      }
-      const connected = target.isConnected;
-      if (!connected) {
-        return {
-          connected: false,
-          visible: null,
-          enabled: null,
-          editable: null,
-          blocker: null
+  if (!counters.length) return out;
+  for (const frame of page.frames()) {
+    let frameCounts;
+    try {
+      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 {
+      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;
       }
-      const style = window.getComputedStyle(target);
-      const rect = target.getBoundingClientRect();
-      const hasBox = rect.width > 0 && rect.height > 0;
-      const opacity = Number.parseFloat(style.opacity || "1");
-      const isVisible = hasBox && style.display !== "none" && style.visibility !== "hidden" && style.visibility !== "collapse" && (!Number.isFinite(opacity) || opacity > 0);
-      let enabled = null;
-      if (target instanceof HTMLButtonElement || target instanceof HTMLInputElement || target instanceof HTMLSelectElement || target instanceof HTMLTextAreaElement || target instanceof HTMLOptionElement || target instanceof HTMLOptGroupElement || target instanceof HTMLFieldSetElement) {
-        enabled = !target.disabled;
-      }
-      let editable = null;
-      if (target instanceof HTMLInputElement) {
-        editable = !target.readOnly && !target.disabled;
-      } else if (target instanceof HTMLTextAreaElement) {
-        editable = !target.readOnly && !target.disabled;
-      } else if (target instanceof HTMLSelectElement) {
-        editable = !target.disabled;
-      } else if (target instanceof HTMLElement && target.isContentEditable) {
-        editable = true;
+    }
+  }
+  return out;
+}
+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);
+        }
       }
-      let blocker = null;
-      if (hasBox && window.innerWidth > 0 && window.innerHeight > 0) {
-        const x = Math.min(
-          Math.max(rect.left + rect.width / 2, 0),
-          window.innerWidth - 1
-        );
-        const y = Math.min(
-          Math.max(rect.top + rect.height / 2, 0),
-          window.innerHeight - 1
-        );
-        const top = document.elementFromPoint(x, y);
-        if (top && top !== target && !target.contains(top)) {
-          const classes = String(top.className || "").split(/\s+/).map((value) => value.trim()).filter(Boolean).slice(0, 5);
-          blocker = {
-            tag: top.tagName.toLowerCase(),
-            id: top.id || null,
-            classes,
-            role: top.getAttribute("role"),
-            text: (top.textContent || "").trim().slice(0, 80) || null
+    };
+    walk(document);
+    if (matches.length !== 1) {
+      return null;
+    }
+    return matches[0];
+  }, String(counter));
+}
+async function readCounterValueInFrame(frame, counter, attribute) {
+  try {
+    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
       }
-      return {
-        connected,
-        visible: isVisible,
-        enabled,
-        editable,
-        blocker
-      };
-    });
+    );
   } catch {
-    return null;
+    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/failure-classifier.ts
 var ACTION_FAILURE_CODES = [
@@ -5092,7 +5200,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);
@@ -5101,7 +5209,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"
   });
 }
@@ -5157,13 +5265,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",
@@ -5171,13 +5272,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;
 }
@@ -5361,13 +5455,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) {
@@ -7677,7 +7780,8 @@ function withTokenQuery(wsUrl, token) {
 // src/cloud/local-cache-sync.ts
 var import_fs3 = __toESM(require("fs"), 1);
 var import_path5 = __toESM(require("path"), 1);
-function collectLocalSelectorCacheEntries(storage) {
+function collectLocalSelectorCacheEntries(storage, options = {}) {
+  const debug = options.debug === true;
   const namespace = storage.getNamespace();
   const namespaceDir = storage.getNamespaceDir();
   if (!import_fs3.default.existsSync(namespaceDir)) return [];
@@ -7686,7 +7790,7 @@ function collectLocalSelectorCacheEntries(storage) {
   for (const fileName of fileNames) {
     if (fileName === "index.json" || !fileName.endsWith(".json")) continue;
     const filePath = import_path5.default.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);
@@ -7711,11 +7815,20 @@ function collectLocalSelectorCacheEntries(storage) {
   }
   return dedupeNewest(entries);
 }
-function readSelectorFile(filePath) {
+function readSelectorFile(filePath, debug) {
   try {
     const raw = import_fs3.default.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;
   }
 }
@@ -9923,7 +10036,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;
@@ -9942,6 +10057,14 @@ 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) => {
@@ -10032,7 +10155,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) {
@@ -10170,12 +10294,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;
@@ -10207,7 +10326,12 @@ var Opensteer = class _Opensteer {
         this.cloud.actionClient = actionClient;
         this.cloud.sessionId = sessionId;
         this.cloud.cloudSessionUrl = session3.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: session3.sessionId,
           workspaceId: session3.cloudSession.workspaceId,
@@ -10294,7 +10418,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
@@ -10303,9 +10429,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 ?? {};
@@ -10406,7 +10535,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
@@ -10505,7 +10634,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
@@ -10608,7 +10737,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
@@ -10718,7 +10847,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
@@ -10817,7 +10946,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;
     }
@@ -10829,7 +10963,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);
@@ -10839,7 +10978,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);
@@ -10999,22 +11143,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();
       }
@@ -11043,7 +11193,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
@@ -11141,6 +11291,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;
@@ -11149,7 +11302,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}`
@@ -11166,7 +11319,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) {
@@ -11307,7 +11469,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
@@ -11403,17 +11565,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,
@@ -11441,17 +11592,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,
@@ -11533,23 +11673,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 {
@@ -11573,8 +11712,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;
@@ -11584,15 +11727,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
     };
@@ -11602,9 +11764,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 prefix2 = [];
+    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
+            }
+          ];
+          prefix2 = [...segment, ...prefix2];
+        }
+      } finally {
+        await frameElement.dispose().catch(() => void 0);
+      }
+      frame = parent;
+    }
+    if (!prefix2.length) {
+      return this.normalizePath(path5);
+    }
+    return this.normalizePath({
+      context: [...prefix2, ...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;
@@ -11615,15 +11816,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);
@@ -11828,12 +12020,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,
@@ -11879,17 +12065,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,
@@ -11907,6 +12082,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;
       }
@@ -11930,15 +12109,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,
@@ -11993,12 +12163,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) {
@@ -12028,7 +12193,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({
@@ -12050,7 +12215,7 @@ var Opensteer = class _Opensteer {
   }
   resolveStorageKey(description) {
     if (!description) return null;
-    return (0, import_crypto2.createHash)("sha256").update(description).digest("hex").slice(0, 16);
+    return (0, import_crypto.createHash)("sha256").update(description).digest("hex").slice(0, 16);
   }
   normalizePath(path5) {
     return sanitizeElementPath(path5);
@@ -12074,6 +12239,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)) {
@@ -12095,7 +12287,7 @@ function normalizeExtractSource(source) {
 }
 function computeSchemaHash(schema) {
   const stable = stableStringify(schema);
-  return (0, import_crypto2.createHash)("sha256").update(stable).digest("hex");
+  return (0, import_crypto.createHash)("sha256").update(stable).digest("hex");
 }
 function buildPathMap(fields) {
   const out = {};
@@ -12257,13 +12449,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 = stripCodeFence2(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") {
@@ -12288,6 +12495,12 @@ function stripCodeFence2(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);
@@ -12310,7 +12523,7 @@ function isInternalOrBlankPageUrl(url) {
 }
 function buildLocalRunId(namespace) {
   const normalized = namespace.trim() || "default";
-  return `${normalized}-${Date.now().toString(36)}-${(0, import_crypto2.randomUUID)().slice(0, 8)}`;
+  return `${normalized}-${Date.now().toString(36)}-${(0, import_crypto.randomUUID)().slice(0, 8)}`;
 }
 
 // src/cli/paths.ts
@@ -12627,7 +12840,16 @@ function enqueueRequest(request, socket) {
     void handleRequest(request, socket);
     return;
   }
-  requestQueue = requestQueue.then(() => handleRequest(request, socket)).catch(() => {
+  requestQueue = requestQueue.then(() => handleRequest(request, socket)).catch((error) => {
+    sendResponse(
+      socket,
+      buildErrorResponse(
+        request.id,
+        error,
+        "Unexpected server error while handling request.",
+        "CLI_INTERNAL_ERROR"
+      )
+    );
   });
 }
 async function handleRequest(request, socket) {
@@ -12636,7 +12858,11 @@ async function handleRequest(request, socket) {
     sendResponse(socket, {
       id,
       ok: false,
-      error: `Session '${session}' is shutting down.`
+      error: `Session '${session}' is shutting down.`,
+      errorInfo: {
+        message: `Session '${session}' is shutting down.`,
+        code: "SESSION_SHUTTING_DOWN"
+      }
     });
     return;
   }
@@ -12644,7 +12870,11 @@ async function handleRequest(request, socket) {
     sendResponse(socket, {
       id,
       ok: false,
-      error: `Session '${session}' is shutting down. Retry your command.`
+      error: `Session '${session}' is shutting down. Retry your command.`,
+      errorInfo: {
+        message: `Session '${session}' is shutting down. Retry your command.`,
+        code: "SESSION_SHUTTING_DOWN"
+      }
     });
     return;
   }
@@ -12660,7 +12890,16 @@ async function handleRequest(request, socket) {
         sendResponse(socket, {
           id,
           ok: false,
-          error: `Session '${session}' is already bound to selector namespace '${selectorNamespace}'. Requested '${requestedName}' does not match. Use the same --name for this session or start a different --session.`
+          error: `Session '${session}' is already bound to selector namespace '${selectorNamespace}'. Requested '${requestedName}' does not match. Use the same --name for this session or start a different --session.`,
+          errorInfo: {
+            message: `Session '${session}' is already bound to selector namespace '${selectorNamespace}'. Requested '${requestedName}' does not match. Use the same --name for this session or start a different --session.`,
+            code: "SESSION_NAMESPACE_MISMATCH",
+            details: {
+              session,
+              activeNamespace: selectorNamespace,
+              requestedNamespace: requestedName
+            }
+          }
         });
         return;
       }
@@ -12718,11 +12957,10 @@ async function handleRequest(request, socket) {
         }
       });
     } catch (err) {
-      sendResponse(socket, {
-        id,
-        ok: false,
-        error: err instanceof Error ? err.message : String(err)
-      });
+      sendResponse(
+        socket,
+        buildErrorResponse(id, err, "Failed to open browser session.")
+      );
     }
     return;
   }
@@ -12738,11 +12976,10 @@ async function handleRequest(request, socket) {
         result: { sessionClosed: true }
       });
     } catch (err) {
-      sendResponse(socket, {
-        id,
-        ok: false,
-        error: err instanceof Error ? err.message : String(err)
-      });
+      sendResponse(
+        socket,
+        buildErrorResponse(id, err, "Failed to close browser session.")
+      );
     }
     beginShutdown();
     return;
@@ -12755,7 +12992,14 @@ async function handleRequest(request, socket) {
     sendResponse(socket, {
       id,
       ok: false,
-      error: `No browser session in session '${session}'. Call 'opensteer open --session ${session}' first, or use 'opensteer sessions' to list active sessions.`
+      error: `No browser session in session '${session}'. Call 'opensteer open --session ${session}' first, or use 'opensteer sessions' to list active sessions.`,
+      errorInfo: {
+        message: `No browser session in session '${session}'. Call 'opensteer open --session ${session}' first, or use 'opensteer sessions' to list active sessions.`,
+        code: "SESSION_NOT_OPEN",
+        details: {
+          session
+        }
+      }
     });
     return;
   }
@@ -12764,7 +13008,14 @@ async function handleRequest(request, socket) {
     sendResponse(socket, {
       id,
       ok: false,
-      error: `Unknown command: ${command}`
+      error: `Unknown command: ${command}`,
+      errorInfo: {
+        message: `Unknown command: ${command}`,
+        code: "UNKNOWN_COMMAND",
+        details: {
+          command
+        }
+      }
     });
     return;
   }
@@ -12772,11 +13023,12 @@ async function handleRequest(request, socket) {
     const result = await handler(instance, args);
     sendResponse(socket, { id, ok: true, result });
   } catch (err) {
-    sendResponse(socket, {
-      id,
-      ok: false,
-      error: err instanceof Error ? err.message : String(err)
-    });
+    sendResponse(
+      socket,
+      buildErrorResponse(id, err, `Command "${command}" failed.`, void 0, {
+        command
+      })
+    );
   }
 }
 if ((0, import_fs4.existsSync)(socketPath)) {
@@ -12797,7 +13049,11 @@ var server = (0, import_net.createServer)((socket) => {
         sendResponse(socket, {
           id: 0,
           ok: false,
-          error: "Invalid JSON request"
+          error: "Invalid JSON request",
+          errorInfo: {
+            message: "Invalid JSON request",
+            code: "INVALID_JSON_REQUEST"
+          }
         });
       }
     }
@@ -12836,3 +13092,25 @@ async function shutdown() {
 }
 process.on("SIGTERM", shutdown);
 process.on("SIGINT", shutdown);
+function buildErrorResponse(id, error, fallbackMessage, fallbackCode, details) {
+  const normalized = normalizeError(error, fallbackMessage);
+  let mergedDetails;
+  if (normalized.details || details) {
+    mergedDetails = {
+      ...normalized.details || {},
+      ...details || {}
+    };
+  }
+  return {
+    id,
+    ok: false,
+    error: normalized.message,
+    errorInfo: {
+      message: normalized.message,
+      ...normalized.code || fallbackCode ? { code: normalized.code || fallbackCode } : {},
+      ...normalized.name ? { name: normalized.name } : {},
+      ...mergedDetails ? { details: mergedDetails } : {},
+      ...normalized.cause ? { cause: normalized.cause } : {}
+    }
+  };
+}