@taodigital/crawler 0.0.0-stage → 1.2.1

package/dist/dead-link-detector.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/dead-link-detector.ts"],
+  "sourcesContent": ["/**\n * Dead link detector \u2014 tracks broken links discovered during crawl.\n *\n * A \"dead link\" is a URL that:\n * - Returns 404, 410, or other 4xx/5xx responses\n * - Times out after maxRetries\n * - Redirects to an error page (detected by title heuristic)\n *\n * Results: list of broken links with source page, status code, and anchor text.\n * Used for: SEO audit export, test report enrichment.\n */\n\nexport interface DeadLink {\n  url: string;\n  statusCode: number;\n  sourceUrl?: string;\n  anchorText?: string;\n  checkedAt: string;\n  reason: 'http-error' | 'timeout' | 'dns-error';\n}\n\nexport class DeadLinkTracker {\n  private deadLinks: DeadLink[] = [];\n  private checked = new Map<string, number>(); // url \u2192 statusCode\n\n  record(\n    url: string,\n    statusCode: number,\n    source?: { sourceUrl?: string; anchorText?: string },\n  ): void {\n    if (this.checked.has(url)) return;\n    this.checked.set(url, statusCode);\n    if (statusCode >= 400) {\n      this.deadLinks.push({\n        url,\n        statusCode,\n        sourceUrl: source?.sourceUrl,\n        anchorText: source?.anchorText,\n        checkedAt: new Date().toISOString(),\n        reason: statusCode === 0 ? 'timeout' : 'http-error',\n      });\n    }\n  }\n\n  recordTimeout(url: string, sourceUrl?: string): void {\n    if (this.checked.has(url)) return;\n    this.checked.set(url, 0);\n    this.deadLinks.push({ url, statusCode: 0, sourceUrl, checkedAt: new Date().toISOString(), reason: 'timeout' });\n  }\n\n  getDeadLinks(): DeadLink[] {\n    return [...this.deadLinks];\n  }\n\n  isKnownBroken(url: string): boolean {\n    const code = this.checked.get(url);\n    return code !== undefined && code >= 400;\n  }\n\n  stats(): { total: number; by404: number; by5xx: number; byTimeout: number } {\n    return {\n      total: this.deadLinks.length,\n      by404: this.deadLinks.filter(l => l.statusCode === 404).length,\n      by5xx: this.deadLinks.filter(l => l.statusCode >= 500).length,\n      byTimeout: this.deadLinks.filter(l => l.reason === 'timeout').length,\n    };\n  }\n\n  toCsv(): string {\n    const rows = [['URL', 'Status', 'Source URL', 'Anchor Text', 'Checked At']];\n    for (const l of this.deadLinks) {\n      rows.push([l.url, String(l.statusCode), l.sourceUrl ?? '', l.anchorText ?? '', l.checkedAt]);\n    }\n    return rows.map(r => r.map(c => `\"${c.replace(/\"/g, '\"\"')}\"`).join(',')).join('\\n');\n  }\n}\n"],
+  "mappings": "AAqBO,MAAM,gBAAgB;AAAA,EACnB,YAAwB,CAAC;AAAA,EACzB,UAAU,oBAAI,IAAoB;AAAA;AAAA,EAE1C,OACE,KACA,YACA,QACM;AACN,QAAI,KAAK,QAAQ,IAAI,GAAG,EAAG;AAC3B,SAAK,QAAQ,IAAI,KAAK,UAAU;AAChC,QAAI,cAAc,KAAK;AACrB,WAAK,UAAU,KAAK;AAAA,QAClB;AAAA,QACA;AAAA,QACA,WAAW,QAAQ;AAAA,QACnB,YAAY,QAAQ;AAAA,QACpB,YAAW,oBAAI,KAAK,GAAE,YAAY;AAAA,QAClC,QAAQ,eAAe,IAAI,YAAY;AAAA,MACzC,CAAC;AAAA,IACH;AAAA,EACF;AAAA,EAEA,cAAc,KAAa,WAA0B;AACnD,QAAI,KAAK,QAAQ,IAAI,GAAG,EAAG;AAC3B,SAAK,QAAQ,IAAI,KAAK,CAAC;AACvB,SAAK,UAAU,KAAK,EAAE,KAAK,YAAY,GAAG,WAAW,YAAW,oBAAI,KAAK,GAAE,YAAY,GAAG,QAAQ,UAAU,CAAC;AAAA,EAC/G;AAAA,EAEA,eAA2B;AACzB,WAAO,CAAC,GAAG,KAAK,SAAS;AAAA,EAC3B;AAAA,EAEA,cAAc,KAAsB;AAClC,UAAM,OAAO,KAAK,QAAQ,IAAI,GAAG;AACjC,WAAO,SAAS,UAAa,QAAQ;AAAA,EACvC;AAAA,EAEA,QAA4E;AAC1E,WAAO;AAAA,MACL,OAAO,KAAK,UAAU;AAAA,MACtB,OAAO,KAAK,UAAU,OAAO,OAAK,EAAE,eAAe,GAAG,EAAE;AAAA,MACxD,OAAO,KAAK,UAAU,OAAO,OAAK,EAAE,cAAc,GAAG,EAAE;AAAA,MACvD,WAAW,KAAK,UAAU,OAAO,OAAK,EAAE,WAAW,SAAS,EAAE;AAAA,IAChE;AAAA,EACF;AAAA,EAEA,QAAgB;AACd,UAAM,OAAO,CAAC,CAAC,OAAO,UAAU,cAAc,eAAe,YAAY,CAAC;AAC1E,eAAW,KAAK,KAAK,WAAW;AAC9B,WAAK,KAAK,CAAC,EAAE,KAAK,OAAO,EAAE,UAAU,GAAG,EAAE,aAAa,IAAI,EAAE,cAAc,IAAI,EAAE,SAAS,CAAC;AAAA,IAC7F;AACA,WAAO,KAAK,IAAI,OAAK,EAAE,IAAI,OAAK,IAAI,EAAE,QAAQ,MAAM,IAAI,CAAC,GAAG,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,IAAI;AAAA,EACpF;AACF;",
+  "names": []
+}

package/dist/dropdown-enumerator.d.ts

@@ -0,0 +1,20 @@
+import type { Page } from 'playwright';
+export interface DropdownOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+export interface DropdownDef {
+    kind: 'native-select' | 'combobox' | 'listbox' | 'multiselect';
+    label: string;
+    locatorHint: string;
+    options: DropdownOption[];
+    defaultValue?: string;
+    cascadesFrom?: string;
+}
+export interface DropdownEnumerationResult {
+    dropdowns: DropdownDef[];
+    conditionalRevealMap: Record<string, string[]>;
+    totalOptionsFound: number;
+}
+export declare function enumerateDropdowns(page: Page): Promise<DropdownEnumerationResult>;

package/dist/dropdown-enumerator.js

@@ -0,0 +1,230 @@
+async function enumerateNativeSelects(page) {
+  const selects = await page.$$("select:not([multiple])");
+  const limited = selects.slice(0, 50);
+  const results = [];
+  for (const handle of limited) {
+    try {
+      const data = await handle.evaluate((el) => {
+        const name = el.name || el.id || "";
+        const ariaLabel = el.getAttribute("aria-label") || "";
+        let labelText = ariaLabel;
+        if (!labelText && el.id) {
+          const lbl = document.querySelector(`label[for="${el.id}"]`);
+          if (lbl) labelText = lbl.textContent?.trim() || "";
+        }
+        if (!labelText && name) labelText = name;
+        const options = Array.from(el.options).map((o) => ({
+          value: o.value,
+          label: o.text.trim(),
+          disabled: o.disabled || void 0
+        }));
+        const selectedOption = el.options[el.selectedIndex];
+        const defaultValue = selectedOption ? selectedOption.value : void 0;
+        const locatorHint = name ? `select[name="${name}"]` : el.id ? `select#${el.id}` : "select";
+        return { label: labelText, locatorHint, options, defaultValue };
+      });
+      results.push({
+        kind: "native-select",
+        label: data.label,
+        locatorHint: data.locatorHint,
+        options: data.options,
+        defaultValue: data.defaultValue
+      });
+    } catch {
+    }
+  }
+  return results;
+}
+async function enumerateCustomDropdowns(page) {
+  const selectors = [
+    '[role="combobox"]',
+    '[aria-haspopup="listbox"]:not([role="combobox"])',
+    "[data-radix-select-trigger]"
+  ];
+  const seen = /* @__PURE__ */ new Set();
+  const handles = [];
+  for (const sel of selectors) {
+    const els = await page.$$(sel);
+    for (const el of els) {
+      const hint = await el.evaluate((e) => {
+        const id = e.id ? `#${e.id}` : "";
+        const aria = e.getAttribute("aria-label") || "";
+        return id || aria || e.tagName.toLowerCase();
+      }).catch(() => "");
+      if (!seen.has(hint)) {
+        seen.add(hint);
+        handles.push({ handle: el, hint });
+      }
+    }
+  }
+  const limited = handles.slice(0, 20);
+  const results = [];
+  for (const { handle, hint } of limited) {
+    try {
+      const ariaLabel = await handle.evaluate((e) => e.getAttribute("aria-label") || e.textContent?.trim() || "").catch(() => "");
+      await handle.click();
+      await page.waitForSelector('[role="listbox"]', { timeout: 2e3 });
+      const options = await page.$$eval(
+        '[role="listbox"] [role="option"]',
+        (els) => els.map((el) => ({
+          value: el.getAttribute("data-value") || el.getAttribute("value") || el.textContent?.trim() || "",
+          label: el.textContent?.trim() || "",
+          disabled: el.getAttribute("aria-disabled") === "true" || void 0
+        }))
+      );
+      await page.keyboard.press("Escape");
+      await page.waitForTimeout(300);
+      results.push({
+        kind: "combobox",
+        label: ariaLabel,
+        locatorHint: hint,
+        options
+      });
+    } catch {
+      try {
+        await page.keyboard.press("Escape");
+        await page.waitForTimeout(300);
+      } catch {
+      }
+    }
+  }
+  return results;
+}
+async function enumerateMultiSelects(page) {
+  const results = [];
+  const nativeMulti = await page.$$("select[multiple]");
+  for (const handle of nativeMulti) {
+    try {
+      const data = await handle.evaluate((el) => {
+        const name = el.name || el.id || "";
+        const ariaLabel = el.getAttribute("aria-label") || "";
+        let labelText = ariaLabel;
+        if (!labelText && el.id) {
+          const lbl = document.querySelector(`label[for="${el.id}"]`);
+          if (lbl) labelText = lbl.textContent?.trim() || "";
+        }
+        if (!labelText && name) labelText = name;
+        const options = Array.from(el.options).map((o) => ({
+          value: o.value,
+          label: o.text.trim(),
+          disabled: o.disabled || void 0
+        }));
+        const locatorHint = name ? `select[multiple][name="${name}"]` : el.id ? `select[multiple]#${el.id}` : "select[multiple]";
+        return { label: labelText, locatorHint, options };
+      });
+      results.push({
+        kind: "multiselect",
+        label: data.label,
+        locatorHint: data.locatorHint,
+        options: data.options
+      });
+    } catch {
+    }
+  }
+  const ariaMulti = await page.$$('[role="listbox"][aria-multiselectable="true"]');
+  for (const handle of ariaMulti) {
+    try {
+      const data = await handle.evaluate((el) => {
+        const ariaLabel = el.getAttribute("aria-label") || el.id || "";
+        const locatorHint = el.id ? `[role="listbox"]#${el.id}` : '[role="listbox"][aria-multiselectable="true"]';
+        const optionEls = el.querySelectorAll('[role="option"]');
+        const options = Array.from(optionEls).map((o) => ({
+          value: o.getAttribute("data-value") || o.getAttribute("value") || o.textContent?.trim() || "",
+          label: o.textContent?.trim() || "",
+          disabled: o.getAttribute("aria-disabled") === "true" || void 0
+        }));
+        return { label: ariaLabel, locatorHint, options };
+      });
+      results.push({
+        kind: "multiselect",
+        label: data.label,
+        locatorHint: data.locatorHint,
+        options: data.options
+      });
+    } catch {
+    }
+  }
+  return results;
+}
+async function detectCascading(page, dropdowns) {
+  const cascadeMap = {};
+  const nativeParents = dropdowns.filter(
+    (d) => d.kind === "native-select" && d.options.length <= 8
+  );
+  for (const parent of nativeParents) {
+    const parentName = parent.locatorHint.match(/name="([^"]+)"/)?.[1];
+    if (!parentName) continue;
+    const otherNatives = dropdowns.filter(
+      (d) => d.kind === "native-select" && d.locatorHint !== parent.locatorHint
+    );
+    if (otherNatives.length === 0) continue;
+    const baselineCounts = await page.$$eval(
+      "select:not([multiple])",
+      (els) => els.map((el) => ({ name: el.name || el.id, count: el.options.length }))
+    ).catch(() => []);
+    let foundChildren = [];
+    for (let i = 0; i < parent.options.length; i++) {
+      try {
+        await page.selectOption(`select[name="${parentName}"]`, { index: i });
+        await page.waitForTimeout(500);
+        const newCounts = await page.$$eval(
+          "select:not([multiple])",
+          (els) => els.map((el) => ({ name: el.name || el.id, count: el.options.length }))
+        ).catch(() => []);
+        for (const curr of newCounts) {
+          const base = baselineCounts.find((b) => b.name === curr.name);
+          if (base && base.count !== curr.count && curr.name !== parentName) {
+            const childHint = `select[name="${curr.name}"]`;
+            const childDef = dropdowns.find((d) => d.locatorHint === childHint);
+            if (childDef && !foundChildren.includes(childHint)) {
+              foundChildren.push(childHint);
+            }
+          }
+        }
+      } catch {
+      }
+    }
+    try {
+      await page.selectOption(`select[name="${parentName}"]`, { index: 0 });
+    } catch {
+    }
+    if (foundChildren.length > 0) {
+      cascadeMap[parent.locatorHint] = foundChildren;
+    }
+  }
+  return cascadeMap;
+}
+async function enumerateDropdowns(page) {
+  try {
+    const [native, custom, multi] = await Promise.all([
+      enumerateNativeSelects(page).catch(() => []),
+      enumerateCustomDropdowns(page).catch(() => []),
+      enumerateMultiSelects(page).catch(() => [])
+    ]);
+    const seen = /* @__PURE__ */ new Set();
+    const dropdowns = [];
+    for (const d of [...native, ...custom, ...multi]) {
+      if (!seen.has(d.locatorHint)) {
+        seen.add(d.locatorHint);
+        dropdowns.push(d);
+      }
+    }
+    const conditionalRevealMap = await detectCascading(page, dropdowns).catch(
+      () => ({})
+    );
+    for (const [parent, children] of Object.entries(conditionalRevealMap)) {
+      for (const childHint of children) {
+        const child = dropdowns.find((d) => d.locatorHint === childHint);
+        if (child) child.cascadesFrom = parent;
+      }
+    }
+    const totalOptionsFound = dropdowns.reduce((sum, d) => sum + d.options.length, 0);
+    return { dropdowns, conditionalRevealMap, totalOptionsFound };
+  } catch {
+    return { dropdowns: [], conditionalRevealMap: {}, totalOptionsFound: 0 };
+  }
+}
+export {
+  enumerateDropdowns
+};
+//# sourceMappingURL=dropdown-enumerator.js.map

package/dist/dropdown-enumerator.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/dropdown-enumerator.ts"],
+  "sourcesContent": ["import type { Page } from 'playwright';\n\nexport interface DropdownOption {\n  value: string;\n  label: string;\n  disabled?: boolean;\n}\n\nexport interface DropdownDef {\n  kind: 'native-select' | 'combobox' | 'listbox' | 'multiselect';\n  label: string;\n  locatorHint: string;\n  options: DropdownOption[];\n  defaultValue?: string;\n  cascadesFrom?: string;\n}\n\nexport interface DropdownEnumerationResult {\n  dropdowns: DropdownDef[];\n  conditionalRevealMap: Record<string, string[]>;\n  totalOptionsFound: number;\n}\n\nasync function enumerateNativeSelects(page: Page): Promise<DropdownDef[]> {\n  const selects = await page.$$('select:not([multiple])');\n  const limited = selects.slice(0, 50);\n  const results: DropdownDef[] = [];\n\n  for (const handle of limited) {\n    try {\n      const data = await handle.evaluate((el: HTMLSelectElement) => {\n        const name = el.name || el.id || '';\n        const ariaLabel = el.getAttribute('aria-label') || '';\n        let labelText = ariaLabel;\n        if (!labelText && el.id) {\n          const lbl = document.querySelector(`label[for=\"${el.id}\"]`);\n          if (lbl) labelText = lbl.textContent?.trim() || '';\n        }\n        if (!labelText && name) labelText = name;\n        const options = Array.from(el.options).map((o) => ({\n          value: o.value,\n          label: o.text.trim(),\n          disabled: o.disabled || undefined,\n        }));\n        const selectedOption = el.options[el.selectedIndex];\n        const defaultValue = selectedOption ? selectedOption.value : undefined;\n        const locatorHint = name\n          ? `select[name=\"${name}\"]`\n          : el.id\n          ? `select#${el.id}`\n          : 'select';\n        return { label: labelText, locatorHint, options, defaultValue };\n      });\n\n      results.push({\n        kind: 'native-select',\n        label: data.label,\n        locatorHint: data.locatorHint,\n        options: data.options,\n        defaultValue: data.defaultValue,\n      });\n    } catch {\n      // skip unresponsive handle\n    }\n  }\n\n  return results;\n}\n\nasync function enumerateCustomDropdowns(page: Page): Promise<DropdownDef[]> {\n  const selectors = [\n    '[role=\"combobox\"]',\n    '[aria-haspopup=\"listbox\"]:not([role=\"combobox\"])',\n    '[data-radix-select-trigger]',\n  ];\n\n  const seen = new Set<string>();\n  const handles: { handle: Awaited<ReturnType<Page['$$']>>[0]; hint: string }[] = [];\n\n  for (const sel of selectors) {\n    const els = await page.$$(sel);\n    for (const el of els) {\n      const hint = await el\n        .evaluate((e: Element) => {\n          const id = e.id ? `#${e.id}` : '';\n          const aria = e.getAttribute('aria-label') || '';\n          return id || aria || e.tagName.toLowerCase();\n        })\n        .catch(() => '');\n      if (!seen.has(hint)) {\n        seen.add(hint);\n        handles.push({ handle: el, hint });\n      }\n    }\n  }\n\n  const limited = handles.slice(0, 20);\n  const results: DropdownDef[] = [];\n\n  for (const { handle, hint } of limited) {\n    try {\n      const ariaLabel = await handle\n        .evaluate((e: Element) => e.getAttribute('aria-label') || e.textContent?.trim() || '')\n        .catch(() => '');\n\n      await handle.click();\n      await page.waitForSelector('[role=\"listbox\"]', { timeout: 2000 });\n\n      const options = await page.$$eval('[role=\"listbox\"] [role=\"option\"]', (els) =>\n        els.map((el) => ({\n          value: el.getAttribute('data-value') || el.getAttribute('value') || el.textContent?.trim() || '',\n          label: el.textContent?.trim() || '',\n          disabled: el.getAttribute('aria-disabled') === 'true' || undefined,\n        }))\n      );\n\n      await page.keyboard.press('Escape');\n      await page.waitForTimeout(300);\n\n      results.push({\n        kind: 'combobox',\n        label: ariaLabel,\n        locatorHint: hint,\n        options,\n      });\n    } catch {\n      try {\n        await page.keyboard.press('Escape');\n        await page.waitForTimeout(300);\n      } catch {\n        // ignore cleanup failure\n      }\n    }\n  }\n\n  return results;\n}\n\nasync function enumerateMultiSelects(page: Page): Promise<DropdownDef[]> {\n  const results: DropdownDef[] = [];\n\n  const nativeMulti = await page.$$('select[multiple]');\n  for (const handle of nativeMulti) {\n    try {\n      const data = await handle.evaluate((el: HTMLSelectElement) => {\n        const name = el.name || el.id || '';\n        const ariaLabel = el.getAttribute('aria-label') || '';\n        let labelText = ariaLabel;\n        if (!labelText && el.id) {\n          const lbl = document.querySelector(`label[for=\"${el.id}\"]`);\n          if (lbl) labelText = lbl.textContent?.trim() || '';\n        }\n        if (!labelText && name) labelText = name;\n        const options = Array.from(el.options).map((o) => ({\n          value: o.value,\n          label: o.text.trim(),\n          disabled: o.disabled || undefined,\n        }));\n        const locatorHint = name\n          ? `select[multiple][name=\"${name}\"]`\n          : el.id\n          ? `select[multiple]#${el.id}`\n          : 'select[multiple]';\n        return { label: labelText, locatorHint, options };\n      });\n\n      results.push({\n        kind: 'multiselect',\n        label: data.label,\n        locatorHint: data.locatorHint,\n        options: data.options,\n      });\n    } catch {\n      // skip\n    }\n  }\n\n  const ariaMulti = await page.$$('[role=\"listbox\"][aria-multiselectable=\"true\"]');\n  for (const handle of ariaMulti) {\n    try {\n      const data = await handle.evaluate((el: Element) => {\n        const ariaLabel = el.getAttribute('aria-label') || el.id || '';\n        const locatorHint = el.id\n          ? `[role=\"listbox\"]#${el.id}`\n          : '[role=\"listbox\"][aria-multiselectable=\"true\"]';\n        const optionEls = el.querySelectorAll('[role=\"option\"]');\n        const options = Array.from(optionEls).map((o) => ({\n          value: o.getAttribute('data-value') || o.getAttribute('value') || o.textContent?.trim() || '',\n          label: o.textContent?.trim() || '',\n          disabled: o.getAttribute('aria-disabled') === 'true' || undefined,\n        }));\n        return { label: ariaLabel, locatorHint, options };\n      });\n\n      results.push({\n        kind: 'multiselect',\n        label: data.label,\n        locatorHint: data.locatorHint,\n        options: data.options,\n      });\n    } catch {\n      // skip\n    }\n  }\n\n  return results;\n}\n\nasync function detectCascading(\n  page: Page,\n  dropdowns: DropdownDef[]\n): Promise<Record<string, string[]>> {\n  const cascadeMap: Record<string, string[]> = {};\n\n  const nativeParents = dropdowns.filter(\n    (d) => d.kind === 'native-select' && d.options.length <= 8\n  );\n\n  for (const parent of nativeParents) {\n    const parentName = parent.locatorHint.match(/name=\"([^\"]+)\"/)?.[1];\n    if (!parentName) continue;\n\n    const otherNatives = dropdowns.filter(\n      (d) => d.kind === 'native-select' && d.locatorHint !== parent.locatorHint\n    );\n    if (otherNatives.length === 0) continue;\n\n    const baselineCounts = await page\n      .$$eval('select:not([multiple])', (els) =>\n        (els as HTMLSelectElement[]).map((el) => ({ name: el.name || el.id, count: el.options.length }))\n      )\n      .catch(() => [] as { name: string; count: number }[]);\n\n    let foundChildren: string[] = [];\n\n    for (let i = 0; i < parent.options.length; i++) {\n      try {\n        await page.selectOption(`select[name=\"${parentName}\"]`, { index: i });\n        await page.waitForTimeout(500);\n\n        const newCounts = await page\n          .$$eval('select:not([multiple])', (els) =>\n            (els as HTMLSelectElement[]).map((el) => ({ name: el.name || el.id, count: el.options.length }))\n          )\n          .catch(() => [] as { name: string; count: number }[]);\n\n        for (const curr of newCounts) {\n          const base = baselineCounts.find((b) => b.name === curr.name);\n          if (base && base.count !== curr.count && curr.name !== parentName) {\n            const childHint = `select[name=\"${curr.name}\"]`;\n            const childDef = dropdowns.find((d) => d.locatorHint === childHint);\n            if (childDef && !foundChildren.includes(childHint)) {\n              foundChildren.push(childHint);\n            }\n          }\n        }\n      } catch {\n        // skip option that fails\n      }\n    }\n\n    // reset to index 0\n    try {\n      await page.selectOption(`select[name=\"${parentName}\"]`, { index: 0 });\n    } catch {\n      // ignore reset failure\n    }\n\n    if (foundChildren.length > 0) {\n      cascadeMap[parent.locatorHint] = foundChildren;\n    }\n  }\n\n  return cascadeMap;\n}\n\nexport async function enumerateDropdowns(page: Page): Promise<DropdownEnumerationResult> {\n  try {\n    const [native, custom, multi] = await Promise.all([\n      enumerateNativeSelects(page).catch(() => [] as DropdownDef[]),\n      enumerateCustomDropdowns(page).catch(() => [] as DropdownDef[]),\n      enumerateMultiSelects(page).catch(() => [] as DropdownDef[]),\n    ]);\n\n    const seen = new Set<string>();\n    const dropdowns: DropdownDef[] = [];\n\n    for (const d of [...native, ...custom, ...multi]) {\n      if (!seen.has(d.locatorHint)) {\n        seen.add(d.locatorHint);\n        dropdowns.push(d);\n      }\n    }\n\n    const conditionalRevealMap = await detectCascading(page, dropdowns).catch(\n      () => ({} as Record<string, string[]>)\n    );\n\n    for (const [parent, children] of Object.entries(conditionalRevealMap)) {\n      for (const childHint of children) {\n        const child = dropdowns.find((d) => d.locatorHint === childHint);\n        if (child) child.cascadesFrom = parent;\n      }\n    }\n\n    const totalOptionsFound = dropdowns.reduce((sum, d) => sum + d.options.length, 0);\n\n    return { dropdowns, conditionalRevealMap, totalOptionsFound };\n  } catch {\n    return { dropdowns: [], conditionalRevealMap: {}, totalOptionsFound: 0 };\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/element-hash.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Compute a stable fingerprint of a screen's element set.
+ * Sorted so insertion-order changes (React re-renders) don't produce false positives.
+ * Returns first 16 hex chars of SHA-256.
+ */
+export declare function computeElementHash(elements: Array<{
+    role: string;
+    meaning: string;
+}>): string;

package/dist/element-hash.js

@@ -0,0 +1,9 @@
+import { createHash } from "node:crypto";
+function computeElementHash(elements) {
+  const pairs = elements.map((e) => `${e.role.toLowerCase()}:${e.meaning.toLowerCase().trim()}`).sort().join("|");
+  return createHash("sha256").update(pairs).digest("hex").slice(0, 16);
+}
+export {
+  computeElementHash
+};
+//# sourceMappingURL=element-hash.js.map

package/dist/element-hash.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/element-hash.ts"],
+  "sourcesContent": ["import { createHash } from 'node:crypto';\n\n/**\n * Compute a stable fingerprint of a screen's element set.\n * Sorted so insertion-order changes (React re-renders) don't produce false positives.\n * Returns first 16 hex chars of SHA-256.\n */\nexport function computeElementHash(\n  elements: Array<{ role: string; meaning: string }>,\n): string {\n  const pairs = elements\n    .map((e) => `${e.role.toLowerCase()}:${e.meaning.toLowerCase().trim()}`)\n    .sort()\n    .join('|');\n  return createHash('sha256').update(pairs).digest('hex').slice(0, 16);\n}\n"],
+  "mappings": "AAAA,SAAS,kBAAkB;AAOpB,SAAS,mBACd,UACQ;AACR,QAAM,QAAQ,SACX,IAAI,CAAC,MAAM,GAAG,EAAE,KAAK,YAAY,CAAC,IAAI,EAAE,QAAQ,YAAY,EAAE,KAAK,CAAC,EAAE,EACtE,KAAK,EACL,KAAK,GAAG;AACX,SAAO,WAAW,QAAQ,EAAE,OAAO,KAAK,EAAE,OAAO,KAAK,EAAE,MAAM,GAAG,EAAE;AACrE;",
+  "names": []
+}

package/dist/email-otp.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Email OTP retrieval — supports 3 providers:
+ *   mailslurp  — managed SaaS (existing, no self-hosting)
+ *   imap       — any real IMAP mailbox (Gmail, Outlook, custom domain catch-all)
+ *   mailpit    — self-hosted SMTP trap (dev/staging only)
+ *
+ * Use mailslurp or imap for production apps.
+ * Use mailpit only when you can point the app's SMTP at the trap server.
+ */
+export type EmailOTPProvider = 'mailslurp' | 'imap' | 'mailpit';
+export interface EmailContent {
+    /** 4-8 digit OTP code, if found. */
+    otp?: string;
+    /** Magic link URL to navigate to, if found. */
+    magicLink?: string;
+}
+export interface EmailOTPConfig {
+    provider: EmailOTPProvider;
+    apiKey?: string;
+    inboxId?: string;
+    imapHost?: string;
+    imapPort?: number;
+    imapUser?: string;
+    imapPass?: string;
+    imapTls?: boolean;
+    mailpitBaseUrl?: string;
+}
+/**
+ * Wait for an email and return its OTP code or magic link URL.
+ * Prefer this over waitForEmailOTP when the app may send passwordless magic links.
+ */
+export declare function waitForEmailContent(config: EmailOTPConfig, since: string | Date): Promise<EmailContent | null>;
+/**
+ * Wait for an OTP email and extract the code.
+ * @deprecated Use waitForEmailContent which also handles magic links.
+ */
+export declare function waitForEmailOTP(config: EmailOTPConfig, since: string | Date): Promise<string | null>;
+/**
+ * Get the email address for a MailSlurp inbox (used to display in UI).
+ * Returns null for IMAP/Mailpit providers — use imapUser directly.
+ */
+export declare function getInboxEmail(configOrApiKey: EmailOTPConfig | string, inboxId?: string): Promise<string | null>;

package/dist/email-otp.js

@@ -0,0 +1,177 @@
+const POLL_INTERVAL_MS = 2e3;
+const MAX_WAIT_MS = 6e4;
+function extractOTP(text) {
+  const m6 = text.match(/\b(\d{6})\b/);
+  if (m6) return m6[1];
+  const m48 = text.match(/\b(\d{4,8})\b/);
+  if (m48) return m48[1];
+  const magic = text.match(/\b([A-Z0-9]{6,10})\b/);
+  if (magic) return magic[1];
+  return null;
+}
+function extractMagicLink(text) {
+  const magicPath = /\/(verify|magic|login|auth|confirm|sign-in)[/?#]/i;
+  const magicQuery = /[?&](token|magic_token|login_token|auth_token|key)=/i;
+  const urlMatches = text.match(/https:\/\/[^\s<>"')\]]+/g);
+  if (!urlMatches) return null;
+  for (const raw of urlMatches) {
+    try {
+      const u = new URL(raw.replace(/[>'")\].,]+$/, ""));
+      if (magicPath.test(u.pathname) || magicQuery.test(u.search)) return u.toString();
+    } catch {
+    }
+  }
+  return null;
+}
+function parseEmailContent(text) {
+  const magicLink = extractMagicLink(text);
+  if (magicLink) return { magicLink };
+  const otp = extractOTP(text);
+  if (otp) return { otp };
+  return {};
+}
+const MAILSLURP_BASE = "https://api.mailslurp.com";
+async function waitForContentMailSlurp(apiKey, inboxId, since) {
+  const deadline = Date.now() + MAX_WAIT_MS;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+    try {
+      const listRes = await fetch(
+        `${MAILSLURP_BASE}/inboxes/${inboxId}/emails?sort=DESC&limit=5&since=${encodeURIComponent(since)}`,
+        { headers: { "x-api-key": apiKey } }
+      );
+      if (!listRes.ok) continue;
+      const emails = await listRes.json();
+      if (!emails.length) continue;
+      const bodyRes = await fetch(`${MAILSLURP_BASE}/emails/${emails[0].id}`, { headers: { "x-api-key": apiKey } });
+      if (!bodyRes.ok) continue;
+      const email = await bodyRes.json();
+      const content = parseEmailContent((email.body ?? "") + " " + (email.subject ?? ""));
+      if (content.otp || content.magicLink) return content;
+    } catch {
+    }
+  }
+  return null;
+}
+async function getInboxEmailMailSlurp(apiKey, inboxId) {
+  try {
+    const res = await fetch(`${MAILSLURP_BASE}/inboxes/${inboxId}`, { headers: { "x-api-key": apiKey } });
+    if (!res.ok) return null;
+    const data = await res.json();
+    return data.emailAddress ?? null;
+  } catch {
+    return null;
+  }
+}
+async function waitForContentMailpit(baseUrl, since) {
+  const deadline = Date.now() + MAX_WAIT_MS;
+  const sinceMs = since.getTime();
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+    try {
+      const res = await fetch(`${baseUrl}/api/v1/messages?limit=10`);
+      if (!res.ok) continue;
+      const data = await res.json();
+      const recent = (data.messages ?? []).filter((m) => new Date(m.Created).getTime() > sinceMs);
+      for (const msg of recent) {
+        const snippet = parseEmailContent(msg.Snippet + " " + msg.Subject);
+        if (snippet.otp || snippet.magicLink) return snippet;
+        const bodyRes = await fetch(`${baseUrl}/api/v1/message/${msg.ID}`);
+        if (!bodyRes.ok) continue;
+        const body = await bodyRes.json();
+        const full = parseEmailContent((body.Text?.Body ?? "") + " " + (body.Subject ?? ""));
+        if (full.otp || full.magicLink) return full;
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+async function waitForContentImap(cfg, since) {
+  let ImapFlow;
+  try {
+    const mod = await import("imapflow");
+    ImapFlow = mod.ImapFlow;
+  } catch {
+    throw new Error("IMAP provider requires imapflow package. Add it to dependencies.");
+  }
+  const client = new ImapFlow({
+    host: cfg.host,
+    port: cfg.port,
+    secure: cfg.tls,
+    auth: { user: cfg.user, pass: cfg.pass },
+    logger: false
+  });
+  try {
+    await client.connect();
+    const lock = await client.getMailboxLock("INBOX");
+    try {
+      const deadline = Date.now() + MAX_WAIT_MS;
+      while (Date.now() < deadline) {
+        const uids = await client.search({ seen: false, since });
+        if (uids.length) {
+          for await (const msg of client.fetch(uids.slice(-5), { source: true })) {
+            const { simpleParser } = await import("mailparser");
+            const parsed = await simpleParser(msg.source);
+            const text = (parsed.text ?? "") + " " + (parsed.subject ?? "");
+            const content = parseEmailContent(text);
+            if (content.otp || content.magicLink) return content;
+          }
+        }
+        await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+      }
+      return null;
+    } finally {
+      lock.release();
+    }
+  } finally {
+    await client.logout().catch(() => {
+    });
+  }
+}
+async function waitForEmailContent(config, since) {
+  const sinceStr = typeof since === "string" ? since : since.toISOString();
+  const sinceDate = typeof since === "string" ? new Date(since) : since;
+  switch (config.provider) {
+    case "mailslurp":
+      if (!config.apiKey || !config.inboxId) throw new Error("mailslurp requires apiKey + inboxId");
+      return waitForContentMailSlurp(config.apiKey, config.inboxId, sinceStr);
+    case "mailpit":
+      return waitForContentMailpit(config.mailpitBaseUrl ?? "http://mailpit:8025", sinceDate);
+    case "imap":
+      if (!config.imapHost || !config.imapUser || !config.imapPass) {
+        throw new Error("imap requires imapHost, imapUser, imapPass");
+      }
+      return waitForContentImap({
+        host: config.imapHost,
+        port: config.imapPort ?? 993,
+        user: config.imapUser,
+        pass: config.imapPass,
+        tls: config.imapTls !== false
+      }, sinceDate);
+    default:
+      return null;
+  }
+}
+async function waitForEmailOTP(config, since) {
+  const content = await waitForEmailContent(config, since);
+  return content?.otp ?? null;
+}
+async function getInboxEmail(configOrApiKey, inboxId) {
+  if (typeof configOrApiKey === "string") {
+    return getInboxEmailMailSlurp(configOrApiKey, inboxId ?? "");
+  }
+  if (configOrApiKey.provider === "mailslurp" && configOrApiKey.apiKey && configOrApiKey.inboxId) {
+    return getInboxEmailMailSlurp(configOrApiKey.apiKey, configOrApiKey.inboxId);
+  }
+  if (configOrApiKey.provider === "imap") {
+    return configOrApiKey.imapUser ?? null;
+  }
+  return null;
+}
+export {
+  getInboxEmail,
+  waitForEmailContent,
+  waitForEmailOTP
+};
+//# sourceMappingURL=email-otp.js.map

package/dist/email-otp.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/email-otp.ts"],
+  "sourcesContent": ["/**\n * Email OTP retrieval \u2014 supports 3 providers:\n *   mailslurp  \u2014 managed SaaS (existing, no self-hosting)\n *   imap       \u2014 any real IMAP mailbox (Gmail, Outlook, custom domain catch-all)\n *   mailpit    \u2014 self-hosted SMTP trap (dev/staging only)\n *\n * Use mailslurp or imap for production apps.\n * Use mailpit only when you can point the app's SMTP at the trap server.\n */\n\nexport type EmailOTPProvider = 'mailslurp' | 'imap' | 'mailpit';\n\nexport interface EmailContent {\n  /** 4-8 digit OTP code, if found. */\n  otp?: string;\n  /** Magic link URL to navigate to, if found. */\n  magicLink?: string;\n}\n\nexport interface EmailOTPConfig {\n  provider: EmailOTPProvider;\n  // MailSlurp\n  apiKey?: string;\n  inboxId?: string;\n  // IMAP (Gmail app-password, Outlook, custom IMAP)\n  imapHost?: string;\n  imapPort?: number;\n  imapUser?: string;\n  imapPass?: string;\n  imapTls?: boolean;\n  // Mailpit (REST API at baseUrl)\n  mailpitBaseUrl?: string;\n}\n\nconst POLL_INTERVAL_MS = 2_000;\nconst MAX_WAIT_MS = 60_000;\n\n/** Extract OTP code from email body text. Prefers 6-digit, falls back to 4-8 digit. */\nfunction extractOTP(text: string): string | null {\n  const m6 = text.match(/\\b(\\d{6})\\b/);\n  if (m6) return m6[1];\n  const m48 = text.match(/\\b(\\d{4,8})\\b/);\n  if (m48) return m48[1];\n  const magic = text.match(/\\b([A-Z0-9]{6,10})\\b/);\n  if (magic) return magic[1];\n  return null;\n}\n\n/** Extract a magic-link URL from email body text. Matches /verify, /magic, /auth/callback, ?token= etc. */\nfunction extractMagicLink(text: string): string | null {\n  const magicPath = /\\/(verify|magic|login|auth|confirm|sign-in)[/?#]/i;\n  const magicQuery = /[?&](token|magic_token|login_token|auth_token|key)=/i;\n  const urlMatches = text.match(/https:\\/\\/[^\\s<>\"')\\]]+/g);\n  if (!urlMatches) return null;\n  for (const raw of urlMatches) {\n    try {\n      const u = new URL(raw.replace(/[>'\")\\].,]+$/, ''));\n      if (magicPath.test(u.pathname) || magicQuery.test(u.search)) return u.toString();\n    } catch { /* skip malformed URLs */ }\n  }\n  return null;\n}\n\nfunction parseEmailContent(text: string): EmailContent {\n  const magicLink = extractMagicLink(text);\n  if (magicLink) return { magicLink };\n  const otp = extractOTP(text);\n  if (otp) return { otp };\n  return {};\n}\n\n// \u2500\u2500 MailSlurp \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nconst MAILSLURP_BASE = 'https://api.mailslurp.com';\n\nasync function waitForContentMailSlurp(apiKey: string, inboxId: string, since: string): Promise<EmailContent | null> {\n  const deadline = Date.now() + MAX_WAIT_MS;\n  while (Date.now() < deadline) {\n    await new Promise(r => setTimeout(r, POLL_INTERVAL_MS));\n    try {\n      const listRes = await fetch(\n        `${MAILSLURP_BASE}/inboxes/${inboxId}/emails?sort=DESC&limit=5&since=${encodeURIComponent(since)}`,\n        { headers: { 'x-api-key': apiKey } }\n      );\n      if (!listRes.ok) continue;\n      const emails = await listRes.json() as Array<{ id: string }>;\n      if (!emails.length) continue;\n      const bodyRes = await fetch(`${MAILSLURP_BASE}/emails/${emails[0].id}`, { headers: { 'x-api-key': apiKey } });\n      if (!bodyRes.ok) continue;\n      const email = await bodyRes.json() as { body?: string; subject?: string };\n      const content = parseEmailContent((email.body ?? '') + ' ' + (email.subject ?? ''));\n      if (content.otp || content.magicLink) return content;\n    } catch { /* retry */ }\n  }\n  return null;\n}\n\nasync function getInboxEmailMailSlurp(apiKey: string, inboxId: string): Promise<string | null> {\n  try {\n    const res = await fetch(`${MAILSLURP_BASE}/inboxes/${inboxId}`, { headers: { 'x-api-key': apiKey } });\n    if (!res.ok) return null;\n    const data = await res.json() as { emailAddress?: string };\n    return data.emailAddress ?? null;\n  } catch { return null; }\n}\n\n// \u2500\u2500 Mailpit (SMTP trap REST API) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nasync function waitForContentMailpit(baseUrl: string, since: Date): Promise<EmailContent | null> {\n  const deadline = Date.now() + MAX_WAIT_MS;\n  const sinceMs = since.getTime();\n  while (Date.now() < deadline) {\n    await new Promise(r => setTimeout(r, POLL_INTERVAL_MS));\n    try {\n      const res = await fetch(`${baseUrl}/api/v1/messages?limit=10`);\n      if (!res.ok) continue;\n      const data = await res.json() as { messages?: Array<{ ID: string; Created: string; Snippet: string; Subject: string }> };\n      const recent = (data.messages ?? []).filter(m => new Date(m.Created).getTime() > sinceMs);\n      for (const msg of recent) {\n        const snippet = parseEmailContent(msg.Snippet + ' ' + msg.Subject);\n        if (snippet.otp || snippet.magicLink) return snippet;\n        // Fetch full body \u2014 snippet may truncate the magic link\n        const bodyRes = await fetch(`${baseUrl}/api/v1/message/${msg.ID}`);\n        if (!bodyRes.ok) continue;\n        const body = await bodyRes.json() as { Text?: { Body?: string }; Subject?: string };\n        const full = parseEmailContent((body.Text?.Body ?? '') + ' ' + (body.Subject ?? ''));\n        if (full.otp || full.magicLink) return full;\n      }\n    } catch { /* retry */ }\n  }\n  return null;\n}\n\n// \u2500\u2500 IMAP (any mailbox) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nasync function waitForContentImap(\n  cfg: { host: string; port: number; user: string; pass: string; tls: boolean },\n  since: Date\n): Promise<EmailContent | null> {\n  let ImapFlow: any;\n  try {\n    const mod = await import('imapflow');\n    ImapFlow = mod.ImapFlow;\n  } catch {\n    throw new Error('IMAP provider requires imapflow package. Add it to dependencies.');\n  }\n\n  const client = new ImapFlow({\n    host: cfg.host,\n    port: cfg.port,\n    secure: cfg.tls,\n    auth: { user: cfg.user, pass: cfg.pass },\n    logger: false,\n  });\n\n  try {\n    await client.connect();\n    const lock = await client.getMailboxLock('INBOX');\n    try {\n      const deadline = Date.now() + MAX_WAIT_MS;\n      while (Date.now() < deadline) {\n        const uids = await client.search({ seen: false, since });\n        if (uids.length) {\n          for await (const msg of client.fetch(uids.slice(-5), { source: true })) {\n            const { simpleParser } = await import('mailparser');\n            const parsed = await simpleParser(msg.source);\n            const text = (parsed.text ?? '') + ' ' + (parsed.subject ?? '');\n            const content = parseEmailContent(text);\n            if (content.otp || content.magicLink) return content;\n          }\n        }\n        await new Promise(r => setTimeout(r, POLL_INTERVAL_MS));\n      }\n      return null;\n    } finally {\n      lock.release();\n    }\n  } finally {\n    await client.logout().catch(() => {});\n  }\n}\n\n// \u2500\u2500 Public API \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * Wait for an email and return its OTP code or magic link URL.\n * Prefer this over waitForEmailOTP when the app may send passwordless magic links.\n */\nexport async function waitForEmailContent(\n  config: EmailOTPConfig,\n  since: string | Date\n): Promise<EmailContent | null> {\n  const sinceStr = typeof since === 'string' ? since : since.toISOString();\n  const sinceDate = typeof since === 'string' ? new Date(since) : since;\n\n  switch (config.provider) {\n    case 'mailslurp':\n      if (!config.apiKey || !config.inboxId) throw new Error('mailslurp requires apiKey + inboxId');\n      return waitForContentMailSlurp(config.apiKey, config.inboxId, sinceStr);\n\n    case 'mailpit':\n      return waitForContentMailpit(config.mailpitBaseUrl ?? 'http://mailpit:8025', sinceDate);\n\n    case 'imap':\n      if (!config.imapHost || !config.imapUser || !config.imapPass) {\n        throw new Error('imap requires imapHost, imapUser, imapPass');\n      }\n      return waitForContentImap({\n        host: config.imapHost,\n        port: config.imapPort ?? 993,\n        user: config.imapUser,\n        pass: config.imapPass,\n        tls: config.imapTls !== false,\n      }, sinceDate);\n\n    default:\n      return null;\n  }\n}\n\n/**\n * Wait for an OTP email and extract the code.\n * @deprecated Use waitForEmailContent which also handles magic links.\n */\nexport async function waitForEmailOTP(\n  config: EmailOTPConfig,\n  since: string | Date\n): Promise<string | null> {\n  const content = await waitForEmailContent(config, since);\n  return content?.otp ?? null;\n}\n\n/**\n * Get the email address for a MailSlurp inbox (used to display in UI).\n * Returns null for IMAP/Mailpit providers \u2014 use imapUser directly.\n */\nexport async function getInboxEmail(\n  configOrApiKey: EmailOTPConfig | string,\n  inboxId?: string\n): Promise<string | null> {\n  // Legacy call: getInboxEmail(apiKey, inboxId)\n  if (typeof configOrApiKey === 'string') {\n    return getInboxEmailMailSlurp(configOrApiKey, inboxId ?? '');\n  }\n  if (configOrApiKey.provider === 'mailslurp' && configOrApiKey.apiKey && configOrApiKey.inboxId) {\n    return getInboxEmailMailSlurp(configOrApiKey.apiKey, configOrApiKey.inboxId);\n  }\n  if (configOrApiKey.provider === 'imap') {\n    return configOrApiKey.imapUser ?? null;\n  }\n  return null;\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/engine-router.d.ts

@@ -0,0 +1,47 @@
+import type { DomainProfile } from './profiles/domain-profile.js';
+export type CrawlEngineName = 'http' | 'browser' | 'browser-stealth' | 'stagehand' | 'vision' | 'recorded-session' | 'native';
+export interface CrawlRouteDecisionInput {
+    appUrl: string;
+    appType?: string | null;
+    hasCredentials: boolean;
+    hasStorageState: boolean;
+    hasAuthToken: boolean;
+    hasSkyvern: boolean;
+    hasProxy: boolean;
+    profile: DomainProfile;
+    previousFailureReason?: string;
+}
+export interface CrawlRouteDecision {
+    engines: CrawlEngineName[];
+    reasons: string[];
+    confidence: number;
+}
+/**
+ * Per-domain rendering predictor — learns whether a domain requires a full browser
+ * or can be served by the fast HTTP engine. Implements adaptive crawlee-python pattern.
+ *
+ * Strategy:
+ * 1. On first encounter of a domain, classify the HTTP response body.
+ * 2. Store the decision in memory (Map). All future URLs on same domain skip re-testing.
+ * 3. "Requires browser" signals: React/Vue/Angular root with no content, tiny body (<500 chars meaningful text).
+ */
+export declare class RenderingTypePredictor {
+    private cache;
+    /** Return cached decision if available, undefined if unknown. */
+    getCached(url: string): 'http' | 'browser' | undefined;
+    /**
+     * Analyze an HTTP response body to predict if JS rendering is required.
+     * Returns 'browser' if JS-heavy signals detected, 'http' otherwise.
+     */
+    predict(url: string, htmlBody: string, statusCode: number): 'http' | 'browser';
+    /** Force a domain to use a specific engine (e.g. after observing crawl errors). */
+    set(url: string, engine: 'http' | 'browser'): void;
+    stats(): {
+        cached: number;
+        browserDomains: string[];
+        httpDomains: string[];
+    };
+}
+/** Singleton predictor — shared across crawl jobs in the same process. */
+export declare const renderingPredictor: RenderingTypePredictor;
+export declare function chooseCrawlEngines(input: CrawlRouteDecisionInput): CrawlRouteDecision;